carlos-flow 2.6.3 → 2.8.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/README.zh.md CHANGED
@@ -35,8 +35,14 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
35
35
 
36
36
  - 越界?→ 运行时 `git diff` 对比卡片白名单,**直接阻断派发**
37
37
  - 说测试通过?→ 真实 `spawn` 执行 `verify.cmd`,**记 PASS 前必须有通过的 exitCode**
38
- - 审计日志?→ SHA-256 **链式哈希**(`prevHash` → `hash`),**改一条全链断裂**
38
+ - 审计日志?→ **链式哈希**(`prevHash` → `hash`),改一条全链断裂。
39
+ 设了 `CARLOS_FLOW_AUDIT_KEY` 时用 **HMAC-SHA256**(带密钥)→ 攻击者重算不出,只能发现不能隐藏
39
40
  - 想跳过?→ 免检需显式 `confirmed=true`,且**每次派发自动清零**
41
+ 审计文件按本地日期分片,`prevHash` 一律联动**前一天的 tail**,跨天不断链。
42
+ 未设密钥时(`plain` 模式)走裸 SHA-256:只能防**意外损坏**,
43
+ 不能防有意篡改;`verifyAuditChain()` 的回传带了 `mode` 字段(`plain`/`hmac`),
44
+ 调用方自行判断强度。审计记录(`audit()`)和状态文件(`saveState()`)
45
+ 写之前先脱敏——密钥片段不入盘。
40
46
 
41
47
  **一句话**:它把「代码评审的门禁」搬到了 AI Agent 上,而且门禁本身是机器执行、不是人执行。
42
48
 
@@ -48,7 +54,8 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
48
54
  |---|------|---------|------------------------|
49
55
  | 1 | **越界改动** | "只改这些文件"是建议不是规则 | `enforceScope()` 运行时 `git diff` 比对白名单,越界**阻断派发** |
50
56
  | 2 | **验证表演** | Agent 自述"测试通过",无人能证明 | `runVerifyCommand()` 真实执行,捕获 stdout/stderr/exitCode;**无验证证据不许记 PASS** |
51
- | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | SHA-256 链式哈希审计,**改一条全链断裂** |
57
+ | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | 链式哈希审计,**改一条全链断裂**;跨天链联动前一天 tail;**审计记录与落盘状态均脱敏后写**;
58
+ 配 `CARLOS_FLOW_AUDIT_KEY` 启用 HMAC 后,**攻击者没有密钥就无法重算掩盖** |
52
59
  | 4 | **失控免检** | 一句话关闭所有防护 | 需卡片显式 `confirmed=true`,**每次派发自动清零** |
53
60
  | 5 | **无限派发** | 领卡即重置计数,可无限重试 | `dispatch_count` 仅在派发时 +1,耗尽同时拦截 claim / dispatch |
54
61
  | 6 | **自证式复核** | 同一 Agent 既实现又审批 | 内置 `auditor` 角色 + 独立合同,裁定严格三档 |
@@ -116,11 +123,11 @@ flowchart TB
116
123
  Plugin["plugins/carlos-flow-trigger.js<br/>chat.message 钩子"]
117
124
  end
118
125
 
119
- subgraph Core["核心 MCP Server (src/index.js) — 15 个工具"]
126
+ subgraph Core["核心 MCP Server (src/index.js) — 16 个工具"]
120
127
  Protocol["flow_protocol"]
121
128
  Submit["flow_submit_requirement"]
122
129
  Dispatch["flow_claim / flow_dispatch"]
123
- Verify["flow_run_verify / flow_check_scope"]
130
+ Verify["flow_run_verify / flow_falsify / flow_check_scope"]
124
131
  Verdict["flow_verdict"]
125
132
  Audit["flow_status / flow_audit"]
126
133
  Trigger["flow_trigger_check"]
@@ -156,7 +163,7 @@ flowchart TB
156
163
  |----|------|------|---------|
157
164
  | **宿主适配层** | `ghost.json` / `plugins/` / `templates/` | 发现、启动、配置、生命周期 | ⚠️ 唯一有平台差异的层 |
