# carlos-flow-opencode 中文文档

规范地址：https://npmcn.com/package/carlos-flow-opencode/

版本：2\.5\.1
npm 元数据更新时间：2026-11-03T06:50:43.992Z
中文译文更新时间：2026-11-03T07:04:49.808Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/carlos-flow-opencode
原文对照：https://npmcn.com/package/carlos-flow-opencode/?lang=original
项目主页：https://github.com/skyer-now/carlos-flow-opencode#readme
源码仓库：https://github.com/skyer-now/carlos-flow-opencode

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：80.5 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：1 个
- 首次发布：2026-11-03T06:49:27.953Z
- 最新版本发布：2026-11-03T06:50:43.825Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

MCP - OpenCode - OpenCode .json（英文）

## 安装

```sh
npm install carlos-flow-opencode
```

也可以使用：`pnpm add carlos-flow-opencode`、`yarn add carlos-flow-opencode`、`bun add carlos-flow-opencode`

## README

# 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\. 克隆仓库

```bash
git clone https://github.com/skyer-now/carlos-flow-opencode.git
cd carlos-flow-opencode
npm install
```

### 2\. 配置 MCP

**方式 A：使用 `.mcprc`（推荐，YAML 格式）**

```bash
cp .mcprc.template ~/.config/opencode/.mcprc
# 编辑 ~/.config/opencode/.mcprc 填入实际路径
```

**方式 B：使用 `opencode.json`**

```bash
cp opencode.json.template ~/.config/opencode/opencode.json
# 编辑 ~/.config/opencode/opencode.json 填入实际路径
```

> 两种配置源二选一生效，以 `opencode.json` 优先。

### 3\. 配置环境变量（可选，也可直接写在配置文件的 env 里）

```bash
cp .env.example .env
# 编辑 .env 或在 ~/.bashrc / ~/.zshrc 中 export
```

### 4\. 重启 OpenCode 验证

```bash
# 完全关闭 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` | 生成还原计划 |

## 🔄 工作流示例

```bash
# 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
```

## 🧪 测试

```bash
# 冒烟测试（共享 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](https://npmcn.com/package/carlos-flow-opencode/LICENSE)

## 🤝 贡献

欢迎 PR！请先跑通 `npm test` 和 `npm run test:e2e`。

* * *

**想要自动 Bridge 管理？** 请看 [carlos-flow-cindy](https://github.com/skyer-now/carlos-flow-cindy) —— Cindy 原生插件，首次调用自动拉起 Bridge，密钥进保险库。

## 常见问题

### carlos-flow-opencode 是什么？

MCP - OpenCode - OpenCode \.json（英文）

### 如何安装 carlos-flow-opencode？

在项目目录运行 npm install carlos-flow-opencode，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 carlos-flow，可以用 npx carlos-flow 直接运行。

### carlos-flow-opencode 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/carlos-flow-opencode 是否存在。

### carlos-flow-opencode 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### carlos-flow-opencode 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### carlos-flow-opencode 可以商用吗？

carlos-flow-opencode 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### carlos-flow-opencode 还在维护吗？

最新版本 2\.5\.1 发布于 2026/11/03（今天）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。