AgentTape

将一次失败的 Codex 运行转化为可移植的回归测试。

AgentTape 是一个开源、本地优先的 Codex 插件，它将受支持的工具失败记录为经过脱敏、版本化的 .tape 证据。检查失败原因，在受控边界处分叉捕获的运行，并将结果保存为离线回归测试，可在 CI 中运行而无需再次调用模型。

大多数追踪工具帮助你观察失败。AgentTape 的构建目标是将该失败转化为一个小巧、可审查的产物，防止同一缺陷再次出现。

Codex tool failure
        ↓
redacted .tape evidence
        ↓
inspect → inject one condition → compare branches
        ↓
save assertions → run offline in CI

为什么选择 AgentTape

• 失败产物，而非另一个仪表盘。 .tape 是可移植的证据，你可以检查、审查、分享，并随缺陷修复一起提交。

• Codex 原生捕获。 捆绑的钩子在用户审查并信任后记录受支持的生命周期、权限和工具事件——无需应用程序插桩。

• 本地且注重隐私。 运行时捕获保留在活动项目内，常见含密钥字段在导出前会被递归脱敏。

• 受控故障注入。 使用权限拒绝、超时、格式错误的 JSON 或截断的响应结果来分叉记录的证据。

• 离线回归测试。 结构化回放和断言使用捕获的证据，零模型调用、零实时工具调用。

• 诚实的回放置信度。 AgentTape 报告覆盖率和局限性，而不是声称每个外部系统都能逐位复现。

Related MCP server: MCP QA Lab

从 GitHub 安装

前置条件：Codex 和 Node.js 20 或更高版本。

codex plugin marketplace add jiangkoumo/agenttape
codex plugin add agenttape@agenttape

安装后启动一个新的 Codex 任务，并在信任捆绑的钩子之前先审查它们。捕获随后存储在活动项目的 .agent-tape/ 目录下。

两分钟工作流

首先，正常使用 Codex，直到某个受支持的本地工具调用失败。然后询问：

Use tool search to find AgentTape. List captured runs, inspect the latest
failed run, and explain the first recorded failure and replay confidence.

AgentTape 暴露了四个 MCP 工具：

在本地或 CI 中运行已保存的回归测试：

node plugins/agenttape/scripts/agenttape.mjs test \
  tests/agenttape/fixture_permission_denied-timeout.tape

通过的断言以代码 0 退出。验证或断言失败则以非零退出，且捕获的比较值会从失败输出中省略。

.tape 捕获了什么

Tape v1 保留了结构化调试所需的证据：

• 运行身份、时间戳、源覆盖率和明确的局限性。

• 有序的生命周期、权限和受支持的本地工具事件。

• 工具输入、输出、明确失败和首个失败边界。

• 记录值被移除位置的脱敏清单。

• 可选的分叉元数据、注入条件和结构化断言。

• 回放置信度输入，使消费者能够区分强证据与仅回放痕迹。

tape 模式独立于 UI 和记录器实现。参见 Tape Schema v1。

回归断言

AgentTape 目前支持以下确定性检查：

• 字段等于预期值。

• 工具存在或不存在。

• 重试次数保持在最大值以下。

• 最终运行状态与预期状态匹配。

• 回放置信度达到最低阈值。

已审查的回归产物写入 tests/agenttape/ 下，默认不会被覆盖。

回放边界

AgentTape 目前提供结构化回放，而非完整的代理重新执行。它重用捕获的状态，替换一个记录的工具结果，并在注入的边界处停止。它不会重新生成下游模型推理。

托管工具、未捕获的外部状态以及第三方系统的变更可能缺失。脱敏标记证明 AgentTape 的脱敏器已运行；它无法证明任意自由格式文本不包含机密。分享每个 .tape 之前请先审查。

完整的信任边界参见 Privacy 和 Security。

仓库结构

plugins/agenttape/
  .codex-plugin/plugin.json   # Codex plugin manifest
  hooks/hooks.json            # Recorder lifecycle hooks
  skills/capture-failure/     # Guided capture workflow
  dist/mcp-server.mjs         # Self-contained bundled MCP server
  scripts/                    # Recorder, schema, and assertion CLI
  schemas/                    # Versioned .tape schema

仓库还包含 src/ 下的可选 Branch Canvas 原型和 remote/ 下的实验性无状态 HTTP MCP。它们使用相同的 tape 和回放概念，但不是安装或使用 Codex 插件所必需的。

本地开发

git clone https://github.com/jiangkoumo/agenttape.git
cd agenttape
npm ci
npm run test:plugin-release
npm run build:plugin
codex plugin marketplace add .
codex plugin add agenttape@agenttape

已提交的 plugins/agenttape/dist/mcp-server.mjs 允许市场安装无需构建仓库即可运行。每当 MCP 源代码变更时，请重新构建并提交它。

在更改可选 Branch Canvas、Sites 适配器或远程 HTTP MCP 接口时，请运行 npm test 和 npm run build。

卸载

codex plugin remove agenttape@agenttape
codex plugin marketplace remove agenttape

贡献

欢迎提交 Issue 和拉取请求。参见 Contributing、Code of Conduct 和 Changelog。

许可证

MIT。参见 LICENSE。