carlos-flow 2.12.0 → 2.12.6
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 +5 -0
- package/CHANGELOG.md +660 -631
- package/README.md +34 -527
- package/README.zh.md +34 -527
- package/TRIGGER_GUIDE.md +2 -2
- package/bridge/mcp-bridge.js +203 -203
- package/check-all.sh +0 -0
- package/ghost.json +32 -1
- package/package.json +114 -113
- package/plugins/carlos-flow-trigger.js +215 -215
- package/scripts/check-artifacts.mjs +7 -0
- package/scripts/check-no-dead-handler.mjs +87 -87
- package/scripts/check-refs.mjs +10 -0
- package/scripts/check-stubs.mjs +90 -0
- package/scripts/check-templates.mjs +126 -126
- package/scripts/clean-readme-noise.mjs +53 -53
- package/scripts/install-hooks.mjs +166 -166
- package/scripts/lang-audit.mjs +172 -172
- package/scripts/mutation-check.mjs +483 -483
- package/scripts/release.mjs +6 -1
- package/scripts/sync-readme.mjs +102 -102
- package/scripts/verify-activation-e2e.sh +55 -55
- package/smoke-test.js +142 -142
- package/src/card.js +296 -288
- package/src/commander.js +10 -0
- package/src/dispatch.js +557 -548
- package/src/index.js +1713 -1686
- package/src/profiles.js +17 -0
- package/src/protocol.js +95 -85
- package/src/state.js +930 -898
- package/src/trigger.js +909 -909
package/README.md
CHANGED
|
@@ -1,553 +1,60 @@
|
|
|
1
|
-
# Carlos Flow
|
|
1
|
+
# Carlos 工作流 (Carlos-Flow)
|
|
2
2
|
|
|
3
|
-
[](https://modelcontextprotocol.io)
|
|
7
|
-
[](./LICENSE)
|
|
8
|
-
[](./.github/workflows/ci.yml)
|
|
3
|
+
[](https://github.com/skyer-now/carlos-flow)
|
|
4
|
+
[](https://www.npmjs.com/package/carlos-flow)
|
|
5
|
+
[](LICENSE)
|
|
9
6
|
|
|
10
|
-
|
|
7
|
+
[中文](README.zh.md) | [English Version](README.en.md)
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
你是否在使用 OpenCode、Claude Code 或其他 AI 编程工具时遇到过困扰?
|
|
10
|
+
* **AI 总是“瞎执行”**:指令明明说得很清楚,AI 却完全没按要求办,还得你花时间纠错。
|
|
11
|
+
* **流程门槛高**:想用 AI 处理复杂任务,却被各种报错和繁琐的工具链挡在门外。
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
>
|
|
16
|
-
> 留痕 → 派发 → 验证 → 裁定 → 审计 → 还原
|
|
17
|
-
>
|
|
18
|
-
> 把「相信 Agent」变成「**验证** Agent」——约束写在代码里,不写在提示词里。
|
|
13
|
+
**Carlos 工作流是一个“通用的 AI 辅助外挂”。无论你用什么开发平台,装上它,立刻为你现有的 AI 工具加装一层“智能监督”和“流程导航”。**
|
|
19
14
|
|
|
20
15
|
---
|
|
21
16
|
|
|
22
|
-
##
|
|
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 的做法是:**约束全部落在代码里,用运行时事实校验,不信自述。**
|
|
17
|
+
## 🌟 为什么它是每个人的“外挂”?
|
|
35
18
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
- 想跳过?→ 免检需显式 `confirmed=true`,且**每次派发自动清零**
|
|
41
|
-
审计文件按本地日期分片,`prevHash` 一律联动**前一天的 tail**,跨天不断链。
|
|
42
|
-
未设密钥时(`plain` 模式)走裸 SHA-256:只能防**意外损坏**,
|
|
43
|
-
不能防有意篡改;`verifyAuditChain()` 的回传带了 `mode` 字段(`plain`/`hmac`),
|
|
44
|
-
调用方自行判断强度。审计记录(`audit()`)和状态文件(`saveState()`)
|
|
45
|
-
写之前先脱敏——密钥片段不入盘。
|
|
19
|
+
### 1. 兼容你所有的开发工具
|
|
20
|
+
* **不换环境,随插随用**:无论你是在用 OpenCode、Claude Code 还是其他 AI 编程工具,Carlos 工作流都能直接兼容。它就像是给你的 AI 装了一个“增强补丁”。
|
|
21
|
+
* **无需改变习惯**:你不需要卸载或更换当前的任何软件。它作为后台辅助,静静地运行在你的开发环境中,只在需要纠偏或引导时出现。
|
|
22
|
+
* **简单来说**:它就是一个“即插即用”的标准接口,让你在任何工具里都能调用这套辅助系统。
|
|
46
23
|
|
|
47
|
-
|
|
24
|
+
### 2. AI 的“贴身监督员” (确保不跑偏)
|
|
25
|
+
* **自动拦截错误**:如果你对 AI 的要求是 A,但它产出的代码变成了 B,Carlos 工作流会自动拦截,并对比你的原始目标,防止 AI 越界或瞎改。
|
|
48
26
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
## 🎯 解决的 8 个真实问题
|
|
52
|
-
|
|
53
|
-
| # | 问题 | 传统现状 | Carlos Flow 的机械化答案 |
|
|
54
|
-
|---|------|---------|------------------------|
|
|
55
|
-
| 1 | **越界改动** | "只改这些文件"是建议不是规则 | `enforceScope()` 运行时 `git diff` 比对白名单,越界**阻断派发** |
|
|
56
|
-
| 2 | **验证表演** | Agent 自述"测试通过",无人能证明 | `runVerifyCommand()` 真实执行,捕获 stdout/stderr/exitCode;**无验证证据不许记 PASS** |
|
|
57
|
-
| 3 | **可洗白审计** | 普通文件日志 —— 可删可改 | 链式哈希审计,**改一条全链断裂**;跨天链联动前一天 tail;**审计记录与落盘状态均脱敏后写**;
|
|
58
|
-
配 `CARLOS_FLOW_AUDIT_KEY` 启用 HMAC 后,**攻击者没有密钥就无法重算掩盖** |
|
|
59
|
-
| 4 | **失控免检** | 一句话关闭所有防护 | 需卡片显式 `confirmed=true`,**每次派发自动清零** |
|
|
60
|
-
| 5 | **无限派发** | 领卡即重置计数,可无限重试 | `dispatch_count` 仅在派发时 +1,耗尽同时拦截 claim / dispatch |
|
|
61
|
-
| 6 | **自证式复核** | 同一 Agent 既实现又审批 | 内置 `auditor` 角色 + 独立合同,裁定严格三档 |
|
|
62
|
-
| 7 | **改坏无法回退** | 只能手动 `git revert` | 派发前自动快照 → `flow_revert_plan` 生成原子还原计划 |
|
|
63
|
-
| 8 | **每次手动喊话** | 不喊就不启动,忘了就裸奔 | **智能触发引擎**自动识别意图,评分达标才触发并解释命中了什么 |
|
|
27
|
+
### 3. AI 的“智能导航员” (降低使用门槛)
|
|
28
|
+
* **手把手引导**:当你不知道怎么下一步处理时,开启“向导模式”。它会自动根据任务拆解步骤,把复杂的技术活变成简单的确认步骤,带你绕开各种报错坑。
|
|
64
29
|
|
|
65
30
|
---
|
|
66
31
|
|
|
67
|
-
##
|
|
68
|
-
|
|
69
|
-
### 1. 零分叉的跨平台架构
|
|
70
|
-
一套核心 MCP Server,**6 大平台**开箱即用。平台差异只在初始化模板,核心逻辑**零分叉**。
|
|
71
|
-
|
|
72
|
-
```
|
|
73
|
-
carlos-flow (单一 npm 包)
|
|
74
|
-
├── src/index.js ← 核心 MCP Server(纯标准协议,零平台耦合)
|
|
75
|
-
├── client/carlos.js ← CLI + init --target <平台>
|
|
76
|
-
├── bridge/ ← Cindy 专属:后台常驻 Bridge
|
|
77
|
-
├── plugins/ ← OpenCode 专属:chat.message 钩子
|
|
78
|
-
└── templates/ ← Cursor / Cline / VS Code / Claude 模板
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
### 2. 智能触发引擎 —— 工作流会自己认出该上场的时候
|
|
82
|
-
三层架构,**每次决策都给出可解释的 breakdown**(命中了哪些词、多少分、为什么)。
|
|
83
|
-
|
|
84
|
-
- **L1 动态上限**:`5 + 会话时长×0.5 + 复杂度×2 − 窗口内已触发×0.3`,封顶 15
|
|
85
|
-
- **L2 三维评分**:关键词 50 / 上下文 30 / 意图 20,加权满分 38
|
|
86
|
-
- **L3 四档决策**:`trigger` / `review` / `ignore` / `throttled`
|
|
87
|
-
|
|
88
|
-
中文流程词**内置**(工作流/门禁/派发/审计/任务卡/子代理…),普通开发需求**不会误触发**。
|
|
89
|
-
|
|
90
|
-
### 3. 反自欺的激活闸门
|
|
91
|
-
自动触发**不等于**直接放行。激活后进入 `activation_pending` 状态:
|
|
92
|
-
在 `scope` / `acceptance` / `verify.cmd` 补齐之前,`flow_claim` / `flow_dispatch` / `flow_verdict` **一律拒绝**。
|
|
93
|
-
|
|
94
|
-
> 防的是「占位卡 → 直接派发 → 直接记 PASS」的假闭环。
|
|
95
|
-
|
|
96
|
-
### 4. Fail-closed 语义
|
|
97
|
-
空 `scope` 判定为**全部越界**(而不是"白名单为空=随便改")。这是安全默认值,不是业务默认值。
|
|
98
|
-
|
|
99
|
-
### 5. 变异测试守护
|
|
100
|
-
13 类变异体(注入退化)**13/13 全部被测试抓住**。锚点唯一性由 `npm run check:anchors` 守护,防止测试"静默失去守护作用"。
|
|
32
|
+
## ⚙️ 工作原理
|
|
101
33
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
34
|
+
Carlos 工作流的核心逻辑是“闭环质检”:
|
|
35
|
+
1. **任务录入**:你设定目标,系统将其记录为任务卡。
|
|
36
|
+
2. **角色调度**:自动派发执行与审计角色,规范操作流程。
|
|
37
|
+
3. **自动化质检**:AI 的产出必须通过系统预设的自动化回归测试。
|
|
38
|
+
4. **结论裁定**:只有通过测试与双轴门禁,任务才被判定为“已完成”。
|
|
105
39
|
|
|
106
40
|
---
|
|
107
41
|
|
|
108
|
-
##
|
|
42
|
+
## ❓ 常见问题 (FAQ)
|
|
109
43
|
|
|
110
|
-
|
|
44
|
+
**Q:我用的是 OpenCode / Claude Code,能装吗?**
|
|
45
|
+
A:完全支持!Carlos 工作流不挑工具,装上就能用。
|
|
111
46
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
subgraph Host["宿主 Agent 平台"]
|
|
115
|
-
Cindy[Cindy<br/>ghost.json]
|
|
116
|
-
OpenCode[OpenCode<br/>plugin + .mcprc]
|
|
117
|
-
Cursor[Cursor / Cline<br/>VS Code / Claude]
|
|
118
|
-
end
|
|
47
|
+
**Q:装上它,我还需要像以前一样写代码吗?**
|
|
48
|
+
A:你需要继续写你的核心逻辑,但 Carlos 会帮你把那些“繁琐的检查”、“步骤引导”和“合规审计”全部自动处理掉。这相当于雇了个专门帮你查错和导航的助理。
|
|
119
49
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
Bridge["bridge/mcp-bridge.js<br/>常驻守护 + Token 认证"]
|
|
123
|
-
Plugin["plugins/carlos-flow-trigger.js<br/>chat.message 钩子"]
|
|
124
|
-
end
|
|
125
|
-
|
|
126
|
-
subgraph Core["核心 MCP Server (src/index.js) — 19 个工具"]
|
|
127
|
-
Protocol["flow_protocol"]
|
|
128
|
-
Submit["flow_submit_requirement"]
|
|
129
|
-
Dispatch["flow_claim / flow_dispatch"]
|
|
130
|
-
Verify["flow_run_verify / flow_falsify / flow_check_scope"]
|
|
131
|
-
Verdict["flow_verdict"]
|
|
132
|
-
Audit["flow_status / flow_audit"]
|
|
133
|
-
Trigger["flow_trigger_check"]
|
|
134
|
-
end
|
|
135
|
-
|
|
136
|
-
subgraph Engine["智能触发引擎 (src/trigger.js)"]
|
|
137
|
-
L1["L1 DynamicTriggerManager"]
|
|
138
|
-
L2["L2 TriggerScorer"]
|
|
139
|
-
L3["L3 TriggerDecisionEngine"]
|
|
140
|
-
end
|
|
141
|
-
|
|
142
|
-
subgraph Storage["持久化层 (CARLOS_FLOW_HOME)"]
|
|
143
|
-
State["gate-state/runs/<sid>/"]
|
|
144
|
-
AuditLog["gate-audit/YYYY-MM-DD.jsonl<br/>SHA-256 链式"]
|
|
145
|
-
Snap["snapshots/"]
|
|
146
|
-
TrigState["trigger-state/"]
|
|
147
|
-
end
|
|
148
|
-
|
|
149
|
-
Cindy --> CLI
|
|
150
|
-
OpenCode --> Plugin
|
|
151
|
-
Cursor --> CLI
|
|
152
|
-
Plugin --> Trigger
|
|
153
|
-
CLI --> Bridge
|
|
154
|
-
Bridge --> Core
|
|
155
|
-
Core --> Engine
|
|
156
|
-
Core --> Storage
|
|
157
|
-
Engine --> TrigState
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
### 分层职责
|
|
161
|
-
|
|
162
|
-
| 层 | 位置 | 职责 | 平台耦合 |
|
|
163
|
-
|----|------|------|---------|
|
|
164
|
-
| **宿主适配层** | `ghost.json` / `plugins/` / `templates/` | 发现、启动、配置、生命周期 | ⚠️ 唯一有平台差异的层 |
|
|
165
|
-
| **客户端层** | `client/carlos.js` / `bridge/` | CLI、触发检查、Bridge 守护 | 仅 Cindy 需要 Bridge |
|
|
166
|
-
| **协议层** | `src/index.js` | 16 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
|
|
167
|
-
| **引擎层** | `src/trigger.js` / `src/card.js` / `src/state.js` | 触发评分、卡片校验、状态/审计 | ✅ 零耦合,纯 JS 无依赖 |
|
|
168
|
-
| **持久化层** | `~/.carlos-flow/` | 状态、审计链、快照、触发历史 | ✅ 跨平台路径约定 |
|
|
169
|
-
|
|
170
|
-
> **核心设计原则**:MCP 协议是**被动**的 —— 服务端不能主动推送。
|
|
171
|
-
> 因此「自动触发」必须由**能拿到用户消息的那一侧**发起(宿主插件钩子 或 Agent 主动调用 `flow_trigger_check`)。
|
|
172
|
-
> 两条路径共用 `src/trigger.js` 同一份实现,**行为完全一致**。
|
|
50
|
+
**Q:这听起来很专业,我能学会吗?**
|
|
51
|
+
A:完全没问题。它的设计目标就是让不懂复杂技术的人,也能顺畅地操作 AI。当你遇到看不懂的问题时,直接问它,它会用最通俗的话告诉你怎么做。
|
|
173
52
|
|
|
174
53
|
---
|
|
175
54
|
|
|
176
|
-
##
|
|
177
|
-
|
|
178
|
-
| 能力 | Carlos Flow | 原生 MCP Server | 提示词 / 手写脚本 |
|
|
179
|
-
|------|-------------|-----------------|------------------|
|
|
180
|
-
| 越界拦截 | ✅ 自己跑 `git diff`;执行者动了 scope 外的文件 → **阻断 PASS** | ❌ | ❌ 靠自觉 |
|
|
181
|
-
| 真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
|
|
182
|
-
| 审计链完整性 | ✅ 链式哈希(+ 可选 HMAC),跨天串联,落盘脱敏 | ❌ | ❌ |
|
|
183
|
-
| 可控免检 | ✅ 显式开启 + 自动清零 | ❌ | ❌ 一句话全关 |
|
|
184
|
-
| 诚实派发配额 | ✅ 只计派发 | ❌ | ❌ |
|
|
185
|
-
| 独立复核 | ✅ 内置 `auditor` 角色 | ❌ | ❌ 可选 |
|
|
186
|
-
| 快照 + 还原 | ✅ 自动、原子计划 | ❌ | ❌ 手动 `git revert` |
|
|
187
|
-
| 守护进程生命周期 | ✅ 全自动(Cindy) | ❌ 手动 | ❌ 手动 |
|
|
188
|
-
| 智能触发 | ✅ 三层评分 + 可解释决策 | ❌ | ❌ |
|
|
189
|
-
| 跨平台 | ✅ 单一包 6 平台 | ⚠️ 需自己写配置 | ❌ |
|
|
190
|
-
|
|
191
|
-
> **信任边界说明**:手工改 `state.json` 里的 verdict 能伪造 PASS —— 状态文件不在审计哈希链内。
|
|
192
|
-
> 这是**本地文件系统权限**的信任边界,不是 MCP 工具面能被绕过的漏洞:
|
|
193
|
-
> 能写 `CARLOS_FLOW_HOME` 的人本来就能改自己的代码。
|
|
194
|
-
> 还要注意:(1)未设 `CARLOS_FLOW_AUDIT_KEY` 时是 `plain` 模式(裸 SHA-256),
|
|
195
|
-
> **`ok: true` 不是「没被篡改过」的证明**,调用方看 `mode` 字段;
|
|
196
|
-
> (2)审计记录与状态(`verify.cmd`/`token`/`password`)脱敏后入盘,密钥片段不留明文。
|
|
197
|
-
> 完整说明见 [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) §六。
|
|
198
|
-
|
|
199
|
-
---
|
|
200
|
-
|
|
201
|
-
## 📦 安装
|
|
202
|
-
|
|
55
|
+
## 🚀 准备好开始了吗?
|
|
56
|
+
只需几行命令,为你的 AI 加上这层保护罩。
|
|
203
57
|
```bash
|
|
204
58
|
npm install -g carlos-flow
|
|
59
|
+
carlos init
|
|
205
60
|
```
|
|
206
|
-
|
|
207
|
-
> ⚠️ 报 `ETARGET: No matching version found`?这是 npm 的 **registry 元数据缓存**没刷新:
|
|
208
|
-
> ```bash
|
|
209
|
-
> npm cache clean --force
|
|
210
|
-
> npm view carlos-flow versions # 验证版本存在
|
|
211
|
-
> ```
|
|
212
|
-
|
|
213
|
-
**兼容性要求**:Node.js ≥ 22.0.0 | MCP SDK ≥ 1.29.0 | 零运行时外部依赖
|
|
214
|
-
|
|
215
|
-
---
|
|
216
|
-
|
|
217
|
-
## 🖥️ 平台支持
|
|
218
|
-
|
|
219
|
-
一个包,六个平台。初始化命令会生成对应平台的配置文件。
|
|
220
|
-
|
|
221
|
-
| 平台 | 初始化命令 | 生成产物 | 平台专属能力 |
|
|
222
|
-
|------|-----------|----------|-------------|
|
|
223
|
-
| **Cindy** | `carlos-flow init --target cindy` | `~/.cindy/ghosts/carlos-flow.json` | Bridge 自动守护 + Settings UI |
|
|
224
|
-
| **OpenCode** | `carlos-flow init --target opencode` | `~/.config/opencode/plugin/opencode.json`<br/>+ 项目 `.mcprc` | `chat.message` 钩子级自动触发 |
|
|
225
|
-
| **Cursor / Windsurf** | `carlos-flow init --target cursor` | 项目 `.cursor/mcp.json` | — |
|
|
226
|
-
| **Cline** | `carlos-flow init --target cline` | 项目 `.cline/mcp.json` | — |
|
|
227
|
-
| **VS Code (Copilot)** | `carlos-flow init --target vscode` | 项目 `.vscode/mcp.json` | — |
|
|
228
|
-
| **Claude Desktop** | `carlos-flow init --target claude` | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`<br/>Windows: `%APPDATA%\Claude\claude_desktop_config.json` | — |
|
|
229
|
-
|
|
230
|
-
> 💡 所有平台共用同一套配置字段:`CARLOS_FLOW_HOME`(状态目录)+ `node <root>/src/index.js`(stdio 启动)。
|
|
231
|
-
|
|
232
|
-
---
|
|
233
|
-
|
|
234
|
-
## 🚀 快速开始
|
|
235
|
-
|
|
236
|
-
### 1. 安装并初始化
|
|
237
|
-
|
|
238
|
-
```bash
|
|
239
|
-
npm install -g carlos-flow
|
|
240
|
-
carlos-flow init --target <你的平台> # cindy | opencode | cursor | cline | vscode | claude
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
### 2. 环境变量(可选,都有默认值)
|
|
244
|
-
|
|
245
|
-
```bash
|
|
246
|
-
CARLOS_FLOW_HOME=~/.carlos-flow # 状态/审计目录(跨平台统一)
|
|
247
|
-
CARLOS_FLOW_MCP_ROOT=/path/to/carlos-flow # 源码安装时指向仓库根目录
|
|
248
|
-
BRIDGE_PORT=19099 # Cindy Bridge 端口
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
> 路径一律用**正斜杠**(`/home/you/apps/carlos-flow`)或**双反斜杠**(`D:\\apps\\carlos-flow`)。
|
|
252
|
-
> 单反斜杠在配置里会被当成转义符,`\c`、`\o` 会被吃掉,路径直接失效。
|
|
253
|
-
|
|
254
|
-
### 3. 验证服务正常
|
|
255
|
-
|
|
256
|
-
```bash
|
|
257
|
-
node client/carlos.js flow_status '{"sessionId":"probe"}'
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
期望输出 `"has_card": false` 即表示服务正常。
|
|
261
|
-
|
|
262
|
-
### 4. 走一次完整门禁
|
|
263
|
-
|
|
264
|
-
```bash
|
|
265
|
-
# ① 留痕(记录用户原话,作为 quote 锚点数据源)
|
|
266
|
-
node client/carlos.js flow_add_user_msg '{"sessionId":"demo","text":"给登录接口加参数校验"}'
|
|
267
|
-
|
|
268
|
-
# ② 提交任务卡(scope 是白名单)
|
|
269
|
-
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"}'
|
|
270
|
-
|
|
271
|
-
# ③ 领取派发名额
|
|
272
|
-
node client/carlos.js flow_claim '{"sessionId":"demo","role":"executor"}'
|
|
273
|
-
|
|
274
|
-
# ④ 派发(自动快照 scope 内文件)
|
|
275
|
-
node client/carlos.js flow_dispatch '{"sessionId":"demo","role":"executor"}'
|
|
276
|
-
|
|
277
|
-
# ⑤ 真实执行验证命令
|
|
278
|
-
node client/carlos.js flow_run_verify '{"sessionId":"demo","cwd":"/path/to/project"}'
|
|
279
|
-
|
|
280
|
-
# ⑥ 记录裁定(没有验证通过证据不许记 PASS)
|
|
281
|
-
node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes":"测试通过"}'
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
---
|
|
285
|
-
|
|
286
|
-
## 🔧 MCP 工具参考(19 个)
|
|
287
|
-
|
|
288
|
-
| 工具 | 作用 | 关键约束 |
|
|
289
|
-
|------|------|---------|
|
|
290
|
-
| `flow_protocol` | 读取完整门禁协议(档位、四段合同、错误分层) | — |
|
|
291
|
-
| `flow_add_user_msg` | 写入用户原话 | **quote 锚点的唯一数据源** |
|
|
292
|
-
| `flow_submit_requirement` | 提交/替换任务卡 | 按风险档强制必填项;伪填充被拒 |
|
|
293
|
-
| `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
|
|
294
|
-
| `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
|
|
295
|
-
| `flow_audit_axes` | **派发双轴审计**(Standards / Spec) | 生成两段并行审计 prompt,只读不改 |
|
|
296
|
-
| `flow_audit_submit` | **提交某一轴结论** | 按 `card_ts` 绑定当前卡;WARN 不硬拦;同轴可覆盖;写审计事件可追溯 |
|
|
297
|
-
| `flow_audit_guard` | **两轴门禁自查** | 与 `flow_verdict` 内的门禁同口径 |
|
|
298
|
-
| `flow_save_result` | 保存子 Agent 执行结果 | — |
|
|
299
|
-
| `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr + `output_hash` |
|
|
300
|
-
| `flow_falsify` | **负对照**:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(`|| true`)会被拒;记 PASS 前必做 |
|
|
301
|
-
| `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
|
|
302
|
-
| `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS;返回 `verdict_role` + `warn_findings`(WARN 汇总) |
|
|
303
|
-
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` / `warn_count` |
|
|
304
|
-
| `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
|
|
305
|
-
| `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
|
|
306
|
-
| `flow_bypass` | 开关免检模式 | 需 `confirmed=true`;派发自动清零 |
|
|
307
|
-
| `flow_revert_plan` | 生成原子还原计划 | 只返回计划,不自动执行 |
|
|
308
|
-
| `flow_trigger_check` | 智能触发检查 | 达标即实际激活;未达标如实返回评分 |
|
|
309
|
-
|
|
310
|
-
> **双轴审查**(防假闭环之六):`flow_verdict` 落 PASS 前,必须先 `flow_audit_axes` 派发 Standards(合不合规范 + 坏味道)与 Spec(忠不忠实实现验收)两轴,由 subagent 独立取证后 `flow_audit_submit` 提交。门禁位于负对照**之后**,是 PASS 落定前的最后一道;两轴证据都绑定当前 `card_ts`(旧卡审查不能冒充新卡),任一轴 FAIL 硬拦,WARN 只标注不拦。
|
|
311
|
-
>
|
|
312
|
-
> **WARN 汇总(v2.11.0)**:WARN(坏味道等 judgement call)以前只存在 `state.audit_axes` 里,主 Agent 不主动读就看不到,「带坏味道通过」在汇报里等于被吞掉。现在 `flow_verdict` 与 `flow_status` 都直接返回 `warn_count` / `warn_findings`(只收 `card_ts` 与当前卡一致的轴结论,换卡后旧 WARN 自动失效)。Standards 轴的 prompt 还内联了一份显式坏味道基线(18 条,术语对齐 Fowler《Refactoring》第二版第 3 章,**非原书全表**)—— 判定不再依赖模型记性。
|
|
313
|
-
|
|
314
|
-
---
|
|
315
|
-
|
|
316
|
-
## ⚙️ 配置
|
|
317
|
-
|
|
318
|
-
### 触发器配置
|
|
319
|
-
|
|
320
|
-
路径:`$CARLOS_FLOW_HOME/trigger-config.json`(首次 `init` 自动生成)
|
|
321
|
-
|
|
322
|
-
```json
|
|
323
|
-
{
|
|
324
|
-
"keywordWeights": {
|
|
325
|
-
"评审": 5
|
|
326
|
-
},
|
|
327
|
-
"readOnlyIntentWords": ["讲一下"],
|
|
328
|
-
"mutatingActionWords": ["重构一下"]
|
|
329
|
-
}
|
|
330
|
-
```
|
|
331
|
-
|
|
332
|
-
**合并语义**(重要):
|
|
333
|
-
- `keywordWeights` → **对象合并**(自定义词覆盖同名默认词,其余默认词保留)
|
|
334
|
-
- 词表数组 → **追加去重**(扩展,不是替换)
|
|
335
|
-
- 其余标量 → 覆盖
|
|
336
|
-
|
|
337
|
-
> 早期实现是浅合并,用户写一个自定义词就把整个默认词表(含内置中文流程词)丢掉 —— 中文场景重新变回 0 分。已修复。
|
|
338
|
-
|
|
339
|
-
### 环境变量
|
|
340
|
-
|
|
341
|
-
| 变量 | 默认值 | 说明 |
|
|
342
|
-
|------|-------|------|
|
|
343
|
-
| `CARLOS_FLOW_HOME` | `~/.carlos-flow` | 状态 / 审计 / 快照目录。`~` 会被展开 |
|
|
344
|
-
| `CARLOS_FLOW_MCP_ROOT` | 自动推导 | 源码安装时指向仓库根目录 |
|
|
345
|
-
| `BRIDGE_PORT` | `19099` | Cindy Bridge 监听端口 |
|
|
346
|
-
| `CARLOS_BRIDGE_TOKEN` | 随机生成落盘 | Bridge 本地认证 token(自动生成,存 0600) |
|
|
347
|
-
| `CARLOS_FLOW_AUDIT_KEY` | — | 设置它(≥16 字符)启用 **HMAC** 审计链 —— 发现**有意篡改**必须配它 |
|
|
348
|
-
| `CARLOS_BRIDGE_TIMEOUT_MS` | `180000` | Bridge 请求超时(需 > 服务端 120s 验证上限) |
|
|
349
|
-
| `CARLOS_MCP_TIMEOUT_MS` | `180000` | CLI 客户端 MCP 调用超时 |
|
|
350
|
-
| `CARLOS_TRIGGER_MESSAGE` | — | CLI 模式下注入触发检查用的用户原话 |
|
|
351
|
-
| `OPENCODE_DB_PATH` | 多路探测 | OpenCode 会话库路径(读用户原话用) |
|
|
352
|
-
|
|
353
|
-
---
|
|
354
|
-
|
|
355
|
-
## 🛡️ 门禁体系 —— 门禁自己也要被门禁
|
|
356
|
-
|
|
357
|
-
> 「项目说自己有门禁」是最容易说的一句话,也最容易被证伪。
|
|
358
|
-
> 所以本项目的门禁**自己也有一套门禁**,且分两类:
|
|
359
|
-
|
|
360
|
-
### 一、静态一致性(东西对不对得上)
|
|
361
|
-
|
|
362
|
-
| 脚本 | 查什么 |
|
|
363
|
-
|------|--------|
|
|
364
|
-
| `npm run check:full` | 旧引用 / 个人路径 / 版本号一致性 / 文档死链 / npm 发布集合 / 模板占位符 / package.json 字段 / 双仓残留 / ghost.json 工具清单 |
|
|
365
|
-
| `npm run check:identity` | 身份、版本、文档、产物、安全五类一致性 |
|
|
366
|
-
| `npm run check:lang` | 提交信息与源码注释是否中文(产物语言体检) |
|
|
367
|
-
| `npm run check:readme` | 中英双语 README 是否漂移 |
|
|
368
|
-
| `npm run check:anchors` | 变异体的注入锚点是否仍能命中(防止测试**静默失去守护作用**) |
|
|
369
|
-
|
|
370
|
-
### 二、行为兑现(说了的做到了吗)—— 这一类才是关键
|
|
371
|
-
|
|
372
|
-
| 脚本 | 查什么 | 为什么需要 |
|
|
373
|
-
|------|--------|-----------|
|
|
374
|
-
| `npm run check:claims` | README/工具描述里的每个能力声明,是否都有对应的代码路径 | 静态检查查不出「承诺 vs 实现」的落差 |
|
|
375
|
-
| `npm run check:params` | `inputSchema` 声明的每个参数,是否在 handler 里**真的被读取**;以及有没有「算出却从未使用」的死变量 | 静默失效型 bug(如 `date` 参数)不报错、测试全绿,只是安静地返回错数据 |
|
|
376
|
-
| `npm run check:no-dead-handler` | 同一 request schema 是否被**重复注册** | 重复注册时后注册的覆盖先注册的 → 先注册的是永不执行的死代码,靠注册顺序维持的正确性会被一次重排静默破坏 |
|
|
377
|
-
|
|
378
|
-
### 三、变异测试 —— 用注入退化撞自己最自豪的代码
|
|
379
|
-
|
|
380
|
-
```bash
|
|
381
|
-
npm run test:mutation # 17 类变异体,必须 17/17 全部被抓住
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
变异体不是随机造的,每一条都对应一个**真实退化**,且必须有测试能抓住它:
|
|
385
|
-
|
|
386
|
-
| 变异体 | 注入的退化 | 抓住它的测试 |
|
|
387
|
-
|--------|-----------|-------------|
|
|
388
|
-
| M1 | 激活只打印日志、不真的激活 | e2e |
|
|
389
|
-
| M2 / M3 | claim / verdict 的闸门失效 | e2e |
|
|
390
|
-
| M4 | 会话撞名(清洗后同形共用状态) | trigger |
|
|
391
|
-
| M5 / M6 | scope 不算补齐项 / 半补齐绕过 | e2e |
|
|
392
|
-
| M7 | 空 scope 退回 fail-open | e2e |
|
|
393
|
-
| M8 | 未派发可记 PASS | e2e |
|
|
394
|
-
| M9 | 闸门派生回退(用上一轮 pending 传递) | e2e 19d-3 |
|
|
395
|
-
| M10 / M11 | 普通卡也上闸 / 占位卡硬编码三项 | e2e |
|
|
396
|
-
| M12 | 跨进程锁失效(`wx` → `a`) | concurrency |
|
|
397
|
-
| M13 | 只读意图误判 | trigger |
|
|
398
|
-
| **M14** | **审计链断链**(去掉 prevHash 链接) | audit-chain |
|
|
399
|
-
| **M15** | **审计链校验恒真** | audit-chain |
|
|
400
|
-
| **M16** | **越界检查退回 fail-open** | scope-enforcement |
|
|
401
|
-
| **M17** | **date 参数失效** | audit-chain |
|
|
402
|
-
|
|
403
|
-
### 四、专项真实验证(不靠 mock)
|
|
404
|
-
|
|
405
|
-
| 脚本 | 验什么 |
|
|
406
|
-
|------|--------|
|
|
407
|
-
| `npm run test:scope` | 在**真实 git 仓库**里改文件 → scope 外改动**真的被阻断**;派发前就有的改动**不误伤** |
|
|
408
|
-
| `npm run test:audit` | **真实篡改**审计记录 → hmac 模式必须发现;plain 模式如实标注局限;legacy 记录不误报;date 参数真的生效 |
|
|
409
|
-
| | **跨天链**连通不留断点;脱敏检查确保密钥片段不留明文 |
|
|
410
|
-
| `npm run test:bridge` | 端口上是**别人的 bridge** 时不得复用(否则状态会写到别人的 HOME) |
|
|
411
|
-
| `npm run test:package` | `npm pack` → 装到干净目录 → 从 `node_modules` 拉起 MCP server 走真实握手 |
|
|
412
|
-
| `npm run test:lang` | 语言体检脚本**真的能抓到英文**(防假绿) |
|
|
413
|
-
|
|
414
|
-
> 💡 **给质疑者的可执行入口**:上面每一条命令都可以自己跑一遍。
|
|
415
|
-
> 一个项目宣称「我的门禁是机械的」,最好的证明不是文档,是**让对方自己跑一遍**。
|
|
416
|
-
|
|
417
|
-
---
|
|
418
|
-
|
|
419
|
-
## 🧪 开发
|
|
420
|
-
|
|
421
|
-
```bash
|
|
422
|
-
git clone https://github.com/skyer-now/carlos-flow.git
|
|
423
|
-
cd carlos-flow
|
|
424
|
-
npm install
|
|
425
|
-
|
|
426
|
-
# 全套测试(129 个用例)
|
|
427
|
-
npm run test:all
|
|
428
|
-
|
|
429
|
-
# 单项
|
|
430
|
-
npm run test:e2e # 端到端 62 项
|
|
431
|
-
npm run test:p0 # P0 门禁 22 项
|
|
432
|
-
npm run test:trigger # 触发引擎 29 项
|
|
433
|
-
npm run test:concurrency # 跨进程并发 3 项
|
|
434
|
-
npm run test:acceptance # 验收 13 项
|
|
435
|
-
npm run test:mutation # 变异测试(13/13 变异体全抓住)
|
|
436
|
-
npm run check:anchors # 变异锚点唯一性守护
|
|
437
|
-
npm run check:readme # 双语 README 一致性
|
|
438
|
-
|
|
439
|
-
# 打包
|
|
440
|
-
npm pack
|
|
441
|
-
```
|
|
442
|
-
|
|
443
|
-
### 测试覆盖矩阵
|
|
444
|
-
|
|
445
|
-
| 套件 | 数量 | 覆盖内容 |
|
|
446
|
-
|------|------|---------|
|
|
447
|
-
| `smoke` | 4 | 卡片解析 / 校验 / 状态往返 |
|
|
448
|
-
| `e2e-carlos` | 62 | 全流程 + 激活闸门 + 假闭环防护 + 越界拦截 |
|
|
449
|
-
| `p0-gates` | 22 | P0 级门禁语义(伪填充、类型校验、fail-closed) |
|
|
450
|
-
| `trigger-e2e` | 29 | 三层引擎 + 会话隔离 + 配置合并 + `~` 展开 |
|
|
451
|
-
| `concurrency-e2e` | 3 | 跨进程并发零泄漏 / 零利用 |
|
|
452
|
-
| `e2e-acceptance` | 13 | MCP 路径触发 + 中文词表 + 插件真实开卡 |
|
|
453
|
-
| **合计** | **129** | **全部通过** |
|
|
454
|
-
|
|
455
|
-
---
|
|
456
|
-
|
|
457
|
-
## 📚 文档
|
|
458
|
-
|
|
459
|
-
| 文档 | 说明 |
|
|
460
|
-
|------|------|
|
|
461
|
-
| [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | 智能触发引擎深度指南(配置、评分、激活、反馈学习) |
|
|
462
|
-
| [CHANGELOG.md](./CHANGELOG.md) | 版本历史(Keep a Changelog + SemVer) |
|
|
463
|
-
| [MIGRATION.md](./MIGRATION.md) | 从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移 |
|
|
464
|
-
| [AGENTS.md](./AGENTS.md) | 变更前置索引:改哪类东西先读哪份权威契约 |
|
|
465
|
-
| [docs/AUDIT_REVIEW.md](./docs/AUDIT_REVIEW.md) | 第三方审查报告的逐条核实与决策记录 |
|
|
466
|
-
| [QA 验收报告](./docs/QA_REPORT_v2.5.5.md) | 第三方只读验收(13/13 变异体全抓住) |
|
|
467
|
-
| [变异测试报告](./docs/MUTATION_REPORT_v2.5.5.md) | 变异体注入细节与结果 |
|
|
468
|
-
|
|
469
|
-
---
|
|
470
|
-
|
|
471
|
-
## ❓ 常见问题
|
|
472
|
-
|
|
473
|
-
<details>
|
|
474
|
-
<summary><b>Q: 和普通 MCP Server 有什么区别?</b></summary>
|
|
475
|
-
|
|
476
|
-
普通 MCP Server 暴露工具,**但不施加约束** —— 它信任调用方会正确使用。
|
|
477
|
-
Carlos Flow 的约束在 **服务端运行时强制执行**:越界文件会被 `enforceScope()` 拦下,
|
|
478
|
-
没跑过验证就不许记 PASS,审计日志改一条就断链。
|
|
479
|
-
</details>
|
|
480
|
-
|
|
481
|
-
<details>
|
|
482
|
-
<summary><b>Q: 只在 Cindy 用,还需要装这么多吗?</b></summary>
|
|
483
|
-
|
|
484
|
-
不需要。单一包对所有用户都是**同一个安装体积**(~106 KB),
|
|
485
|
-
不需要额外下载任何平台专属依赖 —— 只是模板文件不同。
|
|
486
|
-
</details>
|
|
487
|
-
|
|
488
|
-
<details>
|
|
489
|
-
<summary><b>Q: 会拖慢我的 Agent 吗?</b></summary>
|
|
490
|
-
|
|
491
|
-
不会。门禁状态是**文件级持久化**,无数据库、无网络、无常驻进程
|
|
492
|
-
(除 Cindy 版的 Bridge,它只在首次调用时拉起)。
|
|
493
|
-
触发引擎是纯 JS 计算,零依赖。
|
|
494
|
-
</details>
|
|
495
|
-
|
|
496
|
-
<details>
|
|
497
|
-
<summary><b>Q: `CARLOS_FLOW_HOME=~/.carlos-flow` 里的 `~` 会展开吗?</b></summary>
|
|
498
|
-
|
|
499
|
-
会。早期版本**不会展开** —— `path.normalize` 只换分隔符,路径仍是字面量,
|
|
500
|
-
状态写到「当前目录下字面名为 `~` 的目录」里,位置诡异极易丢失。
|
|
501
|
-
现已统一展开(`state.js` / `trigger.js` 共用 `expandHome()`),并有回归用例守护。
|
|
502
|
-
</details>
|
|
503
|
-
|
|
504
|
-
<details>
|
|
505
|
-
<summary><b>Q: 免检模式会不会成为后门?</b></summary>
|
|
506
|
-
|
|
507
|
-
免检需**卡片上显式** `confirmed=true`,且 `bypass_ts` 必须晚于 `card_ts`(旧卡的免检不能作用于新卡)。
|
|
508
|
-
最关键的是:**每次派发后自动清零** —— 免检只对当次派发生效,不会变成长期开关。
|
|
509
|
-
</details>
|
|
510
|
-
|
|
511
|
-
<details>
|
|
512
|
-
<summary><b>Q: 中文能用吗?</b></summary>
|
|
513
|
-
|
|
514
|
-
完全支持。中文流程词内置(工作流/门禁/派发/审计/复核/任务卡/子代理/流程/触发/执行/调度/留痕/裁定),
|
|
515
|
-
中文需求同样能触发;普通开发需求(「给接口加个参数校验」)不会误触发。
|
|
516
|
-
</details>
|
|
517
|
-
|
|
518
|
-
<details>
|
|
519
|
-
<summary><b>Q: 旧包还能用吗?</b></summary>
|
|
520
|
-
|
|
521
|
-
能,但已标记 **Deprecated**。迁移方式见 [MIGRATION.md](./MIGRATION.md)。
|
|
522
|
-
</details>
|
|
523
|
-
|
|
524
|
-
---
|
|
525
|
-
|
|
526
|
-
## 🔗 链接
|
|
527
|
-
|
|
528
|
-
| | |
|
|
529
|
-
|---|---|
|
|
530
|
-
| **仓库** | https://github.com/skyer-now/carlos-flow |
|
|
531
|
-
| **npm** | https://www.npmjs.com/package/carlos-flow |
|
|
532
|
-
| **问题反馈** | https://github.com/skyer-now/carlos-flow/issues |
|
|
533
|
-
| **更新日志** | [CHANGELOG.md](./CHANGELOG.md) |
|
|
534
|
-
|
|
535
|
-
---
|
|
536
|
-
|
|
537
|
-
## 🤝 贡献
|
|
538
|
-
|
|
539
|
-
欢迎 PR!提交前请确保:
|
|
540
|
-
|
|
541
|
-
```bash
|
|
542
|
-
npm run test:all # 129/0 全通过
|
|
543
|
-
npm run check:anchors # 变异锚点未失效
|
|
544
|
-
npm run check:readme # 双语 README 未漂移
|
|
545
|
-
```
|
|
546
|
-
|
|
547
|
-
详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
|
548
|
-
|
|
549
|
-
---
|
|
550
|
-
|
|
551
|
-
## 📄 License
|
|
552
|
-
|
|
553
|
-
[MIT](./LICENSE) © Carlos Flow Contributors
|