regressguard

RegressGuard

提交之前，先了解哪些地方出了问题。

AI 编码 Agent 修改应用时，可能会悄无声息地破坏 API 契约——移除字段、更改状态码、导致测试失败——却仍然报告成功。RegressGuard 会记录一个已知正常的基线，并准确告知你（或 Agent）发生了哪些回归。

它专为融入 Agent 自己的工作循环而构建。 RegressGuard 以 MCP 服务的形式提供，因此 Claude Code 和 Cursor 等 Agent 可以在任何人看到差异之前验证自己的工作并自行修正 ，全程无需额外步骤。 同一引擎也可以作为普通 CLI，供用户和 CI 使用。

# Agent-native (primary): the agent calls these as MCP tools in its loop
check → status                  # see "Agent-native verification (MCP)" below
                                 # the baseline stays yours: agents cannot re-record it

# Human / CI (also works): two commands, no test-writing, under 15 seconds
regressguard snapshot   # record the known-good state
regressguard check      # compare after edits — see what broke

破坏 → 检测 → 修复 → 通过。亲自复现：./demo/demo.sh。

---

安装

macOS / Linux（推荐）

curl -fsSL https://raw.githubusercontent.com/Bharath-code/regressguard/main/install.sh | sh

验证

regressguard version   # first line must say "RegressGuard"

从 v0.1.x 升级？ 二进制文件已从 rg 重命名为 regressguard，因为 rg 与 ripgrep 冲突。没有 rg 兼容层，旧版 rg upgrade 也无法获取 v0.2.0： 请重新运行安装程序，删除旧的 rg，然后运行 regressguard hook install （旧钩子会调用 rg；regressguard doctor 会指出这些钩子）。

---

快速入门（3 分钟）

1. 初始化项目

cd your-project
regressguard init

RegressGuard 会自动检测测试命令、框架和开发服务器 URL。

2. 在 AI 会话开始前记录基线

确保开发服务器正在运行，然后：

regressguard snapshot

输出：

Snapshot

OK Tests       42 passed, 0 failed       6.8s
OK Routes      6 captured, 2 skipped
OK Schemas     6 hashed

Saved:
  .regressguard/snapshot.json

Next:
  Ask your AI agent to make the code change, then run:
  regressguard check

3. 运行 AI Agent

让 Claude Code、Cursor 或 Codex 进行修改。

4. 提交前检查是否存在回归

regressguard check

未发现问题——可以安全提交：

Check

OK No regressions detected

  Tests       42 passed, 0 failed
  Routes      6 unchanged
  Timing      within tolerance

Safe to commit.

发现回归——阻止提交：

Check

X 2 regressions detected

  Route                                 Before    After     Change
  GET /api/users                        schema    schema    schema
    - role (string, removed)
    + age (number, added)
  POST /api/user/update                 200       500       status

Likely cause:
  Auth/session behavior or routing changed during the last code edit.

Changed files since snapshot:
  app/api/users/route.ts
  internal/auth/session.go

Next:
  regressguard check --verbose
  git diff

Commit blocked.

严重问题会返回退出代码 1——可与 git 钩子和 CI 配合使用。

---

Git 钩子（自动保护每次提交）

regressguard hook install

现在，每次执行 git commit 前都会自动运行 regressguard check。检测到严重回归时，提交会被阻止，并显示简洁的输出：

RegressGuard pre-commit

X 1 regression detected
  POST /api/user/update status changed from 200 to 500

Run:
  regressguard check --verbose

Commit blocked. Use --no-verify only if you accept the risk.

仅在接受风险时，才使用 git commit --no-verify 绕过检查。

---

原生 Agent 验证（MCP）

这是 RegressGuard 的主要使用模式。AI Agent 不必等用户运行 regressguard check，而是在自己的编辑循环中将其作为工具调用——这样就能在把修改交给你之前，发现并修复自己刚引入的回归。

启动服务（stdio 传输）：

regressguard mcp serve

注册到 Claude Code：

claude mcp add regressguard -- regressguard mcp serve

注册到 Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "regressguard": { "command": "regressguard", "args": ["mcp", "serve"] }
  }
}

随后，Agent 将获得两个工具：

工具	用途
check	将当前状态与快照对比；返回包含严重级别的结构化发现
status	亚秒级健康检查（快照年龄、路由/配置/钩子状态）——不运行测试

基线由用户掌控。 默认情况下，Agent 不会获得 snapshot 工具。如果它们 可以重新记录基线，就可能接受自己的回归 （check 失败 → snapshot → check 通过）。你需要使用 regressguard snapshot 记录基线。若仍要允许 Agent 重新设定基线，请在 .regressguard/config.json 中设置以下内容并重启 MCP 服务：

{ "mcp": { "allowSnapshot": true } }

工具响应与 regressguard check --json 返回的机器可读数据完全相同——参见 docs/json-contract.md。每次工具调用都会记录到 .regressguard/ 下的只追加审计日志中（工具、状态、耗时、时间戳）。

典型工作循环：Agent 编辑代码 → 调用 check → 查看结构化发现 → 修复回归 → 再次调用 check → 然后才报告完成。

---

命令

命令	用途
regressguard init	为此项目配置 RegressGuard
regressguard quickstart	一条命令自动完成配置并创建快照
regressguard snapshot	记录当前通过的状态
regressguard check	将当前状态与快照进行比较
regressguard status	亚秒级健康检查（快照时长、路由、钩子）——不运行测试
regressguard explain <route>	显示特定路由的前后差异
regressguard watch	监视文件，并在文件变更时自动运行检查
regressguard mcp serve	运行 MCP 服务，让 AI Agent 能够自行验证（见上文）
regressguard hook install	安装 pre-commit git 钩子
regressguard hook uninstall	移除 git 钩子
regressguard config get <key>	读取配置值
regressguard config set <key> <value>	写入配置值
regressguard doctor	诊断设置问题
regressguard upgrade	将 regressguard 更新到最新版本
regressguard completion <shell>	生成 Shell 自动补全（bash、zsh、fish）
regressguard version	打印版本和构建元数据

