# opencode-bridge

**Repository Path**: Cooper0/opencode-bridge

## Basic Information

- **Project Name**: opencode-bridge
- **Description**: opencode 桥接到飞书机器人
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-04
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# opencode-bridge

纯 Rust 实现的 OpenCode ↔ 飞书双向桥接服务。单二进制，无 Python 依赖。

一个进程同时管理多个 OpenCode 会话，支持飞书消息注入、回复推送、会话切换、任务进度查看。

## 架构

```
飞书（私聊 / 群聊 @机器人）
    ↕ WebSocket (pbbp2 protobuf)
[opencode-bridge]                    ← 本项目
    ├── 飞书 WS 客户端  ← 接收消息，推送回复
    ├── HTTP :5180     ← REST API（可选，调试用）
    └── DB 监控线程     ← 轮询 OpenCode SQLite，2 秒一次
    ↕
[OpenCode (--port)]                  ← REST API 同步返回
    ↕
[共享 SQLite DB]                     ← ~/.local/share/opencode/opencode.db
```

## 飞书机器人配置

### 1. 创建飞书应用

1. 打开 [飞书开放平台](https://open.feishu.cn/app)（国际版用 [Lark](https://open.larksuite.com/app)）
2. 点击「创建企业自建应用」
3. 填写应用名称（如「OpenCode 助手」）和描述

### 2. 获取凭证

在应用的「凭证与基础信息」页面获取：

- **App ID**：`cli_xxxxxxxxxxxx`
- **App Secret**：`xxxxxxxxxxxxxxxxxxxxxxxxxx`

### 3. 配置权限

在「权限管理」中开通以下权限：

| 权限 | 权限标识 | 说明 |
|------|---------|------|
| 获取与发送单聊、群组消息 | `im:message` | 收发消息 |
| 以应用身份发消息 | `im:message:send_as_bot` | 机器人发消息 |
| 读取用户发给机器人的单聊消息 | `im:message.p2p_msg:readonly` | 私聊消息内容 |
| 读取群聊中用户@机器人的消息 | `im:message.group_at_msg:readonly` | 群聊@消息内容 |
| 获取群组信息 | `im:chat:readonly` | 群聊信息 |
| 获取与更新群组信息 | `im:chat` | 群组操作（可选） |

### 4. 启用长连接（WebSocket）

1. 进入「事件与回调」→「事件配置」
2. 选择「长连接模式」（非 HTTP 回调模式）
3. 添加事件订阅：**接收消息 v2.0**（`im.message.receive_v1`）

长连接模式无需公网 IP 和回调地址，bridge 直接连飞书 WebSocket。

### 5. 发布应用

1. 在「版本管理与发布」中创建版本
2. 设置可用范围（自己 / 部门 / 全员）
3. 提交审核（企业自建应用通常秒过）

### 6. 测试

- 在飞书中搜索机器人名称，发起私聊
- 创建群聊，将机器人加入群中
- 发送消息，私聊直接回复；群聊需要 @机器人

## 安装

### 一键安装（分发包）

下载分发包 `opencode-bridge_<version>_linux_x86_64.tar.gz` 后：

```bash
tar -xzf opencode-bridge_*.tar.gz
cd opencode-bridge_*/
./install.sh
```

`install.sh` 会自动完成：拷贝二进制到 `~/.local/bin/`、交互式生成飞书凭证文件、注册并启动 systemd user 服务、启用开机自启。

### 编译

```bash
cd opencode-bridge
cargo build --release
cp target/release/opencode-bridge ~/.local/bin/
```

### 配置飞书凭证

凭证放在独立 env 文件中，service 文件通过 `EnvironmentFile` 引用，密钥不暴露在 service 配置中：

```bash
# 创建凭证文件（仅本人可读）
cat > ~/.config/opencode-bridge.env << 'EOF'
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_DOMAIN=feishu
# 国际版 Lark 用：FEISHU_DOMAIN=lark
# 可选：推送监控输出的目标会话
# FEISHU_HOME_CHANNEL=oc_xxx
EOF
chmod 600 ~/.config/opencode-bridge.env
```

也可以通过 CLI 参数传入（不推荐，凭证会出现在进程列表中）：

```bash
opencode-bridge --auto \
  --feishu-app-id cli_xxx \
  --feishu-app-secret xxx \
  --feishu-domain feishu
```

## 注册为系统服务

```bash
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/opencode-bridge.service << 'EOF'
[Unit]
Description=OpenCode Chat Bridge (Multi-Session)
After=network.target

[Service]
Type=simple
EnvironmentFile=%h/.config/opencode-bridge.env
ExecStart=%h/.local/bin/opencode-bridge --auto --listen 5180 --interval 2
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now opencode-bridge.service

# 开机自启（即使未登录也运行）
loginctl enable-linger $USER
```

## 前置条件

- OpenCode 已安装且以 `--port` 启动

```bash
# 启动 OpenCode（加 --port 即可，自动分配端口）
opencode --port

# nvim 插件通常自带 --port，无需手动加
```

## 飞书命令

| 命令 | 说明 |
|------|------|
| `/help` | 命令列表 |
| `/ls` | 运行中的会话（🟢 有端口 = 运行中） |
| `/ls all` | 全部会话（含历史 ⚪） |
| `/s1` `/s2` | 按编号切换会话（编号对应 /ls 显示） |
| `/now` | 当前会话信息（名称、目录、端口） |
| `/log` | 当前会话任务状态（⏳执行中/✅已完成 + 指令 + 进度） |
| `/r` | 刷新端口 + 发现新会话，自动显示列表 |
| `/status` | bridge 整体状态 |
| 其他文字 | 转发到当前 OpenCode 会话 |

群聊中需要 @机器人 才会响应，私聊直接回复。

## HTTP API（可选，调试用）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/sessions` | 列出所有会话 |
| POST | `/send` | 发送消息（`{"text":"...","session":"名称"}`） |
| POST | `/switch` | 切换会话 |
| POST | `/refresh` | 刷新端口 + 发现新会话 |
| POST | `/add` | 添加会话（`{"session":"ses_xxx"}`） |

## 管理命令

```bash
systemctl --user status opencode-bridge      # 状态
systemctl --user restart opencode-bridge     # 重启
systemctl --user stop opencode-bridge        # 停止
journalctl --user -u opencode-bridge -f      # 实时日志
```

## 开发

```bash
# 一键部署（编译 + 停服务 + 拷贝 + 重启 + 看日志）
./deploy.sh

# 打包分发包（编译 release + 打包 tar.gz，含 install.sh）
./build.sh --dist

# 仅打包已有产物（不重新编译）
./build.sh --no-build --dist

# 手动
cargo build --release
systemctl --user stop opencode-bridge.service
cp target/release/opencode-bridge ~/.local/bin/
systemctl --user start opencode-bridge.service
```

详细的架构决策和注意事项见 [AGENTS.md](AGENTS.md)。

## 资源占用

| 指标 | 值 |
|------|-----|
| 内存 RSS | ~5 MB |
| CPU（空闲） | ~0% |
| 二进制大小 | ~5 MB |
| 线程数 | 7-9 |

## 依赖

| crate | 用途 |
|-------|------|
| `rusqlite` (bundled) | SQLite 数据库访问（自带 C 源码编译） |
| `tiny_http` | HTTP 服务器 |
| `ureq` | HTTP 客户端（调 OpenCode REST API） |
| `tungstenite` | 飞书 WebSocket 长连接 |
| `prost` | 飞书 pbbp2 protobuf 帧解码 |
| `clap` | 命令行参数解析 |
| `serde` / `serde_json` | JSON 序列化 |
| `url` | URL 解析 |

## 已知限制

- OpenCode 新建 session 后需发 `/r` 让 bridge 发现新会话
- REST API 注入需要 OpenCode 以 `--port` 启动；无端口时回退到 CLI 模式
- 飞书 WebSocket token 可能过期（日志出现 404 重连），重启服务即可恢复
- 监控靠 DB 轮询（2 秒延迟），非实时推送