@rowansenne/workflow-run 0.35.0 → 0.36.1
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 +29 -1
- package/README.md +2 -0
- package/bin/lib/artifact-context.mjs +1 -1
- package/bin/lib/docsrepo.mjs +4 -6
- package/bin/lib/doctor.mjs +0 -3
- package/bin/lib/install.mjs +15 -15
- package/create-release-md-doc/SKILL.md.tpl +1 -1
- package/create-tech-md-doc/SKILL.md.tpl +1 -1
- package/dev/SKILL.md.tpl +5 -5
- package/dev/references/bug.md +2 -2
- package/dev/references/clarify.md +2 -2
- package/dev/references/delivery.md +3 -3
- package/dev/references/planning.md +3 -3
- package/docs/architecture.html +3 -2
- package/docs/development.md +10 -4
- package/docs/full-install.html +90 -125
- package/docs/installation.md +1 -1
- package/docs/loan-service-install.html +90 -0
- package/docs/team-guide.md +3 -2
- package/docs/workflow-control-roadmap.md +144 -0
- package/docs/workflow-core-phase-one-report.md +41 -0
- package/docs/workflow-core-phase-one.md +317 -0
- package/docs/workflows.md +2 -2
- package/examples/workflow-core.mjs +26 -0
- package/package.json +2 -1
- package/project-review/SKILL.md.tpl +1 -1
- package/project-review/references/checklist.md.tpl +1 -1
- package/project-review/references/reporting.md +2 -2
- package/workflow/core/errors.mjs +61 -0
- package/workflow/core/index.mjs +286 -0
- package/workflow/core/review-handoff.mjs +102 -0
- package/workflow/integrations/skill-document-policy.mjs +28 -0
- package/workflow/lib/artifact-finalize.mjs +49 -10
- package/workflow/lib/code-snapshot.mjs +5 -0
- package/workflow/lib/meta-store.mjs +12 -1
- package/workflow/lib/project.mjs +165 -14
- package/workflow/lib/requirements.mjs +57 -100
- package/workflow/lib/review-scope.mjs +262 -0
- package/workflow/lib/runs.mjs +11 -1
- package/workflow/lib/workspace-read.mjs +13 -4
- package/workflow/references/architecture.md +10 -5
- package/workflow/references/core-api.md +196 -0
- package/workflow/references/execution.md +16 -14
- package/workflow/references/profile.md +20 -0
- package/workflow/references/requirements.md +12 -12
- package/workflow/references/runs.md +1 -1
- package/workflow/scripts/artifact.mjs +36 -14
- package/workflow/scripts/requirement.mjs +36 -40
- package/workflow/scripts/resolve.mjs +2 -2
- package/workflow/scripts/review-handoff.mjs +49 -73
- package/workflow/scripts/review-scope.mjs +78 -294
- package/workflow/scripts/run.mjs +21 -9
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
{"scope":{"base":"main","exclude":["unrelated/**"]}}
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用
|
|
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
|
|
@@ -30,35 +30,37 @@ 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
45
|
|
|
46
46
|
## 需求与方案审查
|
|
47
47
|
|
|
48
|
-
|
|
48
|
+
M / L 在 F3 / B3 确认需求草稿,在 F4 / B4 确认方案草稿。运行有 `document_review_policy: 1` 时,两份文档各自在确认后做独立审查,再正式收尾。S 和没有该字段的升级前运行无需新增独立文档审查。新运行从 S 升为 M / L 后,如已有未审查的需求或方案,回对应阶段补审。
|
|
49
49
|
|
|
50
|
-
1. 草稿写到 tmp
|
|
50
|
+
1. **先讨论草稿。** 草稿写到 tmp,给用户草稿链接或重点摘要。收到明确修改意见就直接更新,回复改了哪些内容。只询问真正未决的取舍;继续讨论期间不生成独立审查交接、不收尾。已有明确答复覆盖的范围、行为和技术决定直接复用;单条修改意见只确认该项,仍需确认的内容集中在同一轮。需要等待时按 [runs.md](runs.md#写-checkpoint) 保存草稿路径、已确认决定及待答问题。
|
|
51
|
+
2. **确认后送审。** 用户已确认本阶段草稿的决定后,将等待中的运行恢复为 `running`,按需生成交接。交接记录当前草稿正文及已登记的业务澄清或需求依据。
|
|
51
52
|
|
|
52
53
|
```sh
|
|
53
54
|
node <skills>/workflow/scripts/review-handoff.mjs --id <id> --kind <requirement|plan> --draft <草稿.md>
|
|
54
55
|
```
|
|
55
56
|
|
|
56
|
-
|
|
57
|
+
3. **审查按已确认的决定开展。** 把交接 `path`、适用的原始材料及用户决定的来源交给未参与起草的子 agent。审查者按 `packet.result_schema` 返回结论、位置、依据、影响和阻塞标记。
|
|
57
58
|
- 需求审查核对范围、场景、规则、技术约束和可验证的验收标准。缺陷修复还要核对现象、根因证据和预期行为。
|
|
58
59
|
- 方案审查以交接中的已定稿需求为依据,核对各验收项的实现与验证安排,以及适用的兼容性、权限、数据和回滚风险。
|
|
59
|
-
|
|
60
|
-
4.
|
|
61
|
-
5.
|
|
60
|
+
- 阻塞项的 `evidence` 指向具体的验收项、已确认决定或可查证的约束,`impact` 写明实际冲突、不可验证的验收项或会引入的风险。架构偏好、可选优化和新增功能填 `blocking: false`,按需采纳或关闭。如果建议被误标为阻塞,主 agent 提供对应的范围或决定,请审查者核实并更正结论。审查者发现需要改变用户决定的真实冲突时,写明影响,由用户或产品决定取舍。
|
|
61
|
+
4. **修订后复核差异。** 在既定决定内直接修复;如有新取舍,一次说明受影响的范围和建议,等待答复后修改。草稿或依据变化时生成绑定当前版本的新 packet。将上一轮同一文档的 packet 和结果(若基线是已收尾版本,也可用该版本正文、依据和审查记录)、正文及依据的差异、待关闭阻塞项和受影响的 AC 或章节一起交给审查者。优先复用原审查者,复核这些内容和相邻约束;基线缺失或无法界定影响时扩大范围。新结果使用当前 packet 的 `inputs`,在 `summary` 注明基线、复核范围及关闭的阻塞项;`findings` 如实保留仍适用的发现。
|
|
62
|
+
5. **需要降级时取得授权。** 子 agent 不可用时在当前阶段保存 `waiting_user`,让用户选择等待独立审查或允许本次自查。只有明确同意后才自查,结果写 `mode: "self"`、实际审查者和 `fallback: {"confirmed":true,"reason":"无法派出子 agent 的实际原因"}`。独立审查结果写 `mode: "independent"` 和实际子 agent 标识。程序校验记录及文档内容,实际派遣和用户答复由主 agent 如实记录。
|
|
63
|
+
6. **审核通过后收尾。** 将最终结果保存为 tmp 下的 JSON。执行 `artifact.mjs finalize` 时额外传 `--packet <交接JSON路径> --result <结果JSON路径>`。收尾会拒绝缺失、过期或仍有阻塞项的结果。审查后未引入用户尚未决定的新取舍时,用已有答复收尾;方案正式收尾后再记录当前版本的 `approval`。F7 / B5 的代码审查按下文执行。
|
|
62
64
|
|
|
63
65
|
## 验证证据
|
|
64
66
|
|
|
@@ -113,13 +115,13 @@ feature 可在 checkpoint 标 F7 completed;bug 的 B5 此时仍 in_progress。
|
|
|
113
115
|
|
|
114
116
|
只有该选择仍有效,才允许 `artifact.mjs finalize --kind delivery --draft ...`。审查后代码/基线变化或报告被修改,旧选择不能继续用;回 F6(bug 回 B4)、验证、复审、再次取得选择。修复回退会清除旧验证、审查与交付选择;方案改变则还须重新确认。
|
|
115
117
|
|
|
116
|
-
交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只
|
|
118
|
+
交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只 reindex 后用旧收尾凭据 complete。
|
|
117
119
|
|
|
118
120
|
## 统一收尾与中断恢复
|
|
119
121
|
|
|
120
122
|
finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运行 revision、阶段、分支和证据;通过后归档旧版、发布正式文件、更新版本/索引、登记运行证据。checkpoint 只能更新当前产物所属步骤、等待状态和上下文,不能夹带下游阶段或用户确认。输出正式 path、cite、previous、version、lint、run;自检警告和待填写项要告知用户,引用用 cite,归档遵循 requirements.md,不能替用户删除。
|
|
121
123
|
|
|
122
|
-
正式文档先写 tmp
|
|
124
|
+
正式文档先写 tmp 草稿;旧 `requirement.mjs path` 入口已删除,不能通过直接覆盖正式文件绕过收尾中断保护。tech / release 分别在 T4 / L4 用 kind tech / release 收尾,使用各自的知识模板;wiki/沉淀后只更新发布或知识元信息仍可显式 reindex,但 reindex 不修复正文 hash 或旧证据。
|
|
123
125
|
|
|
124
126
|
技术方案将生成时间、对比分支、diff 概览、PRD 参考和模板来源放在文件头的 `<!-- workflow-run: … -->` 多行注释中(格式见 create-tech-md-doc,整个块在前 20 行内),不要求正文显示元信息引用块。分支校验仍读取注释中的 `对比分支:`,索引日期读取其中的 `生成时间:`;旧文档的可见元信息继续兼容。注释随正式文件一起归档并参与 hash 校验,Wiki 转换时移除;`meta.json` 仍按现有逻辑记录绑定、索引和运行,不自动接收全部注释字段。
|
|
125
127
|
|
|
@@ -129,4 +131,4 @@ finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运
|
|
|
129
131
|
node <skills>/workflow/scripts/artifact.mjs resume --id <id>
|
|
130
132
|
```
|
|
131
133
|
|
|
132
|
-
|
|
134
|
+
命令会读取当前 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 /
|
|
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`;快速通道不创建记录。`
|
|
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 须有效交付选择。不要直接覆盖正式文件后只
|
|
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>`,不能继续
|
|
61
|
-
- `requirement.mjs path
|
|
62
|
-
- wiki 发布或知识沉淀更新文档元信息后显式 `requirement.mjs
|
|
63
|
-
- 文档/索引不一致、元信息损坏或引用缺失进入只读诊断;文件存在不代表运行完成。确认正文后显式
|
|
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
|
|
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
|
|
89
|
-
2. 用户确认后,按 pending 的 `commands
|
|
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`,对整个团队生效。关掉后
|
|
92
|
+
不想被提示的人可以关掉:`requirement.mjs config --commit-prompt off --local`。这个设置写在 `workflow/profile.local.json`(个人设置,不提交,只影响自己);去掉 `--local` 则写进 `profile.json`,对整个团队生效。关掉后 pending 仍可查询,但不主动提示提交,产物照常写到文档仓库,由自己决定什么时候提交。
|
|
@@ -85,7 +85,7 @@ F3 / B3 只能在需求文档 finalize 后完成;requirement.md 是需求事
|
|
|
85
85
|
|
|
86
86
|
- 用户选修复:save `stage: F5`、`status: running`、`decision: {"action":"fix","confirmed":true}`;bug 回 B4。回到前面的阶段会自动重置该阶段及后续的完成标记、清除旧交付选择,旧 checkpoint 保留在 history;修复、验证和复审后再次等待选择。业务场景变化先回 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
|
|
|
@@ -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 {
|
|
8
|
-
import {
|
|
9
|
-
import { ARTIFACT_TEMPLATES
|
|
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 =
|
|
24
|
-
else if (action === 'abort') out =
|
|
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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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 (
|
|
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
|
|
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 {
|
|
32
|
-
import {
|
|
33
|
-
import {
|
|
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,
|
|
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 <需求名>] |
|
|
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
|
-
|
|
63
|
-
|
|
64
|
-
case '
|
|
65
|
-
case '
|
|
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 (
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,88 +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, 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';
|
|
13
|
-
import { scope } from './review-scope.mjs';
|
|
14
7
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
if (run.stage !== (run.kind === 'feature' ? 'F7' : 'B5')) throw new Error('请先完成验证并进入审查阶段');
|
|
22
|
-
assertValidation(root, req, run, undefined, getSnapshot);
|
|
23
|
-
}
|
|
24
|
-
if (!['快审', '标准', '深审'].includes(depth)) throw new Error('审查深度须为快审 / 标准 / 深审');
|
|
25
|
-
const snapshot = getSnapshot();
|
|
26
|
-
const reviewScope = scope(root, { base: run.scope?.base ?? 'main', exclude: run.scope?.exclude ?? [] });
|
|
27
|
-
if (!reviewScope.ok) throw new Error(reviewScope.error);
|
|
28
|
-
assertSnapshot(root, run, snapshot);
|
|
29
|
-
const profile = readProfile(root).profile;
|
|
30
|
-
const inputs = reviewInputs(run);
|
|
31
|
-
return {
|
|
32
|
-
run_id: id, revision: run.revision, project_root: path.resolve(root), skills: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'),
|
|
33
|
-
branch, depth, snapshot, inputs: hash(JSON.stringify(inputs)), scope: reviewScope, requirement: req.name, facts: inputs.facts,
|
|
34
|
-
requirement_document: run.artifacts?.requirement ?? null, plan: run.artifacts?.plan ?? null, previous_report: run.artifacts?.review ?? null,
|
|
35
|
-
validation: run.validation ?? null,
|
|
36
|
-
commands: Object.fromEntries(['main_branch', 'build', 'test', 'test_single', 'lint'].map((k) => [k, profile?.[k] ?? null])),
|
|
37
|
-
capabilities,
|
|
38
|
-
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: ['未审文件'] } },
|
|
39
|
-
rules: '独立读代码,按 project-review 第 1~7 步审查;返回报告草稿和结构化结果,不改代码、不生成 delivery.md、不提交、不另建运行;主 agent 负责 finalize。零发现 findings 为空数组,scope.review 中每个文件必须进入 reviewed 或 uncovered。',
|
|
40
|
-
};
|
|
41
|
-
}
|
|
8
|
+
import { createWorkflow } from '../core/index.mjs';
|
|
9
|
+
import {
|
|
10
|
+
createCodeHandoff,
|
|
11
|
+
createDocumentHandoff,
|
|
12
|
+
writeReviewPacket,
|
|
13
|
+
} from '../core/review-handoff.mjs';
|
|
42
14
|
|
|
43
|
-
export
|
|
44
|
-
|
|
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
|
-
}
|
|
15
|
+
export const handoff = createCodeHandoff;
|
|
16
|
+
export const documentHandoff = createDocumentHandoff;
|
|
63
17
|
|
|
64
18
|
export function main(argv) {
|
|
65
19
|
try {
|
|
66
|
-
const args = [...argv];
|
|
20
|
+
const args = [...argv];
|
|
21
|
+
const options = {};
|
|
67
22
|
while (args.length) {
|
|
68
23
|
const key = args.shift();
|
|
69
|
-
if (!['--root', '--branch', '--id', '--depth', '--capabilities', '--kind', '--draft'].includes(key) || !args.length)
|
|
70
|
-
|
|
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();
|
|
71
28
|
}
|
|
72
|
-
const root = path.resolve(
|
|
73
|
-
const branch =
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
packet = handoff(root, { branch, id: opts.id, depth: opts.depth, capabilities });
|
|
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
|
+
}
|
|
83
39
|
}
|
|
84
|
-
const
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
+
}
|
|
89
62
|
}
|
|
63
|
+
|
|
64
|
+
export { writeReviewPacket };
|
|
65
|
+
|
|
90
66
|
const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
|
|
91
67
|
if (invoked) process.exit(main(process.argv.slice(2)));
|