@rowansenne/workflow-run 0.34.0 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/CHANGELOG.md +31 -1
  2. package/README.md +2 -0
  3. package/bin/lib/artifact-context.mjs +1 -1
  4. package/bin/lib/docsrepo.mjs +4 -6
  5. package/bin/lib/doctor.mjs +0 -3
  6. package/bin/lib/install.mjs +15 -15
  7. package/bin/lib/uninstall.mjs +2 -0
  8. package/bin/lib/workbuddy.mjs +37 -0
  9. package/bin/workbuddy/dev.md +10 -0
  10. package/bin/workflow-run.mjs +3 -0
  11. package/create-release-md-doc/SKILL.md.tpl +1 -1
  12. package/create-tech-md-doc/SKILL.md.tpl +1 -1
  13. package/dev/SKILL.md.tpl +5 -4
  14. package/dev/references/bug.md +2 -2
  15. package/dev/references/clarify.md +1 -1
  16. package/dev/references/delivery.md +3 -3
  17. package/dev/references/planning.md +2 -2
  18. package/docs/architecture.html +3 -2
  19. package/docs/development.md +10 -4
  20. package/docs/full-install.html +90 -125
  21. package/docs/installation.md +2 -2
  22. package/docs/loan-service-install.html +90 -0
  23. package/docs/team-guide.md +3 -2
  24. package/docs/workflow-control-roadmap.md +144 -0
  25. package/docs/workflow-core-phase-one-report.md +41 -0
  26. package/docs/workflow-core-phase-one.md +317 -0
  27. package/docs/workflows.md +2 -2
  28. package/examples/workflow-core.mjs +26 -0
  29. package/package.json +2 -1
  30. package/project-review/SKILL.md.tpl +1 -1
  31. package/project-review/references/checklist.md.tpl +1 -1
  32. package/project-review/references/reporting.md +2 -2
  33. package/workflow/core/errors.mjs +61 -0
  34. package/workflow/core/index.mjs +286 -0
  35. package/workflow/core/review-handoff.mjs +101 -0
  36. package/workflow/integrations/skill-document-policy.mjs +28 -0
  37. package/workflow/lib/artifact-finalize.mjs +73 -20
  38. package/workflow/lib/code-snapshot.mjs +5 -0
  39. package/workflow/lib/document-review.mjs +53 -0
  40. package/workflow/lib/meta-store.mjs +12 -1
  41. package/workflow/lib/project.mjs +165 -14
  42. package/workflow/lib/requirements.mjs +57 -100
  43. package/workflow/lib/review-scope.mjs +262 -0
  44. package/workflow/lib/run-gates.mjs +13 -2
  45. package/workflow/lib/runs.mjs +13 -2
  46. package/workflow/lib/workspace-read.mjs +13 -4
  47. package/workflow/references/architecture.md +10 -5
  48. package/workflow/references/core-api.md +196 -0
  49. package/workflow/references/execution.md +21 -4
  50. package/workflow/references/profile.md +20 -0
  51. package/workflow/references/requirements.md +12 -12
  52. package/workflow/scripts/artifact.mjs +36 -14
  53. package/workflow/scripts/requirement.mjs +36 -40
  54. package/workflow/scripts/resolve.mjs +2 -2
  55. package/workflow/scripts/review-handoff.mjs +51 -44
  56. package/workflow/scripts/review-scope.mjs +78 -294
  57. package/workflow/scripts/run.mjs +21 -9
