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/AGENTS.md +101 -0
- package/CHANGELOG.md +368 -255
- package/MIGRATION.md +162 -5
- package/README.en.md +79 -10
- package/README.md +89 -11
- package/README.zh.md +89 -11
- package/TRIGGER_GUIDE.md +2 -2
- package/bridge/mcp-bridge.js +15 -1
- package/client/carlos.js +122 -11
- package/ghost.json +18 -1
- package/package.json +10 -3
- package/plugins/carlos-flow-trigger.js +215 -215
- package/scripts/check-claims.mjs +188 -0
- package/scripts/check-no-dead-handler.mjs +88 -0
- package/scripts/check-params.mjs +188 -0
- package/scripts/clean-readme-noise.mjs +53 -53
- package/scripts/lang-audit.mjs +164 -164
- package/scripts/mutation-check.mjs +435 -392
- package/scripts/sync-readme.mjs +102 -102
- package/scripts/verify-activation-e2e.sh +55 -55
- package/src/card.js +288 -288
- package/src/dispatch.js +451 -252
- package/src/index.js +1411 -1252
- package/src/protocol.js +76 -76
- package/src/state.js +288 -21
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
|
-
>
|
|
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
|
-
|
|
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) —
|
|
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` |
|
|
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
|
|
|
@@ -171,9 +173,9 @@ flowchart TB
|
|
|
171
173
|
|
|
172
174
|
| Capability | Carlos Flow | Native MCP Server | Prompts / Scripts |
|
|
173
175
|
|------------|-------------|-------------------|-------------------|
|
|
174
|
-
| Scope enforcement | ✅
|
|
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 (
|
|
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 | — |
|
|
@@ -328,7 +331,8 @@ Path: `$CARLOS_FLOW_HOME/trigger-config.json` (auto-generated by `init`)
|
|
|
328
331
|
| `CARLOS_FLOW_HOME` | `~/.carlos-flow` | State / audit / snapshot directory. `~` is expanded |
|
|
329
332
|
| `CARLOS_FLOW_MCP_ROOT` | auto-derived | Repo root for source installs |
|
|
330
333
|
| `BRIDGE_PORT` | `19099` | Cindy Bridge listening port |
|
|
331
|
-
| `CARLOS_BRIDGE_TOKEN` |
|
|
334
|
+
| `CARLOS_BRIDGE_TOKEN` | random file | Local Bridge auth token (auto-generated, stored 0600) |
|
|
335
|
+
| `CARLOS_FLOW_AUDIT_KEY` | — | Set it (≥16 chars) to enable **HMAC** audit chain — required to detect *intentional* tampering |
|
|
332
336
|
| `CARLOS_BRIDGE_TIMEOUT_MS` | `180000` | Bridge request timeout (must exceed the server's 120s verify limit) |
|
|
333
337
|
| `CARLOS_MCP_TIMEOUT_MS` | `180000` | CLI client MCP call timeout |
|
|
334
338
|
| `CARLOS_TRIGGER_MESSAGE` | — | Inject the user's original message for CLI trigger checks |
|
|
@@ -336,6 +340,71 @@ Path: `$CARLOS_FLOW_HOME/trigger-config.json` (auto-generated by `init`)
|
|
|
336
340
|
|
|
337
341
|
---
|
|
338
342
|
|
|
343
|
+
## 🛡️ The Gate System — the gates are gated too
|
|
344
|
+
|
|
345
|
+
> "This project has gates" is the easiest thing to say and the easiest thing to disprove.
|
|
346
|
+
> So the gates **themselves have gates**, in two categories:
|
|
347
|
+
|
|
348
|
+
### 1. Static consistency (do the pieces agree?)
|
|
349
|
+
|
|
350
|
+
| Script | What it checks |
|
|
351
|
+
|--------|----------------|
|
|
352
|
+
| `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 |
|
|
353
|
+
| `npm run check:identity` | Identity, version, docs, artifacts, security |
|
|
354
|
+
| `npm run check:lang` | Commit messages and source comments are Chinese |
|
|
355
|
+
| `npm run check:readme` | Bilingual READMEs have not drifted |
|
|
356
|
+
| `npm run check:anchors` | Mutation anchors still hit (so tests can't **silently lose their guarding power**) |
|
|
357
|
+
|
|
358
|
+
### 2. Behavioral fidelity (does the code do what it claims?) — this is the key one
|
|
359
|
+
|
|
360
|
+
| Script | What it checks | Why it exists |
|
|
361
|
+
|--------|----------------|--------------|
|
|
362
|
+
| `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* |
|
|
363
|
+
| `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 |
|
|
364
|
+
| `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 |
|
|
365
|
+
|
|
366
|
+
### 3. Mutation testing — aim the injection at the code you're proudest of
|
|
367
|
+
|
|
368
|
+
```bash
|
|
369
|
+
npm run test:mutation # 17 mutants, all 17 must be caught
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
Each mutant corresponds to a **real regression** and must be caught by a real test:
|
|
373
|
+
|
|
374
|
+
| Mutant | Injected regression | Test that catches it |
|
|
375
|
+
|--------|---------------------|----------------------|
|
|
376
|
+
| M1 | Activation only logs, never activates | e2e |
|
|
377
|
+
| M2 / M3 | claim / verdict gates removed | e2e |
|
|
378
|
+
| M4 | Session name collision | trigger |
|
|
379
|
+
| M5 / M6 | scope not a required field / half-fill bypass | e2e |
|
|
380
|
+
| M7 | Empty scope falls back to fail-open | e2e |
|
|
381
|
+
| M8 | PASS without dispatch | e2e |
|
|
382
|
+
| M9 | Gate derivation falls back to previous pending | e2e 19d-3 |
|
|
383
|
+
| M10 / M11 | Normal card also gated / hardcoded three fields | e2e |
|
|
384
|
+
| M12 | Cross-process lock loses exclusivity | concurrency |
|
|
385
|
+
| M13 | Read-only intent misjudged | trigger |
|
|
386
|
+
| **M14** | **Audit chain unlinked** (prevHash removed) | audit-chain |
|
|
387
|
+
| **M15** | **Chain verification always returns ok** | audit-chain |
|
|
388
|
+
| **M16** | **Scope check falls back to fail-open** | scope-enforcement |
|
|
389
|
+
| **M17** | **date parameter silently dead** | audit-chain |
|
|
390
|
+
|
|
391
|
+
### 4. Real end-to-end verifications (no mocks)
|
|
392
|
+
|
|
393
|
+
| Script | What it proves |
|
|
394
|
+
|--------|----------------|
|
|
395
|
+
| `npm run test:scope` | In a **real git repo**, editing a file outside scope is **actually blocked**; pre-existing edits are **not** misjudged |
|
|
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 |
|
|
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) |
|
|
399
|
+
| `npm run test:package` | `npm pack` → install into a clean dir → launch the MCP server from `node_modules` and do a real handshake |
|
|
400
|
+
| `npm run test:lang` | The language audit really **catches** English (guards against a false green) |
|
|
401
|
+
|
|
402
|
+
> 💡 **An executable entry point for skeptics**: every command above can be run by anyone.
|
|
403
|
+
> When a project claims "my gates are mechanical", the best proof isn't documentation —
|
|
404
|
+
> it's **letting the skeptic run it**.
|
|
405
|
+
|
|
406
|
+
---
|
|
407
|
+
|
|
339
408
|
## 🧪 Development
|
|
340
409
|
|
|
341
410
|
```bash
|
package/README.md
CHANGED
|
@@ -35,8 +35,14 @@ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校
|
|
|
35
35
|
|
|
36
36
|
- 越界?→ 运行时 `git diff` 对比卡片白名单,**直接阻断派发**
|
|
37
37
|
- 说测试通过?→ 真实 `spawn` 执行 `verify.cmd`,**记 PASS 前必须有通过的 exitCode**
|
|
38
|
-
- 审计日志?→
|
|
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 | **可洗白审计** | 普通文件日志 —— 可删可改 |
|
|
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) —
|
|
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` |
|
|
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
|
-
| 越界拦截 | ✅
|
|
180
|
+
| 越界拦截 | ✅ 自己跑 `git diff`;执行者动了 scope 外的文件 → **阻断 PASS** | ❌ | ❌ 靠自觉 |
|
|
174
181
|
| 真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
|
|
175
|
-
|
|
|
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 工具参考(
|
|
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` |
|
|
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
|
|