Test Runbook

用于生成、执行和回写可复用的测试 runbook。

启动前检查

1. 读取根级 AGENTS.md；
2. 读取相关计划、runbook、OpenAPI / schema / controller / service 文档；
3. 如存在，读取 .agents/runs/<RUN_ID>/summary；
4. 确认本轮范围是只生成、只执行，还是生成并回写。

执行前声明副作用

执行 runbook 前必须先说明：

• 可能写入的本地文件；
• 可能触达的服务、数据库或外部系统；
• 可能创建的临时数据；
• 明确不会触达的范围；
• 清理和恢复方式。

影响范围不清楚时先停止确认。

Runbook 必备结构

至少包含：

• 目标和成功标准；
• 执行副作用；
• 前置条件；
• 测试变量 / 初始化；
• 步骤和预期结果；
• 失败处理；
• 清理；
• 结果记录和回写规则。

Request / Response 回写规则

• 请求方法、路径、参数和关键响应字段可以写入提交版文档，但必须先脱敏；
• token、Cookie、完整 URL、数据库主机、连接串、行主键和原始响应不得写入提交版文档；
• 未执行的步骤写 未执行 或 blocker，不得写成通过；
• 已执行结果放在文档前部的 当前验证结果 和 本次执行结果。

本地记录边界

• 原始命令输出和敏感痕迹保留在 .agents/runs/<RUN_ID>/ 或其它受控本地位置；
• 提交版 docs/test/* 只保留必要的脱敏摘要；
• 运行记录默认不提交；
• 清理完成后记录实际清理结果。

结果回写

回写前核对：

1. 目标、范围和成功标准；
2. 每一步的真实结果；
3. 失败步骤、阻塞和残余风险；
4. 清理结果；
5. 未执行项和下一步。