@rowansenne/workflow-run 0.35.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 (47) hide show
  1. package/CHANGELOG.md +23 -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/create-release-md-doc/SKILL.md.tpl +1 -1
  8. package/create-tech-md-doc/SKILL.md.tpl +1 -1
  9. package/dev/references/delivery.md +3 -3
  10. package/docs/architecture.html +3 -2
  11. package/docs/development.md +10 -4
  12. package/docs/full-install.html +90 -125
  13. package/docs/installation.md +1 -1
  14. package/docs/loan-service-install.html +90 -0
  15. package/docs/team-guide.md +3 -2
  16. package/docs/workflow-control-roadmap.md +144 -0
  17. package/docs/workflow-core-phase-one-report.md +41 -0
  18. package/docs/workflow-core-phase-one.md +317 -0
  19. package/docs/workflows.md +2 -2
  20. package/examples/workflow-core.mjs +26 -0
  21. package/package.json +2 -1
  22. package/project-review/SKILL.md.tpl +1 -1
  23. package/project-review/references/checklist.md.tpl +1 -1
  24. package/project-review/references/reporting.md +2 -2
  25. package/workflow/core/errors.mjs +61 -0
  26. package/workflow/core/index.mjs +286 -0
  27. package/workflow/core/review-handoff.mjs +101 -0
  28. package/workflow/integrations/skill-document-policy.mjs +28 -0
  29. package/workflow/lib/artifact-finalize.mjs +49 -10
  30. package/workflow/lib/code-snapshot.mjs +5 -0
  31. package/workflow/lib/meta-store.mjs +12 -1
  32. package/workflow/lib/project.mjs +165 -14
  33. package/workflow/lib/requirements.mjs +57 -100
  34. package/workflow/lib/review-scope.mjs +262 -0
  35. package/workflow/lib/runs.mjs +11 -1
  36. package/workflow/lib/workspace-read.mjs +13 -4
  37. package/workflow/references/architecture.md +10 -5
  38. package/workflow/references/core-api.md +196 -0
  39. package/workflow/references/execution.md +4 -4
  40. package/workflow/references/profile.md +20 -0
  41. package/workflow/references/requirements.md +12 -12
  42. package/workflow/scripts/artifact.mjs +36 -14
  43. package/workflow/scripts/requirement.mjs +36 -40
  44. package/workflow/scripts/resolve.mjs +2 -2
  45. package/workflow/scripts/review-handoff.mjs +49 -73
  46. package/workflow/scripts/review-scope.mjs +78 -294
  47. package/workflow/scripts/run.mjs +21 -9
@@ -1,6 +1,6 @@
1
1
  # 产物按需求归档(dev / project-review / 技术方案 / 上线方案共用)
2
2
 
3
- 本约定只适用于工作流的正式需求产物。普通聊天生成的报告、分析、方案、草稿、导出等辅助文件默认放在项目根的 `workflow-run/other/`(可按主题建子目录,需要时创建),即使当前分支已绑定需求,也不调用 `bind / path / sync` 或 `run.mjs`,不写需求 `meta.json`,不进入需求统计和文档视图。单独执行 project-review、技术方案或上线方案等工作流仍按本约定归档。源码、测试、配置和已有文件的维护、工作流指定的临时目录与知识库沿用各自路径;用户明确指定输出路径时以用户为准,不自动搬移已有文件。
3
+ 本约定只适用于工作流的正式需求产物。普通聊天生成的报告、分析、方案、草稿、导出等辅助文件默认放在项目根的 `workflow-run/other/`(可按主题建子目录,需要时创建),即使当前分支已绑定需求,也不调用 `bind / reindex`、`run.mjs` 或 `artifact.mjs`,不写需求 `meta.json`,不进入需求统计和文档视图。单独执行 project-review、技术方案或上线方案等工作流仍按本约定归档。源码、测试、配置和已有文件的维护、工作流指定的临时目录与知识库沿用各自路径;用户明确指定输出路径时以用户为准,不自动搬移已有文件。
4
4
 
5
5
  一个需求的全部产物放在同一个目录,整条链路一眼看全,`/workflow view` 也直接读这里。本工具的产出都在项目根的 `workflow-run/` 里(需求产物、DocNexus 工作区、项目模板、临时文件),不往项目的其他地方写。默认 `workflow-run/` 随代码提交;团队也可以让 `workflow-run/` 成为独立的文档仓库,见最后一节。两种用法的目录结构完全一样(下图),切换时文件不用挪。
6
6
 
@@ -48,19 +48,19 @@ node <skills>/workflow/scripts/requirement.mjs which
48
48
 
