@rowansenne/workflow-run 0.27.0 → 0.29.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 (54) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +97 -27
  3. package/bin/lib/artifact-context.mjs +2 -0
  4. package/bin/lib/doctor.mjs +1 -1
  5. package/bin/lib/install.mjs +1 -1
  6. package/create-release-md-doc/SKILL.md.tpl +4 -5
  7. package/create-tech-md-doc/SKILL.md.tpl +4 -6
  8. package/dev/SKILL.md.tpl +22 -14
  9. package/dev/agents/openai.yaml +2 -0
  10. package/dev/references/bug.md +6 -3
  11. package/dev/references/clarify.md +1 -1
  12. package/dev/references/delivery-template.md +2 -2
  13. package/dev/references/delivery.md +11 -9
  14. package/dev/references/implementation.md +5 -1
  15. package/dev/references/plan-template.md +8 -12
  16. package/dev/references/planning.md +8 -4
  17. package/dev/references/preflight.md +3 -3
  18. package/dev/references/requirement-template.md +32 -0
  19. package/dev/skill.json +10 -2
  20. package/nacos-config/SKILL.md.tpl +42 -0
  21. package/nacos-config/package.json +7 -0
  22. package/nacos-config/references/connection.md +47 -0
  23. package/nacos-config/scripts/config.mjs +288 -0
  24. package/nacos-config/skill.json +9 -0
  25. package/package.json +6 -2
  26. package/project-review/SKILL.md.tpl +4 -3
  27. package/project-review/references/reporting.md +8 -8
  28. package/project-review/references/review-method.md +1 -1
  29. package/project-review/skill.json +2 -1
  30. package/workflow/SKILL.md.tpl +14 -9
  31. package/workflow/lib/artifact-finalize.mjs +156 -0
  32. package/workflow/lib/artifact-model.mjs +2 -2
  33. package/workflow/lib/code-snapshot.mjs +55 -0
  34. package/workflow/lib/meta-store.mjs +4 -2
  35. package/workflow/lib/path-match.mjs +21 -0
  36. package/workflow/lib/requirements.mjs +12 -7
  37. package/workflow/lib/run-gates.mjs +153 -0
  38. package/workflow/lib/runs.mjs +58 -14
  39. package/workflow/lib/workspace-read.mjs +3 -1
  40. package/workflow/references/architecture.md +51 -3
  41. package/workflow/references/capabilities.md +4 -2
  42. package/workflow/references/execution.md +105 -0
  43. package/workflow/references/requirements.md +15 -13
  44. package/workflow/references/runs.md +16 -11
  45. package/workflow/references/status.md +1 -0
  46. package/workflow/references/templates.md +2 -2
  47. package/workflow/scripts/artifact.mjs +39 -0
  48. package/workflow/scripts/pr-desc.mjs +2 -2
  49. package/workflow/scripts/review-handoff.mjs +59 -0
  50. package/workflow/scripts/review-scope.mjs +2 -21
  51. package/workflow/scripts/run.mjs +6 -8
  52. package/workflow/scripts/template.mjs +3 -2
  53. package/workflow/scripts/view.mjs +1 -1
  54. package/workflow/skill.json +2 -1
@@ -1,10 +1,28 @@
1
- # 内部模块边界与统一读取模型
1
+ # 架构、模块边界与统一读取模型
2
2
 
3
- 安装接入在 `bin/`;各 Skill 的 SKILL.md 与 references 定义流程步骤、确认点和调用时机;`workflow/lib/` 承担共享规则与数据读写;`workflow/scripts/` 保留既有命令和导出入口。数据库、代码图谱、wiki 的执行与凭据仍在各自能力目录。`shared/` 只分发参考文档,运行共享代码随 workflow 的 lib 一起安装。
3
+ 本文对应 0.29.0(2026-10-28),包括独立 nacos-config、需求文档与 dev 显式触发规则;实现以代码与各 skill 的 skill.json 为准。
4
4
 
5
+ ## 安装分发与运行
6
+
7
+ 安装接入在 `bin/`;各 Skill 的 SKILL.md 与 references 定义流程步骤、确认点和调用时机;`workflow/lib/` 承担共享规则与数据读写;`workflow/scripts/` 保留既有命令和导出入口。数据库、代码图谱、wiki、Nacos 的执行与凭据仍在各自能力目录。`shared/` 只分发参考文档,运行共享代码随 workflow 的 lib 一起安装。宿主代理执行规则与命令,workflow-run 不提供常驻的 Agent 调度服务。
8
+
9
+ `bin/skills.mjs` 从各目录的 `skill.json` 发现当前 9 个 skills,以 `requires` 展开必需依赖,`optional` 标记可选协作;`userFiles` 决定升级保留范围,`templates` 声明知识模板,`docnexus` 声明分类。`package.json.files` 决定 npm 分发内容。默认在 `.agents/skills/` 安装完整文件,其他环境逐 skill 建相对链接;`--copy` 或链接失败时改用拷贝。安装清单记录分发文件 hash,手改文件升级前备份,用户配置不覆盖。
10
+
11
+ DocNexus 在安装环节必装,即使只选择 nacos-config 也会接入;Nacos 的读取脚本本身没有 workflow / DocNexus 运行依赖。DocNexus 自带的入口、召回等 skills 单独链接给宿主,不计入本包的 9 个 skills。
12
+
13
+ ## 两条执行路径
14
+
15
+ | 请求 | 调用路径 | 状态归属 |
16
+ |---|---|---|
17
+ | 开发、正式审查、技术 / 上线方案 | 宿主 → 流程 skill → workflow/scripts → workflow/lib;按需调用能力型 skills 或 DocNexus | 正式需求产物与 meta.json;按执行协议记录 runs |
18
+ | 读取 Nacos 参数 | 宿主 → nacos-config → config.mjs → 所选 Nacos 配置接口 | 默认仅返回脱敏快照,不绑定需求、不创建运行、不落盘原文 |
19
+
20
+ dev / project-review 可在已有流程中按需调用 nacos-config,读取结果作为配置证据;独立查询不自动启动完整工作流。能力型 skill 的 SQL、HTTP、CodeGraph 执行逻辑不因共享核心存在而搬进 lib。
5
21
 
6
22
  dev / project-review 的 SKILL.md 只保留触发边界、门禁、步骤路由、必要命令和结果去向。方法细节按阶段保存在各自 references 中,进入阶段前只读对应小节,避免开工加载全部方法。F1~F8、B1~B5 与审查第 1~9 步编号不变;报告选择、快速通道、完成标记等关键约束在入口可见,具体执行仍由阶段说明和共享状态协议约束。
7
23
 
24
+ dev 的入口要求显式流程授权:实际调用 `/dev` / `$dev`、点选 skill 或明确要求 dev / 完整开发工作流。普通分析、修改、修复、测试和 Git 操作不会经 workflow 自动转进 dev;旧运行与绑定也不构成启动授权。Codex 的 `dev/agents/openai.yaml` 关闭隐式调用,skill 本文在任何开工命令前检查入口;安装器把同一边界写进所选环境的项目说明。已授权同任务按阶段续接,当前独立分析 / 提交请求不重启或自行推进阶段。
25
+
8
26
  ## 共享核心
9
27
 
10
28
  | 模块 | 职责 |
@@ -14,6 +32,10 @@ dev / project-review 的 SKILL.md 只保留触发边界、门禁、步骤路由
14
32
  | requirement-read | 需求目录和元信息读取、查询与分组 |
15
33
  | requirements | 需求绑定、产物版本、归档、索引写入 |
