flow-comet 1.5.0-rc.3
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/.flow-comet/rules/flow-comet-orchestration.md +13 -0
- package/.flow-comet/skills/flow-comet/GUIDANCE.md +196 -0
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -0
- package/.flow-comet/skills/flow-comet/SKILL.md +196 -0
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +19 -0
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +115 -0
- package/.flow-comet/skills/flow-comet/reference/authoring-lanes.json +33 -0
- package/.flow-comet/skills/flow-comet/reference/composition-report.md +65 -0
- package/.flow-comet/skills/flow-comet/reference/decision-points.md +64 -0
- package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +30 -0
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +169 -0
- package/.flow-comet/skills/flow-comet/reference/init-detection.md +58 -0
- package/.flow-comet/skills/flow-comet/reference/recovery.md +20 -0
- package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +661 -0
- package/.flow-comet/skills/flow-comet/reference/skill-review.md +13 -0
- package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +7 -0
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +681 -0
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +52 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +61 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +909 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-plan.mjs +2 -0
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +312 -0
- package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +136 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +7331 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +376 -0
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +230 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +99 -0
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +4017 -0
- package/.flow-comet/skills/flow-comet/scripts/task-parsing.mjs +28 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +2396 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +378 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +1263 -0
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +195 -0
- package/.flow-comet/skills/flow-comet-change/SKILL.md +29 -0
- package/.flow-comet/skills/flow-comet-compose/SKILL.md +249 -0
- package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +23 -0
- package/.flow-comet/skills/flow-comet-design/SKILL.md +161 -0
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +51 -0
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +26 -0
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +182 -0
- package/.flow-comet/skills/flow-comet-health/SKILL.md +31 -0
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +45 -0
- package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +36 -0
- package/.flow-comet/skills/flow-comet-open/SKILL.md +161 -0
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +33 -0
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +169 -0
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +27 -0
- package/.flow-comet/skills/flow-comet-review/SKILL.md +204 -0
- package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +29 -0
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +214 -0
- package/.flow-comet/skills/flow-comet-task/SKILL.md +33 -0
- package/.flow-comet/skills/flow-comet-test/SKILL.md +41 -0
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +26 -0
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +164 -0
- package/LICENSE +21 -0
- package/README.md +255 -0
- package/package.json +27 -0
- package/scripts/dsh-bridge.mjs +461 -0
- package/scripts/prepare-env.mjs +1526 -0
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
// protocol-utils.mjs: 工作流协议文件(workflow-protocol.json)的统一解析 / 受保护读取 / schema 校验模块
|
|
2
|
+
// 批次 D T01:供 workflow-state.mjs / workflow-guard.mjs / comet-hook-guard.mjs 三脚本共用,
|
|
3
|
+
// 替代各脚本内联的 protocolPath 硬编码,统一协议解析优先级、受保护读取与 fail-closed 校验。
|
|
4
|
+
// 纯 ESM(.mjs),仅依赖 node 内置模块(fs/path),零 npm 依赖。
|
|
5
|
+
//
|
|
6
|
+
// 协议路径解析优先级(resolveProtocol):
|
|
7
|
+
// 1. --protocol <path> CLI 参数(从 cliArgs 中提取;找不到该参数则忽略)
|
|
8
|
+
// 2. 环境变量 FLOW_COMET_PROTOCOL(非空时优先于默认)
|
|
9
|
+
// 3. 默认 <packageRoot>/reference/workflow-protocol.json
|
|
10
|
+
// 相对路径一律相对 runRoot 解析,返回绝对路径。
|
|
11
|
+
//
|
|
12
|
+
// readProtocolFile 复用 comet-hook-guard.mjs readWorkflowProtectedFile 的防护风格
|
|
13
|
+
// (symlink 穿越检测 + TOCTOU 快照比对 + 2MB 字节上限),返回解析后的对象,文件不存在抛错。
|
|
14
|
+
// validateProtocolSchema 为 fail-closed 校验:schemaVersion 必须为 1、nodes 必须是非空数组;
|
|
15
|
+
// 未知可选字段(writeWhitelist / taskFile)前向兼容——存在才校验类型,缺省不报错。
|
|
16
|
+
// 内置协议 reference/workflow-protocol.json 必须能通过该校验。
|
|
17
|
+
|
|
18
|
+
import { constants as fsConstants, promises as fs } from 'fs';
|
|
19
|
+
import path from 'path';
|
|
20
|
+
|
|
21
|
+
export const WORKFLOW_PROTOCOL_MAX_BYTES = 2 * 1024 * 1024;
|
|
22
|
+
|
|
23
|
+
// ---------- 受保护文件读取(复制自 comet-hook-guard.mjs,与各脚本各自内联的风格一致) ----------
|
|
24
|
+
|
|
25
|
+
function workflowPathInside(root, target) {
|
|
26
|
+
const relative = path.relative(root, target);
|
|
27
|
+
return (
|
|
28
|
+
relative === '' ||
|
|
29
|
+
(!path.isAbsolute(relative) &&
|
|
30
|
+
relative !== '..' &&
|
|
31
|
+
!relative.startsWith('..' + path.sep))
|
|
32
|
+
);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
async function inspectWorkflowProtectedPath(
|
|
36
|
+
projectRoot,
|
|
37
|
+
target,
|
|
38
|
+
label,
|
|
39
|
+
expected = 'any',
|
|
40
|
+
) {
|
|
41
|
+
const lexicalRoot = path.resolve(projectRoot);
|
|
42
|
+
const lexicalTarget = path.resolve(target);
|
|
43
|
+
if (!workflowPathInside(lexicalRoot, lexicalTarget)) {
|
|
44
|
+
throw new Error(label + ' must stay inside the project root');
|
|
45
|
+
}
|
|
46
|
+
const rootStat = await fs.lstat(lexicalRoot);
|
|
47
|
+
if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
|
|
48
|
+
throw new Error(label + ' project root must be a real directory');
|
|
49
|
+
}
|
|
50
|
+
const realRoot = await fs.realpath(lexicalRoot);
|
|
51
|
+
const relative = path.relative(lexicalRoot, lexicalTarget);
|
|
52
|
+
const segments = relative === '' ? [] : relative.split(path.sep);
|
|
53
|
+
let cursor = lexicalRoot;
|
|
54
|
+
for (let index = 0; index < segments.length; index++) {
|
|
55
|
+
cursor = path.join(cursor, segments[index]);
|
|
56
|
+
let stat;
|
|
57
|
+
try {
|
|
58
|
+
stat = await fs.lstat(cursor);
|
|
59
|
+
} catch (error) {
|
|
60
|
+
if (
|
|
61
|
+
error &&
|
|
62
|
+
typeof error === 'object' &&
|
|
63
|
+
(error.code === 'ENOENT' || error.code === 'ENOTDIR')
|
|
64
|
+
) {
|
|
65
|
+
return { target: lexicalTarget, exists: false };
|
|
66
|
+
}
|
|
67
|
+
throw error;
|
|
68
|
+
}
|
|
69
|
+
const display = path.relative(lexicalRoot, cursor).replaceAll('\\', '/');
|
|
70
|
+
if (stat.isSymbolicLink()) {
|
|
71
|
+
throw new Error(label + ' crosses a symbolic link or junction at ' + display);
|
|
72
|
+
}
|
|
73
|
+
const final = index === segments.length - 1;
|
|
74
|
+
if (!final && !stat.isDirectory()) {
|
|
75
|
+
throw new Error(label + ' ancestor ' + display + ' must be a real directory');
|
|
76
|
+
}
|
|
77
|
+
if (
|
|
78
|
+
final &&
|
|
79
|
+
((expected === 'file' && !stat.isFile()) ||
|
|
80
|
+
(expected === 'directory' && !stat.isDirectory()) ||
|
|
81
|
+
(expected === 'any' && !stat.isFile() && !stat.isDirectory()))
|
|
82
|
+
) {
|
|
83
|
+
throw new Error(label + ' must be a real ' + expected);
|
|
84
|
+
}
|
|
85
|
+
const physical = await fs.realpath(cursor);
|
|
86
|
+
if (!workflowPathInside(realRoot, physical)) {
|
|
87
|
+
throw new Error(label + ' resolves outside the project root');
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
return { target: lexicalTarget, exists: true };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function workflowFileObjectIdentity(stat) {
|
|
94
|
+
return {
|
|
95
|
+
dev: stat.dev,
|
|
96
|
+
ino: stat.ino,
|
|
97
|
+
birthtime: typeof stat.birthtimeNs === 'bigint' ? stat.birthtimeNs : stat.birthtimeMs,
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function workflowHasIdentity(value) {
|
|
102
|
+
return value !== 0 && value !== 0n && value !== '0';
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function workflowSameFileObject(left, right) {
|
|
106
|
+
const comparableDevice = workflowHasIdentity(left.dev) && workflowHasIdentity(right.dev);
|
|
107
|
+
const comparableInode = workflowHasIdentity(left.ino) && workflowHasIdentity(right.ino);
|
|
108
|
+
if (comparableDevice && left.dev !== right.dev) return false;
|
|
109
|
+
if (comparableInode && left.ino !== right.ino) return false;
|
|
110
|
+
if (comparableDevice && comparableInode) return true;
|
|
111
|
+
return left.birthtime === right.birthtime;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
function workflowSameFileStat(left, right) {
|
|
115
|
+
return (
|
|
116
|
+
workflowSameFileObject(
|
|
117
|
+
workflowFileObjectIdentity(left),
|
|
118
|
+
workflowFileObjectIdentity(right),
|
|
119
|
+
) &&
|
|
120
|
+
left.size === right.size &&
|
|
121
|
+
left.ctimeNs === right.ctimeNs
|
|
122
|
+
);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
async function readWorkflowProtectedFile(
|
|
126
|
+
projectRoot,
|
|
127
|
+
file,
|
|
128
|
+
label,
|
|
129
|
+
maxBytes,
|
|
130
|
+
hooks = {},
|
|
131
|
+
) {
|
|
132
|
+
if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
|
|
133
|
+
throw new Error(label + ' byte limit must be a positive integer');
|
|
134
|
+
}
|
|
135
|
+
const inspection = await inspectWorkflowProtectedPath(
|
|
136
|
+
projectRoot,
|
|
137
|
+
file,
|
|
138
|
+
label,
|
|
139
|
+
'file',
|
|
140
|
+
);
|
|
141
|
+
if (!inspection.exists) {
|
|
142
|
+
const error = new Error(label + ' does not exist');
|
|
143
|
+
error.code = 'ENOENT';
|
|
144
|
+
throw error;
|
|
145
|
+
}
|
|
146
|
+
const before = await fs.lstat(file, { bigint: true });
|
|
147
|
+
if (!before.isFile() || before.isSymbolicLink()) {
|
|
148
|
+
throw new Error(label + ' must be a real file');
|
|
149
|
+
}
|
|
150
|
+
if (before.size > BigInt(maxBytes)) {
|
|
151
|
+
throw new Error(label + ' exceeds ' + String(maxBytes) + ' bytes');
|
|
152
|
+
}
|
|
153
|
+
const beforeRealPath = await fs.realpath(file);
|
|
154
|
+
await hooks.afterLstat?.();
|
|
155
|
+
const flags =
|
|
156
|
+
process.platform === 'win32'
|
|
157
|
+
? fsConstants.O_RDONLY
|
|
158
|
+
: fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK;
|
|
159
|
+
let handle;
|
|
160
|
+
try {
|
|
161
|
+
handle = await fs.open(file, flags);
|
|
162
|
+
} catch (error) {
|
|
163
|
+
if (error && typeof error === 'object' && error.code === 'ELOOP') {
|
|
164
|
+
throw new Error(label + ' must be a real file');
|
|
165
|
+
}
|
|
166
|
+
throw error;
|
|
167
|
+
}
|
|
168
|
+
try {
|
|
169
|
+
const [opened, afterOpen, afterOpenRealPath] = await Promise.all([
|
|
170
|
+
handle.stat({ bigint: true }),
|
|
171
|
+
fs.lstat(file, { bigint: true }),
|
|
172
|
+
fs.realpath(file),
|
|
173
|
+
]);
|
|
174
|
+
if (
|
|
175
|
+
!opened.isFile() ||
|
|
176
|
+
!afterOpen.isFile() ||
|
|
177
|
+
afterOpen.isSymbolicLink() ||
|
|
178
|
+
afterOpenRealPath !== beforeRealPath ||
|
|
179
|
+
!workflowSameFileStat(before, opened) ||
|
|
180
|
+
!workflowSameFileStat(before, afterOpen)
|
|
181
|
+
) {
|
|
182
|
+
throw new Error(label + ' changed while opening');
|
|
183
|
+
}
|
|
184
|
+
await inspectWorkflowProtectedPath(projectRoot, file, label, 'file');
|
|
185
|
+
await hooks.afterOpen?.();
|
|
186
|
+
const chunks = [];
|
|
187
|
+
let total = 0;
|
|
188
|
+
const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1));
|
|
189
|
+
for (;;) {
|
|
190
|
+
const remaining = maxBytes + 1 - total;
|
|
191
|
+
const { bytesRead } = await handle.read(
|
|
192
|
+
buffer,
|
|
193
|
+
0,
|
|
194
|
+
Math.min(buffer.length, remaining),
|
|
195
|
+
null,
|
|
196
|
+
);
|
|
197
|
+
if (bytesRead === 0) break;
|
|
198
|
+
total += bytesRead;
|
|
199
|
+
if (total > maxBytes) {
|
|
200
|
+
throw new Error(label + ' exceeds ' + String(maxBytes) + ' bytes');
|
|
201
|
+
}
|
|
202
|
+
chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
|
|
203
|
+
}
|
|
204
|
+
await hooks.beforeFinalCheck?.();
|
|
205
|
+
const [afterHandle, afterPath, afterRealPath] = await Promise.all([
|
|
206
|
+
handle.stat({ bigint: true }),
|
|
207
|
+
fs.lstat(file, { bigint: true }),
|
|
208
|
+
fs.realpath(file),
|
|
209
|
+
]);
|
|
210
|
+
if (
|
|
211
|
+
!afterPath.isFile() ||
|
|
212
|
+
afterPath.isSymbolicLink() ||
|
|
213
|
+
afterRealPath !== beforeRealPath ||
|
|
214
|
+
!workflowSameFileStat(before, afterHandle) ||
|
|
215
|
+
!workflowSameFileStat(before, afterPath)
|
|
216
|
+
) {
|
|
217
|
+
throw new Error(label + ' changed while reading');
|
|
218
|
+
}
|
|
219
|
+
await inspectWorkflowProtectedPath(projectRoot, file, label, 'file');
|
|
220
|
+
return Buffer.concat(chunks, total);
|
|
221
|
+
} finally {
|
|
222
|
+
await handle.close();
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
// ---------- 协议路径解析 ----------
|
|
227
|
+
|
|
228
|
+
// 解析协议路径:--protocol CLI 参数 > 环境变量 FLOW_COMET_PROTOCOL > 内置默认。
|
|
229
|
+
// cliArgs 支持 "--protocol <path>" 与 "--protocol=<path>" 两种写法;找不到参数则忽略。
|
|
230
|
+
export function resolveProtocol(packageRoot, runRoot, cliArgs = []) {
|
|
231
|
+
for (let index = 0; index < cliArgs.length; index++) {
|
|
232
|
+
const arg = cliArgs[index];
|
|
233
|
+
if (arg === '--protocol') {
|
|
234
|
+
const value = cliArgs[index + 1];
|
|
235
|
+
if (typeof value !== 'string' || value === '') {
|
|
236
|
+
throw new Error('--protocol requires a path argument');
|
|
237
|
+
}
|
|
238
|
+
return path.resolve(runRoot, value);
|
|
239
|
+
}
|
|
240
|
+
if (typeof arg === 'string' && arg.startsWith('--protocol=')) {
|
|
241
|
+
const value = arg.slice('--protocol='.length);
|
|
242
|
+
if (value === '') {
|
|
243
|
+
throw new Error('--protocol requires a path argument');
|
|
244
|
+
}
|
|
245
|
+
return path.resolve(runRoot, value);
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
const envValue = process.env.FLOW_COMET_PROTOCOL;
|
|
249
|
+
if (typeof envValue === 'string' && envValue.trim() !== '') {
|
|
250
|
+
return path.resolve(runRoot, envValue);
|
|
251
|
+
}
|
|
252
|
+
return path.resolve(packageRoot, 'reference', 'workflow-protocol.json');
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
// ---------- 协议文件读取 ----------
|
|
256
|
+
|
|
257
|
+
// 受保护读取协议文件(symlink 穿越检测 + TOCTOU 快照比对 + 2MB 字节上限),
|
|
258
|
+
// 返回 JSON.parse 后的对象;文件不存在或防护校验失败时抛错(fail-closed)。
|
|
259
|
+
export async function readProtocolFile(projectRoot, protocolPath) {
|
|
260
|
+
const buffer = await readWorkflowProtectedFile(
|
|
261
|
+
projectRoot,
|
|
262
|
+
protocolPath,
|
|
263
|
+
'workflow protocol file',
|
|
264
|
+
WORKFLOW_PROTOCOL_MAX_BYTES,
|
|
265
|
+
);
|
|
266
|
+
try {
|
|
267
|
+
return JSON.parse(buffer.toString('utf8'));
|
|
268
|
+
} catch (error) {
|
|
269
|
+
throw new Error('workflow protocol file is not valid JSON: ' + error.message);
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
// ---------- schema 校验 ----------
|
|
274
|
+
|
|
275
|
+
// writeWhitelist 形状校验(validate / parse 共用):对象,值必须都是字符串数组。
|
|
276
|
+
function checkWriteWhitelistShape(writeWhitelist) {
|
|
277
|
+
if (typeof writeWhitelist !== 'object' || writeWhitelist === null || Array.isArray(writeWhitelist)) {
|
|
278
|
+
throw new Error('workflow protocol writeWhitelist must be an object');
|
|
279
|
+
}
|
|
280
|
+
for (const [nodeId, prefixes] of Object.entries(writeWhitelist)) {
|
|
281
|
+
if (!Array.isArray(prefixes) || !prefixes.every((p) => typeof p === 'string')) {
|
|
282
|
+
throw new Error(
|
|
283
|
+
'workflow protocol writeWhitelist[' + nodeId + '] must be an array of strings',
|
|
284
|
+
);
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
return writeWhitelist;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
// fail-closed schema 校验:schemaVersion 必须为 1;nodes 必须是非空数组。
|
|
291
|
+
// 未知可选字段(writeWhitelist / taskFile)前向兼容:存在才校验类型,缺省不报错。
|
|
292
|
+
export function validateProtocolSchema(protocol) {
|
|
293
|
+
if (!protocol || typeof protocol !== 'object' || Array.isArray(protocol)) {
|
|
294
|
+
throw new Error('workflow protocol must be an object');
|
|
295
|
+
}
|
|
296
|
+
if (protocol.schemaVersion !== 1) {
|
|
297
|
+
throw new Error(
|
|
298
|
+
'workflow protocol schemaVersion must be 1 (got ' +
|
|
299
|
+
JSON.stringify(protocol.schemaVersion) +
|
|
300
|
+
')',
|
|
301
|
+
);
|
|
302
|
+
}
|
|
303
|
+
if (!Array.isArray(protocol.nodes) || protocol.nodes.length === 0) {
|
|
304
|
+
throw new Error('workflow protocol nodes must be a non-empty array');
|
|
305
|
+
}
|
|
306
|
+
// 审查补充(2026-08-08):nodes 元素结构校验——空对象/缺 id 的 node 会在
|
|
307
|
+
// determineNode 等消费方崩溃,校验层应 fail-closed 提前拦截
|
|
308
|
+
for (const node of protocol.nodes) {
|
|
309
|
+
if (!node || typeof node !== 'object' || Array.isArray(node)) {
|
|
310
|
+
throw new Error('workflow protocol node must be an object');
|
|
311
|
+
}
|
|
312
|
+
if (typeof node.id !== 'string' || node.id.trim() === '') {
|
|
313
|
+
throw new Error('workflow protocol node must have a non-empty string id');
|
|
314
|
+
}
|
|
315
|
+
if (node.outputSchemas !== undefined && (!Array.isArray(node.outputSchemas) || node.outputSchemas.some((s) => typeof s !== 'string'))) {
|
|
316
|
+
throw new Error('workflow protocol node.outputSchemas must be an array of strings');
|
|
317
|
+
}
|
|
318
|
+
if (node.requiredSkillCalls !== undefined && !Array.isArray(node.requiredSkillCalls)) {
|
|
319
|
+
throw new Error('workflow protocol node.requiredSkillCalls must be an array');
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
if (Object.prototype.hasOwnProperty.call(protocol, 'writeWhitelist')) {
|
|
323
|
+
checkWriteWhitelistShape(protocol.writeWhitelist);
|
|
324
|
+
}
|
|
325
|
+
if (Object.prototype.hasOwnProperty.call(protocol, 'taskFile')) {
|
|
326
|
+
if (typeof protocol.taskFile !== 'string') {
|
|
327
|
+
throw new Error('workflow protocol taskFile must be a string');
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
return true;
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
// ---------- writeWhitelist 解析 ----------
|
|
334
|
+
|
|
335
|
+
// 解析协议可选 writeWhitelist(节点 id → 路径前缀数组)。
|
|
336
|
+
// 协议无该字段时返回 null,表示调用方使用内置缺省白名单表。
|
|
337
|
+
export function parseProtocolWriteWhitelist(protocol) {
|
|
338
|
+
if (
|
|
339
|
+
!protocol ||
|
|
340
|
+
typeof protocol !== 'object' ||
|
|
341
|
+
!Object.prototype.hasOwnProperty.call(protocol, 'writeWhitelist')
|
|
342
|
+
) {
|
|
343
|
+
return null;
|
|
344
|
+
}
|
|
345
|
+
return checkWriteWhitelistShape(protocol.writeWhitelist);
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
// 节点 → flow-kit/prompts/ 协议文件映射(单一来源——workflow-guard 的 exit 协议声明校验与
|
|
349
|
+
// workflow-state 的 M5 record 自动补声明共用;改动词表仅此一处)
|
|
350
|
+
// 注释约定:以 flow-kit/prompts/ 实文件为准(0-change.md ~ 7-integration.md,随 flow-kit 仓库同步)
|
|
351
|
+
export const NODE_PROTOCOL_FILES = {
|
|
352
|
+
open: ['0-change.md', '1-requirement.md'],
|
|
353
|
+
design: ['2-design.md'],
|
|
354
|
+
plan: ['3-task.md'],
|
|
355
|
+
execute: ['4-dev.md'],
|
|
356
|
+
'subagent-execute': ['4-dev.md'],
|
|
357
|
+
review: ['6-review.md', '5-test.md'],
|
|
358
|
+
verify: ['7-integration.md'],
|
|
359
|
+
archive: ['7-integration.md'],
|
|
360
|
+
};
|
|
361
|
+
|
|
362
|
+
// skill → flow-kit/prompts/ 协议文件映射(单一来源——M5 record 自动补声明按 skill 归属
|
|
363
|
+
// 协议文件;手动 skill-load 仍以 --prompt 的 basename 为准,不受此表影响)
|
|
364
|
+
// 与 NODE_PROTOCOL_FILES 的关系:节点级(exit 校验用)与 skill 级(M5 自动补用)两表并存;
|
|
365
|
+
// skill 级取该 skill 承载的协议文件(多节点共用的 skill 如 flow-comet-dev/integration 恒映射同一文件)
|
|
366
|
+
export const SKILL_PROTOCOL_FILES = {
|
|
367
|
+
'flow-comet-change': ['0-change.md'],
|
|
368
|
+
'flow-comet-requirement': ['1-requirement.md'],
|
|
369
|
+
'flow-comet-design': ['2-design.md'],
|
|
370
|
+
'flow-comet-ui-design': ['2a-ui-design.md'],
|
|
371
|
+
'flow-comet-task': ['3-task.md'],
|
|
372
|
+
'flow-comet-dev': ['4-dev.md'],
|
|
373
|
+
'flow-comet-test': ['5-test.md'],
|
|
374
|
+
'flow-comet-review': ['6-review.md'],
|
|
375
|
+
'flow-comet-integration': ['7-integration.md'],
|
|
376
|
+
};
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
// route-node.mjs — 共享「任务状态 → 节点」路由判定核心(单一权威实现)
|
|
2
|
+
// 本模块承载从 workflow-state.mjs determineNode 抽取的节点判定核心(含「串行 pending → execute」回流)。
|
|
3
|
+
// 两侧复用同一实现(guard 与 workflow-state 各调用 resolveNextNode),根治双实现漂移。
|
|
4
|
+
// 纯判定:resolveNextNode 无副作用、无 console 输出、无 process.exit——只读 .specs 产物与任务文件,
|
|
5
|
+
// 仅返回节点 id(或 null = 完成态);展示层(guard NEXT+SKILL 行 / workflow-state NODE+SKILL 行)
|
|
6
|
+
// 由各自调用方渲染,不并入本模块(文案逐字保留)。
|
|
7
|
+
// 接口:resolveNextNode({ runRoot, changeName, protocol, completedNodes = [] })——runRoot 显式传入,
|
|
8
|
+
// specsRoot 由 runRoot 派生为 path.join(runRoot, '.specs')(与两侧调用方各自 .specs 根语义一致)。
|
|
9
|
+
import { promises as fs } from 'fs';
|
|
10
|
+
import path from 'path';
|
|
11
|
+
import { taskBlocks, taskOpeningAttrs } from './task-parsing.mjs';
|
|
12
|
+
|
|
13
|
+
// 节点顺序 = 协议 nodes 顺序(disabled 过滤)。两侧路由排序共用同一实现(单一来源)。
|
|
14
|
+
function route(protocol) {
|
|
15
|
+
return (protocol.nodes ?? []).filter((n) => !n.disabled);
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// ---------- 节点完成判定 · 完成标志从协议 outputSchemas 推导 ----------
|
|
19
|
+
|
|
20
|
+
// 为每个节点构建"完成标志文件集":遍历节点 outputSchemas 引用的 schema 的 artifacts
|
|
21
|
+
// (schema 在协议 outputSchemas 数组中按 id 查找),paths 中 <change-id> 替换为实际
|
|
22
|
+
// changeName,得到相对 specs-root 的文件路径数组。同一 artifact 的 paths 为互斥备选(命中任一即
|
|
23
|
+
// 该 artifact 存在,如 DESIGN.md / DESIGN-lite.md);节点完成 = 标志文件集全部存在
|
|
24
|
+
// (required !== false 的 artifact 全部存在,与 workflow-guard missingRequiredArtifacts 同语义)。
|
|
25
|
+
// 返回 Map<nodeId, Array<{ id, paths }>>。
|
|
26
|
+
function buildNodeCompletionFlags(protocol, changeName) {
|
|
27
|
+
const schemaById = new Map((protocol.outputSchemas ?? []).map((schema) => [schema.id, schema]));
|
|
28
|
+
const flags = new Map();
|
|
29
|
+
for (const node of protocol.nodes ?? []) {
|
|
30
|
+
const artifacts = [];
|
|
31
|
+
for (const schemaId of node.outputSchemas ?? []) {
|
|
32
|
+
const schema = schemaById.get(schemaId);
|
|
33
|
+
for (const artifact of schema?.artifacts ?? []) {
|
|
34
|
+
if (artifact.required === false) continue; // 可选产物不是完成门控
|
|
35
|
+
// fail-fast(与 guard 侧 workflowArtifactRoot 同语义):产物根只支持 'project'/缺省 → runRoot
|
|
36
|
+
// 与 'specs-root' → <root>/.specs;下列三类 classic/native pathBase 依赖项目配置文件,该配置源
|
|
37
|
+
// 已随感知层剥离——不再有读取方,遇即显式报错(不静默兜底),提示改用 specs-root/project + 完整路径。
|
|
38
|
+
if (artifact.pathBase === 'classic-openspec-root'
|
|
39
|
+
|| artifact.pathBase === 'classic-superpowers-root'
|
|
40
|
+
|| artifact.pathBase === 'native-root') {
|
|
41
|
+
throw new Error('产物根 pathBase "' + artifact.pathBase
|
|
42
|
+
+ '" 由 guard 校验支持但状态机推导暂不支持——请改用 specs-root/project + 完整路径(如 project + openspec/changes/xxx.md)');
|
|
43
|
+
}
|
|
44
|
+
artifacts.push({
|
|
45
|
+
id: schemaId + '.' + (artifact.id ?? 'artifact'),
|
|
46
|
+
paths: (artifact.paths ?? []).map((p) => String(p).replaceAll('<change-id>', changeName)),
|
|
47
|
+
pathBase: artifact.pathBase,
|
|
48
|
+
});
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
flags.set(node.id, artifacts);
|
|
52
|
+
}
|
|
53
|
+
return flags;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function escapeRegExp(value) {
|
|
57
|
+
return String(value).replace(/[|\\{}()[\]^$+?.]/gu, '\\$&');
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// 与 workflow-guard.mjs pathPatternExists 同语义的轻量 glob 存在检查:
|
|
61
|
+
// 按路径段逐段 walk,含 `*` 的段按正则匹配(`*` → `.*`,如 *-SUMMARY.md),命中任一真实路径即存在。
|
|
62
|
+
async function pathPatternExists(root, relativePattern) {
|
|
63
|
+
const parts = String(relativePattern).split(/[\\/]+/).filter(Boolean);
|
|
64
|
+
async function walk(current, index) {
|
|
65
|
+
if (index >= parts.length) return fileExists(current);
|
|
66
|
+
const part = parts[index];
|
|
67
|
+
if (!part.includes('*')) return walk(path.join(current, part), index + 1);
|
|
68
|
+
let entries;
|
|
69
|
+
try {
|
|
70
|
+
entries = await fs.readdir(current, { withFileTypes: true });
|
|
71
|
+
} catch {
|
|
72
|
+
return false;
|
|
73
|
+
}
|
|
74
|
+
const matcher = new RegExp('^' + part.split('*').map(escapeRegExp).join('.*') + '$', 'u');
|
|
75
|
+
for (const entry of entries) {
|
|
76
|
+
if (matcher.test(entry.name) && (await walk(path.join(current, entry.name), index + 1))) {
|
|
77
|
+
return true;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
return false;
|
|
81
|
+
}
|
|
82
|
+
return walk(root, 0);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
// 节点完成判定 = 标志文件集全部存在(artifact 存在 = 其 paths 任一命中 glob)
|
|
86
|
+
// 产物推导 pathBase 感知: 产物根按 artifact.pathBase 解析——'specs-root' → specsRoot;'project'/缺省 → runRoot
|
|
87
|
+
// (与 workflow-guard.mjs 的 workflowPathBaseRoot 对齐:内置协议 10 个 artifacts 全部显式
|
|
88
|
+
// 声明 specs-root;compose 自定义协议可声明 project 根工件如 README.md)。
|
|
89
|
+
// classic/native 等其余 pathBase 暂按 specs-root 兜底(与抽取前一致,不回归——guard 侧全量感知)。
|
|
90
|
+
async function nodeFlagsComplete(nodeFlags, nodeId, specsRoot, runRoot) {
|
|
91
|
+
for (const artifact of nodeFlags.get(nodeId) ?? []) {
|
|
92
|
+
let present = false;
|
|
93
|
+
const artifactRoot = artifact.pathBase === 'specs-root' ? specsRoot : runRoot;
|
|
94
|
+
for (const pattern of artifact.paths) {
|
|
95
|
+
if (await pathPatternExists(artifactRoot, pattern)) {
|
|
96
|
+
present = true;
|
|
97
|
+
break;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
if (!present) return false;
|
|
101
|
+
}
|
|
102
|
+
return true;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
// 协议任务文件路径:协议可选 taskFile 字段(相对 .specs/<change-id>/),无声明时缺省 TASK.md。
|
|
106
|
+
// resolveNextNode 与 workflow-state next 的零进展防呆共用(同一解析,防两处漂移)。
|
|
107
|
+
function protocolTaskFilePath(protocol, changeName, specsRoot) {
|
|
108
|
+
const taskFile = typeof protocol.taskFile === 'string' && protocol.taskFile !== ''
|
|
109
|
+
? protocol.taskFile
|
|
110
|
+
: 'TASK.md';
|
|
111
|
+
return path.join(specsRoot, changeName, taskFile);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// 协议是否含 subagent-execute 委托节点(自定义协议可不含——此时 parallel 任务由 execute 直接消化)
|
|
115
|
+
function hasSubagentNode(protocol) {
|
|
116
|
+
return route(protocol).some((n) => n.id === 'subagent-execute');
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
async function fileExists(file) {
|
|
120
|
+
try { await fs.access(file); return true; } catch { return false; }
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// 判定核心(抽取自 workflow-state.mjs determineNode,行为逐字等价——重构保持锚):
|
|
124
|
+
// 输入 { runRoot, changeName, protocol, completedNodes = [] } → 输出节点 id 或 null(完成态)。
|
|
125
|
+
// 判定顺序:① completedNodes 全齐 → null;② execute 家族之前的节点产物门控;③ 无 execute 家族 →
|
|
126
|
+
// 最后节点;④ 任务状态特判(pending 且依赖满足的 parallel → subagent-execute / 串行 pending →
|
|
127
|
+
// execute / 全 done 但缺 SUMMARY → execute / 后置节点产物门控 / 全部通过 → 最后节点);⑤ 解析失败兜底 execute。
|
|
128
|
+
export async function resolveNextNode({ runRoot, changeName, protocol, completedNodes = [] }) {
|
|
129
|
+
const specsRoot = path.join(runRoot, '.specs');
|
|
130
|
+
// (实证): 全部节点已完成 → 完成态,不产出最后节点。
|
|
131
|
+
// 自定义协议无 archive 节点时,completedNodes 全齐后 next 仍会输出 NODE: <最后节点>
|
|
132
|
+
// (产物推导只返回最后节点 id)——此处(产物推导之前)判定:route(protocol) 的所有节点
|
|
133
|
+
// id 均已包含在 completedNodes 中 → 返回 null。printNext(null) 输出 "NEXT: done";
|
|
134
|
+
// status 的 currentNode = null 表示完成态。内置协议不受影响:archive exit 时 workflow-guard
|
|
135
|
+
// 清 activeChange,findActiveChange 返回 null 先于 determineNode 触发;completedNodes 含
|
|
136
|
+
// 全部 8 节点时同样返回 null,与"归档后无活跃 change"语义一致。
|
|
137
|
+
const protocolNodeIds = route(protocol).map((n) => n.id);
|
|
138
|
+
if (protocolNodeIds.length > 0 && protocolNodeIds.every((id) => completedNodes.includes(id))) {
|
|
139
|
+
return null;
|
|
140
|
+
}
|
|
141
|
+
const changeDir = path.join(specsRoot, changeName);
|
|
142
|
+
// 节点完成判定: 节点完成标志从协议 outputSchemas 推导(内置协议缺省行为与现硬编码逐字节一致)
|
|
143
|
+
const nodeFlags = buildNodeCompletionFlags(protocol, changeName);
|
|
144
|
+
// 任务文件路径:协议可选 taskFile 字段(相对 changeDir),无声明时缺省 TASK.md。
|
|
145
|
+
// 自定义协议无 taskFile 时 parallel 检测自然降级为串行(任务文件缺失 → 不路由 subagent-execute)。
|
|
146
|
+
const taskPath = protocolTaskFilePath(protocol, changeName, specsRoot);
|
|
147
|
+
|
|
148
|
+
// 节点顺序 = 协议 nodes 顺序(disabled 过滤,见 route());execute/subagent-execute 由任务状态特判。
|
|
149
|
+
// 按协议顺序拆分:execute/subagent-execute 之前的节点走产物门控(内置 = open → design → plan),
|
|
150
|
+
// 之后的节点在任务全部 done 后按序门控(内置 = review → verify → archive)。
|
|
151
|
+
const orderedNodes = route(protocol);
|
|
152
|
+
const hasExecuteFamily = orderedNodes.some((n) => n.id === 'execute' || n.id === 'subagent-execute');
|
|
153
|
+
const preExecNodes = [];
|
|
154
|
+
const postExecNodes = [];
|
|
155
|
+
let sawExecuteFamily = false;
|
|
156
|
+
for (const node of orderedNodes) {
|
|
157
|
+
if (node.id === 'execute' || node.id === 'subagent-execute') {
|
|
158
|
+
sawExecuteFamily = true;
|
|
159
|
+
continue;
|
|
160
|
+
}
|
|
161
|
+
if (sawExecuteFamily) postExecNodes.push(node);
|
|
162
|
+
else preExecNodes.push(node);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
// 前置产物门控:execute 之前的节点按序检查(内置协议 = open → design → plan)
|
|
166
|
+
for (const node of preExecNodes) {
|
|
167
|
+
if (!(await nodeFlagsComplete(nodeFlags, node.id, specsRoot, runRoot))) return node.id;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
// 协议无 execute/subagent-execute 节点:无任务状态特判,全部节点已按产物门控完成 → 当前处于最后节点
|
|
171
|
+
if (!hasExecuteFamily) {
|
|
172
|
+
return orderedNodes.length > 0 ? orderedNodes[orderedNodes.length - 1].id : 'archive';
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
// execute/subagent-execute 特判:解析任务文件 <task> 块 pending/done/parallel/depends_on。
|
|
176
|
+
// 属性解析统一走 task-parsing.mjs 的 taskOpeningAttrs——只读 <task ...> 开标签(属性序无关、
|
|
177
|
+
// 不受 <action>/<verify> 内容文本干扰),与 workflow-guard 的校验共享同一语义。
|
|
178
|
+
try {
|
|
179
|
+
const taskContent = await fs.readFile(taskPath, 'utf8');
|
|
180
|
+
const taskList = taskBlocks(taskContent);
|
|
181
|
+
const attrsList = taskList.map(taskOpeningAttrs).filter(Boolean);
|
|
182
|
+
const pending = attrsList.filter((a) => a.status === 'pending').length;
|
|
183
|
+
const done = attrsList.filter((a) => a.status === 'done').length;
|
|
184
|
+
if (pending > 0) {
|
|
185
|
+
// 多趟循环路由(循环路由形态决策 · 多趟路由架构决策记录):委托进入谓词每趟重新求值——∃ p ∈ tasks:p.parallel ∧
|
|
186
|
+
// p.status=pending ∧ deps(p) ⊆ doneIds → 路由 subagent-execute(第 N 趟,节点可多次进入)。
|
|
187
|
+
// 旧「首趟委托完成后即固定单趟」的防死循环限制移除;死循环防护改由三重保险承担:
|
|
188
|
+
// plan 出口依赖图前置拦截(guard)/ next 单趟零进展防呆(workflow-state)/ 每趟重入完整 entry 检查
|
|
189
|
+
// (guard entry R2,不绕过)。与 workflow-guard 出口 --apply 平行路由镜像同谓词。
|
|
190
|
+
// 只检测依赖已满足的 parallel 任务,避免 Wave N+1 的 parallel 任务
|
|
191
|
+
// 在 Wave N 串行任务未完成时就被路由到 subagent-execute。
|
|
192
|
+
if (hasSubagentNode(protocol)) {
|
|
193
|
+
// 收集所有 done 任务的 id(开标签属性序无关)
|
|
194
|
+
const doneIds = new Set(attrsList.filter((a) => a.status === 'done' && a.id).map((a) => a.id));
|
|
195
|
+
// 检查 pending parallel 任务中是否有依赖已满足的(开标签 parallel="true" 且 status="pending")
|
|
196
|
+
const parallelBlocks = taskList.filter((block) => {
|
|
197
|
+
const a = taskOpeningAttrs(block);
|
|
198
|
+
return a && a.parallel && a.status === 'pending';
|
|
199
|
+
});
|
|
200
|
+
const eligibleParallel = parallelBlocks.filter((block) => {
|
|
201
|
+
const depsMatch = block.match(/<depends_on>([\s\S]*?)<\/depends_on>/);
|
|
202
|
+
if (!depsMatch || !depsMatch[1].trim()) return true; // 无依赖
|
|
203
|
+
const deps = depsMatch[1].trim().split(/[,\s]+/).filter(Boolean);
|
|
204
|
+
return deps.every((d) => doneIds.has(d));
|
|
205
|
+
});
|
|
206
|
+
if (eligibleParallel.length > 0) return 'subagent-execute';
|
|
207
|
+
}
|
|
208
|
+
return 'execute';
|
|
209
|
+
}
|
|
210
|
+
// 完成判定 fail-closed(CodeRabbit 采纳):pending===0 不足为凭——缺/未知 status 的任务既非
|
|
211
|
+
// pending 也非 done,畸形块若被跳过,会在另一任务已产 SUMMARY 时把完成态误判为「任务全部
|
|
212
|
+
// done」→ 提前路由 review。attrsList.length===0(无任务块可解析)或 done !== attrsList.length
|
|
213
|
+
// (存在缺/未知 status 任务)→ 一律回 execute(不提前放行到后置节点)。
|
|
214
|
+
if (attrsList.length === 0 || done !== attrsList.length) return 'execute';
|
|
215
|
+
// 任务全部 done——execute 完成还需至少一份 SUMMARY(execute 产物门控,内置 = <change-id>/*-SUMMARY.md glob)
|
|
216
|
+
if (!(await nodeFlagsComplete(nodeFlags, 'execute', specsRoot, runRoot))) return 'execute';
|
|
217
|
+
// 后置产物门控:按协议顺序检查 execute 之后的节点(内置 = review → verify → archive)。
|
|
218
|
+
// verify 的完成标志 = flowkit.verify.v1 全部 required artifacts(TEST.md + UAT.md);自然流程中
|
|
219
|
+
// TEST.md 由 review 产出、UAT.md 由 verify 产出,故"verify 看 UAT.md"的判定语义保持不变。
|
|
220
|
+
for (const node of postExecNodes) {
|
|
221
|
+
if (!(await nodeFlagsComplete(nodeFlags, node.id, specsRoot, runRoot))) return node.id;
|
|
222
|
+
}
|
|
223
|
+
// 全部产物门控通过 → 当前处于协议最后一个节点(内置协议 = archive,与现硬编码 checks.uat → 'archive' 一致)
|
|
224
|
+
return orderedNodes.length > 0 ? orderedNodes[orderedNodes.length - 1].id : 'archive';
|
|
225
|
+
} catch {}
|
|
226
|
+
|
|
227
|
+
return 'execute';
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
export { route, protocolTaskFilePath, hasSubagentNode };
|