@rowansenne/workflow-run 0.32.0 → 0.33.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +5 -0
- package/create-release-md-doc/SKILL.md.tpl +11 -10
- package/create-release-md-doc/references/diff-collection.md +1 -1
- package/create-tech-md-doc/SKILL.md.tpl +9 -6
- package/docs/workflows.md +5 -2
- package/package.json +1 -1
- package/workflow/lib/requirements.mjs +1 -1
- package/workflow/references/document-sources.md +13 -0
- package/workflow/scripts/document-sources.mjs +69 -0
package/CHANGELOG.md
CHANGED
|
@@ -17,7 +17,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
|
|
|
17
17
|
|
|
18
18
|
- 两个分支都必填;用户只给一个时问另一个,不要默认 `master`。`--prd` / `--tech` 不能替代分支参数。
|
|
19
19
|
- `<mainBranch>` 用户没给但 `workflow/profile.json` 有 `main_branch` 时,可提出用它作为基线并请用户确认。
|
|
20
|
-
- `--tech <path
|
|
20
|
+
- `--tech <path>`:显式指定技术方案 Markdown,复用经核对的接口表 / 服务表 / DDL / 表名。没传时按 Step 2 查找同需求、同分支的技术方案,有匹配项就在引用中标注「自动关联」。用户说不用就跳过技术方案;dev 产物仍独立查询。
|
|
21
21
|
- `--prd`:Confluence PRD 的 pageId 或 URL,依赖 wiki 连接(见 Step 1)。
|
|
22
22
|
|
|
23
23
|
## Workflow
|
|
@@ -37,8 +37,9 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
|
|
|
37
37
|
|
|
38
38
|
### Step 2 — 采集 diff 并抽取事实
|
|
39
39
|
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
先读 `<skills>/workflow/references/document-sources.md`。优先读查询返回的 `delivery.md` 和 `requirement.md`,用交付配置、SQL、未验证项及需求 AC 制定发布和回归清单;需要核对遗留风险、覆盖缺口时读 `review.md`,需要了解已落地的发布顺序、兼容或迁移约束时读 `plan.md`。
|
|
41
|
+
|
|
42
|
+
按 `references/diff-collection.md` 用三点 `<main>...<dev>` 分层采集本次变更。技术方案(`--tech` 或自动关联)提供候选事实,按本次 diff 和相关代码逐项核对;无法核实的写「待补充」。有 `prd_context` 时做 PRD 对齐校验。
|
|
42
43
|
|
|
43
44
|
### Step 3 — 选模板并填充
|
|
44
45
|
|
|
@@ -49,11 +50,11 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
|
|
|
49
50
|
| 事实 | 来源 |
|
|
50
51
|
|---|---|
|
|
51
52
|
| 上线服务 / 改动范围 | git remote + 项目结构 + 改动范围 + `profile.deploy` |
|
|
52
|
-
| 中间件上线(DDL / 配置 / 依赖) | DDL
|
|
53
|
+
| 中间件上线(DDL / 配置 / 依赖) | DDL、实体、配置、构建文件;对照交付的配置清单和未执行 SQL,按需补方案里已落实的迁移约束;数据评审类章节仅 `profile.data_review` 为 true 时输出 |
|
|
53
54
|
| 灰度方案 | 有 PRD 时取 `prd_context.grayRelease`;否则写「待人工补充」 |
|
|
54
|
-
| 上线后验证 | 接口层 / `tech_context
|
|
55
|
+
| 上线后验证 | 接口层 / 经核对的 `tech_context`、需求 AC、交付未验证项、审查覆盖缺口;有 PRD 时追加业务场景;代码图谱可用时用 `cg.mjs impact --diff <main>...<dev>` 的 `entry_points` 补全要回归的接口 / 消费者 / 定时任务,`sql` / `config_keys` 对照中间件上线(见 `<skills>/code-graph/SKILL.md`) |
|
|
55
56
|
| 监控 | 变更类名 / 方法名 + 定时任务 + topic |
|
|
56
|
-
| 回滚 / 止损 | DDL / 配置 /
|
|
57
|
+
| 回滚 / 止损 | DDL / 配置 / 服务回滚推断,按需纳入方案中的兼容约束和交付时仍存在的审查风险;有 PRD 时追加对齐缺口 |
|
|
57
58
|
|
|
58
59
|
- 灰度、回滚策略属于推断内容,必须标「待人工确认」,不要写成已确定的方案。
|
|
59
60
|
- 文档开头写元信息:
|
|
@@ -64,9 +65,9 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
|
|
|
64
65
|
> diff 概览:<files> files changed, <ins> insertions(+), <del> deletions(-)
|
|
65
66
|
> PRD 参考:<pageId 或 URL 或「无」/「PRD 增强已跳过」>
|
|
66
67
|
> 模板来源:<DocNexus / 项目文件>
|
|
67
|
-
> 技术方案引用:<path
|
|
68
|
-
> 交付说明引用:<path
|
|
69
|
-
>
|
|
68
|
+
> 技术方案引用:<path、版本(如有)或「无」>
|
|
69
|
+
> 交付说明引用:<path、版本或「无」>
|
|
70
|
+
> 待补充章节:<已有取材来源都给不出内容的章节,没有写「无」>
|
|
70
71
|
> ⚠️ 灰度 / 回滚策略基于 diff 推断,需人工校对后补充。
|
|
71
72
|
```
|
|
72
73
|
|
|
@@ -75,7 +76,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
|
|
|
75
76
|
- 正式收尾:Step 4 进入 L4,先写 `workflow-run/tmp/release-doc.md` 草稿,再用 `node <skills>/workflow/scripts/artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind release --draft <草稿> --branch <dev分支>` 自检、归档旧版、发布并更新索引/运行证据;使用返回的 path / cite,规则见 `<skills>/workflow/references/execution.md`。
|
|
76
77
|
- 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
|
|
77
78
|
- 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-release-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
|
|
78
|
-
-
|
|
79
|
+
- 再把路径和摘要告诉用户,按取材规则列出实际引用的 dev 产物及版本。
|
|
79
80
|
|
|
80
81
|
### Step 5 — 后续(都需要用户同意)
|
|
81
82
|
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
|
|
21
21
|
## 复用技术方案(--tech)
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
显式指定或自动关联技术方案时,按章节含义解析接口、涉及服务、DB 变更、表名,形成 `tech_context`。对照本次 diff 核实后复用,按实际代码修正差异,并补上技术方案漏掉的变更。
|
|
24
24
|
|
|
25
25
|
## 特有抽取规则
|
|
26
26
|
|
|
@@ -36,7 +36,9 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
|
|
|
36
36
|
|
|
37
37
|
### Step 2 — 分层采集 diff 并抽取事实
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
先读 `<skills>/workflow/references/document-sources.md`,查询同需求、同分支已完成 dev 的产物版本。默认读返回的 `requirement.md`、`delivery.md`、`plan.md`;需要核对遗留风险、覆盖缺口时读 `review.md`,需要追溯需求文档未展开的已确认业务决策时读 `clarification.md`。
|
|
40
|
+
|
|
41
|
+
按 `references/diff-collection.md` 执行:用三点 `<main>...<dev>`,先 `--name-only` 分层列文件,再读具体 diff;实现事实以 diff 和相关代码为准,无法核实的写「待补充」。有 `prd_context` 时做 PRD 对齐校验(同见 `references/prd.md`)。
|
|
40
42
|
|
|
41
43
|
CodeGraph 是可选增强;未安装时用 diff 精读和代码搜索完成影响面分析,属于正常降级,不记为跳过 Step 2。确有未完成的分析才记录跳过项与原因。
|
|
42
44
|
|
|
@@ -48,14 +50,15 @@ CodeGraph 是可选增强;未安装时用 diff 精读和代码搜索完成影
|
|
|
48
50
|
|
|
49
51
|
| 事实 | 来源 |
|
|
50
52
|
|---|---|
|
|
51
|
-
| 需求背景 |
|
|
53
|
+
| 需求背景 | 优先引用查询返回的需求文档的目标、范围与已确认决定,按需用已确认的业务澄清补充;外部 PRD 用 `prd_context` 并标来源;都没有写「待补充」 |
|
|
52
54
|
| 影响范围 | 各层命中的模块 / 包名;代码图谱可用时补上 `cg.mjs impact --diff <main>...<dev>` 的受影响入口与模块(见 `<skills>/code-graph/SKILL.md`) |
|
|
53
|
-
| 详细方案 | Service
|
|
55
|
+
| 详细方案 | Service 变更;用 `plan.md` 补已落地的设计理由、技术取舍和兼容策略,用 `delivery.md` 补最终结果或缺陷根因;有 PRD 时补业务语义并标注来源 |
|
|
54
56
|
| 接口 / 消息协议 / 字段变更 | 接口与消息层、DTO / VO |
|
|
55
57
|
| 涉及服务 | git remote + 项目结构 + `profile.deploy` |
|
|
56
|
-
| 中间件变更(DB / 配置 / 依赖 / 定时任务) | SQL
|
|
58
|
+
| 中间件变更(DB / 配置 / 依赖 / 定时任务) | SQL、实体、配置、构建文件、定时任务;对照交付的配置与 SQL 清单;代码图谱可用时对照 `impact` 的 `sql` / `config_keys` |
|
|
57
59
|
| 数据链路 / 数据评审 | 有 PRD 且提及表名,或 `profile.data_review` 为 true 时;`prd_context.tables` / diff 推断 |
|
|
58
|
-
|
|
|
60
|
+
| 验收、验证与遗留风险 | 需求文档的 AC、交付的验证与未验证项;结合最终交付按需核对审查报告里的遗留风险和未覆盖场景 |
|
|
61
|
+
| 兼容问题与方案、PRD 对齐缺口 | diff 推断 + 已落实的方案约束 + PRD 对齐缺口(见 `references/prd.md`) |
|
|
59
62
|
|
|
60
63
|
- 正文遵循团队生效模板,不写「自动生成 / 对比分支 / diff 概览 / PRD 参考 / 模板来源」引用块;模板中与 Wiki 页面标题重复的独立文档标题不输出到正文,保留有业务含义的章节标题。
|
|
61
64
|
- 保留模板里的说明文字、表格和带标题代码块(围栏信息串用 `title="标题"`,可与语言组合);具体章节编号、说明内容和标题由模板决定,不在通用 skill 中写死。
|
|
@@ -76,7 +79,7 @@ PRD 参考:<pageId 或 URL 或「无」/「PRD 增强已跳过」>
|
|
|
76
79
|
- 正式收尾:Step 4 进入 T4,先写 `workflow-run/tmp/tech-doc.md` 草稿,再用 `node <skills>/workflow/scripts/artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind tech --draft <草稿> --branch <dev分支>` 自检、归档旧版、发布并更新索引/运行证据;使用返回的 path / cite,规则见 `<skills>/workflow/references/execution.md`。
|
|
77
80
|
- 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
|
|
78
81
|
- 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-tech-md-doc --facts --diff <main>...<dev>` 自检,显式按三点范围核对正文里的类名、文件、接口、表名。有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符);不再强制可见元信息行,但隐藏分支仍须与运行一致。「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
|
|
79
|
-
-
|
|
82
|
+
- 再把路径和摘要告诉用户,按取材规则列出实际引用的 dev 产物及版本。
|
|
80
83
|
|
|
81
84
|
### Step 5 — 后续(都需要用户同意)
|
|
82
85
|
|
package/docs/workflows.md
CHANGED
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
| 分支审查 | `用 project-review 审查当前分支相对 main 的改动` |
|
|
22
22
|
| 工作区快审 | `用 project-review 快审当前未提交的改动` |
|
|
23
23
|
| 技术方案 | `/create-tech-md-doc feature/order-export main --prd 123456` |
|
|
24
|
-
| 上线方案 | `/create-release-md-doc feature/order-export main
|
|
24
|
+
| 上线方案 | `/create-release-md-doc feature/order-export main`(自动查找同需求、同分支的技术方案) |
|
|
25
25
|
| wiki 校验 | `/md-to-wiki "技术方案.md" 123456 --validate-only` |
|
|
26
26
|
| wiki 发布 | `/md-to-wiki "技术方案.md" 123456`(需要已配置 wiki 和已有目标页面) |
|
|
27
27
|
| 只读查库 | `用 database-query 查询 test 连接:SELECT id, status FROM orders LIMIT 10` |
|
|
@@ -125,6 +125,8 @@ Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_inv
|
|
|
125
125
|
|
|
126
126
|
技术方案正文按 DocNexus 生效模板生成,保留说明文字和带标题代码块,不重复添加 Wiki 页面标题。生成时间、对比分支、diff 概览、PRD 参考和模板来源放在文件头的 `<!-- workflow-run: … -->` 隐藏注释中,兼容正式落盘、分支查询和日期统计,Wiki 转换时不展示;旧文档的可见元信息仍可读取。事实自检显式传 `--facts --diff <main>...<dev>`,不再强制正文出现自动化元信息引用块。团队章节编号和组件内容只在模板中维护。
|
|
127
127
|
|
|
128
|
+
技术方案和上线方案优先引用同需求、同分支最近完成的 dev 运行所登记的文档版本。技术方案侧重需求、设计取舍和交付结果,上线方案侧重配置、SQL、回归场景和遗留风险。实现和部署变更以本次 diff 和代码核实,dev 验证结果用于制定上线回归清单。没有已完成的 dev 运行时仍可基于 diff 和可用文档生成。
|
|
129
|
+
|
|
128
130
|
## 脚本化的规则
|
|
129
131
|
|
|
130
132
|
能写成确定规则的判断都放在脚本里,SKILL.md 只说明什么时候调用,不再让 agent 按文字描述自己判断:
|
|
@@ -145,7 +147,8 @@ Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_inv
|
|
|
145
147
|
| `workflow/scripts/requirement.mjs which / bind / path / sync / pending / list / config` | 产物按需求归档(`workflow-run/docs/requirements/<需求>/<项目>/`,两种模式结构相同):查当前分支绑定的需求(没绑定时给出按分支名生成的建议名)、绑定需求名、给出本次落盘路径(不覆盖,带上一版的 wiki 记录)、重建 `meta.json`、列出所有需求;`config` 设置产物位置(文档仓库、项目名、提交提示),`pending` 看文档仓库里还没提交的产物 |
|
|
146
148
|
| `workflow/scripts/view.mjs [--out f] [--open]` | 项目文档视图(`/workflow view`、`npx @rowansenne/workflow-run view`):读需求目录里的产物,生成单个 HTML,按需求列出各阶段、审查记录(各级别数量、复核、与上次对比)、交付记录、沉淀到的知识文档,正文直接渲染;顶部「知识文档」列出每篇知识文档来自哪个需求、哪份产物;数据内嵌,只读、不联网,默认写到 `workflow-run/tmp/view/index.html` |
|
|
147
149
|
| `workflow/scripts/run.mjs show / start / save / complete / cancel` | 需求 meta.json 中的分支运行记录:恢复、checkpoint、已完成状态与时间、等待用户、修复回退、revision 冲突检查 |
|
|
148
|
-
| `workflow/scripts/artifacts.mjs [--branch b \| --all]` | 按分支汇总 `workflow-run/docs/requirements/` 下的方案、交付说明、审查报告、技术方案、上线方案及其 wiki
|
|
150
|
+
| `workflow/scripts/artifacts.mjs [--branch b \| --all]` | 按分支汇总 `workflow-run/docs/requirements/` 下的方案、交付说明、审查报告、技术方案、上线方案及其 wiki 发布记录,给出下一步建议;分支取自文件头元信息(兼容技术方案的隐藏注释与旧可见行)。project-review 据此对照本分支方案、识别复审 |
|
|
151
|
+
| `workflow/scripts/document-sources.mjs --branch b --id <文档运行id>` | 为技术方案和上线方案查询同一需求、分支和最近已完成 dev 运行的产物版本;上线方案同时查找可关联的技术方案 |
|
|
149
152
|
| `workflow/scripts/report.mjs [--since d] [--all-branches] [--json]` | 本地效果报告(`/workflow report`、`npx @rowansenne/workflow-run report`):审查发现与修复率、复核率、需求澄清、沉淀率、知识引用、各分支链路 |
|
|
150
153
|
| `workflow/scripts/feedback.mjs add … / summary [--json]` | 运行反馈:dev / project-review 交付后追加一行过程记录到 `workflow-run/feedback/<用户>.jsonl`;`summary` 按 skill 汇总,跳过的步骤和不清楚的规则按 SKILL.md 章节归类(`npx @rowansenne/workflow-run feedback`);`init` / `upgrade` 装了新版本时清掉本项目旧版本的记录 |
|
|
151
154
|
| `workflow/scripts/review-scope.mjs [--diff b...h \| --base b] [--exclude a,b]` / `rules <文件…>` | 审查范围:由脚本决定审哪些文件、跳过哪些(删除、二进制、敏感文件、依赖目录、生成文件、文档、本工具产物,各带原因)、每个文件的风险级别和分批,以及按文件类型和改动内容该看审查清单的哪几节;`--base` 含未提交和未跟踪的新文件。`rules` 打印这些小节的原文和画像 `review.rules` 里匹配的项目规则。project-review 第 1、3、4 步与 dev 自审使用 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rowansenne/workflow-run",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.33.0",
|
|
4
4
|
"description": "项目级 Agent Skills 一键初始化:workflow / dev / project-review / code-graph / database-query / nacos-config / md-to-wiki / 需求文档与技术上线方案生成",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent-skills",
|
|
@@ -19,7 +19,7 @@ const skipDir = (d) => !d.isDirectory() || d.name.startsWith('.');
|
|
|
19
19
|
// path 时把当前版复制到 workflow-run/tmp/old-artifacts/<需求目录(相对 requirements/)>/<种类>_v<N>.md(不提交),
|
|
20
20
|
// 写完 sync <path> 时新版内容和这份副本不同才算新版本(versions 加一);没写就放弃的话版本号不变
|
|
21
21
|
export const OLD_DIR = `${TMP_DIR}/old-artifacts`;
|
|
22
|
-
const archivePath = (root, dirAbs, kind, v) => path.join(root, OLD_DIR, path.relative(path.join(root, REQ_DIR), dirAbs), `${FILES[kind]}_v${v}.md`);
|
|
22
|
+
export const archivePath = (root, dirAbs, kind, v) => path.join(root, OLD_DIR, path.relative(path.join(root, REQ_DIR), dirAbs), `${FILES[kind]}_v${v}.md`);
|
|
23
23
|
const versionsOf = (dirAbs) => readJson(path.join(dirAbs, 'meta.json'))?.versions ?? {};
|
|
24
24
|
|
|
25
25
|
export function indexArtifacts(dir, versions = {}) {
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# 技术方案与上线方案取材
|
|
2
|
+
|
|
3
|
+
确定需求并创建或恢复文档运行后,在项目根运行:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
node <skills>/workflow/scripts/document-sources.mjs --branch <开发分支> --id <文档运行id>
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
- `dev` 是同一项目、需求和开发分支上最近完成的 `feature` / `bug` 运行。`artifacts` 给出该次运行登记的产物版本、读取路径和引用。最新版已被覆盖时,使用内容匹配的同版本归档;`missing` 中的文件略过,不借用其他轮次的版本。`content_changed: true` 表示当前文件版本相同但收尾后的内容已变化(例如更新了 Wiki 或 DocNexus 元信息),正文先与其他来源核对,无法核实的内容只作为线索。
|
|
10
|
+
- `dev: null` 时,按同一需求和分支的需求文档补充背景与验收;上线方案也可读取同范围的交付说明作为线索。快速通道、旧产物和未完成的运行都可继续按 diff 和可选 PRD 生成。上线方案的 `tech` 是同一需求和分支的技术方案候选,显式 `--tech` 优先。
|
|
11
|
+
- 用本次 `<main>...<dev>` 的三点 diff 与相关代码核实实现和部署事实。方案、审查、交付说明或旧技术方案与本次改动冲突时,以本次代码为准,在交付摘要指出影响文档结论的差异。设计意图和已确认的业务取舍标明来源,计划中的行为要核实是否落地。
|
|
12
|
+
- dev 验证与审查只覆盖原运行的代码、范围和环境,报告时标明来源。代码或基线变化、覆盖范围不一致或无法确认时,将结果视为历史记录,相关场景列为待回归。上线后的验证结果需要上线后实际执行才能填写。
|
|
13
|
+
- 交付摘要列出实际引用的文档路径或 cite 与版本,以及影响结论的缺失、差异和待确认项。按模板对应章节取材。
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// 为技术方案和上线方案只读查询同需求、同分支的 dev 产物。
|
|
3
|
+
import fs from 'node:fs';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { parseArgs } from 'node:util';
|
|
6
|
+
import { FILES, parseBranch } from '../lib/artifact-model.mjs';
|
|
7
|
+
import { hash } from '../lib/code-snapshot.mjs';
|
|
8
|
+
import { archivePath } from '../lib/requirements.mjs';
|
|
9
|
+
import { isDev } from '../lib/run-gates.mjs';
|
|
10
|
+
import { loadWorkspace } from '../lib/workspace-read.mjs';
|
|
11
|
+
|
|
12
|
+
function readArchive(file) {
|
|
13
|
+
try { return fs.readFileSync(file, 'utf8'); } catch (error) {
|
|
14
|
+
if (error.code !== 'ENOENT') throw error;
|
|
15
|
+
return null;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function sources(root, branch, id) {
|
|
20
|
+
const workspace = loadWorkspace(root);
|
|
21
|
+
const doc = workspace.runs.find((run) => run.id === id && run.branch === branch);
|
|
22
|
+
if (!doc || !['tech', 'release'].includes(doc.kind)) throw new Error('请指定目标分支上的技术方案或上线方案运行 id');
|
|
23
|
+
const req = workspace.requirements.find((item) => item.dir === doc.dir);
|
|
24
|
+
const items = workspace.artifacts.filter((a) => path.posix.dirname(a.path) === req.dir && a.branch === branch);
|
|
25
|
+
const latest = (kind) => req.meta.pending_finalization?.kind === kind ? null : items.findLast((a) => a.kind === kind);
|
|
26
|
+
const reference = ({ path, cite, version }) => ({ path, cite, version });
|
|
27
|
+
const dev = workspace.runs.filter((run) => run.dir === req.dir && run.branch === branch && isDev(run)
|
|
28
|
+
&& run.status === 'completed' && run.completed_at).sort((a, b) => a.completed_at.localeCompare(b.completed_at)).at(-1);
|
|
29
|
+
const artifacts = {};
|
|
30
|
+
const missing = [];
|
|
31
|
+
const kinds = dev ? ['requirement', 'delivery', 'plan', 'review', 'clarification'] : doc.kind === 'release' ? ['requirement', 'delivery'] : ['requirement'];
|
|
32
|
+
for (const kind of kinds) {
|
|
33
|
+
if (!dev) {
|
|
34
|
+
const item = latest(kind);
|
|
35
|
+
if (item) artifacts[kind] = reference(item);
|
|
36
|
+
continue;
|
|
37
|
+
}
|
|
38
|
+
const record = dev.artifacts?.[kind];
|
|
39
|
+
const current = items.find((a) => a.path === `${req.dir}/${FILES[kind]}.md` && a.version === record?.version);
|
|
40
|
+
const pending = req.meta.pending_finalization?.kind === kind;
|
|
41
|
+
if (current && !pending && hash(current.text) === record.hash) {
|
|
42
|
+
artifacts[kind] = reference(current);
|
|
43
|
+
continue;
|
|
44
|
+
}
|
|
45
|
+
if (Number.isSafeInteger(record?.version) && record.version > 0) {
|
|
46
|
+
const archive = archivePath(root, req.abs, kind, record.version);
|
|
47
|
+
const text = readArchive(archive);
|
|
48
|
+
if (text && hash(text) === record.hash && parseBranch(text) === branch) {
|
|
49
|
+
artifacts[kind] = { path: path.relative(root, archive).split(path.sep).join('/'), cite: workspace.layout.ref(path.join(req.abs, `${FILES[kind]}.md`)), version: record.version };
|
|
50
|
+
continue;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
// 发布 Wiki 或更新 DocNexus 状态会改变文件哈希,仍可按登记版本读取为待核对的背景。
|
|
54
|
+
if (current && !pending) artifacts[kind] = { ...reference(current), content_changed: true };
|
|
55
|
+
else if (kind !== 'clarification' || record) missing.push(kind);
|
|
56
|
+
}
|
|
57
|
+
const tech = doc.kind === 'release' ? latest('tech') : null;
|
|
58
|
+
return { dev: dev ? { id: dev.id, completed_at: dev.completed_at, snapshot: dev.validation?.snapshot ?? null } : null,
|
|
59
|
+
artifacts, missing, ...(doc.kind === 'release' ? { tech: tech ? reference(tech) : null } : {}) };
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
try {
|
|
63
|
+
const { values } = parseArgs({ options: { root: { type: 'string', default: '.' }, branch: { type: 'string' }, id: { type: 'string' } } });
|
|
64
|
+
if (!values.branch || !values.id) throw new Error('用法:document-sources.mjs --branch <开发分支> --id <文档运行id>');
|
|
65
|
+
console.log(JSON.stringify(sources(path.resolve(values.root), values.branch, values.id), null, 2));
|
|
66
|
+
} catch (error) {
|
|
67
|
+
console.error(error.message);
|
|
68
|
+
process.exitCode = 1;
|
|
69
|
+
}
|