carlos-flow 2.7.0 → 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/MIGRATION.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  **从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移到 `carlos-flow`**
4
4
 
5
- > **版本**:v2.6.0
6
- > **适用**:从 ≤ 2.5.9 的双包架构升级到 2.6.0 单包架构
7
- > **预计耗时**:5 分钟
5
+ > **版本**:v2.7.0
6
+ > **适用**:① 从 ≤ 2.5.9 的双包架构升级到单包架构(包迁移)② 从 v2.6.x 升级到 v2.7.x(状态迁移,见下文)
7
+ > **预计耗时**:5 分钟(包迁移)/ 0 分钟(状态迁移自动完成)
8
8
 
9
9
  ---
10
10
 
@@ -164,6 +164,8 @@ carlos-flow flow_status '{"sessionId":"x"}'
164
164
  | 触发器配置 | `$CARLOS_FLOW_HOME/trigger-config.json` | ✅ 无影响(合并语义不变) |
165
165
 
166
166
  > **默认 `CARLOS_FLOW_HOME` 是 `~/.carlos-flow`** —— 与旧版一致,无需任何配置变更。
167
+ >
168
+ > **⚠️ 审计链上早版本的历史断点**:上表「审计链 ✓ 无影响」指的是**文件不会丢**;但 v2.7.0 修复了跨天链接,升级前写入的文件每天第一条的 `prevHash` 是零值,该历史断点**永久保留**。详见「状态迁移」章节。
167
169
 
168
170
  ### ⚠️ 一个可选的变量命名变化
169
171
 
@@ -196,8 +198,9 @@ carlos-flow flow_status '{"sessionId":"x"}'
196
198
  <details>
197
199
  <summary><b>Q: 升级会不会丢审计链?</b></summary>
198
200
 
199
- 不会。审计链是文件追加式的(`gate-audit/YYYY-MM-DD.jsonl`),`prevHash` 从磁盘尾部读取,
200
- 与进程数、版本无关。升级后继续追加,链不会断。
201
+ 不会丢。审计链是文件追加式的(`gate-audit/YYYY-MM-DD.jsonl`),升级后继续追加。
202
+ 但注意:v2.7.0 修复了「跨天断链」——升级前写入的文件每天第一条的 `prevHash` 是零值,
203
+ 这个历史断点永久保留(详见「状态迁移」章节)。升级后新记录自动正确串联。
201
204
  </details>
202
205
 
203
206
  <details>
@@ -234,6 +237,160 @@ rm -rf ~/.carlos-flow
234
237
 
235
238
  ---
236
239
 
