carlos-flow 0.0.0-stage → 2.6.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 ADDED
@@ -0,0 +1,468 @@
1
+ # Carlos Flow
2
+
3
+ [![npm](https://img.shields.io/npm/v/carlos-flow.svg)](https://www.npmjs.com/package/carlos-flow)
4
+ [![npm downloads](https://img.shields.io/npm/dm/carlos-flow.svg)](https://www.npmjs.com/package/carlos-flow)
5
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
6
+ [![MCP](https://img.shields.io/badge/MCP-1.29%2B-blue.svg)](https://modelcontextprotocol.io)
7
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
8
+ [![CI](https://img.shields.io/badge/CI-passing-brightgreen.svg)](./.github/workflows/ci.yml)
9
+
10
+ **语言 / Languages:** [中文](README.zh.md) | [English](README.en.md)
11
+
12
+ ---
13
+
14
+ > **AI 编码 Agent 的机械门禁(Mechanical Gate)**
15
+ >
16
+ > 留痕 → 派发 → 验证 → 裁定 → 审计 → 还原
17
+ >
18
+ > 把「相信 Agent」变成「**验证** Agent」——约束写在代码里,不写在提示词里。
19
+
20
+ ---
21
+
22
+ ## 📌 这是什么(TL;DR)
23
+
24
+ Carlos Flow 是一个 **MCP Server**,为 AI 编码 Agent 提供**可执行、可审计、不可自欺**的工作流门禁。
25
+
26
+ 普通 Agent 工作流的问题在于:约束都是**建议性的**。
27
+
28
+ | 你说 | Agent 实际做的 |
29
+ |------|--------------|
30
+ | "只改 `src/auth.py`" | 客气地点头,然后把半个仓库重写了 |
31
+ | "跑一下测试" | 汇报"测试通过",其实根本没跑 |
32
+ | "记录一下过程" | 在普通文件里写几行日志 —— 可删可改 |
33
+
34
+ Carlos Flow 的做法是:**约束全部落在代码里,用运行时事实校验,不信自述。**
35
+
36
+ - 越界?→ 运行时 `git diff` 对比卡片白名单,**直接阻断派发**
37
+ - 说测试通过?→ 真实 `spawn` 执行 `verify.cmd`,**记 PASS 前必须有通过的 exitCode**
38
+ - 审计日志?→ SHA-256 **链式哈希**(`prevHash` → `hash`),**改一条全链断裂**
39
+ - 想跳过?→ 免检需显式 `confirmed=true`,且**每次派发自动清零**
40
+
41
+ **一句话**:它把「代码评审的门禁」搬到了 AI Agent 上,而且门禁本身是机器执行、不是人执行。
42
+
43
+ ---
44
+
45
+ ## 🎯 解决的 8 个真实问题
46
+
47
+ | # | 问题 | 传统现状 | Carlos Flow 的机械化答案 |
48
+ |---|------|---------|------------------------|
49
+ | 1 | **越界改动** | "只改这些文件"是建议不是规则 | `enforceScope()` 运行时 `git diff` 比对白名单,越界**阻断派发** |
50
+ | 2 | **验证表演** | Agent 自述"测试通过",无人能证明 | `runVerifyCommand()` 真实执行,捕获 stdout/stderr/exitCode;**无验证证据不许记 PASS** |
51
+ | 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | SHA-256 链式哈希审计,**改一条全链断裂** |
52
+ | 4 | **失控免检** | 一句话关闭所有防护 | 需卡片显式 `confirmed=true`,**每次派发自动清零** |
53
+ | 5 | **无限派发** | 领卡即重置计数,可无限重试 | `dispatch_count` 仅在派发时 +1,耗尽同时拦截 claim / dispatch |
54
+ | 6 | **自证式复核** | 同一 Agent 既实现又审批 | 内置 `auditor` 角色 + 独立合同,裁定严格三档 |
55
+ | 7 | **改坏无法回退** | 只能手动 `git revert` | 派发前自动快照 → `flow_revert_plan` 生成原子还原计划 |
56
+ | 8 | **每次手动喊话** | 不喊就不启动,忘了就裸奔 | **智能触发引擎**自动识别意图,评分达标才触发并解释命中了什么 |
57
+
58
+ ---
59
+
60
+ ## ✨ 核心亮点
61
+
62
+ ### 1. 零分叉的跨平台架构
63
+ 一套核心 MCP Server,**6 大平台**开箱即用。平台差异只在初始化模板,核心逻辑**零分叉**。
64
+
65
+ ```
66
+ carlos-flow (单一 npm 包)
67
+ ├── src/index.js ← 核心 MCP Server(纯标准协议,零平台耦合)
68
+ ├── client/carlos.js ← CLI + init --target <平台>
69
+ ├── bridge/ ← Cindy 专属:后台常驻 Bridge
70
+ ├── plugins/ ← OpenCode 专属:chat.message 钩子
71
+ └── templates/ ← Cursor / Cline / VS Code / Claude 模板
72
+ ```
73
+
74
+ ### 2. 智能触发引擎 —— 工作流会自己认出该上场的时候
75
+ 三层架构,**每次决策都给出可解释的 breakdown**(命中了哪些词、多少分、为什么)。
76
+
77
+ - **L1 动态上限**:`5 + 会话时长×0.5 + 复杂度×2 − 窗口内已触发×0.3`,封顶 15
78
+ - **L2 三维评分**:关键词 50 / 上下文 30 / 意图 20,加权满分 38
79
+ - **L3 四档决策**:`trigger` / `review` / `ignore` / `throttled`
80
+
81
+ 中文流程词**内置**(工作流/门禁/派发/审计/任务卡/子代理…),普通开发需求**不会误触发**。
82
+
83
+ ### 3. 反自欺的激活闸门
84
+ 自动触发**不等于**直接放行。激活后进入 `activation_pending` 状态:
85
+ 在 `scope` / `acceptance` / `verify.cmd` 补齐之前,`flow_claim` / `flow_dispatch` / `flow_verdict` **一律拒绝**。
86
+
87
+ > 防的是「占位卡 → 直接派发 → 直接记 PASS」的假闭环。
88
+
89
+ ### 4. Fail-closed 语义
90
+ 空 `scope` 判定为**全部越界**(而不是"白名单为空=随便改")。这是安全默认值,不是业务默认值。
91
+
92
+ ### 5. 变异测试守护
93
+ 13 类变异体(注入退化)**13/13 全部被测试抓住**。锚点唯一性由 `npm run check:anchors` 守护,防止测试"静默失去守护作用"。
94
+
95
+ ### 6. 跨进程并发安全
96
+ `flow_submit_requirement` 的读-改-写被包在**跨进程排他锁**里(`mkdir` 原子性)。
97
+ 红队实测 40 轮并发复现 4 次的状态丢失,现在**泄漏 0/453**。
98
+
99
+ ---
100
+
101
+ ## 🏗️ 技术框架
102
+
103
+ ### 整体架构
104
+
105
+ ```mermaid
106
+ flowchart TB
107
+ subgraph Host["宿主 Agent 平台"]
108
+ Cindy[Cindy<br/>ghost.json]
109
+ OpenCode[OpenCode<br/>plugin + .mcprc]
110
+ Cursor[Cursor / Cline<br/>VS Code / Claude]
111
+ end
112
+
113
+ subgraph Client["客户端层"]
114
+ CLI["client/carlos.js<br/>CLI + init + 触发检查"]
115
+ Bridge["bridge/mcp-bridge.js<br/>常驻守护 + Token 认证"]
116
+ Plugin["plugins/carlos-flow-trigger.js<br/>chat.message 钩子"]
117
+ end
118
+
119
+ subgraph Core["核心 MCP Server (src/index.js) — 15 个工具"]
120
+ Protocol["flow_protocol"]
121
+ Submit["flow_submit_requirement"]
122
+ Dispatch["flow_claim / flow_dispatch"]
123
+ Verify["flow_run_verify / flow_check_scope"]
124
+ Verdict["flow_verdict"]
125
+ Audit["flow_status / flow_audit"]
126
+ Trigger["flow_trigger_check"]
127
+ end
128
+
129
+ subgraph Engine["智能触发引擎 (src/trigger.js)"]
130
+ L1["L1 DynamicTriggerManager"]
131
+ L2["L2 TriggerScorer"]
132
+ L3["L3 TriggerDecisionEngine"]
133
+ end
134
+
135
+ subgraph Storage["持久化层 (CARLOS_FLOW_HOME)"]
136
+ State["gate-state/runs/<sid>/"]
137
+ AuditLog["gate-audit/YYYY-MM-DD.jsonl<br/>SHA-256 链式"]
138
+ Snap["snapshots/"]
139
+ TrigState["trigger-state/"]
140
+ end
141
+
142
+ Cindy --> CLI
143
+ OpenCode --> Plugin
144
+ Cursor --> CLI
145
+ Plugin --> Trigger
146
+ CLI --> Bridge
147
+ Bridge --> Core
148
+ Core --> Engine
149
+ Core --> Storage
150
+ Engine --> TrigState
151
+ ```
152
+
153
+ ### 分层职责
154
+
155
+ | 层 | 位置 | 职责 | 平台耦合 |
156
+ |----|------|------|---------|
157
+ | **宿主适配层** | `ghost.json` / `plugins/` / `templates/` | 发现、启动、配置、生命周期 | ⚠️ 唯一有平台差异的层 |
158
+ | **客户端层** | `client/carlos.js` / `bridge/` | CLI、触发检查、Bridge 守护 | 仅 Cindy 需要 Bridge |
159
+ | **协议层** | `src/index.js` | 15 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
160
+ | **引擎层** | `src/trigger.js` / `src/card.js` / `src/state.js` | 触发评分、卡片校验、状态/审计 | ✅ 零耦合,纯 JS 无依赖 |
161
+ | **持久化层** | `~/.carlos-flow/` | 状态、审计链、快照、触发历史 | ✅ 跨平台路径约定 |
162
+
163
+ > **核心设计原则**:MCP 协议是**被动**的 —— 服务端不能主动推送。
164
+ > 因此「自动触发」必须由**能拿到用户消息的那一侧**发起(宿主插件钩子 或 Agent 主动调用 `flow_trigger_check`)。
165
+ > 两条路径共用 `src/trigger.js` 同一份实现,**行为完全一致**。
166
+
167
+ ---
168
+
169
+ ## 📊 能力矩阵
170
+
171
+ | 能力 | Carlos Flow | 原生 MCP Server | 提示词 / 手写脚本 |
172
+ |------|-------------|-----------------|------------------|
173
+ | 越界拦截 | ✅ 运行时 `git diff` 级 | ❌ | ❌ 靠自觉 |
174
+ | 真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
175
+ | 防篡改审计 | ✅ SHA-256 链式哈希 | ❌ | ❌ |
176
+ | 可控免检 | ✅ 显式开启 + 自动清零 | ❌ | ❌ 一句话全关 |
177
+ | 诚实派发配额 | ✅ 只计派发 | ❌ | ❌ |
178
+ | 独立复核 | ✅ 内置 `auditor` 角色 | ❌ | ❌ 可选 |
179
+ | 快照 + 还原 | ✅ 自动、原子计划 | ❌ | ❌ 手动 `git revert` |
180
+ | 守护进程生命周期 | ✅ 全自动(Cindy) | ❌ 手动 | ❌ 手动 |
181
+ | 智能触发 | ✅ 三层评分 + 可解释决策 | ❌ | ❌ |
182
+ | 跨平台 | ✅ 单一包 6 平台 | ⚠️ 需自己写配置 | ❌ |
183
+
184
+ > **信任边界说明**:手工改 `state.json` 里的 verdict 能伪造 PASS —— 状态文件不在审计哈希链内。
185
+ > 这是**本地文件系统权限**的信任边界,不是 MCP 工具面能被绕过的漏洞:
186
+ > 能写 `CARLOS_FLOW_HOME` 的人本来就能改自己的代码。
187
+ > 完整说明见 [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) §六。
188
+
189
+ ---
190
+
191
+ ## 📦 安装
192
+
193
+ ```bash
194
+ npm install -g carlos-flow
195
+ ```
196
+
197
+ > ⚠️ 报 `ETARGET: No matching version found`?这是 npm 的 **registry 元数据缓存**没刷新:
198
+ > ```bash
199
+ > npm cache clean --force
200
+ > npm view carlos-flow versions # 验证版本存在
201
+ > ```
202
+
203
+ **兼容性要求**:Node.js ≥ 22.0.0 | MCP SDK ≥ 1.29.0 | 零运行时外部依赖
204
+
205
+ ---
206
+
207
+ ## 🖥️ 平台支持
208
+
209
+ 一个包,六个平台。初始化命令会生成对应平台的配置文件。
210
+
211
+ | 平台 | 初始化命令 | 生成产物 | 平台专属能力 |
212
+ |------|-----------|----------|-------------|
213
+ | **Cindy** | `carlos-flow init --target cindy` | `~/.cindy/ghosts/carlos-flow.json` | Bridge 自动守护 + Settings UI |
214
+ | **OpenCode** | `carlos-flow init --target opencode` | `~/.config/opencode/plugin/opencode.json`<br/>+ 项目 `.mcprc` | `chat.message` 钩子级自动触发 |
215
+ | **Cursor / Windsurf** | `carlos-flow init --target cursor` | 项目 `.cursor/mcp.json` | — |
216
+ | **Cline** | `carlos-flow init --target cline` | 项目 `.cline/mcp.json` | — |
217
+ | **VS Code (Copilot)** | `carlos-flow init --target vscode` | 项目 `.vscode/mcp.json` | — |
218
+ | **Claude Desktop** | `carlos-flow init --target claude` | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`<br/>Windows: `%APPDATA%\Claude\claude_desktop_config.json` | — |
219
+
220
+ > 💡 所有平台共用同一套配置字段:`CARLOS_FLOW_HOME`(状态目录)+ `node <root>/src/index.js`(stdio 启动)。
221
+
222
+ ---
223
+
224
+ ## 🚀 快速开始
225
+
226
+ ### 1. 安装并初始化
227
+
228
+ ```bash
229
+ npm install -g carlos-flow
230
+ carlos-flow init --target <你的平台> # cindy | opencode | cursor | cline | vscode | claude
231
+ ```
232
+
233
+ ### 2. 环境变量(可选,都有默认值)
234
+
235
+ ```bash
236
+ CARLOS_FLOW_HOME=~/.carlos-flow # 状态/审计目录(跨平台统一)
237
+ CARLOS_FLOW_MCP_ROOT=/path/to/carlos-flow # 源码安装时指向仓库根目录
238
+ BRIDGE_PORT=19099 # Cindy Bridge 端口
239
+ ```
240
+
241
+ > 路径一律用**正斜杠**(`/home/you/apps/carlos-flow`)或**双反斜杠**(`D:\\apps\\carlos-flow`)。
242
+ > 单反斜杠在配置里会被当成转义符,`\c`、`\o` 会被吃掉,路径直接失效。
243
+
244
+ ### 3. 验证服务正常
245
+
246
+ ```bash
247
+ node client/carlos.js flow_status '{"sessionId":"probe"}'
248
+ ```
249
+
250
+ 期望输出 `"has_card": false` 即表示服务正常。
251
+
252
+ ### 4. 走一次完整门禁
253
+
254
+ ```bash
255
+ # ① 留痕(记录用户原话,作为 quote 锚点数据源)
256
+ node client/carlos.js flow_add_user_msg '{"sessionId":"demo","text":"给登录接口加参数校验"}'
257
+
258
+ # ② 提交任务卡(scope 是白名单)
259
+ node client/carlos.js flow_submit_requirement '{"sessionId":"demo","goal":"加参数校验","quote":"给登录接口加参数校验","scope":["src/auth.py"],"acceptance":["非法参数返回 400"],"verify":{"cmd":"npm test"},"cwd":"/path/to/project"}'
260
+
261
+ # ③ 领取派发名额
262
+ node client/carlos.js flow_claim '{"sessionId":"demo","role":"executor"}'
263
+
264
+ # ④ 派发(自动快照 scope 内文件)
265
+ node client/carlos.js flow_dispatch '{"sessionId":"demo","role":"executor"}'
266
+
267
+ # ⑤ 真实执行验证命令
268
+ node client/carlos.js flow_run_verify '{"sessionId":"demo","cwd":"/path/to/project"}'
269
+
270
+ # ⑥ 记录裁定(没有验证通过证据不许记 PASS)
271
+ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes":"测试通过"}'
272
+ ```
273
+
274
+ ---
275
+
276
+ ## 🔧 MCP 工具参考(15 个)
277
+
278
+ | 工具 | 作用 | 关键约束 |
279
+ |------|------|---------|
280
+ | `flow_protocol` | 读取完整门禁协议(档位、四段合同、错误分层) | — |
281
+ | `flow_add_user_msg` | 写入用户原话 | **quote 锚点的唯一数据源** |
282
+ | `flow_submit_requirement` | 提交/替换任务卡 | 按风险档强制必填项;伪填充被拒 |
283
+ | `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
284
+ | `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
285
+ | `flow_save_result` | 保存子 Agent 执行结果 | — |
286
+ | `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr |
287
+ | `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
288
+ | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发不许 PASS;验证未过不许 PASS |
289
+ | `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` |
290
+ | `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
291
+ | `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
292
+ | `flow_bypass` | 开关免检模式 | 需 `confirmed=true`;派发自动清零 |
293
+ | `flow_revert_plan` | 生成原子还原计划 | 只返回计划,不自动执行 |
294
+ | `flow_trigger_check` | 智能触发检查 | 达标即实际激活;未达标如实返回评分 |
295
+
296
+ ---
297
+
298
+ ## ⚙️ 配置
299
+
300
+ ### 触发器配置
301
+
302
+ 路径:`$CARLOS_FLOW_HOME/trigger-config.json`(首次 `init` 自动生成)
303
+
304
+ ```json
305
+ {
306
+ "keywordWeights": {
307
+ "评审": 5
308
+ },
309
+ "readOnlyIntentWords": ["讲一下"],
310
+ "mutatingActionWords": ["重构一下"]
311
+ }
312
+ ```
313
+
314
+ **合并语义**(重要):
315
+ - `keywordWeights` → **对象合并**(自定义词覆盖同名默认词,其余默认词保留)
316
+ - 词表数组 → **追加去重**(扩展,不是替换)
317
+ - 其余标量 → 覆盖
318
+
319
+ > 早期实现是浅合并,用户写一个自定义词就把整个默认词表(含内置中文流程词)丢掉 —— 中文场景重新变回 0 分。已修复。
320
+
321
+ ### 环境变量
322
+
323
+ | 变量 | 默认值 | 说明 |
324
+ |------|-------|------|
325
+ | `CARLOS_FLOW_HOME` | `~/.carlos-flow` | 状态 / 审计 / 快照目录。`~` 会被展开 |
326
+ | `CARLOS_FLOW_MCP_ROOT` | 自动推导 | 源码安装时指向仓库根目录 |
327
+ | `BRIDGE_PORT` | `19099` | Cindy Bridge 监听端口 |
328
+ | `CARLOS_BRIDGE_TOKEN` | 内置默认值 | Bridge 本地认证 token |
329
+ | `CARLOS_BRIDGE_TIMEOUT_MS` | `180000` | Bridge 请求超时(需 > 服务端 120s 验证上限) |
330
+ | `CARLOS_MCP_TIMEOUT_MS` | `180000` | CLI 客户端 MCP 调用超时 |
331
+ | `CARLOS_TRIGGER_MESSAGE` | — | CLI 模式下注入触发检查用的用户原话 |
332
+ | `OPENCODE_DB_PATH` | 多路探测 | OpenCode 会话库路径(读用户原话用) |
333
+
334
+ ---
335
+
336
+ ## 🧪 开发
337
+
338
+ ```bash
339
+ git clone https://github.com/skyer-now/carlos-flow.git
340
+ cd carlos-flow
341
+ npm install
342
+
343
+ # 全套测试(129 个用例)
344
+ npm run test:all
345
+
346
+ # 单项
347
+ npm run test:e2e # 端到端 62 项
348
+ npm run test:p0 # P0 门禁 22 项
349
+ npm run test:trigger # 触发引擎 29 项
350
+ npm run test:concurrency # 跨进程并发 3 项
351
+ npm run test:acceptance # 验收 13 项
352
+ npm run test:mutation # 变异测试(13/13 变异体全抓住)
353
+ npm run check:anchors # 变异锚点唯一性守护
354
+ npm run check:readme # 双语 README 一致性
355
+
356
+ # 打包
357
+ npm pack
358
+ ```
359
+
360
+ ### 测试覆盖矩阵
361
+
362
+ | 套件 | 数量 | 覆盖内容 |
363
+ |------|------|---------|
364
+ | `smoke` | 4 | 卡片解析 / 校验 / 状态往返 |
365
+ | `e2e-carlos` | 62 | 全流程 + 激活闸门 + 假闭环防护 + 越界拦截 |
366
+ | `p0-gates` | 22 | P0 级门禁语义(伪填充、类型校验、fail-closed) |
367
+ | `trigger-e2e` | 29 | 三层引擎 + 会话隔离 + 配置合并 + `~` 展开 |
368
+ | `concurrency-e2e` | 3 | 跨进程并发零泄漏 / 零利用 |
369
+ | `e2e-acceptance` | 13 | MCP 路径触发 + 中文词表 + 插件真实开卡 |
370
+ | **合计** | **129** | **全部通过** |
371
+
372
+ ---
373
+
374
+ ## 📚 文档
375
+
376
+ | 文档 | 说明 |
377
+ |------|------|
378
+ | [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | 智能触发引擎深度指南(配置、评分、激活、反馈学习) |
379
+ | [CHANGELOG.md](./CHANGELOG.md) | 版本历史(Keep a Changelog + SemVer) |
380
+ | [MIGRATION.md](./MIGRATION.md) | 从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移 |
381
+ | [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) | 第三方只读验收(13/13 变异体全抓住) |
382
+ | [变异测试报告](./docs/MUTATION_REPORT_v2.5.5.md) | 变异体注入细节与结果 |
383
+
384
+ ---
385
+
386
+ ## ❓ 常见问题
387
+
388
+ <details>
389
+ <summary><b>Q: 和普通 MCP Server 有什么区别?</b></summary>
390
+
391
+ 普通 MCP Server 暴露工具,**但不施加约束** —— 它信任调用方会正确使用。
392
+ Carlos Flow 的约束在 **服务端运行时强制执行**:越界文件会被 `enforceScope()` 拦下,
393
+ 没跑过验证就不许记 PASS,审计日志改一条就断链。
394
+ </details>
395
+
396
+ <details>
397
+ <summary><b>Q: 只在 Cindy 用,还需要装这么多吗?</b></summary>
398
+
399
+ 不需要。单一包对所有用户都是**同一个安装体积**(~106 KB),
400
+ 不需要额外下载任何平台专属依赖 —— 只是模板文件不同。
401
+ </details>
402
+
403
+ <details>
404
+ <summary><b>Q: 会拖慢我的 Agent 吗?</b></summary>
405
+
406
+ 不会。门禁状态是**文件级持久化**,无数据库、无网络、无常驻进程
407
+ (除 Cindy 版的 Bridge,它只在首次调用时拉起)。
408
+ 触发引擎是纯 JS 计算,零依赖。
409
+ </details>
410
+
411
+ <details>
412
+ <summary><b>Q: `CARLOS_FLOW_HOME=~/.carlos-flow` 里的 `~` 会展开吗?</b></summary>
413
+
414
+ 会。早期版本**不会展开** —— `path.normalize` 只换分隔符,路径仍是字面量,
415
+ 状态写到「当前目录下字面名为 `~` 的目录」里,位置诡异极易丢失。
416
+ 现已统一展开(`state.js` / `trigger.js` 共用 `expandHome()`),并有回归用例守护。
417
+ </details>
418
+
419
+ <details>
420
+ <summary><b>Q: 免检模式会不会成为后门?</b></summary>
421
+
422
+ 免检需**卡片上显式** `confirmed=true`,且 `bypass_ts` 必须晚于 `card_ts`(旧卡的免检不能作用于新卡)。
423
+ 最关键的是:**每次派发后自动清零** —— 免检只对当次派发生效,不会变成长期开关。
424
+ </details>
425
+
426
+ <details>
427
+ <summary><b>Q: 中文能用吗?</b></summary>
428
+
429
+ 完全支持。中文流程词内置(工作流/门禁/派发/审计/复核/任务卡/子代理/流程/触发/执行/调度/留痕/裁定),
430
+ 中文需求同样能触发;普通开发需求(「给接口加个参数校验」)不会误触发。
431
+ </details>
432
+
433
+ <details>
434
+ <summary><b>Q: 旧包还能用吗?</b></summary>
435
+
436
+ 能,但已标记 **Deprecated**。迁移方式见 [MIGRATION.md](./MIGRATION.md)。
437
+ </details>
438
+
439
+ ---
440
+
441
+ ## 🔗 链接
442
+
443
+ | | |
444
+ |---|---|
445
+ | **仓库** | https://github.com/skyer-now/carlos-flow |
446
+ | **npm** | https://www.npmjs.com/package/carlos-flow |
447
+ | **问题反馈** | https://github.com/skyer-now/carlos-flow/issues |
448
+ | **更新日志** | [CHANGELOG.md](./CHANGELOG.md) |
449
+
450
+ ---
451
+
452
+ ## 🤝 贡献
453
+
454
+ 欢迎 PR!提交前请确保:
455
+
456
+ ```bash
457
+ npm run test:all # 129/0 全通过
458
+ npm run check:anchors # 变异锚点未失效
459
+ npm run check:readme # 双语 README 未漂移
460
+ ```
461
+
462
+ 详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
463
+
464
+ ---
465
+
466
+ ## 📄 License
467
+
468
+ [MIT](./LICENSE) © Carlos Flow Contributors