@rowansenne/workflow-run 0.29.0 → 0.29.1

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,11 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.29.1] - 2026-10-29
8
+
9
+ ### 优化
10
+ - 同一轮证据校验按需读取并复用代码快照,减少保存、审查和交付中的重复全量扫描;开发流程的审查交接与报告收尾由 8 次扫描降至 4 次。保留交接结束、发布前及中断恢复时的重新检查,每份证据仍独立校验 digest。新增快照复用与扫描次数回归测试。
11
+
7
12
  ## [0.29.0] - 2026-10-28
8
13
 
9
14
  ### 修复
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rowansenne/workflow-run",
3
- "version": "0.29.0",
3
+ "version": "0.29.1",
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",
@@ -3,7 +3,7 @@ import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { randomUUID } from 'node:crypto';
5
5
  import { FILES, parseBranch } from './artifact-model.mjs';
6
- import { hash, assertWorkingBranch } from './code-snapshot.mjs';
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
9
  import { isDev, coreSteps, applyDevEvidence, assertRequirement, assertPlanBasis, assertReview, assertDelivery, reviewEvidence } from './run-gates.mjs';
@@ -34,11 +34,12 @@ export function resumeFinalization(root, { branch, id }) {
34
34
  const current = fileHash(file);
35
35
  if (current !== p.before && current !== p.hash) throw new Error('正式产物在收尾中断后被其他操作修改,请先核对并恢复;不会覆盖');
36
36
  // 中断期间代码/报告也可能变化:发布前重新检查本轮门禁。
37
- applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, { [p.kind]: fs.readFileSync(staged, 'utf8') });
37
+ const getSnapshot = snapshotReader(root, p.run);
38
+ applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, { [p.kind]: fs.readFileSync(staged, 'utf8') }, getSnapshot);
38
39
  if (p.kind === 'plan') assertPlanBasis(root, req, p.run, { plan: fs.readFileSync(staged, 'utf8') });
39
40
  if (p.kind === 'review' || (isDev(p.run) && p.kind === 'delivery')) {
40
- if (p.kind === 'review') assertReview(root, req, p.run, { review: fs.readFileSync(staged, 'utf8') });
41
- else assertDelivery(root, req, p.run);
41
+ if (p.kind === 'review') assertReview(root, req, p.run, { review: fs.readFileSync(staged, 'utf8') }, getSnapshot);
42
+ else assertDelivery(root, req, p.run, undefined, getSnapshot);
42
43
  }
43
44
  if (current !== p.hash) {
44
45
  if (p.previous) {
@@ -115,6 +116,7 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
115
116
  if (!lint?.ok) throw new Error(`草稿自检失败:${lint?.errors?.join(';') || '模板不可用'}`);
116
117
  const at = new Date().toISOString();
117
118
  const run = structuredClone(current);
119
+ const getSnapshot = snapshotReader(root, run);
118
120
  // 文档收尾只能登记当前步骤,不能在一次落盘中跳到下游或替用户作确认。
119
121
  if (Object.keys(input).some((k) => !['steps', 'status', 'waiting_for', 'reason', 'context'].includes(k))) throw new Error('收尾 checkpoint 只接受 steps / status / waiting_for / reason / context;阶段和用户选择用 run.mjs save');
120
122
  const expectedStep = isDev(run) ? (kind === 'requirement' ? (run.kind === 'feature' ? 'F3' : 'B3') : kind === 'plan' ? (run.kind === 'feature' ? 'F4' : 'B4') : kind === 'review' ? (run.kind === 'feature' ? 'F7' : 'B5') : (run.kind === 'feature' ? 'F8' : 'B5')) : ({ review: 'R7', tech: 'T4', release: 'L4' })[run.kind];
@@ -124,7 +126,7 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
124
126
  requirement = assertRequirement(root, req, run);
125
127
  if (run.steps[run.kind === 'feature' ? 'F3' : 'B3'].status !== 'completed') throw new Error('需求文档尚未完成,不能收尾方案');
126
128
  }
127
- if (isDev(run) && kind === 'delivery') assertDelivery(root, req, run);
129
+ if (isDev(run) && kind === 'delivery') assertDelivery(root, req, run, undefined, getSnapshot);
128
130
  if ((fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null) !== existingWiki) throw new Error('wiki 发布记录在收尾期间变化,请重新读取后重试');
129
131
  const before = fileHash(file);
130
132
  const oldVersion = meta.versions?.[kind] ?? 1;
@@ -139,10 +141,10 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
139
141
  }
