@rowansenne/workflow-run 0.27.0 → 0.29.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 -0
- package/README.md +97 -27
- package/bin/lib/artifact-context.mjs +2 -0
- package/bin/lib/doctor.mjs +1 -1
- package/bin/lib/install.mjs +1 -1
- package/create-release-md-doc/SKILL.md.tpl +4 -5
- package/create-tech-md-doc/SKILL.md.tpl +4 -6
- package/dev/SKILL.md.tpl +22 -14
- package/dev/agents/openai.yaml +2 -0
- package/dev/references/bug.md +6 -3
- package/dev/references/clarify.md +1 -1
- package/dev/references/delivery-template.md +2 -2
- package/dev/references/delivery.md +11 -9
- package/dev/references/implementation.md +5 -1
- package/dev/references/plan-template.md +8 -12
- package/dev/references/planning.md +8 -4
- package/dev/references/preflight.md +3 -3
- package/dev/references/requirement-template.md +32 -0
- package/dev/skill.json +10 -2
- package/nacos-config/SKILL.md.tpl +42 -0
- package/nacos-config/package.json +7 -0
- package/nacos-config/references/connection.md +47 -0
- package/nacos-config/scripts/config.mjs +288 -0
- package/nacos-config/skill.json +9 -0
- package/package.json +6 -2
- package/project-review/SKILL.md.tpl +4 -3
- package/project-review/references/reporting.md +8 -8
- package/project-review/references/review-method.md +1 -1
- package/project-review/skill.json +2 -1
- package/workflow/SKILL.md.tpl +14 -9
- package/workflow/lib/artifact-finalize.mjs +156 -0
- package/workflow/lib/artifact-model.mjs +2 -2
- package/workflow/lib/code-snapshot.mjs +55 -0
- package/workflow/lib/meta-store.mjs +4 -2
- package/workflow/lib/path-match.mjs +21 -0
- package/workflow/lib/requirements.mjs +12 -7
- package/workflow/lib/run-gates.mjs +153 -0
- package/workflow/lib/runs.mjs +58 -14
- package/workflow/lib/workspace-read.mjs +3 -1
- package/workflow/references/architecture.md +51 -3
- package/workflow/references/capabilities.md +4 -2
- package/workflow/references/execution.md +105 -0
- package/workflow/references/requirements.md +15 -13
- package/workflow/references/runs.md +16 -11
- package/workflow/references/status.md +1 -0
- package/workflow/references/templates.md +2 -2
- package/workflow/scripts/artifact.mjs +39 -0
- package/workflow/scripts/pr-desc.mjs +2 -2
- package/workflow/scripts/review-handoff.mjs +59 -0
- package/workflow/scripts/review-scope.mjs +2 -21
- package/workflow/scripts/run.mjs +6 -8
- package/workflow/scripts/template.mjs +3 -2
- package/workflow/scripts/view.mjs +1 -1
- package/workflow/skill.json +2 -1
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
// 只读 Nacos:本地配置定位、单配置获取、结构化脱敏。除登录外不发送 POST。
|
|
2
|
+
import fs from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import crypto from 'node:crypto';
|
|
5
|
+
import { fileURLToPath } from 'node:url';
|
|
6
|
+
|
|
7
|
+
const SKILL_DIR = fileURLToPath(new URL('..', import.meta.url));
|
|
8
|
+
const MAX_BYTES = 2 * 1024 * 1024;
|
|
9
|
+
export class UsageError extends Error {}
|
|
10
|
+
const fail = (s) => { throw new UsageError(s); };
|
|
11
|
+
const own = (o, k) => Object.hasOwn(o, k);
|
|
12
|
+
|
|
13
|
+
export function flatten(value, prefix = '', out = Object.create(null), seen = new Set()) {
|
|
14
|
+
if (value && typeof value === 'object' && Object.keys(value).length) {
|
|
15
|
+
if (seen.has(value)) throw new Error('不支持循环配置引用');
|
|
16
|
+
seen.add(value);
|
|
17
|
+
for (const [k, v] of Object.entries(value)) flatten(v, prefix ? `${prefix}.${k}` : k, out, seen);
|
|
18
|
+
seen.delete(value);
|
|
19
|
+
} else if (prefix) out[prefix] = value;
|
|
20
|
+
return out;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export function properties(text) {
|
|
24
|
+
const out = Object.create(null);
|
|
25
|
+
const unescape = (s) => s.replace(/\\u([\da-fA-F]{4})|\\(.)/g, (_, hex, c) => hex ? String.fromCharCode(parseInt(hex, 16)) : ({ t: '\t', n: '\n', r: '\r', f: '\f' }[c] ?? c));
|
|
26
|
+
const lines = text.replace(/\r\n?/g, '\n').split('\n');
|
|
27
|
+
for (let i = 0; i < lines.length; i++) {
|
|
28
|
+
let s = lines[i].trimStart();
|
|
29
|
+
if (!s || /^[#!]/.test(s)) continue;
|
|
30
|
+
while ((s.match(/\\+$/)?.[0].length ?? 0) % 2 === 1 && i + 1 < lines.length) s = s.slice(0, -1) + lines[++i].trimStart();
|
|
31
|
+
const m = /^((?:\\.|[^\s:=\\])*)(?:\s*[=:]\s*|\s+)?(.*)$/.exec(s);
|
|
32
|
+
if (!m) throw new Error('properties 解析失败');
|
|
33
|
+
out[unescape(m[1])] = unescape(m[2]);
|
|
34
|
+
}
|
|
35
|
+
return out;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export async function documents(text, format) {
|
|
39
|
+
try {
|
|
40
|
+
if (format === 'properties') return [properties(text)];
|
|
41
|
+
const structured = (v) => {
|
|
42
|
+
if (v !== null && typeof v !== 'object') throw new Error();
|
|
43
|
+
return flatten(v);
|
|
44
|
+
};
|
|
45
|
+
if (format === 'json') return [structured(JSON.parse(text))];
|
|
46
|
+
if (format !== 'yaml') fail('格式须为 json、yaml 或 properties');
|
|
47
|
+
let yaml;
|
|
48
|
+
try { yaml = await import('yaml'); } catch { fail('缺少 yaml 依赖:运行 npm install --prefix <skills>/nacos-config --ignore-scripts --no-package-lock'); }
|
|
49
|
+
return yaml.parseAllDocuments(text, { prettyErrors: false, logLevel: 'silent' }).map((d) => {
|
|
50
|
+
if (d.errors.length || d.warnings.length) throw new Error();
|
|
51
|
+
return structured(d.toJS({ maxAliasCount: 50 }));
|
|
52
|
+
});
|
|
53
|
+
} catch (e) {
|
|
54
|
+
if (e instanceof UsageError) throw e;
|
|
55
|
+
throw new Error(`配置 ${format} 解析失败(未输出原文)`);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export function resolveValue(value, props, env = process.env, stack = [], fromEnvironment = false) {
|
|
60
|
+
if (typeof value !== 'string') return value;
|
|
61
|
+
if (stack.length > 30) fail('连接参数占位符嵌套超过 30 层');
|
|
62
|
+
if (!fromEnvironment && /^@[\w.-]+@$/.test(value)) fail('连接参数含未解析的构建过滤变量');
|
|
63
|
+
let s = ''; let offset = 0;
|
|
64
|
+
for (let start; (start = value.indexOf('${', offset)) >= 0;) {
|
|
65
|
+
s += value.slice(offset, start);
|
|
66
|
+
let end = start + 2; let depth = 1;
|
|
67
|
+
for (; end < value.length && depth; end++) {
|
|
68
|
+
if (value.startsWith('${', end)) { depth++; end++; }
|
|
69
|
+
else if (value[end] === '}') depth--;
|
|
70
|
+
}
|
|
71
|
+
if (depth) fail('连接参数含未闭合的占位符');
|
|
72
|
+
const expr = value.slice(start + 2, end - 1);
|
|
73
|
+
const colon = expr.indexOf(':');
|
|
74
|
+
const key = colon < 0 ? expr : expr.slice(0, colon);
|
|
75
|
+
if (key.includes('${')) fail('不支持动态占位符名称');
|
|
76
|
+
if (stack.includes(key)) fail('连接参数的占位符存在循环引用');
|
|
77
|
+
const fromEnv = own(env, key);
|
|
78
|
+
const v = fromEnv ? env[key] : own(props, key) ? props[key] : colon >= 0 ? expr.slice(colon + 1) : undefined;
|
|
79
|
+
if (v === undefined) fail(`连接参数缺少变量:${key}`);
|
|
80
|
+
s += String(resolveValue(v, props, env, [...stack, key], fromEnv));
|
|
81
|
+
offset = end;
|
|
82
|
+
}
|
|
83
|
+
s += value.slice(offset);
|
|
84
|
+
if (/\$\{/.test(s)) fail('连接参数含未解析的占位符');
|
|
85
|
+
return s;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function formatOf(file, explicit) {
|
|
89
|
+
const ext = (explicit ?? path.extname(file).slice(1)).toLowerCase();
|
|
90
|
+
const format = ext === 'yml' ? 'yaml' : ext;
|
|
91
|
+
if (!['json', 'yaml', 'properties'].includes(format)) fail('无法判断配置格式,请传 --format json|yaml|properties');
|
|
92
|
+
return format;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function read(file) {
|
|
96
|
+
if (!fs.existsSync(file)) fail('配置文件不存在');
|
|
97
|
+
if (fs.statSync(file).size > MAX_BYTES) fail('配置文件超过 2 MiB');
|
|
98
|
+
return fs.readFileSync(file, 'utf8');
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function profileOf(doc) {
|
|
102
|
+
return doc['spring.config.activate.on-profile'] ?? doc['spring.profiles'];
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
export function mergeDocuments(docs, profile) {
|
|
106
|
+
const selected = profile === undefined ? [] : String(profile).split(',').map((s) => s.trim());
|
|
107
|
+
if (selected.some((s) => !/^[\w.-]+$/.test(s))) fail('profile 只支持精确名称或逗号分隔的名称列表');
|
|
108
|
+
const out = Object.create(null);
|
|
109
|
+
for (const doc of docs) {
|
|
110
|
+
const active = profileOf(doc);
|
|
111
|
+
if (active !== undefined) {
|
|
112
|
+
if (!selected.length) fail('存在 profile 条件文档,请传 --profile 明确选择');
|
|
113
|
+
const names = String(active).split(',').map((s) => s.trim());
|
|
114
|
+
if (names.some((s) => !/^[\w.-]+$/.test(s))) fail('不支持复杂 profile 表达式,请明确提供本次环境配置');
|
|
115
|
+
if (!names.some((name) => selected.includes(name))) continue;
|
|
116
|
+
}
|
|
117
|
+
Object.assign(out, doc);
|
|
118
|
+
}
|
|
119
|
+
return out;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export function localConnection(props, env = process.env) {
|
|
123
|
+
const p = 'spring.cloud.nacos.';
|
|
124
|
+
const get = (k) => {
|
|
125
|
+
const v = resolveValue(props[`${p}config.${k}`] ?? props[`${p}${k}`], props, env);
|
|
126
|
+
if (k !== 'password' && typeof v === 'string' && /@[^@\s]+@/.test(v)) fail('连接参数含未解析的构建过滤变量');
|
|
127
|
+
return v;
|
|
128
|
+
};
|
|
129
|
+
return { server_addr: get('server-addr'), namespace: get('namespace'), group: get('group'), username: get('username'), password: get('password') };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
export function serverURL(address) {
|
|
133
|
+
if (!address || typeof address !== 'string' || address.includes(',')) fail('请配置单个 Nacos server_addr 入口');
|
|
134
|
+
let u;
|
|
135
|
+
try { u = new URL(address.includes('://') ? address : `http://${address}`); } catch { fail('Nacos 地址无效'); }
|
|
136
|
+
if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password || u.search || u.hash) fail('Nacos 地址只支持无凭据、查询参数和片段的 HTTP(S) URL');
|
|
137
|
+
if (u.pathname === '/') u.pathname = '/nacos';
|
|
138
|
+
u.pathname = u.pathname.replace(/\/+$/, '');
|
|
139
|
+
return u;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
const SECRET = /password|passwd|pwd|secret|token|credential|private[_.-]?key|access[_.-]?key|api[_.-]?key|authorization|cookie/i;
|
|
143
|
+
export function maskValue(key, value) {
|
|
144
|
+
if (SECRET.test(key)) return '******';
|
|
145
|
+
if (typeof value !== 'string') return value;
|
|
146
|
+
if (/-----BEGIN [^-]*PRIVATE KEY-----/.test(value)) return '******';
|
|
147
|
+
// Oracle 的 user/password@ 不属于 scheme://userinfo@;含内嵌身份时整值隐藏。
|
|
148
|
+
if (/jdbc:oracle:(?:thin|oci):[^@\r\n]+@/i.test(value)) return '******';
|
|
149
|
+
return value.replace(/(\b[a-z][\w+.-]*:\/\/)[^\s/@]+@/gi, '$1******@')
|
|
150
|
+
.replace(/([?;&](?:password|passwd|pwd|token|access[_-]?token|secret|access[_-]?key|api[_-]?key|authorization)=)[^\s&#;]*/gi, '$1******');
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
export async function retrieve(conn, { dataId, group, namespace, apiVersion, timeout = 15 } = {}, env = process.env) {
|
|
154
|
+
const version = String(apiVersion ?? conn.api_version ?? '1');
|
|
155
|
+
if (!['1', '2', '3'].includes(version)) fail('api_version 须为 1、2 或 3');
|
|
156
|
+
if (!dataId) fail('请明确传 --data-id');
|
|
157
|
+
if (!Number.isFinite(Number(timeout)) || Number(timeout) <= 0 || Number(timeout) > 300) fail('timeout 须为 0~300 秒之间');
|
|
158
|
+
const base = serverURL(conn.server_addr);
|
|
159
|
+
const credential = (name) => {
|
|
160
|
+
const variable = conn[`${name}_env`];
|
|
161
|
+
if (variable) {
|
|
162
|
+
if (!env[variable]) fail(`缺少凭据环境变量:${variable}`);
|
|
163
|
+
return env[variable];
|
|
164
|
+
}
|
|
165
|
+
return conn[name];
|
|
166
|
+
};
|
|
167
|
+
let token = credential('token');
|
|
168
|
+
const username = token ? undefined : credential('username');
|
|
169
|
+
const password = token ? undefined : credential('password');
|
|
170
|
+
if (!token && (username || password) && !(username && password)) fail('Nacos 登录需要同时提供用户名和密码');
|
|
171
|
+
const request = async (route, params, login = false) => {
|
|
172
|
+
const url = new URL(base);
|
|
173
|
+
url.pathname += route;
|
|
174
|
+
const headers = {};
|
|
175
|
+
if (!login && token) {
|
|
176
|
+
if (version === '3') headers.accessToken = token;
|
|
177
|
+
else params.accessToken = token;
|
|
178
|
+
}
|
|
179
|
+
const body = new URLSearchParams(params);
|
|
180
|
+
if (login) headers['Content-Type'] = 'application/x-www-form-urlencoded';
|
|
181
|
+
else url.search = body.toString();
|
|
182
|
+
let res;
|
|
183
|
+
try {
|
|
184
|
+
res = await fetch(url, { method: login ? 'POST' : 'GET', headers, body: login ? body : undefined, redirect: 'error', signal: AbortSignal.timeout(Number(timeout) * 1000) });
|
|
185
|
+
} catch { throw new Error('Nacos 请求失败:网络、超时、TLS 或重定向错误(未输出凭据)'); }
|
|
186
|
+
if (!res.ok) {
|
|
187
|
+
await res.body?.cancel();
|
|
188
|
+
throw new Error(`Nacos ${login ? '登录' : '配置读取'}失败:HTTP ${res.status}(未输出错误体)`);
|
|
189
|
+
}
|
|
190
|
+
const reader = res.body.getReader();
|
|
191
|
+
const chunks = []; let size = 0;
|
|
192
|
+
try {
|
|
193
|
+
while (true) {
|
|
194
|
+
const { done, value } = await reader.read();
|
|
195
|
+
if (done) break;
|
|
196
|
+
size += value.length;
|
|
197
|
+
if (size > MAX_BYTES) { await reader.cancel(); throw new Error(); }
|
|
198
|
+
chunks.push(value);
|
|
199
|
+
}
|
|
200
|
+
} catch { throw new Error('Nacos 响应读取失败、超时或超过 2 MiB'); }
|
|
201
|
+
const text = Buffer.concat(chunks).toString('utf8');
|
|
202
|
+
if (!login && version === '1') return text;
|
|
203
|
+
let result;
|
|
204
|
+
try { result = JSON.parse(text); } catch { throw new Error('Nacos 响应不是预期 JSON(未输出原文)'); }
|
|
205
|
+
if (login) {
|
|
206
|
+
if (typeof result.accessToken !== 'string' || !result.accessToken) throw new Error('Nacos 登录响应缺少 accessToken');
|
|
207
|
+
return result.accessToken;
|
|
208
|
+
}
|
|
209
|
+
if (result.code !== 0) throw new Error('Nacos 返回业务错误(未输出错误体)');
|
|
210
|
+
if (version === '3' && (result.data?.encryptedDataKey || result.data?.success === false || (result.data?.errorCode ?? 0) !== 0)) throw new Error('Nacos 返回加密配置或客户端读取错误,无法作为明文配置使用');
|
|
211
|
+
const content = version === '3' ? result.data?.content : result.data;
|
|
212
|
+
if (typeof content !== 'string') throw new Error('Nacos 响应缺少配置内容');
|
|
213
|
+
return content;
|
|
214
|
+
};
|
|
215
|
+
if (!token && username) token = await request(version === '3' ? '/v3/auth/user/login' : '/v1/auth/login', { username, password }, true);
|
|
216
|
+
const ns = namespace ?? conn.namespace ?? '';
|
|
217
|
+
const g = group ?? conn.group ?? 'DEFAULT_GROUP';
|
|
218
|
+
const params = { dataId, [version === '3' ? 'groupName' : 'group']: g };
|
|
219
|
+
params[version === '1' ? 'tenant' : 'namespaceId'] = version === '1' && ns === 'public' ? '' : ns || (version === '1' ? '' : 'public');
|
|
220
|
+
const content = await request(version === '1' ? '/v1/cs/configs' : version === '2' ? '/v2/cs/config' : '/v3/client/cs/config', params);
|
|
221
|
+
return { source: { server: base.toString(), api_version: version, namespace: ns || 'public', group: g, data_id: dataId, read_at: new Date().toISOString(), sha256: crypto.createHash('sha256').update(content).digest('hex') }, content };
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
function args(argv) {
|
|
225
|
+
const o = { command: argv[0], files: [] };
|
|
226
|
+
const names = { '--conn': 'conn', '--data-id': 'dataId', '--group': 'group', '--namespace': 'namespace', '--api-version': 'apiVersion', '--timeout': 'timeout', '--key': 'key', '--format': 'format', '--profile': 'profile' };
|
|
227
|
+
if (!['inspect', 'get'].includes(o.command)) fail('用法:config.mjs inspect|get [--file 路径] [--conn 名称] [--data-id ID] [--key 属性]');
|
|
228
|
+
for (let i = 1; i < argv.length; i++) {
|
|
229
|
+
const k = argv[i];
|
|
230
|
+
if (k !== '--file' && !names[k]) fail('未知参数(不接受命令行凭据)');
|
|
231
|
+
const v = argv[++i];
|
|
232
|
+
if (v === undefined || v.startsWith('--')) fail(`参数 ${k} 缺少值`);
|
|
233
|
+
if (k === '--file') o.files.push(v); else o[names[k]] = v;
|
|
234
|
+
}
|
|
235
|
+
if (o.files.length && o.conn) fail('--file 与 --conn 不能同时使用');
|
|
236
|
+
return o;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
export async function main(argv, { cwd = process.cwd(), skillDir = SKILL_DIR, env = process.env } = {}) {
|
|
240
|
+
const o = args(argv);
|
|
241
|
+
const configPath = path.join(skillDir, 'config.json');
|
|
242
|
+
let config = {};
|
|
243
|
+
if (!o.files.length && fs.existsSync(configPath)) {
|
|
244
|
+
try { config = JSON.parse(read(configPath)); } catch { fail('本机 config.json 无法解析'); }
|
|
245
|
+
}
|
|
246
|
+
if (o.command === 'inspect') {
|
|
247
|
+
const files = o.files.length ? o.files : ['', 'config', 'src/main/resources'].flatMap((dir) => {
|
|
248
|
+
const p = path.join(cwd, dir);
|
|
249
|
+
return fs.existsSync(p) ? fs.readdirSync(p).sort().filter((n) => /^(application|bootstrap)(?:-[\w.-]+)?\.(ya?ml|properties)$/.test(n)).map((n) => path.join(dir, n)) : [];
|
|
250
|
+
});
|
|
251
|
+
const candidates = [];
|
|
252
|
+
for (const file of files) {
|
|
253
|
+
const docs = await documents(read(path.resolve(cwd, file)), formatOf(file));
|
|
254
|
+
docs.forEach((d, i) => candidates.push({ file, document: i + 1, profile: profileOf(d) ?? null, nacos_keys: Object.keys(d).filter((k) => k.startsWith('spring.cloud.nacos.')), config_imports: Object.entries(d).filter(([k]) => k === 'spring.config.import' || k.startsWith('spring.config.import.')).map(([, v]) => maskValue('import', String(v).split('?')[0])) }));
|
|
255
|
+
}
|
|
256
|
+
return { connections: Object.keys(config.connections ?? {}), default_connection: config.default_connection ?? null, candidates };
|
|
257
|
+
}
|
|
258
|
+
let conn; let selected;
|
|
259
|
+
if (o.files.length) {
|
|
260
|
+
const docs = [];
|
|
261
|
+
for (const file of o.files) docs.push(...await documents(read(path.resolve(cwd, file)), formatOf(file)));
|
|
262
|
+
conn = localConnection(mergeDocuments(docs, o.profile), env);
|
|
263
|
+
selected = { files: o.files, profile: o.profile ?? null };
|
|
264
|
+
} else {
|
|
265
|
+
const name = o.conn ?? config.default_connection;
|
|
266
|
+
if (!name || !own(config.connections ?? {}, name)) fail('请选择已有 --conn,或通过 --file 指定 application / bootstrap 配置');
|
|
267
|
+
conn = config.connections[name];
|
|
268
|
+
if (own(conn, 'password') || own(conn, 'token')) fail('本机连接请使用 password_env / token_env,不保存明文凭据');
|
|
269
|
+
selected = { connection: name };
|
|
270
|
+
}
|
|
271
|
+
if (!o.dataId) fail('请明确传 --data-id');
|
|
272
|
+
const format = formatOf(o.dataId, o.format);
|
|
273
|
+
const result = await retrieve(conn, o, env);
|
|
274
|
+
const docs = await documents(result.content, format);
|
|
275
|
+
if (docs.length !== 1) fail('远程多文档配置无法确定最终属性,请明确拆分或核对各文档');
|
|
276
|
+
const values = Object.create(null);
|
|
277
|
+
for (const [k, v] of Object.entries(docs[0])) if (!o.key || k === o.key || k.startsWith(`${o.key}.`)) values[k] = maskValue(k, v);
|
|
278
|
+
if (o.key && !Object.keys(values).length) fail('所选配置中未找到指定 key');
|
|
279
|
+
return { source: { ...result.source, ...selected }, values, notice: '单个远程配置快照;未计算 Spring 运行时覆盖、灰度和动态刷新。敏感字段已按名称脱敏。' };
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
if (process.argv[1] && fs.existsSync(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
|
|
283
|
+
main(process.argv.slice(2)).then((r) => console.log(JSON.stringify(r, null, 2))).catch((e) => {
|
|
284
|
+
// JSON / YAML / fetch 原始错误可能带原文或请求 URL,只输出本脚本产生的消息。
|
|
285
|
+
console.error(e instanceof UsageError || e.constructor === Error ? e.message : '配置处理失败(未输出原文)');
|
|
286
|
+
process.exitCode = e instanceof UsageError ? 2 : 1;
|
|
287
|
+
});
|
|
288
|
+
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rowansenne/workflow-run",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "项目级 Agent Skills 一键初始化:workflow / dev / project-review / code-graph / database-query / md-to-wiki /
|
|
3
|
+
"version": "0.29.0",
|
|
4
|
+
"description": "项目级 Agent Skills 一键初始化:workflow / dev / project-review / code-graph / database-query / nacos-config / md-to-wiki / 需求文档与技术上线方案生成",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent-skills",
|
|
7
7
|
"claude-code",
|
|
@@ -31,6 +31,7 @@
|
|
|
31
31
|
"create-tech-md-doc",
|
|
32
32
|
"create-release-md-doc",
|
|
33
33
|
"code-graph",
|
|
34
|
+
"nacos-config",
|
|
34
35
|
"README.md",
|
|
35
36
|
"CHANGELOG.md"
|
|
36
37
|
],
|
|
@@ -38,6 +39,9 @@
|
|
|
38
39
|
"test": "node --test \"tests/*.mjs\"",
|
|
39
40
|
"eval:triggers": "node scripts/eval-triggers.mjs"
|
|
40
41
|
},
|
|
42
|
+
"devDependencies": {
|
|
43
|
+
"yaml": "^2.8.1"
|
|
44
|
+
},
|
|
41
45
|
"publishConfig": {
|
|
42
46
|
"access": "public"
|
|
43
47
|
},
|
|
@@ -6,13 +6,14 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
|
|
|
6
6
|
# Code Review
|
|
7
7
|
|
|
8
8
|
审代码并输出有证据的发现;用户未要求修复时不改业务代码。进入每步前读取所指 reference 的对应小节,不预先加载全部方法说明。
|
|
9
|
+
配置相关结论需要远程值且已安装 nacos-config 时,按 `<skills>/nacos-config/SKILL.md` 按需只读核对并注明环境与配置来源;不可用时标明「未核对远程配置」,不能据本地默认值推断实际开关状态。
|
|
9
10
|
|
|
10
11
|
## 门禁
|
|
11
12
|
|
|
12
13
|
- 开工运行 `node <skills>/workflow/scripts/resolve.mjs status`,按 `<skills>/workflow/references/capabilities.md` 复用本轮能力快照;DocNexus 必装,不可用先修复。
|
|
13
14
|
- 审查范围以 `review-scope.mjs` 输出为准;只报本次引入的问题,范围外发现单列,不把没覆盖写成没问题。
|
|
14
15
|
- 每条结论引用真实代码与文件行号,行号由 `locate.mjs` 定位;CRITICAL / HIGH 必须复核,有条件时交独立 agent。
|
|
15
|
-
- dev 完整流程调用:执行第 1~7
|
|
16
|
+
- dev 完整流程调用:执行第 1~7 步,零发现也落盘;只返回报告草稿与结构化证据,由主 agent finalize,不修代码、不生成 delivery.md、不提交、不另开 review 运行,跳过第 8~9 步。
|
|
16
17
|
- dev 内部报告写「未询问(由 dev 交付统一处理)」,缺本轮 delivery.md 是正常时序;主 agent 交报告后等用户选修复或交付。S 快速通道仅当前会话审查。
|
|
17
18
|
- 深审大改动的分角度并行查找须用户同意;写入知识库与其他对外动作仍须授权。
|
|
18
19
|
|
|
@@ -38,7 +39,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
|
|
|
38
39
|
|
|
39
40
|
6. **复核**:必须先读 [verification.md](references/verification.md)。运行 `locate.mjs workflow-run/tmp/review/findings.json`,带相同范围;验证触发条件、防护与引入时间,排除误报,保留成立或待确认的证据。
|
|
40
41
|
|
|
41
|
-
7. **输出报告**:先读 [reporting.md 的第 7 步与 Artifact Location](references/reporting.md)。用 `resolve.mjs template project-review report.md`
|
|
42
|
+
7. **输出报告**:先读 [reporting.md 的第 7 步与 Artifact Location](references/reporting.md)。用 `resolve.mjs template project-review report.md` 取模板;正式报告按 execution.md 用 `artifact.mjs finalize --kind review` 收尾为 review.md 后完整交给用户,灵活模式在对话给 findings。
|
|
42
43
|
|
|
43
44
|
8. **沉淀到 DocNexus**:独立审查交报告后读 [reporting.md 的第 8 步](references/reporting.md)。有值得记录的才询问授权,分类用 `resolve.mjs category project-review`;沉淀结果写报告元信息并 sync。dev 内部不执行。
|
|
44
45
|
|
|
@@ -62,7 +63,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
|
|
|
62
63
|
|
|
63
64
|
## Artifact Location
|
|
64
65
|
|
|
65
|
-
正式报告按 `<skills>/workflow/references/requirements.md
|
|
66
|
+
正式报告按 `<skills>/workflow/references/requirements.md`,在目标工作分支用 `review-handoff.mjs --id <id>` 生成交接材料,报告草稿与结构化结果交 `artifact.mjs finalize --kind review` 收尾;事实用 `lint-doc.mjs <草稿> --skill project-review --facts`,错误修正后交付。具体执行读 reporting.md。
|
|
66
67
|
普通聊天的分析与草稿默认在 `workflow-run/other/`,不 bind、不建运行、不写需求 meta.json;用户明确路径优先。
|
|
67
68
|
|
|
68
69
|
## Verification
|
|
@@ -4,15 +4,15 @@
|
|
|
4
4
|
|
|
5
5
|
## 运行状态
|
|
6
6
|
|
|
7
|
-
独立运行且确定要落盘完整报告时,先确定目标分支与需求名、绑定需求,按 `<skills>/workflow/references/runs.md` 用 kind `review` 创建/恢复运行,R1~R7 对应 SKILL.md 第 1~7 步;每步完成、等待用户或受阻时保存。报告落盘、自检并交给用户后,将 R7 标 completed 并 complete,记录“已完成”和完成时间。可选沉淀、反馈与后续动作按原规则处理。灵活模式只在对话里审查时不创建运行;dev 内部调用也不另起运行,由 dev 主 agent
|
|
7
|
+
独立运行且确定要落盘完整报告时,先确定目标分支与需求名、绑定需求,按 `<skills>/workflow/references/runs.md` 用 kind `review` 创建/恢复运行,R1~R7 对应 SKILL.md 第 1~7 步;每步完成、等待用户或受阻时保存。报告落盘、自检并交给用户后,将 R7 标 completed 并 complete,记录“已完成”和完成时间。可选沉淀、反馈与后续动作按原规则处理。灵活模式只在对话里审查时不创建运行;dev 内部调用也不另起运行,由 dev 主 agent 用 finalize 把报告和证据记录到 F7/B5。正式 review 的交接快照与收尾命令见 `<skills>/workflow/references/execution.md`。
|
|
8
8
|
|
|
9
9
|
## dev 内部调用
|
|
10
10
|
|
|
11
|
-
优先由未参与本轮实现的子 agent 执行第 1~7 步;没有子 agent 时由当前会话的 dev 执行同样的步骤,报告「审查者」写当前 agent,不写成独立审查。完整流程必须落盘报告(零发现也写),不使用下文「灵活模式」免落盘;S 快速通道不落盘,不适用本节。跳过第 8~9 步,沉淀与反馈由 dev
|
|
11
|
+
优先由未参与本轮实现的子 agent 执行第 1~7 步;没有子 agent 时由当前会话的 dev 执行同样的步骤,报告「审查者」写当前 agent,不写成独立审查。完整流程必须落盘报告(零发现也写),不使用下文「灵活模式」免落盘;S 快速通道不落盘,不适用本节。跳过第 8~9 步,沉淀与反馈由 dev 交付时统一处理。只审代码、写 tmp 报告草稿和结构化结果,交回 dev 主 agent finalize;不修改业务代码、不生成 `delivery.md`、不提交。元信息写「未询问(由 dev 交付统一处理)」,不将 F8 的交付沉淀结果复制到内部审查报告;缺少本轮交付说明是正常时序,需求、已确认决定和验证结果以 dev 交接为准,旧交付说明只作历史参考。报告完成后交回主 agent,由主 agent 询问用户修复或交付。
|
|
12
12
|
|
|
13
13
|
## 第 7 步 — 输出报告(dev 完整流程的自审同样执行本步,只跳过第 8~9 步)
|
|
14
14
|
|
|
15
|
-
尚未发起沉淀询问时,报告元信息先写「未询问」。按报告模板输出(`node <skills>/workflow/scripts/resolve.mjs template project-review report.md` 取 `path
|
|
15
|
+
尚未发起沉淀询问时,报告元信息先写「未询问」。按报告模板输出(`node <skills>/workflow/scripts/resolve.mjs template project-review report.md` 取 `path`),按 `<skills>/workflow/references/execution.md`「自动审查交接」生成交接 JSON,返回报告草稿与 packet.result_schema 对应的结果;范围逐文件登记。独立 review 用本运行 finalize;dev 内部由主 agent finalize,同样验证报告仍对应当前代码、方案和验收。落盘规则见 Artifact Location。
|
|
16
16
|
|
|
17
17
|
## 第 8 步 — 沉淀到 DocNexus(需用户授权)
|
|
18
18
|
|
|
@@ -37,11 +37,11 @@
|
|
|
37
37
|
|
|
38
38
|
审查报告按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`,规则见 `<skills>/workflow/references/requirements.md`:
|
|
39
39
|
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
-
|
|
40
|
+
- 正式审查在目标分支工作区进行,绑定并创建 review 运行后,用 `review-handoff.mjs --id <id>` 固定代码快照和范围;各步保存实际进度,需求/范围变化后重新审查。其他分支的只读灵活审查仍按 diff 命令执行,不创建运行。
|
|
41
|
+
- 报告先写 tmp 草稿,另写结构化结果(findings、coverage);按 execution.md 用 `artifact.mjs finalize --kind review --packet <交接JSON> --result <结果JSON>` 收尾,输出 path / cite / previous。dev 内部只交回草稿与结果,不由子 agent 更新 meta。
|
|
42
|
+
- 正式报告同时完整交给用户,内容与落盘文件一致;独立 review 将 R7 标 completed 后 complete,dev 内部由主 agent 保存 waiting_user 等选择。
|
|
43
|
+
- 事实核对仍用 `lint-doc.mjs <草稿> --skill project-review --facts`;错误先修正,无法核实的标待确认。finalize 另校验模板、分支、代码快照与覆盖登记。
|
|
44
|
+
- previous 非空时说明旧版已归档,不能替用户删除;独立文档仓库按 requirements.md 运行 pending 后提示提交,dev 内部延后到 F8。已完成报告的沉淀/wiki 元信息更新仍用 sync。
|
|
45
45
|
|
|
46
46
|
## 终端命令
|
|
47
47
|
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
先读实体、接口、DTO、调用链,理清数据流再下结论;不要凭文件名猜内容。
|
|
15
15
|
- **查项目约定(DocNexus)**:先运行 `node <skills>/workflow/scripts/knowledge.mjs project-review --match <模块名 / 业务名词> --query "<一句话:改动涉及的模块与业务>"`,看以往审查沉淀的反复问题和开发约定(`--query` 在这些分类内按正文 recall),找相关的编码约定、历史决策与已知坑,作为审查依据并在报告中引用 `workflow-run/docnexus/library/<path>`。审查过程中**不写入** DocNexus(写入见第 8 步)。
|
|
16
16
|
- **同分支已有产物**:运行 `node <skills>/workflow/scripts/artifacts.mjs --branch <dev分支>`(单文件 / 未提交改动用当前分支,省略 `--branch`),看输出的 `latest`:
|
|
17
|
-
- `latest.plan`
|
|
17
|
+
- `latest.requirement` 存在 → 读取目标、范围、AC 验收标准与已确认决定,作为需求对照依据;dev 内部审查以 packet.requirement_document 指向的版本为准,context.facts 只作摘要。`latest.plan` / `latest.tech` 提供改动设计、接口 / 数据 / 配置变更。第 3 步审 diff 时区分漏实现和未经需求确认的扩展:验收项漏实现按 HIGH,其余 MEDIUM;未提及的接口 / 表结构 / 配置 / 依赖变更列出核实。旧需求无独立文档时可参考旧方案中的需求内容并标注来源,不自动补造需求文档。只对照能在 diff 核实的项,不推测业务语义。
|
|
18
18
|
- `latest.delivery` 存在(dev 的交付说明)→ 其中「已确认的决定」并入需求对照的依据;「配置清单」「SQL 脚本」和 diff 对照,diff 里有而交付说明漏列的配置 key / DDL 记为 MEDIUM(上线时会被漏掉)。
|
|
19
19
|
- `latest.review` 存在 → 这是**复审**:读上次报告的问题表,并用 `git log --oneline --since=<上次报告日期> <dev分支>` 看之后改了什么。本次报告对上次的每条问题标「已修复 / 仍存在 / 不再适用」(「已修复」要看到对应改动),本次新发现的标「新增」。
|
|
20
20
|
- **涉及数据库**:diff 里有 SQL、Mapper、实体或 DDL 时,按 `<skills>/workflow/references/tables.md` 运行 `node <skills>/workflow/scripts/tables.mjs --diff <基线>...<dev>`(未提交改动用 `--base <基线>`)找出涉及的表;按本轮数据库通道用 `query.mjs --schema --tables <表> --indexes` 只读拉取实际字段、索引与估算行数,作为第 4、6 步判断索引支撑、字段存在与类型、DDL 锁表与滚动发布兼容的依据。查不了库时注明「未与实际库核对」写进「未覆盖与待确认」,这类发现不升到 HIGH 以上,除非 diff 本身就能证明。
|
package/workflow/SKILL.md.tpl
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: workflow
|
|
3
|
-
description: "Entry point for
|
|
3
|
+
description: "Entry point for project workflow commands: /workflow, project profile, integration status, PR/MR descriptions, local reports, requirement document views and templates. Routes to dev only when the user explicitly invokes /dev or $dev, requests the dev/full development workflow, or resumes an authorized dev run. Ordinary analysis, code edits, bug fixes, tests, commits and pushes do not start dev or the full workflow. Other independently requested skills (review, database, Nacos, code graph, docs, wiki) retain their own entry rules. Triggers: skills 配好了吗 / 项目画像 / workflow status / 写 PR 描述 / 工作流效果怎么样 / workflow report / 看看项目文档 / workflow view / 改模板 / workflow template."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Workflow
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
**先判入口**:普通分析、代码修改、测试与 Git 操作不自动启动 dev,也不因本 skill 被加载而进行流程开工检查;直接处理用户当前任务。只有用户实际调用 dev、明确要求使用完整开发工作流,或要求恢复已授权的 dev 运行时,才路由到 dev。
|
|
9
|
+
|
|
10
|
+
**工作流开工能力**:进入本 skill 的状态 / 画像 / 文档等具体功能后,运行 `node <skills>/workflow/scripts/resolve.mjs status`,按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板;同一项目链路复用已有快照,失败统一按该规则处理。
|
|
9
11
|
|
|
10
12
|
本项目个人开发工作流的入口:决定由哪个 skill 处理请求,维护所有 skill 共用的**项目画像**,并统一**增强能力探测**。本 skill 自身不写业务代码。
|
|
11
13
|
|
|
@@ -18,17 +20,19 @@ description: "Entry point for this project's dev workflow skills: routes a reque
|
|
|
18
20
|
/workflow profile # 填写或更新项目画像
|
|
19
21
|
/workflow report # 本地效果报告(审查发现与修复率、需求澄清、沉淀与复用、各分支链路)
|
|
20
22
|
/workflow view # 项目文档视图:按需求浏览方案、交付、审查、技术 / 上线方案(本地静态页面)
|
|
21
|
-
/workflow template [<模板>] [怎么改] # 修改 / 创建文档模板:tech、release、plan、delivery、review、checklist
|
|
23
|
+
/workflow template [<模板>] [怎么改] # 修改 / 创建文档模板:requirement、tech、release、plan、delivery、review、checklist
|
|
22
24
|
```
|
|
23
25
|
|
|
24
26
|
## 能力地图(路由)
|
|
25
27
|
|
|
26
28
|
| 用户意图 | 交给 | 备注 |
|
|
27
29
|
|---|---|---|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
+
| `/dev` / `$dev`,或明确要求使用 dev / 完整开发流程 | `dev` | 用户选择功能开发流程 |
|
|
31
|
+
| `/dev --bug`,或明确要求使用 dev 缺陷修复流程 | `dev --bug` | 用户选择修复流程 |
|
|
32
|
+
| 普通分析、改代码、修 bug、重构、测试、提交 / 推送 | 当前会话直接处理 | 不自动进入 dev,不创建需求或运行 |
|
|
30
33
|
| 审代码、审分支、合并前检查 | `project-review` | |
|
|
31
34
|
| 查库、跑 SQL、核对数据 | `database-query` | 只读优先 |
|
|
35
|
+
| 读 Nacos 远程配置、查参数或开关 | `nacos-config` | 按需只读,先确定环境与 Data ID |
|
|
32
36
|
| 影响面、谁调用了、从哪些入口进来、topic 谁发谁收、定时任务、表在哪些 SQL 里 | `code-graph` | 需 CodeGraph 索引;`mq` / `jobs` / `tables` 不需要 |
|
|
33
37
|
| 根据分支 diff 出技术方案 | `create-tech-md-doc` | 可带 `--prd` |
|
|
34
38
|
| 根据分支 diff 出上线方案 | `create-release-md-doc` | 可带 `--tech` 复用技术方案 |
|
|
@@ -40,12 +44,12 @@ description: "Entry point for this project's dev workflow skills: routes a reque
|
|
|
40
44
|
| 改技术方案 / 上线方案 / 交付说明 / 审查报告的模板,按样例建模板 | `/workflow template` | 草稿 → 校验与影响 → 用户确认后写入 DocNexus(知识库是模板唯一来源) |
|
|
41
45
|
| 记住 / 查找项目决策与约定 | DocNexus(入口 skill `docnexus`) | 需已接入;写入必须用户授权 |
|
|
42
46
|
|
|
43
|
-
|
|
47
|
+
先遵守显式触发边界,不能把「帮我实现」「修这个 bug」「代码提交」「从头到尾处理」推断为启动 dev。用户明确要求独立能力时按对应 skill 执行,不必先输出这张表;直接要求提交代码时执行所需 Git 检查与提交,不先生成 PR 描述或补工作流文档。目标 skill 没安装时给出 `npx @rowansenne/workflow-run --skills <名称>` 补装命令,不假装执行。只有明确要求完整开发工作流时才按下面的完整链路逐段推进;用户只给出普通多步任务时直接处理,不套入 dev。已进入工作流时可用 `node <skills>/workflow/scripts/artifacts.mjs [--branch <分支>]` 读取进度;旧运行、绑定和 next 建议都不构成启动或恢复授权。
|
|
44
48
|
|
|
45
49
|
### 完整链路(从需求到上线)
|
|
46
50
|
|
|
47
51
|
```
|
|
48
|
-
dev(确定工作分支 → 定需求名 →
|
|
52
|
+
dev(确定工作分支 → 定需求名 → 理解与澄清 → 需求文档 → 方案 → 实现 → 测试 → 优先独立子 agent 审查并落盘报告,无则在当前会话自查 → 用户选择修复或交付)
|
|
49
53
|
↳ 修复:实现 → 验证 → 复审(无子 agent 时当前会话)→ 再次选择;交付:完整流程生成 delivery.md,S 快速通道只在对话交付、不落盘
|
|
50
54
|
→ create-tech-md-doc(M / L 规模)
|
|
51
55
|
→ md-to-wiki(发布技术方案,可选)
|
|
@@ -54,7 +58,7 @@ dev(确定工作分支 → 定需求名 → 理解需求 → 方案 → 实现
|
|
|
54
58
|
→ DocNexus 沉淀(可选,需授权)
|
|
55
59
|
```
|
|
56
60
|
|
|
57
|
-
|
|
61
|
+
用户明确要求开始完整链路后,才进入 dev 的 Step 0 确定本次工作分支,再运行 `node <skills>/workflow/scripts/requirement.mjs which` 确认需求名(见 `references/requirements.md`)。入口只转交用户明确给出或确认的名字,不把切换前从旧分支自动读到的名字当成用户已确认的需求名。**这里只问、不 bind**,等第一次真的要落盘产物时再由对应 skill `bind`。这样从入口进来也可以走 S 快速通道,不会提前创建需求目录和 `meta.json`。
|
|
58
62
|
|
|
59
63
|
提交、推送、发布 wiki、写入 DocNexus 都是对外动作,每一步都要用户明确同意。
|
|
60
64
|
|
|
@@ -69,6 +73,7 @@ dev(确定工作分支 → 定需求名 → 理解需求 → 方案 → 实现
|
|
|
69
73
|
| `references/docnexus.md` | 写入 DocNexus 的分类(`resolve.mjs category`)、按分类参考知识库(`knowledge.mjs`) |
|
|
70
74
|
| `references/capabilities.md` | 开工快照、必装组件门槛、可选增强通道与统一失败处理 |
|
|
71
75
|
| `references/status.md` | `/workflow status` 的输出格式 |
|
|
76
|
+
| `references/execution.md` | 关键阶段门禁、执行前代码快照、自动审查交接、统一产物收尾与中断恢复 |
|
|
72
77
|
| `references/runs.md` | 完整流程在 meta.json 中的运行状态、步骤完成标记、保存与恢复、运行完成时间 |
|
|
73
78
|
| `references/requirements.md` | 产物按需求归档(`workflow-run/docs/requirements/<需求名>/<项目名>/`):什么时候问需求名、`requirement.mjs` 绑定分支与给出落盘路径、`meta.json` |
|
|
74
79
|
| `references/tables.md` | 确定改动涉及哪些表(`tables.mjs`)、只读拉取实际表结构 / 索引 / 行数核对(`query.mjs --schema --indexes`),没有库连接时怎么退回 |
|
|
@@ -86,7 +91,7 @@ dev(确定工作分支 → 定需求名 → 理解需求 → 方案 → 实现
|
|
|
86
91
|
- 本 skill 只路由和维护 `profile.json`,不写业务代码;具体工作交给对应 skill,并遵守该 skill 的规则。
|
|
87
92
|
- `profile.json` 只记录项目事实(含 `toolchain` 开发环境配置:JDK / Maven / Node 的路径),**不写密码、token、内网凭据**;路径里的变量在 `env_vars` 里声明。
|
|
88
93
|
- 写 `toolchain` 前先用 `resolve.mjs env --check` 核对路径在本机存在;本机对不上、又只是个人差异的,写进个人的 `profile.local.json`(覆盖 `profile.json`),不要改团队那份。
|
|
89
|
-
-
|
|
94
|
+
- 独立 skill 按自身入口执行;dev 必须先有显式流程授权。普通任务不加载 dev 的开工、需求归档或运行命令,也不为提交代码重启或补齐流程。
|
|
90
95
|
|
|
91
96
|
## 终端命令
|
|
92
97
|
|