carlos-flow 2.5.9 → 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 CHANGED
@@ -1,218 +1,468 @@
1
- # Carlos Flow — 统一分发版(Cindy / OpenCode / Cursor / Cline / VS Code / Claude Desktop)
1
+ # Carlos Flow
2
2
 
3
- > **面向 AI 编码 Agent 的机械门禁**:留痕 → 派发 → 验证 → 裁定 → 审计 → 还原
4
- > 把"相信 Agent"变成"验证 Agent"——机器级 scope 限制、真实命令执行、防篡改审计链。
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)
5
9
 
6
- **语言 / Languages:** [中文](README.zh.md) | [English](README.en.md)
7
- **版本 / Version:** 2.5.9 | **License:** MIT | **CI:** passing | **Node.js:** 22+ | **MCP:** 1.29+
10
+ **语言 / Languages:** [中文](README.zh.md) | [English](README.en.md)
8
11
 
9
12
  ---
10
13
 
11
- ## 🎯 一次安装,全平台可用
14
+ > **AI 编码 Agent 的机械门禁(Mechanical Gate)**
15
+ >
16
+ > 留痕 → 派发 → 验证 → 裁定 → 审计 → 还原
17
+ >
18
+ > 把「相信 Agent」变成「**验证** Agent」——约束写在代码里,不写在提示词里。
12
19
 
13
- ```bash
14
- npm install -g carlos-flow
15
- # 或
16
- npx carlos-flow@latest init --target <平台>
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 模板
17
72
  ```
18
73
 
19
- | 平台 | 初始化命令 | 生成产物 |
20
- |------|-----------|----------|
21
- | **Cindy** | `carlos-flow init --target cindy` | `~/.cindy/ghosts/carlos-flow.json` |
22
- | **OpenCode** | `carlos-flow init --target opencode` | `~/.config/opencode/plugin/opencode.json` + 项目 `.mcprc` |
23
- | **Cursor / Windsurf** | `carlos-flow init --target cursor` | 项目 `.cursor/mcp.json` |
24
- | **Cline** | `carlos-flow init --target cline` | 项目 `.cline/mcp.json` |
25
- | **VS Code (GitHub Copilot)** | `carlos-flow init --target vscode` | 项目 `.vscode/mcp.json` |
26
- | **Claude Desktop** | `carlos-flow init --target claude` | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)<br>`%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
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` **一律拒绝**。
27
86
 
28
- > 💡 **环境变量**:`CARLOS_FLOW_HOME=~/.carlos-flow`(默认),`CARLOS_FLOW_MCP_ROOT`(源码安装时指向本仓库根目录)
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**。
29
98
 
30
99
  ---
31
100
 
32
- ## 🆕 v2.5.9 更新速览
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
+ ### 分层职责
33
154
 
34
- ### ✨ 统一分发包
35
- - 单一 npm 包 `carlos-flow` 支持 **6 大主流 AI 编码平台**
36
- - 核心 MCP Server (`src/index.js`) 零平台耦合,纯标准协议
37
- - 平台差异仅在初始化模板,维护成本大幅降低
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/` | 状态、审计链、快照、触发历史 | ✅ 跨平台路径约定 |
38
162
 
39
- ### 🔧 智能触发引擎(v2.5.5 引入,持续加固)
40
- 引擎会读取你的输入,自动判断现在是否该启动 Carlos 工作流——并且**告诉你为什么**。
163
+ > **核心设计原则**:MCP 协议是**被动**的 —— 服务端不能主动推送。
164
+ > 因此「自动触发」必须由**能拿到用户消息的那一侧**发起(宿主插件钩子 或 Agent 主动调用 `flow_trigger_check`)。
165
+ > 两条路径共用 `src/trigger.js` 同一份实现,**行为完全一致**。
41
166
 
42
- | 层 | 组件 | 做什么 | 为什么需要它 |
43
- |----|------|--------|-------------|
44
- | **L1** | `DynamicTriggerManager` | 动态计算"本会话还允许触发几次" | 固定上限要么太吵、要么太严;会话越长、任务越复杂,上限自动放宽 |
45
- | **L2** | `TriggerScorer` | 给每条消息打分:关键词 50 + 上下文 30 + 意图 20,加权后满分 **38** | 触发与否必须**可解释**——每次都告诉你命中了哪些词、得了多少分 |
46
- | **L3** | `TriggerDecisionEngine` | 四档决策:`trigger` / `review` / `ignore` / `throttled` | 把"要不要触发"从模糊直觉变成明确规则 |
167
+ ---
47
168
 
48
- **两条触发路径,行为完全一致**:
49
- | 路径 | 怎么触发 | 适用 |
50
- |------|---------|------|
51
- | **① MCP 工具** | 调 `flow_trigger_check`(传 `sessionId` + `message`),达标即**实际激活** | 任何 MCP 宿主 |
52
- | **② 命令行客户端** | `node client/carlos.js flow_status '{"sessionId":"x","triggerMessage":"run dispatch workflow"}'` | 脚本 / 调试 |
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) §六。
53
188
 
54
189
  ---
55
190
 
56
- ## 🚀 30 秒快速开始
191
+ ## 📦 安装
57
192
 
58
- ### 1. 安装
59
193
  ```bash
