Carlos 工作流 - OpenCode 适配版
机械门禁 MCP：留痕 → 派发 → 裁定 → 审计 → 快照还原 纯 stdio 传输，无 Bridge，配置走
.mcprc或opencode.json
✨ 特性
- 零依赖运行时：无 Bridge，直接
node src/index.js，OpenCode 原生 MCP 协议 - 标准配置：兼容
.mcprc(YAML) 和opencode.json两种配置源 - 全平台支持：Windows / macOS / Linux 均可运行（需 Node.js 22+）
- 完整门禁流程：12 个工具覆盖 T0/T1/T2 三档路由、四段合同、独立复核、审计链
- 可选 rea 集成：同一 MCP 注册可同时启用 rea 逆向分析工具
📦 安装
1. 克隆仓库
git clone https://github.com/skyer-now/carlos-flow-opencode.git
cd carlos-flow-opencode
npm install
2. 配置 MCP
方式 A：使用 .mcprc（推荐，YAML 格式）
cp .mcprc.template ~/.config/opencode/.mcprc
# 编辑 ~/.config/opencode/.mcprc 填入实际路径
方式 B：使用 opencode.json
cp opencode.json.template ~/.config/opencode/opencode.json
# 编辑 ~/.config/opencode/opencode.json 填入实际路径
两种配置源二选一生效，以
opencode.json优先。
3. 配置环境变量（可选，也可直接写在配置文件的 env 里）
cp .env.example .env
# 编辑 .env 或在 ~/.bashrc / ~/.zshrc 中 export
4. 重启 OpenCode 验证
# 完全关闭 OpenCode（任务管理器结束残留进程），重新打开
mcp list
# 应显示：
# carlos-flow online
⚙️ 环境变量与路径占位符
| 占位符 | 说明 | 示例 |
|---|---|---|
<CARLOS_FLOW_MCP_ROOT> | 本仓库根目录绝对路径（含 src/） | /home/user/carlos-flow-opencode |
<CARLOS_FLOW_HOME> | 状态/审计/快照根目录 | ~/carlos-flow |
<REA_MCP_ROOT> | rea MCP 源码根目录 | /home/user/rea |
<GHIDRA_HOME> | Ghidra 安装目录 | /opt/ghidra_12.1.4_PUBLIC |
<JAVA_HOME> | JDK 21 安装目录 | /usr/lib/jvm/java-21-openjdk |
Windows 路径：用正斜杠
/或双反斜杠\\，如D:/carlos-flow-opencode
🛠️ 可用工具（12 个）
| 工具 | 作用 |
|---|---|
flow_protocol | 读取完整协议文档 |
flow_add_user_msg | 写入用户原话（锚点数据源） |
flow_submit_requirement | 提交任务卡（留痕 + 校验） |
flow_claim | 领取派发名额（executor/auditor） |
flow_dispatch | 生成派发 prompt + 文件快照 |
flow_verdict | 记录裁定（PASS/DIRECTION/LOCAL） |
flow_status | 查询门禁状态 |
flow_audit | 读取审计流水 |
flow_diff_hunks | git diff hunk 分析 |
flow_bypass | 免检开关 |
flow_save_result | 保存子 Agent 结果 |
flow_revert_plan | 生成还原计划 |
🔄 工作流示例
# 1. 写入用户原话
node client/carlos.js flow_add_user_msg '{"sessionId":"my-task","text":"给登录接口加参数校验"}'
# 2. 提交任务卡（留痕）
node client/carlos.js flow_submit_requirement '{"sessionId":"my-task","goal":"给登录接口加参数校验","quote":"给登录接口加参数校验","scope":["src/auth.py"],"acceptance":["缺少参数返回400"],"confirmed":true}'
# 3. 派发 executor
node client/carlos.js flow_claim '{"sessionId":"my-task","role":"executor"}'
node client/carlos.js flow_dispatch '{"sessionId":"my-task","role":"executor","message":"只改src/auth.py"}'
# 4. 子 Agent 执行完后保存结果
node client/carlos.js flow_save_result '{"sessionId":"my-task","role":"executor","stdout":"结论：已加校验","stderr":"","code":0}'
# 5. 派发 auditor 独立复核
node client/carlos.js flow_claim '{"sessionId":"my-task","role":"auditor"}'
node client/carlos.js flow_dispatch '{"sessionId":"my-task","role":"auditor"}'
# 6. 记录裁定
node client/carlos.js flow_verdict '{"sessionId":"my-task","verdict":"PASS","notes":"端测通过"}'
# 7. 查看最终状态
node client/carlos.js flow_status '{"sessionId":"my-task"}'
📁 目录结构
carlos-flow-opencode/
├── src/ # MCP Server 核心（stdio 传输，与 Cindy 版完全一致）
│ ├── index.js # 入口：注册 12 个工具
│ ├── protocol.js # 协议定义
│ ├── card.js # 任务卡解析/修复/校验
│ ├── state.js # 状态持久化/审计链/用户消息源
│ └── dispatch.js # 四段合同/文件快照/结果保存
├── client/ # CLI 客户端（纯 stdio，无 Bridge）
│ └── carlos.js # 直连 MCP Server
├── test/ # 测试套件（共享 Cindy 版 test/ 目录）
├── .mcprc.template # OpenCode MCP 配置模板 (YAML)
├── opencode.json.template # OpenCode 配置模板 (JSON)
├── .env.example # 环境变量模板
├── package.json
└── README.md
🧪 测试
# 冒烟测试（共享 Cindy 版测试，隔离临时目录）
npm test
# 端到端测试（需配置好 CARLOS_FLOW_MCP_ROOT、CARLOS_FLOW_HOME）
npm run test:e2e
# rea 真实 Ghidra 分析测试（需配置 GHIDRA_HOME/JAVA_HOME，另装 rea）
npm run test:rea
🔒 与 Cindy 版的区别
| 特性 | Cindy 版 (carlos-flow-cindy) | OpenCode 版 (carlos-flow-opencode) |
|---|---|---|
| 传输协议 | TCP Bridge (127.0.0.1:19099) | 纯 stdio |
| 后台管理 | 自动（首次调用拉起 Bridge） | 无（OpenCode 管理进程生命周期） |
| 配置方式 | 插件设置页 + 环境变量 | .mcprc / opencode.json + 环境变量 |
| 密钥存储 | Cindy 加密保险库 | 明文配置文件（用户自行管理） |
| rea 集成 | 内置 client/rea.js | 另注册一个 MCP server |
| 适用场景 | Cindy App 用户 | OpenCode 2.2.2+ 用户 |
📄 许可证
MIT License - 详见 LICENSE
🤝 贡献
欢迎 PR！请先跑通 npm test 和 npm run test:e2e。
想要自动 Bridge 管理？ 请看 carlos-flow-cindy —— Cindy 原生插件，首次调用自动拉起 Bridge，密钥进保险库。