@chenmk/superflow 0.5.21 → 0.5.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/INSTALL.en.md +2 -0
  2. package/INSTALL.md +2 -0
  3. package/assets/scripts/superflow-delivery-check.sh +36 -6
  4. package/assets/scripts/superflow-review-coverage.mjs +34 -0
  5. package/assets/scripts/superflow-test-report-lint.py +125 -4
  6. package/assets/skill-registry.json +23 -8
  7. package/assets/skills/openspec-apply-change/SKILL.md +7 -0
  8. package/assets/skills/openspec-archive-change/SKILL.md +13 -1
  9. package/assets/skills/superflow-archive/SKILL.md +17 -0
  10. package/assets/skills/superflow-docs/SKILL.md +11 -0
  11. package/assets/skills/superflow-implement/SKILL.md +11 -0
  12. package/assets/skills/superflow-pipeline/SKILL.md +6 -1
  13. package/assets/skills/superflow-pipeline/references/architecture-design-template.md +4 -2
  14. package/assets/skills/superflow-pipeline/references/batch-prompt-template.md +6 -1
  15. package/assets/skills/superflow-pipeline/references/document-review-coverage.md +26 -0
  16. package/assets/skills/superflow-pipeline/references/document-templates.md +7 -0
  17. package/assets/skills/superflow-pipeline/references/implementation-prompt-template.md +41 -35
  18. package/assets/skills/superflow-pipeline/references/mock-strategy-guide.md +28 -74
  19. package/assets/skills/superflow-pipeline/references/orchestration.md +43 -101
  20. package/assets/skills/superflow-pipeline/references/quality-gate.md +8 -4
  21. package/assets/skills/superflow-pipeline/references/reviewer-checklist.md +99 -3
  22. package/assets/skills/superflow-pipeline/references/superpower-technical-design-template.md +17 -0
  23. package/assets/skills/superflow-pipeline/references/test-execution-template.md +16 -12
  24. package/assets/skills/superflow-pipeline/references/test-guide.md +82 -30
  25. package/assets/skills/superflow-pipeline/scripts/superflow-archive.sh +57 -10
  26. package/assets/skills/superflow-pipeline/scripts/superflow-guard.sh +23 -6
  27. package/assets/skills/superflow-quick-dev/SKILL.md +3 -3
  28. package/assets/skills/superflow-verify/SKILL.md +28 -12
  29. package/assets/skills-en/openspec-apply-change/SKILL.md +8 -0
  30. package/assets/skills-en/openspec-archive-change/SKILL.md +17 -1
  31. package/assets/skills-en/superflow-archive/SKILL.md +20 -0
  32. package/assets/skills-en/superflow-docs/SKILL.md +13 -0
  33. package/assets/skills-en/superflow-implement/SKILL.md +13 -0
  34. package/assets/skills-en/superflow-pipeline/SKILL.md +6 -0
  35. package/assets/skills-en/superflow-pipeline/references/architecture-design-template.md +3 -0
  36. package/assets/skills-en/superflow-pipeline/references/batch-prompt-template.md +7 -0
  37. package/assets/skills-en/superflow-pipeline/references/document-review-coverage.md +32 -0
  38. package/assets/skills-en/superflow-pipeline/references/document-templates.md +8 -0
  39. package/assets/skills-en/superflow-pipeline/references/implementation-prompt-template.md +11 -0
  40. package/assets/skills-en/superflow-pipeline/references/mock-strategy-guide.md +41 -11
  41. package/assets/skills-en/superflow-pipeline/references/orchestration.md +11 -0
  42. package/assets/skills-en/superflow-pipeline/references/quality-gate.md +9 -0
  43. package/assets/skills-en/superflow-pipeline/references/reviewer-checklist.md +122 -1
  44. package/assets/skills-en/superflow-pipeline/references/superpower-technical-design-template.md +21 -0
  45. package/assets/skills-en/superflow-pipeline/references/test-execution-template.md +5 -0
  46. package/assets/skills-en/superflow-pipeline/references/test-guide.md +106 -12
  47. package/assets/skills-en/superflow-pipeline/scripts/superflow-archive.sh +57 -10
  48. package/assets/skills-en/superflow-pipeline/scripts/superflow-guard.sh +23 -6
  49. package/assets/skills-en/superflow-quick-dev/SKILL.md +6 -3
  50. package/assets/skills-en/superflow-verify/SKILL.md +36 -12
  51. package/dist/app/cli.js +5 -5
  52. package/dist/app/cli.js.map +1 -1
  53. package/dist/app/commands/review-coverage.js +8 -3
  54. package/dist/app/commands/review-coverage.js.map +1 -1
  55. package/dist/app/commands/update.js +2 -0
  56. package/dist/app/commands/update.js.map +1 -1
  57. package/dist/build-info.json +1 -0
  58. package/dist/domains/config/cli-help.js +8 -0
  59. package/dist/domains/config/cli-help.js.map +1 -1
  60. package/dist/domains/managed-work/failure.js +9 -0
  61. package/dist/domains/managed-work/failure.js.map +1 -1
  62. package/dist/domains/managed-work/prompts.js +3 -0
  63. package/dist/domains/managed-work/prompts.js.map +1 -1
  64. package/dist/domains/managed-work/runner.js +29 -24
  65. package/dist/domains/managed-work/runner.js.map +1 -1
  66. package/dist/domains/managed-work/service.js +147 -19
  67. package/dist/domains/managed-work/service.js.map +1 -1
  68. package/dist/domains/review/coverage.js +12 -4
  69. package/dist/domains/review/coverage.js.map +1 -1
  70. package/dist/domains/review/report.js +67 -2
  71. package/dist/domains/review/report.js.map +1 -1
  72. package/dist/mcp/runtime-identity.js +19 -4
  73. package/dist/mcp/runtime-identity.js.map +1 -1
  74. package/dist/mcp/server.js +1 -1
  75. package/dist/mcp/server.js.map +1 -1
  76. package/dist/platform/agent-process.js +48 -9
  77. package/dist/platform/agent-process.js.map +1 -1
  78. package/dist/platform/process-liveness.js +46 -0
  79. package/dist/platform/process-liveness.js.map +1 -1
  80. package/package.json +2 -1
  81. package/scripts/ensure-bin-modes.js +37 -2
  82. package/scripts/verify-changed.mjs +321 -0
