carlos-flow 0.0.0-stage → 2.5.9

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.md CHANGED
@@ -1,3 +1,218 @@
1
- # Temporary Holding Version
1
+ # Carlos Flow — 统一分发版(Cindy / OpenCode / Cursor / Cline / VS Code / Claude Desktop)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **面向 AI 编码 Agent 的机械门禁**:留痕 → 派发 → 验证 → 裁定 → 审计 → 还原
4
+ > 把"相信 Agent"变成"验证 Agent"——机器级 scope 限制、真实命令执行、防篡改审计链。
5
+
6
+ **语言 / Languages:** [中文](README.zh.md) | [English](README.en.md)
7
+ **版本 / Version:** 2.5.9 | **License:** MIT | **CI:** passing | **Node.js:** 22+ | **MCP:** 1.29+
8
+
9
+ ---
10
+
11
+ ## 🎯 一次安装,全平台可用
12
+
13
+ ```bash
14
+ npm install -g carlos-flow
15
+ # 或
16
+ npx carlos-flow@latest init --target <平台>
17
+ ```
18
+
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) |
27
+
28
+ > 💡 **环境变量**:`CARLOS_FLOW_HOME=~/.carlos-flow`(默认),`CARLOS_FLOW_MCP_ROOT`(源码安装时指向本仓库根目录)
29
+
30
+ ---
31
+
32
+ ## 🆕 v2.5.9 更新速览
33
+
34
+ ### ✨ 统一分发包
35
+ - 单一 npm 包 `carlos-flow` 支持 **6 大主流 AI 编码平台**
36
+ - 核心 MCP Server (`src/index.js`) 零平台耦合,纯标准协议
37
+ - 平台差异仅在初始化模板,维护成本大幅降低
38
+
39
+ ### 🔧 智能触发引擎(v2.5.5 引入,持续加固)
40
+ 引擎会读取你的输入,自动判断现在是否该启动 Carlos 工作流——并且**告诉你为什么**。
41
+
42
+ | 层 | 组件 | 做什么 | 为什么需要它 |
43
+ |----|------|--------|-------------|
44
+ | **L1** | `DynamicTriggerManager` | 动态计算"本会话还允许触发几次" | 固定上限要么太吵、要么太严;会话越长、任务越复杂,上限自动放宽 |
45
+ | **L2** | `TriggerScorer` | 给每条消息打分:关键词 50 + 上下文 30 + 意图 20,加权后满分 **38** | 触发与否必须**可解释**——每次都告诉你命中了哪些词、得了多少分 |
46
+ | **L3** | `TriggerDecisionEngine` | 四档决策:`trigger` / `review` / `ignore` / `throttled` | 把"要不要触发"从模糊直觉变成明确规则 |
47
+
48
+ **两条触发路径,行为完全一致**:
49
+ | 路径 | 怎么触发 | 适用 |
50
+ |------|---------|------|
51
+ | **① MCP 工具** | 调 `flow_trigger_check`(传 `sessionId` + `message`),达标即**实际激活** | 任何 MCP 宿主 |
52
+ | **② 命令行客户端** | `node client/carlos.js flow_status '{"sessionId":"x","triggerMessage":"run dispatch workflow"}'` | 脚本 / 调试 |
53
+
54
+ ---
55
+
56
+ ## 🚀 30 秒快速开始
57
+
58
+ ### 1. 安装
59
+ ```bash
60
+ npm install -g carlos-flow
61
+ ```
62
+ > ⚠️ **如果报 `ETARGET: No matching version found`** —— npm registry 元数据缓存未刷新。
63
+ > ```bash
64
+ > npm cache clean --force
65
+ > npm view carlos-flow versions # 验证版本存在
66
+ > ```
67
+
68
+ ### 2. 一键初始化(按你的平台选一个)
69
+ ```bash
70
+ # Cindy 用户
71
+ carlos-flow init --target cindy
72
+
73
+ # OpenCode 用户
74
+ carlos-flow init --target opencode
75
+
76
+ # Cursor / Windsurf 用户
77
+ carlos-flow init --target cursor
78
+
79
+ # Cline 用户
80
+ carlos-flow init --target cline
81
+
82
+ # VS Code (Copilot) 用户
83
+ carlos-flow init --target vscode
84
+
85
+ # Claude Desktop 用户
86
+ carlos-flow init --target claude
87
+ ```
88
+
89
+ ### 3. 设置环境变量(可选,有默认值)
90
+ ```bash
91
+ # 默认值已可用,如需自定义:
92
+ # CARLOS_FLOW_HOME=~/.carlos-flow # 状态/审计目录(跨平台)
93
+ # CARLOS_FLOW_MCP_ROOT=/path/to/carlos-flow # 源码安装时指向仓库根目录
94
+ # BRIDGE_PORT=19099 # Cindy Bridge 端口
95
+ ```
96
+
97
+ ### 4. 重启并验证
98
+ ```bash
99
+ # CLI 验证
100
+ node client/carlos.js flow_status '{"sessionId":"probe"}'
101
+ # 期望输出里 has_card: false 即表示服务正常
102
+ ```
103
+
104
+ ---
105
+
106
+ ## 🌟 核心能力
107
+
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 认证、限流 | ❌ 手动 / 手动 |
119
+
120
+ ### 🆕 智能触发引擎 — `src/trigger.js`
121
+ **动态决策 → 判断 → 激活** 完整闭环:
122
+
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/>闸门放行"]
137
+ ```
138
+
139
+ **关键特性**:
140
+ - 🎚️ **动态上限**:`5 + 会话时长(小时)×0.5 + 复杂度×2 − 窗口内已触发×0.3`,封顶 15
141
+ - 🛡️ **不打扰**:同会话最短间隔 5 分钟;触发越多上限**越低**(惩罚项)
142
+ - 📊 **评分透明**:返回完整 `breakdown`(命中关键词 / 上下文词 / 意图类型)
143
+ - ⚖️ **限流也如实**:被限流时照样返回真实评分与置信度
144
+ - 🧠 **反馈学习**:负反馈占多数时自动抬高触发阈值,更保守
145
+ - 🇨🇳 **中文开箱即用**:内置中文流程词;普通开发需求**不会误触发**
146
+
147
+ ---
148
+
149
+ ## 📦 包结构
150
+
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 通过)
169
+ ```
170
+
171
+ ---
172
+
173
+ ## 📚 详细文档
174
+
175
+ - [`TRIGGER_GUIDE.md`](TRIGGER_GUIDE.md) — 智能触发引擎完整使用指南
176
+ - [`CHANGELOG.md`](CHANGELOG.md) — 版本历史
177
+ - [QA 验收报告](docs/QA_REPORT_v2.5.5.md) — 第三方只读验收(13/13 变异体全抓住)
178
+
179
+ ---
180
+
181
+ ## 🛠️ 开发与测试
182
+
183
+ ```bash
184
+ # 克隆源码
185
+ git clone https://github.com/skyer-now/carlos-flow.git
186
+ cd carlos-flow
187
+
188
+ # 安装依赖
189
+ npm install
190
+
191
+ # 跑全套测试(255 个用例)
192
+ npm run test:all
193
+
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 项
199
+ npm run test:acceptance # 验收 13 项
200
+
201
+ # 变异测试(注入缺陷确认测试能抓住)
202
+ npm run test:mutation
203
+
204
+ # 本地打包
205
+ npm pack
206
+ ```
207
+
208
+ ---
209
+
210
+ ## 🤝 贡献
211
+
212
+ 欢迎 PR!请先跑 `npm run test:all` 确保 255/0 全通过。
213
+
214
+ ---
215
+
216
+ ## 📄 License
217
+
218
+ MIT © Carlos Flow Contributors
package/README.zh.md ADDED
@@ -0,0 +1,218 @@
1
+ # Carlos Flow — 统一分发版(Cindy / OpenCode / Cursor / Cline / VS Code / Claude Desktop)
2
+
3
+ > **面向 AI 编码 Agent 的机械门禁**:留痕 → 派发 → 验证 → 裁定 → 审计 → 还原
4
+ > 把"相信 Agent"变成"验证 Agent"——机器级 scope 限制、真实命令执行、防篡改审计链。
5
+
6
+ **语言 / Languages:** [中文](README.zh.md) | [English](README.en.md)
7
+ **版本 / Version:** 2.5.9 | **License:** MIT | **CI:** passing | **Node.js:** 22+ | **MCP:** 1.29+
8
+
9
+ ---
10
+
11
+ ## 🎯 一次安装,全平台可用
12
+
13
+ ```bash
14
+ npm install -g carlos-flow
15
+ # 或
16
+ npx carlos-flow@latest init --target <平台>
17
+ ```
18
+
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) |
27
+
28
+ > 💡 **环境变量**:`CARLOS_FLOW_HOME=~/.carlos-flow`(默认),`CARLOS_FLOW_MCP_ROOT`(源码安装时指向本仓库根目录)
29
+
30
+ ---
31
+
32
+ ## 🆕 v2.5.9 更新速览
33
+
34
+ ### ✨ 统一分发包
35
+ - 单一 npm 包 `carlos-flow` 支持 **6 大主流 AI 编码平台**
36
+ - 核心 MCP Server (`src/index.js`) 零平台耦合,纯标准协议
37
+ - 平台差异仅在初始化模板,维护成本大幅降低
38
+
39
+ ### 🔧 智能触发引擎(v2.5.5 引入,持续加固)
40
+ 引擎会读取你的输入,自动判断现在是否该启动 Carlos 工作流——并且**告诉你为什么**。
41
+
42
+ | 层 | 组件 | 做什么 | 为什么需要它 |
43
+ |----|------|--------|-------------|
44
+ | **L1** | `DynamicTriggerManager` | 动态计算"本会话还允许触发几次" | 固定上限要么太吵、要么太严;会话越长、任务越复杂,上限自动放宽 |
45
+ | **L2** | `TriggerScorer` | 给每条消息打分:关键词 50 + 上下文 30 + 意图 20,加权后满分 **38** | 触发与否必须**可解释**——每次都告诉你命中了哪些词、得了多少分 |
46
+ | **L3** | `TriggerDecisionEngine` | 四档决策:`trigger` / `review` / `ignore` / `throttled` | 把"要不要触发"从模糊直觉变成明确规则 |
47
+
48
+ **两条触发路径,行为完全一致**:
49
+ | 路径 | 怎么触发 | 适用 |
50
+ |------|---------|------|
51
+ | **① MCP 工具** | 调 `flow_trigger_check`(传 `sessionId` + `message`),达标即**实际激活** | 任何 MCP 宿主 |
52
+ | **② 命令行客户端** | `node client/carlos.js flow_status '{"sessionId":"x","triggerMessage":"run dispatch workflow"}'` | 脚本 / 调试 |
53
+
54
+ ---
55
+
56
+ ## 🚀 30 秒快速开始
57
+
58
+ ### 1. 安装
59
+ ```bash
60
+ npm install -g carlos-flow
61
+ ```
62
+ > ⚠️ **如果报 `ETARGET: No matching version found`** —— npm registry 元数据缓存未刷新。
63
+ > ```bash
64
+ > npm cache clean --force
65
+ > npm view carlos-flow versions # 验证版本存在
66
+ > ```
67
+
68
+ ### 2. 一键初始化(按你的平台选一个)
69
+ ```bash
70
+ # Cindy 用户
71
+ carlos-flow init --target cindy
72
+
73
+ # OpenCode 用户
74
+ carlos-flow init --target opencode
75
+
76
+ # Cursor / Windsurf 用户
77
+ carlos-flow init --target cursor
78
+
79
+ # Cline 用户
80
+ carlos-flow init --target cline
81
+
82
+ # VS Code (Copilot) 用户
83
+ carlos-flow init --target vscode
84
+
85
+ # Claude Desktop 用户
86
+ carlos-flow init --target claude
87
+ ```
88
+
89
+ ### 3. 设置环境变量(可选,有默认值)
90
+ ```bash
91
+ # 默认值已可用,如需自定义:
92
+ # CARLOS_FLOW_HOME=~/.carlos-flow # 状态/审计目录(跨平台)
93
+ # CARLOS_FLOW_MCP_ROOT=/path/to/carlos-flow # 源码安装时指向仓库根目录
94
+ # BRIDGE_PORT=19099 # Cindy Bridge 端口
95
+ ```
96
+
97
+ ### 4. 重启并验证
98
+ ```bash
99
+ # CLI 验证
100
+ node client/carlos.js flow_status '{"sessionId":"probe"}'
101
+ # 期望输出里 has_card: false 即表示服务正常
102
+ ```
103
+
104
+ ---
105
+
106
+ ## 🌟 核心能力
107
+
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 认证、限流 | ❌ 手动 / 手动 |
119
+
120
+ ### 🆕 智能触发引擎 — `src/trigger.js`
121
+ **动态决策 → 判断 → 激活** 完整闭环:
122
+
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/>闸门放行"]
137
+ ```
138
+
139
+ **关键特性**:
140
+ - 🎚️ **动态上限**:`5 + 会话时长(小时)×0.5 + 复杂度×2 − 窗口内已触发×0.3`,封顶 15
141
+ - 🛡️ **不打扰**:同会话最短间隔 5 分钟;触发越多上限**越低**(惩罚项)
142
+ - 📊 **评分透明**:返回完整 `breakdown`(命中关键词 / 上下文词 / 意图类型)
143
+ - ⚖️ **限流也如实**:被限流时照样返回真实评分与置信度
144
+ - 🧠 **反馈学习**:负反馈占多数时自动抬高触发阈值,更保守
145
+ - 🇨🇳 **中文开箱即用**:内置中文流程词;普通开发需求**不会误触发**
146
+
147
+ ---
148
+
149
+ ## 📦 包结构
150
+
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 通过)
169
+ ```
170
+
171
+ ---
172
+
173
+ ## 📚 详细文档
174
+
175
+ - [`TRIGGER_GUIDE.md`](TRIGGER_GUIDE.md) — 智能触发引擎完整使用指南
176
+ - [`CHANGELOG.md`](CHANGELOG.md) — 版本历史
177
+ - [QA 验收报告](docs/QA_REPORT_v2.5.5.md) — 第三方只读验收(13/13 变异体全抓住)
178
+
179
+ ---
180
+
181
+ ## 🛠️ 开发与测试
182
+
183
+ ```bash
184
+ # 克隆源码
185
+ git clone https://github.com/skyer-now/carlos-flow.git
186
+ cd carlos-flow
187
+
188
+ # 安装依赖
189
+ npm install
190
+
191
+ # 跑全套测试(255 个用例)
192
+ npm run test:all
193
+
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 项
199
+ npm run test:acceptance # 验收 13 项
200
+
201
+ # 变异测试(注入缺陷确认测试能抓住)
202
+ npm run test:mutation
203
+
204
+ # 本地打包
205
+ npm pack
206
+ ```
207
+
208
+ ---
209
+
210
+ ## 🤝 贡献
211
+
212
+ 欢迎 PR!请先跑 `npm run test:all` 确保 255/0 全通过。
213
+
214
+ ---
215
+
216
+ ## 📄 License
217
+
218
+ MIT © Carlos Flow Contributors