@rowansenne/workflow-run 0.34.0 → 0.36.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.
Files changed (57) hide show
  1. package/CHANGELOG.md +31 -1
  2. package/README.md +2 -0
  3. package/bin/lib/artifact-context.mjs +1 -1
  4. package/bin/lib/docsrepo.mjs +4 -6
  5. package/bin/lib/doctor.mjs +0 -3
  6. package/bin/lib/install.mjs +15 -15
  7. package/bin/lib/uninstall.mjs +2 -0
  8. package/bin/lib/workbuddy.mjs +37 -0
  9. package/bin/workbuddy/dev.md +10 -0
  10. package/bin/workflow-run.mjs +3 -0
  11. package/create-release-md-doc/SKILL.md.tpl +1 -1
  12. package/create-tech-md-doc/SKILL.md.tpl +1 -1
  13. package/dev/SKILL.md.tpl +5 -4
  14. package/dev/references/bug.md +2 -2
  15. package/dev/references/clarify.md +1 -1
  16. package/dev/references/delivery.md +3 -3
  17. package/dev/references/planning.md +2 -2
  18. package/docs/architecture.html +3 -2
  19. package/docs/development.md +10 -4
  20. package/docs/full-install.html +90 -125
  21. package/docs/installation.md +2 -2
  22. package/docs/loan-service-install.html +90 -0
  23. package/docs/team-guide.md +3 -2
  24. package/docs/workflow-control-roadmap.md +144 -0
  25. package/docs/workflow-core-phase-one-report.md +41 -0
  26. package/docs/workflow-core-phase-one.md +317 -0
  27. package/docs/workflows.md +2 -2
  28. package/examples/workflow-core.mjs +26 -0
  29. package/package.json +2 -1
  30. package/project-review/SKILL.md.tpl +1 -1
  31. package/project-review/references/checklist.md.tpl +1 -1
  32. package/project-review/references/reporting.md +2 -2
  33. package/workflow/core/errors.mjs +61 -0
  34. package/workflow/core/index.mjs +286 -0
  35. package/workflow/core/review-handoff.mjs +101 -0
  36. package/workflow/integrations/skill-document-policy.mjs +28 -0
  37. package/workflow/lib/artifact-finalize.mjs +73 -20
  38. package/workflow/lib/code-snapshot.mjs +5 -0
  39. package/workflow/lib/document-review.mjs +53 -0
  40. package/workflow/lib/meta-store.mjs +12 -1
  41. package/workflow/lib/project.mjs +165 -14
  42. package/workflow/lib/requirements.mjs +57 -100
  43. package/workflow/lib/review-scope.mjs +262 -0
  44. package/workflow/lib/run-gates.mjs +13 -2
  45. package/workflow/lib/runs.mjs +13 -2
  46. package/workflow/lib/workspace-read.mjs +13 -4
  47. package/workflow/references/architecture.md +10 -5
  48. package/workflow/references/core-api.md +196 -0
  49. package/workflow/references/execution.md +21 -4
  50. package/workflow/references/profile.md +20 -0
  51. package/workflow/references/requirements.md +12 -12
  52. package/workflow/scripts/artifact.mjs +36 -14
  53. package/workflow/scripts/requirement.mjs +36 -40
  54. package/workflow/scripts/resolve.mjs +2 -2
  55. package/workflow/scripts/review-handoff.mjs +51 -44
  56. package/workflow/scripts/review-scope.mjs +78 -294
  57. package/workflow/scripts/run.mjs +21 -9
@@ -10,7 +10,7 @@
10
10
  {"scope":{"base":"main","exclude":["unrelated/**"]}}
11
11
  ```
12
12
 
13
- 完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 sync 代替收尾。模板由调用方用 `resolve.mjs template <skill> <id>` 读取,按 [templates.md](templates.md) 的「文档模板的两部分」填充正文。首次生成清单时用 dev 的 clarification-template.md,后续各轮把上一版正式清单复制到 tmp 更新,再发布:
13
+ 完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 reindex 代替收尾。模板由调用方用 `resolve.mjs template <skill> <id>` 读取,按 [templates.md](templates.md) 的「文档模板的两部分」填充正文。首次生成清单时用 dev 的 clarification-template.md,后续各轮把上一版正式清单复制到 tmp 更新,再发布:
14
14
 
15
15
  ```sh
16
16
  node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind clarification --draft workflow-run/tmp/clarification.md --input workflow-run/tmp/checkpoint.json
@@ -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 验证。**测试/操作执行前**生成快照:
@@ -96,13 +113,13 @@ feature 可在 checkpoint 标 F7 completed;bug 的 B5 此时仍 in_progress。
96
113
 
97
114
  只有该选择仍有效,才允许 `artifact.mjs finalize --kind delivery --draft ...`。审查后代码/基线变化或报告被修改,旧选择不能继续用;回 F6(bug 回 B4)、验证、复审、再次取得选择。修复回退会清除旧验证、审查与交付选择;方案改变则还须重新确认。
98
115
 
99
- 交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只 sync 后用旧收尾凭据 complete。
116
+ 交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只 reindex 后用旧收尾凭据 complete。
100
117
 
101
118
  ## 统一收尾与中断恢复
102
119
 
103
120
  finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运行 revision、阶段、分支和证据;通过后归档旧版、发布正式文件、更新版本/索引、登记运行证据。checkpoint 只能更新当前产物所属步骤、等待状态和上下文,不能夹带下游阶段或用户确认。输出正式 path、cite、previous、version、lint、run;自检警告和待填写项要告知用户,引用用 cite,归档遵循 requirements.md,不能替用户删除。
