diffgate

DiffGate

编码 Agent 在代码写入磁盘前，对自身运行的确定性护栏。

其他所有检查都为时已晚。代码审查机器人需要 PR。pre-commit 钩子会等 Agent 完成工作并转向其他任务后才运行。DiffGate 是一个 Agent 钩子：你的 Agent 通过 MCP 调用它，在几毫秒内获得结构化发现，不消耗任何 LLM token，并趁仍保留上下文时修复问题——随后，同一套引擎、同一个判定结果，还会在编辑器、pre-commit 钩子和 CI 中运行。这不是让模型给自己的作业打分：相同输入始终产生相同答案。

它从设计上就保持安静。它只评估发生变化的行（🟢 合并 · 🟡 浏览 · 🟠 验证），只有在变更满足条件时才运行测试，也只在满足条件时才阻止合并——在一套公开、有版本记录的语料库上实现了 0 次误拦截，你可以用 diffgate bench 自行重跑（BENCHMARK.md）。人人都声称噪声低；只有这个项目附带了语料库。

为什么它能发现扫描器发现不了的问题 — 我们测量了 Agent 实际会犯哪些错误

在本地模型和前沿模型中：从头编写的代码里，经典 OWASP 漏洞（SQL 注入、XSS、硬编码密钥）的比例为 0%。但同一个能写出完美全新代码的前沿模型，在修改代码时有 13% 的概率重新引入安全隐患——没有防护的递归合并（原型污染）、裸用的 cors()（允许任意来源），以及由请求数据构建但没有路径包含性检查的路径。修改现有代码是 Agent 的大部分工作，而残留问题就在差异中，不在教科书里。用 diffgate marginal 自行重跑。查看测量结果 →

第三方可维护性数据也显示了同样的变化：GitClear 的 2026 年分析发现，自 2023 年以来，代码块重复增加了 81%（每百万条变更行从 40.3 增至 73.0），而跨文件函数关联度下降了 35%——Agent 不再复用代码，而是重新发明。这正是 reinvented-helper 规则的用途（docs/STRUCTURAL-RULES.md）。

等级	含义	你的操作	示例
🟢 绿色	安全 / 独立	自由合并	注释、本地日志记录
🟡 黄色	需要审查（软依赖）	查看一下	已弃用的 API、原生 SQL、网络调用、依赖项修改
🟠 橙色	影响较大，需要设门槛	合并前验证	架构 / 迁移、硬编码密钥、身份验证 / 加密、公有 API 修改、注入点

---

为什么选择 Agent 钩子，而不是另一个代码审查机器人

管道中的每项检查都会在代码写完后触发，而且每一项都比上一项更晚：

	触发时机	问题
代码审查机器人（CodeRabbit、Greptile）	PR 已创建	代码已完成、已经有人为它辩护，而且有人正在等结果
提交前钩子	你完成工作并准备提交时	Agent 已经转向其他任务；你得重新加载上下文才能修复问题
通过 MCP 运行 DiffGate	Agent 仍在编写代码时	它会在代码落地前修复自己的输出

不过，抢先发现问题并非唯一要紧的事——还必须足够安静，否则 Agent 会学会忽略它。代码审查机器人会在 PR 创建后发表评论；代码检查工具和扫描器则会标记所有发现的问题。两者都无法保证高风险代码行得到讨论：我们扫描了 350 个已合并的 AI 辅助 PR——在 109 个包含被标记为 AI 生成的更改的 PR 中，除了作者之外，只有 3 个 PR 引发了任何人的公开讨论。DiffGate 会判断哪些问题值得你关注、值得运行测试或需要阻止提交，其他时候则保持安静。这就是整个产品：

• 仅检查差异。 只报告相对于已提交基线发生更改的代码行上的发现——不产生整文件噪声，也不对你未改动的代码反复讨论。
• 分级分流，而非平铺列表。 三个等级引导注意力：绿色直接合并，黄色扫一眼，橙色需通过门禁。
• 门禁会有选择地运行你的测试。 如果更改为橙色，DiffGate 会运行你的 testCommand，并显示实际退出代码和输出。绿色和黄色更改会立即通过。只有更改的影响确实很大时才会触发测试，因此提交前钩子运行得很快。
• 只有满足条件才会阻止提交。 广泛的跨语言注入问题本身仍仅提供建议；只有在可选代码图谱证明该问题的汇点可从不受信任的入口点（HTTP/事件处理程序）到达时，才会升级为阻止提交的问题。要获得阻止提交的权限，必须有规则依据；要获得图谱提供的阻止权限，则必须有图谱依据。
• 感知更改影响。 使用可选代码图谱时，发现会附带其跨文件影响范围——调用方数量、建议的审查者、未经测试的调用点——而无人调用的导出符号会被降级。跨文件上下文让审查更安静，而不是更吵。
• 速度快。 审查在毫秒内即可完成，只检查更改的代码行——快到足以融入 Agent 和编辑器的内层循环，而不只是用于 CI。
• 噪声低，且可验证。 diffgate bench 会离线运行一个带版本号的语料库：在干净的更改中达到 100% 精确率 / 0 次误阻止。你可以亲自复现——这正是发布语料库的意义。参见 BENCHMARK.md。

