# @alint-js/core 中文文档

规范地址：https://npmcn.com/package/%40alint-js/core/

版本：0\.7\.3
npm 元数据更新时间：2026-09-28T17:18:28.367Z
中文译文更新时间：2026-11-05T19:47:37.342Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alint-js/core
原文对照：https://npmcn.com/package/%40alint-js/core/?lang=original
源码仓库：https://github.com/moeru-ai/alint

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：205 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：13 个
- 首次发布：2026-07-02T14:43:22.830Z
- 最新版本发布：2026-09-28T17:18:28.115Z
- 近 30 天下载量：94044（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 51 个）

## 中文简介

公共规则和插件 SDK 和运行 alint 的引擎

## 安装

```sh
npm install @alint-js/core
```

也可以使用：`pnpm add @alint-js/core`、`yarn add @alint-js/core`、`bun add @alint-js/core`

## README

# `@alint-js/core`

公共 SDK 运行引擎 `alint`。 。 。 .

## 它会做什么

这个软件包提供了插件,规则,语言处理器,嵌入工具和代理适配器所使用的核心SDK并运行引擎API:

-   `definePlugin` 财务报告和审定财务报表 `defineRule`
-   `runAlint`
-   规则登记和统一配置正常化
-   源运行时帮助
-   内建的 JavaScript 源代码提取, 并附加其它语言支持
-   按规模和能力分列的模型分辨率
-   诊断和进步有效载荷类型
-   框架中立代理合同 `@alint-js/core/agent`
-   工具调用结构输出 `@alint-js/core/structured-output`
-   为 SDK 高级消费者配置 DSL和类型

## 如何使用

写一条规则 :

```ts
import { defineRule } from '@alint-js/core'

export const rule = defineRule({
  create: ctx => ({
    async onTargetFile(target) {
      const model = await ctx.model({ size: 'small' })
      const file = await ctx.src.readFile(target.file)

      ctx.report({
        filePath: target.file.path,
        loc: target.loc,
        message: `reviewed ${file.lines.length} lines with ${model.id}`,
      })
    },
  }),
})
```

来源和项目规则都得到紧凑的说明。 源处理器应该通过 `target.file` 改为 `ctx.src.readFile()` 因此核心可以检测出规划以来的变化. 仅在需要时读取源 :

```ts
import { defineRule } from '@alint-js/core'

export const projectRule = defineRule({
  create: ctx => ({
    async onTargetProject(project) {
      for (const entry of project.files) {
        const file = await ctx.src.readFile(entry.path)
        if (file.text.includes('deprecated-api'))
          ctx.report({ filePath: entry.path, message: 'deprecated API used' })
      }
    },
  }),
})
```

`PlannedSourceTarget`, (中文(简体) ), `ProjectFileEntry`,以及 `ProjectTargetEntry` 故意省去源文本. 呼吁 `ctx.src.readFile()` 是明确和插件拥有的,所以规则控制了源文件 并保留了多久。 缓存命中不引用处理器,因此不 执行时读取.

将代理合同用于工具使用规则:

```ts
import { requireAgent } from '@alint-js/core/agent'

const agent = requireAgent(ctx)
```

询问一个验证的、 键入结果的模型 `@alint-js/core/structured-output`它迫使 用于调用一个单一报告工具的模型,该工具的参数与 valibot 计划相符,验证 并反馈到模型中:

```ts
import { generateStructured } from '@alint-js/core/structured-output'
import { array, description, object, pipe } from 'valibot'

const responseSchema = pipe(
  object({ findings: array(findingSchema) }),
  description('Report findings for this file.'),
)

const { findings } = await generateStructured({
  createMessages: retryFeedback => [
    { content: prompt, role: 'system' },
    ...(retryFeedback ? [{ content: retryFeedback, role: 'user' as const }] : []),
    { content: numberedSource, role: 'user' },
  ],
  logger: ctx.logger,
  metering: ctx.metering,
  model: await ctx.model(),
  operation: 'my-rule-judge',
  schema: responseSchema,
})
```

报告工具的名称 `reportFindings` 默认(`toolName` 超过它)及其 描述默认到 schema 的 valibot `description(...)`。 。 。 . `toolParametersFromSchema`, (中文(简体) ), `formatSourceWithLineNumbers`,以及 `formatOutputLanguageInstruction` 为呼叫者输出 建立自己的工具 或提示。 使用 `ctx.agent` 当模型需要时 在回答前用工具来探索,因为强制工具呼叫是一发一发,而不是循环.

### 语文

