@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.
- package/CHANGELOG.md +23 -1
- package/README.md +2 -0
- package/bin/lib/artifact-context.mjs +1 -1
- package/bin/lib/docsrepo.mjs +4 -6
- package/bin/lib/doctor.mjs +0 -3
- package/bin/lib/install.mjs +15 -15
- package/create-release-md-doc/SKILL.md.tpl +1 -1
- package/create-tech-md-doc/SKILL.md.tpl +1 -1
- package/dev/references/delivery.md +3 -3
- package/docs/architecture.html +3 -2
- package/docs/development.md +10 -4
- package/docs/full-install.html +90 -125
- package/docs/installation.md +1 -1
- package/docs/loan-service-install.html +90 -0
- package/docs/team-guide.md +3 -2
- package/docs/workflow-control-roadmap.md +144 -0
- package/docs/workflow-core-phase-one-report.md +41 -0
- package/docs/workflow-core-phase-one.md +317 -0
- package/docs/workflows.md +2 -2
- package/examples/workflow-core.mjs +26 -0
- package/package.json +2 -1
- package/project-review/SKILL.md.tpl +1 -1
- package/project-review/references/checklist.md.tpl +1 -1
- package/project-review/references/reporting.md +2 -2
- package/workflow/core/errors.mjs +61 -0
- package/workflow/core/index.mjs +286 -0
- package/workflow/core/review-handoff.mjs +101 -0
- package/workflow/integrations/skill-document-policy.mjs +28 -0
- package/workflow/lib/artifact-finalize.mjs +49 -10
- package/workflow/lib/code-snapshot.mjs +5 -0
- package/workflow/lib/meta-store.mjs +12 -1
- package/workflow/lib/project.mjs +165 -14
- package/workflow/lib/requirements.mjs +57 -100
- package/workflow/lib/review-scope.mjs +262 -0
- package/workflow/lib/runs.mjs +11 -1
- package/workflow/lib/workspace-read.mjs +13 -4
- package/workflow/references/architecture.md +10 -5
- package/workflow/references/core-api.md +196 -0
- package/workflow/references/execution.md +4 -4
- package/workflow/references/profile.md +20 -0
- package/workflow/references/requirements.md +12 -12
- package/workflow/scripts/artifact.mjs +36 -14
- package/workflow/scripts/requirement.mjs +36 -40
- package/workflow/scripts/resolve.mjs +2 -2
- package/workflow/scripts/review-handoff.mjs +49 -73
- package/workflow/scripts/review-scope.mjs +78 -294
- 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
|
+
}
|
package/workflow/lib/runs.mjs
CHANGED
|
@@ -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 {
|
|
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) {
|
|
@@ -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: '产物索引结构无效,请显式
|
|
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: '文档与已登记索引不一致,请显式
|
|
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 ? {
|
|
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。读侧不调用
|
|
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`:由显式
|
|
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
|
|
62
|
+
`--all-branches` 继续按路径去重、工作区优先;分支中才有的文件从 Git 补入,版本取同一 Git 引用的 meta.json,不混用工作区版本。
|
|
58
63
|
|
|
59
|
-
损坏元信息、无效运行、索引不一致和引用文件缺失进入 diagnostics,状态/报告/视图显示诊断。可读正文保留展示,损坏运行不提供恢复;读取不会将坏元信息重建为空记录。`list` 也只读取;用户修复数据或显式
|
|
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 被替换,核心拒绝旧请求,不会自动改绑。
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
{"scope":{"base":"main","exclude":["unrelated/**"]}}
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用
|
|
13
|
+
完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 reindex 代替收尾。模板由调用方用 `resolve.mjs template <skill> <id>` 读取,按 [templates.md](templates.md) 的「文档模板的两部分」填充正文。首次生成清单时用 dev 的 clarification-template.md,后续各轮把上一版正式清单复制到 tmp 更新,再发布:
|
|
14
14
|
|
|
15
15
|
```sh
|
|
16
16
|
node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind clarification --draft workflow-run/tmp/clarification.md --input workflow-run/tmp/checkpoint.json
|
|
@@ -113,13 +113,13 @@ feature 可在 checkpoint 标 F7 completed;bug 的 B5 此时仍 in_progress。
|
|
|
113
113
|
|
|
114
114
|
只有该选择仍有效,才允许 `artifact.mjs finalize --kind delivery --draft ...`。审查后代码/基线变化或报告被修改,旧选择不能继续用;回 F6(bug 回 B4)、验证、复审、再次取得选择。修复回退会清除旧验证、审查与交付选择;方案改变则还须重新确认。
|
|
115
115
|
|
|
116
|
-
交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只
|
|
116
|
+
交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只 reindex 后用旧收尾凭据 complete。
|
|
117
117
|
|
|
118
118
|
## 统一收尾与中断恢复
|
|
119
119
|
|
|
120
120
|
finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运行 revision、阶段、分支和证据;通过后归档旧版、发布正式文件、更新版本/索引、登记运行证据。checkpoint 只能更新当前产物所属步骤、等待状态和上下文,不能夹带下游阶段或用户确认。输出正式 path、cite、previous、version、lint、run;自检警告和待填写项要告知用户,引用用 cite,归档遵循 requirements.md,不能替用户删除。
|
|
121
121
|
|
|
122
|
-
正式文档先写 tmp
|
|
122
|
+
正式文档先写 tmp 草稿;旧 `requirement.mjs path` 入口已删除,不能通过直接覆盖正式文件绕过收尾中断保护。tech / release 分别在 T4 / L4 用 kind tech / release 收尾,使用各自的知识模板;wiki/沉淀后只更新发布或知识元信息仍可显式 reindex,但 reindex 不修复正文 hash 或旧证据。
|
|
123
123
|
|
|
124
124
|
技术方案将生成时间、对比分支、diff 概览、PRD 参考和模板来源放在文件头的 `<!-- workflow-run: … -->` 多行注释中(格式见 create-tech-md-doc,整个块在前 20 行内),不要求正文显示元信息引用块。分支校验仍读取注释中的 `对比分支:`,索引日期读取其中的 `生成时间:`;旧文档的可见元信息继续兼容。注释随正式文件一起归档并参与 hash 校验,Wiki 转换时移除;`meta.json` 仍按现有逻辑记录绑定、索引和运行,不自动接收全部注释字段。
|
|
125
125
|
|
|
@@ -129,4 +129,4 @@ finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运
|
|
|
129
129
|
node <skills>/workflow/scripts/artifact.mjs resume --id <id>
|
|
130
130
|
```
|
|
131
131
|
|
|
132
|
-
|
|
132
|
+
命令会读取当前 pending 的目标 revision 和 operationId,再通过核心入口在锁内复核;读取后若待办已被替换,旧请求会明确失败,不会误处理新事务。恢复会再次核对代码与正文,已发布的相同文件不重复升版本;原 finalize 命令重试也不会重复推进状态。恢复发现代码变化或正式文件被其他操作改动时,停下保留待办,不覆盖。需要放弃本次收尾时用 `artifact.mjs abort --id <id>`:只在文件仍是本操作原版/新版时恢复原版并清除待办;发生外部冲突则先人工核对。之后回退、重新验证/审查。临时副本保留在 tmp,不删除用户文件。
|
|
@@ -2,6 +2,26 @@
|
|
|
2
2
|
|
|
3
3
|
所有 skill 共用的项目事实,放在本 skill 目录下,**不含任何凭据**,可以提交到 git。缺失的字段一律视为空。
|
|
4
4
|
|
|
5
|
+
## 多环境安装的配置来源
|
|
6
|
+
|
|
7
|
+
用 `--copy` 同时安装 Claude、Qwen、WorkBuddy 等环境时,项目根下会有多份 `workflow/` 拷贝。配置解析顺序是:
|
|
8
|
+
|
|
9
|
+
1. `workflow-run/profile-source.json` 的显式选择;
|
|
10
|
+
2. `.agents/skills/workflow/`;
|
|
11
|
+
3. 唯一存在的其他受支持安装目录;
|
|
12
|
+
4. 多份副本的 `profile.json` 与 `profile.local.json` 完全相同时,按 `.agents` → `.claude` → `.qwen` → `.codebuddy` 固定顺序选择第一份。
|
|
13
|
+
|
|
14
|
+
副本内容不同时核心操作会返回 `PROJECT_CONFIG_AMBIGUOUS`,不会按目录扫描顺序静默任选。明确选择来源:
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
node .claude/skills/workflow/scripts/requirement.mjs config --profile-source claude
|
|
18
|
+
node .claude/skills/workflow/scripts/requirement.mjs config --profile-source qwen
|
|
19
|
+
node .claude/skills/workflow/scripts/requirement.mjs config --profile-source .qwen/skills/workflow
|
|
20
|
+
node .claude/skills/workflow/scripts/requirement.mjs config --profile-source auto
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
选择只接受目标项目内已存在的 `.agents/skills/workflow`、`.claude/skills/workflow`、`.qwen/skills/workflow`、`.codebuddy/skills/workflow`,写入可提交的 `workflow-run/profile-source.json`。`auto` 删除该文件;目录被重装删除后会报来源无效,重新选择即可。团队可提交显式选择,个人若只用另一个环境,也可以运行 `config --profile-source auto` 后重新选择自己的环境。
|
|
24
|
+
|
|
5
25
|
| 字段 | 含义 | 谁在用 |
|
|
6
26
|
|---|---|---|
|
|
7
27
|
| `main_branch` | 主分支名,diff 基线 | dev、project-review、文档类 |
|