16
34
  | runs | 运行阶段、用户选择、revision、完成与取消 |
35
+ | run-gates | 方案确认、实现/验证/审查/交付转换门禁,核对证据与版本 |
36
+ | code-snapshot | 基线、HEAD 与工作区文件内容摘要,校验验证/审查仍适用 |
37
+ | artifact-finalize | 草稿检查、正式发布、归档、索引与运行证据登记;在 meta 中记录可恢复收尾 |
38
+ | path-match | 审查范围与代码快照复用的纯 glob 匹配 |
17
39
  | meta-store | 元信息写锁与原子替换;写入前自动创建父目录,再按真实路径归一化加锁;读取不创建目录 |
18
40
  | document-model | 标题、章节、表格、元信息等纯文本解析 |
19
41
  | artifact-model | 产物种类、文件名、分支、日期、发布与沉淀、审查和交付解析 |
@@ -38,6 +60,32 @@ lib 不依赖 scripts;纯模型不依赖 I/O。读侧不调用 sync 或推进
38
60
 
39
61
  ## 能力边界
40
62
 
41
- `lib/capabilities.mjs` 集中探测接入,`resolve.mjs status` 输出本轮能力快照(ready / blockers、通道、模板解析结果),`references/capabilities.md` 定义所有 Skill 共用的失败处理。CodeGraph 的库探测通过其 status 命令交给能力适配器,lib 不导入 Skill 执行脚本。新会话或环境变化时刷新,不持久化个人能力状态到需求元信息。
63
+ `lib/capabilities.mjs` 集中探测接入,`resolve.mjs status` 输出本轮能力快照(ready / blockers、通道、模板解析结果),`references/capabilities.md` 定义依赖 workflow 的 Skill 共用的失败处理。CodeGraph 的库探测通过其 status 命令交给能力适配器,lib 不导入 Skill 执行脚本。新会话或环境变化时刷新,不持久化个人能力状态到需求元信息。
42
64
 
43
65
  DocNexus 是必装组件:安装器缺失即接入,安装失败不报告完成;已有组件默认复用,`--with-docnexus` 强制更新。模板只从知识库读取,包内模板仅用于导入。知识查询失败不作为空结果继续。CodeGraph、wiki、数据库仍按共享规则选择增强通道;必需目标、需求绑定和语句拦截按各自语义处理。
66
+
67
+ nacos-config 独立按需读取,不属于 capabilities.mjs 集中探测的通道。`inspect` 仅列本地 application / bootstrap 候选与命名连接;`get` 才验证远端网络、鉴权和指定配置。项目画像 `config_center: nacos` 只说明项目使用的配置中心,不代表已有 Nacos 连接、鉴权通过或运行时配置已核实。
68
+
69
+ `config.mjs` 处理 YAML / properties、本地属性与环境变量占位符、显式 profile、指定文件的覆盖顺序和脱敏输出;YAML 解析依赖装在 nacos-config 目录。连接可来自所选文件,或本机 `config.json` 中的命名连接,两者互斥。配置请求仅 GET,POST 仅用于登录;token 不落盘。输出标明 Namespace、Group、Data ID、时间和内容摘要,不模拟完整 Spring 配置合并、灰度或刷新,也不自动生成数据库连接。协议和字段见 `<skills>/nacos-config/references/connection.md`(该 skill 未安装时不可用)。
70
+
71
+ ## 运行环境与数据位置
72
+
73
+ | 位置 | 保存内容 |
74
+ |---|---|
75
+ | 代理技能目录 | SKILL.md、references、执行脚本和安装清单;连接配置按规则忽略 |
76
+ | workflow/profile.json / profile.local.json | 团队项目事实 / 本机环境与覆盖项,均不放凭据;后者不提交 |
77
+ | .docnexus/ | DocNexus 项目配置、npm 清单、依赖、skills、草稿与索引;内部文件按其 gitignore 管理 |
78
+ | .codegraph/ | 本机代码图谱索引,不提交 |
79
+ | workflow-run/docs/requirements/&lt;需求&gt;/&lt;项目&gt;/ | 正式 Markdown 与需求 meta.json(绑定、产物索引、runs、可恢复收尾待办) |
80
+ | workflow-run/docnexus/ | 团队知识与生效模板;技术 / 上线方案模板首次按用户样例创建 |
81
+ | workflow-run/feedback/、other/、tmp/ | 运行反馈、普通聊天辅助文件、忽略提交的临时文件与锁 |
82
+
83
+ view / report 读取需求工作区快照展示,不触发运行转换或远程配置拉取。DocNexus 的 view 是单独的本地知识浏览服务。远端数据库 / wiki / Nacos 始终是外部数据源,本地产物仅保留任务所需、允许展示的证据。
84
+
85
+ ## 执行可靠性
86
+
87
+ 完整流程在 F3 / B3 收尾先生成 requirement.md,独立记录目标、范围、AC 验收与决定;plan.md 保存实现设计并绑定需求 hash / 版本。需求变化后必须重新收尾方案,旧确认与验证、审查、交付证据失效;只改实现方案不修改需求文档。view / report / PR 引用将需求文档作为独立产物展示。
88
+
89
+ 关键转换由 run-gates 执行,不仅在 complete 检查。方案批准关联具体正文;验证在执行前 snapshot、执行后登记;review-handoff 从已保存事实和代码范围生成交接材料,不传实现者结论。审查结果同时返回报告草稿与结构化 findings/coverage,主 agent 统一收尾,交付选择绑定该轮代码与报告版本。
90
+
91
+ artifact.mjs 在命令层解析知识模板并传入精确草稿检查;artifact-finalize 不导入命令入口。两次带锁写入先登记 pending_finalization,再发布文档并提交索引与运行;meta 中的待办是恢复依据,不另建状态数据库。中断后拒绝其他元信息写入,resume 重查证据并幂等完成,abort 安全还原原文件。只读命令展示待办,不自动修复。快照与阶段协议见 execution.md。
@@ -1,12 +1,14 @@
1
1
  # 开工能力与失败处理
2
2
 
3
- 所有 Skill 共用本规则。开工在项目根运行一次:
3
+ 依赖 workflow 的 Skill 共用本规则。开工在项目根运行一次:
4
4
 
5
5
  ```sh
6
6
  node <skills>/workflow/scripts/resolve.mjs status
7
7
  ```
8
8
 
9
- 保留输出作为本轮能力快照;同一项目的流程跳转、子 agent 直接复用,由主 agent 一并交接。新会话恢复、切换项目、配置或安装发生变化时重新探测。快照只放在会话上下文,不作为团队配置或固定状态写入 meta.json。
9
+ 保留输出作为本轮能力快照;同一项目的流程跳转、子 agent 直接复用,由主 agent 一并交接,可用 workflow-run/tmp/capabilities.json 暂存交接。新会话恢复、切换项目、配置或安装发生变化时重新探测。快照仅本轮使用,不作为团队配置或固定状态写入 meta.json。
10
+
11
+ 独立 nacos-config 不要求加载 workflow 或运行本命令,也没有对应的集中能力字段;其 `inspect` 仅检查本地候选,`get` 才验证远端。dev / project-review 内调用它时沿用已有工作流快照,Nacos 读取结果另带配置来源,不据 `profile.config_center` 推断连接可用。
10
12
 
11
13
  ## 开工门槛
12
14
 
