Verify Change（验证改动）
执行验证测试并记录结果。这是 AI 在实现完成后自动调用的 Skill，不需要用户手动触发。
触发条件
- 功能实现完成后（链路改动、治理改动）
- 需要验证改动是否符合预期
- 需要记录验证证据
跳过条件
- 单项目改动：跑单元测试和 lint 即可，不必生成 verification.md 记录
验证层级
1. 单元测试
范围： 单个函数、类、模块
执行：
bash# Python pytest apps/xxx/tests/test_xxx.py -v # Node.js pnpm test
记录：
- 测试用例名称
- 通过/失败状态
- 失败原因（如果有）
2. 集成测试
范围： 单服务内多个模块协同
执行：
bash# 启动本地栈（Runtime + Platform API + Platform Web） bash scripts/local-stack.sh start # 执行集成测试场景 curl http://localhost:8123/api/xxx
记录：
- 测试场景描述
- 执行步骤
- 预期结果 vs 实际结果
- 截图或日志（如有必要）
3. 端到端测试
范围： 完整业务链路
执行：
bash# 启动完整栈（Runtime + Platform API + Platform Web） bash scripts/local-stack.sh start # 检查服务健康状态 bash scripts/local-stack.sh status # 在浏览器或 Postman 中测试完整流程 # Platform Web 默认: http://localhost:3000 # Platform API 默认: http://localhost:2142 # Runtime Service 默认: http://localhost:8123
记录：
- 用户操作步骤
- 关键验证点
- 响应时间
- 截图（重要界面）
4. 性能测试（按需）
范围： 性能敏感的改动
执行：
bash# 压力测试 ab -n 1000 -c 10 http://localhost:8123/api/xxx
记录：
- 性能指标（QPS、延迟、资源占用）
- 与目标值对比
- 性能瓶颈分析
两阶段验证原则
不要每改一小块就全量回归，验证分两个阶段：
| 阶段 | 触发时机 | 范围 |
|---|---|---|
| Phase 验证 | 每个 Task 完成后 | 只跑这个 Task 直接相关的最小测试集，验证改动本身不出错 |
| Final 验证 | 当前范围内所有 Task 全部完成后 | 全量单元测试 + 集成测试 + E2E 链路测试 |
工作流
Phase 验证（每个 Task 完成后执行）
- 确认 Task 的验证项：读 tasks.md 对应 Task 的「验证项」字段
- 执行最小测试集：只跑与这个 Task 直接相关的单元测试
- 记录到 Phase 验证记录：在
verification.md的## Phase 验证记录区块追加一行
Final 验证（所有 Task 完成后执行）
只要当前范围仍有可推进的未完成 Task，新增测试证据仍记在 Phase 验证记录中；不得提前写入 ## Final 验证记录 或生成“最终结论”。真实环境暂缺时，先完成隔离环境内可执行的场景，再判断剩余项是否需要用户提供条件。
-
状态一致性检查（前置，必须通过才能继续）
对照以下四处，确认状态描述一致：
README.md的"状态"字段tasks.md的进度追踪（所有 Phase 的[ ]是否都打x了）verification.md的 Phase 验证记录条数 == 已完成 Task 数CONTEXT.md的活跃项目状态行
不一致 → 先对齐，再做 Final 验证，不得跳过此步骤。
-
读取验证计划
- 标准模板：读取
docs/projects/{YYYYMMDD}-{项目名}/verification.md的「验证计划」章节 - 多专题模板：读取对应子专题文档「验证要求与记录」小节
- 标准模板：读取
-
执行全量测试，按顺序：单元 → 集成 → 端到端 → 性能/安全（按需）
-
记录到 Final 验证记录：更新
verification.md的## Final 验证记录区块 -
问题追踪：发现问题立即记录，分析原因，制定修复方案，修复后重跑受影响的测试
验证记录模板
在 docs/projects/{YYYYMMDD}-{项目名}/verification.md 中维护两个独立区块：
markdown# {项目标题} - 验证记录 ## Phase 验证记录 <!-- 每个 Task 完成后追加一条，只记最小验证结果 --> ### Task 1.1 验证 {日期} - 验证项：{对应 tasks.md 里的验证项描述} - 结果：✅ 通过 / ❌ 失败（原因：{说明}，修复：{方案}） ### Task 1.2 验证 {日期} - 验证项：{对应 tasks.md 里的验证项描述} - 结果：✅ 通过 --- ## Final 验证记录 <!-- 所有 Task 完成后执行一次，全量回归 --> ### {日期} Final 验证 **执行人：** @{用户名} **验证范围：** 全量 #### 单元测试 - ✅ `test_xxx()` - 通过 - ✅ `test_yyy()` - 通过 - ❌ `test_zzz()` - 失败 - **原因：** {失败原因} - **修复：** {修复方案} #### 集成测试 ##### 场景1：{场景名称} **步骤：** 1. {步骤1} 2. {步骤2} **预期：** {预期结果} **实际：** {实际结果} **结论：** ✅ 通过 / ❌ 失败 #### 端到端测试 ##### 链路：platform-web → platform-api → runtime-service **操作：** 1. {用户操作} **结果：** - ✅ 请求成功，耗时 1.2s - ✅ 数据正确显示 #### 性能测试（按需） **指标：** QPS **目标：** > 100 req/s **实际：** 125 req/s **结论：** ✅ 满足要求 #### 问题汇总 1. **问题：** {问题描述} - **发现于：** {哪个测试} - **原因：** {原因分析} - **修复：** {修复方案} - **状态：** 已修复 / 待修复 #### 最终结论 ✅ 全部验证通过，可以合并 ⚠️ 部分通过，有 X 个待修复问题 ❌ 验证失败，需要重新实现 {详细说明}
验证标准
单项目改动
- ✅ 单元测试通过
- ✅ 代码质量检查通过（lint、类型检查）
链路改动
- ✅ 单元测试通过
- ✅ 集成测试通过
- ✅ 端到端测试通过（至少一条完整链路）
- ✅ 相关服务联调成功
治理改动
- ✅ 单元测试通过
- ✅ 集成测试通过
- ✅ 端到端测试通过（所有关键链路）
- ✅ 性能测试通过（如适用）
- ✅ 安全测试通过（如适用）
- ✅ 回滚方案验证（如适用）
- ✅ 生产环境预演（如适用）
完成度判定（四态）
验证完成后，不要只写"通过/不通过"，用下面四个状态描述实际证据情况，避免把"代码改完了"误当成"验证完成了"：
| 状态 | 含义 |
|---|---|
done | 实现 + 必要验证证据都齐全，且和文档描述一致 |
partial | 只有局部证据（比如只跑了单元测试，没跑端到端），需要写清楚缺哪部分 |
blocked | 缺少外部条件（比如没有生产环境权限、依赖服务未就绪），需要写清楚卡在哪 |
deferred | 本阶段明确不覆盖（比如性能测试留到治理改动阶段再做），需要写清楚谁决定推迟、推迟到哪个阶段 |
按边界类型的最低证据要求
| 改动边界类型 | 最低证据 |
|---|---|
| 单服务内部（单项目改动） | 单元测试或组合测试 |
| 跨文件/跨模块 | 覆盖最短相关链路的测试 |
| 鉴权/权限/审计 | 真实调用链证据，或已锁定的契约测试 |
| 持久化/重启/重放 | 真实部署验证，或明确标注 blocked |
| 生产环境/治理改动 | 负责人评审 + 验证记录 |
反模式（不要这样做）
- 代码改完了就等于
done——没有验证证据不能算完成 - 跳过某项测试（skip）却当作通过（pass）来记录
verification.md里写着partial，但项目README.md的状态却写"已完成"——两者必须一致- 文档里描述的能力超前于实际验证证据（比如设计文档说"已支持"，但没有测试能证明）
只有"必要任务完成 + 必要验证记录存在 + 未覆盖的边界已明确标注 + 状态描述一致"，才能把整个项目标记为 done。标准模板下"状态描述一致"指 README.md/plan.md/tasks.md/verification.md 四份文档状态一致；多专题模板下指 README.md 汇总状态与各子专题文档自己的「状态」一致。
partial 和 deferred 是证据或范围状态，不自动结束用户要求的全部工作；继续完成当前范围内可推进的任务。只有整体达到 done，或剩余工作确实需要用户行动、已记录具体阻塞条件和请求而判为 blocked，才作最终汇报。
示例
示例1：链路改动验证
markdown## 2024-09-07 验证 **执行人：** @ljxpython **验证范围：** Runtime 数据建模重构 ### 单元测试 执行 `pytest apps/runtime-service/tests/ -v` - ✅ 所有 23 个测试通过 - 覆盖率：95% ### 集成测试 #### 场景1：创建 runtime 配置 **步骤：** 1. POST /api/runtime/configs 2. 传入新格式的 model_config 3. 检查响应 **结果：** ✅ 通过 - 配置创建成功 - 返回正确的 runtime_id ### 端到端测试 #### 链路：platform-web → platform-api → runtime-service **操作：** 1. 在平台页面创建新 Agent 2. 选择模型和工具 3. 启动对话 **结果：** ✅ 通过 - 页面正常 - 对话成功 - 耗时 1.8s ### 最终结论 ✅ 全部验证通过，可以合并
最佳实践
-
验证要完整
- 不要遗漏验证项
- 关键路径都要测试到
-
记录要清晰
- 写清楚怎么测的
- 结果是什么
- 有问题的话，原因是什么
-
及时修复问题
- 发现问题立即记录
- 优先修复阻塞性问题
- 记录修复后的验证结果
-
保留证据
- 重要的截图保存
- 日志保存（如有异常）
- 性能数据保存
注意事项
- 验证要真实执行，不能编造结果
- 发现问题要如实记录，不要隐瞒
- 对于治理改动，验证要特别严格
- 验证通过后才能合并代码