@@ -1,5 +1,10 @@
1
1
  # Implementation Prompt 模板
2
2
 
3
+ 验证方案只继承 tests.md,并先读 [test-guide.md](test-guide.md)。模板中的启动、
4
+ 接口、DB 和团队 checklist 按已冻结的适用项执行,不适用项给出源码依据;缺失必测
5
+ 环境保持阻塞。当前构建与健康实例一致时复用;新代码/配置必须加载后才可验证。
6
+ 独立核验原始证据,失效或合同要求的路径由实施方重跑,不能由角色切换触发重复环境。
7
+
3
8
  此模板可直接 copy-paste 给新 Agent 使用。根据实际项目替换 `{占位符}`。
4
9
 
5
10
  ---
@@ -13,6 +18,11 @@
13
18
 
14
19
  ## 核心原则(强制执行)
15
20
 
21
+ 开始前读取 tests.md 与 Superflow 的 [test-guide.md](test-guide.md),只继承已冻结的
22
+ 验证信号/用例。生成实际 Prompt 时把指南链接解析为安装资产的真实路径,避免复制后
23
+ 相对路径失效。纯函数或报告格式修改不虚构应用/API/DB,必测项缺环境不得豁免。
24
+
25
+
16
26
  涉及数据库变更时,SQL 已在 [release-sql.md](../release-sql.md) 详设阶段冻结。
17
27
  研发 Agent 只有原样复制权:按 front matter 的 `target_sql_path` 落盘,统一 LF 且
18
28
  保留一个结尾换行,核对 `sql_sha256`。禁止新增、删除、重排、拆分或优化 SQL;
@@ -22,15 +32,15 @@
22
32
  编译成功 ≠ 完成任务
23
33
  Worker 自测通过 ≠ 完成任务
24
34
  测试后补通过 ≠ 完成任务
25
- 独立 Tester 验证通过 = 完成任务
35
+ 冻结合同的全部必测项通过且独立核验完成 = 完成任务
26
36
 
27
- 一个任务只有满足以下 ALL 条件,才能标记为"完成":
37
+ 一个任务只有满足以下冻结的适用条件,才能标记为"完成":
28
38
  1. 代码已修改(git diff 确认)
29
39
  2. 代码自审通过(无 CRITICAL/HIGH 问题,检查空指针/异常/事务/日志)
30
40
  3. 编译通过(clean compile 无 ERROR)
31
- 4. 应用已重新启动(进程验证通过,是新进程)
41
+ 4. 运行实例匹配当前构建/配置、owner 与健康检查通过;需要时重新启动
32
42
  5. **RED-GREEN 证据完整**(编码前同一用例失败,编码后同一用例通过)
33
- 6. **独立 Tester 测试通过**(Tester 独立执行全部用例,客观报告)
43
+ 6. **独立 Tester 测试通过**(Tester 独立核验全部用例,重跑失效或合同指定路径,客观报告)
34
44
  7. 数据库状态验证通过(mysql 查询确认)
35
45
  8. 日志检查通过(无 ERROR,关键日志出现)
36
46
  9. Leader 已独立验证(不信任 Worker/Tester 报告)
@@ -643,12 +653,12 @@ done
643
653
 
644
654
  创建 Team,成员如下:
645
655
 
646
- - **Leader**: 你(协调、集成验证、亲自执行回归测试)
656
+ - **Leader**: 你(协调、独立核验集成/回归证据)
647
657
  - **Worker-1(至少保留)**: Group A - {task-list-1}
648
658
  - **Worker-2(可选)**: Group B - {task-list-2}
649
659
  - **Worker-3(可选)**: Group C - {task-list-3}
650
660
  - **Reviewer(强制参与)**: 代码评审(Worker 先自审,Reviewer 在测试前完成评审)
651
- - **Tester(强制独立,至少保留)**: 独立测试验证(与 Worker 分离,不参考 Worker 自测报告)
661
+ - **Tester(强制独立,至少保留)**: 独立测试验证(与 Worker 分离,独立核验原始证据和源码,不转述自测结论)
652
662
 
653
663
  ## Phase 3: 给每个 Worker 的 Prompt 模板
654
664
 
@@ -736,13 +746,10 @@ git status --short
736
746
  - **路由检查**:新增的固定路径是否可能被现有 `{id}` 路径变量抢占?
737
747
  - **数据权限检查**:访问业务数据的接口是否按 api.md 的数据权限决策实现了?是否复用了当前仓库已有权限模式?是否避免了凭字段名猜测?
738
748
  - **外部 SDK 检查**:SDK 参数是否有来源说明?是否凭字段名猜测?
739
- - 使用 `code-review-java` skill 进行评审
749
+ - 读取 [统一五维 Reviewer 清单](reviewer-checklist.md),通过 `superflow-verify` 进行评审
740
750
  - 发现问题立即修复,修复后重新自审
741
751
  - 自审未通过不得进入编译环节
742
- 步骤 4: 停止旧进程
743
- pkill -f "spring-boot:run" 2>/dev/null || true
744
- pkill -f "GradleDaemon" 2>/dev/null || true
745
- sleep 2
752
+ 步骤 4: 需重启时,执行 tests.md 冻结的 owner 校验与清理入口,仅停止本任务进程;身份不匹配则拒绝停止
746
753
  步骤 5: 确认端口已释放
747
754
  netstat -tlnp | grep {port} # 应该无输出
748
755
  步骤 6: 检查端口占用(必须先做,再编译)
@@ -807,9 +814,8 @@ fi
807
814
  步骤 8: 启动应用(记录 PID)
808
815
 
809
816
  ```bash
810
- # 先停止自己的旧进程(只停自己的,不碰别人的)
811
- pkill -f "spring-boot:run" 2>/dev/null || true
812
- sleep 2
817
+ # 前置条件:需重启时已通过 tests.md 的 owner 校验清理本任务旧实例
818
+ # 健康实例匹配当前待测构建时复用,不执行重复启动
813
819
 
814
820
  # 使用确定的端口启动(可能是原端口或新端口)
815
821
  nohup {run-cmd} > app.log 2>&1 &
@@ -904,7 +910,7 @@ sleep 15
904
910
 
905
911
  ### 核心原则
906
912
 
907
- - **与 Worker 完全分离**:不参考 Worker 的自测报告,独立从头执行测试
913
+ - **与 Worker 完全分离**:独立核验 Worker 的原始证据与源码,不转述其结论;由实施方重跑失效或合同指定用例
908
914
  - **客观报告**:如实报告失败,不替 Worker 找理由
909
915
  - **覆盖全部用例**:执行 tests.md 中所有标注 [自动化] 的用例
910
916
 
@@ -940,15 +946,15 @@ sleep 15
940
946
 
941
947
  ```
