@rowansenne/workflow-run 0.34.0 → 0.35.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 CHANGED
@@ -4,6 +4,14 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.35.0] - 2026-11-16
8
+
9
+ ### 新增
10
+ - 新建 M / L 完整开发与缺陷修复运行在需求和方案收尾前增加独立文档审查。审查绑定草稿与依据,已有运行和 S 规模沿用原流程。
11
+
12
+ ### 修复
13
+ - WorkBuddy 安装 `dev` 时生成可补全的项目级 `/dev` 命令,并保留团队自定义的同名命令。
14
+
7
15
  ## [0.34.0] - 2026-11-15
8
16
 
9
17
  ### 优化
@@ -5,6 +5,7 @@ import path from 'node:path';
5
5
  import { IS_WIN, CANON_DIR, INSTALL_BASES, MANIFEST, step, ok, warn, toPosix, fileHash, readManifest, removeEmptyDirs, lstat, timestamp, removeLink, docnexusInternal } from './core.mjs';
6
6
  import { removeDocNexusContext } from './docnexus.mjs';
7
7
  import { removeArtifactContext } from './artifact-context.mjs';
8
+ import { removeWorkBuddyDevCommand } from './workbuddy.mjs';
8
9
 
9
10
  // 软链接是否指向 absTarget(按解析后的绝对路径比较,兼容 Windows 上 readlink 返回的 \\?\ 前缀)