运行 regressguard <command> --help 查看标志、示例和退出码。

---

配置

配置位于 .regressguard/config.json（便于阅读，可添加到 Git 忽略列表）。

{
  "version": 1,
  "testCommand": "npm test",
  "serverUrl": "http://localhost:3000",
  "auth": {
    "mode": "bearer",
    "testToken": "your-test-token",
    "headerName": "Authorization",
    "prefix": "Bearer"
  },
  "ignoreFields": ["requestId", "traceId"],
  "routes": [
    { "method": "GET", "path": "/api/health" },
    { "method": "GET", "path": "/api/users" },
    { "method": "GET", "path": "/api/admin", "skip": true }
  ]
}

认证模式： bearer（Authorization 标头）、cookie（Cookie 标头），或者省略此项以仅检查公开路由。

ignoreFields： 从架构比较中排除的字段——适用于 requestId 或 traceId 等易变的应用专用值。

---

工作原理

1. regressguard snapshot 会运行你的测试套件并访问每个已配置的路由。它会记录通过/失败计数、HTTP 状态码，以及每个响应的规范化架构哈希值。

2. regressguard check 会重新运行相同的测试和路由，然后与快照进行差异比较：

   • CRITICAL：测试套件出现新的失败、状态码发生变化、响应架构发生变化（例如字段被移除/添加/更改）
   • WARNING：响应时间增加超过 200ms，且超过基准值的 50%
   • PASS：所有内容均在可接受的偏差范围内

3. 架构比较会自动规范化 JSON 负载：

   • 默认动态键：在计算哈希前移除 16 个常见动态键（id、uuid、token、nonce、timestamp、createdAt、updatedAt、deletedAt、created_at、updated_at、deleted_at、sessionId、accessToken、refreshToken、expiresAt、expires_at）。
   • 模式检测：自动检测 ISO-8601 日期字符串、UUID 和 JWT，并将其替换为通用类型表示（"date"、"uuid"、"token"）。
   • 用户自定义：遵循配置中定义的自定义 ignoreFields。

   这样可以确保端点的结构在不同运行之间保持稳定，即使数据库 ID 和时间戳发生变化也不受影响。

4. 如果某个路由的唯一变化是非阻塞的 WARNING（例如计时回退），则会单独显示在一行中，且不会计入“Routes: N unchanged”汇总，也不会计入 --json 输出中的 summary.passed。

已知限制

这些是 v1 中有意做出的取舍——优先避免误报，而非穷尽所有情况。它们已列入路线图，并非意外遗漏：

• 测试身份比较采用尽力而为的方式。 regressguard check 会记录失败测试的名称（jest、vitest、bun、go test 的输出），并在基线中通过的测试开始失败时标记为 CRITICAL——即使失败总数没有变化。如果无法从运行器的输出中解析名称（或基线是在记录名称功能推出前生成的），则会退回到数量比较：只有失败测试的数量增加时才标记为 CRITICAL。请在 CI 中将 regressguard check 与常规测试运行器配合使用，以全面断言每个测试的结果。
• 数组架构根据第一个元素推断。 架构规范化器使用 JSON 数组的第一个元素来表示其结构。如果后续元素的结构不同（异构数组），这种差异不会反映在架构哈希中，也不会被标记。

---

退出代码

代码	含义
0	通过或仅有警告——可以安全提交
1	检测到严重回归——阻止提交
2	用法、配置或运行时错误

---

脚本和 CI

# JSON output for scripts and agents
regressguard check --json | jq .status

# Verbose diagnostics on stderr (stdout stays clean JSON)
regressguard check --json --verbose

# Disable color for CI
NO_COLOR=1 regressguard check

GitHub Action — 在每个 PR 上运行 regressguard check，并评论检测结果：

- uses: Bharath-code/regressguard@v0
  with:
    server-command: npm run dev

对于拉取请求，该操作会与基础分支上提交的快照进行比较（regressguard check --base origin/main），因此，即使 PR 修改 .regressguard/snapshot.json 来掩盖回归，也仍会失败。使用 CODEOWNERS 规则，在基线发生变化时要求人工审批：

/.regressguard/snapshot.json  @your-handle

提交 .regressguard/snapshot.json（regressguard init 会将 .regressguard/* + !.regressguard/snapshot.json 添加到 .gitignore）；.regressguard/ 中的其他所有内容都保留在本地。

有关所有输入（版本固定、工作目录、服务 URL），请参阅 action.yml。

---

支持的技术栈（v1）

• 框架：Next.js App Router、Express、Hono
• 测试运行器：Vitest、Jest、Bun test、npm test
• 包管理器：npm、pnpm、yarn、bun
• 身份验证：Bearer token、Cookie header、公共路由

Python、FastAPI 和 Django 支持计划在 v2 中推出。

---

演示夹具

fixtures/nextjs-app 中包含一个最简 Next.js API 夹具，用于演示和测试。请参阅 fixtures/README.md。

---

开放核心

此仓库——CLI 和 MCP 服务——永久免费且采用 MIT 许可。托管团队层 （跨仓库仪表板、历史记录保留、合规性导出）已列入 docs/paid-layer-spec.md 的规划。凡是在一台机器上为 一个仓库运行的功能都保持免费；付费层仅提供增值功能。

---

更新日志

有关发布历史，请参阅 CHANGELOG.md。

---

许可证

MIT — 请参阅 LICENSE。

---

来自同一位开发者的项目：git-scope。