942
948
 
943
- ## Phase 4: 集成验证(你亲自执行)
949
+ ## Phase 4: 集成证据独立核验(缺失或失效路径由实施方执行)
944
950
 
945
951
  所有 Worker 完成后:
946
- 1. 亲自执行全量编译: {compile-cmd}
947
- 2. 亲自执行进程验证(按上述步骤 3-8)
948
- 3. 亲自执行回归测试: 按 tests.md 完整执行所有 curl
949
- 4. 亲自查询数据库验证数据状态
950
- 5. 亲自检查日志无 ERROR
951
- 6. 亲自执行验收脚本:
952
+ 1. 核验当前源码的构建命令与原始结果: {compile-cmd}
953
+ 2. 核验当前构建、配置与进程 owner 身份证据(按上述步骤 3-8)
954
+ 3. 核验 tests.md 的全部必测入口/回归证据,要求实施方执行缺失或失效路径
955
+ 4. 核验同业务 ID 的数据库前后状态、断言与实际 statement 原始证据
956
+ 5. 核验对应实例/用例的日志断言与已知异常解释
957
+ 6. 核验当前验收脚本的原始结果;脚本本轮变化时由实施方重跑:
952
958
  `~/.codex/hooks/superflow-verify-integration.sh <test-report.md>`
953
959
 
954
960
  ## Phase 4.5: 接口验证 Checklist(每个任务必须逐项执行并记录证据)
@@ -964,12 +970,12 @@ Worker 完成编码和启动后,必须按以下 checklist 逐项执行接口
964
970
  - [ ] 未修改 tests.md 语义来迎合实现;如测试合同需变更,已回到 SDD 文档阶段
965
971
 
966
972
  ### 启动验证(必须执行)
967
- - [ ] 旧进程已停止(`pkill` + `sleep 2` + 端口确认无占用)
973
+ - [ ] 需重启时通过 owner 校验清理本任务旧实例,确认端口释放
968
974
  - [ ] 重新编译通过(`mvn clean compile -DskipTests` BUILD SUCCESS)
969
975
  - [ ] 应用已启动(`mvn spring-boot:run` 或 `./gradlew bootRun`)
970
- - [ ] 进程已验证(PID 存在、启动时间接近当前、端口绑定正确)
976
+ - [ ] 进程已验证(PID/启动指纹、待测构建/配置与端口绑定正确)
971
977
  - [ ] 健康检查通过(`curl /actuator/health` 返回 UP)
972
- - [ ] 日志确认是本次启动(时间戳匹配、无异常退出)
978
+ - [ ] 日志匹配待测实例/构建,无异常退出
973
979
 
974
980
  ### Token 获取(必须执行)
975
981
  - [ ] 已调用 `/captcha/image`(带 `-c` Cookie)
@@ -1005,25 +1011,25 @@ Worker 完成编码和启动后,必须按以下 checklist 逐项执行接口
1005
1011
 
1006
1012
  ---
1007
1013
 
1008
- ## Phase 5: 强制质量门禁(全部必须满足)
1014
+ ## Phase 5: 强制质量门禁(冻结的全部适用项必须满足)
1009
1015
 
1010
1016
  | # | 门禁 | 通过标准 | 验证人 |
1011
1017
  |---|------|---------|--------|
1012
1018
  | 1 | 编译 | `mvn clean compile -DskipTests` BUILD SUCCESS | Worker + Leader |
1013
- | 2 | 启动 | 新进程 + 健康检查 UP + 日志时间戳匹配 | Worker + Leader |
1019
+ | 2 | 启动 | 当前构建/owner 指纹匹配 + 健康检查 UP + 对应实例日志 | Worker + Leader |
1014
1020
  | 3 | **接口测试** | **Worker 逐项执行 L3 checklist 全部勾选** | **Worker** |
1015
- | 4 | **独立测试** | **Tester 独立执行全部用例通过** | **Tester** |
1021
+ | 4 | **独立测试** | **Tester 独立核验全部必测证据,受影响重跑通过** | **Tester** |
1016
1022
  | 5 | 数据库 | `SHOW CREATE TABLE` / `SELECT` 验证数据状态符合预期 | Tester + Leader |
1017
1023
  | 6 | 日志 | `grep ERROR` 无 ERROR + 关键日志出现 | Tester + Leader |
1018
1024
  | 7 | SDD 集成验收脚本 | `superflow-verify-integration.sh <test-report.md>` 通过 | Worker + Leader |
1019
1025
  | 8 | 代码评审 | 无 HIGH+ 问题 | Reviewer |
1020
- | 9 | 全链路回归 | 真实应用 API 集成测试通过;跨系统任务需真实入口证据或明确阻塞 | Leader 亲自 |
1026
+ | 9 | 全链路回归 | 真实应用 API 集成测试通过;跨系统任务需真实入口证据或明确阻塞 | Leader 独立核验 |
1021
1027
 
1022
1028
  ⚠️ **任一门禁未通过,不得交付。Worker 门禁未通过不得报告完成。Leader 抽查未通过标记任务未完成。**
1023
1029
 
1024
1030
  **特别强调:**
1025
- - 门禁 3(接口测试)不是"可选优化",是**必须**。Worker 必须亲自逐项执行 checklist 中的 curl 命令,并记录响应。不能跳过这步直接等 Tester。
1026
- - 门禁 2(启动)不是"端口监听就行",必须验证是新进程(PID、启动时间、日志时间戳)。复用旧进程测试 = 测试无效。
1031
+ - 已冻结的门禁 3(接口测试)不是"可选优化",是**必须**。Worker 必须亲自逐项执行 checklist 中的 curl 命令,并记录响应。不能跳过这步直接等 Tester。
1032
+ - 门禁 2(启动)不是"端口监听就行",必须验证实例对应当前待测构建、配置与 owner;仅端口监听不能证明已加载新代码。
1027
1033
  - 门禁 5(数据库)不是"接口返回对就行",必须真实查询数据库确认数据落库正确。