@@ -0,0 +1,105 @@
1
+ # 关键门禁、代码证据与产物收尾
2
+
3
+ 完整流程进入方案、实现、验证、审查或交付时读对应小节。快速通道不调用本文的运行与落盘命令。所有命令在业务项目根运行,`<skills>` 为安装目录;JSON 输入文件放 `workflow-run/tmp/`。
4
+
5
+ ## 需求、方案与实现门禁
6
+
7
+ 澄清后先按 F4 标准判定规模与通道;完整流程首次创建运行在 F3 / B3 收尾,bind 后先生成独立需求文档。快速通道仍不 bind。`scope` 保存审查基线和明确排除范围,缺省取需求 base/画像 main_branch 与 review.exclude:
8
+
9
+ ```json
10
+ {"scope":{"base":"main","exclude":["unrelated/**"]}}
11
+ ```
12
+
13
+ 完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 sync 代替收尾。模板仍由调用方用 `resolve.mjs template <skill> <id>` 读取:
14
+
15
+ ```sh
16
+ node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind requirement --draft workflow-run/tmp/requirement.md --input workflow-run/tmp/checkpoint.json
17
+ ```
18
+
19
+ 需求文档保存背景目标、范围边界、AC 验收标准、已确认决定与待确认问题。功能收尾 checkpoint 标 `{"steps":{"F3":{"status":"completed"}}}`,bug 改为 B3;随后 save stage F4 / B4。M / L 保留原有需求理解确认,不新增重复确认。未收尾 requirement.md 不能完成 F3 / B3 或进入方案。
20
+
21
+ plan.md 头部引用需求文档 cite 与版本,只写实现设计、技术风险、实施步骤和验证计划;验证引用 AC 编号,不复制业务需求。方案收尾自动绑定需求 hash / 版本:
22
+
23
+ ```sh
24
+ 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
25
+ ```
26
+
27
+ 功能方案收尾的 checkpoint 可写 `{"steps":{"F4":{"status":"completed"}}}`;M / L 等用户确认时可同时写 waiting_user 和 waiting_for。bug 的 B4 还包含实现、验证,方案收尾时不能标完成,checkpoint 可省略。已有方案在草稿中保留正文并追加修复方案,更新当前分支和日期。
28
+
29
+ M / L 取得用户实际确认后,用 save 记录 `approval: {"confirmed":true}`,程序绑定当前 plan.md 的 hash/版本;方案变更后旧确认失效。S 完整流程仍须收尾方案,但无需该确认记录。进入实现:
30
+
31
+ - feature:save `{"stage":"F5","status":"running","approval":{"confirmed":true}}`(S 可省 approval)。
32
+ - bug:在 B4 save `{"status":"running","approval":{"confirmed":true},"implement":true}`;之后才改代码。
33
+
34
+ 未收尾方案、M / L 未确认、核心步骤 skipped 都会被拒绝。程序校验确认记录与版本,不能替代 agent 核实用户是否真的授权。
35
+
36
+ 需求变化回 F3(bug 回 B3)重新澄清并 finalize requirement;程序清除旧方案确认、实现、验证、审查和交付选择,旧方案不能作为新需求的依据。即使方案正文不变,也要在 F4 / B4 重新收尾以绑定新需求版本;M / L 重新取得方案确认。只改实现方式则仅更新 plan,不改 requirement。手动改需求正文而未收尾也会使后续证据校验失败。
37
+
38
+ ## 验证证据
39
+
40
+ feature 实现完成后 save F5 completed,进入 F6;bug 在 B4 验证。**测试/操作执行前**生成快照:
41
+
42
+ ```sh
43
+ node <skills>/workflow/scripts/run.mjs snapshot --id <id>
44
+ ```
45
+
46
+ 保留输出的 `snapshot` 对象,再执行构建、相关/全量测试、lint 与验收操作。执行后 save:
47
+
48
+ ```json
49
+ {
50
+ "validation": {
51
+ "snapshot": {"说明":"替换为执行前输出的完整 snapshot 对象,不是此示例"},
52
+ "checks": [
53
+ {"command":"实际执行的测试命令或验收操作","result":"passed"},
54
+ {"command":"无法执行的集成验证","result":"unverified","reason":"缺少测试环境"}
55
+ ]
56
+ },
57
+ "steps": {"F6":{"status":"completed"}}
58
+ }
59
+ ```
60
+
61
+ result 只接受 passed / failed / unverified;失败或未验证须 reason,不能用计划冒充结果。bug 将 F6 改为 B4,保存后进入 B5;feature 保存后进入 F7。若执行期间代码变化,登记失败,重新生成快照并验证。
62
+
63
+ 快照包含实际工作分支、基线提交、合并基点、HEAD,以及工作区跟踪/未跟踪文件的内容、删除、执行权限和符号链接;暂存本身不改变内容摘要。子模块/嵌套仓库须固定在干净提交,不能用 dirty 标记代替具体代码证据。除明确排除范围外,也覆盖未改动的项目文件,防止调用方/配置变更使证据过期。忽略 Git 忽略的未跟踪文件,以及 workflow-run、已安装 skills、DocNexus 和 CodeGraph 内部文件,避免写报告使自身失效。不能用 `--branch` 给另一实际 checkout 作证。
64
+
65
+ ## 自动审查交接
66
+
67
+ 开工 status 输出保留在本轮 `workflow-run/tmp/capabilities.json`,同链路复用,不写需求 meta。进入 F7 / B5 后生成:
68
+
69
+ ```sh
70
+ node <skills>/workflow/scripts/review-handoff.mjs --id <id> --depth 标准 --capabilities workflow-run/tmp/capabilities.json
71
+ ```
72
+
73
+ 输出 `path` 是交接 JSON,位于 tmp/review/<运行id>/。自动汇总项目/skills 路径、实际基线、排除范围、风险分批、requirement_document(需求文档路径、hash 与版本)、续接事实摘要、方案、验证命令与结果、上次报告及代码快照。验收与业务范围以对应需求文档为准,context 只作缓存摘要。没有能力文件时省略参数,主 agent 补交本轮能力快照;不重新探测。只传事实,不传实现者的自审结论。
74
+
75
+ 独立子 agent 按 project-review 第 1~7 步审查,返回报告草稿与结构化结果,主 agent 负责正式收尾并更新同一运行。没有子 agent 时由当前会话同样执行并如实署名。**审查期间不修改被审代码**。JSON 结果结构以 packet.result_schema 为准,run_id / code / inputs 原样回传,以绑定本轮运行、代码版本和交接内容;范围外发现标 scope: outside,不计入本次交付的严重问题门禁。零发现 findings 为空数组,scope.review 中每个文件必须进入 coverage.reviewed 或 uncovered,不能漏报未审文件。
76
+
77
+ ```sh
78
+ node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind review --draft workflow-run/tmp/review.md --packet <交接JSON路径> --result workflow-run/tmp/review-result.json --input workflow-run/tmp/checkpoint.json
79
+ ```
80
+
81
+ feature 可在 checkpoint 标 F7 completed;bug 的 B5 此时仍 in_progress。主 agent 取得报告后交给用户,save waiting_user 等待修复或交付。收尾要求交接仍对应当前代码、需求事实、方案和验证;仅进度保存不会让交接失效,改变验收/范围等实质内容须重新审查。
82
+
83
+ 独立正式 review 也生成交接材料,R1~R6 记录实际进度,R7 用同一入口收尾 review,再交报告、complete;不要求 dev 的验证或方案。当前协议的代码证据基于实际工作区,正式审查请在目标分支 checkout 中运行;其他分支的只读灵活审查仍可用原 diff 命令,不创建运行。
84
+
85
+ ## 交付门禁
86
+
87
+ 用户明确选择交付后,feature save F8 running、bug 在 B5 save running,并写 `decision: {"action":"deliver","confirmed":true}`。程序自动绑定本轮报告 hash、版本与代码摘要。存在已复核 CRITICAL / HIGH 时,先说明风险、取得逐项接受,再在 decision.accepted_risks 中列出对应 findings 的 id;普通的“交付”不代表接受未说明风险。
88
+
89
+ 只有该选择仍有效,才允许 `artifact.mjs finalize --kind delivery --draft ...`。审查后代码/基线变化或报告被修改,旧选择不能继续用;回 F6(bug 回 B4)、验证、复审、再次取得选择。修复回退会清除旧验证、审查与交付选择;方案改变则还须重新确认。
90
+
91
+ 交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只 sync 后用旧收尾凭据 complete。
92
+
93
+ ## 统一收尾与中断恢复
94
+
95
+ finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运行 revision、阶段、分支和证据;通过后归档旧版、发布正式文件、更新版本/索引、登记运行证据。checkpoint 只能更新当前产物所属步骤、等待状态和上下文,不能夹带下游阶段或用户确认。输出正式 path、cite、previous、version、lint、run;自检警告和待填写项要告知用户,引用用 cite,归档遵循 requirements.md,不能替用户删除。
96
+
97
+ 正式文档先写 tmp 草稿;不要先调用 `requirement.mjs path` 归档再直接覆盖,否则绕过收尾的中断保护。tech / release 分别在 T4 / L4 用 kind tech / release 收尾,使用各自的知识模板;wiki/沉淀后只更新发布或知识元信息仍可显式 sync。
98
+
99
+ 两个文件无法一次原子提交,待办保存在同一个 meta.json 的 pending_finalization,草稿副本在 tmp/finalize/。中断期间其他元信息写入会被拒绝,show 的 next 提示恢复:
100
+
101
+ ```sh
102
+ node <skills>/workflow/scripts/artifact.mjs resume --id <id>
103
+ ```
104
+
105
+ 恢复会再次核对代码与正文,已发布的相同文件不重复升版本;原 finalize 命令重试也不会重复推进状态。恢复发现代码变化或正式文件被其他操作改动时,停下保留待办,不覆盖。需要放弃本次收尾时用 `artifact.mjs abort --id <id>`:只在文件仍是本操作原版/新版时恢复原版并清除待办;发生外部冲突则先人工核对。之后回退、重新验证/审查。临时副本保留在 tmp,不删除用户文件。
@@ -7,6 +7,7 @@
7
7
  ```
8
8
  workflow-run/docs/requirements/<需求名>/<项目名>/
9
9
  ├── meta.json # 运行记录 runs(阶段、步骤完成标记、等待决定、上下文、完成时间)及 需求名、绑定的分支、各产物(种类、版本、日期、wiki 发布记录、DocNexus 沉淀)
10
+ ├── requirement.md # 需求文档(F3 / B3 收尾;目标、范围、AC 验收与澄清决定)
10
11
  ├── plan.md # 方案(dev,非快速通道都写;S / M 简版;缺陷修复追加修复方案节)
11
12
  ├── delivery.md # 交付说明(dev,完整流程审查后用户选择交付才生成;S 快速通道不落盘)
12
13
  ├── review.md # 审查报告(独立 project-review 或 dev 完整流程的自查;S 快速通道不落盘);复审也写这个文件,上一版归档(见「落盘」)
@@ -42,23 +43,24 @@ node <skills>/workflow/scripts/requirement.mjs which
42
43
 
43
44
  一个需求可以绑定多个分支(`bind` 在其他分支上用同一个名字即可)。
44
45
 
46
+ 完整开发 / 修复的首个文档为 F3 / B3 收尾的 requirement.md,绑定和 start 在此时发生;plan.md 随后记录实现设计与需求版本。需求、方案各自版本化,已有历史文档不自动改写。S 快速通道始终不绑定、不落盘;退出快速通道先补需求文档再补方案。
47
+
45
48
  ## 运行状态
46
49
 
47
50
  完整流程在本文件的 `runs` 中按运行 id 保存进度,关联分支;同一需求可有多次运行。`status: completed` 和 `completed_at` 是本次运行已完成的明确标记,步骤也单独记录 completed。保存/恢复和各 skill 的记录时机见 `runs.md`;快速通道不创建记录。`sync` 只重建产物索引,保留 runs 和其他扩展字段;重新 bind 也不会清空历史。元信息采用原子写入与短时写锁,状态更新另有 revision 检查。
48
51
 
49
52
  ## 落盘
50
53
 
51
- ```
52
- node <skills>/workflow/scripts/requirement.mjs path <plan|delivery|review|tech|release>
53
- ```
54
+ 正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <requirement|plan|delivery|review|tech|release> --draft <草稿>` 收尾。命令校验当前步骤、分支与知识模板,归档旧版、发布文件、更新索引/版本并登记运行证据;requirement 在 F3 / B3,plan 在 F4 / B4,方案记录依据的需求版本;review 还须 packet 与结构化 result,delivery 须本轮有效交付选择。不要直接覆盖正式文件后只 sync。
54
55
 
