Skip to content

README.md

Latest commit

 

History

History
184 lines (134 loc) · 11.6 KB

README.md

File metadata and controls

184 lines (134 loc) · 11.6 KB

简体中文 | English

DiffGate banner

MIT License Python 3.12+ WIP Agent ready MCP compatible

DiffGate 是给 Agent 编辑回路装的结构化校验门 —— 改没改、改对没改，AST 说了算。

目录

为什么需要 DiffGate

Cursor、Claude Code、Codex、GPT-5.5 这些 Agent 编辑代码时，经常返回 success，但 diff 是空的、改在了错误的文件，或者只是在注释里"承诺"了改动。Tessl 的 1281 次实测显示，这是大型代码库上最常见的失败类之一 —— 但没有任何 Agent 框架在 edit 步骤之后做结构化校验。

DiffGate 在 Agent 工具调用和下一轮 loop 之间插一道关：解析改前改后的 AST，对比 Agent 自己声明的 claimed_actions，不一致就返回 exit_code=1，让 Agent 自己重试。把一类"安静地撒谎"，变成"吵闹地报错"。

架构

Coding Agent 发出 EditClaim（改前/改后 blob + 声明动作），DiffGate 用 tree-sitter 解析双侧并把声明对齐到 AST diff，Verdict 要么放行（exit 0），要么返回 exit_code 1 作为结构化背压让 Agent 重试

Coding Agent（Cursor / Claude Code / Codex / LangGraph）在每次编辑后发出一个 EditClaim —— 改前 blob、改后 blob、声明的动作。cli.py 与 mcp_server.py 是同一个 verifier.verify(EditClaim) → Verdict 的两层薄壳：核心用 tree-sitter 解析双侧 AST（Python / TypeScript / Go / Rust），把每条声明对齐到真实的结构化 diff。Verdict 要么放行让 loop 继续（exit 0），要么返回 exit_code=1 作为结构化背压，带着 mismatch 原因把 Agent 打回重试 —— 全程本地、离线、确定性，无守护进程、无数据库、无网络调用。

快速开始

pipx install diffgate                                          # ≤30s
diffgate verify --before X.py --after X.py.new --claim "rename foo→bar"
diffgate mcp-server --stdio                                    # 注册到 Claude Code / Cursor 的 mcp.json

接下来把下面 3 行加进 ~/.config/claude-code/mcp.json（或 Cursor 的同等配置）：

{
  "mcpServers": {
    "diffgate": { "command": "diffgate", "args": ["mcp-server", "--stdio"] }
  }
}

完整的 hook 教程见 examples/claude_code_hook.md；Cursor 集成见 examples/cursor_integration.md。

演示

diffgate verify 终端演示：Claude Code 声称改名但实际是空 diff，DiffGate 返回 exit_code 1

↑ 终端实录（由 CI 用 vhs 渲染 docs/demo.tape，打 tag 时自动生成）。

60 秒画面：Claude Code 声称把 module_x.py 里的 foo 全部改名为 bar → DiffGate 解析双侧 AST → 发现实际有 0 处 rename → exit_code=1 → Agent 自动重试。

它是怎么工作的

三个本地进程，全部不联网：

[ coding agent ]  ──tool_call──►  [ diffgate MCP server (python) ]
                                          │
                                          ▼
                                  [ verifier core ]
                                   ├── tree-sitter 解析器 (py/ts/go/rs)
                                   └── claim → ast_change 匹配器

核心数据原语是 EditClaim：

EditClaim {
  before_blob: str
  after_blob: str
  claimed_actions: [
    {kind: "rename"|"add"|"delete"|"move"|"signature_change",
     symbol: str, scope: str}
  ]
}
→ Verdict { passed: bool, mismatches: [...], structural_diff: ast_summary }

cli.py 和 mcp_server.py 是同一个 verifier.verify(edit_claim) → Verdict 的两层薄壳。没有守护进程、数据库、网络调用。

作用域（scope）感知 — v0.2.0

claimed_actions 里的 scope 字段现在会被严格校验。声明 add MyClass.helper 只有当 helper 真的落在 MyClass 里时才放行 —— Agent 改成了一个模块级的 helper() 不再算数。这堵死了一类常见的"安静撒谎"：把类方法和同名的模块级 函数互相混淆。