240
+ ## 🔄 状态迁移:v2.6.x → v2.7.x(自动,无需手工操作)
241
+
242
+ v2.7.0 对**状态文件**和**审计链**做了若干行为变更。除特别说明外,**全部自动完成**,
243
+ 升级后无需手工干预。以下逐项说明「变了什么 / 历史数据会怎样 / 需要你做什么」。
244
+
245
+ ### 1. 审计链:跨天链接修复,历史断点永久保留
246
+
247
+ **变了什么**:v2.7.0 之前,`audit()` 只在**当天**文件内成链——每天第一条记录的
248
+ `prevHash` 是零值(`0000…`),昨天最后一条的 `hash` 没有传给今天。
249
+ 这意味着跨天的链完整性无法验证(篡改昨天的记录,今天默认校验查不出)。
250
+
251
+ v2.7.0 起,`audit()` 用 `nextPrevHash(localDate())` 取「当天 tail,没有则往前找最近
252
+ 一天的 tail」,`verifyAuditChain({fullChain:true})` 逐天串联验证。
253
+
254
+ **历史数据会怎样**:**升级前写入的审计文件不会被改写,其跨天断点永久保留**。
255
+ 升级后跑 `verifyAuditChain({fullChain:true})`,你会看到升级前的日期
256
+ `dayBroken: 1`(每天第一条的 prevHash 对不上前一天 tail)——
257
+ **这是历史事实,不是新故障**。修复只对升级后的新记录生效。
258
+
259
+ **需要你做什么**:
260
+
261
+ - 不需要任何操作。新记录自动正确串联。
262
+ - 如果你需要一条「全链无断点」的干净记录,可归档旧文件:
263
+
264
+ ```bash
265
+ mkdir -p ~/.carlos-flow/gate-audit/archive
266
+ mv ~/.carlos-flow/gate-audit/2026-11-0*.jsonl ~/.carlos-flow/gate-audit/archive/
267
+ ```
268
+
269
+ 归档后 `fullChain` 只验证保留的文件;被归档文件不再参与校验。
270
+ - **不要**手工改写历史文件去「补链」——那等于伪造证据,与审计链的目的相悖。
271
+
272
+ ### 2. state.json:schemaVersion 与自动迁移(v0 → v1)
273
+
274
+ **变了什么**:v2.7.0 的 `state.json` 新增 `schemaVersion` 字段(当前 = 1),
275
+ `loadState()` 会先跑 `migrate()` 再合并默认值。旧版没有版本号,
276
+ 靠 `{...defaultState(), ...parsed}` 防御性合并——改字段名时旧字段会被静默丢弃。
277
+
278
+ **历史数据会怎样**:**自动迁移,无感**。旧 state.json(无 schemaVersion,视为 v0)
279
+ 在下次 `loadState()` 时被补上:
280
+
281
+ - `schemaVersion: 1`
282
+ - `dispatch_baseline: []`(无基线 → 裁定走全量判定,更保守)
283
+ - `activation_pending: []` / `activation_activated: false`
284
+
285
+ **需要你做什么**:不需要。迁移是只增不删的(旧字段原样保留)。
286
+ 若你想确认迁移生效:
287
+
288
+ ```bash
289
+ node client/carlos.js flow_status '{"sessionId":"<你的会话>"}'
290
+ ```
291
+
292
+ ### 3. 敏感信息脱敏:只影响新写入,历史文件不自动清理
293
+
294
+ **变了什么**:v2.7.0 起,`audit()` 的字段与 `saveState()` 的状态在**落盘前**
295
+ 经 `sanitizeFields()` 脱敏:key 命中 `secret/key/password/pwd/token/credential/auth`,
296
+ 或 value 含 `sk_|secret=|password=|token=|api_key=|sk_live|sk_test` 时,
297
+ 只留掩码(≤8 字符 → `[脱敏]`;否则头尾各 4 位 + `***`)。
298
+
299
+ **历史数据会怎样**:**已在磁盘上的旧 state.json / 审计文件不会被自动改写**。
300
+ 如果 v2.6.x 时期有密钥明文落盘,它们仍在原处。
301
+
302
+ **需要你做什么**(可选):
303
+
304
+ - 想彻底清理历史明文:删除对应会话状态目录(该会话需重新建卡):
305
+
306
+ ```bash
307
+ rm -rf ~/.carlos-flow/gate-state/runs/<sid>
308
+ ```
309
+
310
+ 或手动编辑 `~/.carlos-flow/gate-state/runs/<sid>/state.json`。
311
+ - 审计文件同理,可按日期归档/删除。
312
+
313
+ ### 4. Bridge Token:硬编码默认值已移除
314
+
315
+ **变了什么**:v2.6.x 的客户端内置硬编码默认 token(`carlos-local-token-2026`)。
316
+ v2.7.0 改为:优先读 `CARLOS_BRIDGE_TOKEN`;未设置则**首次运行生成 256 位随机
317
+ token** 落盘 `$CARLOS_FLOW_HOME/bridge-token`(权限 0600),跨进程复用。
318
+
319
+ **历史数据会怎样**:升级后首次运行 bridge/客户端会生成新 token。
320
+ **旧的硬编码 token 立即失效**。
321
+
322
+ **需要你做什么**:
323
+
324
+ - 重启 bridge(Cindy 侧重启即生效;OpenCode 侧重启 OpenCode)。
325
+ - 若你在多进程/多机环境共用 token,显式设置 `CARLOS_BRIDGE_TOKEN` 并重启所有进程。
326
+
327
+ ### 5. 无需迁移的部分
328
+
329
+ | 数据 | 说明 |
330
+ |------|------|
331
+ | 任务卡 / 派发计数 / 裁定结果 | 字段结构未变,原地可用 |
332
+ | 快照 `snapshots/` | 无影响 |
333
+ | 触发历史 `trigger-state/` | 无影响 |
334
+ | 触发配置 `trigger-config.json` | 合并语义不变 |
335
+ | `CARLOS_FLOW_HOME` 路径 | 仍为 `~/.carlos-flow` |
336
+
337
+ ---
338
+
339
+ ## 📋 全维度诊断 20 项处置台账
340
+
341
+ > 来源:第三方「全维度补位」诊断(基线 v2.6.2)。本表逐条记录 v2.7.0 的处置结论。
342
+ > 计数口径:架构盲区 6 项 + 工程缺口 11 行(其中第 2 行与盲区 1 同源)+ 文档不同步 4 项
343
+ > = 21 行,去重后 **20 项**。
344
+
345
+ ### A. 架构级盲区(6 项)
346
+
347
+ | # | 诊断项 | v2.7.0 处置 | 结论 |
348
+ |---|--------|------------|------|
349
+ | 1 | 审计链跨天断链、跨天篡改不可见 | `audit()` 改用 `nextPrevHash(localDate())`;`verifyAuditChain` 全链逐天串联 | ✅ 已修(T-88) |
350
+ | 2 | 审计链无密钥 = 无防篡改 | 新增 HMAC 模式(`CARLOS_FLOW_AUDIT_KEY`);未设密钥降级 `plain` 并回传 `mode` 字段 | ✅ 已修(T-80) |
351
+ | 3 | 敏感信息明文落盘 | `audit()` / `saveState()` 落盘前 `sanitizeFields()` 脱敏 | ✅ 已修(T-89) |
352
+ | 4 | Bridge 仅绑 127.0.0.1,同机任意进程可连 | 硬编码默认 Token 已移除(T-82);IP 白名单/mTLS/请求签名超出当前威胁模型(本机信任) | ⏸️ 不改 |
353
+ | 5 | 无可观测性导出(metrics/tracing/优雅关闭) | `/health` 保留;metrics/tracing 属 P3 运维增强,不在核心门禁边界内 | ⏸️ 不改 |
354
+ | 6 | 状态 schema 无版本号、无迁移机制 | 新增 `schemaVersion=1` + `migrate()`(v0→v1 自动补字段) | ✅ 已修 |
355
+
356
+ ### B. 工程成熟度缺口(11 行,去重后 10 项)
357
+
358
+ | # | 诊断项 | v2.7.0 处置 | 结论 |
359
+ |---|--------|------------|------|
360
+ | 1 | 跨平台路径规范化 | `expandHome()` 已解决 `~` 展开;scope 跨平台误判未复现 | ⏸️ 不改 |
361
+ | 2 | 审计链跨文件不链接 | 同盲区 1 | ✅ 已修(同源) |
362
+ | 3 | legacy 记录误报 | legacy 记录只计数、不重置 `prev` | ✅ 已修(T-81) |
363
+ | 4 | 时间戳可伪造 | 本地时钟是信任边界;hash 链仍约束代际关系 | ⏸️ 不改 |
364
+ | 5 | 无磁盘配额/轮转 | P2 运维项,不在代码门禁范围 | ⏸️ 不改 |
365
+ | 6 | 命令注入面(`verify.cmd`) | 用户自建卡片属信任边界;文档已声明 | ⏸️ 不改 |
366
+ | 7 | 无 i18n | P3,中/英 README 已覆盖主要用户 | ⏸️ 不改 |
367
+ | 8 | 无数据备份/恢复 | P2 运维项(`flow_revert_plan` 仅流程级) | ⏸️ 不改 |
368
+ | 9 | 无幂等键设计 | 不在核心风险面 | ⏸️ 不改 |
369
+ | 10 | 并发保护不全(无原子 CAS) | 跨进程排他锁已有;CAS 属增强 | ⏸️ 不改 |
370
+ | 11 | CHANGELOG 缺破坏性变更记录 | v2.7.0 CHANGELOG 含 T-80~T-89 破坏性变更 | ✅ 已修 |
371
+
372
+ ### C. 文档与实现不同步(4 项)
373
+
374
+ | # | 诊断项 | v2.7.0 处置 | 结论 |
375
+ |---|--------|------------|------|
376
+ | 1 | SECURITY「无硬编码密钥」vs 客户端硬编码 token | 硬编码默认值已删除,改随机生成落盘 | ✅ 已修(T-82) |
377
+ | 2 | SECURITY 版本表缺当前版本 | 补 `2.7.x ✅ 活跃维护` | ✅ 已修 |
378
+ | 3 | README「跨平台单包」vs `path.normalize` | 文档保留;风险未复现 | ⏸️ 不改 |
379
+ | 4 | MIGRATION.md 无状态迁移章节 | 本章节即修复 | ✅ 已修 |
380
+
381
+ ### 处置统计
382
+
383
+ | 结论 | 项数 | 说明 |
384
+ |------|------|------|
385
+ | ✅ 已修 | 9 项 | 架构 4(盲区 1/2/3/6)+ 工程 2(缺口 3/11)+ 文档 3(不同步 1/2/4);另盲区 1 与缺口 2 同源合并 |
386
+ | ⏸️ 不改 | 11 项 | 均在当前攻击面 / 承诺边界之外,成本收益不匹配;如未来威胁模型扩展(多用户/多机)再评估 |
387
+
388
+ > **一句话**:20 项中**能修的都修了**(且都有对应测试或门禁守护);
389
+ > 剩下 11 项不是「忘了」,而是**评估后判定不属于本项目的核心承诺边界**——
390
+ > 与其堆功能,不如把边界写清楚。
391
+
392
+ ---
393
+
237
394
  ## 🔗 相关链接
