@rowansenne/workflow-run 0.33.0 → 0.35.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 CHANGED
@@ -4,6 +4,22 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.35.0] - 2026-11-16
8
+
9
+ ### 新增
10
+ - 新建 M / L 完整开发与缺陷修复运行在需求和方案收尾前增加独立文档审查。审查绑定草稿与依据,已有运行和 S 规模沿用原流程。
11
+
12
+ ### 修复
13
+ - WorkBuddy 安装 `dev` 时生成可补全的项目级 `/dev` 命令,并保留团队自定义的同名命令。
14
+
15
+ ## [0.34.0] - 2026-11-15
16
+
17
+ ### 优化
18
+ - 七种文档生成模板统一使用写作要求与正文骨架两部分。生成时遵守要求并填充骨架,章节校验只读取骨架。内置模板迁移到新格式,已有 DocNexus 模板继续兼容,代码审查清单沿用检查项格式。
19
+
20
+ ### 修复
21
+ - 跨平台规范化用户主目录路径。
22
+
7
23
  ## [0.33.0] - 2026-11-04
8
24
 
9
25
  ### 新增
@@ -5,6 +5,7 @@ import path from 'node:path';
5
5
  import { IS_WIN, CANON_DIR, INSTALL_BASES, MANIFEST, step, ok, warn, toPosix, fileHash, readManifest, removeEmptyDirs, lstat, timestamp, removeLink, docnexusInternal } from './core.mjs';
6
6
  import { removeDocNexusContext } from './docnexus.mjs';
7
7
  import { removeArtifactContext } from './artifact-context.mjs';
8
+ import { removeWorkBuddyDevCommand } from './workbuddy.mjs';
8
9
 
9
10
  // 软链接是否指向 absTarget(按解析后的绝对路径比较,兼容 Windows 上 readlink 返回的 \\?\ 前缀)
