@rowansenne/workflow-run 0.31.1 → 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 +11 -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 +23 -16
- package/create-tech-md-doc/references/prd.md +1 -1
- package/create-tech-md-doc/skill.json +1 -6
- package/docs/architecture.html +3 -2
- package/docs/development.md +2 -2
- package/docs/workflows.md +9 -4
- package/md-to-wiki/references/troubleshooting.md +1 -1
- package/md-to-wiki/scripts/md-to-wiki.mjs +13 -5
- package/package.json +1 -1
- package/workflow/lib/artifact-model.mjs +7 -2
- package/workflow/lib/requirements.mjs +1 -1
- package/workflow/references/document-sources.md +13 -0
- package/workflow/references/execution.md +2 -0
- package/workflow/references/feedback.md +1 -0
- package/workflow/scripts/document-sources.mjs +69 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,17 @@
|
|
|
4
4
|
|
|
5
5
|
## [Unreleased]
|
|
6
6
|
|
|
7
|
+
## [0.33.0] - 2026-11-04
|
|
8
|
+
|
|
9
|
+
### 新增
|
|
10
|
+
- 技术方案和上线方案优先复用同一需求、同一分支最近完成的 dev 运行所登记的文档版本,支持读取匹配的历史归档。技术方案补充设计取舍、交付结果和遗留风险,上线方案补充配置、待执行 SQL、迁移约束和回归场景;实现和部署事实仍按本次分支 diff 核实。
|
|
11
|
+
|
|
12
|
+
## [0.32.0] - 2026-11-02
|
|
13
|
+
|
|
14
|
+
### 优化
|
|
15
|
+
- 技术方案将自动化元信息放入文件头隐藏注释,不再强制正文引用块;保留分支收尾校验、产物归组与日期统计,兼容旧文档,事实自检显式指定三点 diff。正文遵循团队模板,保留说明和组件,不重复添加 Wiki 页面标题。
|
|
16
|
+
- Markdown 转 Wiki 的代码宏支持 `title="标题"`,可与语言组合;保留标题转义和 CDATA 处理。明确可选 CodeGraph 缺失但已完成替代分析时不算跳过步骤,并说明反馈记录版本与 npx 汇总版本的区别。
|
|
17
|
+
|
|
7
18
|
## [0.31.1] - 2026-11-02
|
|
8
19
|
|
|
9
20
|
### 修复
|
|
@@ -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,43 +36,50 @@ 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`)。
|
|
42
|
+
|
|
43
|
+
CodeGraph 是可选增强;未安装时用 diff 精读和代码搜索完成影响面分析,属于正常降级,不记为跳过 Step 2。确有未完成的分析才记录跳过项与原因。
|
|
40
44
|
|
|
41
45
|
### Step 3 — 选模板并填充
|
|
42
46
|
|
|
43
|
-
- 模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-tech-md-doc template.md`(`<skills>` 是本 skill 所在的 skills 目录,如 `.agents/skills`),读输出的 `path`,并把 `source`
|
|
47
|
+
- 模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-tech-md-doc template.md`(`<skills>` 是本 skill 所在的 skills 目录,如 `.agents/skills`),读输出的 `path`,并把 `source` 写进下面的隐藏元信息。模板缺失统一按 `workflow/references/templates.md` 创建或导入。
|
|
44
48
|
- 用户要修改、重新生成或换一份技术方案模板时,按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理(模板别名 `tech`;按样例重做用 `draft tech --from <样例>`),保存写入 DocNexus 知识库。
|
|
45
49
|
- 填充:模板的章节和编号因团队而异,**按章节含义**放事实,不按编号。下表是事实的来源,放进模板里含义对应的章节;模板里没有对应章节的事实不擅自加章节,在交付摘要里列出「模板中没有位置的事实」;模板有、但 diff 和 PRD 都给不出内容的章节写「待补充」。
|
|
46
50
|
|
|
47
51
|
| 事实 | 来源 |
|
|
48
52
|
|---|---|
|
|
49
|
-
| 需求背景 |
|
|
53
|
+
| 需求背景 | 优先引用查询返回的需求文档的目标、范围与已确认决定,按需用已确认的业务澄清补充;外部 PRD 用 `prd_context` 并标来源;都没有写「待补充」 |
|
|
50
54
|
| 影响范围 | 各层命中的模块 / 包名;代码图谱可用时补上 `cg.mjs impact --diff <main>...<dev>` 的受影响入口与模块(见 `<skills>/code-graph/SKILL.md`) |
|
|
51
|
-
| 详细方案 | Service
|
|
55
|
+
| 详细方案 | Service 变更;用 `plan.md` 补已落地的设计理由、技术取舍和兼容策略,用 `delivery.md` 补最终结果或缺陷根因;有 PRD 时补业务语义并标注来源 |
|
|
52
56
|
| 接口 / 消息协议 / 字段变更 | 接口与消息层、DTO / VO |
|
|
53
57
|
| 涉及服务 | git remote + 项目结构 + `profile.deploy` |
|
|
54
|
-
| 中间件变更(DB / 配置 / 依赖 / 定时任务) | SQL
|
|
58
|
+
| 中间件变更(DB / 配置 / 依赖 / 定时任务) | SQL、实体、配置、构建文件、定时任务;对照交付的配置与 SQL 清单;代码图谱可用时对照 `impact` 的 `sql` / `config_keys` |
|
|
55
59
|
| 数据链路 / 数据评审 | 有 PRD 且提及表名,或 `profile.data_review` 为 true 时;`prd_context.tables` / diff 推断 |
|
|
56
|
-
|
|
|
60
|
+
| 验收、验证与遗留风险 | 需求文档的 AC、交付的验证与未验证项;结合最终交付按需核对审查报告里的遗留风险和未覆盖场景 |
|
|
61
|
+
| 兼容问题与方案、PRD 对齐缺口 | diff 推断 + 已落实的方案约束 + PRD 对齐缺口(见 `references/prd.md`) |
|
|
57
62
|
|
|
58
|
-
-
|
|
63
|
+
- 正文遵循团队生效模板,不写「自动生成 / 对比分支 / diff 概览 / PRD 参考 / 模板来源」引用块;模板中与 Wiki 页面标题重复的独立文档标题不输出到正文,保留有业务含义的章节标题。
|
|
64
|
+
- 保留模板里的说明文字、表格和带标题代码块(围栏信息串用 `title="标题"`,可与语言组合);具体章节编号、说明内容和标题由模板决定,不在通用 skill 中写死。
|
|
65
|
+
- 文件开头(有 wiki 发布记录时紧随其后)写隐藏元信息,整个注释块保持在前 20 行内。它供分支校验、事实核对和产物索引使用,Markdown / Wiki 正文不展示;这些字段保留在注释中,`meta.json` 按现有逻辑保存绑定、索引和运行:
|
|
59
66
|
|
|
60
67
|
```markdown
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
>
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
+
<!-- workflow-run:
|
|
69
|
+
生成时间:<时间>
|
|
70
|
+
对比分支:`<dev>` ←→ `<main>`(主分支为基线)
|
|
71
|
+
diff 概览:<files> files changed, <ins> insertions(+), <del> deletions(-)
|
|
72
|
+
PRD 参考:<pageId 或 URL 或「无」/「PRD 增强已跳过」>
|
|
73
|
+
模板来源:<resolve 返回的 source>
|
|
74
|
+
-->
|
|
68
75
|
```
|
|
69
76
|
|
|
70
77
|
### Step 4 — 写文件
|
|
71
78
|
|
|
72
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`。
|
|
73
80
|
- 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
|
|
74
|
-
- 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-tech-md-doc --facts
|
|
75
|
-
-
|
|
81
|
+
- 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-tech-md-doc --facts --diff <main>...<dev>` 自检,显式按三点范围核对正文里的类名、文件、接口、表名。有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符);不再强制可见元信息行,但隐藏分支仍须与运行一致。「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
|
|
82
|
+
- 再把路径和摘要告诉用户,按取材规则列出实际引用的 dev 产物及版本。
|
|
76
83
|
|
|
77
84
|
### Step 5 — 后续(都需要用户同意)
|
|
78
85
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# PRD 增强(--prd)
|
|
2
2
|
|
|
3
|
-
拉取步骤、wiki 可用性判断与通用 `prd_context` 字段见 `references/prd-fetch.md`。任一步失败都回退纯 diff
|
|
3
|
+
拉取步骤、wiki 可用性判断与通用 `prd_context` 字段见 `references/prd-fetch.md`。任一步失败都回退纯 diff 流程,文件头隐藏元信息的「PRD 参考」写「PRD 增强已跳过」。
|
|
4
4
|
|
|
5
5
|
技术方案不需要额外字段,通用 `prd_context` 用于模板里的需求背景与数据链路类章节。
|
|
6
6
|
|
|
@@ -15,12 +15,7 @@
|
|
|
15
15
|
"title": "技术方案模板",
|
|
16
16
|
"summary": "create-tech-md-doc 生成技术方案时使用的模板。不随 skills 提供:第一次生成时按用户给的样例文档创建(见 workflow/references/templates.md「创建模板」)。",
|
|
17
17
|
"lint": {
|
|
18
|
-
"requiredMeta": [
|
|
19
|
-
"自动生成",
|
|
20
|
-
"对比分支",
|
|
21
|
-
"diff 概览",
|
|
22
|
-
"模板来源"
|
|
23
|
-
]
|
|
18
|
+
"requiredMeta": []
|
|
24
19
|
}
|
|
25
20
|
}
|
|
26
21
|
],
|
package/docs/architecture.html
CHANGED
|
@@ -193,7 +193,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
|
|
|
193
193
|
|
|
194
194
|
<header class="hero">
|
|
195
195
|
<div>
|
|
196
|
-
<div class="eyebrow">@rowansenne/workflow-run · 0.
|
|
196
|
+
<div class="eyebrow">@rowansenne/workflow-run · 0.32.0 · 2026-11-02</div>
|
|
197
197
|
<h1>让 AI 编程代理按团队的规矩干活</h1>
|
|
198
198
|
<p class="lede">一套装进项目里的 Agent Skills:从需求澄清、开发、测试、自审到技术方案和上线方案,每一步怎么做、做到什么程度、哪些事必须先问人,都写成团队共享的规则和脚本,随代码一起提交。</p>
|
|
199
199
|
<div class="facts">
|
|
@@ -406,6 +406,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
|
|
|
406
406
|
<div>
|
|
407
407
|
<h3>项目事实只写一处</h3>
|
|
408
408
|
<p>主分支、构建和测试命令、配置中心、发布平台、开发环境配置(<code>toolchain</code>:JDK / Maven / Node 的位置)都在 <code>workflow/profile.json</code>。模板里不写死任何公司或项目的约定,换个项目只改画像;个人机器不同的部分写进不提交的 <code>profile.local.json</code> 覆盖。</p>
|
|
409
|
+
<p>技术方案遵循 DocNexus 团队模板,保留说明和带标题代码块,不重复添加 Wiki 页面标题。分支、生成时间等机器元信息放在文件头隐藏注释中,供正式落盘与查询读取,Wiki 正文不展示;旧可见元信息仍兼容。事实自检显式指定 <code>--facts --diff <main>...<dev></code>。</p>
|
|
409
410
|
</div>
|
|
410
411
|
<div>
|
|
411
412
|
<h3>能用脚本就不靠模型</h3>
|
|
@@ -573,7 +574,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
|
|
|
573
574
|
<div class="tree"><pre>node .agents/skills/nacos-config/scripts/config.mjs inspect
|
|
574
575
|
node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resources/bootstrap.yml --file src/main/resources/application-test.yml --data-id order-test.yaml --key order.timeout</pre></div>
|
|
575
576
|
<p class="sub" style="margin-top:12px">支持 JSON / YAML / properties;首次解析 YAML 若缺依赖,在该 skill 目录运行 npm 安装。默认使用 Nacos 1.x / 2.x 的兼容 API,也可显式选择 2.x API 或 3.x Client API。<code>/workflow status</code> 与 <code>doctor</code> 均不测试 Nacos 远端连通性;doctor 会检查本机连接文件的忽略规则。</p>
|
|
576
|
-
<div class="callout">本页对应 0.
|
|
577
|
+
<div class="callout">本页对应 0.32.0,包含技术方案隐藏元信息、带标题代码宏、HTTP 接口验证规则、F2 业务核对与 F3 技术澄清流程;dev 工作流仅在用户显式要求时启动。</div>
|
|
577
578
|
</section>
|
|
578
579
|
|
|
579
580
|
<section>
|
package/docs/development.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
## 当前架构
|
|
6
6
|
|
|
7
|
-
本文对应 0.
|
|
7
|
+
本文对应 0.32.0(2026-11-02),包括技术方案隐藏元信息、带标题代码宏、F2 业务场景清单、F3 技术澄清、HTTP 接口验证、需求与方案证据失效规则,以及锁定依赖和发布包验证。
|
|
8
8
|
|
|
9
9
|
安装分发与任务运行分开。运行时由宿主代理读取 skill 规则、调用脚本;workflow-run 本身不启动常驻 Agent 服务。
|
|
10
10
|
|
|
@@ -143,7 +143,7 @@ workflow-run(安装器仓库)/
|
|
|
143
143
|
"requires": ["workflow"],
|
|
144
144
|
"optional": ["md-to-wiki", "create-release-md-doc"],
|
|
145
145
|
"shared": ["diff-collection-common.md", "prd-fetch.md"],
|
|
146
|
-
"templates": [{ "id": "template.md", "
|
|
146
|
+
"templates": [{ "id": "template.md", "title": "技术方案模板", "summary": "...", "lint": { "requiredMeta": [] } }],
|
|
147
147
|
"docnexus": { "category": "tech-design", "reason": "create-tech-md-doc skill 从技术方案中沉淀的决策、约定与风险", "readFrom": ["create-tech-md-doc", "dev"] }
|
|
148
148
|
}
|
|
149
149
|
```
|
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` |
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
2. 运行 `feedback` 汇总(或直接拿 `workflow-run/feedback/` 下的文件),按「常被跳过的步骤」「读不懂的规则」「提问太多」精简 SKILL.md,发新版本;
|
|
57
57
|
3. 各项目 `upgrade` 时清掉本项目旧版本的记录(git 历史里仍可找回),从新版本重新收集,回到第 1 步。
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
记录中的版本是生成记录时项目内已安装的 skill 版本;用新版 npx 执行汇总不会升级项目 skills 或改写旧记录。可选 CodeGraph 不可用但已用 diff / 代码搜索完成分析时,不记为跳过;实际漏做的分析和规则冲突仍如实记录。字段与记录规则见 `workflow/references/feedback.md`。
|
|
60
60
|
|
|
61
61
|
**PR / MR 描述**:`node <skills>/workflow/scripts/pr-desc.mjs [--branch b] [--base main] [--out 文件]` 把本分支的交付说明(做了什么、已确认的决定、改动、验证、配置 / SQL)、审查报告(结论、CRITICAL / HIGH、影响面)和相关文档路径汇总成描述;没有交付说明时退回用提交记录和改动文件列表。dev 交付后要提 PR 时会调用它;创建 PR 要你同意。
|
|
62
62
|
|
|
@@ -123,6 +123,10 @@ Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_inv
|
|
|
123
123
|
* 守则:不写库、不改凭据、不擅自 commit / push、不装新依赖;测试没跑就写「未验证」。
|
|
124
124
|
* DocNexus 是必装组件,缺失或查询失败时先修复;wiki、CodeGraph、数据库为可选增强,所有 Skill 共用开工能力快照与失败处理规则(`workflow/references/capabilities.md`)。
|
|
125
125
|
|
|
126
|
+
技术方案正文按 DocNexus 生效模板生成,保留说明文字和带标题代码块,不重复添加 Wiki 页面标题。生成时间、对比分支、diff 概览、PRD 参考和模板来源放在文件头的 `<!-- workflow-run: … -->` 隐藏注释中,兼容正式落盘、分支查询和日期统计,Wiki 转换时不展示;旧文档的可见元信息仍可读取。事实自检显式传 `--facts --diff <main>...<dev>`,不再强制正文出现自动化元信息引用块。团队章节编号和组件内容只在模板中维护。
|
|
127
|
+
|
|
128
|
+
技术方案和上线方案优先引用同需求、同分支最近完成的 dev 运行所登记的文档版本。技术方案侧重需求、设计取舍和交付结果,上线方案侧重配置、SQL、回归场景和遗留风险。实现和部署变更以本次 diff 和代码核实,dev 验证结果用于制定上线回归清单。没有已完成的 dev 运行时仍可基于 diff 和可用文档生成。
|
|
129
|
+
|
|
126
130
|
## 脚本化的规则
|
|
127
131
|
|
|
128
132
|
能写成确定规则的判断都放在脚本里,SKILL.md 只说明什么时候调用,不再让 agent 按文字描述自己判断:
|
|
@@ -139,11 +143,12 @@ Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_inv
|
|
|
139
143
|
| `workflow/lib/capabilities.mjs` | 集中探测必装 DocNexus 与可选增强;供 resolve status 输出本轮能力快照 |
|
|
140
144
|
| `workflow/scripts/resolve.mjs status` | `/workflow status` 的能力探测(不输出任何凭据) |
|
|
141
145
|
| `workflow/scripts/resolve.mjs infer-profile` | 按固定规则从构建文件、Makefile、依赖与配置文件、git 推断项目画像草稿,每个字段附依据;不写文件 |
|
|
142
|
-
| `workflow/scripts/lint-doc.mjs <文档> --skill <skill> [--facts]` |
|
|
146
|
+
| `workflow/scripts/lint-doc.mjs <文档> --skill <skill> [--facts --diff <main>...<dev>]` | 对照当前生效的模板检查必填章节、残留占位符和该 skill 要求的元信息;缺普通章节、顺序不一致为警告;列出待填写位置。技术方案不强制可见元信息,事实核对显式指定三点范围;正文里的类名、文件、接口、表名在 diff 和代码里都找不到时给出警告 |
|
|
143
147
|
| `workflow/scripts/requirement.mjs which / bind / path / sync / pending / list / config` | 产物按需求归档(`workflow-run/docs/requirements/<需求>/<项目>/`,两种模式结构相同):查当前分支绑定的需求(没绑定时给出按分支名生成的建议名)、绑定需求名、给出本次落盘路径(不覆盖,带上一版的 wiki 记录)、重建 `meta.json`、列出所有需求;`config` 设置产物位置(文档仓库、项目名、提交提示),`pending` 看文档仓库里还没提交的产物 |
|
|
144
148
|
| `workflow/scripts/view.mjs [--out f] [--open]` | 项目文档视图(`/workflow view`、`npx @rowansenne/workflow-run view`):读需求目录里的产物,生成单个 HTML,按需求列出各阶段、审查记录(各级别数量、复核、与上次对比)、交付记录、沉淀到的知识文档,正文直接渲染;顶部「知识文档」列出每篇知识文档来自哪个需求、哪份产物;数据内嵌,只读、不联网,默认写到 `workflow-run/tmp/view/index.html` |
|
|
145
149
|
| `workflow/scripts/run.mjs show / start / save / complete / cancel` | 需求 meta.json 中的分支运行记录:恢复、checkpoint、已完成状态与时间、等待用户、修复回退、revision 冲突检查 |
|
|
146
|
-
| `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 运行的产物版本;上线方案同时查找可关联的技术方案 |
|
|
147
152
|
| `workflow/scripts/report.mjs [--since d] [--all-branches] [--json]` | 本地效果报告(`/workflow report`、`npx @rowansenne/workflow-run report`):审查发现与修复率、复核率、需求澄清、沉淀率、知识引用、各分支链路 |
|
|
148
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` 装了新版本时清掉本项目旧版本的记录 |
|
|
149
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 自审使用 |
|
|
@@ -10,7 +10,7 @@ node md-to-wiki.mjs --check <html> # 只做良构校验
|
|
|
10
10
|
只用 Node 内置能力,不依赖第三方库,也不调用 wiki API:
|
|
11
11
|
|
|
12
12
|
1. 自带 Markdown 解析:ATX 标题、段落(单换行转 `<br/>`)、引用、有序 / 无序列表(可嵌套、任务列表)、GFM 表格(含对齐)、分隔线、行内代码 / 粗体 / 斜体 / 删除线 / 链接 / 图片 / 自动链接;
|
|
13
|
-
2. 围栏代码块转 `<ac:structured-macro ac:name="code">` 宏,代码放进 `<![CDATA[...]]
|
|
13
|
+
2. 围栏代码块转 `<ac:structured-macro ac:name="code">` 宏,代码放进 `<![CDATA[...]]>`;信息串支持语言、`title="标题"`,或两者组合(如 `java title="示例"`),分别写入代码宏的 `language` / `title` 参数;
|
|
14
14
|
3. 原始 HTML 一律转义成文本,HTML 注释直接丢弃,保证输出良构;
|
|
15
15
|
4. 可选 banner:`--banner` 文件,或把正文第一个引用块移进 `<ac:structured-macro ac:name="info">`;
|
|
16
16
|
5. 写出文件后自动做良构校验,不良构时退出码为 1 并给出行号。
|
|
@@ -41,7 +41,7 @@ function inline(text) {
|
|
|
41
41
|
|
|
42
42
|
// ---------------------------------------------------------------- 块级
|
|
43
43
|
const RE = {
|
|
44
|
-
fence: /^ {0,3}(`{3,}|~{3,})\s*(
|
|
44
|
+
fence: /^ {0,3}(`{3,}|~{3,})\s*(.*)$/,
|
|
45
45
|
heading: /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/,
|
|
46
46
|
hr: /^ {0,3}([-*_])(\s*\1){2,}\s*$/,
|
|
47
47
|
quote: /^ {0,3}>\s?/,
|
|
@@ -57,9 +57,17 @@ const splitRow = (l) => {
|
|
|
57
57
|
return t.split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, '|'));
|
|
58
58
|
};
|
|
59
59
|
|
|
60
|
-
|
|
60
|
+
// 支持 java、title="标题" 和 java title="标题";其他围栏属性不作为语言。
|
|
61
|
+
function parseFenceInfo(info) {
|
|
62
|
+
const lang = info.trim().match(/^([\w+#.-]+)(?=\s|$)/)?.[1] ?? '';
|
|
63
|
+
const title = info.match(/(?:^|\s)title="([^"]*)"/)?.[1] ?? '';
|
|
64
|
+
return { lang, title };
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function codeMacro(lang, title, code) {
|
|
61
68
|
const body = code.replace(/]]>/g, ']]]]><![CDATA[>');
|
|
62
|
-
const p = lang ? `<ac:parameter ac:name="language">${esc(lang)}</ac:parameter>` : ''
|
|
69
|
+
const p = (lang ? `<ac:parameter ac:name="language">${esc(lang)}</ac:parameter>` : '')
|
|
70
|
+
+ (title ? `<ac:parameter ac:name="title">${esc(title)}</ac:parameter>` : '');
|
|
63
71
|
return `<ac:structured-macro ac:name="code" ac:schema-version="1">${p}<ac:plain-text-body><![CDATA[${body}]]></ac:plain-text-body></ac:structured-macro>`;
|
|
64
72
|
}
|
|
65
73
|
|
|
@@ -74,11 +82,11 @@ function blocks(lines) {
|
|
|
74
82
|
|
|
75
83
|
let m;
|
|
76
84
|
if ((m = line.match(RE.fence))) { // 围栏代码块
|
|
77
|
-
const fence = m[1]; const lang = m[2]; const body = [];
|
|
85
|
+
const fence = m[1]; const { lang, title } = parseFenceInfo(m[2]); const body = [];
|
|
78
86
|
i++;
|
|
79
87
|
while (i < lines.length && !new RegExp(`^ {0,3}${fence[0]}{${fence.length},}\\s*$`).test(lines[i])) body.push(lines[i++]);
|
|
80
88
|
i++;
|
|
81
|
-
out.push(codeMacro(lang, body.join('\n') + (body.length ? '\n' : '')));
|
|
89
|
+
out.push(codeMacro(lang, title, body.join('\n') + (body.length ? '\n' : '')));
|
|
82
90
|
continue;
|
|
83
91
|
}
|
|
84
92
|
if ((m = line.match(RE.heading))) { out.push(`<h${m[1].length}>${inline(m[2])}</h${m[1].length}>`); i++; continue; }
|
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",
|
|
@@ -15,6 +15,7 @@ export function parseFile(name) {
|
|
|
15
15
|
}
|
|
16
16
|
|
|
17
17
|
const head = (text, n = 20) => text.split(/\r?\n/).slice(0, n).join('\n');
|
|
18
|
+
// 兼容旧的可见元信息行,以及文件头 workflow-run 注释里的同格式分支。
|
|
18
19
|
export function parseBranch(text) {
|
|
19
20
|
const m = head(text).match(/(?:对比)?分支[::]\s*`?([^`\s||←,,))]+)`?/);
|
|
20
21
|
return m && !/^[{<]/.test(m[1]) ? m[1] : null;
|
|
@@ -29,8 +30,12 @@ export function parseDocnexus(text) {
|
|
|
29
30
|
const v = /DocNexus[::]\s*([^|\n]*)/.exec(head(text))?.[1]?.trim();
|
|
30
31
|
return v && /docnexus\/library\//.test(v) ? v.split(/[、,,]\s*/).map((s) => s.trim()).filter(Boolean) : null;
|
|
31
32
|
}
|
|
32
|
-
//
|
|
33
|
-
export
|
|
33
|
+
// 优先取隐藏生成时间;旧正文日期仍可读,md-to-wiki 的 at= 不作为文档日期。
|
|
34
|
+
export function headerDate(text) {
|
|
35
|
+
const hidden = /<!-- workflow-run:\s*\n([\s\S]*?)-->/.exec(head(text))?.[1];
|
|
36
|
+
return /生成时间[::]\s*(\d{4}-\d{2}-\d{2})/.exec(hidden ?? '')?.[1]
|
|
37
|
+
?? /(\d{4}-\d{2}-\d{2})/.exec(head(text.replace(/<!--[\s\S]*?-->/g, ''), 8))?.[1] ?? null;
|
|
38
|
+
}
|
|
34
39
|
|
|
35
40
|
const LEVELS = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'];
|
|
36
41
|
|
|
@@ -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 与版本,以及影响结论的缺失、差异和待确认项。按模板对应章节取材。
|
|
@@ -104,6 +104,8 @@ finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运
|
|
|
104
104
|
|
|
105
105
|
正式文档先写 tmp 草稿;不要先调用 `requirement.mjs path` 归档再直接覆盖,否则绕过收尾的中断保护。tech / release 分别在 T4 / L4 用 kind tech / release 收尾,使用各自的知识模板;wiki/沉淀后只更新发布或知识元信息仍可显式 sync。
|
|
106
106
|
|
|
107
|
+
技术方案将生成时间、对比分支、diff 概览、PRD 参考和模板来源放在文件头的 `<!-- workflow-run: … -->` 多行注释中(格式见 create-tech-md-doc,整个块在前 20 行内),不要求正文显示元信息引用块。分支校验仍读取注释中的 `对比分支:`,索引日期读取其中的 `生成时间:`;旧文档的可见元信息继续兼容。注释随正式文件一起归档并参与 hash 校验,Wiki 转换时移除;`meta.json` 仍按现有逻辑记录绑定、索引和运行,不自动接收全部注释字段。
|
|
108
|
+
|
|
107
109
|
两个文件无法一次原子提交,待办保存在同一个 meta.json 的 pending_finalization,草稿副本在 tmp/finalize/。中断期间其他元信息写入会被拒绝,show 的 next 提示恢复:
|
|
108
110
|
|
|
109
111
|
```sh
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
- **不问用户、不打断**:交付时静默记录,不为了记录多问一句,也不请用户打分。
|
|
8
8
|
- **只写过程,不写内容**:不写代码、类名、方法名、表名、接口路径、业务名词、客户信息。这个文件会被发给维护 skill 的人。
|
|
9
9
|
- **如实**:跳过了就写跳过,问了几轮就写几轮;不美化。拿不准的数字不写那个参数。
|
|
10
|
+
- **正常降级不算跳过**:可选 CodeGraph 未安装,但已用 diff / 代码搜索完成分析时,不写 `--skipped`;实际未完成的分析才记录。规则冲突仍用 `--unclear` 说明冲突双方,不能把校验通过当成已满足模板。
|
|
10
11
|
- **失败不影响交付**:命令报错就在对话里提一句,不重试、不排查。
|
|
11
12
|
- **一次运行记一行**:dev 内部调用 project-review 自审时只由 dev 记,project-review 不另记。
|
|
12
13
|
|
|
@@ -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
|
+
}
|