55
- - 输出的 `path` 就是要写的文件(相对项目根)。文档里引用产物(「参考产物」、上线方案引用技术方案等)写输出的 `cite`:默认模式下和 `path` 相同;文档仓库模式下是「文档仓库名:仓库内路径」,各服务、各人的克隆里都一样。每种产物的文件名固定(`review.md`、`tech-doc.md` …),引用它的地方不会因为出了新版而失效。已有时,脚本先把当前版复制到 `workflow-run/tmp/old-artifacts/<需求名>/<项目名>/<种类>_v<N>.md`,输出的 `previous` 就是这份(复审对照上次的报告读它),`version` 是这次的版本号;然后把新版直接写到 `path`。
56
- - 退出码 2:当前分支还没绑定需求,按上一节问用户需求名,`bind` 之后再运行一次。
57
- - `wiki_record` 非空:上一版已经发布到 wiki。新版的**第一行原样写这条记录**,md-to-wiki 再发布时会更新同一个页面,不会新建页面。
58
- - 写完运行 `requirement.mjs sync <path>`,更新 `meta.json`。md-to-wiki 发布后改了第一行的记录,或补写了 DocNexus 元信息行,也要再 sync 一次。
59
- - 需求绑定由 `bind` 显式维护;`sync` 记录文档所属分支,但不从文档头隐式新增需求绑定。`list` 和状态/视图/报告只读,不自动 sync。文档与索引不一致、元信息损坏或引用文件缺失时会给出数据诊断;可读正文仍可展示,运行状态不根据文件存在推断完成。修复正文后显式 sync,损坏的元信息先人工核对修复。
60
- - sync 时新版内容和归档的上一版不同,才算新版本(`meta.json` 的 `versions` 加一);没写就放弃的话版本号不变。输出里 `archived` 非空时,告诉用户归档了哪些文件、在哪里(`workflow-run/tmp/old-artifacts/<需求名>/<项目名>/`,不提交),请用户确认不再需要后自己删除;**不要替用户删**。随代码或文档仓库提交过的旧版也能从 git 历史找回。
61
- - sync 输出里 `commit` 非空:按下一节「文档仓库的提交」处理。
56
+ - 输出 path(相对项目根)、cite(跨文档引用)、previous(上一版归档)、version 和 run。文件名固定,目录只留最新版;文档仓库模式的 cite 为「文档仓库名:仓库内路径」。
57
+ - 旧版归档在 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`,不提交;告诉用户归档了什么,不替用户删除。相同命令重试不重复升级版本或状态。
58
+ - 原文第一行的 md-to-wiki 页面记录自动保留,新版仍发布同一页;不能在普通文档收尾中替换页面归属。
59
+ - 文件发布与元信息不能跨文件一次原子提交。待完成收尾保存在同一 meta.json;中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 越过待办。代码或正文冲突时停止,取消和恢复规则见 execution.md。
60
+ - `requirement.mjs path <种类>` 仍保留为底层旧接口(会预先复制归档),不作为新流程的写入入口。查询已有产物用 artifacts / list,正式写入与 cite 用 finalize 输出。
61
+ - wiki 发布或知识沉淀更新文档元信息后显式 `requirement.mjs sync <path>`。sync 重建索引并保留 runs;需求绑定只由 bind 修改,不根据文档头隐式新增。
62
+ - 文档/索引不一致、元信息损坏或引用缺失进入只读诊断;文件存在不代表运行完成。确认正文后显式 sync,损坏的 meta 先人工核对修复。已有旧运行缺少新证据时回到对应阶段重新收尾/验证,不自动补用户确认。
63
+ - 独立文档仓库在允许提示提交的阶段运行 `requirement.mjs pending`,沿用下节规则;dev 内部审查延后到 F8。
62
64
 
63
65
  ## 独立文档仓库
64
66
 
@@ -78,12 +80,12 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
78
80
 
79
81
  ## 文档仓库的提交
80
82
 
81
- 文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。sync 输出里 `commit` 非空时:
83
+ 文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。finalize 后运行 pending(或旧 sync 返回 commit 非空)时:
82
84
 
83
85
  **dev F7 审查例外**:审查环节(独立子 agent 或当前会话自查)拿到 `commit` 信息后不询问、不执行文档提交,先交审查报告、等待用户选择修复或交付。选择交付进入 F8 后(完整流程;S 快速通道不落盘,没有待提交产物),再运行 `requirement.mjs pending` 获取当前待提交内容,按下面步骤询问;修复与复审期间继续延后,不改动 `commit_prompt` 配置。
84
86
 
85
- 1. 把 `commit.files`(未提交的产物)和 `commit.suggested_message` 给用户看,问要不要提交。
86
- 2. 用户确认后,按 `commit.commands` 在文档仓库里提交;推送另外问用户,用户同意后再 `git -C workflow-run push`。
87
+ 1. 把 pending 的 `files`(旧 sync 为 commit.files)和 `suggested_message` 给用户看,问要不要提交。
88
+ 2. 用户确认后,按 pending 的 `commands`(旧 sync 为 commit.commands) 在文档仓库里提交;推送另外问用户,用户同意后再 `git -C workflow-run push`。
87
89
  3. 用户不想现在提交就跳过,不再追问;之后随时可以运行 `requirement.mjs pending` 看还有哪些没提交。
88
90
 
89
91
  不想被提示的人可以关掉:`requirement.mjs config --commit-prompt off --local`。这个设置写在 `workflow/profile.local.json`(个人设置,不提交,只影响自己);去掉 `--local` 则写进 `profile.json`,对整个团队生效。关掉后 sync 不再输出 `commit`,产物照常写到文档仓库,由自己决定什么时候提交。
@@ -2,6 +2,8 @@
2
2
 
3
3
  状态和需求绑定、产物索引统一保存在 `workflow-run/docs/requirements/<需求>/<项目>/meta.json` 的 `runs` 对象中,以运行 id 区分。每次运行有自己的分支、kind、规模、阶段、步骤状态、上下文、历史、revision 和完成时间;同一需求跨分支不会共用一个全局阶段。
4
4
 
5
+ 本文是用户显式启动工作流后的状态协议,不是普通分析、代码修改或 Git 操作的入口。dev 仅由 `/dev` / `$dev`、点选 skill 或明确要求 dev / 完整开发工作流启动;新会话读取旧 runs 不构成恢复授权。已授权同一任务可按保存阶段续接;用户只要求分析或提交代码时,仅处理该请求,不重启流程或自行 save / complete。
6
+
5
7
  **快速通道不 start、不 save、不 bind**,仍然只写既有运行反馈。`show` 只读,无绑定或旧需求没有 runs 时返回空列表,不创建目录,不根据文档存在推断“已完成”。
6
8
 
7
9
  ## 命令与状态
@@ -28,8 +30,8 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
28
30
 
29
31
  | kind | 步骤 | 首次创建时机 |
30
32
  |---|---|---|
31
- | `feature` | Step0、F1~F8 | F4 确定不走快速通道并 bind 后 |
32
- | `bug` | Step0、B1~B5 | B4 确定不走快速通道并 bind 后 |
33
+ | `feature` | Step0、F1~F8 | F3 收尾确定不走快速通道并 bind 后,先写 requirement.md |
34
+ | `bug` | Step0、B1~B5 | B3 收尾确定不走快速通道并 bind 后,先写 requirement.md |
33
35
  | `review` | R1~R7(project-review 第 1~7 步) | 独立审查需要落盘且绑定需求后;dev 内部审查不另开运行 |
34
36
  | `tech` | T0~T4(技术方案 Step 0~4) | 确定需求和分支、绑定后 |
35
37
  | `release` | L0~L4(上线方案 Step 0~4) | 确定需求和分支、绑定后 |
@@ -37,19 +39,20 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
37
39
 
38
40
  “已完成”表示**本次运行范围已交付**,不是整个需求已经上线。dev 完成后,用户选择的技术方案、上线方案、wiki 发布是同一个 meta.json 中的新运行,不把已完成的 dev 改回未完成。提交、推送和知识沉淀仍按既有授权规则处理,不因 completed 自动执行;这些可选后续动作不阻止已完成的技能交付标记完成。
39
41
 
42
+ 关键门禁、代码快照、自动审查交接和正式文档收尾见 [execution.md](execution.md)。完整流程从需求文档开始记录;方案绑定需求 hash/版本,方案确认绑定方案版本,验证和审查绑定代码快照,交付选择绑定本轮报告。
43
+
40
44
  ## 写 checkpoint
41
45
 
42
- 完整 dev 开始记录前已经完成的前置步骤,要把对话中确认的事实补入第一份 checkpoint;没有实际完成的步骤不能补成 completed。例如 F4 开始时:
46
+ 完整 dev 开始记录前已经完成的前置步骤,要把对话中确认的摘要补入第一份 checkpoint;没有实际完成的步骤不能补成 completed。例如 F3 收尾准备写需求文档时:
43
47
 
44
48
  ```json