104
121
 
105
- 正式文档先写 tmp 草稿;不要先调用 `requirement.mjs path` 归档再直接覆盖,否则绕过收尾的中断保护。tech / release 分别在 T4 / L4 用 kind tech / release 收尾,使用各自的知识模板;wiki/沉淀后只更新发布或知识元信息仍可显式 sync。
122
+ 正式文档先写 tmp 草稿;旧 `requirement.mjs path` 入口已删除,不能通过直接覆盖正式文件绕过收尾中断保护。tech / release 分别在 T4 / L4 用 kind tech / release 收尾,使用各自的知识模板;wiki/沉淀后只更新发布或知识元信息仍可显式 reindex,但 reindex 不修复正文 hash 或旧证据。
106
123
 
107
124
  技术方案将生成时间、对比分支、diff 概览、PRD 参考和模板来源放在文件头的 `<!-- workflow-run: … -->` 多行注释中(格式见 create-tech-md-doc,整个块在前 20 行内),不要求正文显示元信息引用块。分支校验仍读取注释中的 `对比分支:`,索引日期读取其中的 `生成时间:`;旧文档的可见元信息继续兼容。注释随正式文件一起归档并参与 hash 校验,Wiki 转换时移除;`meta.json` 仍按现有逻辑记录绑定、索引和运行,不自动接收全部注释字段。
108
125
 
@@ -112,4 +129,4 @@ finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运
112
129
  node <skills>/workflow/scripts/artifact.mjs resume --id <id>
113
130
  ```
114
131
 
115
- 恢复会再次核对代码与正文,已发布的相同文件不重复升版本;原 finalize 命令重试也不会重复推进状态。恢复发现代码变化或正式文件被其他操作改动时,停下保留待办,不覆盖。需要放弃本次收尾时用 `artifact.mjs abort --id <id>`:只在文件仍是本操作原版/新版时恢复原版并清除待办;发生外部冲突则先人工核对。之后回退、重新验证/审查。临时副本保留在 tmp,不删除用户文件。
132
+ 命令会读取当前 pending 的目标 revision 和 operationId,再通过核心入口在锁内复核;读取后若待办已被替换,旧请求会明确失败,不会误处理新事务。恢复会再次核对代码与正文,已发布的相同文件不重复升版本;原 finalize 命令重试也不会重复推进状态。恢复发现代码变化或正式文件被其他操作改动时,停下保留待办,不覆盖。需要放弃本次收尾时用 `artifact.mjs abort --id <id>`:只在文件仍是本操作原版/新版时恢复原版并清除待办;发生外部冲突则先人工核对。之后回退、重新验证/审查。临时副本保留在 tmp,不删除用户文件。
@@ -2,6 +2,26 @@
2
2
 
3
3
  所有 skill 共用的项目事实,放在本 skill 目录下,**不含任何凭据**,可以提交到 git。缺失的字段一律视为空。
4
4
 
5
+ ## 多环境安装的配置来源
6
+
7
+ 用 `--copy` 同时安装 Claude、Qwen、WorkBuddy 等环境时,项目根下会有多份 `workflow/` 拷贝。配置解析顺序是:
8
+
9
+ 1. `workflow-run/profile-source.json` 的显式选择;
10
+ 2. `.agents/skills/workflow/`;
11
+ 3. 唯一存在的其他受支持安装目录;
12
+ 4. 多份副本的 `profile.json` 与 `profile.local.json` 完全相同时,按 `.agents` → `.claude` → `.qwen` → `.codebuddy` 固定顺序选择第一份。
13
+
14
+ 副本内容不同时核心操作会返回 `PROJECT_CONFIG_AMBIGUOUS`,不会按目录扫描顺序静默任选。明确选择来源:
15
+
16
+ ```sh
17
+ node .claude/skills/workflow/scripts/requirement.mjs config --profile-source claude
18
+ node .claude/skills/workflow/scripts/requirement.mjs config --profile-source qwen
19
+ node .claude/skills/workflow/scripts/requirement.mjs config --profile-source .qwen/skills/workflow
20
+ node .claude/skills/workflow/scripts/requirement.mjs config --profile-source auto
21
+ ```
22
+
23
+ 选择只接受目标项目内已存在的 `.agents/skills/workflow`、`.claude/skills/workflow`、`.qwen/skills/workflow`、`.codebuddy/skills/workflow`,写入可提交的 `workflow-run/profile-source.json`。`auto` 删除该文件;目录被重装删除后会报来源无效,重新选择即可。团队可提交显式选择,个人若只用另一个环境,也可以运行 `config --profile-source auto` 后重新选择自己的环境。
24
+
5
25
  | 字段 | 含义 | 谁在用 |
6
26
  |---|---|---|
7
27
  | `main_branch` | 主分支名,diff 基线 | dev、project-review、文档类 |
@@ -1,6 +1,6 @@
1
1
  # 产物按需求归档(dev / project-review / 技术方案 / 上线方案共用)
2
2
 
3
- 本约定只适用于工作流的正式需求产物。普通聊天生成的报告、分析、方案、草稿、导出等辅助文件默认放在项目根的 `workflow-run/other/`(可按主题建子目录,需要时创建),即使当前分支已绑定需求,也不调用 `bind / path / sync` 或 `run.mjs`,不写需求 `meta.json`,不进入需求统计和文档视图。单独执行 project-review、技术方案或上线方案等工作流仍按本约定归档。源码、测试、配置和已有文件的维护、工作流指定的临时目录与知识库沿用各自路径;用户明确指定输出路径时以用户为准,不自动搬移已有文件。
3
+ 本约定只适用于工作流的正式需求产物。普通聊天生成的报告、分析、方案、草稿、导出等辅助文件默认放在项目根的 `workflow-run/other/`(可按主题建子目录,需要时创建),即使当前分支已绑定需求,也不调用 `bind / reindex`、`run.mjs` 或 `artifact.mjs`,不写需求 `meta.json`,不进入需求统计和文档视图。单独执行 project-review、技术方案或上线方案等工作流仍按本约定归档。源码、测试、配置和已有文件的维护、工作流指定的临时目录与知识库沿用各自路径;用户明确指定输出路径时以用户为准,不自动搬移已有文件。
4
4
 
5
5
  一个需求的全部产物放在同一个目录,整条链路一眼看全,`/workflow view` 也直接读这里。本工具的产出都在项目根的 `workflow-run/` 里(需求产物、DocNexus 工作区、项目模板、临时文件),不往项目的其他地方写。默认 `workflow-run/` 随代码提交;团队也可以让 `workflow-run/` 成为独立的文档仓库,见最后一节。两种用法的目录结构完全一样(下图),切换时文件不用挪。
6
6
 
@@ -48,19 +48,19 @@ node <skills>/workflow/scripts/requirement.mjs which
48
48
 
49
49
  ## 运行状态
50
50
 
51
- 完整流程在本文件的 `runs` 中按运行 id 保存进度,关联分支;同一需求可有多次运行。`status: completed` 和 `completed_at` 是本次运行已完成的明确标记,步骤也单独记录 completed。保存/恢复和各 skill 的记录时机见 `runs.md`;快速通道不创建记录。`sync` 只重建产物索引,保留 runs 和其他扩展字段;重新 bind 也不会清空历史。元信息采用原子写入与短时写锁,状态更新另有 revision 检查。
51
+ 完整流程在本文件的 `runs` 中按运行 id 保存进度,关联分支;同一需求可有多次运行。`status: completed` 和 `completed_at` 是本次运行已完成的明确标记,步骤也单独记录 completed。保存/恢复和各 skill 的记录时机见 `runs.md`;快速通道不创建记录。`reindex` 只允许改 `artifacts`、`latest`、`indexed_at`,不改正文、versions、runs、revision、绑定、批准、证据和 `updated`;未登记固定文件写 `version: null, registered: false`。`which` 是只读查询,重新 bind 也不会清空历史。元信息采用原子写入与短时写锁,状态更新另有 revision 检查。
52
52
 
53
53
  ## 落盘
54
54
 
55
- 正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <clarification|requirement|plan|delivery|review|tech|release> --draft <草稿>` 收尾。命令校验阶段、分支与知识模板,归档旧版、更新索引/版本并登记证据;clarification 在 F2 / B3,发布不能代替阶段完成;requirement 在 F3 / B3;plan 在 F4 / B4,并绑定需求版本;review 还须 packet 与结构化 result,delivery 须有效交付选择。不要直接覆盖正式文件后只 sync。
55
+ 正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <clarification|requirement|plan|delivery|review|tech|release> --draft <草稿>` 收尾。命令校验阶段、分支与知识模板,归档旧版、更新索引/版本并登记证据;clarification 在 F2 / B3,发布不能代替阶段完成;requirement 在 F3 / B3;plan 在 F4 / B4,并绑定需求版本;review 还须 packet 与结构化 result,delivery 须有效交付选择。不要直接覆盖正式文件后只 reindex。
56
56
 
57
57
  - 输出 path(相对项目根)、cite(跨文档引用)、previous(上一版归档)、version 和 run。文件名固定,目录只留最新版;文档仓库模式的 cite 为「文档仓库名:仓库内路径」。
58
58
  - 旧版归档在 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`,不提交;告诉用户归档了什么,不替用户删除。相同命令重试不重复升级版本或状态。
