alint

alint 是一个 eslint 启发了用于需要再外观的气相编码代码的代理代码分析工具. 它针对源文件运行模型后置规则,以熟悉的lint格式报告诊断,让规则作者在规则需要更深入上下文时使用平版模型调用或可互换工具使用代理.

虽然 alint 灵感来自 eslint我们期望这个概念 alint 使表格成为代码分析的新范式。 它不应仅限于JavaScript/TypeScript. 您可以将此扩展至其他语言, 非代码的文物, 生成的文件, 或任何插件知道如何审查的内容 .

目录

• 安装和使用
• 概念
• 软件包
• 文档自动化
• 发展
• 状态
• 许可证

安装和使用

先决条件

alint 被写入TypeScript,并作为JavaScript和TypeScript项目的无害环境管理包发布. 发布构建还包括独立的二进制,因此在Python,Go,Rust等非Node.js项目工作的团队可以在不设置Node.js,npm,或pnpm的情况下运行CLI.

您还需要至少一个 OpenAI 兼容模型提供者 。 Ollama 和 LM Studio 等本地供应商.

安装 CLI

从 GitHub 中下载一个独立的二进制, 如果您想要使用的话 alint 没有节点Js工具链.

如果您想要的话, 在全球安装 alint 在所有位置可用的命令 :

npm install -g @alint-js/cli
pnpm add -g @alint-js/cli

或者安装在一个项目中,并通过您的软件包管理器运行:

npm install -D @alint-js/cli
npx alint src

pnpm add -D @alint-js/cli
pnpm exec alint src

配置模式提供者

使用 alint setup 以写入提供者配置。 这个 -N 旗帜短于 --no-interactive,因此设置可以在脚本中运行,也可以通过编码代理运行,而不打开交互式TUI.

无 --local,设置将全局配置写入 ~/.config/alint/config.toml与 --local写着 .alint/config.toml 在当前项目中.

提供者管理命令使用相同的范围政策: 默认情况下编写目标为全局配置,以及 --local 选择当前工程的配置。 更新现有的提供者或编辑单个字段:

alint config providers update --provider openrouter
alint config providers set --provider openrouter endpoint https://openrouter.ai/api/v1
alint config providers set --provider openrouter headers.Authorization "Bearer $TOKEN"
alint config providers unset --provider openrouter headers.Authorization

providers update 探测提供者并添加新报告的模型。 它默认是添加剂,不会仅仅因为远程提供者不再报告而自动删除所配置的模型。 在交互式 TUI 中,取消一个已配置的模型在确认更新时删除它. 使用破坏性 models prune 命令,当您打算删除已配置的模型,而不包含提供者的响应.

提供者检查、命令输出和故障报告只显示标题;它们从来不打印标题值。 作为命令参数提供的标题值可能仍然保留在 shell 历史中 。 使用环境变量, 如 $TOKEN不是字面上的证明.

alint setup -N \
  --provider-endpoint http://localhost:11434/v1 \
  --provider-model qwen:8b

当寄存器应当携带自己的模型映射时, 将提供者设置到当前项目中 :

alint setup -N \
  --local \
  --provider-endpoint http://localhost:11434/v1 \
  --provider-model qwen:8b

alint setup -N \
  --provider-endpoint http://localhost:1234/v1 \
  --provider-model qwen:8b

export OPENROUTER_API_KEY="sk-..."

alint setup -N \
  --provider-endpoint https://openrouter.ai/api/v1 \
  --provider-header "Authorization=Bearer $OPENROUTER_API_KEY" \
  --provider-header "HTTP-Referer=http://localhost" \
  --provider-header "X-OpenRouter-Title=alint" \
  --provider-model openrouter:fusion

export OPENAI_API_KEY="sk-..."

alint setup -N \
  --provider-endpoint https://api.openai.com/v1 \
  --provider-header "Authorization=Bearer $OPENAI_API_KEY" \
  --provider-model gpt-5.4-mini

运行 Alint

根据文件或目录运行 CLI :

alint src
alint demo.ts
alint --format json demo.ts

- 脏了

使用 --dirty 没有文件参数, 仅插入与当前文件不同的文件 HEAD数字 :