测量结果可复现

0% / 13% 这组数据不是营销说辞——它们来自一项脚本化实验（四种从本地到前沿的模型、全新项目与编辑模式、Wilson 置信区间），你可以用 diffgate marginal 重新运行。方法、各模型数据表和注意事项见 docs/MEASUREMENT.md。DiffGate 的安全规则针对实测残留问题进行调校，而非以增加规则数量为目标。

---

快速开始

npm install -g diffgate-review
cd your-repo
diffgate init                    # auto-detects language + test command, writes .diffgate.json
diffgate check --since=HEAD~20   # see what it catches in your own history — no PR required
diffgate check                   # review your pending changes right now

还没有 Git 历史记录或未提交的更改？先查看内置示例的输出：

diffgate init --demo   # live scan, no config or git changes needed

---

使用场景（一个共享引擎，一个判定结果）

1. 在你的编码 Agent 中（通过 MCP）

这是最能发挥作用的环节：Agent 会在生成的代码写入磁盘前自行检查，并返回结构化的发现（不消耗 LLM 令牌），同时展示它修正了什么（原内容 + 修复方案 + 原因），而不是悄悄改写。值得信赖、结果确定的自检机制，能让你放心地赋予 Agent 更大的自主权。

# Claude Code — one command:
claude mcp add diffgate -- diffgate mcp

# One-click via Smithery (zero config):
npx @smithery/cli install diffgate-review --client claude

# Cursor — add to MCP settings:
# { "diffgate": { "command": "diffgate", "args": ["mcp"] } }

也可以在 Claude Desktop 中一键安装：下载 diffgate.mcpb 并打开它。该服务还提供提示词和资源；参见 MCP.md。

2. 在编辑器中（VS Code / Cursor）

更改行上显示行内波浪线，悬停卡片（原因 · 负责人 · 快速修复）、风险审查树、状态栏摘要，以及 深度审查（针对橙色发现项的 Agent 式影响范围分析）。在你审查的差异上，获得与 CLI 完全相同的判定。

从 VS Code Marketplace 或 Open VSX（Cursor / Windsurf / Gitpod）安装。

3. 在命令行中 — 以及 CI 中

diffgate check 会审查你的差异，并在发现高影响问题时以非零状态码退出：本地可用作提交前钩子，流水线中也使用相同的门禁。

diffgate install-hook  # adds .git/hooks/pre-commit; only runs tests on 🟠 orange changes

本地循环是切入点——趁上下文还清晰时修复问题——而且同一引擎也会作为 PR 门禁运行，让判定一路传递到执行门禁的环节，供整个团队使用。有关 GitHub Action、共享经验和组织策略包，请参阅 docs/TEAM.md。CI 运行还可选择通过同一门禁接入外部扫描器（Semgrep），以覆盖更多语言——仅提供建议，默认关闭（docs/CONFIG.md）。

常用命令：

diffgate check                 # review pending changes (the gate)
diffgate check --staged        # staged-only (pre-commit)
diffgate check --since=HEAD~20 # audit recent history, per-commit (see below)
diffgate check --agent         # machine verdict for coding agents
diffgate scan <path>           # analyze files directly (no git needed)
diffgate watch                 # live review as you edit
diffgate guidelines            # review diff against AGENTS.md / CLAUDE.md etc.
diffgate feedback <rule> <f> <l> --dismiss   # suppress a false positive (shared via git)
diffgate mcp                   # start the MCP stdio server

审计近期由 AI 编写的历史记录。 将 check 指向日志中已有的提交——每条发现都会归因于具体提交，因此你看到的是一段历程，而非整个仓库的评分卡：

diffgate check --since=HEAD~20        # last 20 commits, one block per commit
diffgate check --since="2 weeks ago"  # by date instead of a rev
diffgate check --ai-authored          # only agent commits (Claude/Copilot/Cursor/… — heuristic)
diffgate check --author="Claude"      # matches author *and* Co-authored-by trailers
diffgate check <sha>                  # a single commit by hash