60
194
  npm install -g carlos-flow
61
195
  ```
62
- > ⚠️ **如果报 `ETARGET: No matching version found`** —— npm registry 元数据缓存未刷新。
196
+
197
+ > ⚠️ 报 `ETARGET: No matching version found`?这是 npm 的 **registry 元数据缓存**没刷新:
63
198
  > ```bash
64
199
  > npm cache clean --force
65
- > npm view carlos-flow versions # 验证版本存在
200
+ > npm view carlos-flow versions # 验证版本存在
66
201
  > ```
67
202
 
68
- ### 2. 一键初始化(按你的平台选一个)
69
- ```bash
70
- # Cindy 用户
71
- carlos-flow init --target cindy
203
+ **兼容性要求**:Node.js ≥ 22.0.0 | MCP SDK ≥ 1.29.0 | 零运行时外部依赖
72
204
 
73
- # OpenCode 用户
74
- carlos-flow init --target opencode
205
+ ---
75
206
 
76
- # Cursor / Windsurf 用户
77
- carlos-flow init --target cursor
207
+ ## 🖥️ 平台支持
78
208
 
79
- # Cline 用户
80
- carlos-flow init --target cline
209
+ 一个包,六个平台。初始化命令会生成对应平台的配置文件。
81
210
 
82
- # VS Code (Copilot) 用户
83
- carlos-flow init --target vscode
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` | — |
84
219
 
85
- # Claude Desktop 用户
86
- carlos-flow init --target claude
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
87
231
  ```
88
232
 
89
- ### 3. 设置环境变量(可选,有默认值)
233
+ ### 2. 环境变量(可选,都有默认值)
234
+
90
235
  ```bash
91
- # 默认值已可用,如需自定义:
92
- # CARLOS_FLOW_HOME=~/.carlos-flow # 状态/审计目录(跨平台)
93
- # CARLOS_FLOW_MCP_ROOT=/path/to/carlos-flow # 源码安装时指向仓库根目录
94
- # BRIDGE_PORT=19099 # Cindy Bridge 端口
236
+ CARLOS_FLOW_HOME=~/.carlos-flow # 状态/审计目录(跨平台统一)
237
+ CARLOS_FLOW_MCP_ROOT=/path/to/carlos-flow # 源码安装时指向仓库根目录
238
+ BRIDGE_PORT=19099 # Cindy Bridge 端口
95
239
  ```
96
240
 
97
- ### 4. 重启并验证
241
+ > 路径一律用**正斜杠**(`/home/you/apps/carlos-flow`)或**双反斜杠**(`D:\\apps\\carlos-flow`)。
242
+ > 单反斜杠在配置里会被当成转义符,`\c`、`\o` 会被吃掉,路径直接失效。
243
+
244
+ ### 3. 验证服务正常
245
+
98
246
  ```bash
99
- # CLI 验证
100
247
  node client/carlos.js flow_status '{"sessionId":"probe"}'
101
- # 期望输出里 has_card: false 即表示服务正常
102
248
  ```
103
249
 