10
11
  export function linkPointsTo(link, absTarget) {
@@ -54,6 +55,7 @@ export function uninstall(root) {
54
55
  }
55
56
 
56
57
  removeArtifactContext(root);
58
+ removeWorkBuddyDevCommand(root);
57
59
 
58
60
  // 2. 各安装目录:按清单删除模板文件;用户配置与手改过的模板文件先备份
59
61
  for (const [rel, m] of found) {
@@ -0,0 +1,37 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { TPL_DIR, lstat, ok, sameFile, warn } from './core.mjs';
4
+
5
+ const commandPath = '.codebuddy/commands/dev.md';
6
+ const template = path.join(TPL_DIR, 'bin', 'workbuddy', 'dev.md');
7
+
8
+ function commandFile(root) {
9
+ const projectDir = path.join(root, '.codebuddy');
10
+ const commandsDir = path.join(projectDir, 'commands');
11
+ for (const dir of [projectDir, commandsDir]) {
12
+ const st = lstat(dir);
13
+ if (st && !st.isDirectory()) return null;
14
+ }
15
+ return path.join(root, commandPath);
16
+ }
17
+
18
+ export function installWorkBuddyDevCommand(root) {
19
+ const file = commandFile(root);
20
+ if (!file) { warn(`无法安装 ${commandPath},命令目录不是普通目录`); return; }
21
+ fs.mkdirSync(path.dirname(file), { recursive: true });
22
+ try {
23
+ fs.copyFileSync(template, file, fs.constants.COPYFILE_EXCL);
24
+ ok(`已安装 WorkBuddy /dev 项目命令:${commandPath}`);
25
+ } catch (error) {
26
+ if (error.code !== 'EEXIST') throw error;
27
+ if (!lstat(file)?.isFile() || !sameFile(file, template)) warn(`保留已有的 WorkBuddy 项目命令:${commandPath}`);
28
+ }
29
+ }
30
+
31
+ export function removeWorkBuddyDevCommand(root) {
32
+ const file = commandFile(root);
33
+ if (!file || !lstat(file)?.isFile() || !sameFile(file, template)) return;
34
+ fs.unlinkSync(file);
35
+ try { fs.rmdirSync(path.dirname(file)); } catch { /* 目录内可能有其他命令 */ }
36
+ ok(`已移除 WorkBuddy /dev 项目命令:${commandPath}`);
37
+ }
@@ -0,0 +1,10 @@
1
+ ---
2
+ description: "使用 dev 技能执行完整开发或缺陷修复流程"
3
+ argument-hint: "[需求、PRD 或 --bug <现象>]"
4
+ ---
5
+
6
+ <!-- workflow-run: WorkBuddy dev command -->
7
+
8
+ 用户明确调用了 `/dev`。先读取项目根目录下的 `.codebuddy/skills/dev/SKILL.md`,再按其中的流程处理下面的完整参数(包括 `--bug`)。未提供任务且未明确要求续接时,先询问要处理的需求或缺陷。
9
+
10
+ $ARGUMENTS
@@ -24,6 +24,7 @@ import { report, installSkills, linkSkills, updateGitignore, setupHome, recordEn
24
24
  import { setupCodeGraph } from './lib/codegraph.mjs';
25
25
  import { uninstall } from './lib/uninstall.mjs';
26
26
  import { writeArtifactContext } from './lib/artifact-context.mjs';
27
+ import { installWorkBuddyDevCommand } from './lib/workbuddy.mjs';
27
28
  import { checkNodeForDocNexus, setupDocNexus, refreshDocNexusLinks, cleanupLegacyDocNexus, templateRecords, saveTemplateRecords, reportTemplateStatus, installedSkills, docnexusConnected, printTemplateDiffs } from './lib/docnexus.mjs';
28
29
  import { upgradeOptions, doctor } from './lib/doctor.mjs';
29
30
  import { docsRepo } from './lib/docsrepo.mjs';
@@ -249,6 +250,8 @@ async function main() {
249
250
  if (r.failed.length) fail('必需文档模板导入失败,安装未完成。修复后运行 npx @rowansenne/workflow-run seed-templates 重试。');
250
251
  } catch (e) { fail(e.message); }
251
252
 
253
+ if (sel.includes('workbuddy') && skills.includes('dev')) installWorkBuddyDevCommand(o.root);
254
+
252
255
  step('安装完成,启用方式');
253
256
  console.log(' codex : 重启 codex 后自动发现项目级 skills(.agents/skills);也可 /use project-review 手动加载');
254
257
  console.log(' claude : Claude Code 自动发现 .claude/skills,无需额外配置');
@@ -44,6 +44,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
44
44
  ### Step 3 — 选模板并填充
45
45
 
46
46
  - 模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-release-md-doc template.md`(`<skills>` 是本 skill 所在的 skills 目录,如 `.agents/skills`),读输出的 `path`,并把 `source` 写进元数据行。模板缺失统一按 `workflow/references/templates.md` 创建或导入。
47
+ - 按 `workflow/references/templates.md`「文档模板的两部分」读取文档要求和正文骨架。遵守要求,只按正文骨架生成文档。无标记的旧模板沿用原有处理,边界有误时先修复模板。
47
48
  - 用户要修改、重新生成或换一份上线方案模板时,按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理(模板别名 `release`;按样例重做用 `draft release --from <样例>`),保存写入 DocNexus 知识库。
48
49
  - 填充:模板的章节和编号因团队而异,**按章节含义**放事实,不按编号。下表是事实的来源,放进模板里含义对应的章节;模板里没有对应章节的事实不擅自加章节,在交付摘要里列出「模板中没有位置的事实」;模板有、但 diff 和 PRD 都给不出内容的章节写「待补充」。
49
50
 
@@ -45,6 +45,7 @@ CodeGraph 是可选增强;未安装时用 diff 精读和代码搜索完成影
45
45
  ### Step 3 — 选模板并填充
46
46
 
47
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` 创建或导入。
48
+ - 按 `workflow/references/templates.md`「文档模板的两部分」读取文档要求和正文骨架。遵守要求,只按正文骨架生成文档。无标记的旧模板沿用原有处理,边界有误时先修复模板。
48
49
  - 用户要修改、重新生成或换一份技术方案模板时,按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理(模板别名 `tech`;按样例重做用 `draft tech --from <样例>`),保存写入 DocNexus 知识库。
49
50
  - 填充:模板的章节和编号因团队而异,**按章节含义**放事实,不按编号。下表是事实的来源,放进模板里含义对应的章节;模板里没有对应章节的事实不擅自加章节,在交付摘要里列出「模板中没有位置的事实」;模板有、但 diff 和 PRD 都给不出内容的章节写「待补充」。
50
51
 
package/dev/SKILL.md.tpl CHANGED
@@ -18,8 +18,10 @@ description: "Explicitly requested dev workflow for feature development or bug f
18
18
  ## 门禁
19
19
 
20
20
  - 开工先运行 `node <skills>/workflow/scripts/resolve.mjs status`;DocNexus 必装,不可用先修复。可选增强复用 `<skills>/workflow/references/capabilities.md` 的本轮快照。
21
+ - 生成澄清清单、需求、方案和交付说明时,按 `<skills>/workflow/references/templates.md`「文档模板的两部分」读取生效模板。遵守要求区,只用内容区生成正文。无标记的模板沿用旧格式,边界有误时先修复。
21
22
  - 先确定工作分支、已有改动的归属与需求名;切分支重新查询绑定,不替用户丢弃已有改动。
22
23
  - 规模由 agent 判定并说明,不询问规模确认;M / L 的需求理解和方案须用户确认后再实现,权限 / 资金至少按 M。
24
+ - 新建 M / L 完整运行(`document_review_policy: 1`)的需求与方案草稿在各自收尾前须经独立子 agent 审查。按 [execution.md 的文档审查](../workflow/references/execution.md#需求与方案审查) 交接;子 agent 不可用时等用户决定是否允许本次自查。S 和升级前已有运行沿用原门禁。
23
25
  - F2 先落偏业务场景的 clarification.md,供用户找产品核对;逐轮更新原问题状态、追加新问题和反馈。业务明确并完成现状调研后,再进入 F3 澄清技术约束;最终需求确认后进入 F4。
24
26
  - S 快速通道须用户明确同意,且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更,且没有 F2 / F3 已确认的业务决定、本次未发布正式清单且未创建完整流程运行;已有清单或运行沿用完整流程,具体资格见 F4。
25
27
  - 快速通道仍编译、测试、当前会话审查,但不 bind、不建运行、不落需求 / 方案 / 审查 / 交付文档;超限或用户要求落盘先停,回 F3(bug 回 B3)补需求文档,再进入方案。
@@ -52,11 +54,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
52
54
 
53
55
  ### F3 — 需求澄清(偏技术约束)
54
56
 
55
- 读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2 更新清单找产品确认。全部明确后,完整流程 finalize requirement.md、完成 F3,再进 F4。
57
+ 读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2 更新清单找产品确认。全部明确后,完整流程按文档门禁审查需求草稿,再确认、收尾 requirement.md、完成 F3,进入 F4。
56
58
 
57
59
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
58
60
 
59
- 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;涉及 HTTP 接口或接口行为变化时列出接口、AC、测试场景及命令 / 环境。S / M 简版、L 完整版,M / L 确认后记录 approval,再进入实现。
61
+ 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求起草方案,按文档门禁审查草稿,再用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;涉及 HTTP 接口或接口行为变化时列出接口、AC、测试场景及命令 / 环境。S / M 简版、L 完整版,M / L 确认后记录 approval,再进入实现。
60
62
 
61
63
  ### F5 — 实现
62
64
 
@@ -86,11 +88,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
86
88
 
87
89
  ### B3 — 定位根因
88
90
 
89
- 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程先生成独立 requirement.md、完成 B3,再进入修复方案。
91
+ 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程按文档门禁审查需求草稿并收尾 requirement.md、完成 B3,再进入修复方案。
90
92
 
91
93
  ### B4 — 修复与验证
92
94
 
93
- 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,用 `artifact.mjs finalize --kind plan` 收尾;M / L 确认后记录 approval、implement 再修复,复现测试由红变绿。
95
+ 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,按文档门禁审查后用 `artifact.mjs finalize --kind plan` 收尾;M / L 确认后记录 approval、implement 再修复,复现测试由红变绿。
94
96
 
95
97
  ### B5 — 审查与交付
96
98
 
@@ -18,12 +18,12 @@
18
18
  - 区分根因与症状:只在出错表象处加判空 / try-catch 不算修复,除非能说明那里就是根因。
19
19
  - 检查同一根因是否在其他调用方同样存在。
20
20
  - 预期业务行为还需产品确认时,按 clarify.md 的清单规则在 B3 初判规模、bind、start,逐轮发布同目录的 clarification.md 并保存等待反馈;需求明确后沿用该运行收尾需求文档。
21
- - 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成 requirement.md,用 `artifact.mjs finalize --kind requirement` 并标 B3 completed,再进 B4。根因证据作事实依据,修复方式留在 plan.md;已有文档先核对后在草稿更新,不自动覆盖原需求。
21
+ - 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成草稿,按 `clarify.md` 的 F3 审查适用草稿并完成需求理解确认,用 `artifact.mjs finalize --kind requirement` 收尾并标 B3 completed,再进 B4。根因证据作事实依据,修复方式留在 plan.md;已有文档先核对后在草稿更新,不自动覆盖原需求。
22
22
 
23
23
  ### B4 — 修复与验证
24
24
 
25
25
  - 复用 B3 收尾时按 F4 标准判定的规模和通道,不重复询问;范围变化时重新判定。快速通道退出时先回 B3 补需求文档,再补方案。
26
- - **完整流程先把修复方案追加进 `plan.md`**:沿用 B3 已绑定的需求与 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支、本次日期以及 requirement.md 的 cite / 版本。没有方案则按模板创建草稿,只填适用节。用 `artifact.mjs finalize --kind plan` 自检、归档旧版、发布并更新索引,不直接覆盖正式文件;输出的 previous 用于历史对照。运行 `artifacts.mjs --branch <当前修复分支>` 确认 latest.plan。M / L 取得用户确认后记录 approval,再 save implement: true;S 省 approval,仍须 implement。具体 JSON 和证据协议见 `<skills>/workflow/references/execution.md`。规模变化时说明依据、按新规模继续。
26
+ - **完整流程先把修复方案追加进 `plan.md`**:沿用 B3 已绑定的需求与 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支、本次日期以及 requirement.md 的 cite / 版本。没有方案则按模板创建草稿,只填适用节。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」完成适用审查,再用 `artifact.mjs finalize --kind plan` 自检、归档旧版、发布并更新索引,不直接覆盖正式文件;输出的 previous 用于历史对照。运行 `artifacts.mjs --branch <当前修复分支>` 确认 latest.plan。M / L 取得用户确认后记录 approval,再 save implement: true;S 省 approval,仍须 implement。具体 JSON 和证据协议见 `<skills>/workflow/references/execution.md`。规模变化时说明依据、按新规模继续。
27
27
  - 做能消除根因的**最小改动**;B2 的测试由红变绿,相关已有测试保持通过(运行方式同 F6)。
28
28
  - 如果历史脏数据需要修正,写成 SQL 脚本交给用户,不直接执行。
29
29
 
@@ -1,3 +1,7 @@
1
+ <!-- workflow-run:template-rules -->
2
+ - 用产品能核对的语言描述业务规则、范围和验收。接口、表结构和实现选择留到 F3 / F4。
3
+
4
+ <!-- workflow-run:template-content -->
1
5
  # 业务场景待确认清单 — {{需求名}}
2
6
 
3
7
  > 阶段:{{F2 / B3}} | 状态:{{待产品反馈 / 业务已明确}} | 轮次:{{1}} | 更新日期:{{YYYY-MM-DD}}
@@ -17,7 +21,7 @@
17
21
 
18
22
  | 编号 | 问题与场景 | 为什么要确认 / 影响 | 推荐答案与依据 | 产品 / 用户答复及来源 | 状态 |
19
23
  |---|---|---|---|---|---|
20
- | Q1 | {{关联 SC 场景,描述待定业务规则或范围;接口、表结构和实现选择留到 F3 / F4}} | {{影响的用户行为、范围或业务验收}} | {{用产品能理解的语言给建议及依据,不视为已确认}} | {{未答复 / 答复、来源与轮次}} | {{待确认 / 待 Qx 确认后讨论 / 已确认 / 已移出范围}} |
24
+ | Q1 | {{关联 SC 场景,描述待定业务规则或范围}} | {{影响的用户行为、范围或业务验收}} | {{给出建议及依据,不视为已确认}} | {{未答复 / 答复、来源与轮次}} | {{待确认 / 待 Qx 确认后讨论 / 已确认 / 已移出范围}} |
21
25
 
22
26
  ## 本轮核对摘要 *
23
27
 
@@ -56,6 +56,6 @@ F1 形成初版需求理解后,在 F2、进入 F3 之前先输出清单,不
56
56
 
57
57
  技术调研发现新的业务决定或场景冲突时,回 F2 更新业务清单并等待产品确认;确认后重查受影响的技术事实,再回 F3。已确认且不受影响的场景不重复问。bug 在 B3 内更新清单后继续技术澄清。
58
58
 
59
- 业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。M / L 等用户确认理解一致;已有答复可直接复用,不重复确认。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start),用 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并完成 F3 / B3,再进入 F4。
59
+ 业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start)。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」核对适用的需求草稿。M / L 等用户确认理解一致,已有答复能覆盖最终草稿时可直接复用。用 `artifact.mjs finalize --kind requirement` 收尾并完成 F3 / B3,再进入 F4 / B4。
60
60
 
61
61
  requirement.md 是最终需求事实来源,引用清单 cite 与版本,只汇总有效场景、决定与约束;清单保留业务往返核对过程,plan.md 保存实现设计。值得长期记住的规则与取舍在交付时作为 DocNexus 沉淀候选。
@@ -1,3 +1,7 @@
1
+ <!-- workflow-run:template-rules -->
2
+ - 小改动每节一两行即可,不适用的节写「无」。如实记录验证结果。
3
+
4
+ <!-- workflow-run:template-content -->
1
5
  # 开发交付 — {{需求或缺陷简述}}
2
6
 
3
7
  > 类型:{{功能开发 / 缺陷修复}} | 规模:{{S / M / L}} | 日期:{{YYYY-MM-DD}}
@@ -5,8 +9,6 @@
5
9
  > 参考产物:{{最新审查报告路径(独立子 agent 或当前会话自查);方案路径(非快速通道都有)}}
6
10
  > DocNexus:{{尚未发起询问写「未询问」;沉淀后写 workflow-run/docnexus/library/<path>;没有值得沉淀的内容写「无需沉淀」,已询问但未成功入库(含用户拒绝)写「未沉淀」}}
7
11
 
8
- <!-- F7 审查报告交给用户且用户明确选择交付后,F8 / B5 才用 artifact.mjs finalize --kind delivery 将草稿收尾到 workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md。小改动每节写一两行即可,不适用的节写「无」;验证结果必须如实 -->
9
-
10
12
  ## 结果 *
11
13
 
12
14
  {{一两句话:做成了什么;有无未完成项}}
@@ -1,12 +1,14 @@
1
+ <!-- workflow-run:template-rules -->
2
+ - 非快速通道一律落盘。S / M 只需要「方案依据」「改动设计」「风险与应对」「验证计划」,每节几行即可。L 写完整。
3
+ - 缺陷修复在 B4 的草稿中追加 `## 修复方案(根因 + 修复方式)`,与上一节用空行隔开,保留原方案正文。文档头更新为当前修复分支和日期,由 `artifact.mjs finalize --kind plan` 归档上一版。
4
+ - 标题里的「方案」同时覆盖功能开发与缺陷修复。
5
+
6
+ <!-- workflow-run:template-content -->
1
7
  # 方案 — {{需求名}}
2
8
 
3
9
  > 规模:{{S / M / L}} | 分支:{{dev分支}} | 日期:{{YYYY-MM-DD}}
4
10
  > 需求文档:{{requirement.md 的 cite 与版本}} | 参考记忆:{{workflow-run/docnexus/library/... 或「无」}}
5
11
 
6
- <!-- 非快速通道一律落盘:S / M 只需要第 1、3、4、6 节,每节几行即可;L 写完整。走 S 快速通道时不写本文件。
7
- 缺陷修复在 B4 的草稿中追加一节「## 修复方案(根因 + 修复方式)」,前面留一个空行与上一节隔开,保留原方案正文;文档头更新为当前修复分支和本次日期,上一版由 artifact.mjs finalize --kind plan 归档。
8
- 标题里的「方案」同时覆盖功能开发与缺陷修复两种用法。 -->
9
-
10
12
  ## 1. 方案依据
11
13
 
12
14
  - 需求文档:{{requirement.md 的 cite 与版本;目标、范围、验收与业务决定以该文档为准,不复制维护}}
@@ -26,7 +26,7 @@
26
26
  | 只有一两个技术取舍 | 给推荐和依据,能一轮确认就一轮结束 |
27
27
  | M / L 规模,或用户要求先把需求问清楚 | 逐轮确认约束,汇总需求、AC、不做什么与决定,等用户确认理解一致再进 F4 |
28
28
 
29
- **F3 的正式产物**:业务与技术约束均明确后,沿用已有绑定和运行、复核规模;没有清单时,完整流程在此 bind、start(stage F3,仅补记实际完成的 Step0、F1、F2)。用 `resolve.mjs template dev requirement-template.md` 读取模板,将目标、范围、AC、当前有效业务决定与必要技术约束写成草稿,在依据中引用业务清单 cite 与版本。通过 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并将 F3 标 completed,再进入 F4。不因清单发布或产品给了业务答复就跳过技术澄清。
29
+ **F3 的正式产物**:业务与技术约束均明确后,沿用已有绑定和运行、复核规模;没有清单时,完整流程在此 bind、start(stage F3,仅补记实际完成的 Step0、F1、F2)。用 `resolve.mjs template dev requirement-template.md` 读取模板,将目标、范围、AC、当前有效业务决定与必要技术约束写成草稿,在依据中引用业务清单 cite 与版本。按 `clarify.md` 的 F3 审查草稿、确认后,通过 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并将 F3 标 completed,再进入 F4。不因清单发布或产品给了业务答复就跳过技术澄清。
30
30
 
31
31
  requirement.md 是需求事实来源,context 只保存续接摘要。业务变化先回 F2 更新清单、复核现状,再到 F3 更新需求文档;仅技术约束变化回 F3;只调整实现设计则更新 F4 的方案。需求重新收尾后,更新依赖它的方案并重新确认 / 验证。历史需求不自动从旧 plan.md 拆出正文;恢复旧运行时先核实并补齐需求文档。
32
32
 
@@ -46,6 +46,6 @@ requirement.md 是需求事实来源,context 只保存续接摘要。业务变
46
46
 
47
47
  **S 规模快速通道(问用户)**:本次已发布正式清单或已创建完整流程运行时,直接沿用完整流程,不再询问快速通道;后续规模降为 S 也不切换。判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F2 / F3 中确认过的业务决定,且本次尚未发布正式清单、尚未创建完整流程运行时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F3 需求 → F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,先回 F3(缺陷回 B3)补写并 finalize requirement.md,再到 F4 / B4 补方案;M / L 等用户确认方案后再继续,S 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
48
48
 
49
- **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。方案草稿通过 `<skills>/workflow/references/execution.md` 的 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 等用户确认并 save approval 后再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
49
+ **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。草稿按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」完成适用审查,再用 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 等用户确认并 save approval 后再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
50
50
 
51
51
  **HTTP 接口验证计划**:涉及新增 / 修改 HTTP 接口,或参数校验、鉴权、状态码、响应结构及接口业务行为变化时,在验证计划列出方法、路径、关联 AC 与待测场景:正常请求、参数错误(有入参约束时),以及适用的未登录 / 无权限场景。沿用现有框架,明确已有用例如何复用、哪些需要补充、执行命令和环境;F6 按计划编写并执行。纯内部重构且接口行为不变、已有覆盖充分时只列现有测试,不另建重复用例。缺陷修复在 B4 使用相同规则。
@@ -1,3 +1,7 @@
1
+ <!-- workflow-run:template-rules -->
2
+ - 记录需求与依据,实现方案和测试执行结果留在对应产物。
3
+
4
+ <!-- workflow-run:template-content -->
1
5
  # 需求 — {{需求名}}
2
6
 
3
7
  > 规模:{{S / M / L}} | 分支:{{dev分支}} | 日期:{{YYYY-MM-DD}}
@@ -29,4 +33,4 @@
29
33
 
30
34
  ## 事实与依据(如有)
31
35
 
32
- {{PRD、代码、数据或远程配置的来源;有澄清清单时引用 clarification.md 的 cite 与版本,核对过程保留在清单中;缺陷修复附复现与根因证据,不在这里写实现方案或测试执行结果}}
36
+ {{PRD、代码、数据或远程配置的来源;有澄清清单时引用 clarification.md 的 cite 与版本,核对过程保留在清单中;缺陷修复附复现与根因证据}}
@@ -100,7 +100,7 @@ npx @rowansenne/workflow-run@latest doctor --offline
100
100
 
101
101
  这里用 `--copy` 在 `.codebuddy/skills/<skill>/` 生成真实目录和 `SKILL.md`,便于排除目录软链接的兼容问题。已有指向 `.agents/skills/` 的本工具链接会先转成独立拷贝,保留已填配置,再更新技能文件;共享来源和 Qwen 等其他环境的链接不变。后续 `upgrade` 沿用最近一次显式安装的环境和模式。只选择 WorkBuddy 时,全新安装不会生成 `.qwen/skills/`。
102
102
 
103
- 安装后,将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录,重新打开项目并新建会话,再尝试 `/workflow status`、`/dev` 或 `/project-review`。`/workflow profile` 等是技能参数,不是额外的独立技能。
103
+ 安装后,将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录,再新建任务。选择安装 `dev` 时,安装器会同时写入 `.codebuddy/commands/dev.md`,在输入框输入 `/` 可找到 `/dev`,也可输入 `/dev --bug <现象>`。已有同名命令原样保留。其他技能可在任务里显式指定,例如「使用 project-review 技能审查当前分支」。
104
104
 
105
105
  如果仍然不可见,先确认业务项目下确实有 `.codebuddy/skills/workflow/SKILL.md`,并保留安装命令、`doctor --offline` 输出与 WorkBuddy 版本以便排查。项目级配置目录见 [WorkBuddy 官方说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
106
106
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rowansenne/workflow-run",
3
- "version": "0.33.0",
3
+ "version": "0.35.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",
@@ -1,3 +1,7 @@
1
+ <!-- workflow-run:template-rules -->
2
+ - 只有已复核的 CRITICAL / HIGH 问题可以作为「不建议合并」的依据。
3
+
4
+ <!-- workflow-run:template-content -->
1
5
  # 代码审查报告 — {{范围}}
2
6
 
3
7
  > 审查范围:{{分支对比 / 单文件 / 未提交改动}}:{{范围说明}} | 日期:{{YYYY-MM-DD}}
@@ -8,7 +12,7 @@
8
12
 
9
13
  ## 结论摘要 *
10
14
 
11
- {{1-2 句总评:总体质量、关键风险、是否建议合并。只按「已复核」的 CRITICAL / HIGH 下「不建议合并」的结论}}
15
+ {{1-2 句总评:总体质量、关键风险、是否建议合并}}
12
16
 
13
17
  ## 与上次审查对比(如有)
14
18
 
@@ -27,7 +27,7 @@
27
27
 
28
28
  ## Output Template
29
29
 
30
- 报告结构以第 7 步取到的报告模板为准:元信息(审查范围、对比分支、审查方式、参考产物、DocNexus)、结论摘要、与上次审查对比(复审时)、严重问题(带触发条件与复核列)、一般问题、优化建议、需求对照(有方案时)、配置清单(如有)、影响面、未覆盖与待确认。某一节没有内容写「无」,不要删标题。
30
+ 按 `<skills>/workflow/references/templates.md`「文档模板的两部分」读取报告模板。遵守要求区,只用内容区生成正文。无标记的模板沿用旧格式,边界有误时先修复。报告结构以模板为准,包括元信息(审查范围、对比分支、审查方式、参考产物、DocNexus)、结论摘要、与上次审查对比(复审时)、严重问题(带触发条件与复核列)、一般问题、优化建议、需求对照(有方案时)、配置清单(如有)、影响面、未覆盖与待确认。某一节没有内容写「无」,不要删标题。
31
31
 
32
32
  > 灵活模式:单文件 / 小改动只在对话里回复时,可以直接列 findings,不必套完整模板;但每个结论必须指向真实文件+行号并引用代码,不得用"应该/大概"下结论,CRITICAL / HIGH 仍要复核。落盘的报告一律用模板。
33
33
 
@@ -6,7 +6,8 @@ import { FILES, parseBranch } from './artifact-model.mjs';
6
6
  import { hash, assertWorkingBranch, snapshotReader } from './code-snapshot.mjs';
7
7
  import { layout } from './project.mjs';
8
8
  import { readRun, assertRunVersion, applyCheckpoint } from './runs.mjs';
9
- import { isDev, coreSteps, applyDevEvidence, assertRequirement, assertPlanBasis, assertReview, assertDelivery, reviewEvidence } from './run-gates.mjs';
9
+ import { isDev, coreSteps, applyDevEvidence, assertRequirement, assertPlanBasis, assertReview, assertDelivery, reviewEvidence, documentReviewBasis } from './run-gates.mjs';
10
+ import { documentReviewEvidence, requiresDocumentReview } from './document-review.mjs';
10
11
  import { updateMeta } from './meta-store.mjs';
11
12
  import { OLD_DIR, indexArtifacts } from './requirements.mjs';
12
13
 
@@ -19,6 +20,15 @@ export const ARTIFACT_TEMPLATES = {
19
20
  const allowed = { feature: ['clarification', 'requirement', 'plan', 'review', 'delivery'], bug: ['clarification', 'requirement', 'plan', 'review', 'delivery'], review: ['review'], tech: ['tech'], release: ['release'] };
20
21
  const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
21
22
  const fileHash = (file) => fs.existsSync(file) ? hash(fs.readFileSync(file)) : null;
23
+ const wikiRecord = (s) => /^<!-- md-to-wiki: [^\n]*-->/.exec(s)?.[0] ?? null;
24
+
25
+ export function artifactDraft(req, kind, text) {
26
+ const file = path.join(req.abs, `${FILES[kind]}.md`);
27
+ const existingWiki = fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null;
28
+ const draftWiki = wikiRecord(text);
29
+ if (existingWiki && draftWiki && existingWiki !== draftWiki) throw new Error('新版必须保留原 wiki 页面记录;页面变更由 wiki 发布流程处理');
30
+ return { text: existingWiki && !draftWiki ? `${existingWiki}\n${text}` : text, existingWiki };
31
+ }
22
32
 
23
33
  export function resumeFinalization(root, { branch, id }) {
24
34
  const { req } = readRun(root, branch, id);
@@ -36,10 +46,12 @@ export function resumeFinalization(root, { branch, id }) {
36
46
  if (current !== p.before && current !== p.hash) throw new Error('正式产物在收尾中断后被其他操作修改,请先核对并恢复;不会覆盖');
37
47
  // 中断期间代码/报告也可能变化:发布前重新检查本轮门禁。
38
48
  const getSnapshot = snapshotReader(root, p.run);
39
- applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, { [p.kind]: fs.readFileSync(staged, 'utf8') }, getSnapshot);
40
- if (p.kind === 'plan') assertPlanBasis(root, req, p.run, { plan: fs.readFileSync(staged, 'utf8') });
49
+ const contents = { [p.kind]: fs.readFileSync(staged, 'utf8') };
50
+ applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, contents, getSnapshot);
51
+ if (p.kind === 'requirement') assertRequirement(root, req, p.run, contents);
52
+ if (p.kind === 'plan') assertPlanBasis(root, req, p.run, contents);
41
53
  if (p.kind === 'review' || (isDev(p.run) && p.kind === 'delivery')) {
42
- if (p.kind === 'review') assertReview(root, req, p.run, { review: fs.readFileSync(staged, 'utf8') }, getSnapshot);
54
+ if (p.kind === 'review') assertReview(root, req, p.run, contents, getSnapshot);
43
55
  else assertDelivery(root, req, p.run, undefined, getSnapshot);
44
56
  }
45
57
  if (current !== p.hash) {
@@ -91,11 +103,9 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
91
103
  if (!FILES[kind] || typeof text !== 'string') throw new Error('需要有效的产物 kind 和草稿正文');
92
104
  const { req } = readRun(root, branch, id);
93
105
  const file = path.join(req.abs, `${FILES[kind]}.md`);
94
- const wikiRecord = (s) => /^<!-- md-to-wiki: [^\n]*-->/.exec(s)?.[0] ?? null;
95
- const existingWiki = fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null;
96
- const draftWiki = wikiRecord(text);
97
- if (existingWiki && draftWiki && existingWiki !== draftWiki) throw new Error('新版必须保留原 wiki 页面记录;页面变更由 wiki 发布流程处理');
98
- if (existingWiki && !draftWiki) text = `${existingWiki}\n${text}`;
106
+ const draft = artifactDraft(req, kind, text);
107
+ const { existingWiki } = draft;
108
+ text = draft.text;
99
109
  const digest = hash(text);
100
110
  const key = hash(JSON.stringify({ id, revision, kind, digest, input, packet, result }));
101
111
  let repeated = null;
@@ -128,6 +138,9 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
128
138
  requirement = assertRequirement(root, req, run);
129
139
  if (run.steps[run.kind === 'feature' ? 'F3' : 'B3'].status !== 'completed') throw new Error('需求文档尚未完成,不能收尾方案');
130
140
  }
141
+ const documentReview = requiresDocumentReview(run, kind)
142
+ ? documentReviewEvidence(run, kind, digest, kind === 'plan' ? requirement : documentReviewBasis(root, req, run, kind), packet, result, at)
143
+ : null;
131
144
  if (isDev(run) && kind === 'delivery') assertDelivery(root, req, run, undefined, getSnapshot);
132
145
  if ((fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null) !== existingWiki) throw new Error('wiki 发布记录在收尾期间变化,请重新读取后重试');
133
146
  const before = fileHash(file);
@@ -135,6 +148,7 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
135
148
  const version = before === null ? 1 : oldVersion + (before === digest ? 0 : 1);
136
149
  const previous = before !== null && before !== digest ? relative(root, path.join(root, OLD_DIR, path.relative(path.join(root, 'workflow-run/docs/requirements'), req.abs), `${FILES[kind]}_v${oldVersion}.md`)) : null;
137
150
  run.artifacts = { ...(run.artifacts ?? {}), [kind]: { hash: digest, version, path: relative(root, file), previous, lint, at,
151
+ ...(documentReview ? { document_review: documentReview } : {}),
138
152
  ...(requirement ? { requirement: { hash: requirement.hash, version: requirement.version } } : {}) } };
139
153
  const clarificationChanged = kind === 'clarification' && current.artifacts?.clarification?.hash !== digest;
140
154
  if (clarificationChanged || (kind === 'plan' && (current.artifacts?.plan?.hash !== digest || current.artifacts?.plan?.requirement?.hash !== requirement.hash))
@@ -158,7 +172,7 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
158
172
  const staged = path.join(root, 'workflow-run/tmp/finalize', `${op}.md`);
159
173
  fs.mkdirSync(path.dirname(staged), { recursive: true });
160
174
  fs.writeFileSync(staged, text, { flag: 'wx' });
161
- return { ...meta, pending_finalization: { id: op, key, run_id: id, revision, kind, before, hash: digest, version, previous, staged: relative(root, staged), run, packet, checkpoint: input } };
175
+ return { ...meta, pending_finalization: { id: op, key, run_id: id, revision, kind, before, hash: digest, version, previous, staged: relative(root, staged), run, packet: kind === 'review' ? packet : null, checkpoint: input } };
162
176
  }, { root, allowFinalization: true });
163
177
  if (repeated) return repeated;
164
178
  return resumeFinalization(root, { branch, id });
@@ -0,0 +1,53 @@
1
+ import { hash } from './code-snapshot.mjs';
2
+
3
+ const stages = { feature: { requirement: 'F3', plan: 'F4' }, bug: { requirement: 'B3', plan: 'B4' } };
4
+ const nonempty = (value) => typeof value === 'string' && Boolean(value.trim());
5
+
6
+ export const documentReviewStage = (run, kind) => stages[run.kind]?.[kind];
7
+ export const requiresDocumentReview = (run, kind) =>
8
+ run.document_review_policy === 1 && ['M', 'L'].includes(run.size) && Boolean(documentReviewStage(run, kind));
9
+
10
+ export function documentReviewInputs(run, kind, draftHash, basis) {
11
+ return hash(JSON.stringify({
12
+ run_id: run.id, branch: run.branch, kind, draft_hash: draftHash,
13
+ basis: basis ? { hash: basis.hash, version: basis.version } : null,
14
+ }));
15
+ }
16
+
17
+ export function documentReviewEvidence(run, kind, draftHash, basis, packet, result, at) {
18
+ if (!packet || !result) throw new Error('本轮需要文档审查,请通过 --packet 和 --result 提交审查交接与结果');
19
+ const inputs = documentReviewInputs(run, kind, draftHash, basis);
20
+ const reviewedBasis = packet.basis;
21
+ const basisMatches = basis ? reviewedBasis?.path === basis.path && reviewedBasis.hash === basis.hash &&
22
+ reviewedBasis.version === basis.version && typeof reviewedBasis.text === 'string' && hash(reviewedBasis.text) === basis.hash
23
+ : reviewedBasis === null;
24
+ if (packet.run_id !== run.id || packet.kind !== kind || packet.inputs !== inputs ||
25
+ !Number.isInteger(packet.revision) || packet.revision < 1 || packet.revision > run.revision ||
26
+ packet.draft?.hash !== draftHash || typeof packet.draft.text !== 'string' || hash(packet.draft.text) !== draftHash || !basisMatches ||
27
+ result.run_id !== run.id || result.inputs !== inputs) {
28
+ throw new Error('文档审查不对应本轮草稿或其依据,请重新交接并审查');
29
+ }
30
+ if (!['independent', 'self'].includes(result.mode) || !nonempty(result.reviewer) || !nonempty(result.summary)) {
31
+ throw new Error('文档审查结果需要审查方式、审查者和结论');
32
+ }
33
+ if (result.mode === 'self' && (result.fallback?.confirmed !== true || !nonempty(result.fallback.reason))) {
34
+ throw new Error('自查降级须有用户明确同意及无法独立审查的原因');
35
+ }
36
+ if (!Array.isArray(result.findings) || result.findings.some((finding) =>
37
+ !nonempty(finding?.location) || !nonempty(finding.evidence) || !nonempty(finding.impact) ||
38
+ typeof finding.blocking !== 'boolean')) {
39
+ throw new Error('文档审查发现需要位置、依据、影响和 blocking 标记;没有发现时填空数组');
40
+ }
41
+ if (result.findings.some((finding) => finding.blocking)) throw new Error('文档审查仍有阻塞项,请修订并复审后再收尾');
42
+ return {
43
+ inputs, mode: result.mode, reviewer: result.reviewer, summary: result.summary, findings: result.findings, at,
44
+ ...(result.mode === 'self' ? { fallback: { confirmed: true, reason: result.fallback.reason } } : {}),
45
+ };
46
+ }
47
+
48
+ export function assertDocumentReview(run, kind, artifact, basis) {
49
+ if (requiresDocumentReview(run, kind) &&
50
+ artifact.document_review?.inputs !== documentReviewInputs(run, kind, artifact.hash, basis)) {
51
+ throw new Error(`缺少当前版本的文档审查:${kind}.md;请重新审查并收尾`);
52
+ }
53
+ }
@@ -142,7 +142,7 @@ export function expandPath(v, vars = {}, env = process.env) {
142
142
  const look = (n) => (vars[n] !== undefined && vars[n] !== '' ? vars[n] : (env[n] ?? ''));
143
143
  const home = look('HOME') || look('USERPROFILE') || '';
144
144
  let s = v;
145
- if (s === '~' || s.startsWith('~/') || s.startsWith('~\\')) s = home ? home + s.slice(1) : s;
145
+ if (s === '~' || s.startsWith('~/') || s.startsWith('~\\')) s = home ? path.join(home, s.slice(2)) : s;
146
146
  const missing = [];
147
147
  for (const m of v.matchAll(VAR_RE)) { const n = m[1] ?? m[2] ?? m[3]; if (!look(n)) missing.push(n); }
148
148
  const resolved = s.replace(VAR_RE, (m, a, b, c) => look(a ?? b ?? c)).replace(/[\\/]+$/, '');
@@ -3,6 +3,7 @@ import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { FILES, parseBranch } from './artifact-model.mjs';
5
5
  import { hash, assertSnapshot, assertWorkingBranch, snapshotReader } from './code-snapshot.mjs';
6
+ import { assertDocumentReview, requiresDocumentReview } from './document-review.mjs';
6
7
 
7
8
  export const isDev = (run) => ['feature', 'bug'].includes(run.kind);
8
9
  export const coreSteps = (run) => run.kind === 'feature' ? ['F3', 'F4', 'F5', 'F6', 'F7', 'F8'] : ['B3', 'B4', 'B5'];
@@ -15,14 +16,24 @@ export function receipt(root, req, run, kind, contents = {}) {
15
16
  return record;
16
17
  }
17
18
 
19
+ export function documentReviewBasis(root, req, run, kind) {
20
+ if (kind === 'plan') return assertRequirement(root, req, run);
21
+ return run.artifacts?.clarification ? receipt(root, req, run, 'clarification') : null;
22
+ }
23
+
18
24
  export function assertRequirement(root, req, run, contents) {
19
- return receipt(root, req, run, 'requirement', contents);
25
+ const requirement = receipt(root, req, run, 'requirement', contents);
26
+ if (requiresDocumentReview(run, 'requirement')) {
27
+ assertDocumentReview(run, 'requirement', requirement, documentReviewBasis(root, req, run, 'requirement'));
28
+ }
29
+ return requirement;
20
30
  }
21
31
 
22
32
  export function assertPlanBasis(root, req, run, contents) {
23
33
  const requirement = assertRequirement(root, req, run, contents);
24
34
  const plan = receipt(root, req, run, 'plan', contents);
25
35
  if (plan.requirement?.hash !== requirement.hash || plan.requirement.version !== requirement.version) throw new Error('方案依据的需求版本已变化,请根据当前 requirement.md 重新收尾方案');
36
+ assertDocumentReview(run, 'plan', plan, requirement);
26
37
  return plan;
27
38
  }
28
39
 
@@ -101,7 +112,7 @@ export function applyDevEvidence(root, req, run, patch, at, contents = {}, getSn
101
112
  if (run.steps[requirementStep].status !== 'completed') throw new Error('需求文档尚未完成,不能进入方案/修复阶段');
102
113
  }
103
114
  if (run.kind === 'feature') {
104
- if (completed('F4')) receipt(root, req, run, 'plan', contents);
115
+ if (completed('F4')) assertPlanBasis(root, req, run, contents);
105
116
  if (patch.stage === 'F6' || completed('F5')) {
106
117
  const plan = assertPlan(root, req, run, contents);
107
118
  if (run.implementation?.plan !== plan.hash) throw new Error('尚未通过方案门禁进入实现');
@@ -125,7 +125,8 @@ export function startRun(root, { branch, kind = 'feature', size = null, input =
125
125
  selected = applyCheckpoint({ id, kind, size, branch, revision: 1, status: 'running', stage: FLOWS[kind][0],
126
126
  created_at: at, updated_at: at, completed_at: null, steps: Object.fromEntries(FLOWS[kind].map((s) => [s, { status: 'pending' }])),
127
127
  scope: { base: meta.base || profile?.main_branch || 'main', exclude: Array.isArray(profile?.review?.exclude) ? profile.review.exclude.filter((v) => typeof v === 'string') : [] },
128
- artifacts: {}, context: {}, waiting_for: null, reason: null, decision: null, history: [] }, input, at);
128
+ artifacts: {}, context: {}, waiting_for: null, reason: null, decision: null, history: [],
129
+ ...(['feature', 'bug'].includes(kind) ? { document_review_policy: 1 } : {}) }, input, at);
129
130
  applyDevEvidence(root, req, selected, input, at);
130
131
  return { ...meta, runs: { ...runs, [id]: selected }, updated: at };
131
132
  }, { root });
@@ -0,0 +1,18 @@
1
+ // 文档模板可把写作要求放在正文骨架之前。旧模板仍视为完整骨架。
2
+ import { proseLines } from './document-model.mjs';
3
+
4
+ export const RULES_MARKER = '<!-- workflow-run:template-rules -->';
5
+ export const CONTENT_MARKER = '<!-- workflow-run:template-content -->';
6
+
7
+ export function templateParts(text) {
8
+ const lines = text.replace(/\r\n/g, '\n').split('\n');
9
+ const prose = proseLines(text);
10
+ const rules = prose.filter(({ text }) => text.trim() === RULES_MARKER).map(({ line }) => line - 1);
11
+ const content = prose.filter(({ text }) => text.trim() === CONTENT_MARKER).map(({ line }) => line - 1);
12
+ if (!rules.length && !content.length) return { content: text, offset: 0 };
13
+ if (rules.length !== 1 || content.length !== 1 || rules[0] >= content[0] || lines.slice(0, rules[0]).some((line) => line.trim())) {
14
+ return { content: '', error: '模板的要求和内容标记不完整、重复或顺序错误' };
15
+ }
16
+ const offset = content[0] + 1;
17
+ return { rules: lines.slice(rules[0] + 1, content[0]).join('\n'), content: lines.slice(offset).join('\n'), offset };
18
+ }
@@ -10,7 +10,7 @@
10
10
  {"scope":{"base":"main","exclude":["unrelated/**"]}}
11
11
  ```
12
12
 
13
- 完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 sync 代替收尾。模板仍由调用方用 `resolve.mjs template <skill> <id>` 读取。清单用 dev 的 clarification-template.md,每轮复制到 tmp 修改后发布:
13
+ 完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 sync 代替收尾。模板由调用方用 `resolve.mjs template <skill> <id>` 读取,按 [templates.md](templates.md) 的「文档模板的两部分」填充正文。首次生成清单时用 dev 的 clarification-template.md,后续各轮把上一版正式清单复制到 tmp 更新,再发布:
14
14
 
15
15
  ```sh
16
16
  node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind clarification --draft workflow-run/tmp/clarification.md --input workflow-run/tmp/checkpoint.json
@@ -43,6 +43,23 @@ M / L 取得用户实际确认后,用 save 记录 `approval: {"confirmed":true
43
43
 
44
44
  需求变化回 F3(bug 回 B3)重新澄清并 finalize requirement;程序清除旧方案确认、实现、验证、审查和交付选择,旧方案不能作为新需求的依据。即使方案正文不变,也要在 F4 / B4 重新收尾以绑定新需求版本;M / L 重新取得方案确认。只改实现方式则仅更新 plan,不改 requirement。手动改需求正文而未收尾也会使后续证据校验失败。
45
45
 
46
+ ## 需求与方案审查
47
+
48
+ 运行记录有 `document_review_policy: 1` 且当前规模为 M / L 时执行。S 和没有该字段的升级前运行沿用原流程。新运行从 S 升为 M / L 后,如已有未审查的需求或方案,回对应阶段补审。需求在 F3 / B3 审查并完成用户理解确认后收尾;方案在 F4 / B4 审查后收尾,沿用现有方案确认,再开始实现。
49
+
50
+ 1. 草稿写到 tmp 后生成交接。需求用 `--kind requirement`,方案用 `--kind plan`。交接记录将要收尾的草稿正文及已登记的业务澄清或需求依据。
51
+
52
+ ```sh
53
+ node <skills>/workflow/scripts/review-handoff.mjs --id <id> --kind <requirement|plan> --draft <草稿.md>
54
+ ```
55
+
56
+ 2. 将输出的交接 `path` 及相关原始材料交给未参与起草的子 agent。要求它阅读交接里的草稿和依据正文,按需核对原始需求、已确认决定或相关代码。省去主 agent 的自评和预设发现。子 agent 只审查,按 `packet.result_schema` 返回结论、位置、依据、影响和阻塞标记。
57
+ - 需求审查核对范围、场景、规则、技术约束和可验证的验收标准。缺陷修复还要核对现象、根因证据和预期行为。
58
+ - 方案审查以交接中的已定稿需求为依据,核对各验收项的实现与验证安排,以及适用的兼容性、权限、数据和回滚风险。
59
+ 3. 主 agent 修订阻塞项,业务取舍交给用户或产品定。草稿或依据变化后重新生成交接,由独立审查者复核阻塞项及受影响内容,返回对应最终草稿的结论。一般建议按实际情况采纳或说明取舍。在交付给用户确认时附审查结论及阻塞项处理结果。
60
+ 4. 子 agent 不可用时停在本阶段,记录 `waiting_user`,让用户选择等待独立审查或允许本次自查。只有明确同意后才自查,结果写 `mode: "self"`、实际审查者和 `fallback: {"confirmed":true,"reason":"无法派出子 agent 的实际原因"}`。独立审查结果写 `mode: "independent"` 和实际子 agent 标识。程序校验记录及文档内容,实际派遣和用户同意由主 agent 如实记录。
61
+ 5. 将最终结果保存为 tmp 下的 JSON。执行本阶段的 `artifact.mjs finalize` 时额外传 `--packet <交接JSON路径> --result <结果JSON路径>`。收尾会拒绝缺失、过期或仍有阻塞项的结果。通过后审查证据随需求或方案版本写入本次运行的产物记录;F7 / B5 的代码审查仍按下文执行。
62
+
46
63
  ## 验证证据
47
64
 
48
65
  feature 实现完成后 save F5 completed,进入 F6;bug 在 B4 验证。**测试/操作执行前**生成快照:
@@ -1,6 +1,6 @@
1
1
  # 模板来源(文档类 skill 共用)
2
2
 
3
- 澄清清单、需求、技术方案、上线方案、方案、审查清单的模板由脚本判定,各 skill 不自行查找:
3
+ 澄清清单、需求、方案、交付说明、技术方案、上线方案、审查报告与审查清单的模板由脚本判定,各 skill 不自行查找:
4
4
 
5
5
  ```
6
6
  node <skills>/workflow/scripts/resolve.mjs template <skill> <文件名>
@@ -19,6 +19,24 @@ DocNexus 是必装组件,知识库 `workflow-run/docnexus/library/templates/<s
19
19
 
20
20
  `resolve.mjs templates` 列出所有登记模板;登记表在各 Skill 的 `skill.json`。安装和升级自动补入内置模板。
21
21
 
22
+ ## 文档模板的两部分
23
+
24
+ 澄清清单、需求、方案、交付说明、技术方案、上线方案与审查报告使用同一个文件,按顺序放两个独立行标记。代码审查清单沿用检查项格式。
25
+
26
+ ```markdown
27
+ <!-- workflow-run:template-rules -->
28
+ 这里写团队对文档的要求和规定,例如内容依据、编写约束和审核要求。
29
+
30
+ <!-- workflow-run:template-content -->
31
+ # 【技术方案】{{文档标题}}
32
+ ## 需求背景 *
33
+ {{填写说明}}
34
+ ```
35
+
36
+ 生成时读取要求区并遵守其中规则,正文只按内容区的标题、说明、表格和代码块填充。只针对某一节或某列的填写提示留在原处。模板承载团队写作要求,技能中的流程和校验规则仍按技能执行。没有已确认的要求时可留空。
37
+
38
+ 要求标记放在首个非空行,两个标记必须各出现一次且顺序正确。边界有误时先修复。章节校验和变更比较只看正文骨架,生成者需另外核对自然语言要求。无标记的旧模板继续按原格式使用。需要迁移时,在草稿中移动已有规则并核对正文结构。已导入且未被团队修改的默认模板可用 `seed-templates --update` 更新,团队定制版可用 `seed-templates --diff` 对比。
39
+
22
40
  ## 修改模板(/workflow template)
23
41
 
24
42
  用户要改某份模板(「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」),或要新建、按样例重做模板时,用 `template.mjs` 一路走完,不要直接编辑生效中的模板文件。`<模板>` 写别名 `clarification` / `requirement` / `tech` / `release` / `plan` / `delivery` / `review` / `checklist`,或 `<skill>/<文件名>`;没说哪份时先 `template.mjs list` 列出来问。
@@ -41,7 +59,7 @@ DocNexus 是必装组件,知识库 `workflow-run/docnexus/library/templates/<s
41
59
  1. **要样例**:停下来告诉用户还没有这份模板,请用户给一份团队现有的同类文档:本地 Markdown 路径,或 wiki 页面的 pageId / URL。
42
60
  - wiki 页面:运行 `node <skills>/md-to-wiki/scripts/upload.mjs get <pageId> --text`,取输出的 `text` 作样例(需要 wiki 已配置,沿用开工 wiki 通道;无通道时请用户导出成 Markdown 或直接贴出内容)。
43
61
  - 用户手头没有样例:请用户列出要哪些章节、每节写什么,按同样的格式整理成模板。不要自己编一份「通用模板」。
44
- 2. **抽骨架**:把样例存到临时文件(如 `workflow-run/tmp/template-sample.md`),运行 `node <skills>/workflow/scripts/template.mjs draft <模板> --from <样例文件>`(内部用 `make-template.mjs` 抽骨架,结果写进草稿,之后按「修改模板」第 2–4 步完善、校验、保存)。它保留标题层级和表格列,正文换成 `{{...}}` 填写提示,丢掉标题前的元信息块(元信息由生成文档的 skill 自己写)。
62
+ 2. **抽骨架**:把样例存到临时文件(如 `workflow-run/tmp/template-sample.md`),运行 `node <skills>/workflow/scripts/template.mjs draft <模板> --from <样例文件>`(内部用 `make-template.mjs` 抽骨架,之后按「修改模板」第 2–4 步完善、校验、保存)。它保留标题层级和表格列,正文换成 `{{...}}` 填写提示,丢掉标题前的元信息块(元信息由生成文档的 skill 自己写)。文档模板草稿会自动加入两部分标记,要求区初始为空,根据团队确认的规则补充。
45
63
  3. **完善**:在骨架上改:
46
64
  - 把每节的 `{{...}}` 改成具体的填写说明(这一节写什么、从哪类事实来,例如「受影响的接口、模块,带文件路径」),不要把样例里的具体业务内容留在模板里;
47
65
  - 必填章节在标题末尾加 ` *`,可选章节在标题里加「(如有)」:`lint-doc.mjs` 靠这两个标记检查生成的文档;
@@ -18,6 +18,7 @@ import { spawnSync } from 'node:child_process';
18
18
  import { fileURLToPath } from 'node:url';
19
19
  import { resolveTemplate, skillMeta } from './resolve.mjs';
20
20
  import { proseLines, headings } from '../lib/document-model.mjs';
21
+ import { templateParts, RULES_MARKER, CONTENT_MARKER } from '../lib/template-parts.mjs';
21
22
  export { headings, headingKey } from '../lib/document-model.mjs';
22
23
 
23
24
  const TODO = /待填写|待补充|待人工确认/;
@@ -26,7 +27,9 @@ export function lint(doc, template, { requiredMeta = [] } = {}) {
26
27
  const errors = [];
27
28
  const warnings = [];
28
29
  const todos = [];
29
- const tpl = headings(template).filter((h) => !h.placeholder && h.key);
30
+ const parts = templateParts(template);
31
+ if (parts.error) errors.push(parts.error);
32
+ const tpl = headings(parts.content).filter((h) => !h.placeholder && h.key);
30
33
  const got = headings(doc);
31
34
  const gotKeys = got.map((h) => h.key);
32
35
 
@@ -42,6 +45,9 @@ export function lint(doc, template, { requiredMeta = [] } = {}) {
42
45
  if (firstDiff >= 0) warnings.push(`章节顺序与模板不一致(从「${order[firstDiff]}」开始)`);
43
46
 
44
47
  const lines = doc.replace(/\r/g, '').split('\n');
48
+ if (proseLines(doc).some(({ text }) => [RULES_MARKER, CONTENT_MARKER].includes(text.trim()))) {
49
+ errors.push('正文残留模板分区标记,请只填充模板内容区');
50
+ }
45
51
  lines.forEach((text, i) => {
46
52
  if (/\{\{[^}]*\}\}/.test(text)) errors.push(`第 ${i + 1} 行残留模板占位符:${text.trim().slice(0, 60)}`);
47
53
  if (/<在此填写[^>]*>/.test(text)) errors.push(`第 ${i + 1} 行未替换:${text.trim().slice(0, 60)}`);
@@ -6,8 +6,10 @@ import { spawnSync } from 'node:child_process';
6
6
  import { fileURLToPath } from 'node:url';
7
7
  import { readRun } from '../lib/runs.mjs';
8
8
  import { readProfile } from '../lib/project.mjs';
9
- import { snapshotReader, assertSnapshot, hash } from '../lib/code-snapshot.mjs';
10
- import { isDev, assertValidation, reviewInputs } from '../lib/run-gates.mjs';
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';
11
13
  import { scope } from './review-scope.mjs';
12
14
 
13
15
  export function handoff(root, { branch, id, depth = '标准', capabilities = null }) {
@@ -38,19 +40,48 @@ export function handoff(root, { branch, id, depth = '标准', capabilities = nul
38
40
  };
39
41
  }
40
42
 
43
+ export function documentHandoff(root, { branch, id, kind, text }) {
44
+ const { req, run } = readRun(root, branch, id);
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
+ }
63
+
41
64
  export function main(argv) {
42
65
  try {
43
66
  const args = [...argv]; const opts = {};
44
67
  while (args.length) {
45
68
  const key = args.shift();
46
- if (!['--root', '--branch', '--id', '--depth', '--capabilities'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
69
+ if (!['--root', '--branch', '--id', '--depth', '--capabilities', '--kind', '--draft'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
47
70
  opts[key.slice(2)] = args.shift();
48
71
  }
49
72
  const root = path.resolve(opts.root ?? '.');
50
73
  const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
51
- const capabilities = opts.capabilities ? JSON.parse(fs.readFileSync(path.resolve(root, opts.capabilities), 'utf8')) : null;
52
- const packet = handoff(root, { branch, id: opts.id, depth: opts.depth, capabilities });
53
- const file = path.join(root, 'workflow-run/tmp/review', packet.run_id, 'handoff.json');
74
+ let packet;
75
+ let fileName = 'handoff.json';
76
+ if (opts.kind || opts.draft) {
77
+ if (!['requirement', 'plan'].includes(opts.kind) || !opts.draft || opts.depth || opts.capabilities) throw new Error('文档审查使用 --kind requirement|plan --draft <草稿.md>');
78
+ packet = documentHandoff(root, { branch, id: opts.id, kind: opts.kind, text: fs.readFileSync(path.resolve(root, opts.draft), 'utf8') });
79
+ fileName = `${packet.kind}-${packet.inputs}.json`;
80
+ } else {
81
+ const capabilities = opts.capabilities ? JSON.parse(fs.readFileSync(path.resolve(root, opts.capabilities), 'utf8')) : null;
82
+ packet = handoff(root, { branch, id: opts.id, depth: opts.depth, capabilities });
83
+ }
84
+ const file = path.join(root, 'workflow-run/tmp/review', packet.run_id, fileName);
54
85
  fs.mkdirSync(path.dirname(file), { recursive: true });
55
86
  fs.writeFileSync(file, `${JSON.stringify(packet, null, 2)}\n`);
56
87
  console.log(JSON.stringify({ ok: true, path: path.relative(root, file).split(path.sep).join('/'), packet }, null, 2)); return 0;
@@ -23,6 +23,7 @@ import { resolveTemplate, skillMeta } from './resolve.mjs';
23
23
  import { headings, lint } from './lint-doc.mjs';
24
24
  import { skeleton } from './make-template.mjs';
25
25
  import { collect } from './artifacts.mjs';
26
+ import { templateParts, RULES_MARKER, CONTENT_MARKER } from '../lib/template-parts.mjs';
26
27
 
27
28
  const ALIASES = {
28
29
  clarification: ['dev', 'clarification-template.md'],
@@ -58,20 +59,23 @@ const draftPath = (root, { skill, id }) => path.join(root, 'workflow-run', 'tmp'
58
59
  export function checkFormat(text) {
59
60
  const errors = [];
60
61
  const warnings = [];
61
- const hs = headings(text);
62
+ const parts = templateParts(text);
63
+ if (parts.error) errors.push(parts.error);
64
+ const hs = headings(parts.content);
62
65
  if (!hs.length) errors.push('没有任何章节标题(# / ## ...)');
63
- const lines = text.replace(/\r/g, '').split('\n');
66
+ const lines = parts.content.replace(/\r/g, '').split('\n');
67
+ const { offset = 0 } = parts;
64
68
  const first = lines.findIndex((l) => /^#{1,6}\s/.test(l));
65
69
  if (lines.slice(0, first < 0 ? lines.length : first).some((l) => /^\s*>/.test(l))) warnings.push('标题前有引用块:元信息由生成文档的 skill 自己写,模板里不需要');
66
70
  lines.forEach((l, i) => {
67
- if ((l.match(/\{\{/g) || []).length !== (l.match(/\}\}/g) || []).length) errors.push(`第 ${i + 1} 行 {{ }} 不成对:${l.trim().slice(0, 60)}`);
68
- if (/^\s*\{\{\s*fact:/.test(l)) errors.push(`第 ${i + 1} 行是 DocNexus 的事实引用语法 {{fact:...}},模板里写填写说明即可`);
71
+ if ((l.match(/\{\{/g) || []).length !== (l.match(/\}\}/g) || []).length) errors.push(`第 ${i + 1 + offset} 行 {{ }} 不成对:${l.trim().slice(0, 60)}`);
72
+ if (/^\s*\{\{\s*fact:/.test(l)) errors.push(`第 ${i + 1 + offset} 行是 DocNexus 的事实引用语法 {{fact:...}},模板里写填写说明即可`);
69
73
  });
70
74
  const seen = new Map();
71
75
  for (const h of hs.filter((x) => x.level >= 2 && x.key)) {
72
76
  const k = `${h.level}:${h.key}`;
73
77
  if (seen.has(k)) warnings.push(`章节「${h.text}」与第 ${seen.get(k)} 行重名,lint-doc 只认第一个`);
74
- else seen.set(k, h.line);
78
+ else seen.set(k, h.line + offset);
75
79
  }
76
80
  if (hs.length && !hs.some((h) => h.required)) warnings.push('没有标记必填章节(标题末尾加 *):lint-doc 不会因为缺章节报错');
77
81
  return { errors, warnings, headings: hs.length, required: hs.filter((h) => h.required).map((h) => h.text.replace(/\s*\*+\s*$/, '')), optional: hs.filter((h) => h.optional).map((h) => h.text) };
@@ -79,7 +83,7 @@ export function checkFormat(text) {
79
83
 
80
84
  // 与当前模板相比的章节变化(按归一化后的标题比对,改编号不算变化)
81
85
  export function compare(oldText, newText) {
82
- const pick = (t) => headings(t).filter((h) => h.level >= 2 && h.key && !h.placeholder);
86
+ const pick = (t) => headings(templateParts(t).content).filter((h) => h.level >= 2 && h.key && !h.placeholder);
83
87
  const a = pick(oldText);
84
88
  const b = pick(newText);
85
89
  const ak = new Map(a.map((h) => [h.key, h]));
@@ -131,7 +135,8 @@ export function draft(root, t, { from = null, force = false, stdin = () => fs.re
131
135
  if (sample == null) return { code: 1, out: { ok: false, ...base, message: `读不到样例:${from}` } };
132
136
  const sk = skeleton(sample);
133
137
  if (!sk.headings) return { code: 1, out: { ok: false, ...base, message: '样例里没有任何标题,无法抽取结构;请换一份带章节标题的样例' } };
134
- [content, origin] = [sk.template, 'sample'];
138
+ const split = Object.hasOwn(PRODUCES, `${t.skill}/${t.id}`);
139
+ [content, origin] = [split ? `${RULES_MARKER}\n\n${CONTENT_MARKER}\n${sk.template}` : sk.template, 'sample'];
135
140
  } else if (text != null) {
136
141
  [content, origin] = [text, r.source];
137
142
  } else if (r.import_from && read(path.join(root, r.import_from)) != null) {