企业官网建设流程全解析

Cate Agent Hooks回归CI揭秘：7大Agent CLI全覆盖的自动化测试体系设计

【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cate

Cate 是一个开源的无限缩放画布编程工作区，将编辑器、终端与浏览器面板融合在同一空间。它的Agent Hooks 回归 CI是一套无需任何 API Key 的自动化测试体系：在 Linux 上真实安装 Claude Code、Codex、Cursor、Grok、Hermes、Kiro、OpenCode 这 7 大 Agent CLI，配合本地伪造的模型服务，自动捕获上游版本变更导致的 Hook 兼容性问题。本文完整揭秘这套体系的设计思路。

一、Agent Hooks 是什么，为什么需要回归 CI

Cate 通过在 Agent CLI 中注入 Hook 文件/插件，实时捕获会话生命周期事件——会话开始、回合开始/结束、工具调用、权限审批等，并把它们归因到具体的终端面板上，展示在画布中。

问题在于：这些 CLI 由不同厂商发布，更新频繁，Hook 载荷格式可能悄悄变化。一旦变更未被发现，事件就会静默丢失——界面不报错，但 Agent 状态不再更新。

为此，Cate 设计了回归 CI：不只是在代码改动时测试，还每天定时运行，哪怕 Cate 没有提交，也能在第一天就捕获上游变更（详见 docs/agent-hook-ci.md）。

二、触发机制：5 种时机覆盖所有变更入口

CI 工作流 agent-hooks.yml 定义了五种触发时机：

每个 CLI 任务会打印安装的具体版本号并上传 JUnit 报告，报告保留 14 天。

三、7 大 Agent CLI：全覆盖，绝不静默跳过

覆盖矩阵由 scripts/agent-cli-matrix.json 声明，CI 先读取矩阵生成 7 个并行任务（fail-fast: false，一个失败不影响其他任务出结果）：

安装逻辑见 scripts/install-agent-cli.sh——刻意不锁定版本，总是装最新版，这样才能检测到上游漂移。

设计上有一条铁律：🔒选中的 Agent 绝不静默跳过。二进制缺失、启动失败、认证失败、超时、事件归因错误、Hook 缺失，任何一项都会让任务失败。

四、零 API Key 的秘诀：本地伪造模型服务

整套 CI不需要 API Key、不产生付费调用。模型服务全部是本地 fixture（详见 agent-hook-ci.md 的 Provider fixtures）：

关键在于：该是真的都真——真实安装的 CLI、真实 PTY、真实 Hook 文件/插件、真实环境注入、带认证的 HTTP 接收端、变更存储、事件归一化、渲染端状态处理全部真实运行；只有 Electron 上报和系统通知被桩掉。

还有两个精细的设计：

• 子进程环境会剔除继承的凭证，配置完全一次性，Cursor 使用内存凭证存储，绝不触碰 macOS Keychain；
• Codex 不加任何绕过标志启动（不用-c、--profile、--no-daemon或 Hook 信任绕过），因为这些标志可能独立禁用 daemon，反而掩盖CODEX_EXEC_SERVER_URL绕过方案本身的回归。

这套 fixture 还被做过实战验证：开发者用一个只移除CODEX_EXEC_SERVER_URL的包装器跑测试——模型响应都成功了，但两个会话的 Hook 全部携带第一个终端的 ID，测试准确失败；另一组变异测试在归一化阶段丢弃 Codex 的PostToolUse事件，生命周期测试也如期失败。修复代码后测试恢复通过。✅

五、双终端会话隔离：防共享 daemon 串话

冒烟测试 agentHookSmoke.itest.ts 的核心设计：在同一工作区启动两个全新会话、使用不同终端 ID，且第一个终端保持打开，第二个才连接——这样共享 daemon 无法被测试清理逻辑重置，必须暴露真实的跨连接行为。

每个终端必须独立满足 4 项断言：

1. 收到 session-start、turn-start 和后续 turn-end；
2. 会话 ID 非空，回合内一致、终端间互不相同；
3. Hook 正确归因到发起会话的那个终端；
4. 屏幕上出现 provider 随机生成的响应标记（且该标记不在提示词中）。

六、生命周期场景矩阵：每个 CLI 都被"整"一遍

生命周期测试 agentHookLifecycle.itest.ts 让每个 CLI 走完整条路：运行原生写文件工具完成回合 → 响应中途被中断 → 完成恢复回合 → 用 Cate 生产环境的 resume 参数恢复已保存会话。编辑内容必须进入 Cate 的变更存储。各 CLI 的附加场景（见 agent-hook-ci.md 覆盖表）：

场景定义集中在 agentHookLifecycle.config.ts，它把每种原生 Hook 事件名映射到统一的归一化类型，并强制两条规则：

• Cate 新增一个注入 Hook 却没配真实 CLI 场景 → CI 失败；
• 某个场景不再观察到该原生事件 → CI 失败。

对厂商的已知限制，体系选择断言而非隐藏：比如 Kiro V3 没有原生中断 Hook，测试就用 Cate 的 PTY 输入恢复路径来验证；Cursor 和 Grok 不支持原生提示词上下文注入，测试也不会替它们虚构事件。

七、回归门禁：任何失败都不许合并

工作流末尾的Agent hook regression gate任务（agent-hooks.yml 门禁定义）汇总所有 CLI 任务结果——任何一个任务失败、被取消或被跳过，门禁即失败。在仓库分支规则中要求该检查，就能让失败真正阻塞合并。

八、本地一键运行

本地复现同样零门槛：正常安装各 CLI 即可，一次性机器上可执行bash scripts/install-agent-cli.sh <agent-id>（install-agent-cli.sh）。

# 默认：伪造 provider，无需任何 Key npm run test:agent-hooks:ci # 只测一个或多个已安装的 CLI（未知/空 ID 会报错） CATE_HOOK_SMOKE_AGENTS=codex npm run test:agent-hooks:ci CATE_HOOK_SMOKE_AGENTS=cursor,kiro npm run test:agent-hooks:ci

可选地，仓库提供真实 provider 的冒烟模式（vitest.live.config.ts），每个 CLI 只发两次小额付费请求；而常规 CI 工作流完全不读取任何密钥。变更捕获的完整覆盖矩阵另见 e2e/AGENT_CHANGES.md。

九、核心文件导航

• 官方文档：docs/agent-hook-ci.md
• CI 工作流：.github/workflows/agent-hooks.yml
• CLI 矩阵声明：scripts/agent-cli-matrix.json
• CLI 安装脚本：scripts/install-agent-cli.sh
• 双终端冒烟测试：src/runtime/capabilities/agentHookSmoke.itest.ts
• 生命周期测试：src/runtime/capabilities/agentHookLifecycle.itest.ts
• 场景矩阵与事件映射：src/runtime/capabilities/agentHookLifecycle.config.ts
• CLI 夹具与凭证清洗：src/runtime/capabilities/agentHookCliFixture.ts

总结

Cate 的 Agent Hooks 回归 CI 把"多厂商 CLI 兼容性"这个测试难题拆解成了四个精巧的支点：定时+全触发覆盖保证不遗漏上游变更，本地伪造 provider实现零密钥零成本，双终端隔离+场景矩阵保证每个事件链路都被真实验证，回归门禁保证任何静默跳过都不许溜进主干。这套体系对任何需要集成多个第三方 CLI 的项目，都极具参考价值。🚀

【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cate