carlos-flow 2.6.3 → 2.7.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/AGENTS.md ADDED
@@ -0,0 +1,101 @@
1
+ # AGENTS.md — 修改前必读
2
+
3
+ > 本文件是**变更前置索引**:改某一类东西之前,先读对应的那份权威契约。
4
+ > 目的是让「改了实现、忘了改契约」这类静默退化在 review 前就被发现。
5
+
6
+ ---
7
+
8
+ ## 🔍 改之前先读这里
9
+
10
+ | 你要改 | 先读(权威契约) | 同步检查 |
11
+ |--------|-----------------|---------|
12
+ | `src/index.js` 的工具 handler | `src/protocol.js`(该工具的权威定义) | `README.md` 的工具参考表 |
13
+ | `src/index.js` 的参数校验 | `scripts/check-params.mjs` 的判定口径 | 工具的 `inputSchema` |
14
+ | `src/state.js` 的状态字段 | `src/state.js` 的 `defaultState()` + `schemaVersion` | 迁移函数 `migrate()` |
15
+ | `src/state.js` 的审计链 | `docs/AUDIT_REVIEW.md` 的威胁模型 | `test/audit-chain.mjs` |
16
+ | `src/dispatch.js` 的 scope 判定 | `test/scope-enforcement.mjs` 的用例 | `README.md` 的能力矩阵 |
17
+ | 门禁逻辑(claim / dispatch / verdict) | `test/e2e-carlos.mjs` 的第 15~26 组用例 | 变异体 M1~M6 |
18
+ | `src/trigger.js` 触发引擎 | `TRIGGER_GUIDE.md` + `test/trigger-e2e.mjs` | 触发器配置模板 |
19
+ | 对外工具描述 / README | `scripts/check-claims.mjs`(承诺兑现度门禁) | `npm run check:claims` |
20
+ | `bridge/` 或 `client/` | `test/bridge-identity.mjs`(身份隔离) | `npm run test:bridge` |
21
+ | CI / 发布流程 | `.github/workflows/` | `npm run check:full` |
22
+
23
+ ---
24
+
25
+ ## 🚫 红线(改坏了就是事故)
26
+
27
+ 1. **门禁只许收紧,不许放宽**
28
+ - 任何让「本该被拦住的」变得能通过的改动,都是回归。
29
+ - 典型危险:把 `ok: false` 改成 `ok: true`、把 `fail()` 改成 `ok()`、
30
+ 删掉某个拒绝分支、把 `every` 改成 `some`。
31
+
32
+ 2. **PASS 裁定必须同时满足三个条件**
33
+ - `dispatch_count > 0`(确实派发过)
34
+ - `last_verify.ok === true`(验证真的通过)
35
+ - `last_verify.cmd` 与**当前卡片**的 `verify.cmd` 一致(不能用旧卡结果冒充)
36
+
37
+ 3. **空 scope = fail-closed**
38
+ - 卡片 `scope` 为空时,**任何**文件改动都算越界。
39
+ - 不许改成「白名单为空 → 随便改」。
40
+
41
+ 4. **激活占位卡未补齐时不得派发 / 不得裁定**
42
+ - `activation_pending` 非空 → `flow_claim` / `flow_dispatch` / `flow_verdict` 全部拒绝。
43
+
44
+ 5. **审计链的 legacy 记录不得重置链起点**
45
+ - 旧格式记录(无 hash)只计入 `legacy` 计数,**保持 `prev` 不变**。
46
+ - 重置会让 v2.5 升级上来的用户审计链长期报红 —— 误报比漏报更伤信任。
47
+
48
+ 6. **不得引入硬编码密钥 / Token / 路径**
49
+ - 密钥走环境变量;状态目录走 `CARLOS_FLOW_HOME`;路径用 `__ROOT__` 占位符 + `init` 渲染。
50
+
51
+ 7. **工具描述与实现必须一致**
52
+ - 描述里承诺的能力,代码里必须有对应实现。
53
+ - `inputSchema` 声明的参数,handler 必须真的读取。
54
+ - 由 `npm run check:claims` 与 `npm run check:params` 强制。
55
+
56
+ ---
57
+
58
+ ## ✅ 提交前必跑
59
+
60
+ ```bash
61
+ npm run test:all # 主测试套件(smoke + e2e + p0 + trigger + concurrency + acceptance)
62
+ npm run test:scope # 越界拦截真实验证(真实 git 仓库 + 真实改动)
63
+ npm run test:audit # 审计链篡改检测验证(HMAC / plain / legacy / date)
64
+ npm run test:bridge # Bridge 身份隔离(端口上是别人的 bridge 不得复用)
65
+ npm run test:lang # 产物语言体检的自检
66
+ npm run test:package # 包级端到端(真实 tarball + 干净安装 + 真实 MCP 握手)
67
+ npm run check:full # 对外产物全面体检
68
+ npm run check:claims # 承诺兑现度门禁
69
+ npm run check:params # 参数有效性门禁
70
+ npm run check:no-dead-handler # 重复注册门禁
71
+ npm run check:anchors # 变异锚点未失效
72
+ npm run check:readme # 双语 README 未漂移
73
+ ```
74
+
75
+ 变异测试(耗时较长,发布前跑):
76
+
77
+ ```bash
78
+ npm run test:mutation # 17 类变异体必须 17/17 全部被抓住
79
+ ```
80
+
81
+ ---
82
+
83
+ ## 📐 加新工具的清单
84
+
85
+ 1. `src/index.js` 的 `TOOLS` 里加定义(`name` / `description` / `inputSchema` / `handler`)
86
+ 2. `ghost.json` 的 `tools` 里加同样的声明(**Cindy 用户靠它看到工具**,缺了就等于没有)
87
+ 3. 描述里**不要**承诺实现里没有的能力 —— `npm run check:claims` 会查
88
+ 4. `inputSchema` 的每个参数都要在 handler 里真的被读取 —— `npm run check:params` 会查
89
+ 5. 加测试(正常路径 + 至少一个负例)
90
+ 6. 如果改了门禁语义 → 同步 `src/protocol.js` 与 `README.md` 的能力矩阵
91
+
92
+ ---
93
+
94
+ ## 🔗 相关文档
95
+
96
+ - [`README.md`](./README.md) — 项目总览与能力矩阵
97
+ - [`TRIGGER_GUIDE.md`](./TRIGGER_GUIDE.md) — 触发引擎指南
98
+ - [`MIGRATION.md`](./MIGRATION.md) — 旧包迁移
99
+ - [`CHANGELOG.md`](./CHANGELOG.md) — 版本历史
100
+ - [`docs/AUDIT_REVIEW.md`](./docs/AUDIT_REVIEW.md) — 第三方审查报告的逐条核实与决策记录
101
+ - [`SECURITY.md`](./SECURITY.md) — 安全策略与威胁模型
package/CHANGELOG.md CHANGED
@@ -5,6 +5,102 @@
5
5
 
