# opencode-bridge

把 `opencode serve` 暴露为 **OpenAI 兼容 API** 的中间层，供 ARTEX 等需要
function calling 的上层应用使用。工具调用通过「文本协议模拟」实现：
工具 schema 注入 system prompt → 模型输出 `<tool_call>` 文本块 → 桥解析并翻译成
标准 OpenAI `tool_calls` → 上层执行工具后回传 `role:"tool"` 结果 → 桥渲染成
`<tool_result>` 块继续下一轮。

## 架构

```
ARTEX ──OpenAI /v1/chat/completions──> 本桥(Node) ──opencode SDK──> opencode serve
        (messages/tools/stream)                                        └─ 上游模型
```

## 快速开始

```bash
cd /var/www/html/opencode-bridge
npm install
npm start            # 默认 http://127.0.0.1:8086
```

依赖一个运行中的 opencode serve（本机 4096）：

```bash
opencode serve --hostname 127.0.0.1 --port 4096
```

### systemd 部署

```bash
sudo cp bridge.service /etc/systemd/system/opencode-bridge.service
sudo systemctl daemon-reload
sudo systemctl enable --now opencode-bridge
```

## 配置（config.json）

| 键 | 说明 |
|---|---|
| `PORT` / `BIND_HOST` | 监听地址 |
| `API_KEY` | 静态鉴权（Bearer），空则不鉴权 |
| `OPENCODE_SERVER_URL` | opencode serve 地址 |
| `DEFAULT_MODEL` | 缺省模型 |
| `ENABLED_OPENCODE_TOOLS` | 开放给 opencode 会话的原生工具。**必须保留 `read`**（免费层对全关闭会话返回 403）。默认只开 `read`，其余（bash 等）全部关闭 |
| `AUTO_PERMISSION` | 会话内原生工具权限请求的自动应答，默认 `reject` |
| `REQUEST_TIMEOUT_MS` / `IDLE_TIMEOUT_MS` | 超时控制 |
| `MAX_OUTPUT_CHARS_PER_TOKEN` | `max_tokens` 近似约束（每 token 对应字符数） |
| `ESTIMATE_TOKENS` | opencode 不返回 usage 时按字符数估算 token |
| `MAX_TOOL_RETRIES` | 工具块格式错误时纠错重试次数 |

## ARTEX 接入

与官方 API 完全同构，只需改 LLM profile：

- provider: `openai`
- base_url: `http://127.0.0.1:8086/v1`
- api_key: 桥的 `API_KEY`
- model: `opencode/deepseek-v4.1-flash-free`
- streaming: `true` / `false` 均支持（均已实测通过 ARTEX 连接测试）

## 支持能力与已知限制

| 能力 | 状态 |
|---|---|
| 普通对话（非流式 + SSE 流式） | ✅ |
| 工具调用（多工具并行、tool_choice auto/none/required/指定） | ✅ 文本协议模拟 |
| 工具结果回传多轮循环 | ✅（已实测 ARTEX list_tasks 全链路） |
| 并发 | ✅ opencode serve 原生并行会话，桥无锁 |
| 原生 function calling | ❌ 上游不支持，靠文本协议模拟（偶发格式错误由重试消化） |
| token 精确计量 | ❌ opencode 不返回 usage，桥按字符估算 |
| max_tokens 精确约束 | ❌ 仅 prompt 指令 + 客户端截断近似 |
| 模型偶尔倾向 opencode 原生工具 | ⚠️ 已在协议提示中明确禁止；`AUTO_PERMISSION=reject` 兜底 |

## 测试

```bash
node test.mjs        # T1-T8：对话/流式/工具调用/结果回传/并发/多工具并行
```

## 关键实现细节（对接 serve 时踩过的坑）

- 新版权限事件类型为 `message.part.delta`（旧代理监听的 `message.part.updated`
  +delta 已废弃，导致其流式永远空帧）
- 会话把**全部原生工具**关闭会被上游拒绝：
  `OpenCode's free tier can only be used from within OpenCode`（403）。
  实测最少保留 `read` 即可通过
- 模型原生调用未注册工具会报 `unavailable tool`，需在协议提示中预先声明
  「环境信息不可信」
- 模型会把整段回复放进 reasoning 通道，解析时需合并 text+reasoning 两个通道
- 必须监听 `session.error` / `permission.updated` 事件，否则会话可能无限挂起
- SSE 必须先发 headers 再流式写，客户端断连后写要 try/catch（否则进程崩溃）