核心解析 JavaScript 和 TypeScript. 其它东西都用插件注册 所以规则是 哪些语言可以读取,核心决定如何交接:

```ts
defineRule({
  create: () => ({ onTargetFunction: (target) => { /* ... */ } }),
  languages: 'any',
})
```

| `languages` | 规则收到 | 名称语言 无注册 |
| --- | --- | --- |
| 删除 | 仅文件目标,从不函数或类 | 不适用 |
| `'any'` | 每种语言,但 `plaintext` | 从不失败 |
| `['go', 'rust']` | 只有这些语言 | 运行失败, `alint/missing-language` |
| `{ ids: ['go'], skipMissing: true }` | 只有这些语言 | 悄悄跳过 |

`'any'` 不包括 `plaintext` 这是故意的 当一个文件没有语言时, 普通文本会回到什么位置 请求其扩展,所以要求使用语言的规则,否则会被解析出文本. 当这种情况发生时,运行报告 `alint/unregistered-language` 每延长一次——警告 默认, 可配置通过 `linterOptions.reportUnregisteredLanguages`。 。 。 .

宣布名单是更严格的选择。 当用户未安装包时, 运行失败 它提供了其中之一, 而不是让规则 匹配无 和看起来像一个通过.

一个插件通过描述如何将文件变成目标来注册语言 :

```ts
definePlugin({
  languages: {
    zig: {
      extensions: ['.zig'],
      extract: file => [/* SourceTarget[] */],
      name: 'zig',
    },
  },
})
```

Ids是编辑器使用的识别器—— `go`, (中文(简体) ), `python`, (中文(简体) ), `typescript`, (中文(简体) ), `plaintext`。注册失败 在重复名称或扩展名上,因此两个插件永远不能要求同一语言.

来个 `FunctionInfo` 下级 `metadata.function` 和文件的调用站点 下级 `metadata.calls` 在文件目标。 这两个键让规则读懂任何语言 没有自己的分析.

`@alint-js/languages` 提供去,Python和Rust这样.

要解析一个文件, 运行未被要求擦入, 例如, 当构建全工作空间索引时, 使用 `ctx.src.extract(path)`。它解决了文件本身的配置和语言,并且不返回一个 文件配置忽略而非丢弃.

## 何时使用

-   你在写一个 `alint` 插件或规则包.
-   您正在添加语言处理器或源提取器 .
-   您正在嵌入 `alint` 在另一个工具.
-   您正在执行一个 `AgentAdapter`。 。 。 .
-   您需要全项目分析, 能够消耗紧凑的描述符 和懒散地装入源 .

## 不使用时

-   使用 `@alint-js/cli` 用于命令行和普通 `alint.config.*` 文档.
-   使用 `@alint-js/config` 仅用于设置 TOML、配置加载和配置文件工具.
-   需要持续存储器数据库的插件应建立和注入该数据库. 不保留每个 `SourceFile` 返回时间 `ctx.src.readFile()` 以代替一个.

## 内存边界

`alint` 同步源规划读取并解析工作。 计划释放丰富的提取器 值; 队列任务不会保留源文本。 无法约束 插件代码后保留源文件 `ctx.src.readFile()` 返回.

由相同者撰写的有效缓存 `alint` 版本仍然从一个单一的JSON文档读取. 因此,巨大的缓存可能会耗尽现有的内存.

每次缓存规则任务完成后, `alint` 在释放缓存检查点前写入该检查点 排程档. 每个检查点在解剖上取代了单质缓存文件. 运行中断 因此,可以重新使用已经具有持久性的每一种结果,但大型缓存可引起 运行时有大量磁盘写入, 并丢失了许多缓存 。 缓存点击,跳出任务,失败任务, 并且选择退出缓存的规则不会添加检查站的文字。 检查点或最后缓存写入 错误是致命的,并导致运行失败.

## 常见问题

### @alint-js/core 是什么？

公共规则和插件 SDK 和运行 alint 的引擎

### 如何安装 @alint-js/core？

在项目目录运行 npm install @alint-js/core，或使用 pnpm add / yarn add / bun add。

### @alint-js/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @alint-js/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @alint-js/core 可以商用吗？

@alint-js/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @alint-js/core 的下载量有多少？

根据 npm 官方下载统计，@alint-js/core 在 2026/10/06 – 2026/11/04 这 30 天内被下载 94,044 次，日均约 3,135 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alint-js/core 还在维护吗？

最新版本 0\.7\.3 发布于 2026/09/29（1 个月前）；至今共发布 51 个版本，其中过去 12 个月发布了 51 个；首次发布于 2026/07/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。