code-auditor-mcp

代码审计器

在 AI Agent 的编辑循环中强制执行架构不变量。当 Agent 编写的代码违反项目规则时，代码审计器会捕获并阻止此次编辑。Agent 会看到规则提示，并自行修复。

安装

npm install -g code-auditor-mcp
code-audit install --agent all

只需两条命令，即可在所有工具中安装。code-audit install --agent all 会将技能复制到你机器上的每个 AI 编码工具中。使用 --agent 指定特定工具。

每个工具会获得：技能（SKILL.md）、MCP 服务访问权限，以及工具支持时的钩子接线（Claude Code 和 Codex 中会阻止编辑，Cursor 中仅提供提示）。

code-audit install --list   # see the support matrix

Claude Code 用户也可以通过插件安装：

claude plugin marketplace add BenAHammond/code-auditor-mcp
claude plugin install code-auditor

钩子会在首次使用时通过 npx 自动安装审计器。

要求

• Node 18+ 才能运行。使用 Node 23.4+ 可实现无需原生安装：代码审计器使用内置的 node:sqlite 模块，因此安装时无需编译或下载预编译二进制文件。
• 在较旧的 Node（18–23.3）上，代码审计器会回退到 better-sqlite3。这是一个可选依赖，其安装脚本必须在 npm 11.2+/12 上获批一次（这些版本默认会阻止依赖安装脚本）： npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3 （使用 pnpm 时：运行 pnpm approve-builds，然后选择 better-sqlite3）。

配置

项目级设置位于 .codeauditor.json 中（不变量规则、分析器设置和阈值）。此外，还有 11 个环境变量用于调整进程级行为——工作池大小、守护进程和作业队列超时、索引位置、SQLite 后端以及 UI 端口。

变量	用途	可接受的值	默认值
CODE_AUDITOR_WORKERS	用于按文件分发任务的阶段模型工作池大小。1 会强制使用串行路径，以生成字节级一致的报告。	正整数	max(1, cpus − 1)
CODE_AUDITOR_RULE_TIMING	按规则统计墙钟时间（每个规则 ID 累计一个计时器，并显示在报告中）。	1 启用；未设置则禁用	关闭
CODE_AUDITOR_DAEMON_IDLE_MS	守护进程关闭前的空闲超时时间。	正有限毫秒数；无效时使用默认值	300000（5 分钟）
CODE_AUDITOR_DAEMON_LEASE_TTL_MS	守护进程心跳租约 TTL。	有限毫秒数；空白或 0 时使用默认值	60000（60 秒）
CODE_AUDITOR_DATA_DIR	覆盖代码索引数据库目录。	目录路径（会去除首尾空白；空白时使用默认值）	用户级操作系统缓存
CODE_AUDITOR_EXIT_ON_FATAL	发生未捕获异常或未处理的拒绝时退出 MCP 服务。	1 或 true	关闭
CODE_AUDITOR_JOB_TIMEOUT_MS	排队审计任务的单任务超时时间。	有限毫秒数，限制在 60s–4h；低于下限时使用默认值	1800000（30 分钟）
CODE_AUDITOR_JOB_LEASE_TTL_MS	用于回收过期 running 作业行的心跳租约 TTL。	严格为正的有限毫秒数；无效时使用默认值	30000（30 秒）
CODE_AUDITOR_MAX_RUNNING_JOBS	同时运行的排队审计任务的最大数量。	整数 ≥ 1；无效时使用默认值	1
CODE_AUDITOR_SQLITE_BACKEND	强制指定 SQLite 后端。无效值会被报告为无效并拒绝，不会静默探测其他后端。	node-sqlite | better-sqlite3	自动（探测）
MCP_UI_PORT	HTTP UI 服务端口（--ui）。	端口号；无效时使用默认值	3001

设置 CODE_AUDITOR_DATA_DIR 时，索引会按项目隔离（<dir>/projects/<sha256(root)[:16]>/index.db），避免项目之间泄露数据。未设置时，索引位于用户级操作系统缓存中（<os_cache>/code-auditor/projects/<hash>/index.db），因此不会落在受审计的代码仓库中。

提示词示例

“索引代码库并运行完整审计，然后使用 code-audit next-file 逐个检查违规文件。”

“创建一个 .codeauditor.json，禁止导入 lodash，并阻止 src/languages/ 导入 src/analyzers/ 中的任何内容。”

“运行完整审计，修复优先级最高的文件，然后重复运行 code-audit next-file，直到代码树中没有问题。”

“同步代码索引，并且只审计相对于 main 发生更改的部分。”

“添加一条 ast-pattern 规则，阻止使用 new Function(...)。”