alint --dirty

这包括从Git寄存器根上分级,未分级,和未跟踪的文件. 被忽略和被删除的文件被排除在外. 注册的子单元工作树不包括在内。 一个干净的寄存器成功退出而不产生 lint 输出 .

--型号

覆盖一次性运行的匹配模式 :

alint --model qwen:8b demo.ts

- 朗语

当项目本地设置没有配置任何模型时,没有规则级或呼叫级选择器的模型调用 default 别名来自全球设置。 规则选择者继续使用正常的模型匹配. 配置至少一个模型 .alint/config.toml 恢复未选中调用的项目首个匹配 。 明确 --model 绝对优先.

要求模型支持的规则以特定语言写诊断:

alint --lang zh-CN src

--规则

仅运行规则一个过滤名, 读取规则的发现而不支付运行中的其他规则:

alint --rule docs/review-copy src
alint --rule 'docs/*' src
alint --rule docs/review-copy,docs/naming src

匹配配置规则 ID 的图案 (plugin/rule)或作通则自名. 旗帜可重复并接受逗号分隔列表. 被过滤的规则没有计划,因此运行既不呼叫他们的模型,也不报告他们的诊断. 当过滤器匹配没有启用的规则时, 运行失败并列出它所启用的规则 ID , 因为静默的空运行是无法区分的 .

alint 返回退出代码 0 当诊断没有错误,包括只发出警告。 它回来了 1 报告至少一个错误诊断 2 当命令由于配置、输入或运行时失败而无法完成时. alint output inspect 使用相同的退出代码行为来保存结果.

检查配置和输出

有用的 CLI 命令 :

alint config inspect src/index.ts
alint config providers list
alint config providers show openrouter
alint config models list
alint config models show ollama/qwen
alint config models probe --endpoint http://localhost:11434/v1
alint config models rm qwen --provider ollama
alint config models prune --provider ollama -N --yes

当在多个提供者下存在一个模型ID时,将其定性为: <provider>/<model-id> 或通过 --provider <provider-id>配置突变全局写入,除非 --local 选择当前工程的设置配置.

models rm 删除一个精确配置的模型. models prune 探测器提供商模型端点并破坏性地去除已配置的不再报告的ID. 互动 prune 请求确认; 脚本必须通过 -N --yes。 。 。 .

保存机器可读输出并稍后检查,而不重运行模型调用 :

alint --format json src > alint-output.json
alint output inspect alint-output.json

编辑器集成

alint lsp 在 stdin 和 stdout 上作为语言服务器运行。 任何有 LSP 支持的编辑器都可以 用这个.

服务器是缓存第一。 它发布诊断 早期运行存储, 它从来不叫a 单靠模型,所以打开一个工作空间不费钱。 冷的缓存显示没有诊断。 运行 alint 一次填满它.

当编辑器打开工作空间时会出现诊断,当您保存一个文件时它们会刷新. 这个 服务器重装 alint.config.ts 变化后.

配置编辑器以启动命令 。 在尼奥维姆:

vim.lsp.config.alint = {
  cmd = { 'alint', 'lsp' },
  root_markers = { 'alint.config.ts' },
}

服务器宣布了3个命令. alint.runFile 财务报告和审定财务报表 alint.runWorkspace 开始运行此调用 模型和支出符号;既报告进展,也接受取消. alint.clearCache 删除 缓存诊断.

VS 代码

扩展名在 apps/vscode 启动服务器并显示诊断。 未发表 到市场还没有。 要运行它从一次离职:

pnpm -F @alint-js/vscode build
code --extensionDevelopmentPath=apps/vscode/dist /path/to/your/project

扩展查找可按此顺序执行的 Alint : alint.path 设置,然后 node_modules/.bin/alint 在工作空间文件夹中,然后 PATH。工作空间安装需要 优先级,所以服务器和终端运行使用相同的缓存.

代码止门插件( 可选)

安装

代码插件添加了运行的停止钩 alint --dirty 在代理结束前.

运行这些命令从寄存器的默认分支安装插件. 这些命令不选择最近的发布 :