238
395
 
239
396
  | | |
package/README.en.md CHANGED
@@ -38,6 +38,8 @@ Carlos Flow takes the opposite approach: **every constraint is enforced at runti
38
38
  - Audit log? → SHA-256 **chained hashes** (`prevHash` → `hash`); **change one and the chain breaks**
39
39
  - Want to skip? → Bypass needs explicit `confirmed=true`, and **auto-clears on every dispatch**
40
40
 
41
+ After `audit()` and `saveState()` field values (verify.cmd/token/password) are sanitized;
42
+ no key fragment is stored in plain.
41
43
  **In one line**: it brings code-review gates to AI agents — and the gates are executed by machines, not humans.
42
44
 
43
45
  ---
@@ -48,7 +50,7 @@ Carlos Flow takes the opposite approach: **every constraint is enforced at runti
48
50
  |---|---------|------------|-------------------------------|
49
51
  | 1 | **Out-of-scope edits** | "Only these files" is advice, not a rule | `enforceScope()` compares `git diff` to the whitelist at runtime — out-of-scope **blocks dispatch** |
50
52
  | 2 | **Verification theater** | Agent self-reports "tests passed"; no proof | `runVerifyCommand()` really executes, capturing stdout/stderr/exitCode; **no evidence → no PASS** |