“添加一条命名规则，要求 src/hooks/ 中的钩子以 use 开头。”

“添加一条调用约束，规定 src/services/payment.ts 中的 chargeCustomer() 只能从 src/api/ 调用。”

规则类型

共有七种类型。Agent 会将规则写入 .codeauditor.json。配置错误会导致审计失败，而不会被静默忽略。

类型	阻止的内容
import-ban	禁止的模块导入
call-constraint	来自未授权文件的函数调用
module-boundary	跨模块边界的导入
naming	与模式不匹配的导出符号
ast-pattern	匹配 ast-grep 模式的 AST 节点
style-mechanism	每个文件或 glob 中未批准的样式机制
no-raw-values	特定 CSS 属性的硬编码值

适用于你的 Agent

一个技能、一条 CLI 命令、一个 MCP 服务。每个 Agent 都使用相同的审计引擎，唯一的区别在于钩子契约。

Agent	技能	钩子 / 阻止	MCP	已验证
Claude Code	插件或 code-audit install	是 — 阻止	是	2026-07-19
Cursor	code-audit install --agent cursor（仅限项目）	提示	是	2026-07-19
Codex	code-audit install --agent codex + 插件	是 — 阻止	是	2026-07-19
Gemini CLI	code-audit install --agent gemini	否	是	2026-07-19
VS Code / Copilot	code-audit install --agent agents	否	是	2026-07-19
其他 SKILL.md 工具	code-audit install --agent agents	否	是	2026-07-19
ZCode	code-audit install --agent zcode	否（仅限插件）	是	2026-09-10

MCP 配置生成支持的范围比技能安装更广。 MCP 服务的 generate 工具会为以下任一客户端写入客户端配置文件：claude、codex、cursor、gemini、copilot、continue、awsq（AWS Q Developer）、codeium（Codeium/Windsurf）、vscode、cline 和 zcode。其中四个——Continue、AWS Q Developer、Codeium/Windsurf 和 Cline——仅支持 MCP：它们没有基于文件的技能或钩子路径，因此要通过 generate 工具连接，而不是使用 code-audit install。

钩子行为：阻止表示 diff 范围内的 changed 门禁被触发——声明了 gating: true 的不变量规则（这是一个二元的、按规则设置的标志，与严重性无关）会阻止编辑生效（Agent 会看到违规并在原处修复）。提示表示违规会通过可用的最强反馈渠道报告，但编辑已经发生。Cursor 的 afterFileEdit 钩子会即发即弃，不会读取输出。所有环境都支持 MCP，以便在无需 shell 的情况下使用。

发现：确定性与提示性

Code Auditor 的内置规则分为两类：

类别	含义	示例
确定性	结构性事实——工程师会对每项发现采取行动	single-responsibility（300 行函数）、solid/method-complexity（圈复杂度 > 20）、solid/class-size（包含 40 个或更多方法的类）、dependency-inversion（存在接口时仍导入具体实现）
提示性	启发式信号——可能因领域而异，未必准确	sql-injection-risk（不含类型信息的 AST 级字符串模式匹配）、missing-org-filter（特定领域规则——假定 SaaS 租户隔离）、unknown-table（需要用户提供架构）、dry/duplicate（令牌完全相同的代码块）

确定性规则的默认严重级别为 critical 或 severe。提示性规则的默认严重级别为 severe 或 high。在真实语料库上验证后精确率接近零的规则默认禁用（off）——用户可在规则符合自身领域时选择启用。

重新校准

内置严重级别默认值根据真实语料库的分类结果重新校准。当前默认值基于三个语料库的测量结果：本工具自身的代码库、Gin 和 Excalidraw。在这三个语料库中，六条数据访问规则的精确率均接近零，因此默认禁用。

每条禁用规则都会说明它适用于哪类语料库。用户可以通过 .codeauditor.json 中的 severityOverrides 恢复任意规则：

{
  "severityOverrides": {
    "sql-injection-risk": "critical",
    "missing-org-filter": "severe",
    "loop-query": "severe"
  }
}

严重级别覆盖全局生效（优先于按目录设置的路径配置上限）。将规则设为 "off" 会将其完全从输出中移除。

SQL 注入检测

重新校准后，sql-injection-risk 规则默认禁用（off）。在自审计语料库上，该规则的精确率为 0%——它将 TypeScript 模式匹配代码（例如工具自身用于 SQL 检测的 'SELECT'、'FROM'、'WHERE' 等字符串常量）误判为数据库查询。在 Gin 和 Excalidraw 语料库上，该规则的精确率也接近零。