10
11
  export function linkPointsTo(link, absTarget) {
@@ -54,6 +55,7 @@ export function uninstall(root) {
54
55
  }
55
56
 
56
57
  removeArtifactContext(root);
58
+ removeWorkBuddyDevCommand(root);
57
59
 
58
60
  // 2. 各安装目录:按清单删除模板文件;用户配置与手改过的模板文件先备份
59
61
  for (const [rel, m] of found) {
@@ -0,0 +1,37 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { TPL_DIR, lstat, ok, sameFile, warn } from './core.mjs';
4
+
5
+ const commandPath = '.codebuddy/commands/dev.md';
6
+ const template = path.join(TPL_DIR, 'bin', 'workbuddy', 'dev.md');
7
+
8
+ function commandFile(root) {
9
+ const projectDir = path.join(root, '.codebuddy');
10
+ const commandsDir = path.join(projectDir, 'commands');
11
+ for (const dir of [projectDir, commandsDir]) {
12
+ const st = lstat(dir);
13
+ if (st && !st.isDirectory()) return null;
14
+ }
15
+ return path.join(root, commandPath);
16
+ }
17
+
18
+ export function installWorkBuddyDevCommand(root) {
19
+ const file = commandFile(root);
20
+ if (!file) { warn(`无法安装 ${commandPath},命令目录不是普通目录`); return; }
21
+ fs.mkdirSync(path.dirname(file), { recursive: true });
22
+ try {
23
+ fs.copyFileSync(template, file, fs.constants.COPYFILE_EXCL);
24
+ ok(`已安装 WorkBuddy /dev 项目命令:${commandPath}`);
25
+ } catch (error) {
26
+ if (error.code !== 'EEXIST') throw error;
27
+ if (!lstat(file)?.isFile() || !sameFile(file, template)) warn(`保留已有的 WorkBuddy 项目命令:${commandPath}`);
28
+ }
29
+ }
30
+
31
+ export function removeWorkBuddyDevCommand(root) {
32
+ const file = commandFile(root);
33
+ if (!file || !lstat(file)?.isFile() || !sameFile(file, template)) return;
34
+ fs.unlinkSync(file);
35
+ try { fs.rmdirSync(path.dirname(file)); } catch { /* 目录内可能有其他命令 */ }
36
+ ok(`已移除 WorkBuddy /dev 项目命令:${commandPath}`);
37
+ }
@@ -0,0 +1,10 @@
1
+ ---
2
+ description: "使用 dev 技能执行完整开发或缺陷修复流程"
3
+ argument-hint: "[需求、PRD 或 --bug <现象>]"
4
+ ---
5
+
6
+ <!-- workflow-run: WorkBuddy dev command -->
7
+
8
+ 用户明确调用了 `/dev`。先读取项目根目录下的 `.codebuddy/skills/dev/SKILL.md`,再按其中的流程处理下面的完整参数(包括 `--bug`)。未提供任务且未明确要求续接时,先询问要处理的需求或缺陷。
9
+
10
+ $ARGUMENTS
@@ -24,6 +24,7 @@ import { report, installSkills, linkSkills, updateGitignore, setupHome, recordEn
24
24
  import { setupCodeGraph } from './lib/codegraph.mjs';
25
25
  import { uninstall } from './lib/uninstall.mjs';
26
26
  import { writeArtifactContext } from './lib/artifact-context.mjs';
27
+ import { installWorkBuddyDevCommand } from './lib/workbuddy.mjs';
27
28
  import { checkNodeForDocNexus, setupDocNexus, refreshDocNexusLinks, cleanupLegacyDocNexus, templateRecords, saveTemplateRecords, reportTemplateStatus, installedSkills, docnexusConnected, printTemplateDiffs } from './lib/docnexus.mjs';
28
29
  import { upgradeOptions, doctor } from './lib/doctor.mjs';
29
30
  import { docsRepo } from './lib/docsrepo.mjs';
@@ -249,6 +250,8 @@ async function main() {
249
250
  if (r.failed.length) fail('必需文档模板导入失败,安装未完成。修复后运行 npx @rowansenne/workflow-run seed-templates 重试。');
250
251
  } catch (e) { fail(e.message); }
251
252
 
253
+ if (sel.includes('workbuddy') && skills.includes('dev')) installWorkBuddyDevCommand(o.root);
254
+
252
255
  step('安装完成,启用方式');
253
256
  console.log(' codex : 重启 codex 后自动发现项目级 skills(.agents/skills);也可 /use project-review 手动加载');
254
257
  console.log(' claude : Claude Code 自动发现 .claude/skills,无需额外配置');
package/dev/SKILL.md.tpl CHANGED
@@ -21,6 +21,7 @@ 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
+ - 新建 M / L 完整运行(`document_review_policy: 1`)的需求与方案草稿在各自收尾前须经独立子 agent 审查。按 [execution.md 的文档审查](../workflow/references/execution.md#需求与方案审查) 交接;子 agent 不可用时等用户决定是否允许本次自查。S 和升级前已有运行沿用原门禁。
24
25
  - F2 先落偏业务场景的 clarification.md,供用户找产品核对;逐轮更新原问题状态、追加新问题和反馈。业务明确并完成现状调研后,再进入 F3 澄清技术约束;最终需求确认后进入 F4。
25
26
  - S 快速通道须用户明确同意,且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更,且没有 F2 / F3 已确认的业务决定、本次未发布正式清单且未创建完整流程运行;已有清单或运行沿用完整流程,具体资格见 F4。
26
27
  - 快速通道仍编译、测试、当前会话审查,但不 bind、不建运行、不落需求 / 方案 / 审查 / 交付文档;超限或用户要求落盘先停,回 F3(bug 回 B3)补需求文档,再进入方案。
@@ -53,11 +54,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
53
54
 
54
55
  ### F3 — 需求澄清(偏技术约束)
55
56
 
56
- 读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2 更新清单找产品确认。全部明确后,完整流程 finalize requirement.md、完成 F3,再进 F4。
57
+ 读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2 更新清单找产品确认。全部明确后,完整流程按文档门禁审查需求草稿,再确认、收尾 requirement.md、完成 F3,进入 F4。
57
58
 
58
59
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
59
60
 
60
- 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;涉及 HTTP 接口或接口行为变化时列出接口、AC、测试场景及命令 / 环境。S / M 简版、L 完整版,M / L 确认后记录 approval,再进入实现。
61
+ 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求起草方案,按文档门禁审查草稿,再用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;涉及 HTTP 接口或接口行为变化时列出接口、AC、测试场景及命令 / 环境。S / M 简版、L 完整版,M / L 确认后记录 approval,再进入实现。
61
62
 
62
63
  ### F5 — 实现
63
64
 
@@ -87,11 +88,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
87
88
 
88
89
  ### B3 — 定位根因
89
90
 
90
- 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程先生成独立 requirement.md、完成 B3,再进入修复方案。
91
+ 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程按文档门禁审查需求草稿并收尾 requirement.md、完成 B3,再进入修复方案。
91
92
 
92
93
  ### B4 — 修复与验证
93
94
 
94
- 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,用 `artifact.mjs finalize --kind plan` 收尾;M / L 确认后记录 approval、implement 再修复,复现测试由红变绿。
95
+ 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,按文档门禁审查后用 `artifact.mjs finalize --kind plan` 收尾;M / L 确认后记录 approval、implement 再修复,复现测试由红变绿。
95
96
 
96
97
  ### B5 — 审查与交付
97
98
 
@@ -18,12 +18,12 @@
18
18
  - 区分根因与症状:只在出错表象处加判空 / try-catch 不算修复,除非能说明那里就是根因。
19
19
  - 检查同一根因是否在其他调用方同样存在。
20
20
  - 预期业务行为还需产品确认时,按 clarify.md 的清单规则在 B3 初判规模、bind、start,逐轮发布同目录的 clarification.md 并保存等待反馈;需求明确后沿用该运行收尾需求文档。
21
- - 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成 requirement.md,用 `artifact.mjs finalize --kind requirement` 并标 B3 completed,再进 B4。根因证据作事实依据,修复方式留在 plan.md;已有文档先核对后在草稿更新,不自动覆盖原需求。
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 / 版本。没有方案则按模板创建草稿,只填适用节。用 `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`。规模变化时说明依据、按新规模继续。
26
+ - **完整流程先把修复方案追加进 `plan.md`**:沿用 B3 已绑定的需求与 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支、本次日期以及 requirement.md 的 cite / 版本。没有方案则按模板创建草稿,只填适用节。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」完成适用审查,再用 `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
 
@@ -56,6 +56,6 @@ F1 形成初版需求理解后,在 F2、进入 F3 之前先输出清单,不
56
56
 
57
57
  技术调研发现新的业务决定或场景冲突时,回 F2 更新业务清单并等待产品确认;确认后重查受影响的技术事实,再回 F3。已确认且不受影响的场景不重复问。bug 在 B3 内更新清单后继续技术澄清。
58
58
 
59
- 业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。M / L 等用户确认理解一致;已有答复可直接复用,不重复确认。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start),用 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并完成 F3 / B3,再进入 F4。
59
+ 业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start)。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」核对适用的需求草稿。M / L 等用户确认理解一致,已有答复能覆盖最终草稿时可直接复用。用 `artifact.mjs finalize --kind requirement` 收尾并完成 F3 / B3,再进入 F4 / B4。
60
60
 
61
61
  requirement.md 是最终需求事实来源,引用清单 cite 与版本,只汇总有效场景、决定与约束;清单保留业务往返核对过程,plan.md 保存实现设计。值得长期记住的规则与取舍在交付时作为 DocNexus 沉淀候选。
@@ -26,7 +26,7 @@
26
26
  | 只有一两个技术取舍 | 给推荐和依据,能一轮确认就一轮结束 |
27
27
  | M / L 规模,或用户要求先把需求问清楚 | 逐轮确认约束,汇总需求、AC、不做什么与决定,等用户确认理解一致再进 F4 |
28
28
 
29
- **F3 的正式产物**:业务与技术约束均明确后,沿用已有绑定和运行、复核规模;没有清单时,完整流程在此 bind、start(stage F3,仅补记实际完成的 Step0、F1、F2)。用 `resolve.mjs template dev requirement-template.md` 读取模板,将目标、范围、AC、当前有效业务决定与必要技术约束写成草稿,在依据中引用业务清单 cite 与版本。通过 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并将 F3 标 completed,再进入 F4。不因清单发布或产品给了业务答复就跳过技术澄清。
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 并将 F3 标 completed,再进入 F4。不因清单发布或产品给了业务答复就跳过技术澄清。
30
30
 
31
31
  requirement.md 是需求事实来源,context 只保存续接摘要。业务变化先回 F2 更新清单、复核现状,再到 F3 更新需求文档;仅技术约束变化回 F3;只调整实现设计则更新 F4 的方案。需求重新收尾后,更新依赖它的方案并重新确认 / 验证。历史需求不自动从旧 plan.md 拆出正文;恢复旧运行时先核实并补齐需求文档。
32
32
 
@@ -46,6 +46,6 @@ requirement.md 是需求事实来源,context 只保存续接摘要。业务变
46
46
 
47
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 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
48
48
 
49
- **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。方案草稿通过 `<skills>/workflow/references/execution.md` 的 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 等用户确认并 save approval 后再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
49
+ **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。草稿按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」完成适用审查,再用 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 等用户确认并 save approval 后再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
50
50
 
51
51
  **HTTP 接口验证计划**:涉及新增 / 修改 HTTP 接口,或参数校验、鉴权、状态码、响应结构及接口业务行为变化时,在验证计划列出方法、路径、关联 AC 与待测场景:正常请求、参数错误(有入参约束时),以及适用的未登录 / 无权限场景。沿用现有框架,明确已有用例如何复用、哪些需要补充、执行命令和环境;F6 按计划编写并执行。纯内部重构且接口行为不变、已有覆盖充分时只列现有测试,不另建重复用例。缺陷修复在 B4 使用相同规则。
@@ -100,7 +100,7 @@ npx @rowansenne/workflow-run@latest doctor --offline
100
100
 
101
101
  这里用 `--copy` 在 `.codebuddy/skills/<skill>/` 生成真实目录和 `SKILL.md`,便于排除目录软链接的兼容问题。已有指向 `.agents/skills/` 的本工具链接会先转成独立拷贝,保留已填配置,再更新技能文件;共享来源和 Qwen 等其他环境的链接不变。后续 `upgrade` 沿用最近一次显式安装的环境和模式。只选择 WorkBuddy 时,全新安装不会生成 `.qwen/skills/`。
102
102
 
103
- 安装后,将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录,重新打开项目并新建会话,再尝试 `/workflow status`、`/dev` 或 `/project-review`。`/workflow profile` 等是技能参数,不是额外的独立技能。
103
+ 安装后,将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录,再新建任务。选择安装 `dev` 时,安装器会同时写入 `.codebuddy/commands/dev.md`,在输入框输入 `/` 可找到 `/dev`,也可输入 `/dev --bug <现象>`。已有同名命令原样保留。其他技能可在任务里显式指定,例如「使用 project-review 技能审查当前分支」。
104
104
 
105
105
  如果仍然不可见,先确认业务项目下确实有 `.codebuddy/skills/workflow/SKILL.md`,并保留安装命令、`doctor --offline` 输出与 WorkBuddy 版本以便排查。项目级配置目录见 [WorkBuddy 官方说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
106
106
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rowansenne/workflow-run",
3
- "version": "0.34.0",
3
+ "version": "0.35.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",
@@ -6,7 +6,8 @@ import { FILES, parseBranch } from './artifact-model.mjs';
6
6
  import { 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 } from './run-gates.mjs';
9
+ import { isDev, coreSteps, applyDevEvidence, assertRequirement, assertPlanBasis, assertReview, assertDelivery, reviewEvidence, documentReviewBasis } from './run-gates.mjs';
10
+ import { documentReviewEvidence, requiresDocumentReview } from './document-review.mjs';
10
11
  import { updateMeta } from './meta-store.mjs';
11
12
  import { OLD_DIR, indexArtifacts } from './requirements.mjs';
12
13
 
@@ -19,6 +20,15 @@ export const ARTIFACT_TEMPLATES = {
19
20
  const allowed = { feature: ['clarification', 'requirement', 'plan', 'review', 'delivery'], bug: ['clarification', 'requirement', 'plan', 'review', 'delivery'], review: ['review'], tech: ['tech'], release: ['release'] };
20
21
  const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
21
22
  const fileHash = (file) => fs.existsSync(file) ? hash(fs.readFileSync(file)) : null;
23
+ const wikiRecord = (s) => /^<!-- md-to-wiki: [^\n]*-->/.exec(s)?.[0] ?? null;
24
+
25
+ export function artifactDraft(req, kind, text) {
26
+ const file = path.join(req.abs, `${FILES[kind]}.md`);
27
+ const existingWiki = fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null;
28
+ const draftWiki = wikiRecord(text);
29
+ if (existingWiki && draftWiki && existingWiki !== draftWiki) throw new Error('新版必须保留原 wiki 页面记录;页面变更由 wiki 发布流程处理');
30
+ return { text: existingWiki && !draftWiki ? `${existingWiki}\n${text}` : text, existingWiki };
31
+ }
22
32
 
23
33
  export function resumeFinalization(root, { branch, id }) {
24
34
  const { req } = readRun(root, branch, id);
@@ -36,10 +46,12 @@ export function resumeFinalization(root, { branch, id }) {
36
46
  if (current !== p.before && current !== p.hash) throw new Error('正式产物在收尾中断后被其他操作修改,请先核对并恢复;不会覆盖');
37
47
  // 中断期间代码/报告也可能变化:发布前重新检查本轮门禁。
38
48
  const getSnapshot = snapshotReader(root, p.run);
39
- applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, { [p.kind]: fs.readFileSync(staged, 'utf8') }, getSnapshot);
40
- if (p.kind === 'plan') assertPlanBasis(root, req, p.run, { plan: fs.readFileSync(staged, 'utf8') });
49
+ const contents = { [p.kind]: fs.readFileSync(staged, 'utf8') };
50
+ applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, contents, getSnapshot);
51
+ if (p.kind === 'requirement') assertRequirement(root, req, p.run, contents);
52
+ if (p.kind === 'plan') assertPlanBasis(root, req, p.run, contents);
41
53
  if (p.kind === 'review' || (isDev(p.run) && p.kind === 'delivery')) {
42
- if (p.kind === 'review') assertReview(root, req, p.run, { review: fs.readFileSync(staged, 'utf8') }, getSnapshot);
54
+ if (p.kind === 'review') assertReview(root, req, p.run, contents, getSnapshot);
43
55
  else assertDelivery(root, req, p.run, undefined, getSnapshot);
44
56
  }
45
57
  if (current !== p.hash) {
@@ -91,11 +103,9 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
91
103
  if (!FILES[kind] || typeof text !== 'string') throw new Error('需要有效的产物 kind 和草稿正文');
92
104
  const { req } = readRun(root, branch, id);
93
105
  const file = path.join(req.abs, `${FILES[kind]}.md`);
94
- const wikiRecord = (s) => /^<!-- md-to-wiki: [^\n]*-->/.exec(s)?.[0] ?? null;
95
- const existingWiki = fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null;
96
- const draftWiki = wikiRecord(text);
97
- if (existingWiki && draftWiki && existingWiki !== draftWiki) throw new Error('新版必须保留原 wiki 页面记录;页面变更由 wiki 发布流程处理');
98
- if (existingWiki && !draftWiki) text = `${existingWiki}\n${text}`;
106
+ const draft = artifactDraft(req, kind, text);
107
+ const { existingWiki } = draft;
108
+ text = draft.text;
99
109
  const digest = hash(text);
100
110
  const key = hash(JSON.stringify({ id, revision, kind, digest, input, packet, result }));
101
111
  let repeated = null;
@@ -128,6 +138,9 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
128
138
  requirement = assertRequirement(root, req, run);
129
139
  if (run.steps[run.kind === 'feature' ? 'F3' : 'B3'].status !== 'completed') throw new Error('需求文档尚未完成,不能收尾方案');
130
140
  }
141
+ const documentReview = requiresDocumentReview(run, kind)
142
+ ? documentReviewEvidence(run, kind, digest, kind === 'plan' ? requirement : documentReviewBasis(root, req, run, kind), packet, result, at)
143
+ : null;
131
144
  if (isDev(run) && kind === 'delivery') assertDelivery(root, req, run, undefined, getSnapshot);
132
145
  if ((fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null) !== existingWiki) throw new Error('wiki 发布记录在收尾期间变化,请重新读取后重试');
133
146
  const before = fileHash(file);
@@ -135,6 +148,7 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
135
148
  const version = before === null ? 1 : oldVersion + (before === digest ? 0 : 1);
136
149
  const previous = before !== null && before !== digest ? relative(root, path.join(root, OLD_DIR, path.relative(path.join(root, 'workflow-run/docs/requirements'), req.abs), `${FILES[kind]}_v${oldVersion}.md`)) : null;
137
150
  run.artifacts = { ...(run.artifacts ?? {}), [kind]: { hash: digest, version, path: relative(root, file), previous, lint, at,
151
+ ...(documentReview ? { document_review: documentReview } : {}),
138
152
  ...(requirement ? { requirement: { hash: requirement.hash, version: requirement.version } } : {}) } };
139
153
  const clarificationChanged = kind === 'clarification' && current.artifacts?.clarification?.hash !== digest;
140
154
  if (clarificationChanged || (kind === 'plan' && (current.artifacts?.plan?.hash !== digest || current.artifacts?.plan?.requirement?.hash !== requirement.hash))
@@ -158,7 +172,7 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
158
172
  const staged = path.join(root, 'workflow-run/tmp/finalize', `${op}.md`);
159
173
  fs.mkdirSync(path.dirname(staged), { recursive: true });
160
174
  fs.writeFileSync(staged, text, { flag: 'wx' });
161
- return { ...meta, pending_finalization: { id: op, key, run_id: id, revision, kind, before, hash: digest, version, previous, staged: relative(root, staged), run, packet, checkpoint: input } };
175
+ return { ...meta, pending_finalization: { id: op, key, run_id: id, revision, kind, before, hash: digest, version, previous, staged: relative(root, staged), run, packet: kind === 'review' ? packet : null, checkpoint: input } };
162
176
  }, { root, allowFinalization: true });
163
177
  if (repeated) return repeated;
164
178
  return resumeFinalization(root, { branch, id });
@@ -0,0 +1,53 @@
1
+ import { hash } from './code-snapshot.mjs';
2
+
3
+ const stages = { feature: { requirement: 'F3', plan: 'F4' }, bug: { requirement: 'B3', plan: 'B4' } };
4
+ const nonempty = (value) => typeof value === 'string' && Boolean(value.trim());
5
+
6
+ export const documentReviewStage = (run, kind) => stages[run.kind]?.[kind];
7
+ export const requiresDocumentReview = (run, kind) =>
8
+ run.document_review_policy === 1 && ['M', 'L'].includes(run.size) && Boolean(documentReviewStage(run, kind));
9
+
10
+ export function documentReviewInputs(run, kind, draftHash, basis) {
11
+ return hash(JSON.stringify({
12
+ run_id: run.id, branch: run.branch, kind, draft_hash: draftHash,
13
+ basis: basis ? { hash: basis.hash, version: basis.version } : null,
14
+ }));
15
+ }
16
+
17
+ export function documentReviewEvidence(run, kind, draftHash, basis, packet, result, at) {
18
+ if (!packet || !result) throw new Error('本轮需要文档审查,请通过 --packet 和 --result 提交审查交接与结果');
19
+ const inputs = documentReviewInputs(run, kind, draftHash, basis);
20
+ const reviewedBasis = packet.basis;
21
+ const basisMatches = basis ? reviewedBasis?.path === basis.path && reviewedBasis.hash === basis.hash &&
22
+ reviewedBasis.version === basis.version && typeof reviewedBasis.text === 'string' && hash(reviewedBasis.text) === basis.hash
23
+ : reviewedBasis === null;
24
+ if (packet.run_id !== run.id || packet.kind !== kind || packet.inputs !== inputs ||
25
+ !Number.isInteger(packet.revision) || packet.revision < 1 || packet.revision > run.revision ||
26
+ packet.draft?.hash !== draftHash || typeof packet.draft.text !== 'string' || hash(packet.draft.text) !== draftHash || !basisMatches ||
27
+ result.run_id !== run.id || result.inputs !== inputs) {
28
+ throw new Error('文档审查不对应本轮草稿或其依据,请重新交接并审查');
29
+ }
30
+ if (!['independent', 'self'].includes(result.mode) || !nonempty(result.reviewer) || !nonempty(result.summary)) {
31
+ throw new Error('文档审查结果需要审查方式、审查者和结论');
32
+ }
33
+ if (result.mode === 'self' && (result.fallback?.confirmed !== true || !nonempty(result.fallback.reason))) {
34
+ throw new Error('自查降级须有用户明确同意及无法独立审查的原因');
35
+ }
36
+ if (!Array.isArray(result.findings) || result.findings.some((finding) =>
37
+ !nonempty(finding?.location) || !nonempty(finding.evidence) || !nonempty(finding.impact) ||
38
+ typeof finding.blocking !== 'boolean')) {
39
+ throw new Error('文档审查发现需要位置、依据、影响和 blocking 标记;没有发现时填空数组');
40
+ }
41
+ if (result.findings.some((finding) => finding.blocking)) throw new Error('文档审查仍有阻塞项,请修订并复审后再收尾');
42
+ 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 } } : {}),
45
+ };
46
+ }
47
+
48
+ export function assertDocumentReview(run, kind, artifact, basis) {
49
+ if (requiresDocumentReview(run, kind) &&
50
+ artifact.document_review?.inputs !== documentReviewInputs(run, kind, artifact.hash, basis)) {
51
+ throw new Error(`缺少当前版本的文档审查:${kind}.md;请重新审查并收尾`);
52
+ }
53
+ }
@@ -3,6 +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
7
 
7
8
  export const isDev = (run) => ['feature', 'bug'].includes(run.kind);
8
9
  export const coreSteps = (run) => run.kind === 'feature' ? ['F3', 'F4', 'F5', 'F6', 'F7', 'F8'] : ['B3', 'B4', 'B5'];
@@ -15,14 +16,24 @@ export function receipt(root, req, run, kind, contents = {}) {
15
16
  return record;
16
17
  }
17
18
 
19
+ export function documentReviewBasis(root, req, run, kind) {
20
+ if (kind === 'plan') return assertRequirement(root, req, run);
21
+ return run.artifacts?.clarification ? receipt(root, req, run, 'clarification') : null;
22
+ }
23
+
18
24
  export function assertRequirement(root, req, run, contents) {
19
- return receipt(root, req, run, 'requirement', contents);
25
+ const requirement = receipt(root, req, run, 'requirement', contents);
26
+ if (requiresDocumentReview(run, 'requirement')) {
27
+ assertDocumentReview(run, 'requirement', requirement, documentReviewBasis(root, req, run, 'requirement'));
28
+ }
29
+ return requirement;
20
30
  }
21
31
 
22
32
  export function assertPlanBasis(root, req, run, contents) {
23
33
  const requirement = assertRequirement(root, req, run, contents);
24
34
  const plan = receipt(root, req, run, 'plan', contents);
25
35
  if (plan.requirement?.hash !== requirement.hash || plan.requirement.version !== requirement.version) throw new Error('方案依据的需求版本已变化,请根据当前 requirement.md 重新收尾方案');
36
+ assertDocumentReview(run, 'plan', plan, requirement);
26
37
  return plan;
27
38
  }
28
39
 
@@ -101,7 +112,7 @@ export function applyDevEvidence(root, req, run, patch, at, contents = {}, getSn
101
112
  if (run.steps[requirementStep].status !== 'completed') throw new Error('需求文档尚未完成,不能进入方案/修复阶段');
102
113
  }
103
114
  if (run.kind === 'feature') {
104
- if (completed('F4')) receipt(root, req, run, 'plan', contents);
115
+ if (completed('F4')) assertPlanBasis(root, req, run, contents);
105
116
  if (patch.stage === 'F6' || completed('F5')) {
106
117
  const plan = assertPlan(root, req, run, contents);
107
118
  if (run.implementation?.plan !== plan.hash) throw new Error('尚未通过方案门禁进入实现');
@@ -125,7 +125,8 @@ export function startRun(root, { branch, kind = 'feature', size = null, input =
125
125
  selected = applyCheckpoint({ id, kind, size, branch, revision: 1, status: 'running', stage: FLOWS[kind][0],
126
126
  created_at: at, updated_at: at, completed_at: null, steps: Object.fromEntries(FLOWS[kind].map((s) => [s, { status: 'pending' }])),
127
127
  scope: { base: meta.base || profile?.main_branch || 'main', exclude: Array.isArray(profile?.review?.exclude) ? profile.review.exclude.filter((v) => typeof v === 'string') : [] },
128
- artifacts: {}, context: {}, waiting_for: null, reason: null, decision: null, history: [] }, input, at);
128
+ artifacts: {}, context: {}, waiting_for: null, reason: null, decision: null, history: [],
129
+ ...(['feature', 'bug'].includes(kind) ? { document_review_policy: 1 } : {}) }, input, at);
129
130
  applyDevEvidence(root, req, selected, input, at);
130
131
  return { ...meta, runs: { ...runs, [id]: selected }, updated: at };
131
132
  }, { root });
@@ -43,6 +43,23 @@ M / L 取得用户实际确认后,用 save 记录 `approval: {"confirmed":true
43
43
 
44
44
  需求变化回 F3(bug 回 B3)重新澄清并 finalize requirement;程序清除旧方案确认、实现、验证、审查和交付选择,旧方案不能作为新需求的依据。即使方案正文不变,也要在 F4 / B4 重新收尾以绑定新需求版本;M / L 重新取得方案确认。只改实现方式则仅更新 plan,不改 requirement。手动改需求正文而未收尾也会使后续证据校验失败。
45
45
 
46
+ ## 需求与方案审查
47
+
48
+ 运行记录有 `document_review_policy: 1` 且当前规模为 M / L 时执行。S 和没有该字段的升级前运行沿用原流程。新运行从 S 升为 M / L 后,如已有未审查的需求或方案,回对应阶段补审。需求在 F3 / B3 审查并完成用户理解确认后收尾;方案在 F4 / B4 审查后收尾,沿用现有方案确认,再开始实现。
49
+
50
+ 1. 草稿写到 tmp 后生成交接。需求用 `--kind requirement`,方案用 `--kind plan`。交接记录将要收尾的草稿正文及已登记的业务澄清或需求依据。
51
+
52
+ ```sh
53
+ node <skills>/workflow/scripts/review-handoff.mjs --id <id> --kind <requirement|plan> --draft <草稿.md>
54
+ ```
55
+
56
+ 2. 将输出的交接 `path` 及相关原始材料交给未参与起草的子 agent。要求它阅读交接里的草稿和依据正文,按需核对原始需求、已确认决定或相关代码。省去主 agent 的自评和预设发现。子 agent 只审查,按 `packet.result_schema` 返回结论、位置、依据、影响和阻塞标记。
57
+ - 需求审查核对范围、场景、规则、技术约束和可验证的验收标准。缺陷修复还要核对现象、根因证据和预期行为。
58
+ - 方案审查以交接中的已定稿需求为依据,核对各验收项的实现与验证安排,以及适用的兼容性、权限、数据和回滚风险。
59
+ 3. 主 agent 修订阻塞项,业务取舍交给用户或产品定。草稿或依据变化后重新生成交接,由独立审查者复核阻塞项及受影响内容,返回对应最终草稿的结论。一般建议按实际情况采纳或说明取舍。在交付给用户确认时附审查结论及阻塞项处理结果。
60
+ 4. 子 agent 不可用时停在本阶段,记录 `waiting_user`,让用户选择等待独立审查或允许本次自查。只有明确同意后才自查,结果写 `mode: "self"`、实际审查者和 `fallback: {"confirmed":true,"reason":"无法派出子 agent 的实际原因"}`。独立审查结果写 `mode: "independent"` 和实际子 agent 标识。程序校验记录及文档内容,实际派遣和用户同意由主 agent 如实记录。
61
+ 5. 将最终结果保存为 tmp 下的 JSON。执行本阶段的 `artifact.mjs finalize` 时额外传 `--packet <交接JSON路径> --result <结果JSON路径>`。收尾会拒绝缺失、过期或仍有阻塞项的结果。通过后审查证据随需求或方案版本写入本次运行的产物记录;F7 / B5 的代码审查仍按下文执行。
62
+
46
63
  ## 验证证据
47
64
 
48
65
  feature 实现完成后 save F5 completed,进入 F6;bug 在 B4 验证。**测试/操作执行前**生成快照:
@@ -6,8 +6,10 @@ import { spawnSync } from 'node:child_process';
6
6
  import { fileURLToPath } from 'node:url';
7
7
  import { readRun } from '../lib/runs.mjs';
8
8
  import { readProfile } from '../lib/project.mjs';
9
- import { snapshotReader, assertSnapshot, hash } from '../lib/code-snapshot.mjs';
10
- import { isDev, assertValidation, reviewInputs } from '../lib/run-gates.mjs';
9
+ import { snapshotReader, assertSnapshot, assertWorkingBranch, hash } from '../lib/code-snapshot.mjs';
10
+ import { isDev, assertValidation, reviewInputs, documentReviewBasis } from '../lib/run-gates.mjs';
11
+ import { documentReviewStage, documentReviewInputs, requiresDocumentReview } from '../lib/document-review.mjs';
12
+ import { artifactDraft } from '../lib/artifact-finalize.mjs';
11
13
  import { scope } from './review-scope.mjs';
12
14
 
13
15
  export function handoff(root, { branch, id, depth = '标准', capabilities = null }) {
@@ -38,19 +40,48 @@ export function handoff(root, { branch, id, depth = '标准', capabilities = nul
38
40
  };
39
41
  }
40
42
 
43
+ export function documentHandoff(root, { branch, id, kind, text }) {
44
+ const { req, run } = readRun(root, branch, id);
45
+ if (!requiresDocumentReview(run, kind) || ['completed', 'cancelled'].includes(run.status)) throw new Error('只有需要文档审查的进行中运行可生成此交接');
46
+ if (run.stage !== documentReviewStage(run, kind)) throw new Error(`请在 ${documentReviewStage(run, kind)} 阶段生成文档审查交接`);
47
+ if (req.meta.pending_finalization) throw new Error('先恢复待完成的产物收尾');
48
+ assertWorkingBranch(root, run);
49
+ const basis = documentReviewBasis(root, req, run, kind);
50
+ const basisText = basis ? fs.readFileSync(path.resolve(root, basis.path), 'utf8') : null;
51
+ if (basis && hash(basisText) !== basis.hash) throw new Error('文档审查依据在交接期间变化,请重新收尾后再试');
52
+ const draft = artifactDraft(req, kind, text);
53
+ const draftHash = hash(draft.text);
54
+ const inputs = documentReviewInputs(run, kind, draftHash, basis);
55
+ return {
56
+ run_id: id, revision: run.revision, project_root: path.resolve(root), branch, kind, inputs,
57
+ draft: { text: draft.text, hash: draftHash },
58
+ basis: basis ? { path: basis.path, hash: basis.hash, version: basis.version, text: basisText } : null,
59
+ result_schema: { run_id: id, inputs, mode: 'independent', reviewer: '实际子 agent 标识', summary: '审查结论与已复核修订',
60
+ findings: [{ location: '章节或验收编号', evidence: '依据及来源', impact: '实际影响', blocking: false }] },
61
+ };
62
+ }
63
+
41
64
  export function main(argv) {
42
65
  try {
43
66
  const args = [...argv]; const opts = {};
44
67
  while (args.length) {
45
68
  const key = args.shift();
46
- if (!['--root', '--branch', '--id', '--depth', '--capabilities'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
69
+ if (!['--root', '--branch', '--id', '--depth', '--capabilities', '--kind', '--draft'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
47
70
  opts[key.slice(2)] = args.shift();
48
71
  }
49
72
  const root = path.resolve(opts.root ?? '.');
50
73
  const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
51
- const capabilities = opts.capabilities ? JSON.parse(fs.readFileSync(path.resolve(root, opts.capabilities), 'utf8')) : null;
52
- const packet = handoff(root, { branch, id: opts.id, depth: opts.depth, capabilities });
53
- const file = path.join(root, 'workflow-run/tmp/review', packet.run_id, 'handoff.json');
74
+ let packet;
75
+ let fileName = 'handoff.json';
76
+ if (opts.kind || opts.draft) {
77
+ if (!['requirement', 'plan'].includes(opts.kind) || !opts.draft || opts.depth || opts.capabilities) throw new Error('文档审查使用 --kind requirement|plan --draft <草稿.md>');
78
+ packet = documentHandoff(root, { branch, id: opts.id, kind: opts.kind, text: fs.readFileSync(path.resolve(root, opts.draft), 'utf8') });
79
+ fileName = `${packet.kind}-${packet.inputs}.json`;
80
+ } else {
81
+ const capabilities = opts.capabilities ? JSON.parse(fs.readFileSync(path.resolve(root, opts.capabilities), 'utf8')) : null;
82
+ packet = handoff(root, { branch, id: opts.id, depth: opts.depth, capabilities });
83
+ }
84
+ const file = path.join(root, 'workflow-run/tmp/review', packet.run_id, fileName);
54
85
  fs.mkdirSync(path.dirname(file), { recursive: true });
55
86
  fs.writeFileSync(file, `${JSON.stringify(packet, null, 2)}\n`);
56
87
  console.log(JSON.stringify({ ok: true, path: path.relative(root, file).split(path.sep).join('/'), packet }, null, 2)); return 0;