历史模式仅生成报告（它审计过去——不会运行你的测试命令，也不会阻止提交），并支持 --json 和 --limit=<n>（默认值为 50）。合并提交会被跳过。

运行 diffgate --help 查看完整命令列表（report、bench、stats、graph、marginal……）。

---

工作原理

• **感知差异：**通过 git diff（CLI）或内存中的 LCS 差异（编辑器，可准确处理未保存的缓冲区）查找更改行；只报告这些行上的发现项。
• 关键位置使用真实 AST：@babel/parser（JS/TS）和 tree-sitter（Python、PHP、Go、Ruby、Java、C#、Kotlin — 通过 WASM，无需原生构建）为精准规则提供支持：已弃用的调用不会在注释或字符串中匹配；会以结构化方式检测导出签名更改；SQL 注入检测则针对 sink、感知参数并识别净化器——cur.execute(f"… {uid}") / $pdo->query("… $id") 会被拦截，而 cur.execute("… %s", (uid,))、$pdo->prepare("… ?")、单引号字符串 '… $id'，以及日志行中的 SELECT 则不会。
• **其他情况一律采用确定性基础规则：**面向 Go、Java、Ruby 和任意文本的注释感知模式规则，覆盖密钥、破坏性操作／架构更改、身份验证／加密、动态执行／调用外部命令、原始查询和网络调用。被注释掉的代码（# os.system(x)）不会被标记；写在注释中的密钥仍会被标记。文档／说明文件（.md、.rst……）也遵循相同标准：变更日志中的 "oauth2-provider" 一词不是身份验证代码，但 README 中粘贴的密钥仍属于泄漏。
• **有依据才拦截：**对于非 AST 语言中跨语言的宽泛注入建议（Ruby #{}、Go/Ruby 调用外部命令），只有可选代码图证明其可从不可信入口到达时，才会升级为阻止级别——使用社区版 CodeGraph，无需 Pro 污点引擎。（JS/TS、Python 和 PHP 会根据本地 AST 证据拦截，无需此功能。）
• **门禁：**出现高影响更改时，DiffGate 会运行你的 testCommand，并显示实际退出代码和输出。
• 经验记录：diffgate feedback 会记录忽略／确认判定；被忽略的发现项（相同规则 + 相同代码）会在所有位置被抑制。记录保存在 .diffgate/learnings.json；提交该文件即可与团队共享。
• **可选扩展：**与服务提供商无关的 AI 层（通俗易懂的说明 + 修复建议），以及通过可选代码图执行的跨文件影响范围分析。两者默认关闭，且不可用时会平稳退化为不执行操作。

引擎结构：src/core（共享） · src/cli.ts（CLI） · src/mcp.ts（MCP） · extension/（VS Code）。

---

覆盖范围因语言而异

DiffGate 对变更的分析深度取决于文件所用的语言——请明确这一点，以便校准你对干净结果的信任程度。

层级	语言	深度
深度（AST）	JS / TS（@babel）	所有注入类别 + 公共 API 和签名变更 + 已弃用 API 的快速修复。原型污染和 NoSQL 注入仅适用于 JS/TS；JS/TS 发现也可通过代码图进行 污点确认。
深度（AST）	Python、PHP、Go、Ruby、Java、C#、Kotlin（tree-sitter）	面向接收点、识别参数和清理器的注入检测——占位符、参数向量和转义器会被正确视为安全。各语言的接收点类别见下文。

深度 AST 各语言的接收点类别（完整详情——包括每种清理器和安全形式，以及代码图边界——请参阅 docs/SCOPE.md）：

• Python（7）— SQL · XSS · 路径遍历 · CORS · 命令 · 代码 · 反序列化
• PHP（8）— SQL · 命令 · 代码 · 文件包含 · 反序列化 · XSS · 路径遍历 · CORS
• Go（4）— SQL · 命令 · 路径遍历 · CORS
• Ruby（6）— SQL · 命令 · 代码 · 反序列化 · XSS · CORS
• Java（6）— SQL · 命令 · 反序列化 · 路径遍历 · XXE · CORS
• C#（7）— SQL · 命令 · 反序列化 · 路径遍历 · XSS · XXE · CORS
• Kotlin（6）— SQL · 命令 · 反序列化 · 路径遍历 · XXE · CORS

