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.
@@ -0,0 +1,28 @@
1
+ # Carlos 工作流 - OpenCode MCP 配置模板
2
+ # 复制为 ~/.config/opencode/.mcprc 并修改路径
3
+
4
+ mcpServers:
5
+ carlos-flow:
6
+ command: "node"
7
+ args: ["__ROOT__/src/index.js"]
8
+ env:
9
+ CARLOS_FLOW_HOME: "<CARLOS_FLOW_HOME>"
10
+ # 可选:如需使用 rea 工具
11
+ # REA_MCP_ROOT: "<REA_MCP_ROOT>"
12
+ # GHIDRA_INSTALL_DIR: "<GHIDRA_HOME>"
13
+ # JAVA_HOME: "<JAVA_HOME>"
14
+ # NODE_PATH: "node"
15
+
16
+ # 可选:rea 逆向分析工具(需单独安装 Ghidra + JDK 21)
17
+ # rea:
18
+ # command: "node"
19
+ # args: ["<REA_MCP_ROOT>/node_modules/rea-agents/scripts/rea.mjs", "mcp"]
20
+ # env:
21
+ # GHIDRA_INSTALL_DIR: "<GHIDRA_HOME>"
22
+ # JAVA_HOME: "<JAVA_HOME>"
23
+
24
+ # 说明:
25
+ # - __ROOT__ 替换为本仓库根目录绝对路径(含 src/)
26
+ # - <CARLOS_FLOW_HOME> 替换为状态/审计目录,如 ~/carlos-flow 或 ~/opencode-backups
27
+ # - Windows 路径用正斜杠 / 或双反斜杠 \
28
+ # - OpenCode 2.2.2+ 读取此文件或 opencode.json(二选一生效)
package/CHANGELOG.md ADDED
@@ -0,0 +1,176 @@
1
+ # 变更日志 | Changelog
2
+
3
+ > 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)
4
+ > Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), versioning follows [SemVer](https://semver.org/)
5
+
6
+ ---
7
+
8
+ ## [2.6.0] - 2026-11-07 — 单包统一分发(6 大平台)+ 文档全面重写
9
+
10
+ ### 🎯 架构重构 | Breaking Change
11
+
12
+ > **两个包合并为一个**:`carlos-flow-cindy` + `carlos-flow-opencode` → **`carlos-flow`**
13
+ >
14
+ > 合并的根因不是“想统一”,而是**维护成本**:两套包共享 100% 的核心逻辑
15
+ > (`state.js` / `trigger.js` / `card.js` / `dispatch.js` / `protocol.js` / `index.js`),
16
+ > 却要各自发版、各自打 tag、各自跑 CI —— 版本漂移是必然结果
17
+ > (合并前就出现过 `cindy@2.5.9` 与 `opencode@2.5.8` 并存)。
18
+ > 合并后核心逻辑**零分叉**,版本永远一致。
19
+ >
20
+ > **迁移指南**:见 [MIGRATION.md](./MIGRATION.md)
21
+
22
+ | 变更 | 之前 | 现在 |
23
+ |------|------|------|
24
+ | **npm 包名** | `carlos-flow-cindy` + `carlos-flow-opencode` | **`carlos-flow`**(单一包) |
25
+ | **bin 命令** | `carlos-flow` / `carlos-flow-cindy` / `carlos-flow-opencode`(三个包九个入口) | `carlos-flow` + 两个兼容别名(一个包三个入口) |
26
+ | **版本管理** | 双版本,易漂移 | 单版本,一致 |
27
+ | **平台覆盖** | Cindy / OpenCode | Cindy / OpenCode / Cursor / Cline / VS Code / Claude Desktop |
28
+
29
+ ### ✨ 新增 | Added
30
+
31
+ - **`carlos-flow init --target <platform>`** —— 一键生成对应平台的 MCP 配置:
32
+ - `cindy` → `~/.cindy/ghosts/carlos-flow.json`
33
+ - `opencode` → `~/.config/opencode/plugin/opencode.json` + 项目 `.mcprc`
34
+ - `cursor` → 项目 `.cursor/mcp.json`
35
+ - `cline` → 项目 `.cline/mcp.json`
36
+ - `vscode` → 项目 `.vscode/mcp.json`
37
+ - `claude` → `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
38
+ / `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
39
+ - **`templates/` 目录** —— 4 套平台配置模板(Cursor / Cline / VS Code / Claude),
40
+ 统一使用 `__ROOT__` 占位符,由 `init` 渲染成实际路径
41
+ - **`MIGRATION.md`** —— 从旧包迁移的完整指南(命令对照、配置文件位置、行为差异)
42
+ - **`package.json` `exports` 字段** —— `carlos-flow/cindy`、`carlos-flow/opencode`、
43
+ `carlos-flow/trigger-config` 子路径导出,宿主可按需引用清单与默认配置
44
+
45
+ ### 🐛 修复 | Fixed
46
+
47
+ | # | 问题 | 影响 | 修复 |
48
+ |---|------|------|------|
49
+ | T-59 | `CARLOS_FLOW_HOME` 的 `~` 在 `OPENCODE_DB_PATH` 等环境变量上不展开 | Windows 下 `CARLOS_OPENCODE_DB=~/.opencode` 字面写入,OpenCode 用户拿不到原话 → quote 锚点校验失败 → 卡片无法提交 | `state.js` / `trigger.js` 统一走 `expandHome()`(`~`、`~/x`、`~\x` 三种写法全覆盖) |
50
+ | T-60 | `release.mjs` 硬编码双仓身份(`carlos-flow-cindy` / `carlos-flow-opencode`) | 单包化后身份自检直接失败,**发不了版** | 重写为单包发布器:身份自检 → 版本/lock/CHANGELOG/ghost.json 一致性 → 测试 → 打包内容检查 → 推送 main + tag |
51
+ | T-61 | `client/carlos.js` 的 `ROOT` 默认取 `process.cwd()` | 源码目录执行时找不到 `ghost.json` / `templates/`,`init` 报 ENOENT | 改为从脚本自身位置推导包根目录(`client/` → 上级),`CARLOS_FLOW_MCP_ROOT` 仍可覆盖 |
52
+ | T-62 | `init` 的目标白名单只认 `cindy` / `opencode` | 新增平台的 `init --target cursor` 被拒 | 白名单扩展到 6 个平台,错误提示同步列出全部合法值 |
53
+ | T-63 | 包的 `files` 白名单缺 `templates/` | 初始化模板不会进 tarball,`init --target cursor` 装完即失败 | `files` 补入 `templates/`,并用 `npm pack --dry-run` 逐项核对 |
54
+ | T-64 | `ghost.json` / `opencode.json` 里的路径写死为仓库内相对路径 | 安装到 npm 全局目录后路径全错 | 统一改为 `__ROOT__` 占位符,由 `init` 渲染成实际绝对路径 |
55
+ | T-65 | `flow_run_verify` 的工作目录只用 `process.cwd()` | MCP server 是**常驻进程**,它的 cwd 是**启动时**的目录(可能是几个月前的旧仓库)→ `verify.cmd` 在错误目录执行、路径全错 → 门禁把这种失败当成「验证不通过」→ **真 PASS 被误杀** | 工作目录优先级改为:显式 `cwd` > 卡片提交时的项目目录(`card.env.project`)> server 进程 cwd;新增回归用例 23d 守护 |
56
+ | T-66 | Bridge 的 `REQUEST_TIMEOUT` 固定 **5s** | `flow_run_verify` 的服务端内部超时是 120s(真实 spawn `verify.cmd`),但 Bridge 5s 就断 —— **任何耗时 >5s 的验证命令必然超时失败**(如 `npm test`),用户只看到「Timeout」,而服务端那边命令其实跑得好好的 | 默认改为 180s(> 服务端 120s 上限),可用 `CARLOS_BRIDGE_TIMEOUT_MS` 覆盖 |
57
+ | T-67 | CLI 客户端的 MCP 调用超时固定 **5s** | 同上,且比服务端短得多 → `flow_run_verify` 从命令行调用**永远失败** | 改为 180s,可用 `CARLOS_MCP_TIMEOUT_MS` 覆盖 |
58
+
59
+ ### 📚 文档 | Documentation
60
+
61
+ > 全面重写,按顶级开源项目(React / Vue / TypeScript / Kubernetes)的文档标准组织信息架构。
62
+
63
+ - **README** —— 全新信息架构:
64
+ - 徽章栏 + TL;DR(30 秒看懂这是什么、解决什么问题)
65
+ - **痛点对照表** —— 「你说 X / Agent 实际做 Y」直接展示约束从建议变机械
66
+ - **核心亮点** —— 6 大亮点(零分叉跨平台架构 / 智能触发引擎 / 反自欺激活闸门 /
67
+ Fail-closed 语义 / 变异测试守护 / 跨进程并发安全)
68
+ - **技术框架** —— Mermaid 分层架构图 + 五层职责表(哪层有平台耦合、哪层零耦合)
69
+ - **能力矩阵** —— 对比原生 MCP Server 与提示词方案,逐项标注 ✅/❌
70
+ - **15 个 MCP 工具参考表** —— 每个工具的作用与关键约束
71
+ - **配置说明** —— 触发器配置合并语义(追加≠替换)+ 7 个环境变量
72
+ - **测试覆盖矩阵** —— 6 个套件 128 个用例逐项说明
73
+ - **FAQ 7 问** —— 含信任边界、免检是否后门、中文支持、性能影响
74
+ - **CHANGELOG** —— 按 Keep a Changelog 重构,2.5.9 明确标注 Breaking Change 与迁移指引
75
+ - **TRIGGER_GUIDE** —— 补充三层架构详解、评分公式、配置合并语义、激活闸门时序
76
+ - **MIGRATION** —— 新增:旧包 → 新包命令对照、配置文件位置对照、行为差异说明
77
+ - 中英双语**零差异同步**(`npm run check:readme` 守护)
78
+
79
+ ### 🔬 验证 | Verification
80
+
81
+ - 全套测试 **129/0 通过**(smoke 4 / e2e 62 / p0 22 / trigger 29 / concurrency 3 / acceptance 13)
82
+ - 6 平台 `init --target` 命令逐个实测通过
83
+ - 旧包 `carlos-flow-cindy@2.5.9` / `carlos-flow-opencode@2.5.9` 已标记 **Deprecated** 并提示迁移
84
+
85
+ ---
86
+
87
+ ## [2.5.9] - 2026-11-06 — 清除全部个人私有路径(安装/分发可用性修复)
88
+
89
+ ### 🐛 修复 | Fixed
90
+
91
+ > 这一版修的全是**会跟着包分发给所有人**的问题 —— 开发机路径被写进了产物里。
92
+ > 用户按文档照抄必然失败,且无法自行察觉。
93
+
94
+ | # | 问题 | 影响 | 修复 |
95
+ |---|------|------|------|
96
+ | T-52 | Cindy 插件设置页默认值写死 `D:/cindy/carlos-flow-mcp` | Cindy 用户**开箱即见**一个开发者本机的无效路径(目录名根本不存在) | 默认值改为空(留空即用插件自带 `src/`),placeholder 改为通用说明 |
97
+ | T-53 | `scripts/verify-activation-e2e.sh` 写死 `D:/cindy/publish-output/carlos-flow-cindy` | 该脚本**随包分发**:用户跑会 `cd` 到不存在的路径;且在 **opencode 包里还指向 cindy 仓**(跨仓串味) | 根目录改为从**脚本自身位置**推导(`scripts/` → 仓库根),两仓一致 |
98
+ | T-54 | README 安装示例写死 `D:/dev-env/node-v22.23.4-win-x64/...`、`C:/Users/EDY/.carlos-flow` | **用户照抄必失败**(路径不存在 / 指向别人的用户名目录) | 改为 `<npm 全局目录>` 占位符 + `npm root -g` 推导说明;`CARLOS_FLOW_HOME` 改用 `~/.carlos-flow` 平台无关写法 |
99
+ | T-55 | README 环境变量表 / 路径说明 / QA 报告残留 `D:/dev-env/rea`、`D:/dev-env/ghidra/...`、`D:/dev-env/jdk-...`、`D:/cindy/.qa-logs/...` | 继续散落开发者本机路径 | 全部替换为通用示例(`/opt/rea`、`/opt/ghidra_*`、`/usr/lib/jvm/*`);QA 报告改为指向 CI 输出 |
100
+ | T-56 | README 声称 Windows 配置目录是 `%APPDATA%opencode` | **实证是错的**:OpenCode 走 XDG 风格,Windows 上真正被读的是 `~/.config/opencode/`(`$env:USERPROFILE.configopencode`)。照 README 放到 `%APPDATA%` 的用户 → 配置读不到 → **MCP server 根本不启动** | README 统一改为「所有平台都是 `~/.config/opencode/`」,并给出 Windows 的 `$env:USERPROFILE.configopencode` 写法 + 明确警示「不是 %APPDATA%」(中文/英文 FAQ 同步) |
101
+ | T-57 | `CARLOS_FLOW_HOME=~/.carlos-flow` **不会被展开** | `path.normalize` 只换分隔符不展开 `~` → 状态/审计链写到**当前工作目录下字面名为 `~` 的目录**(实测 `FLOW_HOME = ~.carlos-flow`),位置诡异极易丢失 | `state.js` / `trigger.js` 新增 `expandHome()`,统一展开 `~`、`~/...`(Windows 同时支持 `~`);新增回归用例(trigger 29 项) |
102
+ | T-58 | `scripts/verify-install-e2e.sh` 里路径内插进 `node -e` 字符串 | Windows 路径含**反斜杠与空格** → 被拆坏,测试在 Windows 上假失败(实测 tools/list 返回 0 个工具) | 路径一律经**环境变量**传给 node 进程;包目录布局多平台探测(lib/node_modules、node_modules、Lib/…) |
103
+
104
+ > 补充:另修正 `verify-activation-e2e.sh` 的跨仓串味(opencode 包里原本指向 cindy 仓),
105
+ > 以及 README 里 `D:/dev-env/rea`、`ghidra`、`jdk` 等开发机路径(全部换成通用示例)。
106
+
107
+
108
+
109
+ ### 🧪 新增 | Added
110
+
111
+ - **`scripts/verify-install-e2e.sh`** —— 「从没见过本项目的用户」视角的安装验收:
112
+ 从真实 npm registry 装包(独立 prefix,模拟干净环境)→ 检查包内容完整性 →
113
+ 验证触发器模板是合法 JSON 且可被引擎读取 → 拉起 MCP server 走真实 JSON-RPC
114
+ (`tools/list` / `flow_status` / `flow_trigger_check`)→ 审计包内无个人私有路径。
115
+ 跨平台(Windows / Linux 均实测通过);路径一律经环境变量传给 node,**不内插进 `node -e` 字符串**
116
+ (Windows 路径含反斜杠与空格,内插会被拆坏)。
117
+
118
+
119
+ ## [2.5.8] - 2026-11-06 — 修包内容与文档不一致 + 变异体锚点加固
120
+
121
+ ### 🐛 修复 | Fixed
122
+
123
+ | # | 问题 | 影响 | 修复 |
124
+ |---|------|------|------|
125
+ | T-47 | `trigger-config.usable.json` 整份含 `//` 注释 ⇒ **不是合法 JSON** | 复制成 trigger-config.json 后 `JSON.parse` 抛错 → 配置被整体丢弃、静默回退默认词表 ⇒ 用户以为「复制即可生效」,实际自定义词**一条都不生效** | 改为纯 JSON;`trigger-config.example.json` 补上真实可配置键(原先真键都带 `_` 前缀,直接复制同样无效) |
126
+ | T-48 | README 安装命令钉死 `@2.5.5` | 用户照文档装不到含 bin 修复的版本,老 EEXIST 照原样复现 | 改为不钉版本(`npm install -g carlos-flow-opencode`),避免文档随发版过时;版本行同步;`docs/` 报告链接改 GitHub 绝对链接(`docs/` 不在 npm files 白名单,相对链接在 npm 页面 404) |
127
+ | T-49 | `.mutation-report.md` 未被 `.gitignore` 覆盖 | 跑一次变异测试就脏工作区 ⇒ `release.mjs` 的「工作区干净」硬拦、**发不了** | 加 `.gitignore` + 把历史上误提交的该文件取消跟踪并删除;同时清理根目录 13 个死进程残留的 `bridge-*.pid` |
128
+ | T-50 | M6/M9 **共用同一段 from 锚点**、M10 的 from 仅 2 行 | 该段一改缩进/注释 → 多个变异体同时 SKIP:**静默失去守护作用**,而历史报告仍显示「13/13 全部被抓住」 | 三个锚点各自唯一且更长;新增 `scripts/check-mutant-anchors.mjs`(`npm run check:anchors`)+ 接入 CI,锚点失效立刻报错 |
129
+ | T-51 | `release.mjs` 的跳过逻辑按**标签**、目标路径按**身份**解析 —— 两者不同源 | 在 opencode 仓**不带** `--include-peer` 时:「opencode」分支被跳过(跳掉**自己**),「cindy」分支照跑却推了**对方** ⇒ **opencode 包永不发布,反而去发 cindy**,而日志还写「跳过 opencode」 | 推送循环重构为「跳过与路径同源于身份」:本仓**始终**发布,对方仓受 `--include-peer` 约束;两个标签分支合并为一段,日志带仓名与身份标记。四种组合的决策推演已全部验证正确 |
130
+
131
+ > 实测:两个触发器模板复制后,自定义词「评审」生效、默认中文词「门禁」保留、只读词「讲一下」已追加。
132
+
133
+
134
+ ## [2.5.7] - 2026-11-06 — 修 bin 名冲突:两个包可同时全局安装
135
+
136
+ ### 🐛 修复 | Fixed
137
+
138
+ | # | 问题 | 影响 | 修复 |
139
+ |---|------|------|------|
140
+ | T-46 | `carlos-flow-cindy` 与 `carlos-flow-opencode` 声明了**同名 bin** `carlos-flow` | `npm install -g` 两个包时后者与前者互斥 → **EEXIST 报错,两个包无法共存** | npm 的规则是同名 bin 不能共存,必须有一个让位:`carlos-flow-cindy` 保留 `carlos-flow`(通用名)并新增别名 `carlos-flow-cindy`;`carlos-flow-opencode` 只用 `carlos-flow-opencode`。opencode 用户升级后请改用新命令名(README 用法本就是 `node client/carlos.js ...`,不依赖 bin 名) |
141
+
142
+ > 实测:修复前 `npm install -g carlos-flow-cindy@2.5.6 carlos-flow-opencode@2.5.6` 报 EEXIST,修复后两包可同时安装。
143
+
144
+
145
+ ## [2.5.6] - 2026-11-06 — 门禁伪填充绕过修复 + 触发器接入 MCP 路径
146
+
147
+ ### 🐛 修复 | Fixed
148
+
149
+ | # | 问题 | 影响 | 修复 |
150
+ |---|------|------|------|
151
+ | T-34 | `acceptance` 必填校验只看数组长度 | `[""]` / `[null]` / `[0]` / `[{}]` 等伪填充被当作「已填」——空验收标准的卡片能过校验,激活闸门也会误判为「已补齐」而解开 | 必填校验与闸门推导统一改为**内容判定**(严格口径:每个元素都必须是有效非空字符串) |
152
+ | T-35 | 卡片文本字段用 `String(x)` 归一化 | `[null]`→`["null"]`、`[{}]`→`["[object Object]"]`,垃圾串被当成合法验收标准 | 取消过滤式归一化,两条入口(结构化 / cardText)均保留原始类型,由校验器统一判定 |
153
+ | T-36 | `trigger-config.json` 浅合并 | 用户写一个自定义词就把默认词表(含内置中文流程词)整个丢掉,中文场景重新变回 0 分 | 改**深合并**:keywordWeights 合并、词表数组追加去重 |
154
+ | T-37 | README FAQ / TRIGGER_GUIDE 仍写「默认词表为英文」 | 文档与实现不符,用户据此以为中文不触发 | 全部更正,并说明自定义是**追加**不是替换 |
155
+ | T-38 | 验收标准判定用 some(至少一个有效) | `[null,"x"]` 混入的 null 会原样落盘并进入 executor 合同文本 | 收紧为 every(每个元素都必须有效) |
156
+ | T-39 | scope 非字符串元素被静默丢弃 | `scope=[123]` → 静默降档成 read_only 空卡且无提示 | 入口即明确拒绝 |
157
+ | T-40 | 参数校验不查数组元素类型 | `paths:["README.md",123]` 抛不可读的 Node 底层错误 | 补元素级校验,入口即给明确提示 |
158
+
159
+ ### ✨ 新增 | Added
160
+
161
+ - **`flow_trigger_check` MCP 工具** —— 触发引擎不再只接在命令行客户端上,宿主可在消息事件里调用它,
162
+ 获得与 CLI 完全一致的自动触发行为(MCP 协议是被动的,服务端不能主动推送)
163
+ - **OpenCode 插件 `plugins/carlos-flow-trigger.js`** —— 监听 `chat.message` 钩子,实现消息级自动触发;
164
+ 异常只记日志、绝不阻断用户消息
165
+ - **内置中文流程词** —— 工作流 / 门禁 / 任务卡 / 派发 / 子代理 / 流程 / 触发 / 执行 / 调度 / 审计 / 复核 / 留痕 / 裁定;
166
+ 只收流程性词汇,不收「实现 / 新增 / 接口」这类普通开发动词
167
+ - **`trigger-config.usable.json` / `trigger-config.example.json`** —— 可直接用的中文触发配置模板
168
+ - **`test/e2e-acceptance.mjs`(`npm run test:acceptance`)** —— 端到端验收:MCP 触发 / 中文词表 /
169
+ 伪填充拒绝 / 配置合并 / 插件真实开卡
170
+
171
+ ### 🌐 跨平台 | Cross-platform
172
+
173
+ - `runVerifyCommand` 不再硬编码 `cmd.exe`(Linux/macOS 上命令根本没跑,exitCode=127,门禁失守)
174
+ - OpenCode DB 路径多路探测(XDG / macOS 原生 / Windows APPDATA),修复 macOS/Windows 读不到用户原话
175
+ - npm 包补入 `scripts/` 目录 —— 装包后 `npm run test:e2e` 不再因缺文件失败
176
+
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Carlos Flow Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/MIGRATION.md ADDED
@@ -0,0 +1,245 @@
1
+ # 迁移指南 · Migration Guide
2
+
3
+ **从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移到 `carlos-flow`**
4
+
5
+ > **版本**:v2.6.0
6
+ > **适用**:从 ≤ 2.5.9 的双包架构升级到 2.6.0 单包架构
7
+ > **预计耗时**:5 分钟
8
+
9
+ ---
10
+
11
+ ## 📋 TL;DR
12
+
13
+ | | 之前 | 现在 |
14
+ |---|------|------|
15
+ | **安装** | `npm i -g carlos-flow-cindy`<br/>`npm i -g carlos-flow-opencode` | `npm i -g carlos-flow` |
16
+ | **命令** | `carlos-flow` / `carlos-flow-cindy` / `carlos-flow-opencode` | `carlos-flow` / `carlos-flow-cindy`(别名)/ `carlos-flow-opencode`(别名) |
17
+ | **配置** | 手动改 `ghost.json` / `opencode.json` | `carlos-flow init --target <平台>` 一键生成 |
18
+ | **状态目录** | `~/.carlos-flow` | `~/.carlos-flow`(**不变**) |
19
+ | **审计链** | 旧的 `gate-audit/*.jsonl` | 原地保留,**不迁移、不破坏** |
20
+
21
+ **核心变化只有一个**:npm 包从两个变成一个,平台从两个变成六个。
22
+ **你的状态、审计链、快照、触发历史全部原地保留。**
23
+
24
+ ---
25
+
26
+ ## ⚠️ 为什么要迁移
27
+
28
+ ### 1. 双包维护成本是真实的
29
+
30
+ 两个包共享 **100% 的核心逻辑**:
31
+
32
+ ```
33
+ src/index.js src/trigger.js src/state.js
34
+ src/card.js src/dispatch.js src/protocol.js
35
+ ```
36
+
37
+ 却要各自发版、各自打 tag、各自跑 CI、各自写 CHANGELOG。版本漂移不是意外,是必然:
38
+
39
+ > 合并前就出现过 `carlos-flow-cindy@2.5.9` 与 `carlos-flow-opencode@2.5.8` 并存的状态 ——
40
+ > 用户 `npm install carlos-flow-opencode` 装到的是旧版,而 `carlos-flow-cindy` 已经是新版。
41
+
42
+ ### 2. bin 名冲突让两个包无法共存
43
+
44
+ npm 规定同名 bin 不能共存。两个包都声明 `carlos-flow` 时:
45
+
46
+ ```bash
47
+ npm install -g carlos-flow-cindy carlos-flow-opencode
48
+ # npm error EEXIST: file already exists
49
+ ```
50
+
51
+ ### 3. 旧包已弃用
52
+
53
+ ```bash
54
+ npm install carlos-flow-cindy
55
+ # npm WARN deprecated carlos-flow-cindy@2.5.9: Deprecated: use carlos-flow instead
56
+ ```
57
+
58
+ ---
59
+
60
+ ## 🚀 迁移步骤
61
+
62
+ ### Step 1 — 安装新包
63
+
64
+ ```bash
65
+ npm install -g carlos-flow@latest
66
+ ```
67
+
68
+ > 新旧包**可以共存**(`carlos-flow` 三个 bin 名互不冲突),
69
+ > 建议先装新包、验证无误后再卸载旧包。
70
+
71
+ ### Step 2 — 重新初始化配置
72
+
73
+ #### Cindy 用户
74
+
75
+ ```bash
76
+ carlos-flow init --target cindy
77
+ ```
78
+
79
+ 生成 `~/.cindy/ghosts/carlos-flow.json`(含正确路径的 `__ROOT__` 已渲染)。
80
+ **重启 Cindy** 后侧栏出现「Carlos 工作流」。
81
+
82
+ #### OpenCode 用户
83
+
84
+ ```bash
85
+ carlos-flow init --target opencode
86
+ ```
87
+
88
+ 生成两处:
89
+ - `~/.config/opencode/plugin/opencode.json`(全局 MCP 注册)
90
+ - 当前目录 `.mcprc`(项目级 MCP 配置)
91
+
92
+ **重启 OpenCode**。
93
+
94
+ #### Cursor / Cline / VS Code / Claude Desktop 用户
95
+
96
+ ```bash
97
+ carlos-flow init --target cursor # → .cursor/mcp.json
98
+ carlos-flow init --target cline # → .cline/mcp.json
99
+ carlos-flow init --target vscode # → .vscode/mcp.json
100
+ carlos-flow init --target claude # → Claude Desktop 全局配置
101
+ ```
102
+
103
+ ### Step 3 — 验证
104
+
105
+ ```bash
106
+ node client/carlos.js flow_status '{"sessionId":"probe"}'
107
+ ```
108
+
109
+ 期望 `"has_card": false`。
110
+
111
+ > ⚠️ 注意路径:`node client/carlos.js` 需要在**仓库根目录**执行(源码安装场景)。
112
+ > 全局安装后可直接用 `carlos-flow flow_status '{"sessionId":"probe"}'`。
113
+
114
+ ### Step 4 — 卸载旧包(确认无误后)
115
+
116
+ ```bash
117
+ npm uninstall -g carlos-flow-cindy carlos-flow-opencode
118
+ ```
119
+
120
+ ---
121
+
122
+ ## 🔄 命令对照表
123
+
124
+ | 旧命令 | 新命令 | 备注 |
125
+ |--------|--------|------|
126
+ | `carlos-flow`(cindy 包) | `carlos-flow` | 主命令,语义不变 |
127
+ | `carlos-flow-cindy` | `carlos-flow-cindy` | 保留为别名,向后兼容 |
128
+ | `carlos-flow-opencode` | `carlos-flow-opencode` | 保留为别名,向后兼容 |
129
+ | `node client/carlos.js <tool>` | `carlos-flow <tool>` | **新增**:全局安装后可直接用主命令 |
130
+ | — | `carlos-flow init --target <平台>` | **新增**:一键配置 |
131
+
132
+ 所有工具调用参数**完全不变**:
133
+
134
+ ```bash
135
+ # 旧
136
+ node client/carlos.js flow_status '{"sessionId":"x"}'
137
+ # 新(全局安装)
138
+ carlos-flow flow_status '{"sessionId":"x"}'
139
+ ```
140
+
141
+ ---
142
+
143
+ ## 📁 配置文件位置对照
144
+
145
+ | 平台 | 旧(手动配置) | 新(init 生成) |
146
+ |------|---------------|-----------------|
147
+ | **Cindy** | 手动编辑 `~/.cindy/ghosts/carlos-flow.json` | `carlos-flow init --target cindy` 自动生成 |
148
+ | **OpenCode** | 手动编辑 `~/.config/opencode/plugin/opencode.json` + `.mcprc` | `carlos-flow init --target opencode` 自动生成 |
149
+ | **Cursor** | 手动创建 `.cursor/mcp.json` | `carlos-flow init --target cursor` 自动生成 |
150
+ | **Cline** | 手动创建 `.cline/mcp.json` | `carlos-flow init --target cline` 自动生成 |
151
+ | **VS Code** | 手动创建 `.vscode/mcp.json` | `carlos-flow init --target vscode` 自动生成 |
152
+ | **Claude Desktop** | 手动编辑 `claude_desktop_config.json` | `carlos-flow init --target claude` 自动合并 |
153
+
154
+ ---
155
+
156
+ ## 💾 数据与状态:全部原地保留
157
+
158
+ | 数据 | 位置 | 迁移影响 |
159
+ |------|------|---------|
160
+ | 任务卡状态 | `$CARLOS_FLOW_HOME/gate-state/runs/<sid>/state.json` | ✅ 无影响 |
161
+ | 审计链 | `$CARLOS_FLOW_HOME/gate-audit/*.jsonl` | ✅ 无影响(哈希链不中断) |
162
+ | 文件快照 | `$CARLOS_FLOW_HOME/…/snapshots/` | ✅ 无影响 |
163
+ | 触发历史 | `$CARLOS_FLOW_HOME/trigger-state/` | ✅ 无影响 |
164
+ | 触发器配置 | `$CARLOS_FLOW_HOME/trigger-config.json` | ✅ 无影响(合并语义不变) |
165
+
166
+ > **默认 `CARLOS_FLOW_HOME` 是 `~/.carlos-flow`** —— 与旧版一致,无需任何配置变更。
167
+
168
+ ### ⚠️ 一个可选的变量命名变化
169
+
170
+ 如果你之前用的是 `CARLOS_FLOW_ROOT`(trigger.js 的兼容读取),仍然有效;
171
+ 新文档统一用 `CARLOS_FLOW_HOME`。两者语义相同。
172
+
173
+ ---
174
+
175
+ ## 🔍 行为差异(需要注意的 3 点)
176
+
177
+ ### 1. `init` 会写入触发器配置
178
+
179
+ 首次 `init` 时,如果 `$CARLOS_FLOW_HOME/trigger-config.json` 不存在,会自动写入默认配置。
180
+ **已存在的文件不会被覆盖。**
181
+
182
+ ### 2. Claude Desktop 的配置是「合并」而非「覆盖」
183
+
184
+ `init --target claude` 会读取现有的 `claude_desktop_config.json`,
185
+ 只替换 `mcpServers["carlos-flow"]` 这一项,**保留你其他 MCP server 的配置**。
186
+
187
+ ### 3. Cindy 用户的 Bridge 路径由 `__ROOT__` 决定
188
+
189
+ 旧版 `ghost.json` 里的路径是相对路径,装到全局目录后会失效。
190
+ 新版由 `init` 渲染成绝对路径。若你手动编辑过 `ghost.json`,请重新跑一次 `init --target cindy`。
191
+
192
+ ---
193
+
194
+ ## ❓ FAQ
195
+
196
+ <details>
197
+ <summary><b>Q: 升级会不会丢审计链?</b></summary>
198
+
199
+ 不会。审计链是文件追加式的(`gate-audit/YYYY-MM-DD.jsonl`),`prevHash` 从磁盘尾部读取,
200
+ 与进程数、版本无关。升级后继续追加,链不会断。
201
+ </details>
202
+
203
+ <details>
204
+ <summary><b>Q: 可以两个包同时装吗?</b></summary>
205
+
206
+ 可以。`carlos-flow` 的三个 bin 名(`carlos-flow` / `carlos-flow-cindy` / `carlos-flow-opencode`)
207
+ 与旧包**不冲突**(旧包用的是 `carlos-flow-cindy` / `carlos-flow-opencode`,
208
+ 新包保留了同名别名 —— 此时后装的会覆盖前一个的同名 bin,但**代码是同一份**,无实际差异)。
209
+ 建议直接卸载旧包,避免混淆。
210
+ </details>
211
+
212
+ <details>
213
+ <summary><b>Q: 触发阈值会变吗?</b></summary>
214
+
215
+ 不会。`src/trigger.js` 的默认配置(阈值、词表、动态上限公式)在 2.6.0 中**逐字未变**。
216
+ 只有配置**合并语义**在 2.5.6 就已修正为「追加不是替换」,本版本延续。
217
+ </details>
218
+
219
+ <details>
220
+ <summary><b>Q: 旧版本还能用吗?</b></summary>
221
+
222
+ 能,但会显示弃用警告。npm 不会自动卸载旧版本。
223
+ </details>
224
+
225
+ <details>
226
+ <summary><b>Q: 如何完全卸载?</b></summary>
227
+
228
+ ```bash
229
+ npm uninstall -g carlos-flow carlos-flow-cindy carlos-flow-opencode
230
+ # 如需清理状态(会丢失审计链,谨慎)
231
+ rm -rf ~/.carlos-flow
232
+ ```
233
+ </details>
234
+
235
+ ---
236
+
237
+ ## 🔗 相关链接
238
+
239
+ | | |
240
+ |---|---|
241
+ | **仓库** | https://github.com/skyer-now/carlos-flow |
242
+ | **npm** | https://www.npmjs.com/package/carlos-flow |
243
+ | **更新日志** | [CHANGELOG.md](./CHANGELOG.md) |
244
+ | **触发引擎指南** | [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) |
245
+ | **问题反馈** | https://github.com/skyer-now/carlos-flow/issues |