codex plugin marketplace add moeru-ai/alint \
  --sparse .agents/plugins \
  --sparse plugins/codex-plugin-alint
codex plugin add alint@alint

要从发布中安装, 请使用其 Git 标签 :

codex plugin marketplace add moeru-ai/alint \
  --ref vX.Y.Z \
  --sparse .agents/plugins \
  --sparse plugins/codex-plugin-alint
codex plugin add alint@alint

替换 vX.Y.Z 带有要求的释放标记。 当 Codex 问起时审查并信任"停止"钩子. 插件在寄存器启用 Stop Gate 之前不活动 .

配置

代码插件明确要求每个repo启用. 使用此命令启用当前寄存器 :

• .toml: 运行 alint config integrations stop-gate enable
• .js/.ts: (中文(简体) )

export default defineConfig([
  // ...
  {
    integrations: {
      stopGate: {
        enabled: true,
        // target: 'dirty-files' | 'all'
        // timeoutMs: 900000
      },
    },
  },
  // ...
])

概念

alint 保持熟悉的线条形状:选择目标,应用命名规则,报告诊断,并返回CI能够理解的退出代码. 不同的是,当仅用语法检查是不够的时,一个规则可以通过模型调用或工具使用代理来达到判断.

alint 用户端

配置

alint 使用两个配置系统,并有不同的计划和责任:

机器或项目提供者定义使用设置 TOML :

version = 1

[[providers]]
id = "http://localhost:11434/v1"
type = "openai-compatible"
endpoint = "http://localhost:11434/v1"

[[providers.models]]
id = "qwen:8b"
name = "qwen:8b"
size = "small"
capabilities = [ "tool-call" ]

[providers.models.default_params]
thinking = { type = "disabled" }

default_params 合并到每个聊天请求中,用于该模式。 用于模型条目其他部分未覆盖的供应商特定请求字段.

CLI还可以推出ACP编码代理指令并暴露其作为普通模式的规则. 交互式 alint setup 提供克劳德代码,代码x,双子座CLI,基米代码CLI和OpenCode的预设:

version = 1

[[providers]]
id = "acp"

[[providers.models]]
id = "codex"
name = "Codex ACP"
driver = "acp"
aliases = [ "default" ]
capabilities = [ "tool-call" ]
command = "codex-acp"
args = []
cwd = "."

然后运行 alint --model acp/codex src。登录 alint.config.ts 仍保留 lint 策略; 进程命令只来自全局设置或 .alint/config.toml。命令继承了启动的环境 alint; 可选模式 env 条目为字面上覆盖,不应包含承诺的证书。 每个同时提出的请求都启动一个非加太进程,请求工具需要代理商的MCP-over-HTTP支持.

alint 结构化输出迫使一个工具调用(tool_choice) (中文(简体) ). 一些模型,如DeepSeek V4,在启用思维/推理时拒绝这种组合. 对于这些模型,设置 thinking = { type = "disabled" } 如上,结构输出可以运行.

请注意: -N 代表着 --no-interactive,这意味着这不是交互式设置。 不需要TUI,所以可以要求Codex或Claude Code为您运行这个命令.

您还可以使用 --local 将配置写入当前工程 :

alint setup -N \
  --local \
  --provider-endpoint http://localhost:11434/v1 \
  --provider-model qwen:8b

• 无 --local, (中文(简体) ), alint 在下方写入全局配置 ~/.config/alint/config.toml。 。 。 .
• --local 写入 .alint/config.toml 在当前项目中.
• 您可以使用 alint config 命令组.

代码停止门

通过同一工程配置系统配置可选的 Codex Stop Gate 集成 :

alint config integrations stop-gate enable
alint config integrations stop-gate show
alint config integrations stop-gate set --target all --timeout-ms 1800000
alint config integrations stop-gate disable

停下来 门默认被禁用, 仅在寄存器明确设置时运行 integrations.stopGate.enabled = true。激活后的默认值为 target = "dirty-files" 财务报告和审定财务报表 timeoutMs = 900000; 最大超时为 86100000 (23小时55分),在插件的24小时Codex钩限内留有5分钟,用于启动和坚持. 写入器只坚持非默认的覆盖,只扩展现有的 TOML 写入路径;它不会将配置写入器扩展至其他格式. 读取 plugins/codex-plugin-alint 用于完整运行时间行为的文档.