59
59
  - 原文第一行的 md-to-wiki 页面记录自动保留,新版仍发布同一页;不能在普通文档收尾中替换页面归属。
60
- - 文件发布与元信息不能跨文件一次原子提交。待完成收尾保存在同一 meta.json;中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 越过待办。代码或正文冲突时停止,取消和恢复规则见 execution.md。
61
- - `requirement.mjs path <种类>` 仍保留为底层旧接口(会预先复制归档),不作为新流程的写入入口。查询已有产物用 artifacts / list,正式写入与 cite 用 finalize 输出。
62
- - wiki 发布或知识沉淀更新文档元信息后显式 `requirement.mjs sync <path>`。sync 重建索引并保留 runs;需求绑定只由 bind 修改,不根据文档头隐式新增。
63
- - 文档/索引不一致、元信息损坏或引用缺失进入只读诊断;文件存在不代表运行完成。确认正文后显式 sync,损坏的 meta 先人工核对修复。已有旧运行缺少新证据时回到对应阶段重新收尾/验证,不自动补用户确认。
60
+ - 文件发布与元信息不能跨文件一次原子提交。待完成收尾保存在同一 meta.json;中断先 `artifact.mjs resume --id <id>`,不能继续 reindex / save 越过待办。代码或正文冲突时停止,取消和恢复规则见 execution.md。
61
+ - 旧 `requirement.mjs path` 和 `sync` 写入命令已删除。查询已有产物用 artifacts / list,正式写入与 cite 用 finalize 输出。
62
+ - wiki 发布或知识沉淀更新文档元信息后显式 `requirement.mjs reindex`。它只重建派生索引并保留 runs、versions 和证据;需求绑定只由 bind 修改,不根据文档头隐式新增。
63
+ - 文档/索引不一致、元信息损坏或引用缺失进入只读诊断;文件存在不代表运行完成。确认正文后显式 reindex,损坏的 meta 先人工核对修复。已有旧运行缺少新证据时回到对应阶段重新收尾/验证,不自动补用户确认。
64
64
  - 独立文档仓库在允许提示提交的阶段运行 `requirement.mjs pending`,沿用下节规则;dev 内部审查延后到 F8。
