HNGM-HP / opencode-bridge

Feishu / Discord × OpenCode 桥接服务 v2.9.1 [ ]() **中文** | **English** --- 不只服务飞书，也服务 Discord。通过"平台适配层 + 根路由器 + OpenCode 事件中枢 + 领域处理器"，重点解决跨平台扩展、权限闭环稳定性、目录实例一致性和线上可维护性。 随着运行时 Cron（API + + + 自然语言语义解析）与本地可靠性治理落地，本项目和 OpenClaw 在"自动化调度 + 运维可用性"上的能力差距进一步缩小，同时保留本项目在多平台路由与权限闭环上的工程优势。 这个项目解决的不是"能不能回复消息"，而是"跨平台 AI 任务能否长期稳定闭环"。 📋 目录 • 为什么用它 • 能力总览 • 效果演示 • 架构概览 • 快速开始 • 部署与运维 • 环境变量 • 可靠性能力 • 飞书后台配置 • 命令速查 • Agent 使用 • 详细文档 💡为什么用它 • 对使用者友好：权限确认、question 作答、会话操作都在飞书里完成，不强依赖本地终端。 • 对协作友好：支持绑定已有会话与迁移绑定，跨设备、跨群接力时上下文不断裂。 • 对稳定性友好：会话映射持久化 + 双端撤回 + 同规则清理，避免"表面正常、状态错位"。 • 对运维友好：内置部署、升级、状态检查与后台管理流程，适合持续托管运行。 • 对监控友好：内置cron定时任务与主动心跳，可以做到像OpenClaw类似的能力。 • 对未来版本友好：已兼容 OpenCode Server Basic Auth，服务端启用密码后仍可直接接入。 📸 能力总览 | 能力 | 你能得到什么 | 相关命令/配置 | |---|---|---| | 群聊/私聊统一路由 | 同一套入口支持私聊和群聊，按映射路由到正确会话 | 群聊 @ 机器人；私聊直接发消息 | | 私聊建群会话选择 | 建群时可选"新建会话/绑定已有会话"，提交时按选择生效 | 、 | | 手动会话绑定 | 不中断旧上下文，直接把指定 session 接入当前群 | 、 | | 迁移绑定与删除保护 | 绑定已有会话时自动迁移旧群映射，并保护会话不被误删 | 自动生效（手动绑定场景） | | 生命周期清理兜底 | 启动清理与手动清理共用同一规则，降低误清理概率 | | | 权限卡片闭环 | OpenCode 权限请求在飞书内完成确认并回传结果 | | | question 卡片闭环 | OpenCode question 在飞书内回答/跳过并继续任务 | | | 流式多卡防溢出 | 超过组件预算自动分页拆卡，旧页持续更新 | 流式卡片分页（预算 180） | | 双端撤回一致性 | 撤回时同时回滚飞书消息与 OpenCode 会话状态 | | | 模型/角色/强度可视化控制 | 按会话切换模型、角色与推理强度，支持面板查看与命令操作 | 、 、 、 | | 上下文压缩 | 在飞书直接触发会话 summarize，释放上下文窗口 | | | Shell 命令透传 | 白名单 命令通过 OpenCode shell 执行并回显输出 | 、 、 | | 服务端鉴权兼容 | 支持 OpenCode Server Basic Auth，不怕后续默认强制密码 | 、 | | 文件发送到飞书 | AI 可将电脑上的文件/截图直接发送到当前飞书群聊 | 、 | | 工作目录/项目管理 | 创建会话时指定工作目录，支持项目别名、群默认项目、9 阶段安全校验 | 、 、 | | OpenCode 本地可靠性治理 | 运行时 Cron（API/命令/自然语言）+ 本地宕机自动救援（含配置备份/两级回退）+ 可选主动心跳 | 、 、 | | 部署运维闭环 | 提供部署/升级/检查/后台/systemd 的一体化入口 | 、 | 🖼️ 效果演示 Step 1：私聊独立会话（点击展开） Step 2：多群聊独立会话（点击展开） Step 3：图片附件解析（点击展开） Step 4：交互工具测试（点击展开） Step 5：底层权限测试（点击展开） Step 6：会话清理（点击展开） 📌 架构概览 详见 项目架构文档。 核心分层： • **平台接入层**：Feishu Adapter / Discord Adapter • **入口与路由层**：RootRouter / DiscordHandler • **领域服务层**：PermissionHandler / QuestionHandler / OutputBuffer / ChatSessionStore • **OpenCode 集成层**：OpencodeClientWrapper / OpenCodeEventHub 🚀 快速开始 1) 先执行这一条命令（首选） Linux/macOS： Windows PowerShell： 这条命令会自动完成： • 检测 Node.js / npm（缺失时给安装引导） • 检测 OpenCode 安装与端口状态 • 可一键安装 OpenCode（ ） • 安装项目依赖并编译桥接服务 • 若 不存在，会自动由 复制生成（不会覆盖已有 ） • 可在交互阶段直接输入 / 并写入 （支持回撤/跳过） **提醒**： • 不添加 后缀执行命令为菜单。 • 这一条命令可以完成"部署与环境准备"。 • 但飞书密钥需要你自己填，脚本不会替你写入真实凭据；未填写时服务无法正常接收飞书消息。 2) 填写飞书配置（必须，若上一步已输入可跳过） 至少填写： • • 3) 启动 OpenCode（保留 CLI 界面） 4) 启动桥接服务 Linux/macOS： Windows PowerShell： 开发调试可用： 5）npm CLI 安装（更适合本地常驻运行场景） 配置的详细说明见 部署与运维文档。 💻 部署与运维 已安装 Node 后可用命令 | 目标 | 命令 | 说明 | |---|---|---| | 一键部署 | | 默认清洁安装后再安装依赖并编译 | | 一键更新升级 | | 默认清洁升级：先拆卸清理，再拉取并重新部署 | | 安装/升级 OpenCode | | 执行 | | 检查 OpenCode 环境 | | 检查 opencode 命令与端口监听 | | 启动 OpenCode CLI | | 自动写入 后前台执行 | | 首次引导 | | 安装/部署/引导启动的一体化流程 | | 管理菜单 | | 交互式菜单（默认入口） | | 启动后台 | | 后台启动（自动检测/补构建） | | 停止后台 | | 按 PID 停止后台进程 | 详细部署说明见 部署与运维文档。 ⚙️ 环境变量 核心配置： | 变量 | 必填 | 默认值 | 说明 | |---|---|---|---| | | 是 | - | 飞书应用 App ID | | | 是 | - | 飞书应用 App Secret | | | 否 | | OpenCode 地址 | | | 否 | | OpenCode 端口 | | | 否 | | 是否启用 Discord 适配器 | | | 否 | - | Discord Bot Token | 完整配置详见 环境变量配置文档。 🛡️ 可靠性能力（心跳 + Cron + 宕机救援） 详见 可靠性指南。 快速概览 • **内置 Cron 任务**： （30 秒）、 （60 秒）、 （每天 0 点） • **三种管理入口**：HTTP API（ ）、Feishu（ ）、Discord（ ） • **主动心跳**：可配置定时器向 Agent Session 发送检查提示 • **自动救援**：连续失败达到阈值后自动修复本地 OpenCode（仅 loopback） 最小配置 ⚙️ 飞书后台配置 详见 飞书后台配置文档。 事件订阅 | 事件 | 必需 | 用途 | |---|---|---| | | 是 | 接收群聊/私聊消息 | | | 是 | 用户撤回触发 回滚 | | | 是 | 成员退群后触发生命周期清理 | | | 是 | 群解散后清理本地会话映射 | | | 是 | 处理控制面板、权限确认、提问卡片回调 | 应用权限 批量导入权限配置（保存至 后在开发者后台导入）： 📖 命令速查 详见 命令速查文档。 飞书命令 | 命令 | 说明 | |---|---| | | 查看帮助 | | | 打开控制面板 | | | 切换模型 | | | 切换 Agent | | | 开启新话题 | | | 撤回上一轮交互 | | | 压缩上下文 | | | 透传 shell 命令 | Discord 命令 | 命令 | 说明 | |---|---| | | 查看绑定的会话 | | | 新建并绑定会话 | | | 绑定已有会话 | | | 回撤上一轮 | | | 压缩上下文 | 🤖 Agent（角色）使用 详见 Agent 使用文档。 快速开始 • 查看当前 Agent： • 切换 Agent： • 回到默认： 自定义 Agent 📌 关键实现细节 详见 实现细节文档。 • 权限请求回传： 为 • question 工具交互：答案通过用户文字回复解析 • 流式与思考卡片：文本与思考分流写入输出缓冲 • 一致性：同时删除飞书侧消息并对 OpenCode 执行 🛠️ 故障排查 详见 故障排查文档。 | 现象 | 优先检查 | |---|---| | 飞书发送消息后 OpenCode 无反应 | 检查飞书权限配置 | | 点权限卡片后 OpenCode 无反应 | 确认回传值是 | | 失败 | 检查 OpenCode 可用模型 | | 后台模式无法停止 | 是否残留 | 📚 详细文档 | 文档 | 说明 | |---|---| | 架构文档 | 项目分层设计与平台能力矩阵 | | 环境变量 | 完整环境变量配置说明 | | 可靠性指南 | 心跳、Cron 与宕机救援配置 | | 飞书后台配置 | 事件订阅与权限配置 | | 命令速查 | 完整命令列表与使用说明 | | 实现细节 | 关键功能实现说明 | | 故障排查 | 常见问题与解决方案 | | 部署运维 | 部署、升级与 systemd 配置 | | Agent 使用 | 角色配置与自定义 Agent | | 灰度部署 | 路由器模式灰度与回滚 SOP | | SDK API | OpenCode SDK 集成指南 | | 工作目录指南 | 工作目录策略与项目配置 | 📝 许可证 本项目采用 GNU General Public License v3.0 **GPL v3 意味着：** • ✅ 可自由使用、修改和分发 • ✅ 可用于商业目的 • 📝 必须开源修改版本 • 📝 必须保留原作者版权 • 📝 衍生作品必须使用 GPL v3 协议 如果这个项目对你有帮助，请给个 ⭐️ Star！