49
49
  ## 运行状态
50
50
 
51
- 完整流程在本文件的 `runs` 中按运行 id 保存进度,关联分支;同一需求可有多次运行。`status: completed` 和 `completed_at` 是本次运行已完成的明确标记,步骤也单独记录 completed。保存/恢复和各 skill 的记录时机见 `runs.md`;快速通道不创建记录。`sync` 只重建产物索引,保留 runs 和其他扩展字段;重新 bind 也不会清空历史。元信息采用原子写入与短时写锁,状态更新另有 revision 检查。
51
+ 完整流程在本文件的 `runs` 中按运行 id 保存进度,关联分支;同一需求可有多次运行。`status: completed` 和 `completed_at` 是本次运行已完成的明确标记,步骤也单独记录 completed。保存/恢复和各 skill 的记录时机见 `runs.md`;快速通道不创建记录。`reindex` 只允许改 `artifacts`、`latest`、`indexed_at`,不改正文、versions、runs、revision、绑定、批准、证据和 `updated`;未登记固定文件写 `version: null, registered: false`。`which` 是只读查询,重新 bind 也不会清空历史。元信息采用原子写入与短时写锁,状态更新另有 revision 检查。
52
52
 
53
53
  ## 落盘
54
54
 
55
- 正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <clarification|requirement|plan|delivery|review|tech|release> --draft <草稿>` 收尾。命令校验阶段、分支与知识模板,归档旧版、更新索引/版本并登记证据;clarification 在 F2 / B3,发布不能代替阶段完成;requirement 在 F3 / B3;plan 在 F4 / B4,并绑定需求版本;review 还须 packet 与结构化 result,delivery 须有效交付选择。不要直接覆盖正式文件后只 sync。
55
+ 正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <clarification|requirement|plan|delivery|review|tech|release> --draft <草稿>` 收尾。命令校验阶段、分支与知识模板,归档旧版、更新索引/版本并登记证据;clarification 在 F2 / B3,发布不能代替阶段完成;requirement 在 F3 / B3;plan 在 F4 / B4,并绑定需求版本;review 还须 packet 与结构化 result,delivery 须有效交付选择。不要直接覆盖正式文件后只 reindex。
56
56
 
57
57
  - 输出 path(相对项目根)、cite(跨文档引用)、previous(上一版归档)、version 和 run。文件名固定,目录只留最新版;文档仓库模式的 cite 为「文档仓库名:仓库内路径」。