使用规则插件( P)

类似 eslint,使用时 alint.config.ts 文件、 忽略、 插件和规则 :

import { defineConfig } from '@alint-js/cli'
import { examplePlugin } from '@alint-js/plugin-example'

export default defineConfig([
  {
    files: ['**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}'],
    ignore: {
      // Reads applicable nested .gitignore files when selecting lint targets.
      // This is powered by gitignore-fs.
      gitignore: true,
    },
    plugins: {
      example: examplePlugin,
    },
    rules: {
      // The `example` prefix is the local alias configured above.
      'example/inline-miniature-normalizer': 'warn',
      'example/no-redundant-jsdoc': 'warn',
      'example/no-trivial-wrapper-stack': 'warn',
    },
  },
])

内嵌配置

每个 alint.config.* 在寄存器根下方与根配置一起被加载,每个文件被范围化到包含它的目录上:

// packages/app/alint.config.ts
import { defineConfig } from '@alint-js/cli'

import { appPlugin } from './alint/plugin'

export default defineConfig([
  {
    plugins: { app: appPlugin },
    rules: { 'app/layer-boundary': 'error' },
  },
])

以上项目达到 packages/app/** 只有这个. files, (中文(简体) ), directories,以及 ignores 解析与宣布它们的配置的目录相对应,一个不声明目标模式的项目覆盖了它的整个子树,一个更深的配置覆盖了它自己的目录的外侧. 因此,拥有一条规则的软件包需要一个文件,而不是根配置中的条目加上每个读取它的工具所重复的相同范围.

• 发现跳过隐藏目录, node_modules,并构建产出(build, (中文(简体) ), coverage, (中文(简体) ), dist, (中文(简体) ), out, (中文(简体) ), vendor) (中文(简体) ).
• --config <path> pins 精确到一个配置文件并禁用发现, 因此 CI 任务可以运行一个特定的配置 .
• 每个配置文件共享一个插件别名空间和一个插件锁文件,以及 alint plugin install 安装嵌入配置声明的插件。 两个文件将一个别名绑定在不同的分光符上会使负载失败,而不是静默地解决其中之一.
• 保持项目范围规则( :onTargetProject) 在root配置中:项目目标坐落在被嵌入项的基道外,因此被嵌入的配置无法声称.

可执行和静态配置

alint 支持可执行配置( e).js, (中文(简体) ), .ts, (中文(简体) ), .mjs, (中文(简体) ), .cjs, (中文(简体) ), .mts,以及 .cts)和只数据静态配置(.toml, (中文(简体) ), .yaml, (中文(简体) ), .yml, (中文(简体) ), .json, (中文(简体) ), .jsonc,以及 .json5) (中文(简体) ).

• 可执行配置导出一个平面配置阵列,并可直接导入插件定义.
• 静态配置使用一个 config.group 阵列并识别带有字符串的插件源。 它们对于 Python, Rust, Go 和其他不想要编写 JavaScript 配置文件或安装仅用于运行的 Node.js 软件包管理器的寄存器有用 alint。 。 。 .

例如,一个TOML静态配置可以安装精确的远程包或本地插件目录:

[[config.group]]

[config.group.plugins]
plugin_1 = "@scope/[email protected]" # package
plugin_2 = "./plugins/relative-plugin-examplex" # relative directory
plugin_3 = "/opt/alint/plugins/absolute-plugin" # absolute directory

从包含配置文件的目录中解析相对插件路径, 包括何时 --config 指向被嵌入的配置. 在 Windows 上,使用 TOML 文字字符串来保存原生后鞭:

[[config.group]]

[config.group.plugins]
native = 'C:\alint\plugins\native-plugin'

使用 alint plugin install 在添加或更改插件源后.

• 软件包 : @scope/[email protected] 下载该精确版本到 .alint/plugins/store,验证其完整性,并装入其根输出.
• 当地 : ./plugins/my-plugin 或绝对目录加载当前包根导出的位置. alint 检查软件包和条目是否存在,且该条目留在软件包目录中。 它不构建插件或安装插件的依赖性.

宣告本地规则插件

对于简单的即时备份规则,本地插件目录可以省略 package.json 并包含一个或多个 rule.alint.* 文件 :

# rules/architecture/semantic/rule.alint.toml
name = "semantic-boundary"
builtInAgent = "basic-structured"
instruction = """
Find semantic boundary problems in the reviewed source.
Report concrete findings with line numbers and short suggestions.
"""
includeFiles = [ "src/**/*.py" ]
excludeFiles = [
  "**/*_test.py",
  "**/vendor/**",
]