158
165
  | **客户端层** | `client/carlos.js` / `bridge/` | CLI、触发检查、Bridge 守护 | 仅 Cindy 需要 Bridge |
159
- | **协议层** | `src/index.js` | 15 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
166
+ | **协议层** | `src/index.js` | 16 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
160
167
  | **引擎层** | `src/trigger.js` / `src/card.js` / `src/state.js` | 触发评分、卡片校验、状态/审计 | ✅ 零耦合,纯 JS 无依赖 |
161
168
  | **持久化层** | `~/.carlos-flow/` | 状态、审计链、快照、触发历史 | ✅ 跨平台路径约定 |
162
169
 
@@ -170,9 +177,9 @@ flowchart TB
170
177
 
171
178
  | 能力 | Carlos Flow | 原生 MCP Server | 提示词 / 手写脚本 |
172
179
  |------|-------------|-----------------|------------------|
173
- | 越界拦截 | ✅ 运行时 `git diff` 级 | ❌ | ❌ 靠自觉 |
180
+ | 越界拦截 | ✅ 自己跑 `git diff`;执行者动了 scope 外的文件 → **阻断 PASS** | ❌ | ❌ 靠自觉 |
174
181
  | 真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
175
- | 防篡改审计 | ✅ SHA-256 链式哈希 | ❌ | ❌ |
182
+ | 审计链完整性 | ✅ 链式哈希(+ 可选 HMAC),跨天串联,落盘脱敏 | ❌ | ❌ |
176
183
  | 可控免检 | ✅ 显式开启 + 自动清零 | ❌ | ❌ 一句话全关 |
177
184
  | 诚实派发配额 | ✅ 只计派发 | ❌ | ❌ |
178
185
  | 独立复核 | ✅ 内置 `auditor` 角色 | ❌ | ❌ 可选 |
@@ -184,6 +191,9 @@ flowchart TB
184
191
  > **信任边界说明**:手工改 `state.json` 里的 verdict 能伪造 PASS —— 状态文件不在审计哈希链内。
185
192
  > 这是**本地文件系统权限**的信任边界,不是 MCP 工具面能被绕过的漏洞:
186
193
  > 能写 `CARLOS_FLOW_HOME` 的人本来就能改自己的代码。
194
+ > 还要注意:(1)未设 `CARLOS_FLOW_AUDIT_KEY` 时是 `plain` 模式(裸 SHA-256),
195
+ > **`ok: true` 不是「没被篡改过」的证明**,调用方看 `mode` 字段;
196
+ > (2)审计记录与状态(`verify.cmd`/`token`/`password`)脱敏后入盘,密钥片段不留明文。
187
197
  > 完整说明见 [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) §六。
188
198
 
189
199
  ---
@@ -273,7 +283,7 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
273
283
 
274
284
  ---
275
285
 
276
- ## 🔧 MCP 工具参考(15 个)
286
+ ## 🔧 MCP 工具参考(16 个)
277
287
 
278
288
  | 工具 | 作用 | 关键约束 |
279
289
  |------|------|---------|
@@ -283,9 +293,10 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
283
293
  | `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
284
294
  | `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
285
295
  | `flow_save_result` | 保存子 Agent 执行结果 | — |
286
- | `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr |
296
+ | `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr + `output_hash` |
297
+ | `flow_falsify` | **负对照**:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(`|| true`)会被拒;记 PASS 前必做 |
287
298
  | `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
288
- | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发不许 PASS;验证未过不许 PASS |
299
+ | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发不许 PASS;验证未过不许 PASS;**负对照未过不许 PASS** |
289
300
  | `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` |
290
301
  | `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