140
142
  applyCheckpoint(run, input, at, false);
141
143
  if (kind === 'review') {
142
- run.review = reviewEvidence(root, req, run, packet, result, { review: text });
144
+ run.review = reviewEvidence(root, req, run, packet, result, { review: text }, getSnapshot);
143
145
  run.decision = null;
144
146
  }
145
- applyDevEvidence(root, req, run, input, at, { [kind]: text });
147
+ applyDevEvidence(root, req, run, input, at, { [kind]: text }, getSnapshot);
146
148
  run.history.at(-1).artifact = { kind, hash: digest, version };
147
149
  run.revision++; run.updated_at = at; run.last_finalization = key;
148
150
  const op = randomUUID();
@@ -48,8 +48,14 @@ export function codeSnapshot(root, run) {
48
48
  return { ...snapshot, digest: hash(JSON.stringify({ ...snapshot, entries })) };
49
49
  }
50
50
 
51
- export function assertSnapshot(root, run, snapshot) {
52
- const current = codeSnapshot(root, run);
51
+ // 只在同一轮同步校验内复用;新的操作和发布阶段各自创建 reader。
52
+ export function snapshotReader(root, run) {
53
+ let current;
54
+ return () => current ??= codeSnapshot(root, run);
55
+ }
56
+
57
+ export function assertSnapshot(root, run, snapshot, getSnapshot = snapshotReader(root, run)) {
58
+ const current = getSnapshot();
53
59
  if (!snapshot?.digest || snapshot.digest !== current.digest) throw new Error('代码或基线已变化,原验证/审查证据已失效;重新生成快照、验证并审查');
54
60
  return current;
55
61
  }
@@ -2,7 +2,7 @@
2
2
  import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { FILES, parseBranch } from './artifact-model.mjs';
5
- import { hash, assertSnapshot, assertWorkingBranch } from './code-snapshot.mjs';
5
+ import { hash, assertSnapshot, assertWorkingBranch, snapshotReader } from './code-snapshot.mjs';
6
6
 
7
7
  export const isDev = (run) => ['feature', 'bug'].includes(run.kind);
8
8
  export const coreSteps = (run) => run.kind === 'feature' ? ['F3', 'F4', 'F5', 'F6', 'F7', 'F8'] : ['B3', 'B4', 'B5'];
@@ -33,25 +33,25 @@ export function assertPlan(root, req, run, contents) {
33
33
  return plan;
34
34
  }
35
35
 
36
- export function assertValidation(root, req, run, contents) {
36
+ export function assertValidation(root, req, run, contents, getSnapshot = snapshotReader(root, run)) {
37
37
  const plan = assertPlan(root, req, run, contents);
38
38
  if (run.implementation?.plan !== plan.hash) throw new Error('尚未通过方案门禁进入实现,请先进入 F5;bug 保存 implement: true');
39
- assertSnapshot(root, run, run.validation?.snapshot);
39
+ assertSnapshot(root, run, run.validation?.snapshot, getSnapshot);
40
40
  return run.validation;
41
41
  }
42
42
 
43
- export function assertReview(root, req, run, contents) {
44
- const validation = isDev(run) ? assertValidation(root, req, run, contents) : null;
43
+ export function assertReview(root, req, run, contents, getSnapshot = snapshotReader(root, run)) {
44
+ const validation = isDev(run) ? assertValidation(root, req, run, contents, getSnapshot) : null;
45
45
  const report = receipt(root, req, run, 'review', contents);
46
46
  if (!run.review || run.review.report_hash !== report.hash || run.review.report_version !== report.version
47
47
  || run.review.inputs !== hash(JSON.stringify(reviewInputs(run)))
48
48
  || (validation && run.review.snapshot.digest !== validation.snapshot.digest)) throw new Error('缺少对应本轮验证和报告版本的审查证据,请重新审查');
49
- if (!validation) assertSnapshot(root, run, run.review.snapshot);
49
+ if (!validation) assertSnapshot(root, run, run.review.snapshot, getSnapshot);
50
50
  return run.review;
51
51
  }
52
52
 
53
- export function assertDelivery(root, req, run, contents) {
54
- const review = assertReview(root, req, run, contents);
53
+ export function assertDelivery(root, req, run, contents, getSnapshot = snapshotReader(root, run)) {
54
+ const review = assertReview(root, req, run, contents, getSnapshot);
55
55
  const decision = run.decision;
56
56
  if (decision?.action !== 'deliver' || decision.confirmed !== true || decision.report_hash !== review.report_hash
57
57
  || decision.report_version !== review.report_version || decision.code !== review.snapshot.digest) throw new Error('进入交付前必须由用户明确选择本轮报告的交付;旧交付选择不再有效');
@@ -59,7 +59,7 @@ export function assertDelivery(root, req, run, contents) {
59
59
  if (serious.some((f) => !decision.accepted_risks?.includes(f.id))) throw new Error('严重遗留风险必须逐项说明并取得用户明确接受,记录 accepted_risks 中的问题 id');
60
60
  }
61
61
 
62
- export function applyDevEvidence(root, req, run, patch, at, contents = {}) {
62
+ export function applyDevEvidence(root, req, run, patch, at, contents = {}, getSnapshot = snapshotReader(root, run)) {
63
63
  if (!isDev(run)) return;
64
64
  for (const step of coreSteps(run)) if (run.steps[step].status === 'skipped') throw new Error(`完整 dev 核心步骤不能跳过:${step}`);
65
65
  if (patch.approval !== undefined) {
@@ -82,16 +82,16 @@ export function applyDevEvidence(root, req, run, patch, at, contents = {}) {
82
82
  const v = patch.validation;
83
83
  if (!Array.isArray(v?.checks) || !v.checks.length || v.checks.some((c) => !c.command?.trim()
84
84
  || !['passed', 'failed', 'unverified'].includes(c.result) || (c.result !== 'passed' && !c.reason?.trim()))) throw new Error('validation.checks 需要命令/操作、passed / failed / unverified;失败或未验证须写 reason');
85
- const snapshot = assertSnapshot(root, run, v.snapshot);
85
+ const snapshot = assertSnapshot(root, run, v.snapshot, getSnapshot);
86
86
  run.validation = { snapshot, checks: v.checks, at };
87
87
  run.review = null; run.decision = null;
88
88
  if (run.kind === 'feature') for (const step of ['F7', 'F8']) run.steps[step] = { status: 'pending' };
89
89
  }
90
90
  if (patch.decision?.action === 'deliver') {
91
91
  if (run.kind === 'feature' && run.steps.F7.status !== 'completed') throw new Error('审查步骤 F7 尚未完成,不能选择交付');
92
- const review = assertReview(root, req, run, contents);
92
+ const review = assertReview(root, req, run, contents, getSnapshot);
93
93
  run.decision = { ...run.decision, code: review.snapshot.digest, report_hash: review.report_hash, report_version: review.report_version };
94
- assertDelivery(root, req, run, contents);
94
+ assertDelivery(root, req, run, contents, getSnapshot);
95
95
  }
96
96
  const completed = (s) => patch.steps?.[s]?.status === 'completed';
97
97
  const requirementStep = run.kind === 'feature' ? 'F3' : 'B3';
@@ -108,18 +108,18 @@ export function applyDevEvidence(root, req, run, patch, at, contents = {}) {
108
108
  }
109
109
  if (patch.stage === 'F7' || completed('F6')) {
110
110
  if (run.steps.F5.status !== 'completed') throw new Error('实现步骤 F5 尚未完成');
111
- assertValidation(root, req, run, contents);
111
+ assertValidation(root, req, run, contents, getSnapshot);
112
112
  if (patch.stage === 'F7' && run.steps.F6.status !== 'completed') throw new Error('验证步骤 F6 尚未完成');
113
113
  }
114
- if (completed('F7')) assertReview(root, req, run, contents);
115
- if (patch.stage === 'F8' || completed('F8')) assertDelivery(root, req, run, contents);
114
+ if (completed('F7')) assertReview(root, req, run, contents, getSnapshot);
115
+ if (patch.stage === 'F8' || completed('F8')) assertDelivery(root, req, run, contents, getSnapshot);
116
116
  if (completed('F8')) receipt(root, req, run, 'delivery', contents);
117
117
  } else {
118
118
  if (completed('B4') || patch.stage === 'B5') {
119
- assertValidation(root, req, run, contents);
119
+ assertValidation(root, req, run, contents, getSnapshot);
120
120
  if (patch.stage === 'B5' && run.steps.B4.status !== 'completed') throw new Error('修复与验证步骤 B4 尚未完成');
121
121
  }
122
- if (completed('B5')) { assertDelivery(root, req, run, contents); receipt(root, req, run, 'delivery', contents); }
122
+ if (completed('B5')) { assertDelivery(root, req, run, contents, getSnapshot); receipt(root, req, run, 'delivery', contents); }
123
123
  }
124
124
  const event = run.history.at(-1);
125
125
  if (patch.approval) event.approval = run.plan_approval;
@@ -132,10 +132,10 @@ export function reviewInputs(run) {
132
132
  return { facts, requirement: run.artifacts?.requirement ?? null, scope: run.scope, plan: run.artifacts?.plan ?? null, validation: run.validation ?? null };
133
133
  }
134
134
 
135
- export function reviewEvidence(root, req, run, packet, result, contents) {
135
+ export function reviewEvidence(root, req, run, packet, result, contents, getSnapshot = snapshotReader(root, run)) {
136
136
  if (!packet || packet.run_id !== run.id || packet.revision > run.revision || packet.inputs !== hash(JSON.stringify(reviewInputs(run)))) throw new Error('审查交接材料不属于当前运行内容,请重新生成 handoff');
137
- const snapshot = assertSnapshot(root, run, packet.snapshot);
138
- if (isDev(run)) assertValidation(root, req, run, contents);
137
+ const snapshot = assertSnapshot(root, run, packet.snapshot, getSnapshot);
138
+ if (isDev(run)) assertValidation(root, req, run, contents, getSnapshot);
139
139
  if (result?.run_id !== run.id || result.code !== snapshot.digest || result.inputs !== packet.inputs) throw new Error('审查结果的运行、代码版本或交接内容不匹配,请返回本轮审查结果');
140
140
  if (!Array.isArray(result?.findings) || !Array.isArray(result?.coverage?.reviewed) || !Array.isArray(result?.coverage?.uncovered)) throw new Error('审查结果需要 findings 和 coverage.reviewed / uncovered');
141
141
  const covered = [...result.coverage.reviewed, ...result.coverage.uncovered];
@@ -8,7 +8,7 @@ import { updateMeta } from './meta-store.mjs';
8
8
  import { loadWorkspace } from './workspace-read.mjs';
9
9
  import { readProfile } from './project.mjs';
10
10
  import { isDev, coreSteps, applyDevEvidence, assertReview, assertDelivery, receipt } from './run-gates.mjs';
11
- import { codeSnapshot } from './code-snapshot.mjs';
11
+ import { codeSnapshot, snapshotReader } from './code-snapshot.mjs';
12
12
 
13
13
  export const FLOWS = {
14
14
  feature: ['Step0', 'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8'],
@@ -160,17 +160,18 @@ export function changeRun(root, { branch, id, revision, input = {}, action = 'sa
160
160
  run.history.push({ at, stage: run.stage, status: 'cancelled', reason: input.reason });
161
161
  } else {
162
162
  applyCheckpoint(run, input, at, action !== 'complete');
163
- applyDevEvidence(root, req, run, input, at);
163
+ const getSnapshot = snapshotReader(root, run);
164
+ applyDevEvidence(root, req, run, input, at, undefined, getSnapshot);
164
165
  if (action === 'complete') {
165
166
  const steps = FLOWS[run.kind];
166
167
  if (run.status !== 'running' || run.stage !== steps.at(-1) || !steps.every((s) => done(run.steps[s].status)) || run.steps[steps.at(-1)].status !== 'completed') throw new Error('还有未完成步骤、待用户决定或阻塞,不能标记已完成');
167
168
  if (['feature', 'bug'].includes(run.kind)) {
168
169
  const required = coreSteps(run);
169
- assertDelivery(root, req, run);
170
+ assertDelivery(root, req, run, undefined, getSnapshot);
170
171
  receipt(root, req, run, 'delivery');
171
172
  if (required.some((s) => run.steps[s].status !== 'completed') || run.decision?.action !== 'deliver' || !run.decision.confirmed) throw new Error('完整 dev 流程必须完成方案、实现、验证、审查和交付,且用户已选择交付');
172
173
  }
173
- if (run.kind === 'review') assertReview(root, req, run);
174
+ if (run.kind === 'review') assertReview(root, req, run, undefined, getSnapshot);
174
175
  const files = { feature: ['requirement.md', 'plan.md', 'review.md', 'delivery.md'], bug: ['requirement.md', 'plan.md', 'review.md', 'delivery.md'], review: ['review.md'], tech: ['tech-doc.md'], release: ['release-doc.md'] };
175
176
  for (const name of files[run.kind] ?? []) {
176
177
  const file = path.join(req.abs, name);
@@ -6,7 +6,7 @@ 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 { codeSnapshot, assertSnapshot, hash } from '../lib/code-snapshot.mjs';
9
+ import { snapshotReader, assertSnapshot, hash } from '../lib/code-snapshot.mjs';
10
10
  import { isDev, assertValidation, reviewInputs } from '../lib/run-gates.mjs';
11
11
  import { scope } from './review-scope.mjs';
12
12
 
@@ -14,12 +14,13 @@ export function handoff(root, { branch, id, depth = '标准', capabilities = nul
14
14
  const { req, run } = readRun(root, branch, id);
15
15
  if (!['feature', 'bug', 'review'].includes(run.kind) || ['completed', 'cancelled'].includes(run.status)) throw new Error('只有进行中的开发/审查运行可生成交接材料');
16
16
  if (req.meta.pending_finalization) throw new Error('先恢复待完成的产物收尾');
17
+ const getSnapshot = snapshotReader(root, run);
17
18
  if (isDev(run)) {
18
19
  if (run.stage !== (run.kind === 'feature' ? 'F7' : 'B5')) throw new Error('请先完成验证并进入审查阶段');
19
- assertValidation(root, req, run);
20
+ assertValidation(root, req, run, undefined, getSnapshot);
20
21
  }
21
22
  if (!['快审', '标准', '深审'].includes(depth)) throw new Error('审查深度须为快审 / 标准 / 深审');
22
- const snapshot = codeSnapshot(root, run);
23
+ const snapshot = getSnapshot();
23
24
  const reviewScope = scope(root, { base: run.scope?.base ?? 'main', exclude: run.scope?.exclude ?? [] });
24
25
  if (!reviewScope.ok) throw new Error(reviewScope.error);
25
26
  assertSnapshot(root, run, snapshot);