@rowansenne/workflow-run 0.36.0 → 0.37.0
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.
- package/CHANGELOG.md +16 -1
- package/dev/SKILL.md.tpl +11 -11
- package/dev/references/bug.md +3 -3
- package/dev/references/clarify.md +2 -2
- package/dev/references/delivery-template.md +1 -1
- package/dev/references/delivery.md +5 -5
- package/dev/references/implementation.md +1 -1
- package/dev/references/planning.md +6 -6
- package/dev/references/preflight.md +1 -1
- package/docs/architecture.html +4 -4
- package/docs/team-guide.md +2 -2
- package/docs/workflows.md +3 -3
- package/package.json +1 -1
- package/project-review/SKILL.md.tpl +4 -4
- package/project-review/references/diff-strategy.md +4 -4
- package/project-review/references/report.md.tpl +1 -1
- package/project-review/references/reporting.md +2 -2
- package/project-review/references/review-method.md +1 -1
- package/project-review/references/verification.md +6 -5
- package/workflow/SKILL.md.tpl +2 -2
- package/workflow/core/review-handoff.mjs +4 -1
- package/workflow/lib/artifact-finalize.mjs +5 -1
- package/workflow/lib/document-review.mjs +16 -7
- package/workflow/lib/run-gates.mjs +27 -2
- package/workflow/lib/runs.mjs +27 -4
- package/workflow/references/execution.md +25 -17
- package/workflow/references/requirements.md +1 -1
- package/workflow/references/runs.md +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,20 @@
|
|
|
4
4
|
|
|
5
5
|
## [Unreleased]
|
|
6
6
|
|
|
7
|
+
## [0.37.0] - 2026-11-20
|
|
8
|
+
|
|
9
|
+
### 变更
|
|
10
|
+
|
|
11
|
+
- 功能开发在 F3 发布正式 `requirement.md` 后等待用户确认。确认绑定需求版本,确认后才进入 F4 起草方案。
|
|
12
|
+
- 需求、方案、代码及适用的复审、分角度查找和发现复核,由用户选择子 agent 审查、当前 agent 审查或跳过。跳过代码审查时记录未审范围,交付仍需明确确认。
|
|
13
|
+
- F6 每轮验证完成后等待用户确认,再进入 F7。用户要求调整代码或方案时,完成 F5 返工后先等待确认,再重新验证。
|
|
14
|
+
|
|
15
|
+
## [0.36.1] - 2026-11-18
|
|
16
|
+
|
|
17
|
+
### 优化
|
|
18
|
+
|
|
19
|
+
- `/dev` 的 M / L 需求与方案先讨论草稿,用户确认后再发起适用的独立审核。复审聚焦变更、待关闭的阻塞项和受影响的验收项。可选建议不阻塞收尾,已有答复覆盖的决定直接用于登记当前版本的确认。
|
|
20
|
+
|
|
7
21
|
## [0.36.0] - 2026-11-17
|
|
8
22
|
|
|
9
23
|
### 新增
|
|
@@ -484,7 +498,8 @@
|
|
|
484
498
|
- 安装器改为单一 Node 实现,`init-skills.sh` / `init-skills.ps1` 只是薄封装。
|
|
485
499
|
- `code-review` 改名为 `project-review`,升级时自动清理旧名。
|
|
486
500
|
|
|
487
|
-
[Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.
|
|
501
|
+
[Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.37.0...HEAD
|
|
502
|
+
[0.37.0]: https://github.com/guilianerde/skills-init/compare/v0.36.1...v0.37.0
|
|
488
503
|
[0.36.0]: https://github.com/guilianerde/skills-init/compare/v0.35.0...v0.36.0
|
|
489
504
|
[0.26.0]: https://github.com/guilianerde/skills-init/compare/v0.25.0...v0.26.0
|
|
490
505
|
[0.21.0]: https://github.com/guilianerde/skills-init/compare/v0.20.0...v0.21.0
|
package/dev/SKILL.md.tpl
CHANGED
|
@@ -21,12 +21,12 @@ description: "Explicitly requested dev workflow for feature development or bug f
|
|
|
21
21
|
- 生成澄清清单、需求、方案和交付说明时,按 `<skills>/workflow/references/templates.md`「文档模板的两部分」读取生效模板。遵守要求区,只用内容区生成正文。无标记的模板沿用旧格式,边界有误时先修复。
|
|
22
22
|
- 先确定工作分支、已有改动的归属与需求名;切分支重新查询绑定,不替用户丢弃已有改动。
|
|
23
23
|
- 规模由 agent 判定并说明,不询问规模确认;M / L 的需求理解和方案须用户确认后再实现,权限 / 资金至少按 M。
|
|
24
|
-
-
|
|
25
|
-
- F2 先落偏业务场景的 clarification.md,供用户找产品核对;逐轮更新原问题状态、追加新问题和反馈。业务明确并完成现状调研后,再进入 F3
|
|
24
|
+
- M / L 先和用户讨论需求与方案草稿,收到明确反馈直接改稿。适用的审查按 [审查方式选择](../workflow/references/execution.md#审查方式选择) 和 [文档审查流程](../workflow/references/execution.md#需求与方案审查) 执行。
|
|
25
|
+
- F2 先落偏业务场景的 clarification.md,供用户找产品核对;逐轮更新原问题状态、追加新问题和反馈。业务明确并完成现状调研后,再进入 F3 澄清技术约束;完整流程先落盘 requirement.md,再让用户确认正式版本,之后才进入 F4。
|
|
26
26
|
- S 快速通道须用户明确同意,且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更,且没有 F2 / F3 已确认的业务决定、本次未发布正式清单且未创建完整流程运行;已有清单或运行沿用完整流程,具体资格见 F4。
|
|
27
27
|
- 快速通道仍编译、测试、当前会话审查,但不 bind、不建运行、不落需求 / 方案 / 审查 / 交付文档;超限或用户要求落盘先停,回 F3(bug 回 B3)补需求文档,再进入方案。
|
|
28
|
-
-
|
|
29
|
-
-
|
|
28
|
+
- 完整流程先让用户选子 agent 审查、当前 agent 审查或跳过。每轮用 `review.md` 记录结果或跳过决定,交给用户后等待明确选择修复或交付。
|
|
29
|
+
- 功能开发每轮 F6 验证后交结果并停下,用户确认才进入 F7。用户要求修改代码或方案时,完成 F5 返工后先停,用户确认后才重新走 F6。复审方式和交付另由用户选择;严重遗留风险须说明并取得明确接受,不能把一般的“交付”当作接受风险。
|
|
30
30
|
- 交付选择不授权提交、推送、发布或知识写入;没有值得沉淀的知识不询问,有则先取得授权。
|
|
31
31
|
|
|
32
32
|
## Step 0 — 前置检查(两种模式共用)
|
|
@@ -54,11 +54,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
|
|
|
54
54
|
|
|
55
55
|
### F3 — 需求澄清(偏技术约束)
|
|
56
56
|
|
|
57
|
-
读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2
|
|
57
|
+
读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2 更新清单找产品确认。完整流程完成澄清和适用的审查后,先收尾 requirement.md,发正式文档链接及版本并等待用户明确确认;确认前停在 F3,确认后才进入 F4 起草方案。
|
|
58
58
|
|
|
59
59
|
### F4 — 方案(落盘只看是否快速通道,写法按规模)
|
|
60
60
|
|
|
61
|
-
读 [planning.md 的 F4](references/planning.md),复用 F3
|
|
61
|
+
读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求起草方案,按文档门禁先确认、再完成适用的审查,用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;涉及 HTTP 接口或接口行为变化时列出接口、AC、测试场景及命令 / 环境。S / M 简版、L 完整版,M / L 在收尾后记录当前版本的 approval,再进入实现。
|
|
62
62
|
|
|
63
63
|
### F5 — 实现
|
|
64
64
|
|
|
@@ -66,15 +66,15 @@ description: "Explicitly requested dev workflow for feature development or bug f
|
|
|
66
66
|
|
|
67
67
|
### F6 — 验证
|
|
68
68
|
|
|
69
|
-
读 [implementation.md 的 F6](references/implementation.md);HTTP 接口或接口行为有变化时,沿用既有框架补充并执行接口层测试,覆盖正常请求、适用的参数错误和权限场景,断言状态码与响应。完整流程执行前用 `run.mjs snapshot --id <id>` 取快照、执行后 save validation;两种通道都执行相关测试、`profile.test` 与 lint,记录“验收项 → 测试或操作 →
|
|
69
|
+
读 [implementation.md 的 F6](references/implementation.md);HTTP 接口或接口行为有变化时,沿用既有框架补充并执行接口层测试,覆盖正常请求、适用的参数错误和权限场景,断言状态码与响应。完整流程执行前用 `run.mjs snapshot --id <id>` 取快照、执行后 save validation;两种通道都执行相关测试、`profile.test` 与 lint,记录“验收项 → 测试或操作 → 结果”,已有失败与未验证项如实保留;缺接口测试环境时附可执行请求与预期结果。交付验证摘要后停在 F6,等用户确认才进入 F7。用户要求改代码时回 F5,改方案时先回 F4、再到 F5;F5 返工完成后交变更摘要并等待,只有用户确认向下推进才开始新一轮 F6。S 快速通道在对话中执行相同停点。
|
|
70
70
|
|
|
71
71
|
### F7 — 审查、报告与用户选择
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
用户确认本轮 F6 验证结果后,先读 [delivery.md 的 F7](references/delivery.md),完整流程用 `review-handoff.mjs --id <id>` 生成交接材料,按 project-review 第 1~7 步审查;方式由用户明确选择;跳过则登记未审查。审查者提供草稿与结构化结果,主 agent 用 `artifact.mjs finalize --kind review` 收尾,交用户、等修复或交付选择;内部审查不另起运行、不单独沉淀或记反馈。快速通道只在当前会话审查。
|
|
74
74
|
|
|
75
75
|
### F8 — 交付
|
|
76
76
|
|
|
77
|
-
读 [delivery.md 的 F8](references/delivery.md)
|
|
77
|
+
读 [delivery.md 的 F8](references/delivery.md);完整流程记录绑定本轮代码和审查记录的交付选择后,用 `artifact.mjs finalize --kind delivery` 收尾 `delivery.md` 并汇总,快速通道仅对话交付。反馈用 `feedback.mjs add`;沉淀分类用 `resolve.mjs category dev`,详细授权、元信息与后续操作按该文执行。
|
|
78
78
|
|
|
79
79
|
## 缺陷修复流程(`--bug`)
|
|
80
80
|
|
|
@@ -88,11 +88,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
|
|
|
88
88
|
|
|
89
89
|
### B3 — 定位根因
|
|
90
90
|
|
|
91
|
-
读 [bug.md 的 B3](references/bug.md)
|
|
91
|
+
读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程先确认需求草稿,再完成适用的审查、收尾 requirement.md 并完成 B3,进入修复方案。
|
|
92
92
|
|
|
93
93
|
### B4 — 修复与验证
|
|
94
94
|
|
|
95
|
-
先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4
|
|
95
|
+
先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,按文档门禁先确认、再完成适用的审查,用 `artifact.mjs finalize --kind plan` 收尾。M / L 收尾后记录当前版本的 approval,再记录 implement 并修复,复现测试由红变绿。
|
|
96
96
|
|
|
97
97
|
### B5 — 审查与交付
|
|
98
98
|
|
package/dev/references/bug.md
CHANGED
|
@@ -18,17 +18,17 @@
|
|
|
18
18
|
- 区分根因与症状:只在出错表象处加判空 / try-catch 不算修复,除非能说明那里就是根因。
|
|
19
19
|
- 检查同一根因是否在其他调用方同样存在。
|
|
20
20
|
- 预期业务行为还需产品确认时,按 clarify.md 的清单规则在 B3 初判规模、bind、start,逐轮发布同目录的 clarification.md 并保存等待反馈;需求明确后沿用该运行收尾需求文档。
|
|
21
|
-
- 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成草稿,按 `clarify.md` 的 F3
|
|
21
|
+
- 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成草稿,按 `clarify.md` 的 F3 先讨论并确认草稿,再完成适用的审查,用 `artifact.mjs finalize --kind requirement` 收尾并标 B3 completed,再进 B4。根因证据作事实依据,修复方式留在 plan.md;已有文档先核对后在草稿更新,不自动覆盖原需求。
|
|
22
22
|
|
|
23
23
|
### B4 — 修复与验证
|
|
24
24
|
|
|
25
25
|
- 复用 B3 收尾时按 F4 标准判定的规模和通道,不重复询问;范围变化时重新判定。快速通道退出时先回 B3 补需求文档,再补方案。
|
|
26
|
-
- **完整流程先把修复方案追加进 `plan.md`**:沿用 B3 已绑定的需求与 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支、本次日期以及 requirement.md 的 cite / 版本。没有方案则按模板创建草稿,只填适用节。按 `<skills>/workflow/references/execution.md`
|
|
26
|
+
- **完整流程先把修复方案追加进 `plan.md`**:沿用 B3 已绑定的需求与 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支、本次日期以及 requirement.md 的 cite / 版本。没有方案则按模板创建草稿,只填适用节。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」先讨论草稿,M / L 用户确认后完成适用的审查,再用 `artifact.mjs finalize --kind plan` 自检、归档旧版、发布并更新索引,不直接覆盖正式文件;输出的 previous 用于历史对照。运行 `artifacts.mjs --branch <当前修复分支>` 确认 latest.plan。M / L 收尾后记录当前版本的 approval,再 save implement: true;S 省 approval,仍须 implement。具体 JSON 和证据协议见 `<skills>/workflow/references/execution.md`。规模变化时说明依据、按新规模继续。
|
|
27
27
|
- 做能消除根因的**最小改动**;B2 的测试由红变绿,相关已有测试保持通过(运行方式同 F6)。
|
|
28
28
|
- 如果历史脏数据需要修正,写成 SQL 脚本交给用户,不直接执行。
|
|
29
29
|
|
|
30
30
|
### B5 — 审查与交付
|
|
31
31
|
|
|
32
|
-
同 F7、F8
|
|
32
|
+
同 F7、F8:先让用户选择子 agent 审查、当前 agent 审查或跳过,落盘 `review.md` 记录本轮结果,再等待用户选择修复或交付;修复后验证,并重新询问本轮复审与交付选择,完整流程仅在用户选择交付后生成 `delivery.md`(「类型」写缺陷修复)。快速通道同样适用于缺陷修复:S 规模、用户在 B3 收尾时已同意走快速通道,不涉及配置 / SQL / 对外接口 / 表结构 / 权限 / 资金,且同类风险排查没有发现其他调用方受影响时,不绑定需求、不落任何产物文件,审查在当前会话做,交付在对话里一次完成并注明「DocNexus:未询问(快速通道不问沉淀)」;根因(证据链、修复方式)必须在对话里写清楚。完整交付时,交付说明的「根因」节必须写:证据链、修复方式、为什么这样修、同类风险排查结果;DocNexus 沉淀时根因是首要候选。
|
|
33
33
|
|
|
34
34
|
B4 的方案、实现进入与验证证据分开登记:方案 finalize 后,M / L 记录 approval,再 save implement: true;验证用执行前 snapshot 与实际 checks,B4 最后才标 completed。B5 按 execution.md 的交接、报告收尾、交付选择和交付收尾执行,报告完成不代表 B5 已完成。
|
|
@@ -35,7 +35,7 @@ F1 形成初版需求理解后,在 F2、进入 F3 之前先输出清单,不
|
|
|
35
35
|
- 依赖前置答案的问题也记录,注明「待 Qx 确认后讨论」。每轮突出当前能确认的问题,控制在 7 个以内;用户说「按推荐来」只确认本轮已经给出的推荐。
|
|
36
36
|
- 用户带回答复或新版 PRD 后,恢复同一运行,从正式清单复制 tmp 草稿,更新原问题的答复和状态、追加新问题;反馈记录按轮追加。产品改口时保留原答复与变更原因。
|
|
37
37
|
- 每轮汇总「已确认 / 仍待确认 / 本轮新增」,给出 PRD 的业务规则、场景、范围和验收调整建议;只在用户要求修改 PRD 时改原文。
|
|
38
|
-
- 更新后再次 finalize,旧版自动归档,输出新版链接。内容变化会撤销本轮旧需求和方案凭据及下游确认,保留旧文件;后续须重新收尾需求与方案,M / L
|
|
38
|
+
- 更新后再次 finalize,旧版自动归档,输出新版链接。内容变化会撤销本轮旧需求和方案凭据及下游确认,保留旧文件;后续须重新收尾需求与方案,M / L 按文档审查流程核对并记录当前版本的方案确认。仍有未定业务项时继续留在 F2;「继续」或已修改 PRD 不代表未回答的问题自动确认。
|
|
39
39
|
- 新会话明确继续时,读清单、最新 PRD 和运行 context,从未解决项继续,不重问仍有效的已确认项。
|
|
40
40
|
|
|
41
41
|
业务项均已回答或由用户明确移出范围后,将清单标为「业务已明确」并 finalize。结合核对后的场景完成 F2 的代码与数据调研,再 save F2 completed、进入 F3。这里不提前生成 requirement.md,也不把业务反馈视为技术约束已确认。
|
|
@@ -56,6 +56,6 @@ F1 形成初版需求理解后,在 F2、进入 F3 之前先输出清单,不
|
|
|
56
56
|
|
|
57
57
|
技术调研发现新的业务决定或场景冲突时,回 F2 更新业务清单并等待产品确认;确认后重查受影响的技术事实,再回 F3。已确认且不受影响的场景不重复问。bug 在 B3 内更新清单后继续技术澄清。
|
|
58
58
|
|
|
59
|
-
业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start)。按 `<skills>/workflow/references/execution.md`
|
|
59
|
+
业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start)。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」依据已澄清的决定起草,直接落实明确反馈;M / L 请用户选择审查方式。用 `artifact.mjs finalize --kind requirement` 收尾。功能开发发出正式 requirement.md 链接及版本,明确询问是否确认;等待时停在 F3,确认后记录当前版本并进入 F4 起草方案。缺陷修复完成 B3 后按 bug.md 进入 B4。
|
|
60
60
|
|
|
61
61
|
requirement.md 是最终需求事实来源,引用清单 cite 与版本,只汇总有效场景、决定与约束;清单保留业务往返核对过程,plan.md 保存实现设计。值得长期记住的规则与取舍在交付时作为 DocNexus 沉淀候选。
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
> 类型:{{功能开发 / 缺陷修复}} | 规模:{{S / M / L}} | 日期:{{YYYY-MM-DD}}
|
|
8
8
|
> 对比分支:`{{当前分支}}` ←→ `{{主分支}}`
|
|
9
|
-
> 参考产物:{{
|
|
9
|
+
> 参考产物:{{最新审查结果或跳过记录路径;方案路径(非快速通道都有)}}
|
|
10
10
|
> DocNexus:{{尚未发起询问写「未询问」;沉淀后写 workflow-run/docnexus/library/<path>;没有值得沉淀的内容写「无需沉淀」,已询问但未成功入库(含用户拒绝)写「未沉淀」}}
|
|
11
11
|
|
|
12
12
|
## 结果 *
|
|
@@ -7,16 +7,16 @@
|
|
|
7
7
|
**S 快速通道不走本节**:在当前会话按 project-review 的标准清单自查,不写方案、不落 `review.md`、不绑定需求、不交报告等选择;审查结论写进 F8 的对话交付。碰到快速通道的退出条件时,再按下面的完整流程走。
|
|
8
8
|
|
|
9
9
|
- 按 `project-review` skill 审本次改动,用户未指定深度时按 project-review 的「标准」审查。范围用 `node <skills>/workflow/scripts/review-scope.mjs --base <main_branch>`:分支已有的提交、未提交的改动和未跟踪的新文件一起列出。Step 0 确认不属于本需求的文件用 `--exclude <文件,文件>` 排除,它们不计入本次结论(见 Step 0「工作区状态与工作分支」);之后 project-review 的 `rules`、`locate.mjs` 都带同样的参数。
|
|
10
|
-
-
|
|
11
|
-
-
|
|
10
|
+
- **先取得用户对本轮审查方式的明确选择**,按 [审查方式选择](../../workflow/references/execution.md#审查方式选择) 等待答复。选子 agent 时派一个未参与本轮实现的子 agent,执行 project-review 的第 1~7 步(含复核、报告草稿和结构化结果)。交接材料用 `review-handoff.mjs --id <id>` 自动生成,参数与结果结构见 `<skills>/workflow/references/execution.md`「自动审查交接」;不要传实现者的自审结论或预设问题,让它自己读当前代码判断。审查期间主 agent 不再修改被审代码。子 agent 只审查、写 tmp 草稿和结果 JSON,主 agent 负责 finalize、更新同一运行;不修代码、不生成交付说明、不提交。
|
|
11
|
+
- **选当前 agent 审查**:按 project-review 第 1~7 步执行,报告如实署名。**选跳过审查**:只用 `review.md` 记录用户选择、代码版本和未审范围,结论写「用户选择跳过审查,未审查」;交付说明也注明。两种都等用户明确选择交付。
|
|
12
12
|
- **每轮必须落盘 `review.md`**:按 Artifact Location 先绑定需求,再按 project-review 第 7 步生成草稿与结构化结果,由主 agent 用 `artifact.mjs finalize --kind review` 统一自检、落盘和登记证据。问题表、影响面、未覆盖项都要保留;没有发现也生成报告。只跳过 project-review 第 8 步沉淀与第 9 步反馈,沉淀和反馈留给 dev F8 统一处理;报告的元信息固定写「未询问(由 dev 交付统一处理)」。F8 只更新交付说明的沉淀状态,不将内部审查报告同步为交付的沉淀结果,避免把一次询问或沉淀重复计数。本轮尚无交付说明,不能把缺少 `delivery.md` 当成漏项;旧交付说明只能作为历史参考,当前需求与验证以本次交接为准。
|
|
13
13
|
- **先交报告,再等选择**:主 agent 读取报告,将报告内容与路径交给用户,明确询问「修复报告中的问题,还是按当前结果交付?」并等待本轮明确答复。没有发现时也要等用户选择交付;答复含糊或未答复时留在 F7。此时**不创建、不覆盖 `delivery.md`,不提前进入提交、PR 或沉淀环节**。
|
|
14
|
-
- **修复问题**:按用户选定的问题回到 F5
|
|
15
|
-
- **交付**:按 execution.md 保存 decision
|
|
14
|
+
- **修复问题**:按用户选定的问题回到 F5 修复(方案变化先回 F4)。返工完成后等用户确认进入 F6,验证完再次等确认才回 F7 询问本轮复审方式;选子 agent 时由未参与修复的 agent 复审;更新 `review.md` 并归档旧版;执行复审时逐条核对「已修复 / 仍存在 / 不再适用」。再次交报告、等待选择,不因已修复就自动交付。用户自己修复后核对实际改动,按同一 F5 → F6 → F7 确认流程推进。缺陷修复按 B4 → B5 执行。
|
|
15
|
+
- **交付**:按 execution.md 保存 decision,绑定报告版本与代码摘要;确认报告对应当前代码;审查后代码有变动就先按返工和验证确认规则重新推进。仍有已复核的 CRITICAL / HIGH 时,明确建议先修复,说明具体风险并让用户确认是否仍按当前结果交付;不能将一般的「交付」视为接受未说明的严重风险。用户明确接受遗留风险后才进 F8,如实记录遗留问题与未验证项,不得把带问题交付写成「审查通过」或「建议合并」。MEDIUM / LOW 的处理结果也写进交付说明(快速通道写在对话里)。
|
|
16
16
|
|
|
17
17
|
### F8 — 交付
|
|
18
18
|
|
|
19
|
-
**完整流程的进入条件**:F7
|
|
19
|
+
**完整流程的进入条件**:F7 的审查结果或跳过记录已完成并交给用户,且用户明确选择「交付」。修复后仍需完成验证与复审、重新取得交付选择;此前不创建或更新 `delivery.md`。选择交付不等于授权提交、推送、发布或沉淀。S 快速通道不经过这个条件、也不生成报告,见下面的「快速通道交付」。
|
|
20
20
|
|
|
21
21
|
独立文档仓库中 F7 的报告提交提示延后到本步:完整流程交付完成后运行 `requirement.mjs pending`,按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」询问;不让审查环节提前询问或执行提交。
|
|
22
22
|
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
|
|
16
16
|
### F6 — 验证
|
|
17
17
|
|
|
18
|
-
完整流程按 `<skills>/workflow/references/execution.md`「验证证据」,在执行前 snapshot,执行后 save validation
|
|
18
|
+
完整流程按 `<skills>/workflow/references/execution.md`「验证证据」,在执行前 snapshot,执行后 save validation;只有代码快照仍一致,结果才能登记。功能开发完成 F6 后,把构建、测试、验收以及未验证项交给用户,停下等待明确确认,再进入 F7。用户要改代码时回 F5;改方案时先回 F4,按方案规则确认后到 F5。返工只做到 F5,交变更摘要后停下,用户确认后才重新做 F6;新一轮验证结束后再次等待确认。F5 原有的实现检查照常执行。S 快速通道在对话中执行这些停点及构建、测试和验收验证。缺陷修复完成 B4 后进入 B5。
|
|
19
19
|
|
|
20
20
|
- 按验收标准补充或更新单元测试 / 集成测试,测试放在项目既有测试目录、沿用既有测试框架。
|
|
21
21
|
- **HTTP 接口测试按改动触发**:新增 / 修改 HTTP 接口,或改动影响接口的参数校验、鉴权、状态码、响应结构及业务行为时,补充或更新对应接口测试并执行。内部重构未改变接口行为、已有接口测试覆盖充分时,运行现有测试即可,不强制新增重复用例。
|
|
@@ -24,11 +24,11 @@
|
|
|
24
24
|
|---|---|
|
|
25
25
|
| S 规模且没有未定业务或技术决定 | 写明理解与已查证约束,不强行提问;按 F4 标准判规模与通道 |
|
|
26
26
|
| 只有一两个技术取舍 | 给推荐和依据,能一轮确认就一轮结束 |
|
|
27
|
-
| M / L 规模,或用户要求先把需求问清楚 | 逐轮确认约束,汇总需求、AC
|
|
27
|
+
| M / L 规模,或用户要求先把需求问清楚 | 逐轮确认约束,汇总需求、AC、不做什么与决定,发布 requirement.md 后等用户确认正式版本再进 F4 |
|
|
28
28
|
|
|
29
|
-
**F3 的正式产物**:业务与技术约束均明确后,沿用已有绑定和运行、复核规模;没有清单时,完整流程在此 bind、start(stage F3,仅补记实际完成的 Step0、F1、F2)。用 `resolve.mjs template dev requirement-template.md` 读取模板,将目标、范围、AC、当前有效业务决定与必要技术约束写成草稿,在依据中引用业务清单 cite 与版本。按 `clarify.md` 的 F3
|
|
29
|
+
**F3 的正式产物**:业务与技术约束均明确后,沿用已有绑定和运行、复核规模;没有清单时,完整流程在此 bind、start(stage F3,仅补记实际完成的 Step0、F1、F2)。用 `resolve.mjs template dev requirement-template.md` 读取模板,将目标、范围、AC、当前有效业务决定与必要技术约束写成草稿,在依据中引用业务清单 cite 与版本。按 `clarify.md` 的 F3 处理草稿中仍需澄清的决定,再按用户选择完成适用的审查,通过 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 后发正式文档链接及版本,保存 waiting_user。取得用户对该版本的明确确认后,才登记 requirement_approval 并进入 F4。不因清单发布或产品给了业务答复就跳过技术澄清。
|
|
30
30
|
|
|
31
|
-
requirement.md 是需求事实来源,context 只保存续接摘要。业务变化先回 F2 更新清单、复核现状,再到 F3 更新需求文档;仅技术约束变化回 F3;只调整实现设计则更新 F4
|
|
31
|
+
requirement.md 是需求事实来源,context 只保存续接摘要。业务变化先回 F2 更新清单、复核现状,再到 F3 更新需求文档;仅技术约束变化回 F3;只调整实现设计则更新 F4 的方案。需求重新收尾后,更新依赖它的方案,只确认受影响且尚未决定的取舍,再按当前版本登记确认和验证。历史需求不自动从旧 plan.md 拆出正文;恢复旧运行时先核实并补齐需求文档。
|
|
32
32
|
|
|
33
33
|
### F4 — 方案(落盘只看是否快速通道,写法按规模)
|
|
34
34
|
|
|
@@ -42,10 +42,10 @@ requirement.md 是需求事实来源,context 只保存续接摘要。业务变
|
|
|
42
42
|
|
|
43
43
|
**规模判定(S / M / L 都必做,不再询问用户)**:规模由你按上表判定,向用户说明判定的规模与依据(预计改动文件 / 模块、接口 / 数据 / 配置变化及风险)即可,**不询问、不等确认**,直接按该规模推进后续流程;用户主动提出不同意见时,按用户说的规模继续。用户调整范围或实现中发现规模变化时,说明变化依据,按新规模继续。规模判定属于流程选择,不属于业务决定,不影响 S 规模快速通道资格。
|
|
44
44
|
|
|
45
|
-
**需求绑定与方案依据**:完整流程已在 F3
|
|
45
|
+
**需求绑定与方案依据**:完整流程已在 F3 绑定并收尾 requirement.md,用户确认正式版本后本步沿用;方案头写需求文档的 cite 与版本,需求目标、范围和业务决定不复制到方案中维护。方案只解释如何实现,并用 AC 编号关联验证计划。S 快速通道不绑定。
|
|
46
46
|
|
|
47
|
-
**S 规模快速通道(问用户)**:本次已发布正式清单或已创建完整流程运行时,直接沿用完整流程,不再询问快速通道;后续规模降为 S 也不切换。判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F2 / F3 中确认过的业务决定,且本次尚未发布正式清单、尚未创建完整流程运行时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F3 需求 → F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,先回 F3(缺陷回 B3)补写并 finalize requirement.md,再到 F4 / B4 补方案;M / L 等用户确认方案后再继续,S
|
|
47
|
+
**S 规模快速通道(问用户)**:本次已发布正式清单或已创建完整流程运行时,直接沿用完整流程,不再询问快速通道;后续规模降为 S 也不切换。判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F2 / F3 中确认过的业务决定,且本次尚未发布正式清单、尚未创建完整流程运行时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F3 需求 → F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,先回 F3(缺陷回 B3)补写并 finalize requirement.md,再到 F4 / B4 补方案;M / L 等用户确认方案后再继续,S 按简版方案推进。功能开发在 F3 重新发布后先等用户确认正式需求文档。之后回 F5 完成实现、F6 验证、F7 询问审查方式并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
|
|
48
48
|
|
|
49
|
-
**方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path
|
|
49
|
+
**方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」先讨论草稿,M / L 用户确认草稿后,由用户选择本轮审查方式。用 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 收尾后 save 当前版本的 approval,再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
|
|
50
50
|
|
|
51
51
|
**HTTP 接口验证计划**:涉及新增 / 修改 HTTP 接口,或参数校验、鉴权、状态码、响应结构及接口业务行为变化时,在验证计划列出方法、路径、关联 AC 与待测场景:正常请求、参数错误(有入参约束时),以及适用的未登录 / 无权限场景。沿用现有框架,明确已有用例如何复用、哪些需要补充、执行命令和环境;F6 按计划编写并执行。纯内部重构且接口行为不变、已有覆盖充分时只列现有测试,不另建重复用例。缺陷修复在 B4 使用相同规则。
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
- 当前工作分支已绑定 → 直接用,不再问。
|
|
28
28
|
- 本次对话里用户(或 `/workflow` 入口)已经给过名字、只是还没绑定 → 直接用这个名字,不再问。
|
|
29
29
|
- 没绑定 → **现在就问用户这个需求叫什么**(默认值用输出的 `suggested_name`;用户说「按分支名」也行)。**用户给不出名字、或说不清这次要做什么时停在这里,不进入 F1**,已开始的改动保持原样,不替用户猜。名字在第一次落盘时按 Artifact Location bind;S 快速通道只问不 bind、不落盘。
|
|
30
|
-
4. **审查方式**:确认当前环境能否派独立子 agent(`resolve.mjs status`
|
|
30
|
+
4. **审查方式**:确认当前环境能否派独立子 agent(`resolve.mjs status` 探测不到这个能力)。在实际进入原可派子 agent 的审查点时,由用户选择方式;预检的能力判断只用于解释选项的可用性。
|
|
31
31
|
5. **基线**:动代码前运行一次 `profile.build`,再跑和本需求相关的测试(`profile.test_single` 或相关模块,不必全量),记下已经失败的测试和编译错误。之后只对新增的失败负责:已有失败不顺手修,写进交付说明「开工前已有的失败」。跑不了就记「未跑基线」和原因。
|
|
32
32
|
|
|
33
33
|
## 终端命令
|
package/docs/architecture.html
CHANGED
|
@@ -378,11 +378,11 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
|
|
|
378
378
|
<li><span class="code">Step 0</span><div class="name">前置检查</div><div class="what">读画像,先确定工作分支,再问清需求名(给不出就不开始)与工作区里已有的改动归谁,跑一次基线</div></li>
|
|
379
379
|
<li><span class="code">F1</span><div class="name">理解需求</div><div class="what">拉 PRD,召回以往的约定和坑,列初版验收标准</div></li>
|
|
380
380
|
<li class="gate"><span class="code">F2</span><div class="name">业务核对与调研</div><div class="what">先落业务场景清单,与产品逐轮核对;明确后结合场景调研代码与数据<br><span class="art">clarification.md</span></div></li>
|
|
381
|
-
<li class="gate"><span class="code">F3</span><div class="name">需求澄清</div><div class="what"
|
|
381
|
+
<li class="gate"><span class="code">F3</span><div class="name">需求澄清</div><div class="what">基于已确认场景澄清可行性、接口兼容、数据与权限等技术约束;先收尾需求文档,再请用户确认正式版本;确认后进入 F4<br><span class="art">requirement.md</span></div></li>
|
|
382
382
|
<li class="gate"><span class="code">F4</span><div class="name">方案</div><div class="what">需求明确后引用需求版本,写实现设计、实施和验证计划(S / M 简版);涉及 HTTP 改动时列接口验证场景,M / L 确认后实现<br><span class="art">plan.md</span></div></li>
|
|
383
383
|
<li><span class="code">F5</span><div class="name">实现</div><div class="what">贴合现有写法,不顺手重构;SQL 只写脚本不执行</div></li>
|
|
384
|
-
<li><span class="code">F6</span><div class="name">验证</div><div class="what">先相关测试再全量;HTTP 接口改动补接口层测试,覆盖正常、适用的参数错误与权限场景;绑定执行前快照,按 AC
|
|
385
|
-
<li class="gate"><span class="code">F7</span><div class="name">审查</div><div class="what"
|
|
384
|
+
<li class="gate"><span class="code">F6</span><div class="name">验证</div><div class="what">先相关测试再全量;HTTP 接口改动补接口层测试,覆盖正常、适用的参数错误与权限场景;绑定执行前快照,按 AC 记录结果,缺环境写未验证;交验证结果并等用户确认,再进 F7。返工时先停在 F5 等确认,再重新验证</div></li>
|
|
385
|
+
<li class="gate"><span class="code">F7</span><div class="name">审查</div><div class="what">用户选择子 agent 审查、当前 agent 审查或跳过;主 agent 将结果或跳过决定写入 review.md,再等用户选择修复或交付<br><span class="art">review.md</span></div></li>
|
|
386
386
|
<li class="gate"><span class="code">F8</span><div class="name">交付</div><div class="what">用户选择交付后才生成交付说明;提交、PR 先问,沉淀有值得记的内容才问<br><span class="art">delivery.md</span></div></li>
|
|
387
387
|
</ol>
|
|
388
388
|
</div>
|
|
@@ -427,7 +427,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
|
|
|
427
427
|
</div>
|
|
428
428
|
<div>
|
|
429
429
|
<h3>结论要有出处</h3>
|
|
430
|
-
<p
|
|
430
|
+
<p>关于现有代码的结论指向真实文件和行号;审查发现要写出触发条件,严重级别的发现按用户选择独立复核、自行复核或记为待确认。</p>
|
|
431
431
|
</div>
|
|
432
432
|
</div>
|
|
433
433
|
</section>
|
package/docs/team-guide.md
CHANGED
|
@@ -78,7 +78,7 @@ workflow-run/docs/requirements/<需求名>/<项目名>/
|
|
|
78
78
|
├── requirement.md # 需求文档(F3 / B3 收尾:目标、范围、AC 验收与澄清决定)
|
|
79
79
|
├── plan.md # 方案(dev,非快速通道都写;S / M 简版;缺陷修复追加修复方案节)
|
|
80
80
|
├── delivery.md # 交付说明(dev,完整流程审查后用户选择交付才写;S 快速通道不落盘)
|
|
81
|
-
├── review.md #
|
|
81
|
+
├── review.md # 审查报告(独立审查、自查或用户选择跳过的记录;S 快速通道不落盘);复审也写这个文件,上一版归档到 workflow-run/tmp/old-artifacts/
|
|
82
82
|
├── tech-doc.md # 技术方案
|
|
83
83
|
└── release-doc.md # 上线方案
|
|
84
84
|
```
|
|
@@ -89,7 +89,7 @@ workflow-run/docs/requirements/<需求名>/<项目名>/
|
|
|
89
89
|
* 正式文档先写 tmp 草稿,再用 `artifact.mjs finalize` 自检、归档旧版、发布并更新索引与运行证据,输出 path / cite;文件名固定、目录只留最新版。中断后用 resume 恢复,重复命令不会重复升版本;旧版在 tmp/old-artifacts/,不替用户删除,wiki 页面记录自动沿用。旧 path / sync 写入链已删除;只刷新派生索引时使用 `requirement.mjs reindex`,正文、版本和证据仍由 finalize 管理。
|
|
90
90
|
* 需求目录写在项目根的 `.ignore` 里,ripgrep 和 agent 的代码搜索会跳过它,产物多了不会污染搜索结果(找历史决策用 DocNexus)。git 不受影响,建议随代码提交。
|
|
91
91
|
|
|
92
|
-
完整 dev 的关键阶段由程序校验:M / L
|
|
92
|
+
完整 dev 的关键阶段由程序校验:F3 正式需求确认与 M / L 方案确认分别绑定具体版本,测试证据和审查报告绑定包含未提交改动的代码快照,交付选择绑定本轮报告。相关代码、基线或报告变化后需重新验证/审查和选择。独立审查交接由脚本从需求事实、范围与验证结果生成;需要产品核对清单时,在首版清单前创建运行、等待反馈时保存状态;快速通道仍不创建运行。协议见 [execution.md](../workflow/references/execution.md)。
|
|
93
93
|
|
|
94
94
|
**独立文档仓库(可选)**:不想让产物进代码仓库、或一个需求横跨多个服务时,装好 skills 后在项目根运行一条命令:
|
|
95
95
|
|
package/docs/workflows.md
CHANGED
|
@@ -115,10 +115,10 @@ node .agents/skills/workflow/scripts/resolve.mjs env --check # 逐个字段核
|
|
|
115
115
|
|
|
116
116
|
Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_invocation: false`;所有环境同时遵守 skill 入口规则与安装写入的项目说明。已由用户启动的同一 dev 任务可按当前阶段继续,无需每条消息重复命令;只要求分析或提交时仅处理该请求,不重启流程。升级 / 重装会更新规则,随后新建会话加载;其他宿主的原生调用策略取决于宿主支持,不能将配置校验等同于所有模型的行为保证。
|
|
117
117
|
|
|
118
|
-
* **功能开发**:开始前先确定工作分支,再确认需求名(给不出名字或说不清要做什么就不开始)→ 理解需求(可读 PRD、查 DocNexus 历史决策)→ F2 先出业务场景清单与产品核对、调研现有代码 → F3 技术澄清(基于已确认场景查证可行性与系统约束,必要取舍分轮给推荐;新业务问题回 F2;S 规模无未定决定时省提问)→ **规模判定(S / M / L 说明判定依据,不再询问确认)** →
|
|
118
|
+
* **功能开发**:开始前先确定工作分支,再确认需求名(给不出名字或说不清要做什么就不开始)→ 理解需求(可读 PRD、查 DocNexus 历史决策)→ F2 先出业务场景清单与产品核对、调研现有代码 → F3 技术澄清(基于已确认场景查证可行性与系统约束,必要取舍分轮给推荐;新业务问题回 F2;S 规模无未定决定时省提问)→ **规模判定(S / M / L 说明判定依据,不再询问确认)** → 完整流程落盘 requirement.md 并等用户确认正式版本,再按规模出方案(非快速通道一律落方案文档:S 简版、M 精简版、L 完整版;S 符合条件时先问是否走快速通道,走则不落盘)→ 小步实现并编译 → 补测试并运行,报告验证结果并等待确认 → 用户选择子 agent 审查、当前 agent 审查或跳过,落盘 `review.md` 记录结果→ 报告交给用户,等待选择「修复问题 / 交付」;返工完成后等用户确认才重新验证,验证后再等确认才进入复审,最后再次等待交付选择,选择交付后才将交付说明落盘到 `workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md`(带分支元信息;改动、验证结果、配置清单、未执行的 SQL),已接入 DocNexus 时交付里有值得记录的知识才问要不要沉淀(同意后以 `dev-notes` 分类写入,并把库内路径记回交付说明),没有就跳过并在元信息行写「无需沉淀」。审查和上线方案会按分支自动读取这份交付说明。
|
|
119
119
|
* **S 规模快速通道**:已发布本次正式清单或创建完整流程运行时继续完整流程,规模降为 S 也不切换。规模判定不询问用户;S 规模且不涉及配置、SQL / DDL、对外接口、表结构,也没有 F2 / F3 已确认或仍待澄清的业务决定,且本次未发布正式清单、未创建完整流程运行时,**问用户是否走快速通道**,问完等本轮答复——明确同意才走:编译、测试照常,审查在当前会话按标准清单做,**不绑定需求、不落任何产物文件**(方案 / `review.md` / 交付说明都不写;运行反馈照常记一行),对话里一次交付并注明「DocNexus:未询问(快速通道不问沉淀)」;拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件,先停下后续实现、重新评估规模,绑定需求并先回 F3(缺陷 B3)补需求文档,再到 F4 / B4 补方案、自检;M / L 确认方案后再继续实现、验证、审查与交付选择。缺陷修复同样适用(根因仍须在对话里写清楚)。
|
|
120
|
-
* **缺陷修复**:收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知(S 规模问是否走快速通道;M / L 确认根因与修复方式后再改)** → 完整流程先生成描述现象、期望与验收的 `requirement.md`,再把根因与修复方式追加到 `plan.md`,同步更新文档头的修复分支与日期(不另建文件)→ 最小修复让测试转绿 →
|
|
121
|
-
*
|
|
120
|
+
* **缺陷修复**:收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知(S 规模问是否走快速通道;M / L 确认根因与修复方式后再改)** → 完整流程先生成描述现象、期望与验收的 `requirement.md`,再把根因与修复方式追加到 `plan.md`,同步更新文档头的修复分支与日期(不另建文件)→ 最小修复让测试转绿 → 用户选择审查方式,落盘本轮审查或跳过记录→ 用户选择修复或交付(修复后验证并询问复审方式;交付必须写明根因)。
|
|
121
|
+
* 原可派子 agent 的审查点都由用户选择子 agent、当前 agent 或跳过,包括需求、方案、代码、复审、分角度查找及发现复核。跳过时注明未审查范围。遗留严重问题须说明风险并由用户明确接受,不能把选择交付写成审查通过。
|
|
122
122
|
* **HTTP 接口验证**:新增 / 修改接口或接口行为时,F4 在方案列出方法 / 路径、AC 和场景,F6 沿用既有框架编写或更新并执行接口层测试,F7 标准 / 深审检查覆盖与执行证据。至少测正常请求、适用的参数错误和未登录 / 无权限场景,断言状态码与关键响应;纯内部重构且接口行为不变、已有覆盖充分时运行现有用例即可。缺环境时记录未验证、原因及可执行请求和预期结果,不将单元测试通过视为 HTTP 接口测试通过。缺陷修复 B4 / B5 沿用相同规则。
|
|
123
123
|
* 守则:不写库、不改凭据、不擅自 commit / push、不装新依赖;测试没跑就写「未验证」。
|
|
124
124
|
* DocNexus 是必装组件,缺失或查询失败时先修复;wiki、CodeGraph、数据库为可选增强,所有 Skill 共用开工能力快照与失败处理规则(`workflow/references/capabilities.md`)。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rowansenne/workflow-run",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.37.0",
|
|
4
4
|
"description": "项目级 Agent Skills 一键初始化:workflow / dev / project-review / code-graph / database-query / nacos-config / md-to-wiki / 需求文档与技术上线方案生成",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent-skills",
|
|
@@ -12,10 +12,10 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
|
|
|
12
12
|
|
|
13
13
|
- 开工运行 `node <skills>/workflow/scripts/resolve.mjs status`,按 `<skills>/workflow/references/capabilities.md` 复用本轮能力快照;DocNexus 必装,不可用先修复。
|
|
14
14
|
- 审查范围以 `review-scope.mjs` 输出为准;只报本次引入的问题,范围外发现单列,不把没覆盖写成没问题。
|
|
15
|
-
- 每条结论引用真实代码与文件行号,行号由 `locate.mjs` 定位;CRITICAL / HIGH
|
|
16
|
-
- dev 完整流程调用:执行第 1~7
|
|
15
|
+
- 每条结论引用真实代码与文件行号,行号由 `locate.mjs` 定位;CRITICAL / HIGH 按用户选择复核;跳过复核的发现标为待确认。
|
|
16
|
+
- dev 完整流程调用:执行第 1~7 步,零发现或用户选择跳过也落盘;只返回报告草稿与结构化证据,由主 agent finalize,不修代码、不生成 delivery.md、不提交、不另开 review 运行,跳过第 8~9 步。
|
|
17
17
|
- dev 内部报告写「未询问(由 dev 交付统一处理)」,缺本轮 delivery.md 是正常时序;主 agent 交报告后等用户选修复或交付。S 快速通道仅当前会话审查。
|
|
18
|
-
-
|
|
18
|
+
- 深审大改动的分角度查找、严重发现复核均由用户选择子 agent、当前 agent 或跳过;写入知识库与其他对外动作仍须授权。
|
|
19
19
|
|
|
20
20
|
## 运行状态
|
|
21
21
|
|
|
@@ -59,7 +59,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
|
|
|
59
59
|
## Output Template
|
|
60
60
|
|
|
61
61
|
正式报告使用知识库模板,空节写「无」不删标题,复审逐项对照上次报告;细则见 reporting.md。
|
|
62
|
-
单文件 / 小改动可用灵活模式只在对话列 findings
|
|
62
|
+
单文件 / 小改动可用灵活模式只在对话列 findings,仍须给出证据,严重问题按用户选择复核;dev 完整流程不能用此模式免落盘。
|
|
63
63
|
|
|
64
64
|
## Artifact Location
|
|
65
65
|
|
|
@@ -43,13 +43,13 @@ git diff <main>...<dev> --name-only -G '@Transactional|synchronized|Lock\b|@Vers
|
|
|
43
43
|
|
|
44
44
|
## 4. 分角度并行查找(深审大改动,用户确认后)
|
|
45
45
|
|
|
46
|
-
一个人拿着整份清单从头扫到尾,清单越长、diff 越大,后面的维度越容易被草草带过。改动大时可以让几个子 agent 各盯一类问题,同时看同一份 diff
|
|
46
|
+
一个人拿着整份清单从头扫到尾,清单越长、diff 越大,后面的维度越容易被草草带过。改动大时可以让几个子 agent 各盯一类问题,同时看同一份 diff。它比分批精读慢、用量多几倍,所以**三个条件都满足才询问本轮分角度查找方式**:
|
|
47
47
|
|
|
48
48
|
1. 审查深度是**深审**(见 SKILL.md 第 1 步);
|
|
49
49
|
2. 规模属于上表的「更大」(排除后 > 30 个文件或 > 1500 行改动);
|
|
50
50
|
3. 当前环境能派子 agent / 子任务(Claude Code 的 Agent 工具、Codex / Qwen Code 的子 agent 等)。
|
|
51
51
|
|
|
52
|
-
问法:「改动较大(<N> 个文件 / <M>
|
|
52
|
+
问法:「改动较大(<N> 个文件 / <M> 行),本轮分角度查找选子 agent 并行、当前 agent 分批精读,还是跳过第 4 步清单查找?」等待用户明确选择。选择跳过时,报告注明跳过的范围及未覆盖文件,继续本轮其余已授权步骤。
|
|
53
53
|
|
|
54
54
|
**5 个角度**(对应检查清单的小节):
|
|
55
55
|
|
|
@@ -68,9 +68,9 @@ git diff <main>...<dev> --name-only -G '@Transactional|synchronized|Lock\b|@Vers
|
|
|
68
68
|
**收回之后**(由你自己做):
|
|
69
69
|
- 合并去重:同一位置、同一原因的发现合成一条,级别取高的;
|
|
70
70
|
- 子 agent 列出的没读完的文件汇总到「未覆盖与待确认」;
|
|
71
|
-
- 影响面(第 5
|
|
71
|
+
- 影响面(第 5 步)仍由你自己做,再请用户选择对合并后发现的第 6 步复核方式(选独立复核时另派子 agent,不交回给找出它的那个)。
|
|
72
72
|
|
|
73
|
-
报告「审查方式」写「深审,分 <K>
|
|
73
|
+
报告「审查方式」写「深审,分 <K> 个角度并行查找,<实际复核方式>」。
|
|
74
74
|
|
|
75
75
|
## 5. 未提交改动
|
|
76
76
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
> 审查范围:{{分支对比 / 单文件 / 未提交改动}}:{{范围说明}} | 日期:{{YYYY-MM-DD}}
|
|
8
8
|
> 对比分支:`{{dev分支}}` ←→ `{{基线分支}}`(单文件 / 未提交改动两边都写当前分支)
|
|
9
|
-
> 审查方式:{{快审 / 标准 / 深审}},{{全量精读 / 分批精读(N 批,按风险排序)/ 分 K 个角度并行查找 / 部分摘要化}},{{独立复核 / 自行复核}} | 审查者:{{独立子 agent / 当前 agent}} | 清单来源:{{DocNexus / 项目文件 / skill 默认}}
|
|
9
|
+
> 审查方式:{{快审 / 标准 / 深审}},{{全量精读 / 分批精读(N 批,按风险排序)/ 分 K 个角度并行查找 / 部分摘要化}},{{独立复核 / 自行复核 / 用户选择跳过复核}} | 审查者:{{独立子 agent / 当前 agent / 用户选择跳过审查,未审查}} | 清单来源:{{DocNexus / 项目文件 / skill 默认}}
|
|
10
10
|
> 参考产物:{{本分支的方案(plan.md)/ 技术方案路径;独立运行时已有交付说明可一并引用,dev F7 尚未生成本轮交付说明,不要求提供;复审时加「上次审查 v<N>(<日期>)」;没有写「无」}}
|
|
11
11
|
> DocNexus:{{尚未发起询问写「未询问」,dev 内部审查固定写「未询问(由 dev 交付统一处理)」;沉淀后写 workflow-run/docnexus/library/<path>;没有值得沉淀的内容写「无需沉淀」,已询问但未成功入库(含用户拒绝)写「未沉淀」}}
|
|
12
12
|
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
## dev 内部调用
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
由主 agent 先让用户选择子 agent、当前 agent 或跳过。选子 agent 时由未参与本轮实现的 agent 执行第 1~7 步;选当前 agent 时执行相同步骤并如实署名。完整流程必须落盘结果(零发现也写),选择跳过时只落盘未审查记录,不使用下文「灵活模式」免落盘;S 快速通道不落盘,不适用本节。跳过第 8~9 步,沉淀与反馈由 dev 交付时统一处理。只审代码、写 tmp 报告草稿和结构化结果,交回 dev 主 agent finalize;不修改业务代码、不生成 `delivery.md`、不提交。元信息写「未询问(由 dev 交付统一处理)」,不将 F8 的交付沉淀结果复制到内部审查报告;缺少本轮交付说明是正常时序,需求、已确认决定和验证结果以 dev 交接为准,旧交付说明只作历史参考。报告完成后交回主 agent,由主 agent 询问用户修复或交付。
|
|
12
12
|
|
|
13
13
|
## 第 7 步 — 输出报告(dev 完整流程的自审同样执行本步,只跳过第 8~9 步)
|
|
14
14
|
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
|
|
30
30
|
按 `<skills>/workflow/references/templates.md`「文档模板的两部分」读取报告模板。遵守要求区,只用内容区生成正文。无标记的模板沿用旧格式,边界有误时先修复。报告结构以模板为准,包括元信息(审查范围、对比分支、审查方式、参考产物、DocNexus)、结论摘要、与上次审查对比(复审时)、严重问题(带触发条件与复核列)、一般问题、优化建议、需求对照(有方案时)、配置清单(如有)、影响面、未覆盖与待确认。某一节没有内容写「无」,不要删标题。
|
|
31
31
|
|
|
32
|
-
> 灵活模式:单文件 / 小改动只在对话里回复时,可以直接列 findings,不必套完整模板;但每个结论必须指向真实文件+行号并引用代码,不得用"应该/大概"下结论,CRITICAL / HIGH
|
|
32
|
+
> 灵活模式:单文件 / 小改动只在对话里回复时,可以直接列 findings,不必套完整模板;但每个结论必须指向真实文件+行号并引用代码,不得用"应该/大概"下结论,CRITICAL / HIGH 按用户选择复核。落盘的报告一律用模板。
|
|
33
33
|
|
|
34
34
|
## Artifact Location
|
|
35
35
|
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
|
|
22
22
|
## 第 3 步 — 分支对比
|
|
23
23
|
|
|
24
|
-
基线默认取 `workflow/profile.json` 的 `main_branch`(未配置则 `main`)。规模和分批用第 1 步 `review-scope.mjs` 的输出:`summary.size` 是「全量精读」就一次读完;「分批精读」按 `batches` 的顺序(P0 → P1 → P2)读,P0 不能跳过;「过大」时停下请用户缩小范围。审不到的文件写进报告(读法见 `diff-strategy.md`)。**深审且改动属于「更大」、环境又能派子 agent
|
|
24
|
+
基线默认取 `workflow/profile.json` 的 `main_branch`(未配置则 `main`)。规模和分批用第 1 步 `review-scope.mjs` 的输出:`summary.size` 是「全量精读」就一次读完;「分批精读」按 `batches` 的顺序(P0 → P1 → P2)读,P0 不能跳过;「过大」时停下请用户缩小范围。审不到的文件写进报告(读法见 `diff-strategy.md`)。**深审且改动属于「更大」、环境又能派子 agent 时,先让用户选择分角度查找的方式**(`diff-strategy.md`「分角度并行查找」),用户选择子 agent 时,第 4 步由各子 agent 按角度过清单;选择当前 agent 时分批精读,选择跳过时注明未覆盖范围。只审本次改动引入的问题,同时检查改动是否破坏既有调用方。
|
|
25
25
|
|
|
26
26
|
## 第 4 步 — 逐项过检查清单
|
|
27
27
|
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
# 发现复核与严重级别
|
|
2
2
|
|
|
3
|
-
进入第 6
|
|
3
|
+
进入第 6 步前读取;所有审查模式共用,对话回复也按用户选择处理严重发现的复核。
|
|
4
4
|
|
|
5
5
|
## 第 6 步 — 复核
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
7
|
+
发现 CRITICAL / HIGH(深审时包括 MEDIUM)后,按 <skills>/workflow/references/execution.md 的「审查方式选择」请用户选择本轮发现复核方式。所有发现均做下面第 1 条定位。审查结论会被用来决定能不能合并,一条误报会让人白改代码,也会让后面的真问题不被当回事。找出问题的人自己复核容易顺着原来的思路认同自己,所以可以交给独立的一方复核。
|
|
8
|
+
- **选择子 agent 复核**:当前环境能派子 agent / 子任务时(例如 Claude Code 的 Agent 工具、Codex / Qwen Code 的子 agent),每条发现派一个,互不相关的可以同时派。只给它:一句话结论、位置(文件:行号)、你写的触发条件、对比分支(或「未提交改动」)。**不给你的推理过程**,也不告诉它你认为成立。要它自己读代码,按下面 1~4 条检查,回答「成立 / 可能成立 / 不成立」并引用代码作为依据。
|
|
9
|
+
- **选择当前 agent 复核**:当前审查者自行复核,先找它**不成立**的理由,找不到再确认成立。
|
|
10
|
+
- **选择跳过复核**:记录用户选择和未复核范围,受影响发现标「⚠ 待确认」,不计入已复核的严重问题或阻止合并的结论。
|
|
10
11
|
检查项(独立复核和自行复核都按这 4 条):
|
|
11
12
|
1. **定位**:把所有发现(包括 MEDIUM / LOW)写成 `workflow-run/tmp/review/findings.json`(数组,每条 `{ "file", "code"(原代码片段), "line"(你估的行号,可选), "title" }`),运行 `node <skills>/workflow/scripts/locate.mjs workflow-run/tmp/review/findings.json`(带上和第 1 步一样的 `--diff` / `--base`)。报告里的行号一律用它输出的 `start_line`~`end_line`,不用自己数的。`anchored: false` 的回去重读代码、照原样改片段再跑一次,还找不到就降为 MEDIUM 并标「⚠ 待确认」;`ambiguous` 时看 `candidates` 确认是哪一处;`in_change: false` 说明问题不在本次改动的行上,按第 4 条判断是不是本次引入的。
|
|
12
13
|
2. 写出**触发条件**:什么输入 / 状态下会出错、错成什么样。写不出来 → 降为 MEDIUM 并标「⚠ 待确认」。
|
|
@@ -26,5 +27,5 @@
|
|
|
26
27
|
- 每个结论都要能定位到具体文件+行号,并引用真实代码片段;行号来自 `locate.mjs`。
|
|
27
28
|
- 读不到的内容如实说明,不要臆测。
|
|
28
29
|
- 涉及跨分支对比时,确保 diff 基于正确的 base 分支(默认 `main`)。
|
|
29
|
-
- CRITICAL / HIGH
|
|
30
|
+
- 已确认的 CRITICAL / HIGH 都经过用户选定的复核且写得出触发条件;跳过或复核不了的标「⚠ 待确认」,不计入「不建议合并」的结论。
|
|
30
31
|
- `review-scope.mjs` 的每个文件都有交代:`review` 里的都审过,没精读的逐个列在「未覆盖与待确认」;`skipped` 按原因汇总写进同一节(例如「跳过 12 个:生成文件 8、文档 3、敏感文件 1」,敏感文件单独点名提醒)。
|
package/workflow/SKILL.md.tpl
CHANGED
|
@@ -49,8 +49,8 @@ description: "Entry point for project workflow commands: /workflow, project prof
|
|
|
49
49
|
### 完整链路(从需求到上线)
|
|
50
50
|
|
|
51
51
|
```
|
|
52
|
-
dev(确定工作分支 → 定需求名 → 理解与澄清 →
|
|
53
|
-
↳
|
|
52
|
+
dev(确定工作分支 → 定需求名 → 理解与澄清 → 落盘并确认需求文档 → 方案 → 实现 → 测试并等用户确认 → 由用户选择子 agent 审查、当前 agent 审查或跳过并落盘记录 → 用户选择修复或交付)
|
|
53
|
+
↳ 功能修复:实现并等确认 → 验证并等确认 → 询问本轮复审方式 → 再次选择;交付:完整流程生成 delivery.md,S 快速通道只在对话交付、不落盘
|
|
54
54
|
→ create-tech-md-doc(M / L 规模)
|
|
55
55
|
→ md-to-wiki(发布技术方案,可选)
|
|
56
56
|
→ create-release-md-doc(要上线时)
|
|
@@ -52,6 +52,7 @@ export function createCodeHandoff(root, { branch, id, depth = '标准', capabili
|
|
|
52
52
|
run_id: id,
|
|
53
53
|
code: snapshot.digest,
|
|
54
54
|
inputs: hash(JSON.stringify(inputs)),
|
|
55
|
+
...(isDev(run) ? { mode: 'independent|self|skipped', confirmed: '由主 agent 根据用户实际选择填 true' } : {}),
|
|
55
56
|
findings: [{ id: '唯一编号', severity: 'CRITICAL|HIGH|MEDIUM|LOW', verification: 'confirmed|pending', scope: 'in_scope|outside(范围外发现单列)', file: '真实路径', line: 1, summary: '触发条件与影响' }],
|
|
56
57
|
coverage: { reviewed: ['已审文件'], uncovered: ['未审文件'] },
|
|
57
58
|
},
|
|
@@ -82,10 +83,12 @@ export function createDocumentHandoff(root, { branch, id, kind, text }) {
|
|
|
82
83
|
inputs,
|
|
83
84
|
draft: { text: draft.text, hash: draftHash },
|
|
84
85
|
basis: basis ? { path: basis.path, hash: basis.hash, version: basis.version, text: basisText } : null,
|
|
86
|
+
rules: '按已确认的范围、验收项和技术约束审查。阻塞项须给出具体约束或验收依据及实际影响。架构偏好、可选优化和新增功能作为建议。需要新取舍时说明冲突,交用户决定。复审优先看基线差异、待关闭阻塞项和受影响的验收项;影响不明时扩大范围。',
|
|
85
87
|
result_schema: {
|
|
86
88
|
run_id: id,
|
|
87
89
|
inputs,
|
|
88
|
-
mode: 'independent',
|
|
90
|
+
mode: 'independent|self|skipped',
|
|
91
|
+
confirmed: '由主 agent 根据用户实际选择填 true',
|
|
89
92
|
reviewer: '实际子 agent 标识',
|
|
90
93
|
summary: '审查结论与已复核修订',
|
|
91
94
|
findings: [{ location: '章节或验收编号', evidence: '依据及来源', impact: '实际影响', blocking: false }],
|
|
@@ -6,7 +6,7 @@ import { FILES, parseBranch } from './artifact-model.mjs';
|
|
|
6
6
|
import { canonicalJson, hash, assertWorkingBranch, snapshotReader } from './code-snapshot.mjs';
|
|
7
7
|
import { layout } from './project.mjs';
|
|
8
8
|
import { readRun, assertRunVersion, applyCheckpoint } from './runs.mjs';
|
|
9
|
-
import { isDev, coreSteps, applyDevEvidence, assertRequirement, assertPlanBasis, assertReview, assertDelivery, reviewEvidence, documentReviewBasis } from './run-gates.mjs';
|
|
9
|
+
import { isDev, coreSteps, applyDevEvidence, assertRequirement, assertRequirementApproval, assertPlanBasis, assertReview, assertDelivery, reviewEvidence, documentReviewBasis } from './run-gates.mjs';
|
|
10
10
|
import { documentReviewEvidence, requiresDocumentReview } from './document-review.mjs';
|
|
11
11
|
import { updateMeta } from './meta-store.mjs';
|
|
12
12
|
import { OLD_DIR, indexArtifacts } from './requirements.mjs';
|
|
@@ -176,6 +176,7 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
|
|
|
176
176
|
if (kind === 'plan') {
|
|
177
177
|
requirement = assertRequirement(root, req, run);
|
|
178
178
|
if (run.steps[run.kind === 'feature' ? 'F3' : 'B3'].status !== 'completed') throw new Error('需求文档尚未完成,不能收尾方案');
|
|
179
|
+
assertRequirementApproval(run, requirement);
|
|
179
180
|
}
|
|
180
181
|
const documentReview = requiresDocumentReview(run, kind)
|
|
181
182
|
? documentReviewEvidence(run, kind, digest, kind === 'plan' ? requirement : documentReviewBasis(root, req, run, kind), packet, result, at)
|
|
@@ -190,6 +191,9 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
|
|
|
190
191
|
...(documentReview ? { document_review: documentReview } : {}),
|
|
191
192
|
...(requirement ? { requirement: { hash: requirement.hash, version: requirement.version } } : {}) } };
|
|
192
193
|
const clarificationChanged = kind === 'clarification' && current.artifacts?.clarification?.hash !== digest;
|
|
194
|
+
if (clarificationChanged || (kind === 'requirement' && current.artifacts?.requirement?.hash !== digest)) {
|
|
195
|
+
delete run.requirement_approval;
|
|
196
|
+
}
|
|
193
197
|
if (clarificationChanged || (kind === 'plan' && (current.artifacts?.plan?.hash !== digest || current.artifacts?.plan?.requirement?.hash !== requirement.hash))
|
|
194
198
|
|| (kind === 'requirement' && current.artifacts?.requirement?.hash !== digest)) {
|
|
195
199
|
run.plan_approval = null; run.implementation = null; run.validation = null; run.review = null; run.decision = null;
|
|
@@ -5,7 +5,13 @@ const nonempty = (value) => typeof value === 'string' && Boolean(value.trim());
|
|
|
5
5
|
|
|
6
6
|
export const documentReviewStage = (run, kind) => stages[run.kind]?.[kind];
|
|
7
7
|
export const requiresDocumentReview = (run, kind) =>
|
|
8
|
-
run.document_review_policy
|
|
8
|
+
[1, 2].includes(run.document_review_policy) && ['M', 'L'].includes(run.size) && Boolean(documentReviewStage(run, kind));
|
|
9
|
+
|
|
10
|
+
export function assertReviewChoice(result) {
|
|
11
|
+
if (result?.confirmed !== true || !['independent', 'self', 'skipped'].includes(result.mode)) {
|
|
12
|
+
throw new Error('请记录用户明确选择的审查方式:independent / self / skipped,confirmed: true');
|
|
13
|
+
}
|
|
14
|
+
}
|
|
9
15
|
|
|
10
16
|
export function documentReviewInputs(run, kind, draftHash, basis) {
|
|
11
17
|
return hash(JSON.stringify({
|
|
@@ -27,11 +33,15 @@ export function documentReviewEvidence(run, kind, draftHash, basis, packet, resu
|
|
|
27
33
|
result.run_id !== run.id || result.inputs !== inputs) {
|
|
28
34
|
throw new Error('文档审查不对应本轮草稿或其依据,请重新交接并审查');
|
|
29
35
|
}
|
|
30
|
-
|
|
31
|
-
|
|
36
|
+
assertReviewChoice(result);
|
|
37
|
+
if (result.mode === 'skipped') {
|
|
38
|
+
if (!nonempty(result.summary) || !Array.isArray(result.findings) || result.findings.length) {
|
|
39
|
+
throw new Error('跳过文档审查须记录说明,findings 必须为空');
|
|
40
|
+
}
|
|
41
|
+
return { inputs, mode: 'skipped', confirmed: true, summary: result.summary, findings: [], at };
|
|
32
42
|
}
|
|
33
|
-
if (
|
|
34
|
-
throw new Error('
|
|
43
|
+
if (!nonempty(result.reviewer) || !nonempty(result.summary)) {
|
|
44
|
+
throw new Error('文档审查结果需要审查者和结论');
|
|
35
45
|
}
|
|
36
46
|
if (!Array.isArray(result.findings) || result.findings.some((finding) =>
|
|
37
47
|
!nonempty(finding?.location) || !nonempty(finding.evidence) || !nonempty(finding.impact) ||
|
|
@@ -40,8 +50,7 @@ export function documentReviewEvidence(run, kind, draftHash, basis, packet, resu
|
|
|
40
50
|
}
|
|
41
51
|
if (result.findings.some((finding) => finding.blocking)) throw new Error('文档审查仍有阻塞项,请修订并复审后再收尾');
|
|
42
52
|
return {
|
|
43
|
-
inputs, mode: result.mode, reviewer: result.reviewer, summary: result.summary, findings: result.findings, at,
|
|
44
|
-
...(result.mode === 'self' ? { fallback: { confirmed: true, reason: result.fallback.reason } } : {}),
|
|
53
|
+
inputs, mode: result.mode, confirmed: true, reviewer: result.reviewer, summary: result.summary, findings: result.findings, at,
|
|
45
54
|
};
|
|
46
55
|
}
|
|
47
56
|
|
|
@@ -3,7 +3,7 @@ import fs from 'node:fs';
|
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { FILES, parseBranch } from './artifact-model.mjs';
|
|
5
5
|
import { hash, assertSnapshot, assertWorkingBranch, snapshotReader } from './code-snapshot.mjs';
|
|
6
|
-
import { assertDocumentReview, requiresDocumentReview } from './document-review.mjs';
|
|
6
|
+
import { assertDocumentReview, assertReviewChoice, requiresDocumentReview } from './document-review.mjs';
|
|
7
7
|
|
|
8
8
|
export const isDev = (run) => ['feature', 'bug'].includes(run.kind);
|
|
9
9
|
export const coreSteps = (run) => run.kind === 'feature' ? ['F3', 'F4', 'F5', 'F6', 'F7', 'F8'] : ['B3', 'B4', 'B5'];
|
|
@@ -29,8 +29,19 @@ export function assertRequirement(root, req, run, contents) {
|
|
|
29
29
|
return requirement;
|
|
30
30
|
}
|
|
31
31
|
|
|
32
|
+
export function assertRequirementApproval(run, requirement) {
|
|
33
|
+
if (run.kind !== 'feature') return;
|
|
34
|
+
// 升级前已经基于当前需求版本完成的方案可以继续。
|
|
35
|
+
const plannedVersion = run.artifacts?.plan?.requirement;
|
|
36
|
+
if (run.document_review_policy !== 2 && plannedVersion?.hash === requirement.hash && plannedVersion.version === requirement.version) return;
|
|
37
|
+
if (run.requirement_approval?.hash !== requirement.hash || run.requirement_approval.version !== requirement.version) {
|
|
38
|
+
throw new Error('请先让用户明确确认已落盘的当前版本 requirement.md,再进入 F4');
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
32
42
|
export function assertPlanBasis(root, req, run, contents) {
|
|
33
43
|
const requirement = assertRequirement(root, req, run, contents);
|
|
44
|
+
assertRequirementApproval(run, requirement);
|
|
34
45
|
const plan = receipt(root, req, run, 'plan', contents);
|
|
35
46
|
if (plan.requirement?.hash !== requirement.hash || plan.requirement.version !== requirement.version) throw new Error('方案依据的需求版本已变化,请根据当前 requirement.md 重新收尾方案');
|
|
36
47
|
assertDocumentReview(run, 'plan', plan, requirement);
|
|
@@ -71,6 +82,15 @@ export function assertDelivery(root, req, run, contents, getSnapshot = snapshotR
|
|
|
71
82
|
}
|
|
72
83
|
|
|
73
84
|
export function applyDevEvidence(root, req, run, patch, at, contents = {}, getSnapshot = snapshotReader(root, run)) {
|
|
85
|
+
if (patch.requirement_approval !== undefined) {
|
|
86
|
+
if (run.kind !== 'feature' || run.steps.F3.status !== 'completed' || run.stage !== 'F4' ||
|
|
87
|
+
patch.requirement_approval?.confirmed !== true) {
|
|
88
|
+
throw new Error('requirement_approval 仅在 F3 正式需求完成且用户明确确认后,随进入 F4 一起保存');
|
|
89
|
+
}
|
|
90
|
+
const requirement = assertRequirement(root, req, run, contents);
|
|
91
|
+
run.requirement_approval = { hash: requirement.hash, version: requirement.version, at };
|
|
92
|
+
run.history.at(-1).requirement_approval = run.requirement_approval;
|
|
93
|
+
}
|
|
74
94
|
if (!isDev(run)) return;
|
|
75
95
|
for (const step of coreSteps(run)) if (run.steps[step].status === 'skipped') throw new Error(`完整 dev 核心步骤不能跳过:${step}`);
|
|
76
96
|
if (patch.approval !== undefined) {
|
|
@@ -108,8 +128,9 @@ export function applyDevEvidence(root, req, run, patch, at, contents = {}, getSn
|
|
|
108
128
|
const requirementStep = run.kind === 'feature' ? 'F3' : 'B3';
|
|
109
129
|
if (completed(requirementStep)) assertRequirement(root, req, run, contents);
|
|
110
130
|
if (patch.stage === (run.kind === 'feature' ? 'F4' : 'B4')) {
|
|
111
|
-
assertRequirement(root, req, run, contents);
|
|
131
|
+
const requirement = assertRequirement(root, req, run, contents);
|
|
112
132
|
if (run.steps[requirementStep].status !== 'completed') throw new Error('需求文档尚未完成,不能进入方案/修复阶段');
|
|
133
|
+
assertRequirementApproval(run, requirement);
|
|
113
134
|
}
|
|
114
135
|
if (run.kind === 'feature') {
|
|
115
136
|
if (completed('F4')) assertPlanBasis(root, req, run, contents);
|
|
@@ -149,6 +170,10 @@ export function reviewEvidence(root, req, run, packet, result, contents, getSnap
|
|
|
149
170
|
if (isDev(run)) assertValidation(root, req, run, contents, getSnapshot);
|
|
150
171
|
if (result?.run_id !== run.id || result.code !== snapshot.digest || result.inputs !== packet.inputs) throw new Error('审查结果的运行、代码版本或交接内容不匹配,请返回本轮审查结果');
|
|
151
172
|
if (!Array.isArray(result?.findings) || !Array.isArray(result?.coverage?.reviewed) || !Array.isArray(result?.coverage?.uncovered)) throw new Error('审查结果需要 findings 和 coverage.reviewed / uncovered');
|
|
173
|
+
if (isDev(run) || result.mode !== undefined) assertReviewChoice(result);
|
|
174
|
+
if (result.mode === 'skipped' && (result.findings.length || result.coverage.reviewed.length)) {
|
|
175
|
+
throw new Error('用户选择跳过审查时,findings 和 coverage.reviewed 必须为空');
|
|
176
|
+
}
|
|
152
177
|
const covered = [...result.coverage.reviewed, ...result.coverage.uncovered];
|
|
153
178
|
const expected = packet.scope.review.map((f) => f.path);
|
|
154
179
|
if (new Set(covered).size !== covered.length || expected.length !== covered.length || expected.some((p) => !covered.includes(p))) throw new Error('审查覆盖范围必须逐文件对应交接材料,未审完的放入 uncovered');
|
package/workflow/lib/runs.mjs
CHANGED
|
@@ -63,7 +63,7 @@ export function runState(root, branch, workspace = loadWorkspace(root), id = nul
|
|
|
63
63
|
|
|
64
64
|
export function applyCheckpoint(run, patch, at, reopen = true) {
|
|
65
65
|
if (!object(patch)) throw new Error('checkpoint 必须是 JSON 对象');
|
|
66
|
-
const allowed = ['stage', 'status', 'size', 'waiting_for', 'reason', 'steps', 'context', 'decision', 'approval', 'implement', 'validation', 'scope'];
|
|
66
|
+
const allowed = ['stage', 'status', 'size', 'waiting_for', 'reason', 'steps', 'context', 'decision', 'requirement_approval', 'approval', 'implement', 'validation', 'advance', 'scope'];
|
|
67
67
|
for (const key of Object.keys(patch)) if (!allowed.includes(key)) throw new Error(`不支持修改字段:${key}`);
|
|
68
68
|
if (patch.status !== undefined && !['running', 'waiting_user', 'blocked'].includes(patch.status)) throw new Error('save 的状态只支持 running / waiting_user / blocked;完成用 complete,取消用 cancel');
|
|
69
69
|
if (patch.size !== undefined) {
|
|
@@ -73,7 +73,23 @@ export function applyCheckpoint(run, patch, at, reopen = true) {
|
|
|
73
73
|
const stages = FLOWS[run.kind];
|
|
74
74
|
const stage = patch.stage ?? run.stage;
|
|
75
75
|
if (!stages.includes(stage)) throw new Error(`无效阶段:${stage}`);
|
|
76
|
-
const
|
|
76
|
+
const feature = run.kind === 'feature';
|
|
77
|
+
const hasReachedValidation = feature && run.history.some((event) => event.stage === 'F6');
|
|
78
|
+
const advancingToReview = feature && stage === 'F7' && run.stage !== 'F7';
|
|
79
|
+
const advancingToRevalidation = hasReachedValidation && stage === 'F6' && stages.indexOf(run.stage) < stages.indexOf('F6');
|
|
80
|
+
if (advancingToReview && (run.stage !== 'F6' || run.steps.F6.status !== 'completed')) {
|
|
81
|
+
throw new Error('请先在 F6 完成验证并交给用户确认');
|
|
82
|
+
}
|
|
83
|
+
if (advancingToRevalidation && (run.stage !== 'F5' || run.steps.F5.status !== 'completed')) {
|
|
84
|
+
throw new Error('请先在 F5 完成返工并交给用户确认');
|
|
85
|
+
}
|
|
86
|
+
if ((advancingToReview || advancingToRevalidation) && patch.advance?.confirmed !== true) {
|
|
87
|
+
throw new Error(`进入 ${stage} 前须取得用户明确确认:advance.confirmed`);
|
|
88
|
+
}
|
|
89
|
+
if (patch.advance !== undefined && !advancingToReview && !advancingToRevalidation) {
|
|
90
|
+
throw new Error('advance 仅用于用户确认进入 F7 或返工后进入 F6');
|
|
91
|
+
}
|
|
92
|
+
let status = patch.status ?? (patch.advance ? 'running' : run.status);
|
|
77
93
|
// 回到已完成的阶段时,后续完成标记失效;历史 checkpoint 仍保留。
|
|
78
94
|
if (reopen && patch.stage && (stages.indexOf(stage) < stages.indexOf(run.stage) || (status === 'running' && done(run.steps[stage].status)))) {
|
|
79
95
|
for (const name of stages.slice(stages.indexOf(stage))) run.steps[name] = { status: 'pending' };
|
|
@@ -108,15 +124,22 @@ export function applyCheckpoint(run, patch, at, reopen = true) {
|
|
|
108
124
|
if (patch.decision.accepted_risks !== undefined && (!Array.isArray(patch.decision.accepted_risks) || patch.decision.accepted_risks.some((v) => typeof v !== 'string'))) throw new Error('accepted_risks 必须是已明确接受的问题 id 数组');
|
|
109
125
|
run.decision = { ...patch.decision, at };
|
|
110
126
|
}
|
|
127
|
+
const confirmation = feature && (stage === 'F6' && run.steps.F6.status === 'completed'
|
|
128
|
+
? '确认 F6 验证结果并选择是否进入 F7'
|
|
129
|
+
: stage === 'F5' && hasReachedValidation && run.steps.F5.status === 'completed'
|
|
130
|
+
? '确认 F5 返工结果并选择是否进入 F6'
|
|
131
|
+
: null);
|
|
132
|
+
if (confirmation) status = 'waiting_user';
|
|
111
133
|
run.stage = stage;
|
|
112
134
|
run.status = status;
|
|
113
|
-
run.waiting_for = status === 'waiting_user' ? (patch.waiting_for ?? run.waiting_for) : null;
|
|
135
|
+
run.waiting_for = status === 'waiting_user' ? (confirmation || (patch.waiting_for ?? run.waiting_for)) : null;
|
|
114
136
|
run.reason = status === 'blocked' ? (patch.reason ?? run.reason) : null;
|
|
115
137
|
if (status === 'waiting_user' && !run.waiting_for?.trim()) throw new Error('等待用户时必须填写 waiting_for');
|
|
116
138
|
if (status === 'blocked' && !run.reason?.trim()) throw new Error('阻塞时必须填写 reason');
|
|
117
139
|
if (status === 'running' && run.steps[stage].status === 'pending') run.steps[stage] = { status: 'in_progress', updated_at: at };
|
|
118
140
|
run.updated_at = at;
|
|
119
141
|
run.history.push({ at, stage, status, steps: patch.steps ?? {}, ...(patch.decision ? { decision: run.decision } : {}) });
|
|
142
|
+
if (patch.advance) run.history.at(-1).advance = { confirmed: true };
|
|
120
143
|
return run;
|
|
121
144
|
}
|
|
122
145
|
|
|
@@ -136,7 +159,7 @@ export function startRun(root, { branch, kind = 'feature', size = null, input =
|
|
|
136
159
|
created_at: at, updated_at: at, completed_at: null, steps: Object.fromEntries(FLOWS[kind].map((s) => [s, { status: 'pending' }])),
|
|
137
160
|
scope: { base: meta.base || profile?.main_branch || 'main', exclude: Array.isArray(profile?.review?.exclude) ? profile.review.exclude.filter((v) => typeof v === 'string') : [] },
|
|
138
161
|
artifacts: {}, context: {}, waiting_for: null, reason: null, decision: null, history: [],
|
|
139
|
-
...(['feature', 'bug'].includes(kind) ? { document_review_policy:
|
|
162
|
+
...(['feature', 'bug'].includes(kind) ? { document_review_policy: 2 } : {}) }, input, at);
|
|
140
163
|
applyDevEvidence(root, req, selected, input, at);
|
|
141
164
|
return { ...meta, runs: { ...runs, [id]: selected }, updated: at };
|
|
142
165
|
}, { root });
|
|
@@ -22,7 +22,7 @@ node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision
|
|
|
22
22
|
node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind requirement --draft workflow-run/tmp/requirement.md --input workflow-run/tmp/checkpoint.json
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
-
需求文档保存背景目标、范围边界、AC 验收标准、已确认决定与待确认问题。功能收尾 checkpoint 标 `{"
|
|
25
|
+
需求文档保存背景目标、范围边界、AC 验收标准、已确认决定与待确认问题。功能收尾 checkpoint 标 F3 completed、status waiting_user、waiting_for「确认正式 requirement.md」。发文件链接和版本,等用户明确确认后,才用 save `{"stage":"F4","status":"running","requirement_approval":{"confirmed":true}}` 进入 F4 起草方案。程序把确认绑定到当前需求 hash 和版本;需求重新收尾且内容变化后须重新确认。缺陷修复在需求收尾时标 B3 completed,按 B3 / B4 规则继续。
|
|
26
26
|
|
|
27
27
|
plan.md 头部引用需求文档 cite 与版本,只写实现设计、技术风险、实施步骤和验证计划;验证引用 AC 编号,不复制业务需求。方案收尾自动绑定需求 hash / 版本:
|
|
28
28
|
|
|
@@ -30,39 +30,47 @@ plan.md 头部引用需求文档 cite 与版本,只写实现设计、技术风
|
|
|
30
30
|
node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind plan --draft workflow-run/tmp/plan.md --input workflow-run/tmp/checkpoint.json
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
功能方案收尾的 checkpoint 可写 `{"steps":{"F4":{"status":"completed"}}}
|
|
33
|
+
功能方案收尾的 checkpoint 可写 `{"steps":{"F4":{"status":"completed"}}}`。bug 的 B4 还包含实现、验证,方案收尾时不能标完成,checkpoint 可省略。已有方案在草稿中保留正文并追加修复方案,更新当前分支和日期。
|
|
34
34
|
|
|
35
|
-
M / L
|
|
35
|
+
M / L 先取得用户对方案草稿的实际确认,正式收尾后用 save 记录 `approval: {"confirmed":true}`,程序绑定当前 plan.md 的 hash/版本。审核后的定稿仍在用户确认的范围、行为、技术取舍和风险边界内时,按原答复登记,发一条审查和修改摘要即可。已收尾方案更新后旧凭据失效,须按当前版本重新登记。S 完整流程仍须收尾方案,但无需该确认记录。进入实现:
|
|
36
36
|
|
|
37
37
|
- feature:save `{"stage":"F5","status":"running","approval":{"confirmed":true}}`(S 可省 approval)。
|
|
38
38
|
- bug:在 B4 save `{"status":"running","approval":{"confirmed":true},"implement":true}`;之后才改代码。
|
|
39
39
|
|
|
40
40
|
未收尾方案、M / L 未确认、核心步骤 skipped 都会被拒绝。程序校验确认记录与版本,不能替代 agent 核实用户是否真的授权。
|
|
41
41
|
|
|
42
|
-
业务清单内容变化时撤销本轮 requirement / plan 凭据,清除旧方案确认、实现、验证、审查与交付选择,并重置后续步骤;正式文件和历史版本保留供查阅,相同清单内容重新发布不触发该失效处理。即便需求和方案正文不变,也必须分别重新 finalize
|
|
42
|
+
业务清单内容变化时撤销本轮 requirement / plan 凭据,清除旧方案确认、实现、验证、审查与交付选择,并重置后续步骤;正式文件和历史版本保留供查阅,相同清单内容重新发布不触发该失效处理。即便需求和方案正文不变,也必须分别重新 finalize;M / L 在新方案上核对用户确认的决定是否仍适用,并重新登记当前版本的确认。
|
|
43
43
|
|
|
44
|
-
需求变化回 F3(bug 回 B3
|
|
44
|
+
需求变化回 F3(bug 回 B3),只澄清变化和受影响的内容,再 finalize requirement;程序清除旧方案确认、实现、验证、审查和交付选择。即使方案正文不变,也要在 F4 / B4 重新收尾以绑定新需求版本。M / L 只向用户确认新增或改变且尚未决定的取舍。只改实现方式则仅更新 plan。手动改需求正文而未收尾也会使后续证据校验失败。
|
|
45
|
+
|
|
46
|
+
## 审查方式选择
|
|
47
|
+
|
|
48
|
+
每到允许派子 agent 的审查点,主 agent 先说明本轮范围(需求、方案、代码、修订复审、分角度查找或发现复核),让用户明确选择 **子 agent 审查 / 当前 agent 审查 / 跳过审查**。有运行时保存 waiting_user,等答复后继续。不可派遣时说明子 agent 选项当前不可用,仍由用户决定自查、跳过或等待。已明确选择的本轮范围可以直接执行;一次询问可包含多个明确列出的审查点。已有流程授权或对其他轮次的选择不能用来推定本轮选择。子 agent 遇到未确认的下级审查点,把范围交主 agent 询问。
|
|
49
|
+
|
|
50
|
+
选择跳过时明确记录「未审查」及跳过的范围。验证、正式需求确认及交付选择仍分别执行。对结果 JSON,由主 agent 按实际答复记录 `mode: "independent" | "self" | "skipped"` 和 `confirmed: true`;审查者只提供实际审查内容。
|
|
45
51
|
|
|
46
52
|
## 需求与方案审查
|
|
47
53
|
|
|
48
|
-
|
|
54
|
+
M / L 在 F3 / B3 澄清需求决定,在 F4 / B4 确认方案草稿。运行有文档审查策略时,两份文档各自在相关决定明确后询问本轮审查方式,按选择处理再正式收尾。F3 正式落盘后请用户确认正式版本。S 和没有该字段的升级前运行无需新增文档审查。新运行从 S 升为 M / L 后,如已有未审查的需求或方案,回对应阶段补审。
|
|
49
55
|
|
|
50
|
-
1. 草稿写到 tmp
|
|
56
|
+
1. **先讨论草稿。** 草稿写到 tmp,给用户草稿链接或重点摘要。收到明确修改意见就直接更新,回复改了哪些内容。只询问真正未决的取舍;继续讨论期间不送审、不收尾。已有明确答复覆盖的范围、行为和技术决定直接复用;单条修改意见只确认该项,仍需确认的内容集中在同一轮。需要等待时按 [runs.md](runs.md#写-checkpoint) 保存草稿路径、已确认决定及待答问题。
|
|
57
|
+
2. **决定明确后询问审查方式。** 用户选定本轮方式后,将等待中的运行恢复为 `running`,生成交接。交接记录当前草稿正文及已登记的业务澄清或需求依据。
|
|
51
58
|
|
|
52
59
|
```sh
|
|
53
60
|
node <skills>/workflow/scripts/review-handoff.mjs --id <id> --kind <requirement|plan> --draft <草稿.md>
|
|
54
61
|
```
|
|
55
62
|
|
|
56
|
-
|
|
63
|
+
3. **审查按已确认的决定开展。** 选子 agent 时把交接 `path`、适用的原始材料及用户决定的来源交给未参与起草的子 agent;选当前 agent 时用相同材料自查。审查者按 `packet.result_schema` 返回结论、位置、依据、影响和阻塞标记。
|
|
57
64
|
- 需求审查核对范围、场景、规则、技术约束和可验证的验收标准。缺陷修复还要核对现象、根因证据和预期行为。
|
|
58
65
|
- 方案审查以交接中的已定稿需求为依据,核对各验收项的实现与验证安排,以及适用的兼容性、权限、数据和回滚风险。
|
|
59
|
-
|
|
60
|
-
4.
|
|
61
|
-
5.
|
|
66
|
+
- 阻塞项的 `evidence` 指向具体的验收项、已确认决定或可查证的约束,`impact` 写明实际冲突、不可验证的验收项或会引入的风险。架构偏好、可选优化和新增功能填 `blocking: false`,按需采纳或关闭。如果建议被误标为阻塞,主 agent 提供对应的范围或决定,请审查者核实并更正结论。审查者发现需要改变用户决定的真实冲突时,写明影响,由用户或产品决定取舍。
|
|
67
|
+
4. **修订后复核差异。** 在既定决定内直接修复;如有新取舍,一次说明受影响的范围和建议,等待答复后修改。草稿或依据变化时生成绑定当前版本的新 packet。将上一轮同一文档的 packet 和结果(若基线是已收尾版本,也可用该版本正文、依据和审查记录)、正文及依据的差异、待关闭阻塞项和受影响的 AC 或章节一起交给审查者。按用户对本轮复审的选择执行;若选择子 agent,优先复用原审查者,复核这些内容和相邻约束;基线缺失或无法界定影响时扩大范围。新结果使用当前 packet 的 `inputs`,在 `summary` 注明基线、复核范围及关闭的阻塞项;`findings` 如实保留仍适用的发现。
|
|
68
|
+
5. **登记选择。** 独立审查和自查填写实际审查者。用户选跳过时以当前 packet 登记 `mode: "skipped"`、`confirmed: true`、明确写明跳过的 summary 和空 findings。程序校验标记及文档内容,主 agent 如实记录用户答复。
|
|
69
|
+
6. **完成审查或登记跳过后收尾。** 将最终结果保存为 tmp 下的 JSON。执行 `artifact.mjs finalize` 时额外传 `--packet <交接JSON路径> --result <结果JSON路径>`。收尾会拒绝缺失、过期或仍有阻塞项的结果。审查后涉及新的取舍时先取得决定。F3 收尾后另请用户确认正式版本;M / L 方案收尾后按前文记录当前版本的 `approval`。F7 / B5 的代码审查按下文执行。
|
|
62
70
|
|
|
63
71
|
## 验证证据
|
|
64
72
|
|
|
65
|
-
feature
|
|
73
|
+
feature 首次实现完成后 save F5 completed,进入 F6。已经进入过 F6 的运行回到 F5 或之前阶段返工时,完成 F5 后先 save F5 completed,程序保留 F5 并置为 waiting_user。把改动摘要交给用户,确认推进后再 save `{"stage":"F6","advance":{"confirmed":true}}`。修改方案先按 F4 规则收尾并确认,再到 F5 实现。bug 在 B4 验证。**测试/操作执行前**生成快照:
|
|
66
74
|
|
|
67
75
|
```sh
|
|
68
76
|
node <skills>/workflow/scripts/run.mjs snapshot --id <id>
|
|
@@ -83,13 +91,13 @@ node <skills>/workflow/scripts/run.mjs snapshot --id <id>
|
|
|
83
91
|
}
|
|
84
92
|
```
|
|
85
93
|
|
|
86
|
-
result 只接受 passed / failed / unverified;失败或未验证须 reason,不能用计划冒充结果。bug 将 F6 改为 B4,保存后进入 B5
|
|
94
|
+
result 只接受 passed / failed / unverified;失败或未验证须 reason,不能用计划冒充结果。bug 将 F6 改为 B4,保存后进入 B5。feature 保存 F6 completed 时程序保留 F6 并置为 waiting_user。向用户交付本轮验证结果,等用户明确确认推进,再 save `{"stage":"F7","advance":{"confirmed":true}}`。程序重新校验当前代码快照与验证证据,阶段确认与 F7 的审查方式选择分别记录。若执行期间代码变化,旧快照不能登记,需重新生成快照并验证。
|
|
87
95
|
|
|
88
96
|
快照包含实际工作分支、基线提交、合并基点、HEAD,以及工作区跟踪/未跟踪文件的内容、删除、执行权限和符号链接;暂存本身不改变内容摘要。子模块/嵌套仓库须固定在干净提交,不能用 dirty 标记代替具体代码证据。除明确排除范围外,也覆盖未改动的项目文件,防止调用方/配置变更使证据过期。忽略 Git 忽略的未跟踪文件,以及 workflow-run、已安装 skills、DocNexus 和 CodeGraph 内部文件,避免写报告使自身失效。不能用 `--branch` 给另一实际 checkout 作证。
|
|
89
97
|
|
|
90
98
|
## 自动审查交接
|
|
91
99
|
|
|
92
|
-
开工 status 输出保留在本轮 `workflow-run/tmp/capabilities.json`,同链路复用,不写需求 meta。进入 F7 / B5
|
|
100
|
+
开工 status 输出保留在本轮 `workflow-run/tmp/capabilities.json`,同链路复用,不写需求 meta。进入 F7 / B5 后先询问本轮审查方式,用户选择后生成:
|
|
93
101
|
|
|
94
102
|
```sh
|
|
95
103
|
node <skills>/workflow/scripts/review-handoff.mjs --id <id> --depth 标准 --capabilities workflow-run/tmp/capabilities.json
|
|
@@ -97,13 +105,13 @@ node <skills>/workflow/scripts/review-handoff.mjs --id <id> --depth 标准 --cap
|
|
|
97
105
|
|
|
98
106
|
输出 `path` 是交接 JSON,位于 tmp/review/<运行id>/。自动汇总项目/skills 路径、实际基线、排除范围、风险分批、requirement_document(需求文档路径、hash 与版本)、续接事实摘要、方案、验证命令与结果、上次报告及代码快照。验收与业务范围以对应需求文档为准,context 只作缓存摘要。没有能力文件时省略参数,主 agent 补交本轮能力快照;不重新探测。只传事实,不传实现者的自审结论。
|
|
99
107
|
|
|
100
|
-
|
|
108
|
+
选子 agent 或当前 agent 时按 project-review 第 1~7 步审查,由主 agent 收尾并更新同一运行。选跳过时按模板写跳过记录,审查方式和结论标明「用户选择跳过审查,未审查」,结果的 findings 和 coverage.reviewed 均为空,coverage.uncovered 列出全部审查范围;交付说明同步注明未审查。**审查期间不修改被审代码**。JSON 结果结构以 packet.result_schema 为准,run_id / code / inputs 原样回传,以绑定本轮运行、代码版本和交接内容;范围外发现标 scope: outside,不计入本次交付的严重问题门禁。零发现 findings 为空数组,scope.review 中每个文件必须进入 coverage.reviewed 或 uncovered,不能漏报未审文件。
|
|
101
109
|
|
|
102
110
|
```sh
|
|
103
111
|
node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind review --draft workflow-run/tmp/review.md --packet <交接JSON路径> --result workflow-run/tmp/review-result.json --input workflow-run/tmp/checkpoint.json
|
|
104
112
|
```
|
|
105
113
|
|
|
106
|
-
feature 可在 checkpoint 标 F7 completed;bug 的 B5 此时仍 in_progress。主 agent 取得报告后交给用户,save waiting_user
|
|
114
|
+
feature 可在 checkpoint 标 F7 completed;bug 的 B5 此时仍 in_progress。主 agent 取得报告后交给用户,save waiting_user 等待修复或交付。跳过审查也须取得明确的交付选择。收尾要求交接仍对应当前代码、需求事实、方案和验证;仅进度保存不会让交接失效,改变验收/范围等实质内容须重新审查。
|
|
107
115
|
|
|
108
116
|
独立正式 review 也生成交接材料,R1~R6 记录实际进度,R7 用同一入口收尾 review,再交报告、complete;不要求 dev 的验证或方案。当前协议的代码证据基于实际工作区,正式审查请在目标分支 checkout 中运行;其他分支的只读灵活审查仍可用原 diff 命令,不创建运行。
|
|
109
117
|
|
|
@@ -111,7 +119,7 @@ feature 可在 checkpoint 标 F7 completed;bug 的 B5 此时仍 in_progress。
|
|
|
111
119
|
|
|
112
120
|
用户明确选择交付后,feature save F8 running、bug 在 B5 save running,并写 `decision: {"action":"deliver","confirmed":true}`。程序自动绑定本轮报告 hash、版本与代码摘要。存在已复核 CRITICAL / HIGH 时,先说明风险、取得逐项接受,再在 decision.accepted_risks 中列出对应 findings 的 id;普通的“交付”不代表接受未说明风险。
|
|
113
121
|
|
|
114
|
-
只有该选择仍有效,才允许 `artifact.mjs finalize --kind delivery --draft
|
|
122
|
+
只有该选择仍有效,才允许 `artifact.mjs finalize --kind delivery --draft ...`。审查后代码/基线变化或报告被修改,旧选择不能继续用;回适用的实现或验证阶段,按本节的确认点推进到复审并再次取得交付选择;bug 回 B4。修复回退会清除旧验证、审查与交付选择;方案改变则还须重新确认。
|
|
115
123
|
|
|
116
124
|
交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只 reindex 后用旧收尾凭据 complete。
|
|
117
125
|
|
|
@@ -83,7 +83,7 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
|
|
|
83
83
|
|
|
84
84
|
文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。finalize 或 reindex 后运行 pending 时:
|
|
85
85
|
|
|
86
|
-
**dev F7
|
|
86
|
+
**dev F7 审查例外**:审查环节(含登记用户选择跳过)拿到 `commit` 信息后不询问、不执行文档提交,先交审查报告、等待用户选择修复或交付。选择交付进入 F8 后(完整流程;S 快速通道不落盘,没有待提交产物),再运行 `requirement.mjs pending` 获取当前待提交内容,按下面步骤询问;修复与复审期间继续延后,不改动 `commit_prompt` 配置。
|
|
87
87
|
|
|
88
88
|
1. 把 pending 的 `files` 和 `suggested_message` 给用户看,问要不要提交。
|
|
89
89
|
2. 用户确认后,按 pending 的 `commands` 在文档仓库里提交;推送另外问用户,用户同意后再 `git -C workflow-run push`。
|
|
@@ -83,9 +83,9 @@ F3 / B3 只能在需求文档 finalize 后完成;requirement.md 是需求事
|
|
|
83
83
|
|
|
84
84
|
前面的 F4~F6 必须已按实际进度保存,不能为凑齐示例而直接标完成。bug 的 B5 同时包含审查与交付,报告完成等待选择时 B5 仍为 in_progress,最后交付才标完成。
|
|
85
85
|
|
|
86
|
-
- 用户选修复:save `stage: F5`、`status: running`、`decision: {"action":"fix","confirmed":true}`;bug 回 B4。回到前面的阶段会自动重置该阶段及后续的完成标记、清除旧交付选择,旧 checkpoint 保留在 history
|
|
86
|
+
- 用户选修复:save `stage: F5`、`status: running`、`decision: {"action":"fix","confirmed":true}`;bug 回 B4。回到前面的阶段会自动重置该阶段及后续的完成标记、清除旧交付选择,旧 checkpoint 保留在 history;功能返工完成 F5 时等待用户确认,进入 F6 用 `advance: {"confirmed":true}`;每轮 F6 完成后再次等待确认,进入 F7 用同样字段。缺陷修复在 B4 验证后回 B5。复审后再次等待交付选择。业务场景变化先回 F2 更新清单,再到 F3 重新收尾需求;仅技术约束变化回 F3,规模变化同时写 size。
|
|
87
87
|
- 用户明确选交付:按 execution.md 核对本轮证据,save `stage: F8`、`status: running`、`decision: {"action":"deliver","confirmed":true}`;bug 留在 B5。只记录用户实际确认的选择,遗留风险写 context。
|
|
88
|
-
-
|
|
88
|
+
- 等需求/方案草稿反馈:`status: waiting_user`,waiting_for 说明待答问题,context 保存 tmp 草稿路径、已确认决定及待确认项。恢复时先核对草稿是否仍对应这些决定,直接落实明确反馈。待决定项解决后按 [execution.md](execution.md#需求与方案审查) 送审和收尾。
|
|
89
89
|
- 环境等阻塞:`status: blocked`、reason 说明原因,保留步骤与 remaining;解除后 save running。
|
|
90
90
|
- 取消:用 cancel,input 提供 reason,不能用 complete 把取消记成完成。
|
|
91
91
|
|