58
58
  - 旧版归档在 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`,不提交;告诉用户归档了什么,不替用户删除。相同命令重试不重复升级版本或状态。
59
59
  - 原文第一行的 md-to-wiki 页面记录自动保留,新版仍发布同一页;不能在普通文档收尾中替换页面归属。
60
- - 文件发布与元信息不能跨文件一次原子提交。待完成收尾保存在同一 meta.json;中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 越过待办。代码或正文冲突时停止,取消和恢复规则见 execution.md。
61
- - `requirement.mjs path <种类>` 仍保留为底层旧接口(会预先复制归档),不作为新流程的写入入口。查询已有产物用 artifacts / list,正式写入与 cite 用 finalize 输出。
62
- - wiki 发布或知识沉淀更新文档元信息后显式 `requirement.mjs sync <path>`。sync 重建索引并保留 runs;需求绑定只由 bind 修改,不根据文档头隐式新增。
63
- - 文档/索引不一致、元信息损坏或引用缺失进入只读诊断;文件存在不代表运行完成。确认正文后显式 sync,损坏的 meta 先人工核对修复。已有旧运行缺少新证据时回到对应阶段重新收尾/验证,不自动补用户确认。
60
+ - 文件发布与元信息不能跨文件一次原子提交。待完成收尾保存在同一 meta.json;中断先 `artifact.mjs resume --id <id>`,不能继续 reindex / save 越过待办。代码或正文冲突时停止,取消和恢复规则见 execution.md。
61
+ - 旧 `requirement.mjs path` 和 `sync` 写入命令已删除。查询已有产物用 artifacts / list,正式写入与 cite 用 finalize 输出。
62
+ - wiki 发布或知识沉淀更新文档元信息后显式 `requirement.mjs reindex`。它只重建派生索引并保留 runs、versions 和证据;需求绑定只由 bind 修改,不根据文档头隐式新增。
63
+ - 文档/索引不一致、元信息损坏或引用缺失进入只读诊断;文件存在不代表运行完成。确认正文后显式 reindex,损坏的 meta 先人工核对修复。已有旧运行缺少新证据时回到对应阶段重新收尾/验证,不自动补用户确认。
64
64
  - 独立文档仓库在允许提示提交的阶段运行 `requirement.mjs pending`,沿用下节规则;dev 内部审查延后到 F8。
65
65
 
66
66
  ## 独立文档仓库
@@ -76,17 +76,17 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
76
76
  - 布局和随代码提交时一样。绑定需求时 `which` 会列出 `other_projects`(其他服务已有、已拉到本地的需求),用同一个名字 `bind` 就加入了那个需求。
77
77
  - DocNexus 也在这个仓库里(`workflow-run/docnexus/`),各服务共用一个知识库。
78
78
  - `project`:这个项目在文档仓库里的名字,写在 `workflow/profile.json` 的 `artifacts.project`(随代码提交,团队共用),**只需配置一次**;随代码提交时已经自动写过的就直接沿用。没配时脚本退出码 2(`need_project`)并给出 `suggested_project`(git 远端仓库名):问用户一次,然后运行 `requirement.mjs config --project <项目名>`,之后一直沿用。
79
- - 查看或修改配置:`requirement.mjs config [--project <项目名>] [--commit-prompt on|off] [--local]`。
79
+ - 查看或修改配置:`requirement.mjs config [--project <项目名>] [--commit-prompt on|off] [--profile-source <环境|路径|auto>] [--local]`。多环境 `--copy` 的 profile 内容不同时,用 `--profile-source` 选择;选择和候选见 [profile.md](profile.md)。
80
80
  - `/workflow view` 在这个模式下显示文档仓库里所有项目的需求,一个需求下按项目区分产物。
81
81
 
82
82
  ## 文档仓库的提交
83
83
 
84
- 文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。finalize 后运行 pending(或旧 sync 返回 commit 非空)时:
84
+ 文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。finalize 或 reindex 后运行 pending 时:
85
85
 
86
86
  **dev F7 审查例外**:审查环节(独立子 agent 或当前会话自查)拿到 `commit` 信息后不询问、不执行文档提交,先交审查报告、等待用户选择修复或交付。选择交付进入 F8 后(完整流程;S 快速通道不落盘,没有待提交产物),再运行 `requirement.mjs pending` 获取当前待提交内容,按下面步骤询问;修复与复审期间继续延后,不改动 `commit_prompt` 配置。
87
87
 
88
- 1. 把 pending 的 `files`(旧 sync 为 commit.files)和 `suggested_message` 给用户看,问要不要提交。
89
- 2. 用户确认后,按 pending 的 `commands`(旧 sync 为 commit.commands) 在文档仓库里提交;推送另外问用户,用户同意后再 `git -C workflow-run push`。
88
+ 1. 把 pending 的 `files` 和 `suggested_message` 给用户看,问要不要提交。
89
+ 2. 用户确认后,按 pending 的 `commands` 在文档仓库里提交;推送另外问用户,用户同意后再 `git -C workflow-run push`。
90
90
  3. 用户不想现在提交就跳过,不再追问;之后随时可以运行 `requirement.mjs pending` 看还有哪些没提交。
91
91
 
92
- 不想被提示的人可以关掉:`requirement.mjs config --commit-prompt off --local`。这个设置写在 `workflow/profile.local.json`(个人设置,不提交,只影响自己);去掉 `--local` 则写进 `profile.json`,对整个团队生效。关掉后 sync 不再输出 `commit`,产物照常写到文档仓库,由自己决定什么时候提交。
92
+ 不想被提示的人可以关掉:`requirement.mjs config --commit-prompt off --local`。这个设置写在 `workflow/profile.local.json`(个人设置,不提交,只影响自己);去掉 `--local` 则写进 `profile.json`,对整个团队生效。关掉后 pending 仍可查询,但不主动提示提交,产物照常写到文档仓库,由自己决定什么时候提交。
@@ -4,9 +4,9 @@ import fs from 'node:fs';
4
4
  import path from 'node:path';
5
5
  import { spawnSync } from 'node:child_process';
6
6
  import { fileURLToPath } from 'node:url';
7
- import { resolveTemplate, skillMeta } from './resolve.mjs';
8
- import { lint } from './lint-doc.mjs';
9
- import { ARTIFACT_TEMPLATES, finalizeArtifact, resumeFinalization, abortFinalization } from '../lib/artifact-finalize.mjs';
7
+ import { createWorkflow } from '../core/index.mjs';
8
+ import { createSkillDocumentPolicy } from '../integrations/skill-document-policy.mjs';
9
+ import { ARTIFACT_TEMPLATES } from '../lib/artifact-finalize.mjs';
10
10
 
11
11
  export function main(argv) {
12
12
  try {
@@ -19,21 +19,43 @@ export function main(argv) {
19
19
  const root = path.resolve(opts.root ?? '.');
20
20
  const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
21
21
  const read = (p) => p ? JSON.parse(fs.readFileSync(p === '-' ? 0 : path.resolve(root, p), 'utf8')) : undefined;
22
+ const workflow = createWorkflow({ root, documentPolicy: createSkillDocumentPolicy(root) });
23
+ const pendingRequest = () => {
24
+ const state = workflow.runs.status({ branch, id: opts.id });
25
+ if (!state.pending) throw new Error(`没有该运行待处理的产物收尾:${opts.id}`);
26
+ return {
27
+ branch,
28
+ id: opts.id,
29
+ expectedRevision: state.pending.runRevision,
30
+ operationId: state.pending.operationId,
31
+ };
32
+ };
22
33
  let out;
23
- if (action === 'resume') out = resumeFinalization(root, { branch, id: opts.id });
24
- else if (action === 'abort') out = abortFinalization(root, { branch, id: opts.id });
34
+ if (action === 'resume') out = workflow.artifacts.resume(pendingRequest());
35
+ else if (action === 'abort') out = workflow.artifacts.abort(pendingRequest());
25
36
  else if (action === 'finalize') {
26
- const [skill, template] = ARTIFACT_TEMPLATES[opts.kind] ?? [];
27
- if (!skill || !opts.draft) throw new Error('finalize 需要 --kind clarification|requirement|plan|review|delivery|tech|release 和 --draft <草稿.md>');
28
- const resolved = resolveTemplate(root, skill, template);
29
- if (!resolved.ok) throw new Error(resolved.hint ?? JSON.stringify(resolved));
30
- const source = fs.readFileSync(path.resolve(root, resolved.path), 'utf8');
31
- const rules = skillMeta(skill).templates.find((t) => t.id === template).lint;
32
- out = finalizeArtifact(root, { branch, id: opts.id, revision: Number(opts['expect-revision']), kind: opts.kind,
33
- text: fs.readFileSync(path.resolve(root, opts.draft), 'utf8'), input: read(opts.input) ?? {}, packet: read(opts.packet), result: read(opts.result) }, (text) => lint(text, source, rules));
37
+ if (!ARTIFACT_TEMPLATES[opts.kind] || !opts.draft) throw new Error('finalize 需要 --kind clarification|requirement|plan|review|delivery|tech|release 和 --draft <草稿.md>');
38
+ out = workflow.artifacts.finalize({
39
+ branch,
40
+ id: opts.id,
41
+ expectedRevision: Number(opts['expect-revision']),
42
+ kind: opts.kind,
43
+ text: fs.readFileSync(path.resolve(root, opts.draft), 'utf8'),
44
+ input: read(opts.input) ?? {},
45
+ packet: read(opts.packet) ?? null,
46
+ result: read(opts.result) ?? null,
47
+ });
34
48
  } else throw new Error('用法:artifact.mjs finalize --id <id> --expect-revision <n> --kind <种类> --draft <草稿> [--input <checkpoint.json>] [--packet <handoff.json> --result <审查结果.json>] | resume --id <id> | abort --id <id>');
35
49
  console.log(JSON.stringify(out, null, 2)); return 0;
36
- } catch (e) { console.error(e.message); return 1; }
50
+ } catch (error) {
51
+ console.error(JSON.stringify({
52
+ ok: false,
53
+ ...(error.code ? { code: error.code } : {}),
54
+ message: error.message,
55
+ ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}),
56
+ }, null, 2));
57
+ return 1;
58
+ }
37
59
  }
38
60
  const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
39
61
  if (invoked) process.exit(main(process.argv.slice(2)));
@@ -8,17 +8,13 @@
8
8
  // - 默认:workflow-run/ 随代码提交;项目名没配置时取 git 远端仓库名(第一次 bind 时写进 profile.json,之后固定)
9
9
  // - 独立文档仓库:团队文档仓库克隆到 workflow-run/(它自己是 git 仓库,代码仓库忽略它),项目名要先配置(各服务在同一个仓库里,名字由团队定);
10
10
  // 文档仓库单独提交(写完由用户确认,可用 artifacts.commit_prompt 关闭提交提示)
11
- // 需求目录写进项目根 .ignore,不参与代码搜索。旧版本(随代码提交时没有 <项目名>/ 这一层)的产物由安装器 upgrade 时迁移(migrateLayout)
12
11
  // 需求名由用户在流程开始或第一次落盘时给出;用户不给时按分支名生成。分支 → 需求的绑定记在 meta.json 的 branches。
13
12
  // 说明见 workflow/references/requirements.md。
14
13
  //
15
14
  // 用法(在项目根执行;--root 可指定项目根;--branch 缺省为当前 git 分支):
16
15
  // requirement.mjs which [--branch b] # 当前分支绑定的需求;没绑定时给出建议名、最近的需求(文档仓库模式还列出其他项目的需求)
17
16
  // requirement.mjs bind [--name <需求名>] [--branch b] [--base m] # 绑定(没有就新建);不给 --name 按分支名生成
18
- // requirement.mjs path <clarification|requirement|plan|delivery|review|tech|release> [--branch b] # 本次落盘的文件路径(文件名固定;已有时上一版复制到
19
- // # workflow-run/tmp/old-artifacts/<种类>_v<N>.md,输出 previous)
20
- // requirement.mjs sync [<需求目录或其中的文件> | --all] # 按目录里的文件重建 meta.json;指定了目录 / 文件时确认新版本号、输出归档了哪些上一版;
21
- // # 文档仓库模式下带上提交提示
17
+ // requirement.mjs reindex [--branch b | --all] # 只重建派生索引;不改正文、版本、运行状态或证据
22
18
  // requirement.mjs pending [--branch b] # 文档仓库模式:当前需求在文档仓库里未提交的改动与建议的提交命令
23
19
  // requirement.mjs list # 所有需求(名称、分支、产物数、更新时间)
24
20
  // requirement.mjs config [--project <项目名>] [--commit-prompt on|off] [--local] # 查看 / 修改产物配置
@@ -28,12 +24,12 @@ import fs from 'node:fs';
28
24
  import path from 'node:path';
29
25
  import { spawnSync } from 'node:child_process';
30
26
  import { fileURLToPath } from 'node:url';
31
- import { HOME, setConfig, artifactsConfig, layout } from '../lib/project.mjs';
32
- import { which, bind, nextPath, list, pending, sync } from '../lib/requirements.mjs';
33
- import { requirements, find } from '../lib/requirement-read.mjs';
34
- export { HOME, REQ_DIR, TEMPLATES_DIR, TMP_DIR, IGNORE_LINE, homeDir, homeIsRepo, dirName, profileDir, artifactsConfig, layout, suggestProject, setConfig, ensureIgnore } from '../lib/project.mjs';
27
+ import { createWorkflow } from '../core/index.mjs';
28
+ import { HOME, setConfig, artifactsConfig, layout, setProfileSource, profileSources } from '../lib/project.mjs';
29
+ import { list, pending } from '../lib/requirements.mjs';
30
+ export { HOME, REQ_DIR, TEMPLATES_DIR, TMP_DIR, PROFILE_SOURCE, IGNORE_LINE, homeDir, homeIsRepo, dirName, profileDir, artifactsConfig, layout, suggestProject, setConfig, setProfileSource, profileSources, ensureIgnore } from '../lib/project.mjs';
35
31
  export { requirements, repoRequirements, artifactFiles, find } from '../lib/requirement-read.mjs';
36
- export { OLD_DIR, sync, which, bind, nextPath, list, pending, legacyRequirements, migrateLayout } from '../lib/requirements.mjs';
32
+ export { OLD_DIR, list, pending } from '../lib/requirements.mjs';
37
33
  export { FILES, parseFile, parseBranch, parseDocnexus } from '../lib/artifact-model.mjs';
38
34
  function currentBranch(root) {
39
35
  const r = spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' });
@@ -41,7 +37,7 @@ function currentBranch(root) {
41
37
  }
42
38
 
43
39
  // ------------------------------------------------------------------ CLI
44
- const USAGE = '用法: requirement.mjs which | bind [--name <需求名>] | path <clarification|requirement|plan|delivery|review|tech|release> | sync [<目录|文件> | --all] | pending | list | config [--project <名>] [--commit-prompt on|off] [--local] (通用:--root <项目根> --branch <分支>)';
40
+ const USAGE = '用法: requirement.mjs which | bind [--name <需求名>] | reindex [--all] | pending | list | config [--project <名>] [--commit-prompt on|off] [--profile-source <环境|路径|auto>] [--local] (通用:--root <项目根> --branch <分支>)';
45
41
 
46
42
  function main(argv) {
47
43
  let root = process.cwd();
@@ -50,55 +46,55 @@ function main(argv) {
50
46
  for (let i = 0; i < argv.length; i++) {
51
47
  const a = argv[i];
52
48
  if (a === '--root') root = path.resolve(argv[++i] ?? '.');
53
- else if (['--name', '--branch', '--base', '--repo', '--project', '--commit-prompt'].includes(a)) { if (i + 1 >= argv.length) { console.error(USAGE); return 1; } o[a.slice(2)] = argv[++i]; }
49
+ else if (['--name', '--branch', '--base', '--repo', '--project', '--commit-prompt', '--profile-source'].includes(a)) { if (i + 1 >= argv.length) { console.error(USAGE); return 1; } o[a.slice(2)] = argv[++i]; }
54
50
  else if (a === '--all' || a === '--local') o[a.slice(2)] = true;
55
51
  else if (a.startsWith('--')) { console.error(USAGE); return 1; }
56
52
  else pos.push(a);
57
53
  }
58
54
  const [cmd, arg] = pos;
59
55
  const branch = o.branch ?? currentBranch(root);
56
+ const workflow = createWorkflow({ root });
60
57
  const print = (x, code = 0) => { console.log(JSON.stringify(x, null, 2)); return code; };
61
58
  const ready = (x) => (x.ok === false && x.need_project ? 2 : 0);
62
- switch (cmd) {
63
- case 'which': { const r = which(root, branch); return print(r, ready(r)); }
64
- case 'bind': { const r = bind(root, { name: o.name, branch, base: o.base }); return print(r, r.ok ? 0 : ready(r) || 1); }
65
- case 'path': { const r = nextPath(root, arg, branch); return print(r.out, r.code); }
59
+ try {
60
+ switch (cmd) {
61
+ case 'which': { const r = workflow.requirements.which({ branch }); return print(r, ready(r)); }
62
+ case 'bind': { const r = workflow.requirements.bind({ name: o.name, branch, base: o.base }); return print(r, r.ok ? 0 : ready(r) || 1); }
63
+ case 'reindex': {
64
+ if (!o.all && !branch) { console.error('无法确定当前分支,请用 --branch 指定或使用 --all'); return 1; }
65
+ const r = workflow.maintenance.reindex({ branch, all: !!o.all });
66
+ return print(r, r.ok === false ? 1 : 0);
67
+ }
66
68
  case 'list': return print(list(root));
67
69
  case 'pending': { const r = pending(root, branch); return print(r, ready(r)); }
68
70
  case 'config': {
69
71
  const patch = {};
72
+ let source = null;
70
73
  if (o.repo !== undefined) { console.error(`--repo 已不再支持:独立文档仓库改为把团队文档仓库克隆到项目根的 ${HOME}/(见 workflow/references/requirements.md)`); return 1; }
71
74
  if (o.project !== undefined) patch.project = o.project;
72
75
  if (o['commit-prompt'] !== undefined) {
73
76
  if (!['on', 'off'].includes(o['commit-prompt'])) { console.error('--commit-prompt 取 on / off'); return 1; }
74
77
  patch.commit_prompt = o['commit-prompt'] === 'on';
75
78
  }
76
- if (!Object.keys(patch).length) { const L = layout(root); const c = artifactsConfig(root); return print({ mode: L.mode, repo: L.repo_rel ?? null, project: L.project, commit_prompt: c.commit_prompt, ok: L.ok, hint: L.ok ? null : L.hint }); }
77
- return print(setConfig(root, patch, { local: !!o.local }));
78
- }
79
- case 'sync': {
80
- const L = layout(root);
81
- if (o.all) return print(requirements(root, L).map((r) => ({ dir: r.dir, artifacts: sync(root, r.dir).artifacts.length })));
82
- let target = null;
83
- if (arg) {
84
- const abs = path.resolve(root, arg);
85
- target = requirements(root, L).find((r) => abs === r.abs || abs.startsWith(r.abs + path.sep)) ?? null;
86
- } else target = find(root, branch, L);
87
- if (!target) { console.error('不在当前项目的需求目录下,或当前分支没有绑定需求'); return 1; }
88
- const m = sync(root, target.dir, { bump: true });
89
- const out = { dir: target.dir, name: m.name, artifacts: m.artifacts.length, latest: m.latest, versions: m.versions ?? {} };
90
- if (m.archived.length) {
91
- const to = path.posix.dirname(m.archived[0].file);
92
- out.archived = { files: m.archived, dir: to, hint: `上一版已归档到 ${to}/(不提交),目录里只留最新版。告诉用户归档了哪些文件,请用户确认不再需要后自己删除;不要替用户删` };
93
- }
94
- // 文档仓库模式:写完产物后提示提交(由用户确认;artifacts.commit_prompt 关闭时不提示)
95
- if (L.mode === 'repo') {
96
- const pd = pending(root, branch, target.dir);
97
- out.commit = pd.commit_prompt && pd.files?.length ? { repo: pd.repo, files: pd.files, suggested_message: pd.suggested_message, commands: pd.commands, hint: '文档仓库有未提交的产物:把改动和建议的提交信息给用户看,用户确认后再执行 commands;推送另外问用户' } : null;
79
+ if (o['profile-source'] !== undefined) source = setProfileSource(root, o['profile-source']);
80
+ if (!Object.keys(patch).length) {
81
+ if (source) return print(source);
82
+ const L = layout(root); const c = artifactsConfig(root);
83
+ return print({ mode: L.mode, repo: L.repo_rel ?? null, project: L.project, commit_prompt: c.commit_prompt, profile_source: c.profile_source, candidates: profileSources(root), ok: L.ok, hint: L.ok ? null : L.hint });
98
84
  }
99
- return print(out);
85
+ const configured = setConfig(root, patch, { local: !!o.local });
86
+ return print(source ? { ...configured, profile_source: source } : configured);
87
+ }
88
+ default: console.error(USAGE); return 1;
100
89
  }
101
- default: console.error(USAGE); return 1;
90
+ } catch (error) {
91
+ console.error(JSON.stringify({
92
+ ok: false,
93
+ ...(error.code ? { code: error.code } : {}),
94
+ message: error.message,
95
+ ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}),
96
+ }, null, 2));
97
+ return 1;
102
98
  }
103
99
  }
104
100
 
@@ -98,7 +98,7 @@ export function status(root) {
98
98
  // 已安装的 skill(--skills 子集安装时只有一部分),路由前据此判断目标 skill 是否可用
99
99
  skills: skillMetas().map((m) => m.name),
100
100
  // 本机系统与终端(安装时记录),写命令按它来
101
- env: readEnv(),
101
+ env: readEnv(root),
102
102
  profile: { ok: p.complete, empty: p.empty, how: p.complete ? null : '运行 /workflow profile' },
103
103
  // 开发环境配置:只在配过时给出(没配不算问题,构建跑不起来时才需要)
104
104
  toolchain: p.toolchain.configured
@@ -147,7 +147,7 @@ function main(argv) {
147
147
  case 'env':
148
148
  // env(默认):本机系统与终端;--check:核对画像里的开发环境配置在本机是否存在
149
149
  if (rest.includes('--check') || rest.includes('--resolve')) { print(checkToolchain(root)); return 0; }
150
- print(readEnv()); return 0;
150
+ print(readEnv(root)); return 0;
151
151
  }
152
152
  console.error('用法: resolve.mjs [--root <项目根>] template <skill> <文件名> | templates | profile | infer-profile | category <skill> | status | env [--check]');
153
153
  return 1;
@@ -4,88 +4,64 @@ import fs from 'node:fs';
4
4
  import path from 'node:path';
5
5
  import { spawnSync } from 'node:child_process';
6
6
  import { fileURLToPath } from 'node:url';
7
- import { readRun } from '../lib/runs.mjs';
8
- import { readProfile } from '../lib/project.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';
13
- import { scope } from './review-scope.mjs';
14
7
 
15
- export function handoff(root, { branch, id, depth = '标准', capabilities = null }) {
16
- const { req, run } = readRun(root, branch, id);
17
- if (!['feature', 'bug', 'review'].includes(run.kind) || ['completed', 'cancelled'].includes(run.status)) throw new Error('只有进行中的开发/审查运行可生成交接材料');
18
- if (req.meta.pending_finalization) throw new Error('先恢复待完成的产物收尾');
19
- const getSnapshot = snapshotReader(root, run);
20
- if (isDev(run)) {
21
- if (run.stage !== (run.kind === 'feature' ? 'F7' : 'B5')) throw new Error('请先完成验证并进入审查阶段');
22
- assertValidation(root, req, run, undefined, getSnapshot);
23
- }
24
- if (!['快审', '标准', '深审'].includes(depth)) throw new Error('审查深度须为快审 / 标准 / 深审');
25
- const snapshot = getSnapshot();
26
- const reviewScope = scope(root, { base: run.scope?.base ?? 'main', exclude: run.scope?.exclude ?? [] });
27
- if (!reviewScope.ok) throw new Error(reviewScope.error);
28
- assertSnapshot(root, run, snapshot);
29
- const profile = readProfile(root).profile;
30
- const inputs = reviewInputs(run);
31
- return {
32
- run_id: id, revision: run.revision, project_root: path.resolve(root), skills: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'),
33
- branch, depth, snapshot, inputs: hash(JSON.stringify(inputs)), scope: reviewScope, requirement: req.name, facts: inputs.facts,
34
- requirement_document: run.artifacts?.requirement ?? null, plan: run.artifacts?.plan ?? null, previous_report: run.artifacts?.review ?? null,
35
- validation: run.validation ?? null,
36
- commands: Object.fromEntries(['main_branch', 'build', 'test', 'test_single', 'lint'].map((k) => [k, profile?.[k] ?? null])),
37
- capabilities,
38
- result_schema: { run_id: id, code: snapshot.digest, inputs: hash(JSON.stringify(inputs)), findings: [{ id: '唯一编号', severity: 'CRITICAL|HIGH|MEDIUM|LOW', verification: 'confirmed|pending', scope: 'in_scope|outside(范围外发现单列)', file: '真实路径', line: 1, summary: '触发条件与影响' }], coverage: { reviewed: ['已审文件'], uncovered: ['未审文件'] } },
39
- rules: '独立读代码,按 project-review 第 1~7 步审查;返回报告草稿和结构化结果,不改代码、不生成 delivery.md、不提交、不另建运行;主 agent 负责 finalize。零发现 findings 为空数组,scope.review 中每个文件必须进入 reviewed 或 uncovered。',
40
- };
41
- }
8
+ import { createWorkflow } from '../core/index.mjs';
9
+ import {
10
+ createCodeHandoff,
11
+ createDocumentHandoff,
12
+ writeReviewPacket,
13
+ } from '../core/review-handoff.mjs';
42
14
 
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
- }
15
+ export const handoff = createCodeHandoff;
16
+ export const documentHandoff = createDocumentHandoff;
63
17
 
64
18
  export function main(argv) {
65
19
  try {
66
- const args = [...argv]; const opts = {};
20
+ const args = [...argv];
21
+ const options = {};
67
22
  while (args.length) {
68
23
  const key = args.shift();
69
- if (!['--root', '--branch', '--id', '--depth', '--capabilities', '--kind', '--draft'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
70
- opts[key.slice(2)] = args.shift();
24
+ if (!['--root', '--branch', '--id', '--depth', '--capabilities', '--kind', '--draft'].includes(key) || !args.length) {
25
+ throw new Error(`未知或缺少值的参数:${key}`);
26
+ }
27
+ options[key.slice(2)] = args.shift();
71
28
  }
72
- const root = path.resolve(opts.root ?? '.');
73
- const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
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 });
29
+ const root = path.resolve(options.root ?? '.');
30
+ const branch = options.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
31
+ if (!options.id) throw new Error('需要 --id <运行id>');
32
+ const capabilities = options.capabilities
33
+ ? JSON.parse(fs.readFileSync(path.resolve(root, options.capabilities), 'utf8'))
34
+ : null;
35
+ if (options.kind || options.draft) {
36
+ if (!['requirement', 'plan'].includes(options.kind) || !options.draft || options.depth || options.capabilities) {
37
+ throw new Error('文档审查使用 --kind requirement|plan --draft <草稿.md>');
38
+ }
83
39
  }
84
- const file = path.join(root, 'workflow-run/tmp/review', packet.run_id, fileName);
85
- fs.mkdirSync(path.dirname(file), { recursive: true });
86
- fs.writeFileSync(file, `${JSON.stringify(packet, null, 2)}\n`);
87
- console.log(JSON.stringify({ ok: true, path: path.relative(root, file).split(path.sep).join('/'), packet }, null, 2)); return 0;
88
- } catch (e) { console.error(e.message); return 1; }
40
+ const text = options.draft ? fs.readFileSync(path.resolve(root, options.draft), 'utf8') : null;
41
+ const workflow = createWorkflow({ root });
42
+ const packet = workflow.reviews.prepare({
43
+ branch,
44
+ id: options.id,
45
+ kind: options.kind ?? null,
46
+ text,
47
+ depth: options.depth ?? '标准',
48
+ capabilities,
49
+ });
50
+ const out = { ok: true, path: packet.path, packet: packet.packet };
51
+ console.log(JSON.stringify(out, null, 2));
52
+ return 0;
53
+ } catch (error) {
54
+ console.error(JSON.stringify({
55
+ ok: false,
56
+ ...(error.code ? { code: error.code } : {}),
57
+ message: error.message,
58
+ ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}),
59
+ }, null, 2));
60
+ return 1;
61
+ }
89
62
  }
63
+
64
+ export { writeReviewPacket };
65
+
90
66
  const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
91
67
  if (invoked) process.exit(main(process.argv.slice(2)));