通过相同的静态引用目录 plugins 表格显示:

[[config.group]]
files = [ "src/**/*.py" ]
language = "plaintext"

[config.group.plugins]
arch = "./rules/architecture"

[config.group.rules]
"arch/semantic-boundary" = "warn"

name 成为当地规则 id. builtInAgent 可能会是 basic-structured 仅限快速结构化输出规则或 basic-coding-agent 对于一个带有文件系统工具的小型内置代理. includeFiles 财务报告和审定财务报表 excludeFiles 确定可在哪些地方报告诊断;它们不限制什么 basic-coding-agent 可以检查.

编辑规则 instruction, (中文(简体) ), includeFiles,或 excludeFiles 无效它缓存的解析结果: 一个声明规则宣布这些输入为它的缓存密钥, 因此更改的规则文本永远不会重放 stale 解析结果 .

更改源字符串,移动本地目录,或更改其同位链接目标后,再次运行安装命令. 同一本地目录内的变化由下一个CLI进程加载而无需重排.

本地插件执行为可信任的节点.js代码 。 目录封存检查验证已安装的源; 它们不是一个沙盒 .

插件锁文件

alint plugin install 写入 .alint/plugins/lock.json。软件包条目锁定下载的软件包和完整性元数据。 本地条目在运行时装入当前内容时会锁定物理目录身份 .

规则的断裂遵循了熟悉的公约:

• "off" 或者说 0 禁用规则.
• "warn" 或者说 1 报告警告.
• "error" 或者说 2 报告错误.

平面配置可以通过选择分析非 JavaScript 文件 plaintext语言标识符 VS 代码的语言标识符,所以注册语言的插件应当使用相同的id:

import docsPlugin from '@your-alint-config/docs-rules'

import { defineConfig } from '@alint-js/cli'

export default defineConfig([
  {
    files: ['docs/**/*.md', '**/*.txt'],
    language: 'plaintext',
    plugins: {
      docs: docsPlugin,
    },
    rules: {
      'docs/review-copy': 'warn',
    },
  },
])

缓存和 Stats

alint 默认的缓存规则目标结果 .alintcache 以避免LLM重复要求源目标不变.

每次缓存规则任务完成后, alint 在释放该工作的调度器位置之前, 写一个缓存检查点 。 每个检查点在解剖学上取代了完整的缓存文件,因此被中断的运行可以再利用已经持久化的每一个结果. 缓存点击, 跳出任务, 失败任务, 以及选择退出缓存的规则不会添加检查点写入 。 任何检查点或最终缓存写出错误,都会导致运行失败.

[注] .alintcache 不应该对吉特负责。 添加到 .gitignore 在进行重复本地分析之前.

echo ".alintcache" >> .gitignore

禁用单个运行的缓存 :

alint --no-cache src

运行数据是默认记录的. 使用 --no-stats 以跳过记录运行,并使用 stats 命令组检查一段时间内保存的用法.

规则开发者侧

为了减少分析过程中的象征性成本,同时允许规则作者指定模型大小和能力, alint 允许规则作者 请求匹配( M) 模型为 能力选择器 财务报告和审定财务报表 大小选择器,而不是硬化整个 alint 运行以对所有规则使用单一模式.

换句话说,你可以在你的机器上设置你的"深搜索"(DeepSeek),"OpenAI"(OpenAI),"Ollama"(Ollama),或者其他"OpenAI"兼容的模型,让规则作者要求一个模型与"OpenAI"(OpenAI)兼容 tool-call 能力及 small 尺寸. alint 将匹配最佳配置的模型.

