agent-diff-guard

June 21, 2026 · View on GitHub

设计判断在 DESIGN.md。这里是怎么走:从今天的单兵 CLI,到团队 PR 守门,到企业治理层,每一阶段的形态、要解决的技术命题、以及"做到什么程度才算这一阶段成立"。

原则:每一阶段都必须独立有用。 不为了下一阶段而过度设计当前阶段——守门人自己最反对"顺手多做"。

现状:v0.0.1 — 单兵 dogfood ✅

规则引擎 + diff 解析 + task-drift 偏离检测 + pre-push hook 已端到端跑通。strict 类型检查通过,误报防线测试与命中测试并存。

它已经能做的: 一个人在自己仓库,git push 前自动刹车。

阶段 1:把 CLI 打磨到"可信任的单兵工具"

目标:让任何个人开发者装上就敢一直开着。这一阶段的成败完全由误报率决定。

1.1 误报清零(最高优先级)

  • 收集真实 agent diff 语料(自己的 + 早期用户的),建立误报回归基准:每加一条规则,跑一遍历史正常改动,必须零新增误报。
  • secret 检测降假阳:当前是 regex 粗筛,需引入熵值判断 + 已知占位符词典 + 上下文(example/test/fixture 目录豁免)。
  • test-deleted 规则细化:区分"删测试作弊"vs"正当重构/移动测试文件"(改名、合并、迁移目录不该报)。

1.2 范围计算修正(dogfood 已暴露)

  • 修 README 已记的雷:同一 commit 内多类雷在增量 push 时可能漏报(@{u}..HEAD vs 全量)。这是漏报,违背"关键时刻刹车"。

1.3 规则可配置化

  • .agent-diff-guard.toml / .json:每个仓库自定义敏感路径、豁免目录、规则开关、严重级别覆写。
  • 但默认配置必须开箱即用且极保守——配置是给"想收紧"的人,不是"必须配才能用"。

1.4 task 输入升级

  • task-drift 当前是词面关联,假阳/假阴都高。升级方向:接受结构化任务输入(从 commit message、PR 标题、或 agent 的 task 记录),用语义相似度替代词面 includes。可选本地小模型 / 可选调云端(用户自带 key)。
  • 与 Claude Code / Cursor 的 task 上下文打通:理想形态是 agent 干活时就把"我这次的任务是 X"喂给守门人,无需用户手填。

阶段 1 成立的标志: 早期用户装上后一周内没有一个人因为误报关掉它,且至少拦下过一次真实的 agent 越界。

阶段 2:从"一个人的刹车"到"团队的共识刹车"

目标:进入团队的 merge 流程,成为留存抓手。形态从本地 hook 扩展到 GitHub App + PR 评论。

2.1 GitHub App / PR 评论形态

  • GitHub App:PR 打开/更新时,对 base...head 跑守门人,把 wake-you-up 发现以单条、克制的 PR 评论呈现(同样遵守"最多 1–3 处")。
  • check run 状态:neutral(让人看一眼)而非 failure(机器拍死)——守门人的语义是人在回路,不是硬 gate。这点是和所有"CI 拦死"工具的刻意区别。
  • 放行留痕:谁 resolve 了哪条守门发现,记下来(团队独有价值的起点)。

2.2 团队规则中心化

  • 组织级规则配置:把"我们团队认为哪些 agent 改动该确认"集中定义,所有仓库继承。
  • 跨成员一致:个人 hook 可 --no-verify 绕过,团队 gate 的绕过需留痕/需理由。

2.3 多渠道分发

  • GitHub Marketplace 上架(团队版天然入口)。
  • npm 包 + homebrew(CLI 个人版的标准分发)。
  • 评估 VS Code / Cursor 扩展:在 agent 改完、用户 review 时,就地标出守门发现。

阶段 2 成立的标志: 有团队把它纳入 merge checklist;出现第一批付费订阅;留存(月留)健康。

阶段 3:企业治理层 —— agent 改动的可审计性

目标:当一个组织有几百工程师 × 每人 N 个 agent,"谁的 agent 改了什么、谁批准的"成为合规问题。我们做这个问题的记录者与治理者。

3.1 治理与合规

  • 审计日志:每一条 agent 越界改动、每一次人工放行,完整可追溯、可导出。
  • SSO / SAML、RBAC、策略强制(policy enforcement,不止提示)。
  • SOC2 路径(企业采购前置)。

3.2 私有部署

  • 自托管 / VPC 部署,代码与日志不出企业边界(这是把段 1 "代码不离开机器"的信任优势延伸到企业)。

3.3 跨 agent 中立性作为卖点

  • 明确支持守护任意 agent(Claude Code、Cursor、Copilot、自研 harness)的改动——中立第三方守门人,正是 harness 厂商结构上做不了的位置(见 DESIGN §3)。

阶段 3 成立的标志: 企业为"agent 改动可审计"付年费;它出现在采购清单的"AI 治理"条目下。

Loop 生态集成方向（2026-06 研究）

详见 LOOP-ECOSYSTEM-RESEARCH.md · 具体任务见 todo.md 🔵 Loop Ecosystem（LE-01 ~ LE-18）

基于深度研究（21 来源 / 105 claims / 对抗验证），确认 agent-diff-guard 占据经验证的结构性空位——Loop 时代的验证层。Gas Town（15.9k stars）需要 Witness、Ralph 需要 between-iteration gate、Datadog 需要 guard verdict 数据、loop-audit 需要 guard-readiness 维度。

三个阶段 18 个方向：近期（OTEL export / hash chaining / Loop Monitor）→ 中期（语义漂移 / Gas Town adapter / Ralph gate）→ 长期（Loop Contract 标准 / EU AI Act compliance / 跨 agent 中立性）。

始终不做的事(反路线图)

守门人的克制也体现在拒绝做什么上:

  • ❌ 不做通用 AI code review。 一旦开始追求"审得全",就掉进 CodeRabbit 们的红海,也违背"宁可漏不可烦"。
  • ❌ 不做 dashboard。 "展示所有 agent 状态"是注意力黑洞,正是我们要解决的问题的反面。
  • ❌ 不默认上传代码。 信任是地基,云端处理永远是用户显式 opt-in。
  • ❌ 不为了多报而放宽规则。 每一条规则的纳入标准只会越来越严,不会越来越松。

演进的内在逻辑

单兵 CLI ──信任──> 团队 PR 守门 ──留存──> 企业治理层
   │                    │                      │
 误报清零            进 merge 流程          可审计/合规
 (能力地基)          (协作粘性)            (高 ARPU)
   │                    │                      │
   └──────── 同一份判断力,越校准越深 ─────────┘

每一阶段卖的是同一件事的不同切面:帮"一个人 × N agent"的世界,把注意力精准地花在真该看的那 1–3 处改动上。 个人省注意力,团队防事故,企业要合规——痛感随规模放大,这是产品天然的扩张曲线。