package/CHANGELOG.md CHANGED
@@ -4,6 +4,35 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.36.0] - 2026-11-17
8
+
9
+ ### 新增
10
+ - 新增 `workflow/core/index.mjs` 内部程序入口,运行状态、需求绑定、索引维护、产物 finalize 和审查交接可由 Skills 脚本与 Node.js 调用方共用。
11
+ - 新增项目级配置隔离:实例绑定明确 root,不读取核心模块所在项目的 profile;多个规范路径之外的配置副本有歧义时明确报错。
12
+ - 多环境 `--copy` 安装中内容相同的 profile 副本自动视为等价;内容不同时可用 `requirement.mjs config --profile-source` 写入项目级来源,`auto` 恢复自动判断。
13
+ - 审查范围、分类和分批逻辑抽到共享库,审查交接通过核心生成。
14
+
15
+ ### 变更
16
+ - `requirement.mjs which` 改为纯只读;新增 `requirement.mjs reindex`,只刷新派生索引,不提升 versions、不归档、不推进运行或生成证据。
17
+ - `run.mjs` 的操作与导出收口到核心门面;`artifact.mjs finalize` 通过核心和 Skills 文档策略执行。
18
+ - 核心 `artifacts.resume/abort` 冻结为 `{ branch, id, expectedRevision, operationId }`:`expectedRevision` 使用 status 的 `runRevision`,pending 基准 revision 由核心核对;旧操作 ID 不能恢复或中止后来创建的事务。`artifact.mjs` 恢复命令自动读取当前待办身份,CLI 用法保持不变。
19
+ - `requirement.mjs` 不再转导出底层 `bind / which / reindex`,Skills 的状态写操作只能经过 `createWorkflow` 门面。
20
+ - 双入口验收改用安装后的 `run.mjs`、`artifact.mjs`、`review-handoff.mjs` 和真实模板策略推进完整 feature run,覆盖真实 lint 失败、pending 恢复与 finalize 成功重放;发布包测试也验证安装后的脚本与内部核心操作同一运行。
21
+ - trigger 评估不再把 provider 以普通文本返回的 API 错误当成“没有触发 skill”,并会对调用失败或分流不符合预期返回非零退出码;评估会话只开放 `Skill` / `Read`,允许先读普通文件再识别后续 `SKILL.md`,避免把只读探索误判为未触发。
22
+
23
+ ### 移除
24
+ - 删除 `requirement.mjs path`、`nextPath()`、旧 `sync` 命令及版本 bump 直写链。
25
+ - 删除旧需求目录自动迁移入口;用户工作区中的历史目录和 `old-artifacts/` 不会被自动删除或移动。
26
+ - 旧流程已确认无使用者;包含第一阶段的下一版本 `0.36.0` 按 pre-1.0 规则显式发布破坏性命令变化,不提供兼容壳或迁移。
27
+
28
+ ## [0.35.0] - 2026-11-16
29
+
30
+ ### 新增
31
+ - 新建 M / L 完整开发与缺陷修复运行在需求和方案收尾前增加独立文档审查。审查绑定草稿与依据,已有运行和 S 规模沿用原流程。
32
+
33
+ ### 修复
34
+ - WorkBuddy 安装 `dev` 时生成可补全的项目级 `/dev` 命令,并保留团队自定义的同名命令。
35
+
7
36
  ## [0.34.0] - 2026-11-15
8
37
 
9
38
  ### 优化
@@ -455,7 +484,8 @@
455
484
  - 安装器改为单一 Node 实现,`init-skills.sh` / `init-skills.ps1` 只是薄封装。
456
485
  - `code-review` 改名为 `project-review`,升级时自动清理旧名。
457
486
 