# Agent 声称给类 A 加了方法 helper，实际只加了一个模块级函数 → exit_code 1
diffgate verify --before a.py --after a.py.new --claim "add helper in A"

scope 留空时是通配符，按符号名匹配（与 v0.1 行为完全一致），所以旧的无作用域 声明不受影响。

对比同类项目

诚实对比，不画饼：

维度 DiffGate Aider test-loop langgenius/dify ChromeDevTools/chrome-devtools-mcp
拦截"空 diff / 改错文件"的假成功 ✓ — — —
行为正确性（跑测试） — ✓ partial —
Agent 工作流编排 — partial ✓ (远超 DiffGate) —
浏览器 / DevTools 侧观察 — — — ✓ (远超 DiffGate)
跨 Agent / 跨 IDE ✓ (MCP 协议) Aider-only Dify-only Chrome-only
部署 单进程 / 本地 单进程 多服务 / 容器 Chrome 扩展

DiffGate 只解决一类问题（结构化撒谎），不取代上面任何一个。Aider 仍然是更好的 pair-programmer；Dify 仍然是更好的 Agent 编排；chrome-devtools-mcp 在浏览器侧依然无可替代。

配置说明

键 类型 默认 含义
languages list [py, ts, go, rs] 启用的 tree-sitter 解析器
strict_renames bool true rename claim 必须改到所有引用；false 时只校验声明位置
mcp.transport enum stdio stdio 或 sse
bench.traces path 内置 200 条 diffgate bench 使用的 ground-truth JSONL

完整配置见 diffgate --help。

路线图

  • m1 — diffgate verify：CLI + Python/TS 解析 + 20 条 silent-lie fixture 全部命中
  • m2 — diffgate mcp-server：MCP 工具 verify_edit，配合 Claude Code / Cursor 即开即用
  • m3 — diffgate bench：回放 trace，输出 precision/recall
  • v0.2 — 作用域感知校验：scope 字段严格匹配，拦截"类方法 vs 同名模块函数"混淆
  • v0.3 — CLI/MCP 对齐 + 多语言：结构化 --claim-file（含 stdin）、多文件校验、新增 Java / C++ / Ruby 解析器，外加三处 silent-lie 修复
  • DiffGate Cloud（付费）：跨团队聚合 catch-rate、SSO、Prometheus exporter
  • 框架集成：LangGraph / Mastra / Autogen 官方可选 gate

付费 / Pricing

自托管永远免费。 CLI、MCP server、tree-sitter 解析器、bench 工具全部 MIT 协议，没有任何 phone-home。

付费产品（v0.2）—— DiffGate Cloud：面向字节、阿里、腾讯、美团、京东这类内部 Dev Platform 团队的托管聚合面板。把每个工程师、每个团队的 Agent catch-rate 汇总到一个仪表盘，带 SSO、审计日志、Prometheus exporter，并优先支持 Java / C++ 解析器。定价大约¥1,200 / 工程师 / 年（按容量分层），约为一个 Cursor Business 席位的 1/3 —— 定位为"你已经付了席位钱的那个 Agent，再加一道安全网"。

试点流程：14 天免费 → 第 14 天给一份团队聚合的 catch-rate + 估算的"节省工程师小时"读数 → 年合同（最低 ¥100k 起，按席位扩容）。Stripe（USD）+ 阿里云国际 / 微信支付商户号（CNY）双通道结算。

如果你在字节 / 阿里 / 腾讯 / 美团 / 京东的内部 Dev Platform，欢迎邮件 leo.stack@outlook.com 聊试点。

License & 贡献

MIT，详见 LICENSE。Bug、误判、漏判一律欢迎开 issue —— 把 EditClaim 的 before/after 贴上来即可，复现非常便宜。PR 之前先开 issue 对齐一下范围。

Share this

DiffGate — 给 Coding Agent 编辑回路的结构化校验门。
你已经付了 Cursor / Claude Code 的席位钱，再加一道 Agentic 安全网，
让"声称改完了"的假成功变成 exit-code 1。OSS + MCP。
https://github.com/SuperMarioYL/diffgate

MIT © 2026 SuperMarioYL