45
49
  {
46
- "stage": "F4",
50
+ "stage": "F3",
47
51
  "status": "running",
48
52
  "steps": {
49
53
  "Step0": { "status": "completed" },
50
54
  "F1": { "status": "completed" },
51
- "F2": { "status": "completed" },
52
- "F3": { "status": "completed", "note": "理解与验收已确认" }
55
+ "F2": { "status": "completed" }
53
56
  },
54
57
  "context": {
55
58
  "summary": "本次要实现的行为",
@@ -64,7 +67,9 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
64
67
 
65
68
  每完成一个步骤、发生阻塞、准备等待用户,或结束本轮会话前,save 一次;`context` 按顶层字段合并,列表字段更新时提供完整列表,不写密码、token。每一步可记录 `evidence`(命令、结果、产物路径、未验证原因)和 `note`;这些是已观察到的结果,不得用计划冒充。
66
69
 
67
- 审查报告已交给用户、等待修复或交付时:
70
+ F3 / B3 只能在需求文档 finalize 后完成;requirement.md 是需求事实来源,context 摘要与它保持一致。需求文档及方案各自独立版本、归档和展示;改需求须重新收尾依赖它的方案。历史文档不自动拆分,旧开发运行恢复时回到 F3 / B3 核实并补齐,不能用旧方案冒充需求文档。
71
+
72
+ 报告必须先由 artifact.mjs finalize 收尾并登记审查证据;报告已交给用户、等待修复或交付时:
68
73
 
69
74
  ```json
70
75
  {
@@ -79,20 +84,20 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
79
84
  前面的 F4~F6 必须已按实际进度保存,不能为凑齐示例而直接标完成。bug 的 B5 同时包含审查与交付,报告完成等待选择时 B5 仍为 in_progress,最后交付才标完成。
80
85
 
81
86
  - 用户选修复:save `stage: F5`、`status: running`、`decision: {"action":"fix","confirmed":true}`;bug 回 B4。回到前面的阶段会自动重置该阶段及后续的完成标记、清除旧交付选择,旧 checkpoint 保留在 history;修复、验证和复审后再次等待选择。需求变化需回 F3,规模变化同时写 size。
82
- - 用户明确选交付:save `stage: F8`、`status: running`、`decision: {"action":"deliver","confirmed":true}`;bug 留在 B5。只记录用户实际确认的选择,遗留风险写 context。
87
+ - 用户明确选交付:按 execution.md 核对本轮证据,save `stage: F8`、`status: running`、`decision: {"action":"deliver","confirmed":true}`;bug 留在 B5。只记录用户实际确认的选择,遗留风险写 context。
83
88
  - 等方案确认:`status: waiting_user`,waiting_for 说明待确认方案;方案已写不代表用户已同意。
84
89
  - 环境等阻塞:`status: blocked`、reason 说明原因,保留步骤与 remaining;解除后 save running。
85
90
  - 取消:用 cancel,input 提供 reason,不能用 complete 把取消记成完成。
86
91
 
87
- 交付产物、自检、摘要和反馈已处理后,把最后步骤标 completed,再运行 complete。complete 要求所有步骤 completed 或有原因的 skipped;完整 dev 的方案、实现、验证、审查、交付核心步骤不能跳过,用户必须已选择交付,并有当前分支的 plan.md、review.md、delivery.md。其他文档/审查运行也检查当前分支的对应文件。验证步骤完成可以包含如实记录的“未验证”,不等于所有测试都通过。
92
+ 交付产物、自检、摘要和反馈已处理后,把最后步骤标 completed,再运行 complete。complete 要求所有步骤 completed 或有原因的 skipped;完整 dev 的方案、实现、验证、审查、交付核心步骤在 save 时就不能跳过,用户必须已选择交付,并有本运行已收尾、内容仍匹配且属于当前分支的 requirement.md、plan.md、review.md、delivery.md,以及有效代码与审查证据。独立审查也核对代码快照与报告收尾凭据,其他文档运行检查当前分支的对应文件。验证步骤完成可以包含如实记录的“未验证”,不等于所有测试都通过。
88
93
 
89
94
  complete 不接受待用户确认或 blocked 的运行。还在处理本次已承诺的交付事项时不能提前完成;可选下一步不属于本次运行范围。状态写入具有 revision 检查和短时元信息写锁;版本冲突时重新 show,核对并合并进度,不盲目重试覆盖。写入用 workflow-run/tmp/locks/ 下的短时锁目录(不落在需求目录、不会随产物提交),目录名为元信息相对路径的 SHA-256,避免长中文路径超过文件名限制。每次写入持有唯一的 PID/UUID 标记;只回收超过 30 秒且进程已退出的旧标记,非空锁目录不能删除,释放时也只删除自己的标记。mkdir 后尚未写入标记就崩溃的空目录,过期后同样自动恢复。
90
95
 
91
96
  ## 新会话恢复
92
97
 
93
- 1. 先确认业务项目根和当前工作分支,再 show;多个运行时按用户的任务选 id,不能把其他分支的状态直接套过来。
98
+ 1. 先确认业务项目根和当前工作分支,再 show;若提示 pending_finalization,先按 execution.md 恢复/取消收尾。多个运行时按用户的任务选 id,不能把其他分支的状态直接套过来。
94
99
  2. 读取 context、各步骤状态、waiting_for、reason、history 和关联文档,核对 git 改动、已有产物与证据是否仍适用。记录不是当前代码仍然正确的保证。
95
- 3. 从保存的阶段继续,已完成的有效步骤不重复执行。waiting_user 时先取得对应答复;不能将“继续”直接当成“交付”或接受风险。代码已变化而验证/报告失效时,回退到实现或验证阶段并 save,再验证与复审。
100
+ 3. 从保存的阶段继续,已完成的有效步骤不重复执行。waiting_user 时先取得对应答复;不能将“继续”直接当成“交付”或接受风险。show 的 freshness 会提示代码证据是否仍有效;代码已变化而验证/报告失效时,回退到实现或验证阶段并 save,再验证与复审。
96
101
  4. completed 运行只展示已完成及时间,不自动重启;需要新的工作时 start 新记录。旧需求没有 runs 时明确说明暂无可恢复状态,按文档和代码重建,经核对后再记录,不自动假定已完成。
97
102
 
98
103
  `artifacts.mjs` 的 execution 和 `/workflow status` 使用同一份状态;有未结束运行时 next 优先显示等待、阻塞或当前阶段,不越过修复/交付选择推荐后续动作。`/workflow view` 即使尚无 Markdown 也展示已有运行,包含“已完成”标识和完成时间。
@@ -17,6 +17,7 @@
17
17
  运行:<id / 暂无记录> | 状态:<进行中 / 等待用户 / 受阻 / 已完成 / 已取消> | 当前阶段:<stage>
18
18
  已完成步骤:<steps 中 completed 的名称> | 完成时间:<completed_at / —>
19
19
  等待 / 阻塞:<waiting_for / reason / 无>
20
+ 产物收尾:<pending_finalization 的种类与恢复命令 / 无> | 代码证据:<freshness / 暂未记录>
20
21
  | 环节 | 产物 | wiki |
21
22
  |---|---|---|
22
23
  | 方案 / 交付说明 / 审查报告 / 技术方案 / 上线方案 | <path 或「—」> | <pageId vN 或「未发布」> |
@@ -21,7 +21,7 @@ DocNexus 是必装组件,知识库 `workflow-run/docnexus/library/templates/<s
21
21
 
22
22
  ## 修改模板(/workflow template)
23
23
 
24
- 用户要改某份模板(「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」),或要新建、按样例重做模板时,用 `template.mjs` 一路走完,不要直接编辑生效中的模板文件。`<模板>` 写别名 `tech` / `release` / `plan` / `delivery` / `review` / `checklist`,或 `<skill>/<文件名>`;没说哪份时先 `template.mjs list` 列出来问。
24
+ 用户要改某份模板(「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」),或要新建、按样例重做模板时,用 `template.mjs` 一路走完,不要直接编辑生效中的模板文件。`<模板>` 写别名 `requirement` / `tech` / `release` / `plan` / `delivery` / `review` / `checklist`,或 `<skill>/<文件名>`;没说哪份时先 `template.mjs list` 列出来问。
25
25
 
26
26
  1. **起草稿**:`node <skills>/workflow/scripts/template.mjs draft <模板>`,把当前生效的模板复制到 `workflow-run/tmp/template-draft/<skill>/<文件名>`(输出的 `draft`)。草稿已存在会沿用(上次没改完);要从当前模板重来加 `--force`。
27
27
  - 退出码 2、`need_sample: true`:还没有这份模板,按下面「创建模板」第 1 步向用户要样例,再运行 `draft <模板> --from <样例文件>`(从 stdin 读用 `--from -`)。用户要「按这份文档重做模板」时同样用 `--from`。
@@ -31,7 +31,7 @@ DocNexus 是必装组件,知识库 `workflow-run/docnexus/library/templates/<s
31
31
  - `impact`:最近几份已生成的文档按新模板会多出哪些错误(例如新的必填章节它们没有)。只影响以后生成和 lint,已有文档不会被改;
32
32
  - `warnings`:例如没有任何必填章节;
33
33
  - 附上草稿全文(或改动的部分)。
34
- 4. **用户确认后保存**:`node <skills>/workflow/scripts/template.mjs save <模板>`。它不直接写知识库,退出码 2:按输出的 `hint` 走 capture 流程把草稿写入知识库(写入要用户授权),完成后运行 `resolve.mjs template <skill> <文件名>` 确认 `path` 指向知识库里的那份,再删除草稿。改的是带默认版本的模板(plan / delivery / review / checklist)时,知识库里的版本取代默认版本,以后升级 skills 也不会覆盖它。
34
+ 4. **用户确认后保存**:`node <skills>/workflow/scripts/template.mjs save <模板>`。它不直接写知识库,退出码 2:按输出的 `hint` 走 capture 流程把草稿写入知识库(写入要用户授权),完成后运行 `resolve.mjs template <skill> <文件名>` 确认 `path` 指向知识库里的那份,再删除草稿。改的是带默认版本的模板(requirement / plan / delivery / review / checklist)时,知识库里的版本取代默认版本,以后升级 skills 也不会覆盖它。
35
35
  5. 用户想撤销:DocNexus 里的模板按 timeline 恢复旧版本。
36
36
 
37
37
  ## 创建模板
@@ -0,0 +1,39 @@
1
+ #!/usr/bin/env node
2
+ // 正式文档写入入口;草稿在 tmp 中编辑,lint 通过后再发布、登记索引与运行证据。
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import { spawnSync } from 'node:child_process';
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';
10
+
11
+ export function main(argv) {
12
+ try {
13
+ const args = [...argv]; const action = args.shift(); const opts = {};
14
+ while (args.length) {
15
+ const key = args.shift();
16
+ if (!['--root', '--branch', '--id', '--expect-revision', '--kind', '--draft', '--input', '--packet', '--result'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
17
+ opts[key.slice(2)] = args.shift();
18
+ }
19
+ const root = path.resolve(opts.root ?? '.');
20
+ const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
21
+ const read = (p) => p ? JSON.parse(fs.readFileSync(p === '-' ? 0 : path.resolve(root, p), 'utf8')) : undefined;
22
+ 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 });
25
+ else if (action === 'finalize') {
26
+ const [skill, template] = ARTIFACT_TEMPLATES[opts.kind] ?? [];
27
+ if (!skill || !opts.draft) throw new Error('finalize 需要 --kind 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));
34
+ } 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
+ console.log(JSON.stringify(out, null, 2)); return 0;
36
+ } catch (e) { console.error(e.message); return 1; }
37
+ }
38
+ const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
39
+ if (invoked) process.exit(main(process.argv.slice(2)));
@@ -25,7 +25,7 @@ export function buildDescription(root, branch, base, workspace = loadWorkspace(r
25
25
  const view = branchView(root, branch, workspace);
26
26
  const texts = new Map(workspace.artifacts.map((a) => [a.path, a.text]));
27
27
  const read = (a) => a ? texts.get(a.path) : null;
28
- const { delivery, review, plan, tech, release } = view.latest;
28
+ const { requirement, delivery, review, plan, tech, release } = view.latest;
29
29
  const L = [];
30
30
  const add = (title, body) => { if (body) L.push(`## ${title}`, '', body, ''); };
31
31
 
@@ -57,7 +57,7 @@ export function buildDescription(root, branch, base, workspace = loadWorkspace(r
57
57
  add('影响面', keep(section(s, '影响面')));
58
58
  }
59
59
 
60
- const docs = [['方案', plan], ['交付说明', delivery], ['审查报告', review], ['技术方案', tech], ['上线方案', release]]
60
+ const docs = [['需求文档', requirement], ['方案', plan], ['交付说明', delivery], ['审查报告', review], ['技术方案', tech], ['上线方案', release]]
61
61
 
62
62
  .filter(([, a]) => a).map(([label, a]) => `- ${label}:\`${a.cite ?? a.path}\`${a.wiki?.url ? `(wiki:${a.wiki.url})` : a.wiki ? `(wiki pageId ${a.wiki.pageId})` : ''}`);
63
63
  add('相关文档', docs.length ? docs.join('\n') : null);
@@ -0,0 +1,59 @@
1
+ #!/usr/bin/env node
2
+ // 只交接事实与证据,不交接实现者自审结论;生成过程不推进运行。
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import { spawnSync } from 'node:child_process';
6
+ import { fileURLToPath } from 'node:url';
7
+ import { readRun } from '../lib/runs.mjs';
8
+ import { readProfile } from '../lib/project.mjs';
9
+ import { codeSnapshot, 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
+
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
+ if (isDev(run)) {
18
+ if (run.stage !== (run.kind === 'feature' ? 'F7' : 'B5')) throw new Error('请先完成验证并进入审查阶段');
19
+ assertValidation(root, req, run);
20
+ }
21
+ if (!['快审', '标准', '深审'].includes(depth)) throw new Error('审查深度须为快审 / 标准 / 深审');
22
+ const snapshot = codeSnapshot(root, run);
23
+ const reviewScope = scope(root, { base: run.scope?.base ?? 'main', exclude: run.scope?.exclude ?? [] });
24
+ if (!reviewScope.ok) throw new Error(reviewScope.error);
25
+ assertSnapshot(root, run, snapshot);
26
+ const profile = readProfile(root).profile;
27
+ const inputs = reviewInputs(run);
28
+ return {
29
+ run_id: id, revision: run.revision, project_root: path.resolve(root), skills: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'),
30
+ branch, depth, snapshot, inputs: hash(JSON.stringify(inputs)), scope: reviewScope, requirement: req.name, facts: inputs.facts,
31
+ requirement_document: run.artifacts?.requirement ?? null, plan: run.artifacts?.plan ?? null, previous_report: run.artifacts?.review ?? null,
32
+ validation: run.validation ?? null,
33
+ commands: Object.fromEntries(['main_branch', 'build', 'test', 'test_single', 'lint'].map((k) => [k, profile?.[k] ?? null])),
34
+ capabilities,
35
+ 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: ['未审文件'] } },
36
+ rules: '独立读代码,按 project-review 第 1~7 步审查;返回报告草稿和结构化结果,不改代码、不生成 delivery.md、不提交、不另建运行;主 agent 负责 finalize。零发现 findings 为空数组,scope.review 中每个文件必须进入 reviewed 或 uncovered。',
37
+ };
38
+ }
39
+
40
+ export function main(argv) {
41
+ try {
42
+ const args = [...argv]; const opts = {};
43
+ while (args.length) {
44
+ const key = args.shift();
45
+ if (!['--root', '--branch', '--id', '--depth', '--capabilities'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
46
+ opts[key.slice(2)] = args.shift();
47
+ }
48
+ const root = path.resolve(opts.root ?? '.');
49
+ const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
50
+ const capabilities = opts.capabilities ? JSON.parse(fs.readFileSync(path.resolve(root, opts.capabilities), 'utf8')) : null;
51
+ const packet = handoff(root, { branch, id: opts.id, depth: opts.depth, capabilities });
52
+ const file = path.join(root, 'workflow-run/tmp/review', packet.run_id, 'handoff.json');
53
+ fs.mkdirSync(path.dirname(file), { recursive: true });
54
+ fs.writeFileSync(file, `${JSON.stringify(packet, null, 2)}\n`);
55
+ console.log(JSON.stringify({ ok: true, path: path.relative(root, file).split(path.sep).join('/'), packet }, null, 2)); return 0;
56
+ } catch (e) { console.error(e.message); return 1; }
57
+ }
58
+ const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
59
+ if (invoked) process.exit(main(process.argv.slice(2)));
@@ -24,27 +24,8 @@ import { resolveTemplate } from './resolve.mjs';
24
24
  const git = (root, args) => spawnSync('git', ['-c', 'core.quotepath=false', ...args], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
25
25
  const toPosix = (p) => p.split(path.sep).join('/');
26
26
 
27
- // ---------------------------------------------------------------- glob
28
- // ** 跨目录、* 不跨 /、? 单个字符、{a,b} 展开(括号里同样支持这些写法);不含 / 的模式匹配文件名(同 .gitignore)。不区分大小写。
29
- // 没有闭合的 { 按普通字符处理(画像里写错也不会卡住)
30
- function globSource(glob) {
31
- let re = '';
32
- for (let i = 0; i < glob.length; i++) {
33
- const c = glob[i];
34
- const end = c === '{' ? glob.indexOf('}', i) : -1;
35
- if (c === '*' && glob[i + 1] === '*') {
36
- const slash = glob[i + 2] === '/';
37
- re += slash ? '(?:.*/)?' : '.*';
38
- i += slash ? 2 : 1;
39
- } else if (c === '*') re += '[^/]*';
40
- else if (c === '?') re += '[^/]';
41
- else if (end > i) { re += `(?:${glob.slice(i + 1, end).split(',').map(globSource).join('|')})`; i = end; }
42
- else re += c.replace(/[.+^$(){}|[\]\\]/g, '\\$&');
43
- }
44
- return re;
45
- }
46
- export const globToRegExp = (glob) => new RegExp(`^${globSource(glob)}$`, 'i');
47
- export const matchGlob = (p, glob) => globToRegExp(glob).test(glob.includes('/') ? p : p.split('/').pop());
27
+ import { matchGlob } from '../lib/path-match.mjs';
28
+ export { matchGlob, globToRegExp } from '../lib/path-match.mjs';
48
29
  const matchAny = (p, globs = []) => globs.find((g) => matchGlob(p, g)) ?? null;
49
30
 
50
31
  // ---------------------------------------------------------------- 跳过规则
@@ -5,7 +5,8 @@ import path from 'node:path';
5
5
  import { spawnSync } from 'node:child_process';
6
6
  import { fileURLToPath } from 'node:url';
7
7
 
8
- import { STATUS_LABELS, runState, startRun, changeRun } from '../lib/runs.mjs';
8
+ import { runState, startRun, changeRun, readRun } from '../lib/runs.mjs';
9
+ import { codeSnapshot } from '../lib/code-snapshot.mjs';
9
10
  export { FLOWS, STATUS_LABELS, allRuns, branchRuns, runState, startRun, changeRun } from '../lib/runs.mjs';
10
11
  const branchOf = (root) => spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim() || null;
11
12
 
@@ -22,13 +23,10 @@ function main(argv) {
22
23
  const input = opts.input ? JSON.parse(fs.readFileSync(opts.input === '-' ? 0 : path.resolve(root, opts.input), 'utf8')) : {};
23
24
  let out;
24
25
  if (action === 'show') {
25
- out = runState(root, branch);
26
- if (opts.id) {
27
- out.current = out.runs.find((r) => r.id === opts.id) ?? null;
28
- if (!out.current) throw new Error('当前分支没有这个运行');
29
- out.next = `${STATUS_LABELS[out.current.status]}:${out.current.stage}(${out.current.id})`;
30
- }
31
- } else if (action === 'start') out = startRun(root, { branch, kind: opts.kind, size: opts.size, input, dir: opts.dir });
26
+ out = runState(root, branch, undefined, opts.id);
27
+ if (opts.id && !out.current) throw new Error('当前分支没有这个运行');
28
+ } else if (action === 'snapshot') out = { ok: true, snapshot: codeSnapshot(root, readRun(root, branch, opts.id).run) };
29
+ else if (action === 'start') out = startRun(root, { branch, kind: opts.kind, size: opts.size, input, dir: opts.dir });
32
30
  else out = changeRun(root, { branch, id: opts.id, revision: opts['expect-revision'] === undefined ? null : Number(opts['expect-revision']), input, action });
33
31
  console.log(JSON.stringify(out, null, 2)); return 0;
34
32
  } catch (e) { console.error(e.message); return 1; }
@@ -10,7 +10,7 @@
10
10
  // node .agents/skills/workflow/scripts/template.mjs draft <模板> [--from <样例.md | ->] [--force]
11
11
  // node .agents/skills/workflow/scripts/template.mjs check <模板> [--file <草稿>]
12
12
  // node .agents/skills/workflow/scripts/template.mjs save <模板> [--file <草稿>]
13
- // <模板>:tech | release | plan | delivery | review | checklist,或 <skill>[/<模板文件名>](如 create-tech-md-doc/template.md)
13
+ // <模板>:requirement | tech | release | plan | delivery | review | checklist,或 <skill>[/<模板文件名>](如 create-tech-md-doc/template.md)
14
14
  // draft:把当前生效的模板复制成草稿;还没有模板(或 --from)时按样例抽骨架(make-template.mjs)。草稿已存在时不覆盖,--force 重来
15
15
  // check:草稿本身的格式问题、与当前模板相比的章节变化、拿最近几份已生成文档按新旧模板各跑一次 lint-doc 看影响
16
16
  // save:check 无错误后给出写入知识库的 capture 指引(写入后重新运行 resolve.mjs template 确认生效)
@@ -25,6 +25,7 @@ import { skeleton } from './make-template.mjs';
25
25
  import { collect } from './artifacts.mjs';
26
26
 
27
27
  const ALIASES = {
28
+ requirement: ['dev', 'requirement-template.md'],
28
29
  tech: ['create-tech-md-doc', 'template.md'],
29
30
  release: ['create-release-md-doc', 'template.md'],
30
31
  plan: ['dev', 'plan-template.md'],
@@ -33,7 +34,7 @@ const ALIASES = {
33
34
  checklist: ['project-review', 'checklist.md'],
34
35
  };
35
36
  // 模板 → 用它生成的产物种类(artifacts.mjs 的 KINDS),用来找已生成的文档试跑
36
- const PRODUCES = { 'create-tech-md-doc/template.md': 'tech', 'create-release-md-doc/template.md': 'release', 'dev/plan-template.md': 'plan', 'dev/delivery-template.md': 'delivery', 'project-review/report.md': 'review' };
37
+ const PRODUCES = { 'create-tech-md-doc/template.md': 'tech', 'create-release-md-doc/template.md': 'release', 'dev/requirement-template.md': 'requirement', 'dev/plan-template.md': 'plan', 'dev/delivery-template.md': 'delivery', 'project-review/report.md': 'review' };
37
38
  const SAMPLE_DOCS = 5;
38
39
 
39
40
  const rel = (root, p) => path.relative(root, p).split(path.sep).join('/');