458
- [Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.26.0...HEAD
487
+ [Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.36.0...HEAD
488
+ [0.36.0]: https://github.com/guilianerde/skills-init/compare/v0.35.0...v0.36.0
459
489
  [0.26.0]: https://github.com/guilianerde/skills-init/compare/v0.25.0...v0.26.0
460
490
  [0.21.0]: https://github.com/guilianerde/skills-init/compare/v0.20.0...v0.21.0
461
491
  [0.20.0]: https://github.com/guilianerde/skills-init/compare/v0.19.0...v0.20.0
package/README.md CHANGED
@@ -56,3 +56,5 @@ npx @rowansenne/workflow-run@latest seed-templates --update # 补入模板并更
56
56
  [安装与升级](docs/installation.md) · [工作流与命令](docs/workflows.md) · [外部能力集成](docs/integrations.md) · [团队指南](docs/team-guide.md) · [维护与发布](docs/development.md) · [更新记录](CHANGELOG.md)
57
57
 
58
58
  [架构图解](docs/architecture.html) · [分步安装教程](docs/full-install.html)
59
+
60
+ 架构演进:[整体开发目标](docs/workflow-control-roadmap.md) · [第一阶段方案](docs/workflow-core-phase-one.md) · [第一阶段实施报告](docs/workflow-core-phase-one-report.md)
@@ -13,7 +13,7 @@ const BLOCK = [
13
13
  '- dev 工作流仅在用户实际调用 `/dev` / `$dev`、点选 dev skill,或明确要求使用 dev / 完整开发工作流时启动。普通分析、问答、代码修改、修 bug、重构、测试、提交代码和推送都不构成启动授权;讨论 dev 或引用命令示例也不构成授权。',
14
14
  '- 未获 dev 流程授权时,直接处理当前任务,不自动做工作流开工探测、确认需求名、绑定需求、创建运行或补齐需求 / 方案 / 审查 / 交付文档,也不主动询问是否开启 dev。已授权的同一 dev 任务可按当前阶段续接;只问分析或要求提交代码时仅处理当前请求,不重启或自行推进流程。旧运行、旧产物和分支绑定不构成新任务或新会话的恢复授权。',
15
15
  `- 普通聊天中生成的报告、分析、方案、草稿、导出等辅助文件,默认写到项目根的 \`${HOME}/other/\`(需要时创建,可按主题建子目录)。不要因为分支已绑定需求就放进需求目录。`,
16
- `- \`${HOME}/docs/requirements/\` 只存通过 dev、project-review、create-tech-md-doc、create-release-md-doc 等工作流生成的正式需求产物。普通聊天不得为辅助文件调用 requirement.mjs bind / path / sync 或 run.mjs,不创建或更新需求 meta.json,也不将这些文件计入需求产物和运行状态。`,
16
+ `- \`${HOME}/docs/requirements/\` 只存通过 dev、project-review、create-tech-md-doc、create-release-md-doc 等工作流生成的正式需求产物。普通聊天不得为辅助文件调用 requirement.mjs bind / reindex、run.mjs 或 artifact.mjs,不创建或更新需求 meta.json,也不将这些文件计入需求产物和运行状态。`,
17
17
  '- 项目源码、测试、配置及已有文件的维护仍遵循项目原目录;工作流自身指定的临时目录、知识库等路径沿用各自规则。用户明确指定输出路径时按用户要求执行,不自动搬移已有文件。',
18
18
  END,
19
19
  ].join('\n');
@@ -2,7 +2,6 @@
2
2
  // - workflow-run/ 里没有内容(或只有 tmp/):直接克隆
3
3
  // - 已有产物、DocNexus 等内容:原地 git init 并接上远端。远端是空仓库时本地内容就是文档仓库的第一批内容;
4
4
  // 远端已有内容时检出远端,本地文件和远端同路径冲突就退回原状、列出冲突的文件(不合并)
5
- // - 先把旧结构的产物迁到 <需求>/<项目名>/
6
5
  // - 代码仓库 .gitignore 加 /workflow-run/;文档仓库的 .git/info/exclude 加 /tmp/(本机临时文件不进文档仓库)
7
6
  // - 项目名写进 workflow/profile.json 的 artifacts.project(--project,或沿用已有的,默认 git 远端仓库名)
8
7
  // - 文档仓库里有 DocNexus 时接上本项目的链接与段落;还没装依赖时提示
@@ -12,9 +11,9 @@ import fs from 'node:fs';
12
11
  import path from 'node:path';
13
12
  import { spawnSync } from 'node:child_process';
14
13
  import { HOME, step, ok, warn, toPosix, findManifests, docnexusBin } from './core.mjs';
15
- import { updateGitignore, excludeHomeTmp, reportMigration } from './install.mjs';
14
+ import { updateGitignore, excludeHomeTmp } from './install.mjs';
16
15
  import { refreshDocNexusLinks } from './docnexus.mjs';
17
- import { layout, setConfig, artifactsConfig, suggestProject, migrateLayout } from '../../workflow/scripts/requirement.mjs';
16
+ import { layout, setConfig, artifactsConfig, suggestProject } from '../../workflow/scripts/requirement.mjs';
18
17
 
19
18
  const git = (cwd, args, opts = {}) => spawnSync('git', args, { cwd, encoding: 'utf8', ...opts });
20
19
 
@@ -31,11 +30,10 @@ function show(root) {
31
30
  return 0;
32
31
  }
33
32
 
34
- // workflow-run/ 里已有内容:原地变成文档仓库。返回是否成功;失败时 workflow-run/ 保持原样(只多了迁移到新结构的产物)
33
+ // workflow-run/ 里已有内容:原地变成文档仓库。返回是否成功。
35
34
  function inPlace(root, home, url, project, installed) {
36
- // 先定项目名,再把旧结构迁到 <需求>/<项目名>/,这样和文档仓库里其他服务的目录对得上
35
+ // 先定项目名,未配置时后续初始化以该名字写入 target profile。
37
36
  if (project && installed) setConfig(root, { project });
38
- reportMigration(migrateLayout(root));
39
37
  const remote = git(root, ['ls-remote', '--symref', url]);
40
38
  if (remote.status !== 0) { warn(`连不上 ${url}(地址、权限或网络),没有改动`); return false; }
41
39
  const heads = remote.stdout.split('\n').filter((l) => /\trefs\/heads\//.test(l)).map((l) => l.split('\t')[1].replace('refs/heads/', ''));
@@ -6,7 +6,6 @@ import { spawnSync } from 'node:child_process';
6
6
  import { PKG, CANON_DIR, INSTALL_BASES, LINK_ENVS, HOME, SKILLS, step, ok, warn, fail, toPosix, fileHash, readManifest, lstat, findManifests, cmpVersion } from './core.mjs';
7
7
  import { reportTemplateStatus, legacyDocNexusPaths } from './docnexus.mjs';
8
8
  import { codegraphVersion } from './codegraph.mjs';
9
- import { legacyRequirements } from '../../workflow/scripts/requirement.mjs';
10
9
 
11
10
  // upgrade = 用清单里记录的环境与模式非交互重装;数据库配置原样保留
12
11
  export function upgradeOptions(o) {
@@ -111,8 +110,6 @@ export function doctor(root, offline) {
111
110
  const mode = st.artifacts?.mode === 'repo' ? `独立文档仓库(${HOME}/ 自己是 git 仓库)` : '随项目提交';
112
111
  if (st.artifacts && !st.artifacts.ok) meh(`产出目录 ${HOME}/:${mode},${st.artifacts.how}`);
113
112
  else ok(`产出目录 ${HOME}/:${mode}${st.artifacts?.project ? `,本项目的产物在 docs/requirements/<需求>/${st.artifacts.project}/` : ''}`);
114
- const legacy = legacyRequirements(root);
115
- if (legacy.length) meh(`${legacy.length} 个需求还是旧结构(文件直接放在 docs/requirements/<需求>/ 下):运行 npx @rowansenne/workflow-run upgrade 迁到 <需求>/<项目名>/`);
116
113
  if (st.docnexus.ok) {
117
114
  if (!reportTemplateStatus(root, meh)) ok('DocNexus 已接入,文档模板齐全且与默认模板同步(或为团队定制版)');
118
115
  } else if (fs.existsSync(path.join(root, '.docnexus', 'project.json'))) bad('DocNexus 配置或运行环境不完整:需要 format 7、output_dir=workflow-run 和 .docnexus/ 下的 CLI,运行 upgrade --with-docnexus 修复');
@@ -5,7 +5,7 @@ import path from 'node:path';
5
5
  import { TPL_DIR, PKG, CANON_DIR, INSTALL_BASES, SKILLS, SKILL_LIST, USER_FILES, MANIFEST, ok, warn, fail, readJson, walk, toPosix, sameFile, writeFile, render, sha256, fileHash, readManifest, removeEmptyDirs, lstat, timestamp, removeLink, HOME } from './core.mjs';
6
6
  import { writeDbConfig } from './db.mjs';
7
7
  import { linkPointsTo } from './uninstall.mjs';
8
- import { layout, ensureIgnore, homeIsRepo, migrateLayout, IGNORE_LINE, TMP_DIR } from '../../workflow/scripts/requirement.mjs';
8
+ import { layout, ensureIgnore, homeIsRepo, IGNORE_LINE, TMP_DIR } from '../../workflow/scripts/requirement.mjs';
9
9
  import { detectEnv } from '../../workflow/lib/project.mjs';
10
10
  import { rotate as rotateFeedback, ensureUnionMerge } from '../../workflow/scripts/feedback.mjs';
11
11
 
@@ -268,23 +268,23 @@ export function excludeHomeTmp(root) {
268
268
  export function setupHome(root) {
269
269
  if (ensureIgnore(root)) ok(`.ignore 已加上 ${IGNORE_LINE}(需求产物不参与代码搜索)`);
270
270
  excludeHomeTmp(root);
271
- const L = layout(root);
272
- if (L.mode === 'repo' && !L.ok) warn(`${HOME}/ 是独立的文档仓库,还没配置本项目的项目名:${L.hint}`);
273
- reportMigration(migrateLayout(root));
271
+ try {
272
+ const L = layout(root);
273
+ if (L.mode === 'repo' && !L.ok) warn(`${HOME}/ 是独立的文档仓库,还没配置本项目的项目名:${L.hint}`);
274
+ } catch (error) {
275
+ if (error.code !== 'PROJECT_CONFIG_AMBIGUOUS') throw error;
276
+ warn(`${error.message};安装已完成,但依赖项目配置的核心操作会暂停,先运行 requirement.mjs config --profile-source <环境|路径> 明确来源`);
277
+ }
274
278
  // 运行反馈只收当前版本的:装了新版本就清掉本项目旧版本的记录(随 workflow-run/ 提交过的,git 历史里仍可找回)
275
- const removed = rotateFeedback(root, PKG.version);
279
+ let removed = 0;
280
+ try {
281
+ removed = rotateFeedback(root, PKG.version);
282
+ } catch (error) {
283
+ if (error.code !== 'PROJECT_CONFIG_AMBIGUOUS') throw error;
284
+ warn('运行反馈轮换已跳过:先运行 requirement.mjs config --profile-source <环境|路径> 明确 profile 来源');
285
+ }
276
286
  const attr = ensureUnionMerge(root);
277
287
  if (attr?.action === 'added') ok(`${attr.file} 已加上 ${attr.rule}(文档仓库里运行反馈多分支合并时保留两边的记录)`);
278
288
  if (attr?.action === 'removed') ok(`${attr.file} 已去掉 ${attr.rule}(随代码提交时不再改代码仓库的 .gitattributes);改动需要你提交`);
279
289
  if (removed) ok(`运行反馈:已清空旧版本的 ${removed} 条记录(${HOME}/feedback/),从这一版重新收集;改动需要你提交`);
280
290
  }
281
-
282
- // 旧结构(<需求>/ 下直接放文件)迁到 <需求>/<项目名>/ 的结果
283
- export function reportMigration(r) {
284
- if (r.moved.length) {
285
- const reqs = [...new Set(r.moved.map((m) => path.posix.dirname(m.from)))];
286
- ok(`需求产物已迁到新结构 <需求>/${r.project}/(${reqs.length} 个需求、${r.moved.length} 个文件,被 git 跟踪的用 git mv):${reqs.join('、')}`);
287
- ok(`项目名 ${r.project} 记在 workflow/profile.json;迁移的改动(含 profile.json)需要你提交`);
288
- }
289
- for (const s of r.skipped) warn(`${s.dir} 没有迁移:${s.reason}。处理后重跑 npx @rowansenne/workflow-run upgrade`);
290
- }
@@ -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,无需额外配置');
@@ -75,7 +75,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
75
75
  ### Step 4 — 写文件
76
76
 
77
77
  - 正式收尾: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`。
78
- - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
78
+ - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息只刷新派生索引时显式运行 `requirement.mjs reindex`。
79
79
  - 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-release-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
80
80
  - 再把路径和摘要告诉用户,按取材规则列出实际引用的 dev 产物及版本。
81
81
 
@@ -78,7 +78,7 @@ PRD 参考:<pageId 或 URL 或「无」/「PRD 增强已跳过」>
78
78
  ### Step 4 — 写文件
79
79
 
80
80
  - 正式收尾: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`。
81
- - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
81
+ - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息只刷新派生索引时显式运行 `requirement.mjs reindex`。
82
82
  - 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-tech-md-doc --facts --diff <main>...<dev>` 自检,显式按三点范围核对正文里的类名、文件、接口、表名。有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符);不再强制可见元信息行,但隐藏分支仍须与运行一致。「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
83
83
  - 再把路径和摘要告诉用户,按取材规则列出实际引用的 dev 产物及版本。
84
84
 
package/dev/SKILL.md.tpl CHANGED
@@ -21,6 +21,7 @@ description: "Explicitly requested dev workflow for feature development or bug f
21
21
  - 生成澄清清单、需求、方案和交付说明时,按 `<skills>/workflow/references/templates.md`「文档模板的两部分」读取生效模板。遵守要求区,只用内容区生成正文。无标记的模板沿用旧格式,边界有误时先修复。
22
22
  - 先确定工作分支、已有改动的归属与需求名;切分支重新查询绑定,不替用户丢弃已有改动。
23
23
  - 规模由 agent 判定并说明,不询问规模确认;M / L 的需求理解和方案须用户确认后再实现,权限 / 资金至少按 M。
24
+ - 新建 M / L 完整运行(`document_review_policy: 1`)的需求与方案草稿在各自收尾前须经独立子 agent 审查。按 [execution.md 的文档审查](../workflow/references/execution.md#需求与方案审查) 交接;子 agent 不可用时等用户决定是否允许本次自查。S 和升级前已有运行沿用原门禁。
24
25
  - F2 先落偏业务场景的 clarification.md,供用户找产品核对;逐轮更新原问题状态、追加新问题和反馈。业务明确并完成现状调研后,再进入 F3 澄清技术约束;最终需求确认后进入 F4。
25
26
  - S 快速通道须用户明确同意,且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更,且没有 F2 / F3 已确认的业务决定、本次未发布正式清单且未创建完整流程运行;已有清单或运行沿用完整流程,具体资格见 F4。
26
27
  - 快速通道仍编译、测试、当前会话审查,但不 bind、不建运行、不落需求 / 方案 / 审查 / 交付文档;超限或用户要求落盘先停,回 F3(bug 回 B3)补需求文档,再进入方案。
@@ -53,11 +54,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
53
54
 
54
55
  ### F3 — 需求澄清(偏技术约束)
55
56
 
56
- 读 [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。
57
58
 
58
59
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
59
60
 
60
- 读 [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,再进入实现。
61
62
 
62
63
  ### F5 — 实现
63
64
 
@@ -87,11 +88,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
87
88
 
88
89
  ### B3 — 定位根因
89
90
 
90
- 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程先生成独立 requirement.md、完成 B3,再进入修复方案。
91
+ 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程按文档门禁审查需求草稿并收尾 requirement.md、完成 B3,再进入修复方案。
91
92
 
92
93
  ### B4 — 修复与验证
93
94
 
94
- 先读 [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 再修复,复现测试由红变绿。
95
96
 
96
97
  ### B5 — 审查与交付
97
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
 
@@ -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 沉淀候选。
@@ -25,7 +25,7 @@
25
25
  完整流程:
26
26
 
27
27
  1. **落盘交付说明**:模板路径用 `node <skills>/workflow/scripts/resolve.mjs template dev delivery-template.md` 取,先写到 tmp 草稿,按 execution.md 用 `artifact.mjs finalize --kind delivery` 发布(见 Artifact Location)。元信息行的「对比分支」写当前分支和 `profile.main_branch`,`artifacts.mjs`、project-review、上线方案靠它找到这份交付;「参考产物」写 requirement.md 的 cite / 版本、最新方案与审查报告。「审查」节记录报告结论、修复与复审结果、用户选择交付及接受的遗留风险。尚未发起沉淀询问时,元信息先写「未询问」,再按第 5 步更新。小改动每节一两行即可,不适用的节写「无」,但验证结果必须如实。
28
- 2. **自检与收尾**:finalize 内部使用知识库交付模板检查草稿,有错误先修正;成功输出正式路径、cite 和版本。不要直接覆盖正式文件后用 sync 代替。
28
+ 2. **自检与收尾**:finalize 内部使用知识库交付模板检查草稿,有错误先修正;成功输出正式路径、cite 和版本。不要直接覆盖正式文件后用 reindex 代替。
29
29
  3. **对话里给摘要**:结果、验证(含未验证项)、最新审查报告路径与结论、遗留问题和用户接受的风险、配置 / SQL 有无、交付文件路径;不必把全文贴进对话。
30
30
  4. **记录运行反馈**(不问用户):按 `<skills>/workflow/references/feedback.md` 运行 `node <skills>/workflow/scripts/feedback.mjs add --skill dev --model <模型名> --mode <feature|bug> --size <S|M|L> --fast <yes|no> --rounds <提问轮数> --corrections <用户纠正理解的次数> --acceptance <已验证>/<总数> --baseline-failures <n>`,有跳过的步骤、不清楚或做不到的规则、用户的抱怨时再加 `--skipped` / `--unclear` / `--feedback`。只写过程,不写代码和业务名词;报错就提一句,不影响交付。
31
31
  完成上述交付摘要与反馈后,按运行状态协议将 F8(bug 为 B5)标 completed 并 complete。下面的可选后续动作在完成标记后处理。
@@ -39,7 +39,7 @@
39
39
  - 有 → 明确问用户「要不要启动 DocNexus 流程,把本次交付沉淀到 DocNexus?」,并列出建议沉淀的条目;发起询问时将交付说明的元信息改成「未沉淀」,成功入库后再写知识路径,避免将已询问但尚未入库算成「未询问」。
40
40
  - 用户同意 → 以交付说明为来源,按 DocNexus 入口 skill `docnexus` 的 capture 流程写入;正文只写知识,不写分支、路径;有 facts 时按 `<skills>/workflow/references/docnexus.md`「沉淀的来源」的格式写 provenance;分类用 `node <skills>/workflow/scripts/resolve.mjs category dev` 的结果作为调用方显式分类封存(见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」)。只沉淀确认过的事实,不沉淀「未验证」「待确认」的内容;知识库已有同主题的沉淀时更新那一篇(带 `--base-version`),不重复新建。写入成功后把交付说明的「DocNexus」元信息行改成 `workflow-run/docnexus/library/<path>`,并回报给用户。
41
41
  - 用户不同意 → 交付说明的元信息行改成「未沉淀」,不再追问。
42
- - 元信息更新后运行 `requirement.mjs sync <交付路径>`;F7 内部审查报告的「未询问」不随此结论改变。
42
+ - 元信息更新后运行 `requirement.mjs reindex`;它不修复正文 hash 或旧交付证据。F7 内部审查报告的「未询问」不随此结论改变。
43
43
 
44
44
  ## Artifact Location
45
45
 
@@ -47,4 +47,4 @@
47
47
 
48
48
  - **需求名**:Step 0 已运行 `requirement.mjs which` 并问定名字。第一次落盘前运行 `requirement.mjs bind --name "<需求名>"`(用户明确同意按分支名生成时不带 `--name`);S 快速通道不 bind、不落盘。缺陷修复同样处理(可以选择挂到原需求下)。
49
49
  - **正式写入**:按 `<skills>/workflow/references/execution.md`,澄清清单、需求、方案、审查、交付都先写 tmp 草稿,再用 `artifact.mjs finalize --kind clarification|requirement|plan|review|delivery` 完成自检、旧版归档、索引与运行证据登记。缺陷修复在 B4 的方案草稿中保留原文并追加修复方案,不另建正式文件。
50
- - 使用输出的 path / cite 引用;previous 非空时告知上一版归档位置,不能替用户删除。中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 覆盖待办。独立文档仓库在交付完成后运行 pending,按 requirements.md 提示提交。已完成交付的 wiki/DocNexus 元信息更新仍显式 sync。
50
+ - 使用输出的 path / cite 引用;previous 非空时告知上一版归档位置,不能替用户删除。中断先 `artifact.mjs resume --id <id>`,不能继续 reindex / save 覆盖待办。独立文档仓库在交付完成后运行 pending,按 requirements.md 提示提交。已完成交付的 wiki/DocNexus 元信息更新使用显式 reindex。
@@ -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 使用相同规则。
@@ -275,7 +275,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
275
275
  <div class="tag">命令脚本<small>workflow/scripts · 确定性命令</small></div>
276
276
  <div class="cells">
277
277
  <div class="cell"><b>resolve.mjs</b><span>模板来源、能力状态</span></div>
278
- <div class="cell"><b>requirement.mjs</b><span>需求绑定、产物路径</span></div>
278
+ <div class="cell"><b>requirement.mjs</b><span>需求绑定与派生索引维护</span></div>
279
279
  <div class="cell"><b>run.mjs</b><span>运行状态与恢复</span></div>
280
280
  <div class="cell"><b>artifact.mjs</b><span>产物收尾、中断恢复与安全取消</span></div>
281
281
  <div class="cell"><b>review-handoff.mjs</b><span>审查交接与结构化结果</span></div>
@@ -296,12 +296,13 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
296
296
  <div class="cell"><b>artifact-model</b><span>产物类型与元信息解析(纯模型,无 I/O)</span></div>
297
297
  <div class="cell"><b>requirement-read</b><span>需求目录与元信息读取</span></div>
298
298
  <div class="cell"><b>workspace-read</b><span>工作区/Git 统一快照,一次命令读一遍</span></div>
299
- <div class="cell"><b>requirements</b><span>绑定、版本、归档、sync</span></div>
299
+ <div class="cell"><b>requirements</b><span>绑定与派生索引;正式发布由 finalize 负责</span></div>
300
300
  <div class="cell"><b>runs</b><span>运行阶段、revision、完成校验</span></div>
301
301
  <div class="cell"><b>run-gates</b><span>方案、验证、审查与交付门禁</span></div>
302
302
  <div class="cell"><b>code-snapshot</b><span>代码内容摘要与证据有效性</span></div>
303
303
  <div class="cell"><b>artifact-finalize</b><span>发布、归档、索引与可恢复收尾</span></div>
304
304
  <div class="cell"><b>path-match</b><span>审查与代码证据共用的范围匹配</span></div>
305
+ <div class="cell"><b>review-scope</b><span>审查范围、跳过规则、风险分类与分批</span></div>
305
306
  <div class="cell"><b>meta-store</b><span>写锁与原子替换</span></div>
306
307
  </div>
307
308
  </div>
@@ -64,15 +64,21 @@ workflow-run(安装器仓库)/
64
64
  ├── docs/ # 专题文档与图文教程
65
65
  ├── workflow/
66
66
  │ ├── SKILL.md.tpl · skill.json
67
+ │ ├── core/ # 内部程序入口;实现统一由 Skills 脚本和 Node.js 调用方使用
68
+ │ │ ├── index.mjs # createWorkflow、操作表、错误契约
69
+ │ │ ├── errors.mjs # 稳定错误 code 与领域错误映射
70
+ │ │ └── review-handoff.mjs # 代码 / 文档审查交接组装
71
+ │ ├── integrations/ # Skills 模板策略等外围装配,不进入核心依赖
67
72
  │ ├── lib/ # 共享核心;不反向依赖 scripts 命令入口
68
73
  │ │ ├── project.mjs # 布局、画像、环境与配置
69
74
  │ │ ├── requirement-read.mjs # 需求目录与元信息读取
70
- │ │ ├── requirements.mjs # 绑定、版本归档与索引同步
75
+ │ │ ├── requirements.mjs # 需求绑定、派生索引维护
71
76
  │ │ ├── runs.mjs # 运行状态、阶段与完成校验
72
77
  │ │ ├── run-gates.mjs # 方案、验证、审查与交付门禁
73
78
  │ │ ├── code-snapshot.mjs # 代码内容摘要,绑定验证和审查证据
74
79
  │ │ ├── artifact-finalize.mjs # 可恢复的产物收尾
75
80
  │ │ ├── path-match.mjs # 共享范围匹配
81
+ │ │ ├── review-scope.mjs # 审查范围、跳过规则、风险分类与分批
76
82
  │ │ ├── meta-store.mjs # 写锁与原子存储
77
83
  │ │ ├── document-model.mjs # 标题、章节、表格等纯文本模型
78
84
  │ │ ├── artifact-model.mjs # 产物类型、元信息、审查与交付解析
@@ -87,8 +93,8 @@ workflow-run(安装器仓库)/
87
93
  │ ├── scripts/template.mjs # 修改 / 创建模板:草稿 → 校验与影响 → 保存
88
94
  │ ├── scripts/tables.mjs # 找出改动涉及的数据库表
89
95
  │ ├── scripts/artifact.mjs # 草稿收尾 / 中断恢复 / 安全取消
90
- │ ├── scripts/review-handoff.mjs # 自动生成审查交接与结果结构
91
- │ ├── scripts/requirement.mjs # 产物按需求归档:绑定需求名、落盘路径、meta.json
96
+ │ ├── scripts/review-handoff.mjs # 参数 / 文件 I/O;调用 core reviews.prepare
97
+ │ ├── scripts/requirement.mjs # 参数 / 输出;调用 core 的 bind / which / reindex
92
98
  │ ├── scripts/view.mjs # 项目文档视图(本地静态页面)
93
99
  │ ├── scripts/make-template.mjs # 从样例文档抽模板骨架
94
100
  │ ├── scripts/doc-sections.mjs # 原解析导出入口,转交 lib/document-model.mjs
@@ -175,7 +181,7 @@ workflow-run(安装器仓库)/
175
181
 
176
182
  dev 与 project-review 的 SKILL.md 保留门禁、步骤路由、必要命令和结果去向;进入阶段前才读取对应 reference 的小节。dev 的开工、调研方案、实现验证、审查交付和缺陷修复分开加载;审查的方法、复核、报告与后续也分开加载。完整流程的步骤编号、用户选择、运行状态与正式产物规则沿用原协议,必守规则不藏在脚本注释中。
177
183
 
178
- 状态查询、文档视图、效果报告和 PR 描述共用 `workflow/lib/workspace-read.mjs` 的单次命令内存快照,正文与元信息采集一次,使用统一解析规则。需求绑定、运行状态和已登记版本来自 `meta.json`;正文、文档头和发布记录来自 Markdown,产物索引由显式 `sync` 重建。`list` 只读,`sync` 不再从文档头隐式增加绑定分支,绑定使用 `bind`。跨项目视图仍展示全部服务,分支查询和效果报告默认当前项目;`--all-branches` 保持同路径工作区优先,Git 中的版本信息从同一引用读取。异常数据通过 diagnostics 报告,可读的正文仍展示,读取不修复或覆盖元信息。边界与数据归属详见 [内部架构](../workflow/references/architecture.md)。
184
+ 状态查询、文档视图、效果报告和 PR 描述共用 `workflow/lib/workspace-read.mjs` 的单次命令内存快照,正文与元信息采集一次,使用统一解析规则。需求绑定、运行状态和已登记版本来自 `meta.json`;正文、文档头和发布记录来自 Markdown,派生产物索引由显式 `reindex` 重建。`list` 与 `which` 只读,`reindex` 不修改 versions、runs、revision、批准、证据或正文,绑定使用 `bind`。跨项目视图仍展示全部服务,分支查询和效果报告默认当前项目;`--all-branches` 保持同路径工作区优先,Git 中的版本信息从同一引用读取。异常数据通过 diagnostics 报告,可读的正文仍展示,读取不修复或覆盖元信息。边界与数据归属详见 [内部架构](../workflow/references/architecture.md),程序接口见 [core-api.md](../workflow/references/core-api.md)。
179
185
 
180
186
  新增一个 skill 就是新建目录、写 `SKILL.md.tpl` 和 `skill.json`,再加进 `package.json` 的 `files`。`tests/test-skills-meta.mjs` 会检查它们是否一致。
181
187