65
65
 
66
66
  ## 独立文档仓库
@@ -76,17 +76,17 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
76
76
  - 布局和随代码提交时一样。绑定需求时 `which` 会列出 `other_projects`(其他服务已有、已拉到本地的需求),用同一个名字 `bind` 就加入了那个需求。
77
77
  - DocNexus 也在这个仓库里(`workflow-run/docnexus/`),各服务共用一个知识库。
78
78
  - `project`:这个项目在文档仓库里的名字,写在 `workflow/profile.json` 的 `artifacts.project`(随代码提交,团队共用),**只需配置一次**;随代码提交时已经自动写过的就直接沿用。没配时脚本退出码 2(`need_project`)并给出 `suggested_project`(git 远端仓库名):问用户一次,然后运行 `requirement.mjs config --project <项目名>`,之后一直沿用。
79
- - 查看或修改配置:`requirement.mjs config [--project <项目名>] [--commit-prompt on|off] [--local]`。
79
+ - 查看或修改配置:`requirement.mjs config [--project <项目名>] [--commit-prompt on|off] [--profile-source <环境|路径|auto>] [--local]`。多环境 `--copy` 的 profile 内容不同时,用 `--profile-source` 选择;选择和候选见 [profile.md](profile.md)。
80
80
  - `/workflow view` 在这个模式下显示文档仓库里所有项目的需求,一个需求下按项目区分产物。
81
81
 
82
82
  ## 文档仓库的提交
83
83
 
84
- 文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。finalize 后运行 pending(或旧 sync 返回 commit 非空)时:
84
+ 文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。finalize 或 reindex 后运行 pending 时:
85
85
 
86
86
  **dev F7 审查例外**:审查环节(独立子 agent 或当前会话自查)拿到 `commit` 信息后不询问、不执行文档提交,先交审查报告、等待用户选择修复或交付。选择交付进入 F8 后(完整流程;S 快速通道不落盘,没有待提交产物),再运行 `requirement.mjs pending` 获取当前待提交内容,按下面步骤询问;修复与复审期间继续延后,不改动 `commit_prompt` 配置。
87
87
 
88
- 1. 把 pending 的 `files`(旧 sync 为 commit.files)和 `suggested_message` 给用户看,问要不要提交。
89
- 2. 用户确认后,按 pending 的 `commands`(旧 sync 为 commit.commands) 在文档仓库里提交;推送另外问用户,用户同意后再 `git -C workflow-run push`。
88
+ 1. 把 pending 的 `files` 和 `suggested_message` 给用户看,问要不要提交。
89
+ 2. 用户确认后,按 pending 的 `commands` 在文档仓库里提交;推送另外问用户,用户同意后再 `git -C workflow-run push`。
90
90
  3. 用户不想现在提交就跳过,不再追问;之后随时可以运行 `requirement.mjs pending` 看还有哪些没提交。
91
91
 
92
- 不想被提示的人可以关掉:`requirement.mjs config --commit-prompt off --local`。这个设置写在 `workflow/profile.local.json`(个人设置,不提交,只影响自己);去掉 `--local` 则写进 `profile.json`,对整个团队生效。关掉后 sync 不再输出 `commit`,产物照常写到文档仓库,由自己决定什么时候提交。
92
+ 不想被提示的人可以关掉:`requirement.mjs config --commit-prompt off --local`。这个设置写在 `workflow/profile.local.json`(个人设置,不提交,只影响自己);去掉 `--local` 则写进 `profile.json`,对整个团队生效。关掉后 pending 仍可查询,但不主动提示提交,产物照常写到文档仓库,由自己决定什么时候提交。
@@ -4,9 +4,9 @@ import fs from 'node:fs';
4
4
  import path from 'node:path';
5
5
  import { spawnSync } from 'node:child_process';
6
6
  import { fileURLToPath } from 'node:url';
7
- import { resolveTemplate, skillMeta } from './resolve.mjs';
8
- import { lint } from './lint-doc.mjs';
9
- import { ARTIFACT_TEMPLATES, finalizeArtifact, resumeFinalization, abortFinalization } from '../lib/artifact-finalize.mjs';
7
+ import { createWorkflow } from '../core/index.mjs';
8
+ import { createSkillDocumentPolicy } from '../integrations/skill-document-policy.mjs';
9
+ import { ARTIFACT_TEMPLATES } from '../lib/artifact-finalize.mjs';
10
10
 
