carlos-flow 2.5.9 → 2.6.1
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/CHANGELOG.md +184 -90
- package/MIGRATION.md +245 -0
- package/README.en.md +461 -476
- package/README.md +388 -138
- package/README.zh.md +388 -138
- package/TRIGGER_GUIDE.md +745 -554
- package/bridge/mcp-bridge.js +7 -1
- package/client/carlos.js +9 -2
- package/ghost.json +1 -1
- package/package.json +4 -2
- package/scripts/check-repo-parity.mjs +198 -253
- package/src/index.js +12 -2
package/README.md
CHANGED
|
@@ -1,218 +1,468 @@
|
|
|
1
|
-
# Carlos Flow
|
|
1
|
+
# Carlos Flow
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/carlos-flow)
|
|
4
|
+
[](https://www.npmjs.com/package/carlos-flow)
|
|
5
|
+
[](https://nodejs.org)
|
|
6
|
+
[](https://modelcontextprotocol.io)
|
|
7
|
+
[](./LICENSE)
|
|
8
|
+
[](./.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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
>
|
|
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
|
-
##
|
|
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
|
-
|
|
36
|
-
|
|
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
|
-
|
|
40
|
-
|
|
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
|
-
|
|
52
|
-
|
|
|
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
|
-
##
|
|
191
|
+
## 📦 安装
|
|
57
192
|
|
|
58
|
-
### 1. 安装
|
|
59
193
|
```bash
|
|
60
194
|
npm install -g carlos-flow
|
|
61
195
|
```
|
|
62
|
-
|
|
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
|
-
|
|
69
|
-
```bash
|
|
70
|
-
# Cindy 用户
|
|
71
|
-
carlos-flow init --target cindy
|
|
203
|
+
**兼容性要求**:Node.js ≥ 22.0.0 | MCP SDK ≥ 1.29.0 | 零运行时外部依赖
|
|
72
204
|
|
|
73
|
-
|
|
74
|
-
carlos-flow init --target opencode
|
|
205
|
+
---
|
|
75
206
|
|
|
76
|
-
|
|
77
|
-
carlos-flow init --target cursor
|
|
207
|
+
## 🖥️ 平台支持
|
|
78
208
|
|
|
79
|
-
|
|
80
|
-
carlos-flow init --target cline
|
|
209
|
+
一个包,六个平台。初始化命令会生成对应平台的配置文件。
|
|
81
210
|
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
|
|
86
|
-
|
|
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
|
-
###
|
|
233
|
+
### 2. 环境变量(可选,都有默认值)
|
|
234
|
+
|
|
90
235
|
```bash
|
|
91
|
-
#
|
|
92
|
-
|
|
93
|
-
#
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
-
|
|
176
|
-
|
|
177
|
-
-
|
|
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
|
-
#
|
|
343
|
+
# 全套测试(129 个用例)
|
|
192
344
|
npm run test:all
|
|
193
345
|
|
|
194
|
-
#
|
|
195
|
-
npm run test:e2e
|
|
196
|
-
npm run test:p0
|
|
197
|
-
npm run test:trigger
|
|
198
|
-
npm run test:concurrency #
|
|
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
|
|
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
|