内容
# 开源代码桥
一个模型上下文协议（MCP）服务器，允许任何AI工具（Claude Code、Antigravity、VS Code、Cursor、Windsurf、JetBrains、Claude Desktop等）将任务委派给[开源代码命令行界面](https://github.com/sst/opencode)作为子代理 — 完全通过开源代码自己的`opencode serve` HTTP/SSE API驱动，具有异步推送事件、任务合约、上下文跟踪、检查点和多会话编排。
> 代理指令位于[`AGENTS.md`](./AGENTS.md) — 或者只需调用`opencode_guide`工具，一旦此服务器注册；它从正在运行的服务器的实际状态返回相同的指南。
## 架构
桥接器通过普通的HTTP与单个、长期运行的`opencode serve`进程通信：
- **一个共享进程，无限会话。** `server-manager.ts`启动并单例管理`opencode serve`（状态跟踪在`~/.opencode-bridge/server.json`）；每次`opencode_start`调用只会在该服务器上创建一个轻量级会话，而不是为每个任务启动一个新的CLI进程。无需`node-pty`原生绑定，无需每个任务重新身份验证。
- **一个事件流，所有会话。** 与`/api/event`的单个SSE连接承载所有会话的事件，按`durable.aggregateID`标记；`http-bridge.ts`将它们分发到正确的本地会话（`session.next.step.started/ended/failed`，`session.next.tool.called`，`session.next.text.delta`，…）并从中推导出状态（`running` / `idle` / `waiting_input` / `error`）— 无需ANSI解析，无需空闲定时器启发式。
- **自我愈合。** 开源代码的HTTP API不会将会话运行器故障（例如模型解析错误）作为API可见错误或事件公开 — 失败的会话将永远停留在`running`状态，与正常运行的会话无法区分。桥接器跟踪开源代码自己的内部日志（`~/.local/share/opencode/log/opencode.log`）以立即检测这些故障，并运行一个停滞监视器（在提示后N秒内未生成令牌）作为第二道防线。因为观察到单个这样的故障会阻塞该服务器进程的整个回合队列，所以检测到一个故障会触发`opencode serve`的自动重启，以便后续会话不会受到影响。
## 功能
- ⚡ **异步事件**：将状态转换（`running`、`idle`、`waiting_input`、`error`、`stale`、`contract_violated`）写入`~/.opencode-mcp-events.jsonl`。
- 🔀 **多会话编排**：运行最多3个并发开源代码会话，具有依赖关系排序（`opencode_batch`）。
- 🗂️ **上下文存储**：跟踪会话事件流报告的每个文件创建/修改。
- 🛡️ **任务合约**：强制执行持续时间限制、路径范围限制、文件数量上限和禁止命令。
- 📸 **检查点和恢复**：每60秒自动保存状态快照，并从任何检查点重试失败的会话。
- 🎯 **预飞行分类器**：对传入任务进行评分，以决定是否委派并推荐最佳模型。
- 🩺 **故障可见性**：`opencode_health`公开`last_error` — 来自开源代码运行器的实际底层异常，而不仅仅是通用挂起。
- 🖥️ **服务器自省**：`opencode_server_health` / `opencode_server_restart`公开并控制底层`opencode serve`进程本身，与任何单个会话分开。
- 📖 **自我文档**：`opencode_guide`返回一个完整的、实时的行为指南（模型选择、工作流、陷阱） — 在任何MCP主机中都能正常工作。
## 先决条件
- [Node.js](https://nodejs.org) v18+
- [开源代码命令行界面](https://github.com/sst/opencode)已安装并经过身份验证（`opencode auth login`）— 运行`opencode --version`确认它在PATH上。
## 快速入门
1. **克隆和构建：**
```bash
git clone https://github.com/Dheerax/opencode_mcp.git
cd opencode_mcp
npm install
npm run build
```
2. **注册为MCP服务器：**
- **Claude Code：**
```bash
claude mcp add -s user opencode-mcp-bridge -- node /absolute/path/to/opencode_mcp/dist/index.js
```
- **Antigravity / VS Code / Cursor / Windsurf：**
添加到您的MCP服务器配置：
```json
{
"mcpServers": {
"opencode-mcp-bridge": {
"command": "node",
"args": ["/absolute/path/to/opencode_mcp/dist/index.js"]
}
}
}
```
3. **运行设置：**
从您的主机代理调用`opencode_setup`工具一次以生成工作区集成说明，然后调用`opencode_guide`以获取完整的使用指南。
## 所有工具
参见 [`AGENTS.md`](./AGENTS.md) 以获取完整的工具参考表和工作流指南 — 或者直接调用`opencode_guide` MCP工具，它返回相同的内容。
## 故障排除
如果会话状态立即保持`error`，并且`opencode_health`的`last_error`提到了您期望工作的提供商（例如`google/*`模型）的`ModelUnavailableError`，则该提供商的缓存OAuth令牌可能已过期。直接重新身份验证：
```bash
opencode auth logout <provider>
opencode auth login <provider>
```
这是开源代码/提供商身份验证问题，而不是桥接器本身可以修复的问题 — 它只能检测到它，通过`last_error`报告，并恢复服务器进程，以便它不会为其他会话保持阻塞状态。
## 许可证
[MIT](./LICENSE)