11
11
  export function main(argv) {
12
12
  try {
@@ -19,21 +19,43 @@ export function main(argv) {
19
19
  const root = path.resolve(opts.root ?? '.');
20
20
  const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
21
21
  const read = (p) => p ? JSON.parse(fs.readFileSync(p === '-' ? 0 : path.resolve(root, p), 'utf8')) : undefined;
22
+ const workflow = createWorkflow({ root, documentPolicy: createSkillDocumentPolicy(root) });
23
+ const pendingRequest = () => {
24
+ const state = workflow.runs.status({ branch, id: opts.id });
25
+ if (!state.pending) throw new Error(`没有该运行待处理的产物收尾:${opts.id}`);
26
+ return {
27
+ branch,
28
+ id: opts.id,
29
+ expectedRevision: state.pending.runRevision,
30
+ operationId: state.pending.operationId,
31
+ };
32
+ };
22
33
  let out;
23
- if (action === 'resume') out = resumeFinalization(root, { branch, id: opts.id });
24
- else if (action === 'abort') out = abortFinalization(root, { branch, id: opts.id });
34
+ if (action === 'resume') out = workflow.artifacts.resume(pendingRequest());
35
+ else if (action === 'abort') out = workflow.artifacts.abort(pendingRequest());
25
36
  else if (action === 'finalize') {
26
- const [skill, template] = ARTIFACT_TEMPLATES[opts.kind] ?? [];
27
- if (!skill || !opts.draft) throw new Error('finalize 需要 --kind clarification|requirement|plan|review|delivery|tech|release 和 --draft <草稿.md>');
28
- const resolved = resolveTemplate(root, skill, template);
29
- if (!resolved.ok) throw new Error(resolved.hint ?? JSON.stringify(resolved));
30
- const source = fs.readFileSync(path.resolve(root, resolved.path), 'utf8');
31
- const rules = skillMeta(skill).templates.find((t) => t.id === template).lint;
32
- out = finalizeArtifact(root, { branch, id: opts.id, revision: Number(opts['expect-revision']), kind: opts.kind,
33
- text: fs.readFileSync(path.resolve(root, opts.draft), 'utf8'), input: read(opts.input) ?? {}, packet: read(opts.packet), result: read(opts.result) }, (text) => lint(text, source, rules));
37
+ if (!ARTIFACT_TEMPLATES[opts.kind] || !opts.draft) throw new Error('finalize 需要 --kind clarification|requirement|plan|review|delivery|tech|release 和 --draft <草稿.md>');
38
+ out = workflow.artifacts.finalize({
39
+ branch,
40
+ id: opts.id,
41
+ expectedRevision: Number(opts['expect-revision']),
42
+ kind: opts.kind,
43
+ text: fs.readFileSync(path.resolve(root, opts.draft), 'utf8'),
44
+ input: read(opts.input) ?? {},
45
+ packet: read(opts.packet) ?? null,
46
+ result: read(opts.result) ?? null,
47
+ });
34
48
  } else throw new Error('用法:artifact.mjs finalize --id <id> --expect-revision <n> --kind <种类> --draft <草稿> [--input <checkpoint.json>] [--packet <handoff.json> --result <审查结果.json>] | resume --id <id> | abort --id <id>');
35
49
  console.log(JSON.stringify(out, null, 2)); return 0;
36
- } catch (e) { console.error(e.message); return 1; }
50
+ } catch (error) {
51
+ console.error(JSON.stringify({
52
+ ok: false,
53
+ ...(error.code ? { code: error.code } : {}),
54
+ message: error.message,
55
+ ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}),
56
+ }, null, 2));
57
+ return 1;
58
+ }
37
59
  }
38
60
  const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
39
61
  if (invoked) process.exit(main(process.argv.slice(2)));
@@ -8,17 +8,13 @@
8
8
  // - 默认:workflow-run/ 随代码提交;项目名没配置时取 git 远端仓库名(第一次 bind 时写进 profile.json,之后固定)
9
9
  // - 独立文档仓库:团队文档仓库克隆到 workflow-run/(它自己是 git 仓库,代码仓库忽略它),项目名要先配置(各服务在同一个仓库里,名字由团队定);
10
10
  // 文档仓库单独提交(写完由用户确认,可用 artifacts.commit_prompt 关闭提交提示)
11
- // 需求目录写进项目根 .ignore,不参与代码搜索。旧版本(随代码提交时没有 <项目名>/ 这一层)的产物由安装器 upgrade 时迁移(migrateLayout)
12
11
  // 需求名由用户在流程开始或第一次落盘时给出;用户不给时按分支名生成。分支 → 需求的绑定记在 meta.json 的 branches。
13
12
  // 说明见 workflow/references/requirements.md。
14
13
  //
15
14
  // 用法(在项目根执行;--root 可指定项目根;--branch 缺省为当前 git 分支):
16
15
  // requirement.mjs which [--branch b] # 当前分支绑定的需求;没绑定时给出建议名、最近的需求(文档仓库模式还列出其他项目的需求)
17
16
  // requirement.mjs bind [--name <需求名>] [--branch b] [--base m] # 绑定(没有就新建);不给 --name 按分支名生成
18
- // requirement.mjs path <clarification|requirement|plan|delivery|review|tech|release> [--branch b] # 本次落盘的文件路径(文件名固定;已有时上一版复制到
19
- // # workflow-run/tmp/old-artifacts/<种类>_v<N>.md,输出 previous)
20
- // requirement.mjs sync [<需求目录或其中的文件> | --all] # 按目录里的文件重建 meta.json;指定了目录 / 文件时确认新版本号、输出归档了哪些上一版;
21
- // # 文档仓库模式下带上提交提示
17
+ // requirement.mjs reindex [--branch b | --all] # 只重建派生索引;不改正文、版本、运行状态或证据
22
18
  // requirement.mjs pending [--branch b] # 文档仓库模式:当前需求在文档仓库里未提交的改动与建议的提交命令
23
19
  // requirement.mjs list # 所有需求(名称、分支、产物数、更新时间)