6
6
  ---
7
7
 
8
+ ## [2.7.0] - 2026-11-07 — 第三方审查全线修复:核心承诺终于成立 + 安全承诺降级为准确表述
9
+
10
+ > 本版源于一份第三方审查报告(逐条核实与决策记录见 [`docs/AUDIT_REVIEW.md`](./docs/AUDIT_REVIEW.md))。
11
+ > 核实基线:v2.6.3(commit \`f3e081c\`)。报告的 11 项指控,**10 项属实**、1 项部分属实(机制对但结论不准)。
12
+ > 全部已修,并固化为**自动门禁**,不再依赖人工记得检查。
13
+
14
+ ### 🎯 核心承诺修复(P0)—— 「越界直接阻断派发」从今天起成立
15
+
16
+ | # | 问题 | 影响 | 修复 |
17
+ |---|------|------|------|
18
+ | T-79 | \`enforceScope(scope, diffFiles)\` 是纯函数、**从不自己跑 git diff**,完全信任调用方传入的 paths;且 \`flow_dispatch\` 里**零 scope 校验**(只有快照) | README 承诺的「越界?→ 运行时 git diff 对比白名单,**直接阻断派发**」**完全不成立** —— 越界改动根本不会被发现 | ① \`enforceScope(scope, cwd, diffFiles?)\` 改为**自己跑 \`git diff --name-only\`**(cwd 传入,不传 paths 即自动采集);② \`flow_dispatch\` 记录**派发前基线**;③ \`flow_verdict\` 记 PASS 前用「当前改动 − 基线」算出**本次执行引入的**改动,越界则**拒绝记 PASS**并写 \`scope_violation\` 审计 |
19
+
20
+ > **为什么阻断点选在「裁定前」而不是「派发前」**:派发那一刻子 Agent **还没动手**,
21
+ > 它之后会改哪些文件无从得知。此时跑 git diff 得到的是「用户自己已有的未提交改动」,
22
+ > 拿它当越界拦下来会**误伤正常用法**。
23
+ > 正确语义是「本次执行有没有越界」—— 所以用**基线增量**判定,
24
+ > 既拦住越界,又不误伤用户原有改动。两点都有实测(\`test/scope-enforcement.mjs\`)。
25
+
26
+ ### 🔐 安全承诺修复(P0)—— 审计链从「假装防篡改」改为「分模式如实告知」
27
+
28
+ | # | 问题 | 影响 | 修复 |
29
+ |---|------|------|------|
30
+ | T-80 | 审计链是**裸 SHA-256**(无密钥),攻击者能读文件就能重算整条链 | README 宣称「改一条全链断裂」「防篡改」—— 实测**能洗白**。这是**威胁模型缺失**,不是实现 bug | 新增两种模式:设 \`CARLOS_FLOW_AUDIT_KEY\` → **HMAC-SHA256**(带密钥,无密钥者重算不出 → 篡改必被发现);未设 → 降级 \`plain\` 并在 \`verifyAuditChain()\` 结果里**显式标注 \`mode\` 字段**。README/SECURITY 同步改成**准确表述**(不再笼统宣称「防篡改」) |
31
+ | T-81 | \`verifyAuditChain\` 的 legacy 分支 \`prev = "0".repeat(64)\` **重置链起点** | 一条旧格式记录就让其后所有记录 \`prevHash\` 对不上 → 全判 broken → **v2.5 升级用户审计链长期报红**,会误以为记录被篡改(**误报比漏报更伤信任**) | legacy 记录只计入计数,**保持 \`prev\` 不变** |
32
+ | T-82 | 客户端有**硬编码默认 Token**(\`carlos-local-token-2026\`),与 bridge 侧 fail-closed 行为不一致 | 任何本机进程都知道这个字符串;SECURITY.md 却声称「无硬编码密钥」—— 自相矛盾 | 去掉硬编码默认值:优先读 \`CARLOS_BRIDGE_TOKEN\`;未设则**首次运行生成 256 位随机 token** 落盘 \`$CARLOS_FLOW_HOME/bridge-token\`(0600),跨进程复用 |
33
+ | T-83 | \`flow_audit\` 的 \`date\` 参数**完全失效**(\`rawDate\` 算出却不用,文件路径仍是 \`localDate()\`) | 工具描述承诺「可按日期过滤」,实际传 \`date=2020-01-01\` 读到的是**今天**的数据 —— 错而不报 | \`readAudit\` / \`verifyAuditChain\` 均改用 \`rawDate\` 构造文件路径 |
34
+
35
+ ### 🧭 行为兑现类门禁(新增)—— 防止这类问题复发
36
+
37
+ > 报告里最有价值的一个元发现:**现有门禁擅长查「静态一致性」,不擅长查「行为兑现」**。
38
+ > 上面的 P0 与 P1 问题**一个都没被现有门禁抓到**。为此新增三个门禁:
39
+
40
+ | 脚本 | 查什么 |
41
+ |------|--------|
42
+ | \`npm run check:claims\` | README/工具描述的每个能力声明都有对应代码路径;10 条核心承诺 + 6 条关键不变量 |
43
+ | \`npm run check:params\` | \`inputSchema\` 每个参数都被 handler **真实读取**;无「算出却从未使用」的死变量;\`date\` 贯通检查 |
44
+ | \`npm run check:no-dead-handler\` | 同一 request schema 不得重复注册;handler 必须走 \`TOOLS.find\` 分发且调用 \`validateToolArgs\` |
45
+
46
+ ### 🧬 专项真实验证(新增)—— 不靠 mock,用真实 git / 真实篡改
47
+
48
+ | 脚本 | 验什么 | 用例数 |
49
+ |------|--------|--------|
50
+ | \`npm run test:scope\` | 真实 git 仓库里改文件 → scope 外改动**真被阻断**;派发前已有改动**不误伤**;\`flow_check_scope\` 自动 diff 模式 | 5/5 |
51
+ | \`npm run test:audit\` | **真实篡改**审计记录 → hmac 模式必发现;plain 模式如实标注局限;legacy 不误报;date 真的生效 | 12/12 |
52
+ | \`npm run test:bridge\` | 端口上是**别人的 bridge** 时不复用(状态不会写到别人的 HOME);同身份可复用 | 6/6 |
53
+ | \`npm run test:lang\` | 语言体检**真能抓到英文**(防假绿) | 12/12 |
54
+
55
+ ### 🧹 整洁性修复
56
+
57
+ | # | 问题 | 修复 |
58
+ |---|------|------|
59
+ | T-84 | \`CallToolRequestSchema\` **注册了两次**(后注册覆盖先注册 → 先注册的是 17 行死代码,靠注册顺序维持参数校验的正确性) | 删除先注册的那个;\`check:no-dead-handler\` 守住不再复发 |
60
+ | T-85 | \`wasActivated\` 死变量(算出从未使用) | 删除;\`check:params\` 以后自动发现这类 |
61
+ | T-86 | \`flow_claim\` / \`flow_revert_plan\` 的 \`inputSchema\` 声明了 \`cwd\` 但 handler 从不读 | **删掉声明**(这两个操作确实不需要工作目录 —— 声明一个不生效的参数会误导调用方) |
62
+ | T-87 | legacy 记录导致审计链误报 | 见 T-81 |
63
+
64
+ ### 🧬 变异测试扩容 —— 用注入退化撞自己最自豪的代码
65
+
66
+ 变异体从 13 类增到 **17 类**,新增的 4 条全部针对本次修复的核心:
67
+
68
+ | 变异体 | 注入的退化 | 抓住它的测试 |
69
+ |--------|-----------|-------------|
70
+ | **M14** | 审计链去掉 prevHash 链接 | test:audit |
71
+ | **M15** | \`verifyAuditChain\` 永远返回 ok:true | test:audit |
72
+ | **M16** | \`enforceScope\` 退回 fail-open | test:scope |
73
+ | **M17** | \`date\` 参数失效 | test:audit |
74
+
75
+ 并修掉了**历史守护缺口 M9**(闸门派生回退):之前一直 NOT CAUGHT,
76
+ 因为普通流程下它与正确实现等价。新增 e2e 用例 19d-3 构造「pending 非空但 activated=false」
77
+ 的不一致状态,验证普通卡提交能**自愈**而不是把用户永久锁死。
78
+
79
+ > **变异测试结果:17/17 全部被抓住**(此前 13/14,M9 逃逸)。
80
+
81
+ ### ✨ 新增 | Added
82
+
83
+ - **`AGENTS.md`** —— 变更前置索引:改哪类东西先读哪份权威契约;7 条红线(门禁只许收紧、
84
+ PASS 三条件、空 scope fail-closed、占位卡未补齐不得派发/裁定、legacy 不重置链起点、
85
+ 不引入硬编码密钥、描述与实现必须一致);提交前必跑清单;加新工具的 6 步清单
86
+ - **状态 schema 版本机制** —— \`schemaVersion\` + \`migrate()\`:将来改字段名时,
87
+ 旧状态**显式迁移**而不是静默降级(早先靠 \`{...defaultState(), ...parsed}\` 防御性合并,
88
+ 改字段名会让老用户状态静默丢字段 —— 极难定位)
89
+ - **README「门禁体系」章节** —— 把 11 个门禁脚本、17 类变异体、5 个真实验证整理成可读结构,
90
+ 并给出**给质疑者的可执行入口**(每条命令都能自己跑一遍)
91
+
92
+ ### 🔬 验证 | Verification
93
+
94
+ | 项 | 结果 |
95
+ |----|------|
96
+ | 主测试 | **131/0**(smoke 4 / e2e 64 / p0 22 / trigger 29 / concurrency 3 / acceptance 13) |
97
+ | 专项真实验证 | scope **5/0** · audit **12/0** · bridge **6/0** |
98
+ | 语言体检自检 | **12/0** |
99
+ | 变异测试 | **17/17 全部被抓住** |
100
+ | 门禁脚本 | check:full / identity / lang / claims / params / no-dead-handler / anchors / readme —— 全通过 |
101
+
102
+ ---
103
+
8
104
  ## [2.6.3] - 2026-11-07 — 统一工具返回结构 + 新增包级端到端实测
9
105
 
10
106
  ### 🐛 修复 | Fixed
package/README.en.md CHANGED
@@ -171,7 +171,7 @@ flowchart TB
171
171
 
172
172
  | Capability | Carlos Flow | Native MCP Server | Prompts / Scripts |
173
173
  |------------|-------------|-------------------|-------------------|
174
- | Scope enforcement | ✅ Runtime `git diff` | ❌ | ❌ Honor system |
174
+ | Scope enforcement | ✅ Runs `git diff` itself; **blocks PASS** when the executor touched out-of-scope files | ❌ | ❌ Honor system |
175
175
  | Real verification | ✅ spawn + capture; no evidence → no PASS | ❌ | ❌ Agent says so |
176
176
  | Tamper-proof audit | ✅ SHA-256 chained hashes | ❌ | ❌ |
177
177
  | Controlled bypass | ✅ Explicit + auto-cleared | ❌ | ❌ One sentence kills all |
@@ -328,7 +328,8 @@ Path: `$CARLOS_FLOW_HOME/trigger-config.json` (auto-generated by `init`)
328
328
  | `CARLOS_FLOW_HOME` | `~/.carlos-flow` | State / audit / snapshot directory. `~` is expanded |
329
329
  | `CARLOS_FLOW_MCP_ROOT` | auto-derived | Repo root for source installs |
330
330
  | `BRIDGE_PORT` | `19099` | Cindy Bridge listening port |
331
- | `CARLOS_BRIDGE_TOKEN` | built-in default | Local Bridge auth token |
331
+ | `CARLOS_BRIDGE_TOKEN` | random file | Local Bridge auth token (auto-generated, stored 0600) |
332
+ | `CARLOS_FLOW_AUDIT_KEY` | — | Set it (≥16 chars) to enable **HMAC** audit chain — required to detect *intentional* tampering |
332
333
  | `CARLOS_BRIDGE_TIMEOUT_MS` | `180000` | Bridge request timeout (must exceed the server's 120s verify limit) |
333
334
  | `CARLOS_MCP_TIMEOUT_MS` | `180000` | CLI client MCP call timeout |
334
335
  | `CARLOS_TRIGGER_MESSAGE` | — | Inject the user's original message for CLI trigger checks |
@@ -336,6 +337,70 @@ Path: `$CARLOS_FLOW_HOME/trigger-config.json` (auto-generated by `init`)
336
337
 
337
338
  ---
338
339
 
340
+ ## 🛡️ The Gate System — the gates are gated too
341
+
342
+ > "This project has gates" is the easiest thing to say and the easiest thing to disprove.
343
+ > So the gates **themselves have gates**, in two categories:
344
+
345
+ ### 1. Static consistency (do the pieces agree?)
346
+
347
+ | Script | What it checks |
348
+ |--------|----------------|
349
+ | `npm run check:full` | Legacy refs / personal paths / version consistency / dead links / npm publish set / template placeholders / package.json fields / two-repo leftovers / ghost.json tool list |
350
+ | `npm run check:identity` | Identity, version, docs, artifacts, security |
351
+ | `npm run check:lang` | Commit messages and source comments are Chinese |
352
+ | `npm run check:readme` | Bilingual READMEs have not drifted |
353
+ | `npm run check:anchors` | Mutation anchors still hit (so tests can't **silently lose their guarding power**) |
354
+
355
+ ### 2. Behavioral fidelity (does the code do what it claims?) — this is the key one
356
+
357
+ | Script | What it checks | Why it exists |
358
+ |--------|----------------|--------------|
359
+ | `npm run check:claims` | Every capability claimed in the README / tool descriptions has a matching code path | Static checks can't see the gap between *claimed* and *implemented* |
360
+ | `npm run check:params` | Every `inputSchema` parameter is **actually read** by its handler; plus no "computed but never used" dead variables | Silent-failure bugs (like a dead `date` param) don't error, don't fail tests — they just quietly return wrong data |
361
+ | `npm run check:no-dead-handler` | No request schema is **registered twice** | The second registration overwrites the first → the first is dead code, and correctness that depends on registration order breaks silently on any reshuffle |
362
+
363
+ ### 3. Mutation testing — aim the injection at the code you're proudest of
364
+
365
+ ```bash
366
+ npm run test:mutation # 17 mutants, all 17 must be caught
367
+ ```
368
+
369
+ Each mutant corresponds to a **real regression** and must be caught by a real test:
370
+
371
+ | Mutant | Injected regression | Test that catches it |
372
+ |--------|---------------------|----------------------|
373
+ | M1 | Activation only logs, never activates | e2e |
374
+ | M2 / M3 | claim / verdict gates removed | e2e |
375
+ | M4 | Session name collision | trigger |
376
+ | M5 / M6 | scope not a required field / half-fill bypass | e2e |
377
+ | M7 | Empty scope falls back to fail-open | e2e |
378
+ | M8 | PASS without dispatch | e2e |
379
+ | M9 | Gate derivation falls back to previous pending | e2e 19d-3 |
380
+ | M10 / M11 | Normal card also gated / hardcoded three fields | e2e |
381
+ | M12 | Cross-process lock loses exclusivity | concurrency |
382
+ | M13 | Read-only intent misjudged | trigger |
383
+ | **M14** | **Audit chain unlinked** (prevHash removed) | audit-chain |
384
+ | **M15** | **Chain verification always returns ok** | audit-chain |
385
+ | **M16** | **Scope check falls back to fail-open** | scope-enforcement |
386
+ | **M17** | **date parameter silently dead** | audit-chain |
387
+
388
+ ### 4. Real end-to-end verifications (no mocks)
389
+
390
+ | Script | What it proves |
391
+ |--------|----------------|
392
+ | `npm run test:scope` | In a **real git repo**, editing a file outside scope is **actually blocked**; pre-existing edits are **not** misjudged |
393
+ | `npm run test:audit` | **Actually tampering** with an audit record → hmac mode must detect it; plain mode honestly states its limits; legacy records don't cause false alarms; `date` actually works |
394
+ | `npm run test:bridge` | A bridge belonging to **someone else** on the port is not reused (otherwise state lands in someone else's HOME) |
395
+ | `npm run test:package` | `npm pack` → install into a clean dir → launch the MCP server from `node_modules` and do a real handshake |
396
+ | `npm run test:lang` | The language audit really **catches** English (guards against a false green) |
397
+
398
+ > 💡 **An executable entry point for skeptics**: every command above can be run by anyone.
399
+ > When a project claims "my gates are mechanical", the best proof isn't documentation —
400
+ > it's **letting the skeptic run it**.
401
+
402
+ ---
403
+
339
404
  ## 🧪 Development
340
405
 
341
406
  ```bash
package/README.md CHANGED
@@ -35,7 +35,8 @@ 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`,且**每次派发自动清零**
40
41
 
41
42
  **一句话**:它把「代码评审的门禁」搬到了 AI Agent 上,而且门禁本身是机器执行、不是人执行。
@@ -48,7 +49,7 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
48
49
  |---|------|---------|------------------------|
49
50
  | 1 | **越界改动** | "只改这些文件"是建议不是规则 | `enforceScope()` 运行时 `git diff` 比对白名单,越界**阻断派发** |
50
51
  | 2 | **验证表演** | Agent 自述"测试通过",无人能证明 | `runVerifyCommand()` 真实执行,捕获 stdout/stderr/exitCode;**无验证证据不许记 PASS** |
51
- | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | SHA-256 链式哈希审计,**改一条全链断裂** |
52
+ | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | 链式哈希审计,**改一条全链断裂**;配 `CARLOS_FLOW_AUDIT_KEY` 启用 HMAC 后,**攻击者没有密钥就无法重算掩盖** |
52
53
  | 4 | **失控免检** | 一句话关闭所有防护 | 需卡片显式 `confirmed=true`,**每次派发自动清零** |
53
54
  | 5 | **无限派发** | 领卡即重置计数,可无限重试 | `dispatch_count` 仅在派发时 +1,耗尽同时拦截 claim / dispatch |
54
55
  | 6 | **自证式复核** | 同一 Agent 既实现又审批 | 内置 `auditor` 角色 + 独立合同,裁定严格三档 |
@@ -170,9 +171,9 @@ flowchart TB
170
171
 
171
172
  | 能力 | Carlos Flow | 原生 MCP Server | 提示词 / 手写脚本 |
172
173
  |------|-------------|-----------------|------------------|
173
- | 越界拦截 | ✅ 运行时 `git diff` 级 | ❌ | ❌ 靠自觉 |
174
+ | 越界拦截 | ✅ 自己跑 `git diff`;执行者动了 scope 外的文件 → **阻断 PASS** | ❌ | ❌ 靠自觉 |
174
175
  | 真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
175
- | 防篡改审计 | ✅ SHA-256 链式哈希 | ❌ | ❌ |
176
+ | 审计链完整性 | ✅ 链式哈希(+ 可选 HMAC 密钥) | ❌ | ❌ |
176
177
  | 可控免检 | ✅ 显式开启 + 自动清零 | ❌ | ❌ 一句话全关 |
177
178
  | 诚实派发配额 | ✅ 只计派发 | ❌ | ❌ |
178
179
  | 独立复核 | ✅ 内置 `auditor` 角色 | ❌ | ❌ 可选 |
@@ -325,7 +326,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
325
326
  | `CARLOS_FLOW_HOME` | `~/.carlos-flow` | 状态 / 审计 / 快照目录。`~` 会被展开 |
326
327
  | `CARLOS_FLOW_MCP_ROOT` | 自动推导 | 源码安装时指向仓库根目录 |
327
328
  | `BRIDGE_PORT` | `19099` | Cindy Bridge 监听端口 |
328
- | `CARLOS_BRIDGE_TOKEN` | 内置默认值 | Bridge 本地认证 token |
329
+ | `CARLOS_BRIDGE_TOKEN` | 随机生成落盘 | Bridge 本地认证 token(自动生成,存 0600) |
330
+ | `CARLOS_FLOW_AUDIT_KEY` | — | 设置它(≥16 字符)启用 **HMAC** 审计链 —— 发现**有意篡改**必须配它 |
329
331
  | `CARLOS_BRIDGE_TIMEOUT_MS` | `180000` | Bridge 请求超时(需 > 服务端 120s 验证上限) |
330
332
  | `CARLOS_MCP_TIMEOUT_MS` | `180000` | CLI 客户端 MCP 调用超时 |
331
333
  | `CARLOS_TRIGGER_MESSAGE` | — | CLI 模式下注入触发检查用的用户原话 |
@@ -333,6 +335,69 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
333
335
 
334
336
  ---
335
337
 
338
+ ## 🛡️ 门禁体系 —— 门禁自己也要被门禁
339
+
340
+ > 「项目说自己有门禁」是最容易说的一句话,也最容易被证伪。
341
+ > 所以本项目的门禁**自己也有一套门禁**,且分两类:
342
+
343
+ ### 一、静态一致性(东西对不对得上)
344
+
345
+ | 脚本 | 查什么 |
346
+ |------|--------|
347
+ | `npm run check:full` | 旧引用 / 个人路径 / 版本号一致性 / 文档死链 / npm 发布集合 / 模板占位符 / package.json 字段 / 双仓残留 / ghost.json 工具清单 |
348
+ | `npm run check:identity` | 身份、版本、文档、产物、安全五类一致性 |
349
+ | `npm run check:lang` | 提交信息与源码注释是否中文(产物语言体检) |
350
+ | `npm run check:readme` | 中英双语 README 是否漂移 |
351
+ | `npm run check:anchors` | 变异体的注入锚点是否仍能命中(防止测试**静默失去守护作用**) |
352
+
353
+ ### 二、行为兑现(说了的做到了吗)—— 这一类才是关键
354
+
355
+ | 脚本 | 查什么 | 为什么需要 |
356
+ |------|--------|-----------|
357
+ | `npm run check:claims` | README/工具描述里的每个能力声明,是否都有对应的代码路径 | 静态检查查不出「承诺 vs 实现」的落差 |
358
+ | `npm run check:params` | `inputSchema` 声明的每个参数,是否在 handler 里**真的被读取**;以及有没有「算出却从未使用」的死变量 | 静默失效型 bug(如 `date` 参数)不报错、测试全绿,只是安静地返回错数据 |
359
+ | `npm run check:no-dead-handler` | 同一 request schema 是否被**重复注册** | 重复注册时后注册的覆盖先注册的 → 先注册的是永不执行的死代码,靠注册顺序维持的正确性会被一次重排静默破坏 |
360
+
361
+ ### 三、变异测试 —— 用注入退化撞自己最自豪的代码
362
+
363
+ ```bash
364
+ npm run test:mutation # 17 类变异体,必须 17/17 全部被抓住
365
+ ```
366
+
367
+ 变异体不是随机造的,每一条都对应一个**真实退化**,且必须有测试能抓住它:
368
+
369
+ | 变异体 | 注入的退化 | 抓住它的测试 |
370
+ |--------|-----------|-------------|
371
+ | M1 | 激活只打印日志、不真的激活 | e2e |
372
+ | M2 / M3 | claim / verdict 的闸门失效 | e2e |
373
+ | M4 | 会话撞名(清洗后同形共用状态) | trigger |
374
+ | M5 / M6 | scope 不算补齐项 / 半补齐绕过 | e2e |
375
+ | M7 | 空 scope 退回 fail-open | e2e |
376
+ | M8 | 未派发可记 PASS | e2e |
377
+ | M9 | 闸门派生回退(用上一轮 pending 传递) | e2e 19d-3 |
378
+ | M10 / M11 | 普通卡也上闸 / 占位卡硬编码三项 | e2e |
379
+ | M12 | 跨进程锁失效(`wx` → `a`) | concurrency |
380
+ | M13 | 只读意图误判 | trigger |
381
+ | **M14** | **审计链断链**(去掉 prevHash 链接) | audit-chain |
382
+ | **M15** | **审计链校验恒真** | audit-chain |
383
+ | **M16** | **越界检查退回 fail-open** | scope-enforcement |
384
+ | **M17** | **date 参数失效** | audit-chain |
385
+
386
+ ### 四、专项真实验证(不靠 mock)
387
+
388
+ | 脚本 | 验什么 |
389
+ |------|--------|
390
+ | `npm run test:scope` | 在**真实 git 仓库**里改文件 → scope 外改动**真的被阻断**;派发前就有的改动**不误伤** |
391
+ | `npm run test:audit` | **真实篡改**审计记录 → hmac 模式必须发现;plain 模式如实标注局限;legacy 记录不误报;date 参数真的生效 |
392
+ | `npm run test:bridge` | 端口上是**别人的 bridge** 时不得复用(否则状态会写到别人的 HOME) |
393
+ | `npm run test:package` | `npm pack` → 装到干净目录 → 从 `node_modules` 拉起 MCP server 走真实握手 |
394
+ | `npm run test:lang` | 语言体检脚本**真的能抓到英文**(防假绿) |
395
+
396
+ > 💡 **给质疑者的可执行入口**:上面每一条命令都可以自己跑一遍。
397
+ > 一个项目宣称「我的门禁是机械的」,最好的证明不是文档,是**让对方自己跑一遍**。
398
+
399
+ ---
400
+
336
401
  ## 🧪 开发
337
402
 
338
403
  ```bash
@@ -378,6 +443,8 @@ npm pack
378
443
  | [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | 智能触发引擎深度指南(配置、评分、激活、反馈学习) |
379
444
  | [CHANGELOG.md](./CHANGELOG.md) | 版本历史(Keep a Changelog + SemVer) |
380
445
  | [MIGRATION.md](./MIGRATION.md) | 从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移 |
446
+ | [AGENTS.md](./AGENTS.md) | 变更前置索引:改哪类东西先读哪份权威契约 |
447
+ | [docs/AUDIT_REVIEW.md](./docs/AUDIT_REVIEW.md) | 第三方审查报告的逐条核实与决策记录 |
381
448
  | [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) | 第三方只读验收(13/13 变异体全抓住) |
382
449
  | [变异测试报告](./docs/MUTATION_REPORT_v2.5.5.md) | 变异体注入细节与结果 |
383
450
 
package/README.zh.md CHANGED
@@ -35,7 +35,8 @@ 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`,且**每次派发自动清零**
40
41
 
41
42
  **一句话**:它把「代码评审的门禁」搬到了 AI Agent 上,而且门禁本身是机器执行、不是人执行。
@@ -48,7 +49,7 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
48
49
  |---|------|---------|------------------------|
49
50
  | 1 | **越界改动** | "只改这些文件"是建议不是规则 | `enforceScope()` 运行时 `git diff` 比对白名单,越界**阻断派发** |
50
51
  | 2 | **验证表演** | Agent 自述"测试通过",无人能证明 | `runVerifyCommand()` 真实执行,捕获 stdout/stderr/exitCode;**无验证证据不许记 PASS** |
51
- | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | SHA-256 链式哈希审计,**改一条全链断裂** |
52
+ | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | 链式哈希审计,**改一条全链断裂**;配 `CARLOS_FLOW_AUDIT_KEY` 启用 HMAC 后,**攻击者没有密钥就无法重算掩盖** |
52
53
  | 4 | **失控免检** | 一句话关闭所有防护 | 需卡片显式 `confirmed=true`,**每次派发自动清零** |
53
54
  | 5 | **无限派发** | 领卡即重置计数,可无限重试 | `dispatch_count` 仅在派发时 +1,耗尽同时拦截 claim / dispatch |
54
55
  | 6 | **自证式复核** | 同一 Agent 既实现又审批 | 内置 `auditor` 角色 + 独立合同,裁定严格三档 |
@@ -170,9 +171,9 @@ flowchart TB
170
171
 
171
172
  | 能力 | Carlos Flow | 原生 MCP Server | 提示词 / 手写脚本 |
172
173
  |------|-------------|-----------------|------------------|
173
- | 越界拦截 | ✅ 运行时 `git diff` 级 | ❌ | ❌ 靠自觉 |
174
+ | 越界拦截 | ✅ 自己跑 `git diff`;执行者动了 scope 外的文件 → **阻断 PASS** | ❌ | ❌ 靠自觉 |
174
175
  | 真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
175
- | 防篡改审计 | ✅ SHA-256 链式哈希 | ❌ | ❌ |
176
+ | 审计链完整性 | ✅ 链式哈希(+ 可选 HMAC 密钥) | ❌ | ❌ |
176
177
  | 可控免检 | ✅ 显式开启 + 自动清零 | ❌ | ❌ 一句话全关 |
177
178
  | 诚实派发配额 | ✅ 只计派发 | ❌ | ❌ |
178
179
  | 独立复核 | ✅ 内置 `auditor` 角色 | ❌ | ❌ 可选 |
@@ -325,7 +326,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
325
326
  | `CARLOS_FLOW_HOME` | `~/.carlos-flow` | 状态 / 审计 / 快照目录。`~` 会被展开 |
326
327
  | `CARLOS_FLOW_MCP_ROOT` | 自动推导 | 源码安装时指向仓库根目录 |
327
328
  | `BRIDGE_PORT` | `19099` | Cindy Bridge 监听端口 |
328
- | `CARLOS_BRIDGE_TOKEN` | 内置默认值 | Bridge 本地认证 token |
329
+ | `CARLOS_BRIDGE_TOKEN` | 随机生成落盘 | Bridge 本地认证 token(自动生成,存 0600) |
330
+ | `CARLOS_FLOW_AUDIT_KEY` | — | 设置它(≥16 字符)启用 **HMAC** 审计链 —— 发现**有意篡改**必须配它 |
329
331
  | `CARLOS_BRIDGE_TIMEOUT_MS` | `180000` | Bridge 请求超时(需 > 服务端 120s 验证上限) |
330
332
  | `CARLOS_MCP_TIMEOUT_MS` | `180000` | CLI 客户端 MCP 调用超时 |
331
333
  | `CARLOS_TRIGGER_MESSAGE` | — | CLI 模式下注入触发检查用的用户原话 |
@@ -333,6 +335,69 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
333
335
 
334
336
  ---
335
337
 
338
+ ## 🛡️ 门禁体系 —— 门禁自己也要被门禁
339
+
340
+ > 「项目说自己有门禁」是最容易说的一句话,也最容易被证伪。
341
+ > 所以本项目的门禁**自己也有一套门禁**,且分两类:
342
+
343
+ ### 一、静态一致性(东西对不对得上)
344
+
345
+ | 脚本 | 查什么 |
346
+ |------|--------|
347
+ | `npm run check:full` | 旧引用 / 个人路径 / 版本号一致性 / 文档死链 / npm 发布集合 / 模板占位符 / package.json 字段 / 双仓残留 / ghost.json 工具清单 |
348
+ | `npm run check:identity` | 身份、版本、文档、产物、安全五类一致性 |
349
+ | `npm run check:lang` | 提交信息与源码注释是否中文(产物语言体检) |
350
+ | `npm run check:readme` | 中英双语 README 是否漂移 |
351
+ | `npm run check:anchors` | 变异体的注入锚点是否仍能命中(防止测试**静默失去守护作用**) |
352
+
353
+ ### 二、行为兑现(说了的做到了吗)—— 这一类才是关键
354
+
355
+ | 脚本 | 查什么 | 为什么需要 |
356
+ |------|--------|-----------|
357
+ | `npm run check:claims` | README/工具描述里的每个能力声明,是否都有对应的代码路径 | 静态检查查不出「承诺 vs 实现」的落差 |
358
+ | `npm run check:params` | `inputSchema` 声明的每个参数,是否在 handler 里**真的被读取**;以及有没有「算出却从未使用」的死变量 | 静默失效型 bug(如 `date` 参数)不报错、测试全绿,只是安静地返回错数据 |
359
+ | `npm run check:no-dead-handler` | 同一 request schema 是否被**重复注册** | 重复注册时后注册的覆盖先注册的 → 先注册的是永不执行的死代码,靠注册顺序维持的正确性会被一次重排静默破坏 |
360
+
361
+ ### 三、变异测试 —— 用注入退化撞自己最自豪的代码
362
+
363
+ ```bash
364
+ npm run test:mutation # 17 类变异体,必须 17/17 全部被抓住
365
+ ```
366
+
367
+ 变异体不是随机造的,每一条都对应一个**真实退化**,且必须有测试能抓住它:
368
+
369
+ | 变异体 | 注入的退化 | 抓住它的测试 |
370
+ |--------|-----------|-------------|
371
+ | M1 | 激活只打印日志、不真的激活 | e2e |
372
+ | M2 / M3 | claim / verdict 的闸门失效 | e2e |
373
+ | M4 | 会话撞名(清洗后同形共用状态) | trigger |
374
+ | M5 / M6 | scope 不算补齐项 / 半补齐绕过 | e2e |
375
+ | M7 | 空 scope 退回 fail-open | e2e |
376
+ | M8 | 未派发可记 PASS | e2e |
377
+ | M9 | 闸门派生回退(用上一轮 pending 传递) | e2e 19d-3 |
378
+ | M10 / M11 | 普通卡也上闸 / 占位卡硬编码三项 | e2e |
379
+ | M12 | 跨进程锁失效(`wx` → `a`) | concurrency |
380
+ | M13 | 只读意图误判 | trigger |
381
+ | **M14** | **审计链断链**(去掉 prevHash 链接) | audit-chain |
382
+ | **M15** | **审计链校验恒真** | audit-chain |
383
+ | **M16** | **越界检查退回 fail-open** | scope-enforcement |
384
+ | **M17** | **date 参数失效** | audit-chain |
385
+
386
+ ### 四、专项真实验证(不靠 mock)
387
+
388
+ | 脚本 | 验什么 |
389
+ |------|--------|
390
+ | `npm run test:scope` | 在**真实 git 仓库**里改文件 → scope 外改动**真的被阻断**;派发前就有的改动**不误伤** |
391
+ | `npm run test:audit` | **真实篡改**审计记录 → hmac 模式必须发现;plain 模式如实标注局限;legacy 记录不误报;date 参数真的生效 |
392
+ | `npm run test:bridge` | 端口上是**别人的 bridge** 时不得复用(否则状态会写到别人的 HOME) |
393
+ | `npm run test:package` | `npm pack` → 装到干净目录 → 从 `node_modules` 拉起 MCP server 走真实握手 |
394
+ | `npm run test:lang` | 语言体检脚本**真的能抓到英文**(防假绿) |
395
+
396
+ > 💡 **给质疑者的可执行入口**:上面每一条命令都可以自己跑一遍。
397
+ > 一个项目宣称「我的门禁是机械的」,最好的证明不是文档,是**让对方自己跑一遍**。
398
+
399
+ ---
400
+
336
401
  ## 🧪 开发
337
402
 
338
403
  ```bash
@@ -378,6 +443,8 @@ npm pack
378
443
  | [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | 智能触发引擎深度指南(配置、评分、激活、反馈学习) |
379
444
  | [CHANGELOG.md](./CHANGELOG.md) | 版本历史(Keep a Changelog + SemVer) |
380
445
  | [MIGRATION.md](./MIGRATION.md) | 从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移 |
446
+ | [AGENTS.md](./AGENTS.md) | 变更前置索引:改哪类东西先读哪份权威契约 |
447
+ | [docs/AUDIT_REVIEW.md](./docs/AUDIT_REVIEW.md) | 第三方审查报告的逐条核实与决策记录 |
381
448
  | [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) | 第三方只读验收(13/13 变异体全抓住) |
382
449
  | [变异测试报告](./docs/MUTATION_REPORT_v2.5.5.md) | 变异体注入细节与结果 |
383
450
 
package/TRIGGER_GUIDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Carlos Flow 智能触发引擎使用指南
2
2
 
3
- > **版本**: v2.6.3
3
+ > **版本**: v2.7.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.7.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