104
- ---
250
+ 期望输出 `"has_card": false` 即表示服务正常。
105
251
 
106
- ## 🌟 核心能力
252
+ ### 4. 走一次完整门禁
107
253
 
108
- ### 🔒 机械门禁(非建议性)
109
- | 能力 | 实现方式 | 对比:原生 MCP / 提示词 |
110
- |------|---------|------------------------|
111
- | **越界拦截** | 运行时 `git diff` 对比卡片 `scope` 白名单 | ❌ 无 / 靠自觉 |
112
- | **真实验证** | `spawn` 执行 `verify.cmd`,捕获 stdout/stderr/exitCode;记 PASS 前**必须**有验证通过证据 | ❌ 无 / Agent 自述 |
113
- | **防篡改审计** | SHA-256 链式哈希(`prevHash`→`hash`),改一条全链断裂 | ❌ 无 / 无 |
114
- | **可控免检** | 显式 `confirmed=true`,**每次派发自动清零** | ❌ 无 / 一句话全关 |
115
- | **诚实派发配额** | `dispatch_count` 只在派发时 +1,耗尽即拦截 | ❌ 无 / 无 |
116
- | **独立复核** | 内置 `auditor` 角色,独立合同,裁定三档 `PASS/DIRECTION/LOCAL` | ❌ 无 / 可选 |
117
- | **快照 + 还原** | 派发前自动快照 → `flow_revert_plan` 生成原子还原计划 | ❌ 无 / 手动 `git revert` |
118
- | **守护进程** | Bridge 首次调用自动拉起、健康检查、Token 认证、限流 | ❌ 手动 / 手动 |
254
+ ```bash
255
+ # ① 留痕(记录用户原话,作为 quote 锚点数据源)
256
+ node client/carlos.js flow_add_user_msg '{"sessionId":"demo","text":"给登录接口加参数校验"}'
119
257
 
120
- ### 🆕 智能触发引擎 — `src/trigger.js`
121
- **动态决策 → 判断 → 激活** 完整闭环:
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"}'
122
260
 
123
- ```mermaid
124
- flowchart LR
125
- U[用户输入] --> L1{"L1 动态上限"}
126
- L1 -->|已限流| T["throttled<br/>如实返回评分"]
127
- L1 -->|可以| L2{"L2 三维评分"}
128
- L2 -->|< 10| I["ignore"]
129
- L2 -->|10~15| R["review<br/>建议手动"]
130
- L2 -->|≥ 15| L3{"≥25 且置信度≥0.8?"}
131
- L3 -->|否| M["manual<br/>给建议"]
132
- L3 -->|是| A["✅ 激活"]
133
- A --> S1["flow_add_user_msg<br/>用户原话入库"]
134
- S1 --> S2["flow_submit_requirement<br/>activation: true"]
135
- S2 --> G["activation_pending<br/>闸门:缺字段拦claim/dispatch/verdict"]
136
- G -->|补齐后| R2["重新提交完整卡<br/>闸门放行"]
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":"测试通过"}'
137
272
  ```
138
273
 
139
- **关键特性**:
140
- - 🎚️ **动态上限**:`5 + 会话时长(小时)×0.5 + 复杂度×2 − 窗口内已触发×0.3`,封顶 15
141
- - 🛡️ **不打扰**:同会话最短间隔 5 分钟;触发越多上限**越低**(惩罚项)
142
- - 📊 **评分透明**:返回完整 `breakdown`(命中关键词 / 上下文词 / 意图类型)
143
- - ⚖️ **限流也如实**:被限流时照样返回真实评分与置信度
144
- - 🧠 **反馈学习**:负反馈占多数时自动抬高触发阈值,更保守
145
- - 🇨🇳 **中文开箱即用**:内置中文流程词;普通开发需求**不会误触发**
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` | 智能触发检查 | 达标即实际激活;未达标如实返回评分 |
146
295
 
147
296
  ---
148
297
 
149
- ## 📦 包结构
298
+ ## ⚙️ 配置
150
299
 