24
20
  // requirement.mjs config [--project <项目名>] [--commit-prompt on|off] [--local] # 查看 / 修改产物配置
@@ -28,12 +24,12 @@ import fs from 'node:fs';
28
24
  import path from 'node:path';
29
25
  import { spawnSync } from 'node:child_process';
30
26
  import { fileURLToPath } from 'node:url';
31
- import { HOME, setConfig, artifactsConfig, layout } from '../lib/project.mjs';
32
- import { which, bind, nextPath, list, pending, sync } from '../lib/requirements.mjs';
33
- import { requirements, find } from '../lib/requirement-read.mjs';
34
- export { HOME, REQ_DIR, TEMPLATES_DIR, TMP_DIR, IGNORE_LINE, homeDir, homeIsRepo, dirName, profileDir, artifactsConfig, layout, suggestProject, setConfig, ensureIgnore } from '../lib/project.mjs';
27
+ import { createWorkflow } from '../core/index.mjs';
28
+ import { HOME, setConfig, artifactsConfig, layout, setProfileSource, profileSources } from '../lib/project.mjs';
29
+ import { list, pending } from '../lib/requirements.mjs';
30
+ export { HOME, REQ_DIR, TEMPLATES_DIR, TMP_DIR, PROFILE_SOURCE, IGNORE_LINE, homeDir, homeIsRepo, dirName, profileDir, artifactsConfig, layout, suggestProject, setConfig, setProfileSource, profileSources, ensureIgnore } from '../lib/project.mjs';
35
31
  export { requirements, repoRequirements, artifactFiles, find } from '../lib/requirement-read.mjs';
36
- export { OLD_DIR, sync, which, bind, nextPath, list, pending, legacyRequirements, migrateLayout } from '../lib/requirements.mjs';
32
+ export { OLD_DIR, list, pending } from '../lib/requirements.mjs';
37
33
  export { FILES, parseFile, parseBranch, parseDocnexus } from '../lib/artifact-model.mjs';
