carlos-flow 2.13.0 → 2.14.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +27 -2
- package/CHANGELOG.md +26 -0
- package/README.en.md +40 -2
- package/README.md +39 -3
- package/README.zh.md +39 -3
- package/TRIGGER_GUIDE.md +3 -3
- package/bridge/mcp-bridge.js +106 -6
- package/client/carlos.js +187 -4
- package/ghost.json +19 -559
- package/main.js +267 -0
- package/package.json +12 -7
- package/scripts/check-stubs.mjs +1 -1
- package/scripts/check-templates.mjs +42 -3
- package/scripts/full-audit.mjs +66 -6
- package/scripts/lang-audit.mjs +7 -1
- package/scripts/mutation-check.mjs +74 -7
- package/src/dispatch.js +204 -17
- package/src/index.js +208 -74
- package/src/mcp-stdio.mjs +139 -0
- package/src/protocol.js +182 -1
- package/src/state.js +36 -4
package/src/protocol.js
CHANGED
|
@@ -4,7 +4,10 @@
|
|
|
4
4
|
// 状态字段从 defaultState() 生成,而不是手写常量 ——
|
|
5
5
|
// 手写副本会漂移(历史上就漏过 claimed / claimed_role / activation_* 等 9 个字段),
|
|
6
6
|
// 而协议是 Agent 运行时读取的权威依据,漂移会让 Agent 按错误的字段名做决策。
|
|
7
|
-
// 代价:protocol.js 依赖 state.js
|
|
7
|
+
// 代价:protocol.js 依赖 state.js(纯数据模块,无副作用,无循环依赖),
|
|
8
|
+
// 并依赖 node:fs / node:path 读取项目级敏感规则配置(见文件末尾)。
|
|
9
|
+
import fs from "node:fs";
|
|
10
|
+
import path from "node:path";
|
|
8
11
|
import { defaultState } from "./state.js";
|
|
9
12
|
|
|
10
13
|
export const GUIDE_MODE = { ROSTER: "主agent(Orchestrator),开发(executor+developer),测试(executor+tester),审核(auditor+reviewer)", TALKING_POINTS: ["一次只说一件事", "术语给类比", "给选择题不抛开放式问题", "复述意图", "明示能力边界"], REPORT_TEMPLATE: "【在做什么】/【已经完成】/【要你选】/【还有什么风险】" };
|
|
@@ -71,6 +74,168 @@ const SENSITIVE_EXTENSIONS = new Set([
|
|
|
71
74
|
".kdbx", ".kdb", ".gpg", ".asc", ".crt", ".cer", ".der",
|
|
72
75
|
]);
|
|
73
76
|
|
|
77
|
+
// ---- 项目级敏感路径扩展(只能追加,不能缩减)-------------------------------
|
|
78
|
+
//
|
|
79
|
+
// 为什么需要:内置名单(.env / 私钥 / 锁文件 / migrations 目录…)是**安全基线**,
|
|
80
|
+
// 但每个项目的敏感面并不相同 —— 有的私有证书目录叫 `secret_material/`,
|
|
81
|
+
// 有的对账账本放在 `billing/ledger/`。过去这些只能靠人肉提醒,
|
|
82
|
+
// 现在允许项目在仓库根放一个 `.carlos.json` 追加自己的规则:
|
|
83
|
+
//
|
|
84
|
+
// { "sensitive": { "names": ["pay_api_key.txt"], "segments": ["ledger"],
|
|
85
|
+
// "extensions": [".vault"], "prefixes": ["billing/ledger/"] } }
|
|
86
|
+
//
|
|
87
|
+
// 红线(AGENTS.md 第 1 条「门禁只许收紧,不许放宽」):
|
|
88
|
+
// · 只能**追加**:本模块不提供任何删减 / 豁免 / 否定语法;
|
|
89
|
+
// · 以 `!` 或 `-` 开头的条目一律忽略并写 stderr —— 防止有人用
|
|
90
|
+
// `"!package.json"` 试图把内置基线里的项放出去;
|
|
91
|
+
// · 配置读不到 / 解析失败 → 保持内置基线(不会因为配置坏了就放宽门禁)。
|
|
92
|
+
const PROJECT_CONFIG_FILE = ".carlos.json";
|
|
93
|
+
const MAX_CONFIG_WALK = 12; // 向上找配置的最大层数,防止符号链接成环
|
|
94
|
+
|
|
95
|
+
const EXTRA_SENSITIVE = {
|
|
96
|
+
names: new Set(),
|
|
97
|
+
segments: new Set(),
|
|
98
|
+
extensions: new Set(),
|
|
99
|
+
prefixes: [],
|
|
100
|
+
};
|
|
101
|
+
let extraConfigKey = "";
|
|
102
|
+
let extraConfigFile = "";
|
|
103
|
+
|
|
104
|
+
const normalizeRule = (v) => String(v == null ? "" : v).trim().replace(/\\/g, "/").toLowerCase();
|
|
105
|
+
|
|
106
|
+
function isNegated(rule) {
|
|
107
|
+
return rule.startsWith("!") || rule.startsWith("-");
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
function addRules(list, target, kind) {
|
|
111
|
+
let added = 0;
|
|
112
|
+
let ignored = 0;
|
|
113
|
+
for (const raw of Array.isArray(list) ? list : []) {
|
|
114
|
+
const n = normalizeRule(raw);
|
|
115
|
+
if (!n) continue;
|
|
116
|
+
if (isNegated(n)) {
|
|
117
|
+
// 不允许「取消敏感」语法:只提示,不生效(门禁只许收紧)
|
|
118
|
+
ignored++;
|
|
119
|
+
try {
|
|
120
|
+
process.stderr.write(`[carlos-flow] 已忽略否定式敏感规则(不允许放宽门禁):${raw}\n`);
|
|
121
|
+
} catch { /* stderr 不可写时静默 */ }
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
if (kind === "extension") {
|
|
125
|
+
const ext = n.startsWith(".") ? n : "." + n;
|
|
126
|
+
if (!target.has(ext)) { target.add(ext); added++; }
|
|
127
|
+
} else if (kind === "prefix") {
|
|
128
|
+
const p = n.endsWith("/") ? n : n + "/";
|
|
129
|
+
if (!target.includes(p)) { target.push(p); added++; }
|
|
130
|
+
} else if (!target.has(n)) {
|
|
131
|
+
target.add(n);
|
|
132
|
+
added++;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
return { added, ignored };
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** 清空项目级扩展,回到内置基线(测试与「换项目」场景用)。 */
|
|
139
|
+
export function resetSensitiveRules() {
|
|
140
|
+
EXTRA_SENSITIVE.names.clear();
|
|
141
|
+
EXTRA_SENSITIVE.segments.clear();
|
|
142
|
+
EXTRA_SENSITIVE.extensions.clear();
|
|
143
|
+
EXTRA_SENSITIVE.prefixes.length = 0;
|
|
144
|
+
extraConfigKey = "";
|
|
145
|
+
extraConfigFile = "";
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* 追加一份项目级敏感规则(**只增不减**)。
|
|
150
|
+
* 接受 `.carlos.json` 的整份内容(读 `sensitive` 键),也接受直接给出的规则对象。
|
|
151
|
+
* 返回实际生效的条数与被忽略的否定式条数,便于 status / 测试断言「真的加上了」。
|
|
152
|
+
*/
|
|
153
|
+
export function addProjectSensitiveRules(cfg) {
|
|
154
|
+
const root = cfg && typeof cfg === "object" && !Array.isArray(cfg) ? cfg : {};
|
|
155
|
+
const s = root.sensitive && typeof root.sensitive === "object" && !Array.isArray(root.sensitive)
|
|
156
|
+
? root.sensitive
|
|
157
|
+
: root;
|
|
158
|
+
const out = { names: 0, segments: 0, extensions: 0, prefixes: 0, ignored: 0 };
|
|
159
|
+
const n = addRules(s.names, EXTRA_SENSITIVE.names, "name");
|
|
160
|
+
out.names = n.added; out.ignored += n.ignored;
|
|
161
|
+
const sg = addRules(s.segments, EXTRA_SENSITIVE.segments, "segment");
|
|
162
|
+
out.segments = sg.added; out.ignored += sg.ignored;
|
|
163
|
+
const ex = addRules(s.extensions, EXTRA_SENSITIVE.extensions, "extension");
|
|
164
|
+
out.extensions = ex.added; out.ignored += ex.ignored;
|
|
165
|
+
const px = addRules(s.prefixes, EXTRA_SENSITIVE.prefixes, "prefix");
|
|
166
|
+
out.prefixes = px.added; out.ignored += px.ignored;
|
|
167
|
+
return out;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** 当前生效的敏感规则快照(内置基线 + 项目扩展),用于诊断与测试。 */
|
|
171
|
+
export function sensitiveRulesSnapshot() {
|
|
172
|
+
return {
|
|
173
|
+
builtin: {
|
|
174
|
+
names: SENSITIVE_NAMES.size,
|
|
175
|
+
segments: SENSITIVE_SEGMENTS.size,
|
|
176
|
+
extensions: SENSITIVE_EXTENSIONS.size,
|
|
177
|
+
},
|
|
178
|
+
extra: {
|
|
179
|
+
names: Array.from(EXTRA_SENSITIVE.names).sort(),
|
|
180
|
+
segments: Array.from(EXTRA_SENSITIVE.segments).sort(),
|
|
181
|
+
extensions: Array.from(EXTRA_SENSITIVE.extensions).sort(),
|
|
182
|
+
prefixes: EXTRA_SENSITIVE.prefixes.slice().sort(),
|
|
183
|
+
},
|
|
184
|
+
configFile: extraConfigFile || null,
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* 从 startDir 逐级向上找 `.carlos.json`,加载其中的 `sensitive` 规则。
|
|
190
|
+
*
|
|
191
|
+
* 缓存:按「文件路径 + mtime + size」判定是否重复加载 —— 每次工具调用都会走一遍,
|
|
192
|
+
* 不做缓存的话每个请求都要重新读盘解析。
|
|
193
|
+
* 找不到配置时**清空扩展**(回到内置基线),避免上一个项目追加的规则污染本项目。
|
|
194
|
+
*/
|
|
195
|
+
export function loadProjectSensitiveConfig(startDir) {
|
|
196
|
+
const start = typeof startDir === "string" && startDir ? path.resolve(startDir) : process.cwd();
|
|
197
|
+
let dir = start;
|
|
198
|
+
for (let i = 0; i < MAX_CONFIG_WALK; i++) {
|
|
199
|
+
const file = path.join(dir, PROJECT_CONFIG_FILE);
|
|
200
|
+
try {
|
|
201
|
+
const st = fs.statSync(file);
|
|
202
|
+
const key = file + "|" + st.mtimeMs + "|" + st.size;
|
|
203
|
+
if (key === extraConfigKey) {
|
|
204
|
+
return { loaded: extraConfigFile === file, file, cached: true };
|
|
205
|
+
}
|
|
206
|
+
let parsed = null;
|
|
207
|
+
let parseError = null;
|
|
208
|
+
try {
|
|
209
|
+
parsed = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
210
|
+
} catch (e) {
|
|
211
|
+
parseError = e && e.message ? e.message : String(e);
|
|
212
|
+
}
|
|
213
|
+
resetSensitiveRules();
|
|
214
|
+
if (parseError) {
|
|
215
|
+
// 配置坏了 → 保持内置基线,绝不因此放宽门禁
|
|
216
|
+
try {
|
|
217
|
+
process.stderr.write(`[carlos-flow] .carlos.json 解析失败,已退回内置敏感基线:${parseError}\n`);
|
|
218
|
+
} catch { /* ignore */ }
|
|
219
|
+
extraConfigKey = key;
|
|
220
|
+
return { loaded: false, file, error: parseError };
|
|
221
|
+
}
|
|
222
|
+
const applied = addProjectSensitiveRules(parsed);
|
|
223
|
+
extraConfigKey = key;
|
|
224
|
+
extraConfigFile = file;
|
|
225
|
+
return { loaded: true, file, applied };
|
|
226
|
+
} catch (e) {
|
|
227
|
+
if (!e || e.code !== "ENOENT") {
|
|
228
|
+
// 权限等其它错误:保持当前规则继续向上找
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
const parent = path.dirname(dir);
|
|
232
|
+
if (parent === dir) break;
|
|
233
|
+
dir = parent;
|
|
234
|
+
}
|
|
235
|
+
if (extraConfigKey) resetSensitiveRules();
|
|
236
|
+
return { loaded: false, file: null };
|
|
237
|
+
}
|
|
238
|
+
|
|
74
239
|
export function isSensitive(rel) {
|
|
75
240
|
if (typeof rel !== "string" || rel.length === 0) return false;
|
|
76
241
|
const normalized = rel.replace(/\\/g, "/").toLowerCase();
|
|
@@ -85,6 +250,22 @@ export function isSensitive(rel) {
|
|
|
85
250
|
for (const ext of SENSITIVE_EXTENSIONS) {
|
|
86
251
|
if (base.endsWith(ext)) return true;
|
|
87
252
|
}
|
|
253
|
+
|
|
254
|
+
// 项目级扩展(只能追加;为空时零开销)
|
|
255
|
+
if (EXTRA_SENSITIVE.names.size && EXTRA_SENSITIVE.names.has(base)) return true;
|
|
256
|
+
if (EXTRA_SENSITIVE.segments.size) {
|
|
257
|
+
for (const seg of segments.slice(0, -1)) {
|
|
258
|
+
if (EXTRA_SENSITIVE.segments.has(seg)) return true;
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
if (EXTRA_SENSITIVE.extensions.size) {
|
|
262
|
+
for (const ext of EXTRA_SENSITIVE.extensions) {
|
|
263
|
+
if (base.endsWith(ext)) return true;
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
for (const prefix of EXTRA_SENSITIVE.prefixes) {
|
|
267
|
+
if (normalized === prefix.slice(0, -1) || normalized.startsWith(prefix)) return true;
|
|
268
|
+
}
|
|
88
269
|
return false;
|
|
89
270
|
}
|
|
90
271
|
|
package/src/state.js
CHANGED
|
@@ -307,6 +307,7 @@ export function withStateLock(sid, fn, opts = {}) {
|
|
|
307
307
|
const staleMs = Number(opts.staleMs) || 30000;
|
|
308
308
|
const deadline = Date.now() + timeoutMs;
|
|
309
309
|
let acquired = false;
|
|
310
|
+
let attempt = 0;
|
|
310
311
|
|
|
311
312
|
for (;;) {
|
|
312
313
|
try {
|
|
@@ -314,14 +315,34 @@ export function withStateLock(sid, fn, opts = {}) {
|
|
|
314
315
|
// wx = O_CREAT|O_EXCL,文件已存在则抛 EEXIST —— 原子排他
|
|
315
316
|
const fd = fs.openSync(lockFile, "wx");
|
|
316
317
|
fs.closeSync(fd);
|
|
318
|
+
// 把持有者 pid 写进锁文件:**排他性仍完全由 O_CREAT|O_EXCL 保证**,
|
|
319
|
+
// 写内容只发生在拿到锁之后,用途有两个:
|
|
320
|
+
// ① 诊断 —— 锁超时时能说清「是哪个进程占着」;
|
|
321
|
+
// ② 即时回收 —— 持有者崩了(ESRCH)可以立刻回收,不必干等满 staleMs。
|
|
322
|
+
try { fs.writeFileSync(lockFile, String(process.pid), "utf8"); } catch { /* 内容非必需 */ }
|
|
317
323
|
acquired = true;
|
|
318
324
|
break;
|
|
319
325
|
} catch (e) {
|
|
320
326
|
if (e.code !== "EEXIST") throw e;
|
|
321
|
-
// 陈旧锁(持有者已崩溃)→
|
|
327
|
+
// 陈旧锁(持有者已崩溃)→ 回收。两道判定:
|
|
328
|
+
// ① 锁文件里记录的 pid 已不是活进程(ESRCH)→ 立即回收;
|
|
329
|
+
// ② 老版本锁文件没有 pid,或 pid 不可解析 → 只能按 mtime 超过 staleMs 判陈旧。
|
|
330
|
+
// EPERM 表示「进程存在但无权发信号」→ 按活着处理,绝不误删别人的锁。
|
|
322
331
|
try {
|
|
323
332
|
const st = fs.statSync(lockFile);
|
|
324
|
-
|
|
333
|
+
let holderDead = false;
|
|
334
|
+
let holderPid = 0;
|
|
335
|
+
try {
|
|
336
|
+
holderPid = parseInt(fs.readFileSync(lockFile, "utf8").trim(), 10);
|
|
337
|
+
if (Number.isInteger(holderPid) && holderPid > 0 && holderPid !== process.pid) {
|
|
338
|
+
try {
|
|
339
|
+
process.kill(holderPid, 0);
|
|
340
|
+
} catch (err) {
|
|
341
|
+
if (err && err.code === "ESRCH") holderDead = true;
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
} catch { /* 内容读不到:按时间判定 */ }
|
|
345
|
+
if (holderDead || Date.now() - st.mtimeMs > staleMs) {
|
|
325
346
|
fs.unlinkSync(lockFile);
|
|
326
347
|
continue;
|
|
327
348
|
}
|
|
@@ -330,9 +351,20 @@ export function withStateLock(sid, fn, opts = {}) {
|
|
|
330
351
|
}
|
|
331
352
|
if (Date.now() > deadline) {
|
|
332
353
|
// 拿不到锁:fail-closed —— 宁可报错也不要在无锁下写状态
|
|
333
|
-
|
|
354
|
+
let holder = "";
|
|
355
|
+
try {
|
|
356
|
+
const pid = parseInt(fs.readFileSync(lockFile, "utf8").trim(), 10);
|
|
357
|
+
if (Number.isInteger(pid) && pid > 0) holder = `(持有者 pid=${pid})`;
|
|
358
|
+
} catch { /* 读不到内容就不提 */ }
|
|
359
|
+
throw new Error(`获取状态锁超时(session=${sanitizeId(sid)}${holder}),请稍后重试`);
|
|
334
360
|
}
|
|
335
|
-
|
|
361
|
+
// 指数退避 + 抖动。
|
|
362
|
+
// 固定 15ms 会让多个进程「同步醒来」反复撞在一起(并发套件里表现为偶发超时);
|
|
363
|
+
// 抖动把重试错开,退避上限 120ms 保证总吞吐不被拖垮。
|
|
364
|
+
attempt++;
|
|
365
|
+
const base = Math.min(120, 5 * Math.pow(1.6, attempt));
|
|
366
|
+
const jitter = Math.floor(Math.random() * base * 0.3);
|
|
367
|
+
sleepMs(Math.floor(base + jitter));
|
|
336
368
|
}
|
|
337
369
|
}
|
|
338
370
|
|