151
- ```
152
- carlos-flow/
153
- ├── client/carlos.js # CLI 入口(含 init --target)
154
- ├── src/index.js # 核心 MCP Server(stdio,标准协议)
155
- ├── src/trigger.js # 智能触发引擎
156
- ├── bridge/mcp-bridge.js # Cindy 专用:后台常驻 + Token 认证
157
- ├── plugins/carlos-flow-trigger.js # OpenCode 专用:chat.message 钩子
158
- ├── ghost.json # Cindy 清单(__ROOT__ 占位符)
159
- ├── opencode.json # OpenCode 配置(已渲染)
160
- ├── opencode.json.template # OpenCode 模板
161
- ├── .mcprc.template # OpenCode MCP 配置模板
162
- ├── trigger-config.usable.json # 触发器默认配置
163
- ├── templates/
164
- │ ├── cursor/mcp.json # Cursor / Windsurf
165
- │ ├── cline/mcp.json # Cline
166
- │ ├── vscode/mcp.json # VS Code (Copilot)
167
- │ └── claude/claude_desktop_config.json # Claude Desktop
168
- └── test/ # 全套测试(255/0 通过)
300
+ ### 触发器配置
301
+
302
+ 路径:`$CARLOS_FLOW_HOME/trigger-config.json`(首次 `init` 自动生成)
303
+
304
+ ```json
305
+ {
306
+ "keywordWeights": {
307
+ "评审": 5
308
+ },
309
+ "readOnlyIntentWords": ["讲一下"],
310
+ "mutatingActionWords": ["重构一下"]
311
+ }
169
312
  ```
170
313
 
171
- ---
314
+ **合并语义**(重要):
315
+ - `keywordWeights` → **对象合并**(自定义词覆盖同名默认词,其余默认词保留)
316
+ - 词表数组 → **追加去重**(扩展,不是替换)
317
+ - 其余标量 → 覆盖
318
+
319
+ > 早期实现是浅合并,用户写一个自定义词就把整个默认词表(含内置中文流程词)丢掉 —— 中文场景重新变回 0 分。已修复。
172
320
 
173
- ## 📚 详细文档
321
+ ### 环境变量
174
322
 
175
- - [`TRIGGER_GUIDE.md`](TRIGGER_GUIDE.md) — 智能触发引擎完整使用指南
176
- - [`CHANGELOG.md`](CHANGELOG.md) — 版本历史
177
- - [QA 验收报告](docs/QA_REPORT_v2.5.5.md) — 第三方只读验收(13/13 变异体全抓住)
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 会话库路径(读用户原话用) |
178
333
 
179
334
  ---
180
335
 
181
- ## 🛠️ 开发与测试
336
+ ## 🧪 开发
182
337
 
183
338
  ```bash
184
- # 克隆源码
185
339
  git clone https://github.com/skyer-now/carlos-flow.git
186
340
  cd carlos-flow
187
-
188
- # 安装依赖
189
341
  npm install
190
342
 
191
- # 跑全套测试(255 个用例)
343
+ # 全套测试(129 个用例)
192
344
  npm run test:all
193
345
 
194
- # 单独跑
195
- npm run test:e2e # 端到端 61 项
196
- npm run test:p0 # P0 门禁 22 项
197
- npm run test:trigger # 触发引擎 29 项
198
- npm run test:concurrency # 并发 3 项
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 项
199
351
  npm run test:acceptance # 验收 13 项
352
+ npm run test:mutation # 变异测试(13/13 变异体全抓住)
353
+ npm run check:anchors # 变异锚点唯一性守护
354
+ npm run check:readme # 双语 README 一致性
200
355
 
201
- # 变异测试(注入缺陷确认测试能抓住)
202
- npm run test:mutation
203
-
204
- # 本地打包
356
+ # 打包
205
357
  npm pack
206
358
  ```
207
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
+
208
450
  ---
209
451
 
210
452
  ## 🤝 贡献
211
453
 
212
- 欢迎 PR!请先跑 `npm run test:all` 确保 255/0 全通过。
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)。
213
463
 
214
464
  ---
215
465
 
216
466
  ## 📄 License
217
467
 
218
- MIT © Carlos Flow Contributors
468
+ [MIT](./LICENSE) © Carlos Flow Contributors