SSRF 是适用于全部八种深度 AST 语言的跨语言建议（请求污染的 URL 进入出站请求接收点；限定于特定库且仅针对污染值，因此不会标记静态／配置 URL）。XXE 覆盖 JVM（Java、Kotlin）和 .NET（C#）；如果文件显示已采用可识别的加固措施，则会抑制该发现。宽松的 CORS 现也覆盖全部八种语言，包括通配符 Access-Control-Allow-Origin、允许所有来源的框架配置（gin/rs-cors、Spring @CrossOrigin、ASP.NET AllowAnyOrigin()、Ktor anyHost()、rack-cors）以及反射请求来源；显式允许列表不会被标记。

层级	语言	深度
基础（模式）	C/C++、Rust、Swift、Scala，……	密钥、破坏性／架构变更、身份验证／加密、动态执行／调用 shell、原始查询、网络调用、TODO。会通过代码图升级的跨语言注入建议。
文本	YAML、Terraform、JSON、任意文本	密钥和 TODO/FIXME 标记。

快速是设计目标，覆盖范围也与之匹配。 审查会在几毫秒内完成对变更行的分析，这正是同一项检查可以放进 Agent 和编辑器的内部循环中的原因。这种速度是经过权衡的：DiffGate 是针对差异的确定性门禁，而不是穷尽整个代码仓库的污点分析引擎。覆盖范围按语言划分（有 AST 的语言采用深度分析，其他语言采用模式基础检测），安全规则针对 Agent 实际交付的残留风险进行调优，而非追求原始规则数量最大化；干净结果表示*“在此语言的层级下没有匹配项”，而非“已证明安全”*。如需对多种语言进行深入的跨文件污点分析，请配合专用 SAST 使用。各语言完整详情及代码图边界：docs/SCOPE.md。

---

配置

diffgate init 会在代码仓库根目录生成定制的 .diffgate.json。最简示例：

{
  "testCommand": "npm test",          // run for orange changes (the gate)
  "gate": { "mode": "working", "failOn": "orange" },
  "deprecated": [
    { "pattern": "StripeClient.charge", "replacedBy": "StripeClient.createPaymentIntent" }
  ]
}

任何规则——无论内置还是自定义——都可以通过路径范围限定的 include/exclude glob 进行配置；当某个禁用惯用写法在单个文件中确属合理时（例如配置加载器内部使用 process.env），可用此方式作为例外。完整的架构、内置规则表、LLM 提供方及按规则调优说明：docs/CONFIG.md。

---

更多

• PR 经过了审查，但风险代码行没有。 — 我们对 PR 审查轨迹的研究：350 个已合并的 AI 辅助 PR，109 个包含被标记为 AI 编写的更改，其中只有 3 个有作者以外的人员公开讨论。
• docs/SCOPE.md： 按语言划分的覆盖层级（深度 AST 分析、模式匹配或仅文本分析），以及代码图谱能做和不能做的事。
• docs/CONFIG.md： 完整的 .diffgate.json 架构、所有内置规则、LLM 提供方、原生精度和测试范围行为。
• docs/TEAM.md： 如何在团队中推广 DiffGate（GitHub Action / PR 门禁、共享经验、组织级策略包、SOC 2 证据、面向管理者的指标）。
• docs/CODE-GRAPH.md： 可选的跨文件影响范围分析（调用方数量、建议审阅者、测试缺口、可达性、污点分析）。
• docs/STRUCTURAL-RULES.md： structural 规则包——检测过度设计而非漏洞（不必要的抽象、透传包装器、复杂度激增）；所有规则均不会阻止合并，并支持按语言设置阈值。
• docs/MEASUREMENT.md： Agent 实际会在没有提示的情况下提交哪些内容，以及如何复现（diffgate marginal）。
• MCP.md： MCP 工具、提示词、资源和 AI 配置。

---

试用

diffgate scan mock_project

你会看到绿色发现（日志记录）、黄色发现（已弃用的调用）和橙色发现（DROP COLUMN 迁移、公共导出）。

测试

npm test    # builds the extension, runs the full unit/integration suite + extension smoke test

支持项目

如果 DiffGate 帮你发现了问题，或者你只是喜欢为 Agent 代码设置确定性门禁的想法，请**为仓库点亮星标 ⭐**。这能向其他人表明，值得一试。

• 🐛 发现了误拦截，或它漏掉了某个风险点？ 提交问题——误拦截是我们按 P0 级别处理的 Bug。
• 💡 希望覆盖某种语言或规则？ 提交功能请求，并说明你希望检测的惯用写法。
• 🔒 安全问题报告？ 请私下披露——参见 SECURITY.md。

贡献与许可证

请参阅 CONTRIBUTING.md。采用 Apache 2.0 许可证；参见 LICENSE。