1028
1034
  - 门禁 7(验收脚本)不是形式检查,可失败即说明证据缺口;失败时只能补证据或标记阻塞,不能绕过。
1029
1035
 
@@ -1035,15 +1041,15 @@ Worker 完成编码和启动后,必须按以下 checklist 逐项执行接口
1035
1041
 
1036
1042
  2. ❌ **编译成功就交付(必须通过全部门禁)**
1037
1043
  - ❌ 错误:"代码已修改,编译通过,任务完成"
1038
- - ✅ 正确:"代码已修改,编译通过,应用已启动,接口已真实调用,数据库已验证,test-report 已回填,任务完成"
1044
+ - ✅ 正确:"冻结的全部适用信号通过,必测真实入口/数据库证据齐全,test-report 已回填,任务完成"
1039
1045
 
1040
- 3. ❌ **不启动应用就宣称完成**
1046
+ 3. ❌ **跳过合同必测的应用启动就宣称完成**
1041
1047
  - ❌ 错误:"单元测试通过,openspec 验证通过,任务完成"(从未启动应用、从未调接口)
1042
- - ✅ 正确:必须启动应用 → 进程验证 → 健康检查 UP → 逐项执行 L3 checklist → 数据库验证 → 日志检查 → 全部完成后才能报告
1048
+ - ✅ 正确:合同要求真实链路时,必须完成启动/实例身份核验 → 就绪 → 指定入口 → DB/日志断言;纯函数只执行其冻结 seam,报告格式整改核验受影响证据
1043
1049
 
1044
1050
  4. ❌ **Worker 自测自报"完成"(Worker 只报告"开发完成", Tester 独立验证后才能算完成)**
1045
1051
 
1046
- 4. ❌ **Tester 参考 Worker 的自测结果(Tester 必须独立从头执行全部用例)**
1052
+ 4. ❌ **Tester 只转述 Worker 结论(必须独立核验源码与原始证据;失效或合同指定路径重跑)**
1047
1053
 
1048
1054
  5. ❌ **复用旧进程测试新代码(必须停止旧进程重新启动)**
1049
1055
 
@@ -1,86 +1,40 @@
1
1
  # Mock 策略与边界声明指南
2
2
 
3
- 比赛/项目中涉及外部接口、设备回调、第三方服务时,必须明确 Mock 策略并在交付物中声明。
3
+ ## 适用与事实源
4
4
 