51
- | 3 | **Mutable audit logs** | Plain files — deletable, editable | SHA-256 chained hashes — **change one and the whole chain breaks** |
53
+ | 3 | **Mutable audit logs** | Plain files — deletable, editable | SHA-256 chained hashes (per-day files, prevHash threaded to previous day's tail, cross-day chain intact) — **change one and the whole chain breaks** |
52
54
  | 4 | **Uncontrolled bypass** | One sentence disables all guards | Requires explicit `confirmed=true` on the card; **auto-cleared on every dispatch** |
53
55
  | 5 | **Unlimited dispatch** | Claim resets the counter; infinite retries | `dispatch_count` increments only on dispatch; exhaustion blocks both claim and dispatch |
54
56
  | 6 | **Self-certified review** | Same agent implements and approves | Built-in `auditor` role + independent contract, strict three-tier verdict |
@@ -116,11 +118,11 @@ flowchart TB
116
118
  Plugin["plugins/carlos-flow-trigger.js<br/>chat.message hook"]
117
119
  end
118
120
 
119
- subgraph Core["Core MCP Server (src/index.js) — 15 tools"]
121
+ subgraph Core["Core MCP Server (src/index.js) — 16 tools"]
120
122
  Protocol["flow_protocol"]
121
123
  Submit["flow_submit_requirement"]
122
124
  Dispatch["flow_claim / flow_dispatch"]
123
- Verify["flow_run_verify / flow_check_scope"]
125
+ Verify["flow_run_verify / flow_falsify / flow_check_scope"]
124
126
  Verdict["flow_verdict"]
125
127
  Audit["flow_status / flow_audit"]
126
128
  Trigger["flow_trigger_check"]
@@ -156,7 +158,7 @@ flowchart TB
156
158
  |-------|----------|----------------|-------------------|
157
159
  | **Host adapter** | `ghost.json` / `plugins/` / `templates/` | Discovery, launch, config, lifecycle | ⚠️ The **only** platform-specific layer |
158
160
  | **Client** | `client/carlos.js` / `bridge/` | CLI, trigger check, Bridge daemon | Bridge is Cindy-only |
159
- | **Protocol** | `src/index.js` | 15 MCP tools + validation + gate semantics | ✅ Zero coupling, pure standard MCP |
161
+ | **Protocol** | `src/index.js` | 16 MCP tools + validation + gate semantics | ✅ Zero coupling, pure standard MCP |
160
162
  | **Engine** | `src/trigger.js` / `src/card.js` / `src/state.js` | Trigger scoring, card validation, state/audit | ✅ Zero coupling, pure JS, no deps |
161
163
  | **Persistence** | `~/.carlos-flow/` | State, audit chain, snapshots, trigger history | ✅ Cross-platform path convention |
162
164
 
@@ -173,7 +175,7 @@ flowchart TB
173
175
  |------------|-------------|-------------------|-------------------|
174
176
  | Scope enforcement | ✅ Runs `git diff` itself; **blocks PASS** when the executor touched out-of-scope files | ❌ | ❌ Honor system |
175
177
  | Real verification | ✅ spawn + capture; no evidence → no PASS | ❌ | ❌ Agent says so |
176
- | Tamper-proof audit | ✅ SHA-256 chained hashes | ❌ | ❌ |
178
+ | Tamper-proof audit | ✅ SHA-256 chained hashes, cross-day threaded, values sanitized | ❌ | ❌ |
177
179
  | Controlled bypass | ✅ Explicit + auto-cleared | ❌ | ❌ One sentence kills all |
178
180
  | Honest dispatch quota | ✅ Counts only dispatches | ❌ | ❌ |
179
181
  | Independent review | ✅ Built-in `auditor` role | ❌ | ❌ Optional |
@@ -275,7 +277,7 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
275
277
 
276
278
  ---
277
279
 
278
- ## 🔧 MCP Tool Reference (15 tools)
280
+ ## 🔧 MCP Tool Reference (16 tools)
279
281
 
280
282
  | Tool | Purpose | Key constraint |
281
283
  |------|---------|----------------|
@@ -285,9 +287,10 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
285
287
  | `flow_claim` | Claim a dispatch slot (executor / auditor) | Rejected while the activation gate is open |
286
288
  | `flow_dispatch` | Dispatch a sub-agent per the four-part contract | Auto-snapshots files in scope before dispatch |
287
289
  | `flow_save_result` | Save a sub-agent's result | — |
288
- | `flow_run_verify` | **Really execute** `verify.cmd` | Returns exitCode / stdout / stderr |
290
+ | `flow_run_verify` | **Really execute** `verify.cmd` | Returns exitCode / stdout / stderr + `output_hash` |
291
+ | `flow_falsify` | **Negative control**: run `verify.cmd` pre-change (must fail) and post-change (must pass) | Vacuous tests (`|| true`) rejected; required before PASS |
289
292
  | `flow_check_scope` | Check whether files are in scope | Empty scope → fail-closed, everything out of scope |
290
- | `flow_verdict` | Record verdict PASS / DIRECTION / LOCAL | No PASS without dispatch; no PASS without passing verification |
293
+ | `flow_verdict` | Record verdict PASS / DIRECTION / LOCAL | No PASS without dispatch; no PASS without passing verification; **no PASS without a passing negative control** |
291
294
  | `flow_status` | Query gate state | Exposes `activation_pending` / `verify_passed` |
292
295
  | `flow_audit` | Read the audit stream | Includes 6 activation-related event kinds |
293
296
  | `flow_diff_hunks` | Parse `git diff -U0` hunk ranges | — |
@@ -390,7 +393,8 @@ Each mutant corresponds to a **real regression** and must be caught by a real te
390
393
  | Script | What it proves |
391
394
  |--------|----------------|
392
395
  | `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 |
396
+ | `npm run test:audit` | **Actually tampering** with an audit record
397
+ | | cross-day chain must connect; only sanitized values, no key fragment stored | → hmac mode must detect it; plain mode honestly states its limits; legacy records don't cause false alarms; `date` actually works |
394
398
  | `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
399
  | `npm run test:package` | `npm pack` → install into a clean dir → launch the MCP server from `node_modules` and do a real handshake |
396
400
  | `npm run test:lang` | The language audit really **catches** English (guards against a false green) |
package/README.md CHANGED
@@ -38,6 +38,11 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
38
38
  - 审计日志?→ **链式哈希**(`prevHash` → `hash`),改一条全链断裂。
39
39
  设了 `CARLOS_FLOW_AUDIT_KEY` 时用 **HMAC-SHA256**(带密钥)→ 攻击者重算不出,只能发现不能隐藏
40
40
  - 想跳过?→ 免检需显式 `confirmed=true`,且**每次派发自动清零**
41
+ 审计文件按本地日期分片,`prevHash` 一律联动**前一天的 tail**,跨天不断链。
42
+ 未设密钥时(`plain` 模式)走裸 SHA-256:只能防**意外损坏**,
43
+ 不能防有意篡改;`verifyAuditChain()` 的回传带了 `mode` 字段(`plain`/`hmac`),
44
+ 调用方自行判断强度。审计记录(`audit()`)和状态文件(`saveState()`)
45
+ 写之前先脱敏——密钥片段不入盘。
41
46
 
42
47
  **一句话**:它把「代码评审的门禁」搬到了 AI Agent 上,而且门禁本身是机器执行、不是人执行。
43
48
 
@@ -49,7 +54,8 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
49
54
  |---|------|---------|------------------------|
50
55
  | 1 | **越界改动** | "只改这些文件"是建议不是规则 | `enforceScope()` 运行时 `git diff` 比对白名单,越界**阻断派发** |
51
56
  | 2 | **验证表演** | Agent 自述"测试通过",无人能证明 | `runVerifyCommand()` 真实执行,捕获 stdout/stderr/exitCode;**无验证证据不许记 PASS** |
52
- | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | 链式哈希审计,**改一条全链断裂**;配 `CARLOS_FLOW_AUDIT_KEY` 启用 HMAC 后,**攻击者没有密钥就无法重算掩盖** |
57
+ | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | 链式哈希审计,**改一条全链断裂**;跨天链联动前一天 tail;**审计记录与落盘状态均脱敏后写**;
58
+ 配 `CARLOS_FLOW_AUDIT_KEY` 启用 HMAC 后,**攻击者没有密钥就无法重算掩盖** |
53
59
  | 4 | **失控免检** | 一句话关闭所有防护 | 需卡片显式 `confirmed=true`,**每次派发自动清零** |
54
60
  | 5 | **无限派发** | 领卡即重置计数,可无限重试 | `dispatch_count` 仅在派发时 +1,耗尽同时拦截 claim / dispatch |
55
61
  | 6 | **自证式复核** | 同一 Agent 既实现又审批 | 内置 `auditor` 角色 + 独立合同,裁定严格三档 |
@@ -117,11 +123,11 @@ flowchart TB
117
123
  Plugin["plugins/carlos-flow-trigger.js<br/>chat.message 钩子"]
118
124
  end
119
125
 
120
- subgraph Core["核心 MCP Server (src/index.js) — 15 个工具"]
126
+ subgraph Core["核心 MCP Server (src/index.js) — 16 个工具"]
121
127
  Protocol["flow_protocol"]
122
128
  Submit["flow_submit_requirement"]
123
129
  Dispatch["flow_claim / flow_dispatch"]
124
- Verify["flow_run_verify / flow_check_scope"]
130
+ Verify["flow_run_verify / flow_falsify / flow_check_scope"]
125
131
  Verdict["flow_verdict"]
126
132
  Audit["flow_status / flow_audit"]
127
133
  Trigger["flow_trigger_check"]
@@ -157,7 +163,7 @@ flowchart TB
157
163
  |----|------|------|---------|
158
164
  | **宿主适配层** | `ghost.json` / `plugins/` / `templates/` | 发现、启动、配置、生命周期 | ⚠️ 唯一有平台差异的层 |
159
165
  | **客户端层** | `client/carlos.js` / `bridge/` | CLI、触发检查、Bridge 守护 | 仅 Cindy 需要 Bridge |
160
- | **协议层** | `src/index.js` | 15 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
166
+ | **协议层** | `src/index.js` | 16 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
161
167
  | **引擎层** | `src/trigger.js` / `src/card.js` / `src/state.js` | 触发评分、卡片校验、状态/审计 | ✅ 零耦合,纯 JS 无依赖 |
162
168
  | **持久化层** | `~/.carlos-flow/` | 状态、审计链、快照、触发历史 | ✅ 跨平台路径约定 |
163
169
 
@@ -173,7 +179,7 @@ flowchart TB
173
179
  |------|-------------|-----------------|------------------|
174
180
  | 越界拦截 | ✅ 自己跑 `git diff`;执行者动了 scope 外的文件 → **阻断 PASS** | ❌ | ❌ 靠自觉 |
175
181
  | 真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
176
- | 审计链完整性 | ✅ 链式哈希(+ 可选 HMAC 密钥) | ❌ | ❌ |
182
+ | 审计链完整性 | ✅ 链式哈希(+ 可选 HMAC),跨天串联,落盘脱敏 | ❌ | ❌ |
177
183
  | 可控免检 | ✅ 显式开启 + 自动清零 | ❌ | ❌ 一句话全关 |
178
184
  | 诚实派发配额 | ✅ 只计派发 | ❌ | ❌ |
179
185
  | 独立复核 | ✅ 内置 `auditor` 角色 | ❌ | ❌ 可选 |
@@ -185,6 +191,9 @@ flowchart TB
185
191
  > **信任边界说明**:手工改 `state.json` 里的 verdict 能伪造 PASS —— 状态文件不在审计哈希链内。
186
192
  > 这是**本地文件系统权限**的信任边界,不是 MCP 工具面能被绕过的漏洞:
187
193
  > 能写 `CARLOS_FLOW_HOME` 的人本来就能改自己的代码。
194
+ > 还要注意:(1)未设 `CARLOS_FLOW_AUDIT_KEY` 时是 `plain` 模式(裸 SHA-256),
195
+ > **`ok: true` 不是「没被篡改过」的证明**,调用方看 `mode` 字段;
196
+ > (2)审计记录与状态(`verify.cmd`/`token`/`password`)脱敏后入盘,密钥片段不留明文。
188
197
  > 完整说明见 [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) §六。
189
198
 
190
199
  ---
@@ -274,7 +283,7 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
274
283
 
275
284
  ---
276
285
 
277
- ## 🔧 MCP 工具参考(15 个)
286
+ ## 🔧 MCP 工具参考(16 个)
278
287
 
279
288
  | 工具 | 作用 | 关键约束 |
280
289
  |------|------|---------|
@@ -284,9 +293,10 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
284
293
  | `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
285
294
  | `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
286
295
  | `flow_save_result` | 保存子 Agent 执行结果 | — |
287
- | `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 前必做 |
288
298
  | `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
289
- | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发不许 PASS;验证未过不许 PASS |
299
+ | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发不许 PASS;验证未过不许 PASS;**负对照未过不许 PASS** |
290
300
  | `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` |
291
301
  | `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
292
302
  | `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
@@ -389,6 +399,7 @@ npm run test:mutation # 17 类变异体,必须 17/17 全部被抓住
389
399
  |------|--------|
390
400
  | `npm run test:scope` | 在**真实 git 仓库**里改文件 → scope 外改动**真的被阻断**;派发前就有的改动**不误伤** |
391
401
  | `npm run test:audit` | **真实篡改**审计记录 → hmac 模式必须发现;plain 模式如实标注局限;legacy 记录不误报;date 参数真的生效 |
402
+ | | **跨天链**连通不留断点;脱敏检查确保密钥片段不留明文 |
392
403
  | `npm run test:bridge` | 端口上是**别人的 bridge** 时不得复用(否则状态会写到别人的 HOME) |
393
404
  | `npm run test:package` | `npm pack` → 装到干净目录 → 从 `node_modules` 拉起 MCP server 走真实握手 |
394
405
  | `npm run test:lang` | 语言体检脚本**真的能抓到英文**(防假绿) |
package/README.zh.md CHANGED
@@ -38,6 +38,11 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
38
38
  - 审计日志?→ **链式哈希**(`prevHash` → `hash`),改一条全链断裂。
39
39
  设了 `CARLOS_FLOW_AUDIT_KEY` 时用 **HMAC-SHA256**(带密钥)→ 攻击者重算不出,只能发现不能隐藏
40
40
  - 想跳过?→ 免检需显式 `confirmed=true`,且**每次派发自动清零**
41
+ 审计文件按本地日期分片,`prevHash` 一律联动**前一天的 tail**,跨天不断链。
42
+ 未设密钥时(`plain` 模式)走裸 SHA-256:只能防**意外损坏**,
43
+ 不能防有意篡改;`verifyAuditChain()` 的回传带了 `mode` 字段(`plain`/`hmac`),
44
+ 调用方自行判断强度。审计记录(`audit()`)和状态文件(`saveState()`)
45
+ 写之前先脱敏——密钥片段不入盘。
41
46
 
42
47
  **一句话**:它把「代码评审的门禁」搬到了 AI Agent 上,而且门禁本身是机器执行、不是人执行。
43
48
 
@@ -49,7 +54,8 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
49
54
  |---|------|---------|------------------------|
50
55
  | 1 | **越界改动** | "只改这些文件"是建议不是规则 | `enforceScope()` 运行时 `git diff` 比对白名单,越界**阻断派发** |
51
56
  | 2 | **验证表演** | Agent 自述"测试通过",无人能证明 | `runVerifyCommand()` 真实执行,捕获 stdout/stderr/exitCode;**无验证证据不许记 PASS** |
52
- | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | 链式哈希审计,**改一条全链断裂**;配 `CARLOS_FLOW_AUDIT_KEY` 启用 HMAC 后,**攻击者没有密钥就无法重算掩盖** |
57
+ | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | 链式哈希审计,**改一条全链断裂**;跨天链联动前一天 tail;**审计记录与落盘状态均脱敏后写**;
58
+ 配 `CARLOS_FLOW_AUDIT_KEY` 启用 HMAC 后,**攻击者没有密钥就无法重算掩盖** |
53
59
  | 4 | **失控免检** | 一句话关闭所有防护 | 需卡片显式 `confirmed=true`,**每次派发自动清零** |
54
60
  | 5 | **无限派发** | 领卡即重置计数,可无限重试 | `dispatch_count` 仅在派发时 +1,耗尽同时拦截 claim / dispatch |
55
61
  | 6 | **自证式复核** | 同一 Agent 既实现又审批 | 内置 `auditor` 角色 + 独立合同,裁定严格三档 |
@@ -117,11 +123,11 @@ flowchart TB
117
123
  Plugin["plugins/carlos-flow-trigger.js<br/>chat.message 钩子"]
118
124
  end
119
125
 
120
- subgraph Core["核心 MCP Server (src/index.js) — 15 个工具"]
126
+ subgraph Core["核心 MCP Server (src/index.js) — 16 个工具"]
121
127
  Protocol["flow_protocol"]
122
128
  Submit["flow_submit_requirement"]
123
129
  Dispatch["flow_claim / flow_dispatch"]
124
- Verify["flow_run_verify / flow_check_scope"]
130
+ Verify["flow_run_verify / flow_falsify / flow_check_scope"]
125
131
  Verdict["flow_verdict"]
126
132
  Audit["flow_status / flow_audit"]
127
133
  Trigger["flow_trigger_check"]
@@ -157,7 +163,7 @@ flowchart TB
157
163
  |----|------|------|---------|
158
164
  | **宿主适配层** | `ghost.json` / `plugins/` / `templates/` | 发现、启动、配置、生命周期 | ⚠️ 唯一有平台差异的层 |
159
165
  | **客户端层** | `client/carlos.js` / `bridge/` | CLI、触发检查、Bridge 守护 | 仅 Cindy 需要 Bridge |
160
- | **协议层** | `src/index.js` | 15 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
166
+ | **协议层** | `src/index.js` | 16 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
161
167
  | **引擎层** | `src/trigger.js` / `src/card.js` / `src/state.js` | 触发评分、卡片校验、状态/审计 | ✅ 零耦合,纯 JS 无依赖 |
162
168
  | **持久化层** | `~/.carlos-flow/` | 状态、审计链、快照、触发历史 | ✅ 跨平台路径约定 |
163
169
 
@@ -173,7 +179,7 @@ flowchart TB
173
179
  |------|-------------|-----------------|------------------|
174
180
  | 越界拦截 | ✅ 自己跑 `git diff`;执行者动了 scope 外的文件 → **阻断 PASS** | ❌ | ❌ 靠自觉 |
175
181
  | 真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
176
- | 审计链完整性 | ✅ 链式哈希(+ 可选 HMAC 密钥) | ❌ | ❌ |
182
+ | 审计链完整性 | ✅ 链式哈希(+ 可选 HMAC),跨天串联,落盘脱敏 | ❌ | ❌ |
177
183
  | 可控免检 | ✅ 显式开启 + 自动清零 | ❌ | ❌ 一句话全关 |
178
184
  | 诚实派发配额 | ✅ 只计派发 | ❌ | ❌ |
179
185
  | 独立复核 | ✅ 内置 `auditor` 角色 | ❌ | ❌ 可选 |
@@ -185,6 +191,9 @@ flowchart TB
185
191
  > **信任边界说明**:手工改 `state.json` 里的 verdict 能伪造 PASS —— 状态文件不在审计哈希链内。
186
192
  > 这是**本地文件系统权限**的信任边界,不是 MCP 工具面能被绕过的漏洞:
187
193
  > 能写 `CARLOS_FLOW_HOME` 的人本来就能改自己的代码。
194
+ > 还要注意:(1)未设 `CARLOS_FLOW_AUDIT_KEY` 时是 `plain` 模式(裸 SHA-256),
195
+ > **`ok: true` 不是「没被篡改过」的证明**,调用方看 `mode` 字段;
196
+ > (2)审计记录与状态(`verify.cmd`/`token`/`password`)脱敏后入盘,密钥片段不留明文。
188
197
  > 完整说明见 [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) §六。
189
198
 
190
199
  ---
@@ -274,7 +283,7 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
274
283
 
275
284
  ---
276
285
 
277
- ## 🔧 MCP 工具参考(15 个)
286
+ ## 🔧 MCP 工具参考(16 个)
278
287
 
279
288
  | 工具 | 作用 | 关键约束 |
280
289
  |------|------|---------|
@@ -284,9 +293,10 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
284
293
  | `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
285
294
  | `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
286
295
  | `flow_save_result` | 保存子 Agent 执行结果 | — |
287
- | `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 前必做 |
288
298
  | `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
289
- | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发不许 PASS;验证未过不许 PASS |
299
+ | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发不许 PASS;验证未过不许 PASS;**负对照未过不许 PASS** |
290
300
  | `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` |
291
301
  | `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
292
302
  | `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
@@ -389,6 +399,7 @@ npm run test:mutation # 17 类变异体,必须 17/17 全部被抓住
389
399
  |------|--------|
390
400
  | `npm run test:scope` | 在**真实 git 仓库**里改文件 → scope 外改动**真的被阻断**;派发前就有的改动**不误伤** |
391
401
  | `npm run test:audit` | **真实篡改**审计记录 → hmac 模式必须发现;plain 模式如实标注局限;legacy 记录不误报;date 参数真的生效 |
402
+ | | **跨天链**连通不留断点;脱敏检查确保密钥片段不留明文 |
392
403
  | `npm run test:bridge` | 端口上是**别人的 bridge** 时不得复用(否则状态会写到别人的 HOME) |
393
404
  | `npm run test:package` | `npm pack` → 装到干净目录 → 从 `node_modules` 拉起 MCP server 走真实握手 |
394
405
  | `npm run test:lang` | 语言体检脚本**真的能抓到英文**(防假绿) |
package/TRIGGER_GUIDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Carlos Flow 智能触发引擎使用指南
2
2
 
3
- > **版本**: v2.7.0
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.7.0
782
+ **版本**: v2.8.0
783
783
  **更新日期**: 2026-11-07
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.7.0",
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.7.0",
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",