Tracegate CI

Tracegate CI

适用于 TypeScript 的本地 CI，只运行变更可能影响的测试，并且必须先证明跳过其余测试是安全的。

Tracegate 会在每个测试文件运行时记录它触及的内容：它执行的函数、加载的模块和读取的文件。更改代码时，如果某个测试记录的输入没有变化，就可以复用上次通过的结果。其余测试照常运行。

只有证明安全之后，它才会跳过测试：

• 先影子运行。 每个测试仍会运行，Tracegate 会记录它本来会跳过哪些测试。
• 准入门槛。 一个执行通道只有在 14 天内运行满 20 次，且最近 14 天没有未分流的漏报后，才会开始跳过测试。
• 随机审计。 5% 可跳过的测试仍会照常运行。
• 出现漏报即暂停。 如果一个预测为可安全跳过的测试实际失败，该执行通道会在 14 天内运行所有测试，除非有人将这次漏报分流为测试偶发故障。

它无法把失败结果变成通过结果。失败测试的记录会被丢弃，且不会复用超过 72 小时的记录。

Tracegate 源自一个私有的 TypeScript 单体仓库，其中约有 3,700 个测试文件，每次合并都要通过它的检查。该仓库测得的漏报率已发布在 docs/evidence/ 中。

安装

npm install --save-dev tracegate-ci
npx tracegate init --write --mcp   # writes tracegate.config.json and wires the recorder
npx tracegate doctor --canary      # checks the setup by recording one test file
npx tracegate run                  # runs the lane; in shadow, everything still runs
npx tracegate savings              # what skipping would have saved so far

如需试用两周并分享测得的数据，请参阅 docs/trial.md。

不带 --write 的 init 只会打印它将执行的操作。它不会覆盖现有配置，并会告诉你需要手动编辑哪些 Vitest 配置。

要求： 仓库中需安装 Node 22+、git、Vitest 4.1–5.x 或 Jest 30，以及 TypeScript 5 或 6。使用 TypeScript 7 时，还需通过别名安装 Tracegate 会查找的 6 版： npm i -D tracegate-typescript@npm:typescript@6。

Claude Code 插件

/plugin marketplace add davidscotttufts/tracegate-ci
/plugin install tracegate@tracegate

该插件会添加一个 MCP 服务、两个子 Agent（red-reader、deps-oracle）、两个技能和一个钩子。在 Tracegate 仓库中，该钩子会阻止 Agent 在队列之外直接运行 vitest 或 npm test，也会阻止它们自行分流漏报或批准跳过测试。设置 TRACEGATE_HOOK=off 可关闭钩子。

插件运行和触及的内容（也见 PRIVACY.md）：

• 运行： 使用 node 运行自身文件（通过标准输入输出运行的 MCP 服务及钩子）、git、你的测试运行器、你提供给 tracegate lease 的命令，以及运行 attest 时使用的 ssh-keygen 或 gpg。
• 读取： 你的仓库及其历史记录、测试覆盖率，以及这台机器的负载和内存（macOS 上使用 ps、vm_stat、sysctl 和 pmset；Linux 上使用 /proc）。
• 写入： .git/tracegate/ 中的记录账本、操作系统临时目录中的临时文件和套接字、运行 attest 时写入 refs/notes/tracegate 下的 git notes，以及 init --write 列出的文件。
• 发送： 默认不发送任何内容：没有遥测数据，也不会进行网络调用。你自行启用的两个功能会通过你自己的登录信息使用网络：attest --status 使用 gh 发布 GitHub 提交状态；发布总线 使用 gcloud 读写你指定的 GCS 存储桶。
• 安装： 不安装任何内容。此软件包没有运行时依赖项。

判定方式

如果测试依赖的内容自上次运行后没有变化，就会复用它上次通过的结果。也就是说，以下内容均未发生变化：

• 测试执行过的函数、使用的常量或加载的模块；
• 测试读取的文件；
• 测试文件本身；
• 全局输入，例如 package.json、锁文件或 Vitest 配置；
• 对于会运行 git 命令的测试，仓库的历史记录。

未提交的编辑也会计入。测试从未运行过的函数内部的编辑则不会。

记录无法感知的是时钟、环境变量、网络和其他进程。72 小时的时限、随机审计以及至少每天一次的全量运行可弥补这些盲区。完整规则见判定方式。

命令

命令	功能
tracegate run	选择并运行测试、记录结果，并从中学习。
tracegate status	查看每条通道的模式，以及距离准入门槛的进度。
tracegate savings	查看截至目前跳过测试节省的资源。
tracegate report-card	查看漏测率及 95% 置信区间。私有仓库可使用 --redact。
tracegate triage	将漏测标记为不稳定测试或记录器错误。
tracegate lease	在机器资源充足时运行命令。
tracegate train	对分支队列执行门禁，并合并通过的分支。
tracegate daemon	夜间运行完整通道，并对排队的分支进行预测试。
tracegate bus	查看另一台机器正在执行门禁或部署的内容。
tracegate attest / verify	对提交中经过测试的内容签名并进行验证。
tracegate mcp	为 Agent 提供的 MCP 服务。

tracegate --help 会列出所有命令和标志。

配置

tracegate init --write 会创建 tracegate.config.json。一个通道对应一个测试项目：

{
  "lanes": {
    "api": { "dir": "packages/api", "src": "src", "globals": ["test/setup/"] },
    "web": { "dir": "packages/web", "src": "src" }
  }
}

在 globals 下列出测试配置目录：每项测试都会加载它，因此此处的任何更改都会运行整个通道。所有设置均见指南。

还有哪些功能

功能	用途
代理器	为机器提供一个队列。门禁、后台任务和每个 Agent 的测试运行共享 CPU 和内存，而不是相互争抢。
合并列车	将一批分支作为实际的合并提交执行门禁；对未通过的一批进行二分定位；只合并确切通过的内容。
Red Reader	Agent 会读取每次失败的运行，并可将“不稳定”失败标记为真实错误，但绝不能反向操作。
静默保护	如果更改跳过、聚焦或删除测试，就会判定失败，直到有人批准。
Conductor	优先运行最可能失败的测试，并建议哪些分支应单独执行门禁。
依赖项更改	锁文件更改后，只重新运行加载了已更改包的测试。
键控输入	翻译文件中某个字符串的编辑，只会重新运行用到该字符串的测试。
守护进程	利用空闲时段运行完整测试，以及对排队的分支进行预测试。
发布总线	让两台机器能够查看彼此的合并列车和部署。
证明	记录提交的确切树上运行了什么，并对记录签名。

为什么不用 Vitest 的 recordDependencies？此对比 在相同提交上运行两者。Tracegate 会按函数选择测试、查看运行时读取的文件，并审计自身跳过的测试。

更多内容

• 指南：完整参考。
• 路线图和更新日志。
• 背景：设计背后的研究与测量结果。
• 使用示例：涵盖 claude-code-merge-queue、编辑级保护、工作树和 bin/ci 脚本。

Apache-2.0。请参阅 LICENSE 和 NOTICE。