@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
@@ -0,0 +1,262 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { spawnSync } from 'node:child_process';
4
+
5
+ import { readProfile } from './project.mjs';
6
+ import { matchGlob } from './path-match.mjs';
7
+
8
+ const git = (root, args) => spawnSync('git', ['-c', 'core.quotepath=false', ...args], {
9
+ cwd: root,
10
+ encoding: 'utf8',
11
+ maxBuffer: 256 * 1024 * 1024,
12
+ });
13
+ const toPosix = (value) => value.split(path.sep).join('/');
14
+ const matchAny = (value, globs = []) => globs.find((glob) => matchGlob(value, glob)) ?? null;
15
+
16
+ const SECRET = ['**/.env', '**/.env.*', '**/*.pem', '**/*.key', '**/*.p12', '**/*.pfx', '**/*.jks', '**/*.keystore', '**/id_rsa*', '**/id_dsa*', '**/id_ecdsa*', '**/id_ed25519*', '**/.ssh/**', '**/.netrc', '**/.npmrc', '**/.pypirc', '**/database-query/config.json', '**/wiki-config.json'];
17
+ const SECRET_OK = ['**/.env.example', '**/.env.sample', '**/.env.template'];
18
+ const DEPENDENCY = ['**/node_modules/**', '**/vendor/**', '**/bower_components/**', '**/target/**', '**/.gradle/**', '**/__pycache__/**', '**/.venv/**', '**/site-packages/**', '**/.next/**', '**/.nuxt/**'];
19
+ const GENERATED = ['**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml', '**/go.sum', '**/Cargo.lock', '**/poetry.lock', '**/composer.lock', '**/Gemfile.lock', '**/*.min.js', '**/*.min.css', '**/*.map', '**/*.pb.go', '**/*.gen.go', '**/*.generated.*', '**/generated/**', '**/__snapshots__/**', '**/*.snap'];
20
+ const DOCS = ['**/*.md', '**/*.md.tpl', '**/*.txt', '**/*.rst', '**/*.adoc', '**/LICENSE', '**/CHANGELOG*'];
21
+ const TOOLING = ['workflow-run/**', '.agents/skills/**', '.claude/skills/**', '.qwen/skills/**', '.codebuddy/skills/**', '.codegraph/**'];
22
+ const NOTE = {
23
+ deleted: '文件已删除,不审内容;影响面里确认没有调用方还在用它',
24
+ binary: '二进制文件',
25
+ secret: '敏感文件,不读内容;它出现在改动里就提醒用户确认是否误提交了凭据',
26
+ dependency: '依赖目录',
27
+ generated: '生成文件或锁文件;依赖变化看 pom.xml / package.json / go.mod 等清单文件',
28
+ docs: '文档',
29
+ tooling: 'workflow-run 的产物或已安装的 skills',
30
+ user_exclude: '用户指定不审(--exclude 或画像 review.exclude)',
31
+ };
32
+
33
+ export function skipReason(file, { include = [], exclude = [] } = {}) {
34
+ if (file.status === 'D') return 'deleted';
35
+ if (file.binary) return 'binary';
36
+ const filePath = file.path;
37
+ if (matchAny(filePath, SECRET) && !matchAny(filePath, SECRET_OK)) return 'secret';
38
+ if (matchAny(filePath, exclude)) return 'user_exclude';
39
+ if (matchAny(filePath, include)) return null;
40
+ if (matchAny(filePath, DEPENDENCY)) return 'dependency';
41
+ if (matchAny(filePath, GENERATED)) return 'generated';
42
+ if (matchAny(filePath, DOCS)) return 'docs';
43
+ if (matchAny(filePath, TOOLING)) return 'tooling';
44
+ return null;
45
+ }
46
+
47
+ const LANG = [
48
+ [/\.(java|kt|kts|scala|groovy)$/i, 'Java / Kotlin'],
49
+ [/\.go$/i, 'Go'],
50
+ [/\.(ts|tsx|js|jsx|mjs|cjs|vue)$/i, 'TypeScript / JavaScript'],
51
+ [/\.(py|pyi)$/i, 'Python'],
52
+ [/\.sql$/i, 'SQL / MyBatis'],
53
+ ];
54
+ const TEST = /(^|\/)(src\/test\/|tests?\/|__tests__\/)|(Test|Tests|Spec)\.(java|kt|scala|groovy|swift)$|[._-](test|spec)\.[jt]sx?$|_test\.(go|py|rs)$|(^|\/)test_[^/]*\.py$/i;
55
+ const CONFIG = /(^|\/)(application|bootstrap)[^/]*\.(ya?ml|properties)$|\.(properties|conf|ini|toml)$|(^|\/)config\/[^/]*\.(ya?ml|json)$|(^|\/)\.env\.(example|sample|template)$/i;
56
+ const BUILD = /(^|\/)(pom\.xml|build\.gradle(\.kts)?|settings\.gradle(\.kts)?|package\.json|go\.mod|requirements[^/]*\.txt|pyproject\.toml|Cargo\.toml|composer\.json|Gemfile)$/i;
57
+ const SQLFILE = /\.sql$|(^|\/)(db|migration|migrations|flyway|liquibase)\/(?:[^/]+\/)*[^/]+\.(xml|ya?ml|json)$/i;
58
+ const MAPPER = /mapper[^/]*\.xml$|dao[^/]*\.xml$/i;
59
+ const DATA_OBJ = /(^|\/)(entity|entities|dto|vo|po|bo|domain|model|models|pojo|converter|convert|assembler)(\/|$)|(Entity|DTO|Dto|VO|Vo|PO|BO|Converter|Assembler|Mapping)\.(java|kt|ts|go|py)$/;
60
+ const ENTRY = /(^|\/)(controller|controllers|api|apis|endpoint|resource|resources|handler|handlers|router|routes)\/|Controller\.(java|kt)$/i;
61
+ const P1_PATH = /(^|\/)(service|services|impl|biz|manager|job|jobs|task|tasks|listener|consumer|consumers|handler|handlers|domain|entity|dto|vo|converter|repository|dao)\//i;
62
+ const KW = {
63
+ p0: /@Transactional|synchronized|\.(?:try)?lock\(|ReentrantLock|@Version|BigDecimal|amount|balance|@KafkaListener|KafkaTemplate|RabbitTemplate|RocketMQ|@PreAuthorize|@Secured|ALTER TABLE|CREATE TABLE|DELETE FROM|UPDATE\s+\S+\s+SET/i,
64
+ concurrency: /synchronized|\.(?:try)?lock\(|ReentrantLock|Atomic[A-Z]|ConcurrentHashMap|volatile|@Async|ThreadPool|Executor|CompletableFuture|go func|sync\.(Mutex|RWMutex|WaitGroup)|@Version|setnx|redisson/i,
65
+ mq: /@KafkaListener|@RabbitListener|@RocketMQMessageListener|@JmsListener|KafkaTemplate|RabbitTemplate|RocketMQTemplate|\.send\(|callback|notify|@Transactional/i,
66
+ sql: /\b(SELECT|INSERT|UPDATE|DELETE)\b.+\b(FROM|INTO|SET|WHERE)\b|@Select|@Update|@Insert|@Delete|createQuery|nativeQuery|jdbcTemplate/i,
67
+ config: /@Value\s*\(|@ConfigurationProperties|@NacosValue|@ApolloConfig|getProperty\(|os\.Getenv|process\.env/,
68
+ security: /@PreAuthorize|@Secured|permission|auth|token|password|secret|role/i,
69
+ };
70
+
71
+ export const stripComments = (text) => text.split('\n').map((line) => (
72
+ /^\s*(\*|\/\*)/.test(line) ? '' : line.replace(/(^|\s)\/\/.*$/, '$1')
73
+ )).join('\n');
74
+ export const stripRegexLiterals = (text) => text.replace(/([=(:,[!&|?{};]\s*|return\s+)\/(?![*/])(?:\\.|\[(?:\\.|[^\]\\\n])*\]|[^/\\\n[])+\/[a-z]*/g, '$1/re/');
75
+
76
+ export function classify(file, profileRules = []) {
77
+ const filePath = file.path;
78
+ let changed = file.changed_text ?? '';
79
+ if (/\.(java|kt|kts|scala|groovy|go|m?[jt]sx?|cjs|vue)$/i.test(filePath)) changed = stripComments(changed);
80
+ if (/\.(m?[jt]sx?|cjs|vue)$/i.test(filePath)) changed = stripRegexLiterals(changed);
81
+ const hit = (key) => KW[key].test(changed);
82
+ const lang = LANG.find(([pattern]) => pattern.test(filePath))?.[1] ?? (MAPPER.test(filePath) ? 'SQL / MyBatis' : null);
83
+ const kind = TEST.test(filePath) ? 'test'
84
+ : MAPPER.test(filePath) || SQLFILE.test(filePath) ? 'sql'
85
+ : BUILD.test(filePath) ? 'build'
86
+ : CONFIG.test(filePath) ? 'config'
87
+ : lang ? 'code' : 'other';
88
+ const sections = new Set();
89
+ if (kind === 'test') { sections.add(1); sections.add(13); }
90
+ else if (kind === 'sql') { [1, 6, 7, 12].forEach((number) => sections.add(number)); }
91
+ else if (kind === 'config') { [6, 10].forEach((number) => sections.add(number)); }
92
+ else if (kind === 'build') { sections.add(6); }
93
+ else { [1, 2, 5, 6, 7].forEach((number) => sections.add(number)); }
94
+ if (kind === 'code' || kind === 'other') {
95
+ if (DATA_OBJ.test(filePath)) sections.add(3);
96
+ if (hit('concurrency')) sections.add(4);
97
+ if (hit('mq')) sections.add(11);
98
+ if (hit('sql')) sections.add(12);
99
+ if (hit('config')) sections.add(10);
100
+ }
101
+ if (lang && kind !== 'config' && kind !== 'build') sections.add(14);
102
+ const risk = kind === 'test' ? 'P2'
103
+ : kind === 'sql' || kind === 'config' || ENTRY.test(filePath) || (kind === 'code' && hit('p0')) ? 'P0'
104
+ : P1_PATH.test(filePath) || DATA_OBJ.test(filePath) || kind === 'build' ? 'P1' : 'P2';
105
+ const project_rules = profileRules.filter((rule) => rule?.path && rule?.rule && matchGlob(filePath, rule.path))
106
+ .map((rule) => ({ path: rule.path, rule: rule.rule }));
107
+ return { kind, lang, risk, sections: [...sections].sort((a, b) => a - b), ...(project_rules.length ? { project_rules } : {}) };
108
+ }
109
+
110
+ export function parseDiff(text) {
111
+ const files = [];
112
+ let file = null;
113
+ let newLine = 0;
114
+ const strip = (value) => value.replace(/^"|"$/g, '').replace(/^[ab]\//, '');
115
+ for (const line of text.split('\n')) {
116
+ if (line.startsWith('diff --git ')) {
117
+ const match = /^diff --git (?:"?a\/(.+?)"?) (?:"?b\/(.+?)"?)$/.exec(line);
118
+ file = { path: match?.[2] ?? '', old: match?.[1] ?? '', status: 'M', binary: false, added: 0, deleted: 0, hunks: [], changed: [], inHunk: false };
119
+ files.push(file);
120
+ continue;
121
+ }
122
+ if (!file) continue;
123
+ if (file.inHunk) {
124
+ if (line.startsWith('@@')) { /* 下一段 hunk */ }
125
+ else if (line.startsWith('+')) { file.added++; file.changed.push(line.slice(1)); continue; }
126
+ else if (line.startsWith('-')) { file.deleted++; file.changed.push(line.slice(1)); continue; }
127
+ else continue;
128
+ }
129
+ if (line.startsWith('new file mode')) file.status = 'A';
130
+ else if (line.startsWith('deleted file mode')) file.status = 'D';
131
+ else if (line.startsWith('rename from ')) { file.old = line.slice(12); file.status = 'R'; }
132
+ else if (line.startsWith('rename to ')) file.path = line.slice(10);
133
+ else if (line.startsWith('Binary files ')) file.binary = true;
134
+ else if (line.startsWith('--- ')) { if (line !== '--- /dev/null') file.old = strip(line.slice(4)); }
135
+ else if (line.startsWith('+++ ')) { if (line !== '+++ /dev/null') file.path = strip(line.slice(4)); }
136
+ else if (line.startsWith('@@')) {
137
+ const match = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
138
+ newLine = Number(match?.[1] ?? 0);
139
+ const count = match?.[2] === undefined ? 1 : Number(match[2]);
140
+ if (count > 0) file.hunks.push([newLine, newLine + count - 1]);
141
+ file.inHunk = true;
142
+ }
143
+ }
144
+ return files.map(({ old, changed, inHunk, ...entry }) => ({
145
+ ...entry,
146
+ ...(entry.status === 'R' && old !== entry.path ? { old_path: old } : {}),
147
+ changed_text: changed.join('\n'),
148
+ }));
149
+ }
150
+
151
+ export function loadDiff(root, { diff = null, base = null } = {}) {
152
+ if (diff) {
153
+ if (!/\.{2,3}/.test(diff)) return { ok: false, error: '--diff 写成 <base>...<head>' };
154
+ const head = diff.split(/\.{2,3}/)[1] || 'HEAD';
155
+ const result = git(root, ['diff', '-U0', '-M', '--no-color', '--no-ext-diff', diff]);
156
+ if (result.status !== 0) return { ok: false, error: result.stderr.trim() || `git diff ${diff} 失败` };
157
+ return { ok: true, mode: 'diff', range: diff, ref: head, files: parseDiff(result.stdout) };
158
+ }
159
+ const baseBranch = base || readProfile(root).profile?.main_branch || 'main';
160
+ const mergeBase = git(root, ['merge-base', baseBranch, 'HEAD']);
161
+ if (mergeBase.status !== 0) return { ok: false, error: mergeBase.stderr.trim() || `找不到 ${baseBranch} 与 HEAD 的合并基点` };
162
+ const from = mergeBase.stdout.trim();
163
+ const result = git(root, ['diff', '-U0', '-M', '--no-color', '--no-ext-diff', from]);
164
+ if (result.status !== 0) return { ok: false, error: result.stderr.trim() || `git diff ${baseBranch} 失败` };
165
+ const files = parseDiff(result.stdout);
166
+ for (const entry of git(root, ['ls-files', '--others', '--exclude-standard', '-z']).stdout.split('\0').filter(Boolean)) {
167
+ const abs = path.join(root, entry);
168
+ let buffer;
169
+ try { buffer = fs.readFileSync(abs); } catch { continue; }
170
+ const binary = buffer.subarray(0, 8000).includes(0);
171
+ const text = binary ? '' : buffer.toString('utf8');
172
+ const count = binary || !text ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
173
+ files.push({ path: toPosix(entry), status: 'A', untracked: true, binary, added: count, deleted: 0, hunks: count ? [[1, count]] : [], changed_text: text });
174
+ }
175
+ return { ok: true, mode: 'base', range: `${baseBranch}...(含未提交与未跟踪)`, base: baseBranch, ref: 'WORKTREE', files };
176
+ }
177
+
178
+ export function readAt(root, ref, file) {
179
+ if (ref === 'WORKTREE') {
180
+ try { return fs.readFileSync(path.join(root, file), 'utf8'); } catch { return null; }
181
+ }
182
+ const result = git(root, ['show', `${ref}:${file}`]);
183
+ return result.status === 0 ? result.stdout : null;
184
+ }
185
+
186
+ const FULL_FILES = 30; const FULL_LINES = 1500; const BATCH_FILES = 15; const BATCH_LINES = 800; const TOO_MANY = 500;
187
+ export function plan(review) {
188
+ const lines = review.reduce((total, file) => total + file.added + file.deleted, 0);
189
+ if (review.length > TOO_MANY) return { size: '过大', batches: [], hint: `排除后还有 ${review.length} 个文件:停下,请用户按模块或提交区间缩小范围` };
190
+ const order = { P0: 0, P1: 1, P2: 2 };
191
+ const sorted = [...review].sort((a, b) => order[a.risk] - order[b.risk] || a.path.localeCompare(b.path));
192
+ if (review.length <= FULL_FILES && lines <= FULL_LINES) return { size: '全量精读', batches: [sorted.map((file) => file.path)] };
193
+ const batches = [];
194
+ let current = [];
195
+ let count = 0;
196
+ for (const file of sorted) {
197
+ const linesInFile = file.added + file.deleted;
198
+ if (current.length && (current.length >= BATCH_FILES || count + linesInFile > BATCH_LINES || current.at(-1).risk !== file.risk)) {
199
+ batches.push(current);
200
+ current = [];
201
+ count = 0;
202
+ }
203
+ current.push(file);
204
+ count += linesInFile;
205
+ }
206
+ if (current.length) batches.push(current);
207
+ return { size: '分批精读', batches: batches.map((batch) => batch.map((file) => file.path)), hint: '按批次顺序精读(P0 → P1 → P2),P0 不能跳过;没读完的批次写进报告「未覆盖与待确认」' };
208
+ }
209
+
210
+ export function reviewConfig(root) {
211
+ const review = readProfile(root).profile?.review ?? {};
212
+ const list = (value) => (Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.trim()) : []);
213
+ return { include: list(review.include), exclude: list(review.exclude), rules: Array.isArray(review.rules) ? review.rules : [] };
214
+ }
215
+
216
+ export function scope(root, options = {}) {
217
+ const diff = loadDiff(root, options);
218
+ if (!diff.ok) return diff;
219
+ const config = options.config ?? reviewConfig(root);
220
+ const exclude = [...config.exclude, ...(options.exclude ?? [])];
221
+ const review = [];
222
+ const skipped = [];
223
+ for (const file of diff.files) {
224
+ const reason = skipReason(file, { include: config.include, exclude });
225
+ const base = {
226
+ path: file.path,
227
+ ...(file.old_path ? { old_path: file.old_path } : {}),
228
+ status: file.status,
229
+ ...(file.untracked ? { untracked: true } : {}),
230
+ added: file.added,
231
+ deleted: file.deleted,
232
+ };
233
+ if (reason) { skipped.push({ ...base, reason, note: NOTE[reason] }); continue; }
234
+ review.push({ ...base, ...classify(file, config.rules), ...(file.added + file.deleted > BATCH_LINES ? { large: true } : {}) });
235
+ }
236
+ const batchPlan = plan(review);
237
+ const count = (items, key) => items.reduce((map, item) => {
238
+ map[item[key]] = (map[item[key]] ?? 0) + 1;
239
+ return map;
240
+ }, {});
241
+ return {
242
+ ok: true,
243
+ mode: diff.mode,
244
+ range: diff.range,
245
+ ref: diff.ref,
246
+ summary: {
247
+ files: diff.files.length,
248
+ review: review.length,
249
+ skipped: skipped.length,
250
+ lines: review.reduce((total, file) => total + file.added + file.deleted, 0),
251
+ risk: count(review, 'risk'),
252
+ skipped_by_reason: count(skipped, 'reason'),
253
+ size: batchPlan.size,
254
+ },
255
+ overall_sections: review.length ? [9, 13] : [],
256
+ review,
257
+ skipped,
258
+ batches: batchPlan.batches,
259
+ ...(batchPlan.hint ? { hint: batchPlan.hint } : {}),
260
+ next: '每个文件按 sections 过清单(rules <文件…> 打印对应小节原文和项目规则);整个改动再过一次 overall_sections(9 影响面、13 测试)。报告「未覆盖与待确认」按 reason 汇总 skipped,没读完的文件逐个列出',
261
+ };
262
+ }
@@ -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('尚未通过方案门禁进入实现');
@@ -33,6 +33,7 @@ export const branchRuns = (root, branch, workspace) => allRuns(root, workspace).
33
33
  export function runState(root, branch, workspace = loadWorkspace(root), id = null) {
34
34
  const runs = branchRuns(root, branch, workspace);
35
35
  const current = id ? runs.find((r) => r.id === id) ?? null : runs.filter((r) => !terminal(r.status)).at(-1) ?? runs.at(-1) ?? null;
36
+ const pending = current?.pending_finalization ?? null;
36
37
  let next = !current ? null : current.pending_finalization ? `先恢复产物收尾:artifact.mjs resume --id ${current.id}` : current.status === 'waiting_user' ? `等待用户:${current.waiting_for}`
37
38
  : current.status === 'blocked' ? `处理阻塞:${current.reason}`
38
39
  : terminal(current.status) ? `${STATUS_LABELS[current.status]}:${current.kind}(${current.id})`
@@ -48,7 +49,16 @@ export function runState(root, branch, workspace = loadWorkspace(root), id = nul
48
49
  if (!current.pending_finalization) next = `核对证据失败:${e.message}`;
49
50
  }
50
51
  }
51
- return { branch, current, runs, next, ...(freshness ? { freshness } : {}), ...(workspace.diagnostics.length ? { diagnostics: workspace.diagnostics } : {}) };
52
+ return {
53
+ branch,
54
+ current,
55
+ runRevision: pending?.runRevision ?? current?.revision ?? null,
56
+ ...(pending ? { pending } : {}),
57
+ runs,
58
+ next,
59
+ ...(freshness ? { freshness } : {}),
60
+ ...(workspace.diagnostics.length ? { diagnostics: workspace.diagnostics } : {}),
61
+ };
52
62
  }
53
63
 
54
64
  export function applyCheckpoint(run, patch, at, reopen = true) {
@@ -125,7 +135,8 @@ export function startRun(root, { branch, kind = 'feature', size = null, input =
125
135
  selected = applyCheckpoint({ id, kind, size, branch, revision: 1, status: 'running', stage: FLOWS[kind][0],
126
136
  created_at: at, updated_at: at, completed_at: null, steps: Object.fromEntries(FLOWS[kind].map((s) => [s, { status: 'pending' }])),
127
137
  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);
138
+ artifacts: {}, context: {}, waiting_for: null, reason: null, decision: null, history: [],
139
+ ...(['feature', 'bug'].includes(kind) ? { document_review_policy: 1 } : {}) }, input, at);
129
140
  applyDevEvidence(root, req, selected, input, at);
130
141
  return { ...meta, runs: { ...runs, [id]: selected }, updated: at };
131
142
  }, { root });
@@ -73,7 +73,7 @@ export function loadWorkspace(root, { allProjects = false, allBranches = false }
73
73
  const found = new Set();
74
74
  const index = Array.isArray(req.meta.artifacts) ? req.meta.artifacts.filter((item) => item && typeof item.file === 'string') : [];
75
75
  if (req.meta.artifacts !== undefined && (!Array.isArray(req.meta.artifacts) || index.length !== req.meta.artifacts.length)) {
76
- diagnostics.push({ code: 'invalid_index', path: `${req.dir}/meta.json`, message: '产物索引结构无效,请显式 sync;运行状态保留' });
76
+ diagnostics.push({ code: 'invalid_index', path: `${req.dir}/meta.json`, message: '产物索引结构无效,请显式 reindex;运行状态保留' });
77
77
  }
78
78
  for (const entry of fs.readdirSync(req.abs, { withFileTypes: true })) {
79
79
  if (!entry.isFile() || !parseFile(entry.name)) continue;
@@ -84,9 +84,9 @@ export function loadWorkspace(root, { allProjects = false, allBranches = false }
84
84
  artifacts.push(a);
85
85
  const indexed = index.find((i) => i.file === entry.name);
86
86
  if ((Array.isArray(req.meta.artifacts) && !indexed) || (indexed && (indexed.branch !== a.branch || indexed.date !== a.date
87
- || JSON.stringify(indexed.wiki) !== JSON.stringify(a.wiki) || indexed.version !== a.version
87
+ || JSON.stringify(indexed.wiki) !== JSON.stringify(a.wiki) || (indexed.registered !== false && indexed.version !== a.version)
88
88
  || JSON.stringify(indexed.docnexus ?? []) !== JSON.stringify(a.knowledge)))) {
89
- diagnostics.push({ code: 'stale_index', path: file, message: '文档与已登记索引不一致,请显式 sync' });
89
+ diagnostics.push({ code: 'stale_index', path: file, message: '文档与已登记索引不一致,请显式 reindex' });
90
90
  }
91
91
  } catch (e) {
92
92
  diagnostics.push({ code: 'unreadable_artifact', path: file, message: e.message });
@@ -105,7 +105,16 @@ export function loadWorkspace(root, { allProjects = false, allBranches = false }
105
105
  }
106
106
  const pending = req.meta.pending_finalization;
107
107
  runs.push({ ...run, requirement: req.name, dir: req.dir, project: req.project,
108
- ...(pending?.run_id === id ? { pending_finalization: { kind: pending.kind, id: pending.id } } : {}) });
108
+ ...(pending?.run_id === id ? {
109
+ pending_finalization: {
110
+ kind: pending.kind,
111
+ id: pending.id,
112
+ operationId: pending.id,
113
+ runId: pending.run_id,
114
+ baseRevision: pending.revision,
115
+ runRevision: pending.run?.revision ?? pending.revision + 1,
116
+ },
117
+ } : {}) });
109
118
  }
110
119
  }
111
120
  artifacts.sort(byArtifactDate);
@@ -2,6 +2,8 @@
2
2
 
3
3
  本文对应 0.29.0(2026-10-28),包括独立 nacos-config、需求文档与 dev 显式触发规则;实现以代码与各 skill 的 skill.json 为准。
4
4
 
5
+ 内部程序调用的方法、错误与暂定边界见 [core-api.md](core-api.md)。
6
+
5
7
  ## 安装分发与运行
6
8
 
7
9
  安装接入在 `bin/`;各 Skill 的 SKILL.md 与 references 定义流程步骤、确认点和调用时机;`workflow/lib/` 承担共享规则与数据读写;`workflow/scripts/` 保留既有命令和导出入口。数据库、代码图谱、wiki、Nacos 的执行与凭据仍在各自能力目录。`shared/` 只分发参考文档,运行共享代码随 workflow 的 lib 一起安装。宿主代理执行规则与命令,workflow-run 不提供常驻的 Agent 调度服务。
@@ -27,36 +29,39 @@ dev 的入口要求显式流程授权:实际调用 `/dev` / `$dev`、点选 sk
27
29
 
28
30
  | 模块 | 职责 |
29
31
  |---|---|
32
+ | core/index | 无全局单例的 `createWorkflow` 门面;统一运行、需求、索引、产物和审查操作 |
33
+ | core/review-handoff | 只组装审查事实与证据,不推进运行 |
30
34
  | capabilities | 必装 DocNexus 门槛、wiki / CodeGraph / 数据库的统一接入探测与通道选择 |
31
35
  | project | 布局、路径、项目画像、本机环境与配置 |
32
36
  | requirement-read | 需求目录和元信息读取、查询与分组 |
33
- | requirements | 需求绑定、产物版本、归档、索引写入 |
37
+ | requirements | 需求绑定与派生索引维护;正式版本和归档由 finalize 负责 |
34
38
  | runs | 运行阶段、用户选择、revision、完成与取消 |
35
39
  | run-gates | 方案确认、实现/验证/审查/交付转换门禁,核对证据与版本 |
36
40
  | code-snapshot | 基线、HEAD 与工作区文件内容摘要,校验验证/审查仍适用 |
37
41
  | artifact-finalize | 草稿检查、正式发布、归档、索引与运行证据登记;在 meta 中记录可恢复收尾 |
38
42
  | path-match | 审查范围与代码快照复用的纯 glob 匹配 |
43
+ | review-scope | 审查范围、跳过规则、风险分类、清单路由输入与分批 |
39
44
  | meta-store | 元信息写锁与原子替换;写入前自动创建父目录,再按真实路径归一化加锁;读取不创建目录 |
40
45
  | document-model | 标题、章节、表格、元信息等纯文本解析 |
41
46
  | artifact-model | 产物种类、文件名、分支、日期、发布与沉淀、审查和交付解析 |
42
47
  | workspace-read | 工作区/Git 数据采集,统一内存快照与诊断 |
43
48
 
44
- lib 不依赖 scripts;纯模型不依赖 I/O。读侧不调用 sync 或推进运行,写侧在原有锁内重读元信息。布局配置不依赖需求或运行,避免形成循环依赖。`updateMeta` 负责创建写入所需的父目录,调用方负责需求绑定与流程前置校验;存储层建目录不代表需求已绑定。
49
+ lib 不依赖 scripts;纯模型不依赖 I/O。读侧不调用 reindex 或推进运行,写侧在原有锁内重读元信息。布局配置不依赖需求或运行,避免形成循环依赖。`updateMeta` 负责创建写入所需的父目录,调用方负责需求绑定与流程前置校验;存储层建目录不代表需求已绑定。
45
50
 
46
51
  ## 数据归属
47
52
 
48
53
  - `meta.json`:需求名称、绑定分支、项目、已登记版本、runs 和扩展字段。
49
54
  - Markdown:正文、文档头、wiki 发布记录、DocNexus 沉淀引用。
50
- - `artifacts`、`latest`:由显式 sync 重建的索引,不能覆盖 runs;文档头不隐式改变需求绑定。
55
+ - `artifacts`、`latest`:由显式 reindex 重建的派生索引,不能覆盖 versions、runs、批准或证据;文档头不隐式改变需求绑定。
51
56
  - 文件存在不代表运行已完成。只读查询不会创建需求目录或状态文件。
52
57
 
53
58
  `loadWorkspace` 返回 requirements、artifacts、runs、diagnostics、layout 和 scanned_branches。产物条目包含来源、需求/项目、分支、类型、版本、日期、正文及解析结果。相同来源和查询范围内,按日期、版本、修改时间排序。当前项目、全部项目和 Git 分支是显式读取范围:view 使用全部项目,分支查询与效果报告默认当前项目;所有入口都忽略 other、tmp、DocNexus 知识目录。
54
59
 
55
60
  一次命令内只采集一份快照并传给各查询,正文不再次读取。快照是已读数据的内存表示,不是跨全部文件的事务锁;并发改动在下次采集时可见。不会新增持久索引或缓存文件。运行写入仍用 revision 与元信息锁。
56
61
 
57
- `--all-branches` 继续按路径去重、工作区优先;分支中才有的文件从 Git 补入,版本取同一 Git 引用的 meta.json,不混用工作区版本。未迁移旧目录的 Git 产物仍可读取,版本缺失时按原文件名规则回退。
62
+ `--all-branches` 继续按路径去重、工作区优先;分支中才有的文件从 Git 补入,版本取同一 Git 引用的 meta.json,不混用工作区版本。
58
63
 
59
- 损坏元信息、无效运行、索引不一致和引用文件缺失进入 diagnostics,状态/报告/视图显示诊断。可读正文保留展示,损坏运行不提供恢复;读取不会将坏元信息重建为空记录。`list` 也只读取;用户修复数据或显式 sync 后重新加载即可。
64
+ 损坏元信息、无效运行、索引不一致和引用文件缺失进入 diagnostics,状态/报告/视图显示诊断。可读正文保留展示,损坏运行不提供恢复;读取不会将坏元信息重建为空记录。`list` 也只读取;用户修复数据或显式 reindex 后重新加载即可。
60
65
 
61
66
  ## 能力边界
62
67
 
@@ -0,0 +1,196 @@
1
+ # Workflow Core 内部接口
2
+
3
+ 状态:第一阶段内部接口契约已冻结(2026-11-17)。本接口只供同包 Skills 和内部 Node.js 调用,不是第二阶段外部协议。
4
+
5
+ 入口:
6
+
7
+ ```js
8
+ import { createWorkflow } from '../workflow/core/index.mjs';
9
+
10
+ const workflow = createWorkflow({
11
+ root: '/absolute/business/project',
12
+ documentPolicy,
13
+ });
14
+ ```
15
+
16
+ `root` 必须显式且为绝对路径。构造不读写文件、不启动子进程、不创建运行。`documentPolicy` 只在正式产物收尾时需要;不提供时 `artifacts.finalize` 返回 `INVALID_ARGUMENT`。
17
+
18
+ Skills 命令脚本保留参数解析和人类可读输出,不转导出底层写函数。例如 `requirement.mjs` 只保留自身 CLI、只读查询与外围配置 helper,不再导出 `bind / which / reindex / reindexRequirement`;调用方必须进入 `createWorkflow` 的 `requirements.bind / which` 或 `maintenance.reindex`。核心实现模块仍供门面和同包测试内部使用,但不构成脚本级旁路。
19
+
20
+ | 能力 | 归属 | 入口 |
21
+ | --- | --- | --- |
22
+ | `bind` / `which` / `reindex` | 核心生命周期 / 查询 | `createWorkflow` |
23
+ | `list` / `pending` | Skills 外围只读展示 | `requirement.mjs` 与 `workflow/lib/workspace-read.mjs` |
24
+ | 项目配置读取与 `config` | Skills 外围配置 | `requirement.mjs` / `workflow/lib/project.mjs` |
25
+
26
+ 架构测试扫描 `workflow/scripts/**/*.mjs`,禁止从 `workflow/lib/requirements.mjs` 导入或转导出 `bind / reindex / reindexRequirement`。新增旁路会直接使测试失败。
27
+
28
+ ## 方法
29
+
30
+ | 分组 | 方法 | 输入 | 结果 |
31
+ | --- | --- | --- | --- |
32
+ | requirements | `bind` | `{ name?, branch, base? }` | 绑定、目录和分支 |
33
+ | requirements | `which` | `{ branch }` | 当前绑定;只读 |
34
+ | maintenance | `reindex` | `{ branch?, all? }` | 派生索引结果;不推进运行 |
35
+ | runs | `start` | `{ branch, kind?, size?, input?, dir? }` | 新建或恢复现有活动运行 |
36
+ | runs | `status` | `{ branch, id? }` | 当前运行列表、下一步、证据新鲜度以及 pending 的 revision / operationId |
37
+ | runs | `get` | `{ branch, id }` | 指定运行及需求目录 |
38
+ | runs | `save` | `{ branch, id, expectedRevision, input }` | 保存 checkpoint |
39
+ | runs | `complete` | `{ branch, id, expectedRevision, input? }` | 完成并通过末步门禁 |
40
+ | runs | `cancel` | `{ branch, id, expectedRevision, reason }` | 取消运行 |
41
+ | snapshots | `capture` | `{ branch, id }` | 当前分支代码快照 |
42
+ | artifacts | `finalize` | `{ branch, id, expectedRevision, kind, text, input?, packet?, result? }` | 发布、归档、索引和证据 |
43
+ | artifacts | `resume` | `{ branch, id, expectedRevision, operationId }` | 核对 pending 身份后发布并提交目标 revision |
44
+ | artifacts | `abort` | `{ branch, id, expectedRevision, operationId }` | 核对 pending 身份后还原文件并移除待办 |
45
+ | reviews | `prepare` | `{ branch, id, depth?, capabilities?, kind?, text? }` | 审查交接 JSON 文件 |
46
+
47
+ ## reindex 契约
48
+
49
+ `maintenance.reindex({ branch })` 处理当前绑定需求;`maintenance.reindex({ all: true })` 逐个处理当前项目的全部需求。`all` 必须是布尔值。有 `pending_finalization` 的目录拒绝维护;批量模式按目录加锁、继续处理其他目录,不声称跨目录原子性。
50
+
51
+ 只允许写以下派生字段:
52
+
53
+ - `artifacts`:当前目录内已识别产物的派生索引。
54
+ - `latest`:每种产物的最新文件,可能包含未登记版本。
55
+ - `indexed_at`:只在 `artifacts` 或 `latest` 变化、或旧数据缺少该字段时更新。
56
+
57
+ `versions`、`runs`、`branches`、`base`、批准、证据、正文和 `updated` 均保持不变。固定文件名没有权威 `versions` 记录时,索引项持久化为 `version: null, registered: false`,并在 `unregistered` 中返回;reindex 不提升版本、不归档、不生成证据。
58
+
59
+ 单需求结果:
60
+
61
+ ```js
62
+ {
63
+ ok: true,
64
+ dir: 'workflow-run/docs/requirements/order/svc',
65
+ changed: true,
66
+ artifacts: 2, // 兼容数量字段
67
+ artifact_count: 2,
68
+ latest: {},
69
+ versions: {},
70
+ unregistered: [{ kind: 'review', file: 'review.md' }],
71
+ }
72
+ ```
73
+
74
+ `all` 结果:
75
+
76
+ ```js
77
+ {
78
+ ok: false,
79
+ results: [
80
+ { ok: true, dir: '...', changed: false, artifact_count: 1, latest: {}, versions: {}, unregistered: [] },
81
+ { ok: false, dir: '...', error: '产物收尾尚未完成...', code: 'PENDING_FINALIZATION' },
82
+ ],
83
+ }
84
+ ```
85
+
86
+ 损坏 JSON、branch 未绑定需求等单需求错误直接抛出 `WorkflowError`;批量模式把它们记录在对应结果中。
87
+
88
+ `list`、`pending` 是 Skills 外围只读查询,`config` 是外围配置入口;它们不进入核心生命周期,也不能写 run、产物索引或证据。
89
+
90
+ ## 文档策略
91
+
92
+ `documentPolicy` 是受信任的代码扩展点:
93
+
94
+ ```js
95
+ const documentPolicy = {
96
+ validate({ kind, text }) {
97
+ return {
98
+ ok: true,
99
+ errors: [],
100
+ warnings: [],
101
+ };
102
+ },
103
+ };
104
+ ```
105
+
106
+ Skills 使用 `workflow/integrations/skill-document-policy.mjs` 读取当前模板并执行正文检查。核心不跳过缺失 policy,也不把 policy 扩展成通用插件系统。
107
+
108
+ 输入固定为 `{ kind, text }`,其中 `text` 已包含需要保留的 wiki 页面记录;返回结构固定为 `{ ok, errors, warnings }`,`errors` / `warnings` 均为字符串数组。`ok !== true` 时 finalize 拒绝发布,警告随成功结果返回。policy 抛出的异常按核心错误映射处理,不吞掉后继续写文件。
109
+
110
+ ## 错误
111
+
112
+ 领域失败抛出 `WorkflowError`:
113
+
114
+ ```js
115
+ {
116
+ name: 'WorkflowError',
117
+ code: 'REVISION_CONFLICT',
118
+ message: '...',
119
+ details: {},
120
+ }
121
+ ```
122
+
123
+ 稳定字段是 `name`、`code`、`message`、`details`;发生底层异常时同时保留 `cause`。`details` 始终是对象。调用方按 `code` 分支,不解析中文 `message`。本阶段冻结的错误码集合见下方,新增或删除属于接口变更。
124
+
125
+ 稳定 code 定义在 `workflow/core/errors.mjs`:
126
+
127
+ - `INVALID_ARGUMENT`
128
+ - `PROJECT_ROOT_INVALID`
129
+ - `PROJECT_CONFIG_AMBIGUOUS`
130
+ - `REQUIREMENT_NOT_READY`
131
+ - `REQUIREMENT_NOT_BOUND`
132
+ - `BRANCH_MISMATCH`
133
+ - `RUN_NOT_FOUND`
134
+ - `REVISION_CONFLICT`
135
+ - `RUN_TERMINAL`
136
+ - `STAGE_NOT_ALLOWED`
137
+ - `GATE_REJECTED`
138
+ - `EVIDENCE_INVALID`
139
+ - `PENDING_FINALIZATION`
140
+ - `PENDING_OPERATION_MISMATCH`
141
+ - `STORAGE_ERROR`
142
+ - `NOT_IMPLEMENTED`(保留码;第一阶段已迁移的操作不使用)
143
+
144
+ CLI 将错误作为 JSON 写到 stderr,并返回非零退出码。底层 I/O 错误保留为 `cause`,路径等安全元信息可放入 `details`。
145
+
146
+ ## finalize 重放
147
+
148
+ 请求标识使用递归键排序的稳定 JSON,包含 run、原始 `expectedRevision`、产物类型、发布正文摘要、checkpoint、packet 和 result。同一语义请求重复时返回 `alreadyFinalized: true`,不增加 revision、历史或版本;正文或输入变化后不能借旧 revision 绕过冲突检查。
149
+
150
+ 首次成功和成功重放均有 `ok`、`path`、`run`;核心门面把底层 `already_finalized` 原样保留,并增加 camelCase `alreadyFinalized`。首次成功为 `false`,成功重放为 `true`。成功重放不承诺在后续别的 finalize 或正文变化后继续返回旧响应,调用方必须检查 `run.revision` 与正文当前状态。
151
+
152
+ 首次发布还返回 `operationId`、`baseRevision`、`cite`、`previous`、`version`、`lint`;重放只证明请求对应操作的成功结果已经提交,调用方不能据旧 `alreadyFinalized` 声称当前代码证据仍然有效。
153
+
154
+ ## pending 恢复与中止
155
+
156
+ 收尾中断时,`meta.runs[id]` 保留已提交运行,`pending_finalization` 保存本次操作预定的下一版运行。`runs.status()` 用顶层字段表达两者:
157
+
158
+ ```js
159
+ const state = workflow.runs.status({ branch, id });
160
+ // state.runRevision: 9
161
+ // state.current.revision: 8(已提交快照)
162
+ // state.pending: {
163
+ // operationId: 'op-123',
164
+ // runId: id,
165
+ // kind: 'delivery',
166
+ // baseRevision: 8,
167
+ // runRevision: 9,
168
+ // }
169
+
170
+ workflow.artifacts.resume({
171
+ branch,
172
+ id,
173
+ expectedRevision: state.runRevision,
174
+ operationId: state.pending.operationId,
175
+ });
176
+ ```
177
+
178
+ `expectedRevision` 始终是调用时的 `status.runRevision`,不是 pending 的 base revision。核心在需求锁内再次核对已保存运行等于 `baseRevision`、请求等于目标 `runRevision`,并精确比较 operationId;任一不符都不会打开、发布或还原正文。
179
+
180
+ `resume` 成功提交 pending 的目标运行。`abort` 只移除该 pending 并保留已保存的 base 运行;之后可以创建新的 pending,但它会获得新的 operationId,旧请求即使 revision 相同也不能操作新事务。若 pending 已消失、被替换或已由另一请求完成,旧 operationId 返回 `PENDING_OPERATION_MISMATCH`。
181
+
182
+ ## 配置来源
183
+
184
+ 项目配置只从目标 root 解析。`workflow-run/profile-source.json` 中的显式选择优先级最高;没有显式选择时,规范位置 `.agents/skills/workflow/` 优先;其他支持的安装位置只在规范位置不存在时参与解析。
185
+
186
+ `--copy` 多环境安装首次生成的多份 `profile.json` / `profile.local.json` 内容完全相同时,可以自动使用按 `.agents` → `.claude` → `.qwen` → `.codebuddy` 固定顺序出现的第一份;任一份配置变化后,解析会返回 `PROJECT_CONFIG_AMBIGUOUS`,不会静默改选。显式选择只在目标 root 内受支持的安装目录中生效:
187
+
188
+ ```sh
189
+ node <skills>/workflow/scripts/requirement.mjs config --profile-source claude
190
+ node <skills>/workflow/scripts/requirement.mjs config --profile-source .qwen/skills/workflow
191
+ node <skills>/workflow/scripts/requirement.mjs config --profile-source auto
192
+ ```
193
+
194
+ 选择写入 `workflow-run/profile-source.json` 的 `profile_dir`,`auto` 删除该文件并恢复自动解析。来源文件损坏、目录被删除或试图选择 root 外目录时返回 `PROJECT_CONFIG_AMBIGUOUS`,`details.reason` 为 `invalid_source`,同时列出可用来源。
195
+
196
+ CLI 的 `artifact.mjs resume/abort --id <id>` 会先读取 status 中当前 pending 的 `runRevision` 和 `operationId`,再调用同一核心入口;若读取后 pending 被替换,核心拒绝旧请求,不会自动改绑。