5
- ## 何时需要 Mock
5
+ 设计隔离测试或报告替代证据时读取;选择验证信号先读 [test-guide.md](test-guide.md)。
6
+ 数据库分层、mockBoundary 和执行凭证只继承
7
+ [document-review-coverage.md](document-review-coverage.md#数据库分层合同)。
8
+ 本指南说明可隔离范围,不授权降低 tests.md 已冻结的真实环境验收。
6
9
 
7
- | 场景 | 是否 Mock | 说明 |
8
- |------|-----------|------|
9
- | 外部 HTTP API(支付、短信、地图) | ✅ 必须 | 避免真实调用产生费用或副作用 |
10
- | 设备回调(门禁、摄像头、传感器) | ✅ 必须 | 无真实硬件环境 |
11
- | 数据库(无测试环境) | ✅ 可选 | 可用 H2 / Docker MySQL |
12
- | 消息队列 | ✅ 可选 | 可用内存队列替代 |
13
- | 缓存(Redis) | ✅ 可选 | 可用 Caffeine / 本地缓存 |
14
- | 文件存储(OSS) | ✅ 可选 | 可用本地文件系统 |
10
+ | 场景 | 可隔离的范围 | 能证明什么 / 仍需验证什么 |
11
+ |---|---|---|
12
+ | 纯逻辑单测 | 被测逻辑之外的数据访问/HTTP/MQ依赖 | 分支、参数与失败处理;不能证明真实 SQL 或落库 |
13
+ | 必测持久化/事务/CAS | mockBoundary.allowed 的外部客户端 | 生产 Service/Mapper 不得 mock;实际同引擎数据库与生产 statement 必须执行 |
14
+ | 外部支付/短信/设备 | 合同允许的客户端、沙箱或模拟消息 | 局部处理;真实外部能力必须另有沙箱/真实入口证据,缺环境记阻塞 |
15
+ | MQ/Redis/OSS | 纯逻辑测试的接口边界 | 内存队列、本地缓存/文件不能关闭真实协议、锁、持久化或外部链路要求 |
15
16
 
16
- ## Mock 方式选择
17
+ 真实同引擎 Docker/Testcontainers 数据库不是 Mock。冻结环境允许时复用;共享环境要求
18
+ 不能擅自替换。H2/SQLite 不能替代 MySQL 的方言、锁、事务或落库语义;缺库时保留
19
+ 逻辑局部证据,必测数据库项 BLOCKED/PARTIAL。
17
20
 
18
- | 方式 | 适用场景 | 实现手段 | 验证能力 |
19
- |------|----------|----------|----------|
20
- | `@MockBean` | Spring Boot 单元/集成测试 | Mockito | 验证调用次数、参数 |
21
- | `WireMock` | HTTP 外部服务 | 独立 Mock 服务器 | 验证请求格式、返回预设响应 |
22
- | 本地模拟服务 | 设备回调、Webhook | 单独启动的 HTTP 服务 | 手动触发回调 |
23
- | 接口假实现 | 无测试框架时 | 接口的硬编码实现 | 固定返回 |
24
- | H2 内存数据库 | 无 MySQL 环境 | `spring.datasource.url=jdbc:h2:mem` | 标准 SQL 验证 |
21
+ ## 声明与报告
25
22
 
26
- ## Mock 边界声明模板
23
+ 每个隔离边界写入现有 tests.md / test-report.md:实际能力、替换对象、mockBoundary、
24
+ 假设、可证明范围、仍未验证范围、真实验证命令/阻塞原因及证据路径。
25
+ 分开记录 `Mock 验证`、`测试端点验证`、`真实入口验证`。辅助逻辑 case 可通过,
26
+ 但 mock-only 不能关闭同一入口的必要数据库或真实链路 case。
27
27
 
28
- 每个使用 Mock 的外部依赖必须在交付文档中填写下表:
28
+ ## 示例:隔离支付客户端,验证真实落库
29
29
 
30
- ```markdown
31
- ## Mock 声明
32
-
33
- ### 外部依赖 1:<名称>
34
-
35
- | 项目 | 说明 |
36
- |------|------|
37
- | 实际能力 | ____(如:真实支付扣款) |
38
- | Mock 方式 | ____(如:@MockBean + 固定返回 success) |
39
- | Mock 范围 | ____(哪些接口/方法被 Mock) |
40
- | 假设条件 | ____(如:假设支付网关永远返回成功) |
41
- | 替代验证 | ____(如何验证代码逻辑正确,如:检查数据库状态变化) |
42
- | 恢复真实 | ____(如何切回真实服务,如:去掉 @MockBean 注解) |
43
- ```
44
-
45
- ## 示例:门禁设备回调 Mock
46
-
47
- ```markdown
48
- ### 外部依赖:人行门禁设备
49
-
50
- | 项目 | 说明 |
51
- |------|------|
52
- | 实际能力 | 真实硬件设备,刷卡/人脸识别后主动回调服务器 |
53
- | Mock 方式 | 本地启动模拟 HTTP 服务(Python Flask / Node.js) |
54
- | Mock 范围 | `/device/callback` 接口接收回调 |
55
- | 假设条件 | 假设设备回调的报文格式与真实设备一致 |
56
- | 替代验证 | 手动 POST 模拟回调报文,验证服务器处理逻辑(记录通行日志、开门指令) |
57
- | 恢复真实 | 将回调地址指向真实设备网关 |
58
- ```
59
-
60
- ## 示例:支付接口 Mock
61
-
62
- ```java
63
- // 测试中使用 @MockBean
64
- @MockBean
65
- private PaymentClient paymentClient;
66
-
67
- @BeforeEach
68
- void setUp() {
69
- when(paymentClient.charge(any()))
70
- .thenReturn(PaymentResult.success("mock-trade-no"));
71
- }
72
-
73
- // 验证替代方式:检查订单状态是否变为 PAID
74
- @Test
75
- void shouldUpdateOrderStatusWhenPaymentSuccess() {
76
- // 执行支付流程
77
- // 断言:数据库订单状态 = PAID(不依赖真实支付)
78
- }
79
- ```
30
+ 当合同允许隔离 PaymentClient 时,用固定成功响应驱动**真实**业务 Service 和 Mapper,
31
+ 在已冻结的 MySQL 上按订单 ID 检查 before/after、金额与状态,并核验必要副作用。
32
+ 这个用例证明业务处理与落库,不证明支付网关实际扣款;后者单独验证或记录阻塞。
33
+ 纯 Service 单测可 mock Mapper,但只能报告逻辑结果,不得称为数据库集成通过。
80
34
 
81
35
  ## 禁止事项
82
36
 
83
- 1. ❌ Mock 后不声明假设条件
84
- 2. ❌ Mock 范围过大(把整个 Service 层都 Mock 掉)
85
- 3. ❌ 无替代验证方式(Mock 后不知道代码对不对)
86
- 4. ❌ 生产代码中残留 Mock 逻辑
37
+ - mock 被测主体,或在必测数据库 case 中 mock 生产 Service/Mapper。
38
+ - 用固定成功、调用次数、HTTP 200、影响行数非零代替业务/数据库值断言。
39
+ - 混合替代证据和真实证据,或把未执行/跳过用例计入完整通过。
40
+ - 为赶交付静默更换冻结后端、放宽断言,或在生产代码保留 Mock。
@@ -1,5 +1,10 @@
1
1
  # 实现编排指南:多 Agent 协作开发
2
2
 
3
+ 验证方案只继承 tests.md,并先读 [test-guide.md](test-guide.md)。模板中的启动、
4
+ 接口、DB 和团队 checklist 按已冻结的适用项执行,不适用项给出源码依据;缺失必测
5
+ 环境保持阻塞。当前构建与健康实例一致时复用;新代码/配置必须加载后才可验证。
6
+ 独立核验原始证据,失效或合同要求的路径由实施方重跑,不能由角色切换触发重复环境。
7
+
3
8
  > **分批实现优先**:对复杂需求,编排前必须先按 [分批实现拆分指南](batch-split-guide.md) 拆分为 P0 → P1 → P2 → P3 → P4 批次。每批独立编排、独立验收,通过后才能开始下一批。
4
9
 
5
10
  ## 编排决策
@@ -51,12 +56,12 @@ Group 4: 独立模块(Bug 6, 7, 11)
51
56
  - 创建 TaskList,按依赖拓扑排序
52
57
  - 将任务分配给 Worker Agent
53
58
  - 监控进度,处理阻塞任务
54
- - **亲自执行集成测试和回归测试(不依赖 Worker 报告)**
59
+ - **独立审查集成/回归原始证据与源码,要求实施方补齐失效或缺失验证**
55
60
  - 汇总质量报告
56
61
 
57
62
  **必须遵守**:
58
63
  - **不要直接编码**,只负责协调和集成验证
59
- - **不信任 Worker 的测试报告**,必须亲自验证至少 30% 的关键用例
64
+ - **不信任 Worker 的测试报告**,按冻结合同与风险独立核验关键用例的源码和原始证据
60
65
  - **必须执行进程验证**,确认测试的是新代码而非旧进程
61
66
 
62
67
  ### 角色 2:Worker(执行 Agent)
@@ -78,19 +83,19 @@ Group 4: 独立模块(Bug 6, 7, 11)
78
83
 
79
84
  **职责**:
80
85
  - **独立于 Worker**,接收 Leader 分配的测试任务
81
- - 按 tests.md 的用例独立执行测试(不依赖 Worker 的自测报告)
86
+ - 按 tests.md 独立核验用例覆盖、源码与原始证据,不只转述 Worker 结论
82
87
  - 验证接口、数据库、日志,输出客观测试结果
83
88
  - 发现失败时,向 Leader 报告失败现象,不直接向 Worker 反馈
84
89
 
85
90
  **必须遵守**:
86
91
  - **与 Worker 完全分离**:Worker 负责开发,Tester 负责验证,不能是同一人
87
- - **独立验证**:不参考 Worker 的测试报告,从头执行测试
92
+ - **独立验证**:核验实际源码和原始证据,失效或合同指定路径由实施方重跑
88
93
  - **客观报告**:如实报告失败,不替 Worker 找理由("可能环境问题"、"应该没改这块")
89
- - **覆盖全部用例**:必须执行 tests.md 中所有标注 [自动化] 的用例,不能抽样
94
+ - **覆盖全部用例**:必须核对全部必测自动化用例的有效执行证据,不用抽样替代完整覆盖
90
95
 
91
96
  **Tester 的测试流程**:
92
97
  ```
93
- 接收测试任务 → 读取 tests.md → 独立执行测试
98
+ 接收测试任务 → 读取 tests.md → 独立核验源码与原始证据 → 必要时要求实施方重跑
94
99
  → 通过:向 Leader 报告"测试通过,证据如下..."
95
100
  → 失败:向 Leader 报告"测试失败,现象如下..."
96
101
  ```
@@ -113,7 +118,7 @@ Group 4: 独立模块(Bug 6, 7, 11)
113
118
  - 对 Worker 提交的代码进行 review
114
119
  - 检查编码规范、安全漏洞、性能问题
115
120
  - 验证是否符合 design.md 的设计方案
116
- - 使用 `code-review-java` skill 进行评审
121
+ - 读取 [统一五维 Reviewer 清单](reviewer-checklist.md),通过 `superflow-verify` 进行评审
117
122
 
118
123
  **必须遵守**:
119
124
  - **Worker 必须在测试前先自审代码**,不能等全部编码完成再补审
@@ -148,12 +153,12 @@ Group 4: 独立模块(Bug 6, 7, 11)
148
153
  | 1 | 代码已修改 | Worker | git diff 确认 |
149
154
  | 2 | 代码自审通过 | Worker | 已执行 review,无 CRITICAL/HIGH |
150
155
  | 3 | 编译通过 | Worker | clean compile 无 ERROR |
151
- | 4 | 应用已重新启动 | Worker | 进程验证通过(新进程、新时间戳) |
156
+ | 4 | 应用匹配当前待测构建 | Worker | 构建/配置与 owner 指纹核验,必要时重启 |
152
157
  | 5 | **接口已真实调用** | **Worker** | **逐项执行 L3 checklist,记录 curl + 响应** |
153
158
  | 6 | **数据库已验证** | **Worker** | **SHOW CREATE TABLE / SELECT 确认数据状态** |
154
159
  | 7 | **日志已检查** | **Worker** | **grep ERROR 无 ERROR** |
155
160
  | 8 | test-report 已回填 | Worker | 包含 curl、响应、DB、日志证据 |
156
- | 9 | **独立 Tester 测试通过** | **Tester** | **Tester 独立执行全部用例,客观报告** |
161
+ | 9 | **独立 Tester 测试通过** | **Tester** | **Tester 独立核验全部必测用例,重跑失效或合同指定路径,客观报告** |
157
162
  | 10 | Leader 已独立验证 | Leader | Leader 亲自验证或抽查 |
158
163
  | 11 | build→verify 最终代码评审通过 | Leader/Reviewer | 使用 `requesting-code-review`,确认无 CRITICAL/HIGH 遗留 |
159
164
 
@@ -199,7 +204,7 @@ Group 4: 独立模块(Bug 6, 7, 11)
199
204
  - 不能依赖增量编译
200
205
 
201
206
  3. **启动前先停止旧进程(只停自己的,不碰别人的)**
202
- - `pkill -f "spring-boot:run"` 或 `pkill -f "GradleDaemon"`
207
+ - 执行 tests.md 冻结的 owner 校验与清理入口,仅停止本任务实例;拒绝身份不匹配资源
203
208
  - **启动前必须检查端口占用**:`lsof -i :{port}` 或 `netstat -tlnp | grep {port}`
204
209
  - **如果端口被其他 agent 占用**:自己换一个端口启动,不得关闭其他进程
205
210
  - 确认端口释放后再启动
@@ -259,14 +264,14 @@ Worker 流程:
259
264
  └──────────────── 编译/启动失败,修复后重新编译 ───┘
260
265
 
261
266
  Tester 流程(Worker 启动后):
262
- [接收任务] → 读取 tests.md → 独立执行测试 → 数据库验证 → 日志检查 → [报告:测试通过/失败]
267
+ [接收任务] → 读取 tests.md → 独立核验源码与原始证据 → 必要时要求实施方重跑 → 数据库验证 → 日志检查 → [报告:测试通过/失败]
263
268
  ↑ |
264
269
  └──────── 测试失败,报告 Leader ────────────────┘
265
270
  ```
266
271
 
267
272
  **关键分离原则**:
268
273
  - Worker 不报告"测试通过",只报告"应用已启动,可供测试"
269
- - Tester 独立执行测试,不参考 Worker 的自测结果
274
+ - Tester 独立核验源码与原始证据,不转述 Worker 的自测结论
270
275
  - Tester 的测试报告直接发给 Leader,不发给 Worker
271
276
  - Leader 根据 Tester 报告判断任务是否完成
272
277
 
@@ -274,7 +279,7 @@ Tester 流程(Worker 启动后):
274
279
  1. 读取修改后的文件,逐行检查
275
280
  2. 对照 design.md 检查是否按设计实现
276
281
  3. 检查:空指针风险、异常处理、事务边界、日志规范
277
- 4. 使用 `code-review-java` skill 进行正式评审
282
+ 4. 读取 [统一五维 Reviewer 清单](reviewer-checklist.md),通过 `superflow-verify` 进行正式评审
278
283
  5. **自审未通过不得进入编译环节**
279
284
 
280
285
  **Worker-1** 执行 Group A:
@@ -303,85 +308,22 @@ Worker 可能看到端口监听就误以为应用启动成功,但实际上:
303
308
 
304
309
  #### 验证步骤
305
310
 
306
- **步骤 1:停止所有旧进程**
307
- ```bash
308
- pkill -f "spring-boot:run" 2>/dev/null || true
309
- pkill -f "GradleDaemon" 2>/dev/null || true
310
- sleep 2
311
- ```
312
-
313
- **步骤 2:确认端口已释放**
314
- ```bash
315
- # 应该无输出,如果有输出说明旧进程还在
316
- netstat -tlnp 2>/dev/null | grep {port} || ss -tlnp | grep {port}
317
- ```
318
-
319
- **步骤 3:清理并重新编译**
320
- ```bash
321
- # Maven
322
- mvn clean compile -DskipTests
323
-
324
- # Gradle
325
- ./gradlew clean compileJava -x test
326
- ```
327
-
328
- **步骤 4:启动应用**
329
- ```bash
330
- # Maven
331
- nohup mvn spring-boot:run -Dspring-boot.run.profiles={profile} > app.log 2>&1 &
332
-
333
- # Gradle
334
- nohup ./gradlew bootRun --args='--spring.profiles.active={profile}' > app.log 2>&1 &
335
-
336
- echo $! > /tmp/app.pid # 记录 PID
337
- ```
338
-
339
- **步骤 5:等待并确认是新进程**
340
- ```bash
341
- sleep 15 # 等待启动
342
-
343
- # 获取监听端口的 PID
344
- NEW_PID=$(cat /tmp/app.pid)
345
-
346
- # 检查进程存在且启动时间接近当前时间
347
- ps -o pid,lstart,cmd -p $NEW_PID
348
-
349
- # 检查端口绑定的是否是这个 PID
350
- netstat -tlnp | grep {port}
351
- ```
352
-
353
- **步骤 6:检查日志确认本次启动**
354
- ```bash
355
- tail -30 app.log
356
- # 日志中必须有本次启动的时间戳
357
- # 如果看到几天前的日志或旧时间戳,说明是旧进程!必须停止重来!
358
- ```
359
-
360
- **步骤 7:验证加载的是新代码**
361
- ```bash
362
- # Gradle
363
- ls -la build/classes/java/main/{修改的类路径}.class
364
-
365
- # Maven
366
- ls -la target/classes/{修改的类路径}.class
367
-
368
- # 时间戳应该在本次编译时间附近(5分钟内)
369
- ```
370
-
371
- **步骤 8:健康检查**
372
- ```bash
373
- curl -s http://localhost:{port}{context-path}/actuator/health | grep UP
374
- # 必须返回 UP,否则启动失败
375
- ```
311
+ 1. 将当前源码/构建、配置和冻结环境与运行实例身份核对;一致且健康时复用。
312
+ 2. 需加载新代码或配置时,由实施方执行 tests.md 的单命令验收入口,复用既有
313
+ owner helper,先核验 owner 再清理旧实例;不停止其他任务或 IDE 的进程。
314
+ 3. 按冻结命令构建、启动并通过就绪条件;保存 PID/启动指纹、构建与配置身份、端口、
315
+ 健康检查和日志。单独的文件时间戳、端口监听或 sleep 结束不能证明新代码已加载。
316
+ 4. 执行真实受影响入口和业务/DB/副作用断言,失败时保留日志并运行 owner 清理。
317
+ 5. 独立评审读取对应原始证据;仅报告格式整改不重复启动、查库和全链路运行。
376
318
 
377
319
  ### Phase 4:集成验证(Leader 执行)
378
320
 
379
321
  所有 Worker 完成后:
380
322
 
381
323
  1. **合并检查**:确认没有同一文件的冲突修改
382
- 2. **Leader 亲自执行全量编译**:使用正确的构建工具命令
383
- 3. **Leader 亲自执行进程验证**:按 Phase 3 步骤执行
384
- 4. **Leader 亲自执行回归测试**:
324
+ 2. **Leader 核验构建证据**:确认当前源码对应正确构建命令与成功输出
325
+ 3. **Leader 核验进程证据**:按 Phase 3 核对 owner、构建、配置与实例身份
326
+ 4. **Leader 核验回归结果,要求实施方补齐失效或合同指定的路径**:
385
327
  ```
386
328
  start → aiRecognize → confirm → finish
387
329
  ```
@@ -411,11 +353,11 @@ curl -s http://localhost:{port}{context-path}/actuator/health | grep UP
411
353
  #### 门禁 2:启动门禁
412
354
  - **执行**:按构建工具命令矩阵正确启动应用
413
355
  - **通过标准**:
414
- 1. 进程是新启动的(非旧进程)——通过进程验证确认
356
+ 1. 运行实例匹配当前待测构建、配置与 owner——通过指纹和证据确认
415
357
  2. 健康检查返回 UP:`curl http://localhost:{port}{context-path}/actuator/health`
416
- 3. 日志中出现本次启动时间戳
358
+ 3. 日志与本次验证的实例/构建身份一致
417
359
  - **验证人**:Worker 执行并报告 PID,Leader 独立验证
418
- - **禁止**:看到端口监听就报告 UP,必须验证是新进程
360
+ - **禁止**:看到端口监听就报告 UP,必须验证实例身份与当前待测构建一致
419
361
 
420
362
  #### 门禁 3:接口测试门禁
421
363
  - **执行**:按 tests.md 逐个执行 curl 命令
@@ -436,26 +378,26 @@ curl -s http://localhost:{port}{context-path}/actuator/health | grep UP
436
378
  - **验证人**:Worker + Leader 都必须检查
437
379
 
438
380
  #### 门禁 6:代码评审门禁
439
- - **执行**:使用 `code-review-java` skill
381
+ - **执行**:读取 [统一五维 Reviewer 清单](reviewer-checklist.md),通过 `superflow-verify`
440
382
  - **通过标准**:无 CRITICAL / HIGH 级别问题
441
383
  - **验证人**:Reviewer 或 Leader
442
384
 
443
385
  #### 门禁 7:全链路回归门禁
444
386
  - **执行**:按 tests.md 的 end-to-end 场景完整执行一遍
445
387
  - **通过标准**:全流程通过,无异常
446
- - **验证人**:Leader 必须亲自执行
388
+ - **验证人**:实施方执行,Leader 独立核验原始结果
447
389
 
448
390
  #### 门禁未通过的处理
449
391
 
450
392
  1. **Worker 执行时门禁未通过**:
451
393
  - 不得报告任务完成
452
- - 必须修复问题并重新执行全部门禁
394
+ - 必须修复问题后重跑受影响、证据失效或合同指定的门禁,核验其余历史证据仍适用
453
395
  - 若无法修复,立即上报 Leader
454
396
 
455
397
  2. **Leader 验证时门禁未通过**:
456
398
  - 标记 Worker 任务为"未完成"
457
399
  - 要求 Worker 重新执行
458
- - 连续 2 次未通过,Leader 亲自介入修复
400
+ - 连续 2 次未通过,Leader 汇总根因与 finding,由实施方修复
459
401
 
460
402
  ---
461
403
 
@@ -513,7 +455,7 @@ curl -s http://localhost:{port}{context-path}/actuator/health | grep UP
513
455
  - 测试范围: tests.md 中 Bug 5 的全部用例
514
456
  - 应用状态: Worker 已启动,PID: 12345,健康检查: UP
515
457
  - 测试要求:
516
- 1. 独立执行全部用例,不参考 Worker 的自测结果
458
+ 1. 独立核验全部必测用例的源码与原始证据,不转述 Worker 结论;仅重跑失效或合同指定路径
517
459
  2. 覆盖接口测试、数据库验证、日志检查
518
460
  3. 如实报告失败,不替 Worker 找理由
519
461
  - 报告对象: 直接回复 Leader,不发给 Worker
@@ -543,27 +485,27 @@ curl -s http://localhost:{port}{context-path}/actuator/health | grep UP
543
485
 
544
486
  1. **禁止编译成功就交付**
545
487
  - ❌ 错误:"代码已修改,编译通过,任务完成"
546
- - ✅ 正确:"代码已修改,编译通过,应用已启动,独立 Tester 验证通过,任务完成"
488
+ - ✅ 正确:"代码已修改,编译通过,冻结的全部适用信号已有原始证据,独立核验通过,任务完成"
547
489
 
548
490
  2. **禁止 Worker 自测自报"完成"**
549
491
  - ❌ 错误:Worker 自己测自己报"测试通过,任务完成"
550
492
  - ✅ 正确:Worker 只报告"开发完成,应用已启动",等待独立 Tester 验证
551
493
 
552
- 3. **禁止 Tester 参考 Worker 的自测结果**
494
+ 3. **禁止 Tester 只转述 Worker 的自测结论**
553
495
  - ❌ 错误:Tester 看了 Worker 的报告后"差不多就行"
554
- - ✅ 正确:Tester 独立从头执行全部用例,不参考 Worker 报告
496
+ - ✅ 正确:Tester 独立检查原始证据与源码适用性,失效或合同指定路径由实施方重跑
555
497
 
556
498
  4. **禁止复用旧进程测试新代码**
557
499
  - ❌ 错误:端口已有监听,直接 curl 测试
558
- - ✅ 正确:先停止旧进程,重新编译启动,确认是新进程后再测试
500
+ - ✅ 正确:先核验实例与待测构建/配置一致;需加载新代码时通过 owner 清理入口重启再验证
559
501
 
560
- 5. **禁止仅做代码层面验证**
502
+ 5. **禁止仅做代码层面验证来关闭必测真实入口**
561
503
  - ❌ 错误:grep 代码确认修复逻辑正确,未实际调接口
562
- - ✅ 正确:必须实际调接口验证运行时行为
504
+ - ✅ 正确:必须按冻结用例实际驱动所需入口验证运行时行为;纯函数执行其测试 seam
563
505
 
564
506
  6. **禁止信任 Worker/Tester 报告而不自己验证**
565
507
  - ❌ 错误:Worker 说"测试通过"或 Tester 说"都过了",Leader 直接相信
566
- - ✅ 正确:Leader 必须独立执行关键验证(至少抽查 30% 的测试用例)
508
+ - ✅ 正确:Leader 必须按风险独立核验关键用例原始证据与源码,必要时要求实施方重跑
567
509
 
568
510
  7. **禁止跳过 clean 直接编译**
569
511
  - ❌ 错误:`mvn compile`(无 clean)
@@ -1,5 +1,9 @@
1
1
  # 质量门检查清单
2
2
 
3
+ 按 [test-guide.md](test-guide.md)核对已冻结的验证信号与适用依据。必测项缺环境保持
4
+ 阻塞;不适用项不得用来删减冻结门禁。健康实例匹配当前构建时复用,独立核验原始证据,
5
+ 由实施方重跑失效或合同指定路径。
6
+
3
7
  **执行以下 checklist**,分为文档交付阶段(Stage 7)和实现交付阶段(分批验收)。
4
8
 
5
9
  ---
@@ -99,16 +103,16 @@
99
103
 
100
104
  ## 第二阶段:实现交付质量门(每批验收)
101
105
 
102
- 每批实现完成后,必须执行以下门禁,**全部通过才能开始下一批**。
106
+ 每批实现完成后,必须执行冻结的全部适用门禁,**全部通过才能开始下一批**。
103
107
 
104
108
  ### 批次通用门禁
105
109
 
106
110
  | # | 门禁 | 执行方式 | 通过标准 | 验证人 |
107
111
  | --- | -------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
108
112
  | 1 | 编译 | `mvn/gradle clean compile` | BUILD SUCCESS | Worker |
109
- | 2 | 启动 | 正确命令启动 + 进程验证 | 新进程、健康检查 UP | Worker |
113
+ | 2 | 启动 | 正确命令启动 + 进程验证 | 当前待测构建/配置与 owner 指纹匹配、健康检查 UP | Worker |
110
114
  | 3 | 范围合规 | `git diff --name-only` | 只修改了 prompt 允许范围内的文件 | Worker + Reviewer |
111
- | 4 | 代码评审 | `code-review-java` / reviewer-checklist | 无 HIGH+ 问题,评审清单全部通过 | Reviewer |
115
+ | 4 | 代码评审 | `superflow-verify` / 统一五维 reviewer-checklist | 无 HIGH+ 问题,评审清单全部通过 | Reviewer |
112
116
  | 5 | 接口测试 | curl 调接口 | 本批用例全部断言通过 | Tester |
113
117
  | 6 | 数据库 | mysql 查询 | 数据状态符合预期 | Tester |
114
118
  | 7 | 日志 | grep ERROR | 无 ERROR,关键日志出现 | Tester |
@@ -156,7 +160,7 @@
156
160
  ### 结果处理
157
161
 
158
162
  - **全部通过** → 标记本批完成,可开始下一批
159
- - **任一未通过** → 停止,修复后重新执行全部门禁,不得进入下一批
163
+ - **任一未通过** → 停止,修复后重跑受影响、失效或合同指定门禁,并核验其余有效证据,不得进入下一批
160
164
  - **连续 2 次未通过** → Leader 亲自介入,或拆解为更小的子批次
161
165
 
162
166
  ---