Package Exports

opencode-bridge
opencode-bridge/package.json

Readme

OpenCode Bridge

OpenCode Bridge 是一款企业级 AI 编程协作桥接服务，将 OpenCode（AI 编程助手）无缝接入主流即时通讯平台，实现跨平台、跨设备的智能编程协作体验。

📱 支持平台

平台	状态	核心特性
飞书 (Lark)	✅ 完整支持	卡片交互、流式输出、权限确认、文件传输、撤回同步
Discord	✅ 完整支持	组件交互、Embed 消息、Slash 命令、频道管理
企业微信 (WeCom)	✅ 完整支持	文本交互、消息收发
Telegram	✅ 完整支持	文本交互、Inline 键盘
QQ (OneBot)	✅ 完整支持	文本交互、群聊支持
WhatsApp	✅ 完整支持	文本交互、媒体消息
个人微信	✅ 完整支持	扫码登录、文本交互

✨ 核心特性

🔄 智能会话管理

独立会话绑定：每个群聊/私聊独立绑定 OpenCode 会话，上下文互不干扰
会话迁移：支持会话绑定、迁移、重命名，跨设备接力不断裂
多项目支持：支持多项目目录切换，项目别名配置
自动清理：自动清理无效会话，防止资源泄漏

🤖 AI 交互能力

流式输出：实时显示 AI 响应，支持思维链展示
权限交互：AI 权限请求在聊天平台内完成确认
问题回答：AI 提问在聊天平台内完成作答
文件传输：AI 可将文件/截图发送到聊天平台
Shell 透传：白名单命令可直接在聊天中执行

🛡️ 可靠性保障

心跳监控：定时探测 OpenCode 健康状态
自动救援：OpenCode 宕机时自动重启恢复
Cron 任务：支持运行时动态管理定时任务
日志审计：完整的操作日志和错误追踪

🎛️ Web 管理面板

可视化配置：浏览器实时修改所有配置参数
平台管理：查看各平台连接状态
Cron 管理：创建、启用/禁用、删除定时任务
服务控制：查看服务状态、远程重启

🚀 快速开始

1. 克隆项目

git clone https://github.com/HNGM-HP/opencode-bridge.git
cd opencode-bridge

2. 一键部署

Linux/macOS:

chmod +x ./scripts/deploy.sh
./scripts/deploy.sh guide

Windows PowerShell:

.\scripts\deploy.ps1 guide

该命令会自动完成：

检测并引导安装 Node.js
检测并引导安装 OpenCode
安装项目依赖并编译
生成初始配置文件

3. 启动服务

Linux/macOS:

./scripts/start.sh

Windows PowerShell:

.\scripts\start.ps1

开发模式:

npm run dev

4. 配置平台

服务启动后，访问 Web 配置面板完成平台配置：

http://localhost:4098

首次访问时会提示设置管理密码。

📝 命令速查

飞书命令

命令	说明
`/help`	查看帮助
`/panel`	打开控制面板（模型、角色、强度）
`/model <provider:model>`	切换模型
`/agent <name>`	切换 Agent
`/effort <档位>`	设置推理强度
`/session new`	开启新话题
`/session <sessionId>`	绑定已有会话
`/undo`	撤回上一轮交互
`/compact`	压缩上下文
`/project list`	列出可用项目
`/send <路径>`	发送文件到群聊
`/cron ...`	管理 Cron 任务
`!<shell 命令>`	透传 Shell 命令

Discord 命令

命令	说明
`///session`	查看绑定的会话
`///new`	新建并绑定会话
`///bind <sessionId>`	绑定已有会话
`///undo`	撤回上一轮
`///compact`	压缩上下文
`///workdir`	设置工作目录
`///cron ...`	管理 Cron 任务

企业微信命令

命令	说明
`/help`	查看帮助
`/panel`	打开控制面板
`/model <provider:model>`	切换模型
`/agent <name>`	切换 Agent
`/session new`	开启新话题
`/undo`	撤回上一轮交互
`/compact`	压缩上下文

🏗️ 架构概览

┌─────────────────────────────────────────────────────────────┐
│                      平台适配层                              │
│  飞书 │ Discord │ 企业微信 │ Telegram │ QQ │ WhatsApp │ 微信  │
└────┬────────┬────────┬────────┬────────┬────────┬──────────┘
     │        │        │        │        │        │
     └────────┴────────┴────────┴────────┴────────┘
                        │
              ┌─────────▼─────────┐
              │     路由层        │
              │   RootRouter      │
              └─────────┬─────────┘
                        │
     ┌──────────────────┼──────────────────┐
     │                  │                  │
┌────▼────┐      ┌─────▼─────┐      ┌─────▼─────┐
│权限处理 │      │ 问题处理  │      │ 输出缓冲  │
│Permission│     │ Question  │      │ Output    │
└────┬────┘      └─────┬─────┘      └─────┬─────┘
     │                 │                  │
     └─────────────────┼──────────────────┘
                       │
             ┌─────────▼─────────┐
             │   OpenCode 集成   │
             │  OpencodeClient   │
             └─────────┬─────────┘
                       │
             ┌─────────▼─────────┐
             │   OpenCode CLI    │
             └───────────────────┘

📚 文档导航

核心文档

文档	说明
架构设计	项目分层设计与核心模块职责
配置中心	完整配置参数说明
部署运维	部署、升级与 systemd 配置
命令速查	完整命令列表与使用说明
可靠性指南	心跳、Cron 与宕机救援配置
故障排查	常见问题与解决方案

平台配置文档

文档	说明
飞书配置	飞书事件订阅与权限配置
Discord 配置	Discord 机器人配置指南
企业微信配置	企业微信机器人配置指南
Telegram 配置	Telegram Bot 配置指南
QQ 配置	QQ 官方/OneBot 协议配置指南
WhatsApp 配置	WhatsApp Personal/Business 配置指南
微信个人号配置	微信个人号配置指南

扩展文档

文档	说明
Agent 使用	角色配置与自定义 Agent
实现细节	关键功能实现说明
SDK API	OpenCode SDK 集成指南
工作目录指南	工作目录策略与项目配置
灰度部署	路由器模式灰度与回滚

📋 环境要求

Node.js: >= 18.0.0
操作系统: Linux / macOS / Windows
OpenCode: 需要安装并运行

🔧 配置说明

配置管理方式

方式	说明
Web 面板（推荐）	访问 `http://localhost:4098` 可视化配置
SQLite 数据库	配置存储在 `data/config.db`
.env 文件	仅存储 Admin 面板启动参数

核心配置项

配置项	默认值	说明
`FEISHU_ENABLED`	`false`	是否启用飞书适配器
`DISCORD_ENABLED`	`false`	是否启用 Discord 适配器
`OPENCODE_HOST`	`localhost`	OpenCode 地址
`OPENCODE_PORT`	`4096`	OpenCode 端口
`ADMIN_PORT`	`4098`	Web 配置面板监听端口

完整配置参数请参考配置中心文档。

📄 许可证

本项目采用 GNU General Public License v3.0

GPL v3 意味着：

✅ 可自由使用、修改和分发
✅ 可用于商业目的
✅ 必须开源修改版本
✅ 必须保留原作者版权
✅ 衍生作品必须使用 GPL v3 协议

🌟 贡献与反馈

如果这个项目对你有帮助，请给个 Star！

遇到问题或有改进建议，欢迎提交 Issue 或 Pull Request。

📞 技术支持

GitHub Issues: 问题反馈
项目主页: GitHub Repository