适合重新启用的情况：项目通过字符串拼接或模板字面量构造 SQL，且相关函数的唯一用途是组装查询。该规则可检测这些模式。对于仅使用 ORM 或参数化查询的代码库，此规则会产生噪声。

重新启用并拦截 SQL 注入：

{
  "severityOverrides": {
    "sql-injection-risk": "critical"
  }
}

设置 sql-injection-risk: critical（并将该规则标记为 gating）后，Agent 的钩子会阻止引入 AST 级 SQL 注入模式的编辑。

忽略项

每项发现都是一项测量，而非定论——但测量偶尔会出错。当 Agent 遇到误报时（规则通常正确，但不适用于这段特定代码），可以忽略这一处，而不是绕过规则：

code-audit dismiss <fingerprint> --reason "generated code, not hand-written"

<fingerprint> 来自 JSON 报告（每条违规记录都包含一个 fingerprint 字段）。必须提供书面 --reason，且忽略操作只会清除一项发现——规则 + 文件 + 符号，因此同一规则在其他位置仍会触发。忽略项保存在提交到代码库的 .codeauditor.dismissals.json 中，可在差异中审查。

匿名驳回反馈（选择加入）

Agent 驳回某项发现时给出的原因，是改进规则最有用的信号。Code Auditor 可以将已驳回的发现发送到用于收集这些信息的匿名反馈服务。

该功能默认关闭，只能通过以下三种方式之一明确选择加入（按优先级排序）：

1. 单次调用——code-audit dismiss --telemetry … 仅发送这一次驳回；--no-telemetry 则会禁止发送这一次。
2. 环境变量——CODE_AUDITOR_TELEMETRY=1（或 0），作为无头运行／CI 运行的机器级默认设置。
3. 持久化设置——使用 code-audit telemetry status|enable|disable（或 telemetry MCP 工具），将选择记录在用户配置目录中。

telemetry enable 无需参数：它会选择加入内置服务端点（可覆盖以支持自托管）。选择加入后会生成一个匿名安装 ID：在本地随机生成，绝不根据你的机器、用户或项目生成，仅用于按来源归类提交数据。

发送的内容——工具版本、规则 ID、紧急程度、按原样输入的驳回原因、结构化 AST 签名（仅包含语法类型，绝不包含其内容）、粗略的语言提示、时间戳和匿名安装 ID。绝不发送的内容——源代码、标识符、字面量、文件路径，以及任何从你的代码或环境中推导出的信息。发送尽力而为：若处于离线状态或无法访问端点，则会静默处理，绝不会阻止编辑或导致门禁失败。

样式智能

Code Auditor 会为项目中的每条样式声明建立索引，包括 CSS、SCSS、Tailwind、内联样式和 CSS-in-JS。样式规则会读取全局分布，并标记单文件代码检查工具无法发现的样式碎片化问题。

7 个检测器，10 个规则 ID：

检测器	检测内容
值漂移	近似重复的颜色值（delta-E < 2.0），以及某个值占主导时的精确值离群项
偏离比例尺	不在推断出的项目比例尺上的 margin/padding/gap/font-size 值
未定义的类	没有匹配 CSS 选择器或 Tailwind 工具类的 className 值
绕过设计令牌	与设计令牌匹配、却未引用该令牌的硬编码值
实现机制碎片化	同一个 (property, value) 通过 ≥ 3 种机制（CSS、内联样式、Tailwind）实现
声明集相似度	声明相同率 > 90% 的两个 CSS 规则块
z-index 泛滥	全项目的 z-index 清单——不同值过多或存在孤立的单个值

样式规则会读取全项目的 SQLite 索引，因此，限定范围的运行（仅处理变更文件）仍会与完整的项目基线进行比较。在限定范围的运行中出现新的 #273828 漂移颜色时，也会根据完整语料库中的 #1e2328 值将其捕获。

样式不变量规则：

{
  "rules": [
    {
      "kind": "style-mechanism",
      "message": "Only Tailwind in src/components/",
      "allow": ["tailwind"],
      "path": "src/components/**"
    },
    {
      "kind": "no-raw-values",
      "message": "No raw colors in src/pages/ — use design tokens",
      "properties": ["color", "background-color"],
      "path": "src/pages/**"
    }
  ]
}

样式搜索运算符——按属性、值、机制或令牌搜索：

code-audit search "css:margin-top value:16px"          # specific value
code-audit search "mechanism:inline css:color"          # inline color declarations
code-audit search "token:--color-primary"                # bypassing a design token

React 规则还增加了原生元素检测：如果你的项目有一个 Button 封装组件，那么在 Button 定义之外使用原生 <button> 会被标记为严重问题。

许可证

MIT