38
34
  function currentBranch(root) {
39
35
  const r = spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' });
@@ -41,7 +37,7 @@ function currentBranch(root) {
41
37
  }
42
38
 
43
39
  // ------------------------------------------------------------------ CLI
44
- const USAGE = '用法: requirement.mjs which | bind [--name <需求名>] | path <clarification|requirement|plan|delivery|review|tech|release> | sync [<目录|文件> | --all] | pending | list | config [--project <名>] [--commit-prompt on|off] [--local] (通用:--root <项目根> --branch <分支>)';
40
+ const USAGE = '用法: requirement.mjs which | bind [--name <需求名>] | reindex [--all] | pending | list | config [--project <名>] [--commit-prompt on|off] [--profile-source <环境|路径|auto>] [--local] (通用:--root <项目根> --branch <分支>)';
45
41
 
46
42
  function main(argv) {
47
43
  let root = process.cwd();
@@ -50,55 +46,55 @@ function main(argv) {
50
46
  for (let i = 0; i < argv.length; i++) {
51
47
  const a = argv[i];
52
48
  if (a === '--root') root = path.resolve(argv[++i] ?? '.');
53
- else if (['--name', '--branch', '--base', '--repo', '--project', '--commit-prompt'].includes(a)) { if (i + 1 >= argv.length) { console.error(USAGE); return 1; } o[a.slice(2)] = argv[++i]; }
49
+ else if (['--name', '--branch', '--base', '--repo', '--project', '--commit-prompt', '--profile-source'].includes(a)) { if (i + 1 >= argv.length) { console.error(USAGE); return 1; } o[a.slice(2)] = argv[++i]; }
54
50
  else if (a === '--all' || a === '--local') o[a.slice(2)] = true;
55
51
  else if (a.startsWith('--')) { console.error(USAGE); return 1; }
56
52
  else pos.push(a);
57
53
  }
58
54
  const [cmd, arg] = pos;
59
55
  const branch = o.branch ?? currentBranch(root);
56
+ const workflow = createWorkflow({ root });
60
57
  const print = (x, code = 0) => { console.log(JSON.stringify(x, null, 2)); return code; };
61
58
  const ready = (x) => (x.ok === false && x.need_project ? 2 : 0);
62
- switch (cmd) {
63
- case 'which': { const r = which(root, branch); return print(r, ready(r)); }
64
- case 'bind': { const r = bind(root, { name: o.name, branch, base: o.base }); return print(r, r.ok ? 0 : ready(r) || 1); }
65
- case 'path': { const r = nextPath(root, arg, branch); return print(r.out, r.code); }
59
+ try {
60
+ switch (cmd) {
61
+ case 'which': { const r = workflow.requirements.which({ branch }); return print(r, ready(r)); }
62
+ case 'bind': { const r = workflow.requirements.bind({ name: o.name, branch, base: o.base }); return print(r, r.ok ? 0 : ready(r) || 1); }
63
+ case 'reindex': {
64
+ if (!o.all && !branch) { console.error('无法确定当前分支,请用 --branch 指定或使用 --all'); return 1; }
65
+ const r = workflow.maintenance.reindex({ branch, all: !!o.all });
66
+ return print(r, r.ok === false ? 1 : 0);
67
+ }
66
68
  case 'list': return print(list(root));
67
69
  case 'pending': { const r = pending(root, branch); return print(r, ready(r)); }
68
70
  case 'config': {
69
71
  const patch = {};
72
+ let source = null;
70
73
  if (o.repo !== undefined) { console.error(`--repo 已不再支持:独立文档仓库改为把团队文档仓库克隆到项目根的 ${HOME}/(见 workflow/references/requirements.md)`); return 1; }
71
74
  if (o.project !== undefined) patch.project = o.project;
72
75
  if (o['commit-prompt'] !== undefined) {
73
76
  if (!['on', 'off'].includes(o['commit-prompt'])) { console.error('--commit-prompt 取 on / off'); return 1; }
74
77
  patch.commit_prompt = o['commit-prompt'] === 'on';
75
78
  }
76
- if (!Object.keys(patch).length) { const L = layout(root); const c = artifactsConfig(root); return print({ mode: L.mode, repo: L.repo_rel ?? null, project: L.project, commit_prompt: c.commit_prompt, ok: L.ok, hint: L.ok ? null : L.hint }); }
77
- return print(setConfig(root, patch, { local: !!o.local }));
78
- }
79
- case 'sync': {
80
- const L = layout(root);
81
- if (o.all) return print(requirements(root, L).map((r) => ({ dir: r.dir, artifacts: sync(root, r.dir).artifacts.length })));
82
- let target = null;
83
- if (arg) {
84
- const abs = path.resolve(root, arg);
85
- target = requirements(root, L).find((r) => abs === r.abs || abs.startsWith(r.abs + path.sep)) ?? null;
86
- } else target = find(root, branch, L);
87
- if (!target) { console.error('不在当前项目的需求目录下,或当前分支没有绑定需求'); return 1; }
88
- const m = sync(root, target.dir, { bump: true });
89
- const out = { dir: target.dir, name: m.name, artifacts: m.artifacts.length, latest: m.latest, versions: m.versions ?? {} };
90
- if (m.archived.length) {
91
- const to = path.posix.dirname(m.archived[0].file);
92
- out.archived = { files: m.archived, dir: to, hint: `上一版已归档到 ${to}/(不提交),目录里只留最新版。告诉用户归档了哪些文件,请用户确认不再需要后自己删除;不要替用户删` };
93
- }
94
- // 文档仓库模式:写完产物后提示提交(由用户确认;artifacts.commit_prompt 关闭时不提示)
95
- if (L.mode === 'repo') {
96
- const pd = pending(root, branch, target.dir);
97
- out.commit = pd.commit_prompt && pd.files?.length ? { repo: pd.repo, files: pd.files, suggested_message: pd.suggested_message, commands: pd.commands, hint: '文档仓库有未提交的产物:把改动和建议的提交信息给用户看,用户确认后再执行 commands;推送另外问用户' } : null;
79
+ if (o['profile-source'] !== undefined) source = setProfileSource(root, o['profile-source']);
80
+ if (!Object.keys(patch).length) {
81
+ if (source) return print(source);
82
+ const L = layout(root); const c = artifactsConfig(root);
83
+ return print({ mode: L.mode, repo: L.repo_rel ?? null, project: L.project, commit_prompt: c.commit_prompt, profile_source: c.profile_source, candidates: profileSources(root), ok: L.ok, hint: L.ok ? null : L.hint });
98
84
  }
99
- return print(out);
85
+ const configured = setConfig(root, patch, { local: !!o.local });
86
+ return print(source ? { ...configured, profile_source: source } : configured);
87
+ }
88
+ default: console.error(USAGE); return 1;
100
89
  }
101
- default: console.error(USAGE); return 1;
90
+ } catch (error) {
91
+ console.error(JSON.stringify({
92
+ ok: false,
93
+ ...(error.code ? { code: error.code } : {}),
94
+ message: error.message,
95
+ ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}),
96
+ }, null, 2));
97
+ return 1;
102
98
  }
103
99
  }
104
100
 
@@ -98,7 +98,7 @@ export function status(root) {
98
98
  // 已安装的 skill(--skills 子集安装时只有一部分),路由前据此判断目标 skill 是否可用
99
99
  skills: skillMetas().map((m) => m.name),
100
100
  // 本机系统与终端(安装时记录),写命令按它来
101
- env: readEnv(),
101
+ env: readEnv(root),
102
102
  profile: { ok: p.complete, empty: p.empty, how: p.complete ? null : '运行 /workflow profile' },
103
103
  // 开发环境配置:只在配过时给出(没配不算问题,构建跑不起来时才需要)
104
104
  toolchain: p.toolchain.configured
@@ -147,7 +147,7 @@ function main(argv) {
147
147
  case 'env':
148
148
  // env(默认):本机系统与终端;--check:核对画像里的开发环境配置在本机是否存在
149
149
  if (rest.includes('--check') || rest.includes('--resolve')) { print(checkToolchain(root)); return 0; }
150
- print(readEnv()); return 0;
150
+ print(readEnv(root)); return 0;
151
151
  }
152
152
  console.error('用法: resolve.mjs [--root <项目根>] template <skill> <文件名> | templates | profile | infer-profile | category <skill> | status | env [--check]');
153
153
  return 1;
@@ -4,57 +4,64 @@ import fs from 'node:fs';
4
4
  import path from 'node:path';
5
5
  import { spawnSync } from 'node:child_process';
6
6
  import { fileURLToPath } from 'node:url';
7
- import { readRun } from '../lib/runs.mjs';
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';
11
- import { scope } from './review-scope.mjs';
12
7
 
13
- export function handoff(root, { branch, id, depth = '标准', capabilities = null }) {
14
- const { req, run } = readRun(root, branch, id);
15
- if (!['feature', 'bug', 'review'].includes(run.kind) || ['completed', 'cancelled'].includes(run.status)) throw new Error('只有进行中的开发/审查运行可生成交接材料');
16
- if (req.meta.pending_finalization) throw new Error('先恢复待完成的产物收尾');
17
- const getSnapshot = snapshotReader(root, run);
18
- if (isDev(run)) {
19
- if (run.stage !== (run.kind === 'feature' ? 'F7' : 'B5')) throw new Error('请先完成验证并进入审查阶段');
20
- assertValidation(root, req, run, undefined, getSnapshot);
21
- }
22
- if (!['快审', '标准', '深审'].includes(depth)) throw new Error('审查深度须为快审 / 标准 / 深审');
23
- const snapshot = getSnapshot();
24
- const reviewScope = scope(root, { base: run.scope?.base ?? 'main', exclude: run.scope?.exclude ?? [] });
25
- if (!reviewScope.ok) throw new Error(reviewScope.error);
26
- assertSnapshot(root, run, snapshot);
27
- const profile = readProfile(root).profile;
28
- const inputs = reviewInputs(run);
29
- return {
30
- run_id: id, revision: run.revision, project_root: path.resolve(root), skills: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'),
31
- branch, depth, snapshot, inputs: hash(JSON.stringify(inputs)), scope: reviewScope, requirement: req.name, facts: inputs.facts,
32
- requirement_document: run.artifacts?.requirement ?? null, plan: run.artifacts?.plan ?? null, previous_report: run.artifacts?.review ?? null,
33
- validation: run.validation ?? null,
34
- commands: Object.fromEntries(['main_branch', 'build', 'test', 'test_single', 'lint'].map((k) => [k, profile?.[k] ?? null])),
35
- capabilities,
36
- result_schema: { run_id: id, code: snapshot.digest, inputs: hash(JSON.stringify(inputs)), findings: [{ id: '唯一编号', severity: 'CRITICAL|HIGH|MEDIUM|LOW', verification: 'confirmed|pending', scope: 'in_scope|outside(范围外发现单列)', file: '真实路径', line: 1, summary: '触发条件与影响' }], coverage: { reviewed: ['已审文件'], uncovered: ['未审文件'] } },
37
- rules: '独立读代码,按 project-review 第 1~7 步审查;返回报告草稿和结构化结果,不改代码、不生成 delivery.md、不提交、不另建运行;主 agent 负责 finalize。零发现 findings 为空数组,scope.review 中每个文件必须进入 reviewed 或 uncovered。',
38
- };
39
- }
8
+ import { createWorkflow } from '../core/index.mjs';
9
+ import {
10
+ createCodeHandoff,
11
+ createDocumentHandoff,
12
+ writeReviewPacket,
13
+ } from '../core/review-handoff.mjs';
14
+
15
+ export const handoff = createCodeHandoff;
16
+ export const documentHandoff = createDocumentHandoff;
40
17
 
41
18
  export function main(argv) {
42
19
  try {
43
- const args = [...argv]; const opts = {};
20
+ const args = [...argv];
21
+ const options = {};
44
22
  while (args.length) {
45
23
  const key = args.shift();
46
- if (!['--root', '--branch', '--id', '--depth', '--capabilities'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
47
- opts[key.slice(2)] = args.shift();
24
+ if (!['--root', '--branch', '--id', '--depth', '--capabilities', '--kind', '--draft'].includes(key) || !args.length) {
25
+ throw new Error(`未知或缺少值的参数:${key}`);
26
+ }
27
+ options[key.slice(2)] = args.shift();
28
+ }
29
+ const root = path.resolve(options.root ?? '.');
30
+ const branch = options.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
31
+ if (!options.id) throw new Error('需要 --id <运行id>');
32
+ const capabilities = options.capabilities
33
+ ? JSON.parse(fs.readFileSync(path.resolve(root, options.capabilities), 'utf8'))
34
+ : null;
35
+ if (options.kind || options.draft) {
36
+ if (!['requirement', 'plan'].includes(options.kind) || !options.draft || options.depth || options.capabilities) {
37
+ throw new Error('文档审查使用 --kind requirement|plan --draft <草稿.md>');
38
+ }
48
39
  }
49
- const root = path.resolve(opts.root ?? '.');
50
- 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');
54
- fs.mkdirSync(path.dirname(file), { recursive: true });
55
- fs.writeFileSync(file, `${JSON.stringify(packet, null, 2)}\n`);
56
- console.log(JSON.stringify({ ok: true, path: path.relative(root, file).split(path.sep).join('/'), packet }, null, 2)); return 0;
57
- } catch (e) { console.error(e.message); return 1; }
40
+ const text = options.draft ? fs.readFileSync(path.resolve(root, options.draft), 'utf8') : null;
41
+ const workflow = createWorkflow({ root });
42
+ const packet = workflow.reviews.prepare({
43
+ branch,
44
+ id: options.id,
45
+ kind: options.kind ?? null,
46
+ text,
47
+ depth: options.depth ?? '标准',
48
+ capabilities,
49
+ });
50
+ const out = { ok: true, path: packet.path, packet: packet.packet };
51
+ console.log(JSON.stringify(out, null, 2));
52
+ return 0;
53
+ } catch (error) {
54
+ console.error(JSON.stringify({
55
+ ok: false,
56
+ ...(error.code ? { code: error.code } : {}),
57
+ message: error.message,
58
+ ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}),
59
+ }, null, 2));
60
+ return 1;
61
+ }
58
62
  }
63
+
64
+ export { writeReviewPacket };
65
+
59
66
  const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
60
67
  if (invoked) process.exit(main(process.argv.slice(2)));