291
302
  | `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
@@ -325,7 +336,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
325
336
  | `CARLOS_FLOW_HOME` | `~/.carlos-flow` | 状态 / 审计 / 快照目录。`~` 会被展开 |
326
337
  | `CARLOS_FLOW_MCP_ROOT` | 自动推导 | 源码安装时指向仓库根目录 |
327
338
  | `BRIDGE_PORT` | `19099` | Cindy Bridge 监听端口 |
328
- | `CARLOS_BRIDGE_TOKEN` | 内置默认值 | Bridge 本地认证 token |
339
+ | `CARLOS_BRIDGE_TOKEN` | 随机生成落盘 | Bridge 本地认证 token(自动生成,存 0600) |
340
+ | `CARLOS_FLOW_AUDIT_KEY` | — | 设置它(≥16 字符)启用 **HMAC** 审计链 —— 发现**有意篡改**必须配它 |
329
341
  | `CARLOS_BRIDGE_TIMEOUT_MS` | `180000` | Bridge 请求超时(需 > 服务端 120s 验证上限) |
330
342
  | `CARLOS_MCP_TIMEOUT_MS` | `180000` | CLI 客户端 MCP 调用超时 |
331
343
  | `CARLOS_TRIGGER_MESSAGE` | — | CLI 模式下注入触发检查用的用户原话 |
@@ -333,6 +345,70 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
333
345
 
334
346
  ---
335
347
 
348
+ ## 🛡️ 门禁体系 —— 门禁自己也要被门禁
349
+
350
+ > 「项目说自己有门禁」是最容易说的一句话,也最容易被证伪。
351
+ > 所以本项目的门禁**自己也有一套门禁**,且分两类:
352
+
353
+ ### 一、静态一致性(东西对不对得上)
354
+
355
+ | 脚本 | 查什么 |
356
+ |------|--------|
357
+ | `npm run check:full` | 旧引用 / 个人路径 / 版本号一致性 / 文档死链 / npm 发布集合 / 模板占位符 / package.json 字段 / 双仓残留 / ghost.json 工具清单 |
358
+ | `npm run check:identity` | 身份、版本、文档、产物、安全五类一致性 |
359
+ | `npm run check:lang` | 提交信息与源码注释是否中文(产物语言体检) |
360
+ | `npm run check:readme` | 中英双语 README 是否漂移 |
361
+ | `npm run check:anchors` | 变异体的注入锚点是否仍能命中(防止测试**静默失去守护作用**) |
362
+
363
+ ### 二、行为兑现(说了的做到了吗)—— 这一类才是关键
364
+
365
+ | 脚本 | 查什么 | 为什么需要 |
366
+ |------|--------|-----------|
367
+ | `npm run check:claims` | README/工具描述里的每个能力声明,是否都有对应的代码路径 | 静态检查查不出「承诺 vs 实现」的落差 |
368
+ | `npm run check:params` | `inputSchema` 声明的每个参数,是否在 handler 里**真的被读取**;以及有没有「算出却从未使用」的死变量 | 静默失效型 bug(如 `date` 参数)不报错、测试全绿,只是安静地返回错数据 |
369
+ | `npm run check:no-dead-handler` | 同一 request schema 是否被**重复注册** | 重复注册时后注册的覆盖先注册的 → 先注册的是永不执行的死代码,靠注册顺序维持的正确性会被一次重排静默破坏 |
370
+
371
+ ### 三、变异测试 —— 用注入退化撞自己最自豪的代码
372
+
373
+ ```bash
374
+ npm run test:mutation # 17 类变异体,必须 17/17 全部被抓住
375
+ ```
376
+
377
+ 变异体不是随机造的,每一条都对应一个**真实退化**,且必须有测试能抓住它:
378
+
379
+ | 变异体 | 注入的退化 | 抓住它的测试 |
380
+ |--------|-----------|-------------|
381
+ | M1 | 激活只打印日志、不真的激活 | e2e |
382
+ | M2 / M3 | claim / verdict 的闸门失效 | e2e |
383
+ | M4 | 会话撞名(清洗后同形共用状态) | trigger |
384
+ | M5 / M6 | scope 不算补齐项 / 半补齐绕过 | e2e |
385
+ | M7 | 空 scope 退回 fail-open | e2e |
386
+ | M8 | 未派发可记 PASS | e2e |
387
+ | M9 | 闸门派生回退(用上一轮 pending 传递) | e2e 19d-3 |
388
+ | M10 / M11 | 普通卡也上闸 / 占位卡硬编码三项 | e2e |
389
+ | M12 | 跨进程锁失效(`wx` → `a`) | concurrency |
390
+ | M13 | 只读意图误判 | trigger |
391
+ | **M14** | **审计链断链**(去掉 prevHash 链接) | audit-chain |
392
+ | **M15** | **审计链校验恒真** | audit-chain |
393
+ | **M16** | **越界检查退回 fail-open** | scope-enforcement |
394
+ | **M17** | **date 参数失效** | audit-chain |
395
+
396
+ ### 四、专项真实验证(不靠 mock)
397
+
398
+ | 脚本 | 验什么 |
399
+ |------|--------|
400
+ | `npm run test:scope` | 在**真实 git 仓库**里改文件 → scope 外改动**真的被阻断**;派发前就有的改动**不误伤** |
401
+ | `npm run test:audit` | **真实篡改**审计记录 → hmac 模式必须发现;plain 模式如实标注局限;legacy 记录不误报;date 参数真的生效 |
402
+ | | **跨天链**连通不留断点;脱敏检查确保密钥片段不留明文 |
403
+ | `npm run test:bridge` | 端口上是**别人的 bridge** 时不得复用(否则状态会写到别人的 HOME) |
404
+ | `npm run test:package` | `npm pack` → 装到干净目录 → 从 `node_modules` 拉起 MCP server 走真实握手 |
405
+ | `npm run test:lang` | 语言体检脚本**真的能抓到英文**(防假绿) |
406
+
407
+ > 💡 **给质疑者的可执行入口**:上面每一条命令都可以自己跑一遍。
408
+ > 一个项目宣称「我的门禁是机械的」,最好的证明不是文档,是**让对方自己跑一遍**。
409
+
410
+ ---
411
+
336
412
  ## 🧪 开发
337
413
 
338
414
  ```bash