const model = await ctx.model({
  capabilities: ['tool-call'],
  size: 'small',
})

您也可以打电话 ctx.model() 如果某项规则不需要特定的大小或能力,则无需论证.

关于代理

单位 alint我们并不局限于任何SDK特工 您可以使用从 Eve, Strands, Pi, Claude Code SDK, Codex SDK等框架导出客户端, 或者使用另一个工具运行时间来实施自己的代理来分析代码.

代理规则的使用 ctx.agent 当它们需要多步工具循环时,比如在报告发现前读取相关文件. 该规则保持框架不可知性,用户选择适配器:

import { createApeiraAdapter } from '@alint-js/agent-apeira'
import { createAgentExamplePlugin } from '@alint-js/plugin-example-agent'

export default [
  {
    agent: createApeiraAdapter(),
    extends: ['agent-example/recommended'],
    plugins: {
      'agent-example': createAgentExamplePlugin(),
    },
  },
]

当前适配器包包括:

• @alint-js/agent-apeira 在Xsai堆放的阿皮拉.
• @alint-js/agent-pi 为皮.

然而,要注意象征性成本. alint 它被设计成一个代码分析工具,其中对模型的快速和重复的呼叫是预期的. 本地模型,便宜的小模型,和缓存友好的提示通常比通过大型主机模型来引导每个规则目标更好的默认.

BYOA,任何代理都行

带上你自己的代理 alint 不尝试拥有代理吊带。 规则可以取决于 @alint-js/core 代理合同,而实际运行时间可以是Apeira,Pi,你自己的内部代理,或者一个叫作需要的工具的小功能.

如果缺少适配器,您可以执行缺失的函数,或者将自己的插件包来替换. 重要的部分是,规则 报告诊断通过 alint;代理如何读取文件,调用工具,计划步骤,或与模型交谈,被故意留给适配器或插件作者.

示例规则

规则是普通的 JavaScript 对象, 由公共 DSL 构建 @alint-js/core规则接收源目标并报告诊断结果.

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

export const checkFunctionRule = defineRule({
  create: ctx => ({
    async onTargetFunction(target) {
      const model = await ctx.model({ capabilities: ['tool-call'], size: 'small' })

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

作为插件的软件包规则 :

import { definePlugin } from '@alint-js/core'

import { checkFunctionRule } from './rules/check-function'

export default definePlugin({
  configs: {
    recommended: [
      {
        rules: {
          'my-plugin/check-function': 'warn',
        },
      },
    ],
  },
  rules: {
    'check-function': checkFunctionRule,
  },
})

当规则取决于外部状态时,规则作者可以选择退出缓存:

defineRule({
  cache: false,
  create: ctx => ({
    onTargetFile(target) {
      // Always reruns.
    },
  }),
})

其调查结果取决于投入的规则,其来源并不表明这些投入必须声明为: cacheKey: 导入的提示,共享信件构建器,或构建规则的预设文本. alint 将规则源和 cacheKey 进入每个缓存条目 :

import prompt from './prompt.md?raw'

defineRule({
  cacheKey: { agentVersion: 1, prompt },
  create: ctx => ({ /* ... */ }),
})

没有缓存密钥,编辑即时更改规则在缓存条目仍然有效时对模型的要求,而下一次运行则作为缓存点击重放之前的发现,而根本不运行规则.

软件包

文档自动化

上面的目录是用 doctoc 所以README导航不是手写的. 更改标题后运行 :

pnpm docs:update

docs:update 刷新根 README TOC 然后复制根 README 到 packages/cli/README.md,保留 npm 读取器 @alint-js/cli 与项目概览同步.

发展

此寄存器是一个 pnpm 工作空间 .

pnpm install
pnpm -F @alint-js/cli build
pnpm -F @alint-js/core exec vitest run

发送更改前, 运行 :

pnpm typecheck
pnpm lint

状态

alint 时间很早,API可能会改变。 核心方向是稳定的: lint-tyle诊断,模型后置规则,平面配置,提供者设置,以及可选的代理适配器.

许可证

麻省理工学院