@@ -378,6 +454,8 @@ npm pack
378
454
  | [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | 智能触发引擎深度指南(配置、评分、激活、反馈学习) |
379
455
  | [CHANGELOG.md](./CHANGELOG.md) | 版本历史(Keep a Changelog + SemVer) |
380
456
  | [MIGRATION.md](./MIGRATION.md) | 从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移 |
457
+ | [AGENTS.md](./AGENTS.md) | 变更前置索引:改哪类东西先读哪份权威契约 |
458
+ | [docs/AUDIT_REVIEW.md](./docs/AUDIT_REVIEW.md) | 第三方审查报告的逐条核实与决策记录 |
381
459
  | [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) | 第三方只读验收(13/13 变异体全抓住) |
382
460
  | [变异测试报告](./docs/MUTATION_REPORT_v2.5.5.md) | 变异体注入细节与结果 |
383
461
 
package/TRIGGER_GUIDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Carlos Flow 智能触发引擎使用指南
2
2
 
3
- > **版本**: v2.6.3
3
+ > **版本**: v2.8.0
4
4
  > **适用**:`carlos-flow` 单包架构(2.6.0+)
5
5
  > **代码位置**:`src/trigger.js`(零外部依赖的纯 JavaScript 实现)
6
6
 
@@ -779,5 +779,5 @@ MIT License
779
779
 
780
780
  ---
781
781
 
782
- **版本**: v2.6.3
782
+ **版本**: v2.8.0
783
783
  **更新日期**: 2026-11-07
@@ -115,7 +115,21 @@ const server = createServer((socket) => {
115
115
 
116
116
  // 健康检查
117
117
  if (t === "GET /health") {
118
- socket.write(JSON.stringify({ status: "ok", uptime: process.uptime() }) + "\n");
118
+ // 必须回传**身份**,否则客户端无法判断“这个 bridge 是不是我该用的那个”。
119
+ //
120
+ // 背景:早先 /health 只回 {status:"ok"},客户端只要看到 ok 就复用 ——
121
+ // 于是端口上若跑着**另一个 ROOT / 另一个 CARLOS_FLOW_HOME** 的 bridge,
122
+ // 客户端会静默连过去:它启动时的 HOME 生效、调用方传的 CARLOS_FLOW_HOME
123
+ // 完全失效(状态写到别人的目录),且协议可能不匹配导致挂死。
124
+ // 现在回传 root / flow_home / pid,客户端逐一比对,不符就当“未运行”。
125
+ const health = {
126
+ status: "ok",
127
+ root: process.env.CARLOS_FLOW_MCP_ROOT || "",
128
+ flow_home: process.env.CARLOS_FLOW_HOME || "",
129
+ pid: process.pid,
130
+ port: PORT,
131
+ };
132
+ socket.write(JSON.stringify(health) + "\n");
119
133
  continue;
120
134
  }
121
135
 
package/client/carlos.js CHANGED
@@ -7,6 +7,7 @@
7
7
  import { createConnection, createServer } from "node:net";
8
8
  import { spawn } from "node:child_process";
9
9
  import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
10
+ import { randomBytes } from "node:crypto";
10
11
  import { resolve, join, dirname } from "node:path";
11
12
  import { fileURLToPath, pathToFileURL } from "node:url";
12
13
  import os from "node:os";
@@ -27,7 +28,49 @@ const BRIDGE_SCRIPT = [
27
28
  const MCP_SERVER = ROOT_ABS + "/src/index.js";
28
29
  // PID 文件按端口区分:多 Bridge 并存(测试用独立端口)时不会互相覆盖
29
30
  const PID_FILE = ROOT_ABS + "/bridge-" + BRIDGE_PORT + ".pid";
30
- const BRIDGE_TOKEN = process.env.CARLOS_BRIDGE_TOKEN || "carlos-local-token-2026";
31
+ // 实际使用的 bridge 端口:pickBridgePort 选定后写入,后续 callMCP 一律用它。
32
+ // 早先 callMCP 写死 BRIDGE_PORT,而 bridge 可能起在别的端口 → 连不上。
33
+ let ACTIVE_PORT = BRIDGE_PORT;
34
+ const BRIDGE_TOKEN_FILE = () => join(DEFAULT_FLOW_HOME, "bridge-token");
35
+
36
+ // 读取或生成 Bridge token。
37
+ //
38
+ // 早先这里是 `process.env.CARLOS_BRIDGE_TOKEN || "carlos-local-token-2026"` ——
39
+ // 一个**硬编码的默认值**。任何本机进程都知道这个字符串,都能连上本机 bridge
40
+ // (虽然只监听 127.0.0.1,但「本机任意进程可连」本身就是一道没关的门),
41
+ // 而且它与 bridge 侧的 fail-closed 行为不一致(bridge 没设环境变量就拒绕)。
42
+ //
43
+ // 现在:
44
+ // 1) 优先用环境变量 CARLOS_BRIDGE_TOKEN;
45
+ // 2) 没有则首次运行生成随机 token 落到 $CARLOS_FLOW_HOME/bridge-token(0600),
46
+ // 之后跨进程复用同一个(client 与 bridge 必须用同一把钥匙);
47
+ // 3) 文件权限设 0600(POSIX);Windows 上靠 ACL 默认保护。
48
+ //
49
+ // 这样既没有硬编码默认值,也不需要用户手工配置环境变量。
50
+ function resolveBridgeToken() {
51
+ const fromEnv = process.env.CARLOS_BRIDGE_TOKEN;
52
+ if (fromEnv && String(fromEnv).trim()) return String(fromEnv).trim();
53
+
54
+ const file = BRIDGE_TOKEN_FILE();
55
+ try {
56
+ if (existsSync(file)) {
57
+ const t = readFileSync(file, "utf8").trim();
58
+ if (t.length >= 32) return t;
59
+ }
60
+ } catch { /* 读不到 → 重新生成 */ }
61
+
62
+ const token = randomBytes(32).toString("hex");
63
+ try {
64
+ mkdirSync(dirname(file), { recursive: true });
65
+ writeFileSync(file, token + "\n", { encoding: "utf8", mode: 0o600 });
66
+ } catch {
67
+ // 落盘失败(只读 HOME 等)→ 退化为进程级临时 token:
68
+ // 本进程内 client 与 bridge 仍然一致,只是重启后失效。
69
+ }
70
+ return token;
71
+ }
72
+
73
+ const BRIDGE_TOKEN = resolveBridgeToken();
31
74
 
32
75
  // 智能触发引擎(本文件是 ESM,必须用动态 import;require 在 ESM 中不存在)
33
76
  // 加载失败时降级为「不触发」,不影响主流程
@@ -154,8 +197,27 @@ async function checkTrigger(message = '') {
154
197
  }
155
198
  }
156
199
 
200
+ // 路径归一化比较:判断两个路径是否指向同一个目录。
201
+ // 为什么要归一化:同一个目录在不同环境下可能是 POSIX 形式(Git Bash 的 /tmp/x)、
202
+ // Windows 形式、带不带尾斜杠、大小写差异 —— 直接字符串比较会把
203
+ // 「同一个目录」判成「不同身份」,于是永远不复用、每次都另起一个 bridge。
204
+ function samePath(a, b) {
205
+ if (!a || !b) return true; // 对方没报 → 不以此为拒理由
206
+ const norm = (p) => {
207
+ try {
208
+ let s = resolve(String(p));
209
+ // 去掉尾分隔符(根目录除外)
210
+ if (s.length > 1) s = s.replace(/[\\/]+$/, "");
211
+ return process.platform === "win32" ? s.toLowerCase() : s;
212
+ } catch {
213
+ return String(p);
214
+ }
215
+ };
216
+ return norm(a) === norm(b);
217
+ }
218
+
157
219
  // 检查 bridge 是否已在运行(先读 PID,再 TCP 探测)
158
- function isBridgeRunning() {
220
+ function isBridgeRunning(port = BRIDGE_PORT) {
159
221
  return new Promise((resolve) => {
160
222
  // 先检查 PID 文件
161
223
  if (existsSync(PID_FILE)) {
@@ -172,7 +234,7 @@ function isBridgeRunning() {
172
234
  }
173
235
 
174
236
  // TCP 探测
175
- const s = createConnection(BRIDGE_PORT, "127.0.0.1");
237
+ const s = createConnection(port, "127.0.0.1");
176
238
  s.on("connect", () => {
177
239
  // 发送健康检查
178
240
  s.write("GET /health\n");
@@ -181,7 +243,31 @@ function isBridgeRunning() {
181
243
  const resp = data.toString().trim();
182
244
  try {
183
245
  const json = JSON.parse(resp);
184
- if (json.status === "ok") { s.end(); resolve(true); return; }
246
+ if (json.status !== "ok") { s.end(); resolve(false); return; }
247
+ // ⚠️ 身份校验:端口上跑的 bridge 必须是**我这份代码 + 我这个 HOME**。
248
+ //
249
+ // 早先只判 status==ok 就复用 —— 于是端口上是**另一个 ROOT** 的 bridge 时
250
+ // (比如开发机上的旧仓库那份),本进程会静默连过去:
251
+ // · 它启动时的 CARLOS_FLOW_HOME 生效 → 本次传入的 HOME 完全失效,
252
+ // 状态/审计写到**别人的目录**(测试污染生产状态的真凶);
253
+ // · 协议/版本可能不匹配 → 调用挂死。
254
+ // 现在比对 root 与 flow_home,不符就当“未运行”,另起一个自己的 bridge。
255
+ //
256
+ // 路径必须**归一化**后再比:同一个目录在不同环境下可能是
257
+ // POSIX 形式(Git Bash:/tmp/x)、Windows 形式(D:\\x)、带不带尾斜杠、
258
+ // 大小写差异 —— 直接字符串比较会把「同一个目录」判成「不同身份」,
259
+ // 于是永远不复用、每次都另起一个 bridge。
260
+ const sameRoot = samePath(json.root, ROOT_ABS);
261
+ const wantHome = process.env.CARLOS_FLOW_HOME || DEFAULT_FLOW_HOME;
262
+ const sameHome = samePath(json.flow_home, wantHome);
263
+ if (!sameRoot || !sameHome) {
264
+ s.end();
265
+ resolve(false);
266
+ return;
267
+ }
268
+ s.end();
269
+ resolve(true);
270
+ return;
185
271
  } catch {}
186
272
  s.end();
187
273
  // 健康检查失败但端口存活,也算运行中
@@ -192,10 +278,32 @@ function isBridgeRunning() {
192
278
  });
193
279
  }
194
280
 
281
+ // 找一个能用的端口。
282
+ //
283
+ // 首选 BRIDGE_PORT;若该端口已被**另一个身份的 bridge** 占用,
284
+ // 则向上探测若干个端口另起一个 —— 不能硬挤同一端口:
285
+ // 挤不进去时 spawn 会失败或挂死(实测客户端因此超时挂死 30s)。
286
+ async function pickBridgePort() {
287
+ for (let i = 0; i < 20; i++) {
288
+ const port = BRIDGE_PORT + i;
289
+ // 端口空闲 → 直接用
290
+ const busy = await new Promise((res) => {
291
+ const s = createConnection(port, "127.0.0.1");
292
+ s.on("connect", () => { s.end(); res(true); });
293
+ s.on("error", () => res(false));
294
+ setTimeout(() => { s.destroy(); res(false); }, 800);
295
+ });
296
+ if (!busy) return port;
297
+ // 端口被占 → 若是**同身份**的 bridge,直接复用
298
+ if (await isBridgeRunning(port)) return port;
299
+ }
300
+ return BRIDGE_PORT;
301
+ }
302
+
195
303
  // 自动启动 bridge(后台常驻)
196
- function startBridge() {
304
+ function startBridge(port = BRIDGE_PORT) {
197
305
  return new Promise((resolve, reject) => {
198
- const child = spawn(process.execPath, [BRIDGE_SCRIPT, String(BRIDGE_PORT)], {
306
+ const child = spawn(process.execPath, [BRIDGE_SCRIPT, String(port)], {
199
307
  stdio: ["ignore", "ignore", "pipe"],
200
308
  detached: true,
201
309
  windowsHide: true,
@@ -212,14 +320,14 @@ function startBridge() {
212
320
  // stderr 管道会挂住父进程的事件循环(bridge 常驻,管道永不关闭)→ 必须 unref
213
321
  try { child.stderr?.unref?.(); } catch {}
214
322
 
215
- // 写入 PID 文件
216
- try { writeFileSync(PID_FILE, String(child.pid), "utf8"); } catch {}
323
+ // 写入 PID 文件(按**实际使用的端口**命名,避免多实例互相覆盖)
324
+ try { writeFileSync(join(ROOT_ABS, `bridge-${port}.pid`), String(child.pid), "utf8"); } catch {}
217
325
 
218
326
  // 等待 bridge 就绪:用轻量健康检查端点,不占用 MCP 的 initialize 握手
219
327
  // (否则同一 MCP server 会被握手两次,导致首次调用挂起)
220
328
  const check = setInterval(async () => {
221
329
  const ready = await new Promise((res) => {
222
- const s = createConnection(BRIDGE_PORT, "127.0.0.1");
330
+ const s = createConnection(port, "127.0.0.1");
223
331
  let buf = "";
224
332
  s.on("connect", () => { s.write("GET /health\n"); });
225
333
  s.on("data", (data) => {
@@ -250,7 +358,7 @@ function startBridge() {
250
358
  // 通过 bridge 调用 MCP
251
359
  function callMCP(method, params) {
252
360
  return new Promise((resolve, reject) => {
253
- const socket = createConnection(BRIDGE_PORT, "127.0.0.1");
361
+ const socket = createConnection(ACTIVE_PORT, "127.0.0.1");
254
362
  let buf = "";
255
363
  const reqId = Math.floor(Math.random() * 100000000) + 2;
256
364
  let resolved = false;
@@ -406,7 +514,10 @@ async function main() {
406
514
  for (let attempt = 0; attempt < 3; attempt++) {
407
515
  if (await isBridgeRunning()) break;
408
516
  try {
409
- await startBridge();
517
+ // 选端口:首选 BRIDGE_PORT;若被**别的身份的 bridge** 占用则向上另选
518
+ const port = await pickBridgePort();
519
+ ACTIVE_PORT = port;
520
+ await startBridge(port);
410
521
  break;
411
522
  } catch (e) {
412
523
  lastErr = e;
package/ghost.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "name": "Carlos 工作流",
6
6
  "description": "机械门禁 MCP:留痕/派发/裁定/审计/快照/免检/还原。自动管理 Bridge 后台常驻,首次调用 ~3-5s,后续 ~1s。",
7
7
  "whenToUse": "需要走 Carlos 工作流门禁时使用:留痕/派发/裁定/审计/快照/免检/还原",
8
- "version": "2.6.3",
8
+ "version": "2.8.0",
9
9
  "kind": "mcp",
10
10
  "entry": "client/carlos.js",
11
11
  "command": "门禁",
@@ -418,6 +418,23 @@
418
418
  }
419
419
  }
420
420
  },
421
+ {
422
+ "name": "flow_falsify",
423
+ "description": "负对照(negative control):把工作区还原到派发时的「改动前」状态跑同一 verify.cmd,要求它失败;再还原「改动后」状态跑一次,要求它通过。只有「改动前失败 + 改动后通过」才证明这个测试真的在测本次改动(而不是 `|| true` / `echo ok` 这类空测试)。记 PASS 裁定前必须先做负对照。",
424
+ "parameters": {
425
+ "type": "object",
426
+ "properties": {
427
+ "sessionId": {
428
+ "type": "string",
429
+ "description": "会话 ID,默认 unknown"
430
+ },
431
+ "cwd": {
432
+ "type": "string",
433
+ "description": "工作目录,默认 process.cwd()"
434
+ }
435
+ }
436
+ }
437
+ },
421
438
  {
422
439
  "name": "flow_check_scope",
423
440
  "description": "检查指定文件列表是否在卡片 scope 范围内。用于在提交裁定前自查越界改动。空 scope 判定为全部越界(fail-closed)。",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "carlos-flow",
3
- "version": "2.6.3",
3
+ "version": "2.8.0",
4
4
  "description": "Carlos 工作流 — AI 编码 Agent 的机械门禁。留痕/派发/验证/裁定/审计/还原,约束写在代码里而非提示词里。单一包支持 Cindy/OpenCode/Cursor/Cline/VS Code/Claude Desktop。",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
@@ -42,7 +42,13 @@
42
42
  "check:lang": "node scripts/lang-audit.mjs",
43
43
  "test:lang": "node test/lang-audit.test.mjs",
44
44
  "check:full": "node scripts/full-audit.mjs",
45
- "test:package": "node test/package-e2e.mjs"
45
+ "test:package": "node test/package-e2e.mjs",
46
+ "check:claims": "node scripts/check-claims.mjs",
47
+ "check:params": "node scripts/check-params.mjs",
48
+ "check:no-dead-handler": "node scripts/check-no-dead-handler.mjs",
49
+ "test:scope": "node test/scope-enforcement.mjs",
50
+ "test:audit": "node test/audit-chain.mjs",
51
+ "test:bridge": "node test/bridge-identity.mjs"
46
52
  },
47
53
  "keywords": [
48
54
  "carlos",
@@ -89,6 +95,7 @@
89
95
  "TRIGGER_GUIDE.md",
90
96
  "MIGRATION.md",
91
97
  "CHANGELOG.md",
92
- "LICENSE"
98
+ "LICENSE",
99
+ "AGENTS.md"
93
100
  ]
94
101
  }