Feishu / Discord ×ばつ OpenCode 桥接服务 v2.9.0

v2.9.0 Node.js >= 18 TypeScript License: GPLv3

这是一个跨平台桥接层,不只服务飞书,也服务 Discord。v2.9.0 将核心从"单文件堆逻辑"重构为"平台适配层 + 根路由器 + OpenCode 事件中枢 + 领域处理器",重点解决跨平台扩展、权限闭环稳定性、目录实例一致性和线上可维护性。

随着运行时 Cron(API + /cron + ///cron + 自然语言语义解析)与本地可靠性治理落地,本项目和 OpenClaw 在"自动化调度 + 运维可用性"上的能力差距进一步缩小,同时保留本项目在多平台路由与权限闭环上的工程优势。

• 权限和提问链路一旦断路,任务会卡住:permission.asked / question.asked 必须形成严格闭环。
• 多平台并行时最怕串线:会话绑定、权限队列、输出缓冲如果不按平台隔离,异常很难排查。
• 切目录后的实例一致性是高频坑:日志显示"允许",实际 OpenCode 目录实例未命中,任务仍会挂起。
• 卡片与文本交互模型差异大:飞书与 Discord 不能硬复制同一交互范式,必须走平台原生能力。
• 运维闭环要求越来越高:仅靠"能跑起来"不够,必须可验证、可回滚、可灰度。

这个项目解决的不是"能不能回复消息",而是"跨平台 AI 任务能否长期稳定闭环"。

结论:如果目标只是"在聊天里接一个 AI",很多桥接都能满足;如果你要的是"跨平台 + 权限/提问/会话/目录/调度/回滚/运维"一体化工程链路,这个项目更适合生产化长期使用。

注:左列为常见实现归纳,不代表任一具体项目的完整能力清单;请以各项目当期版本文档为准。

新时代了,让 AI 代理自动部署吧:请在 OpenCode 执行如下指令:

请阅读 https://github.com/HNGM-HP/opencode-bridge/blob/main/AI_Deployment_Guide.md 文档并安装程序

• 先看痛点
• 与 OpenClaw 和同类桥接对比
• 为什么用它
• 能力总览
• 效果演示
• 架构概览
• 快速开始
• 部署与运维
• 环境变量
• 可靠性能力(心跳 + Cron + 宕机救援)
• 飞书后台配置
• 命令速查
• 关键实现细节
• 故障排查

• 对使用者友好:权限确认、question 作答、会话操作都在飞书里完成,不强依赖本地终端。
• 对协作友好:支持绑定已有会话与迁移绑定,跨设备、跨群接力时上下文不断裂。
• 对稳定性友好:会话映射持久化 + 双端撤回 + 同规则清理,避免"表面正常、状态错位"。
• 对运维友好:内置部署、升级、状态检查与后台管理流程,适合持续托管运行。
• 对未来版本友好:已兼容 OpenCode Server Basic Auth,服务端启用密码后仍可直接接入。

折叠展示图片,下面按场景整理:

flowchart TB
 subgraph Platforms[平台接入层]
 FE[Feishu Adapter]
 DC[Discord Adapter]
 end
 subgraph Ingress[入口与路由层]
 RR[RootRouter\nFeishu 消息/卡片动作]
 DH[DiscordHandler\n频道消息/命令]
 end
 subgraph Domain[领域服务层]
 PH[PermissionHandler]
 QH[QuestionHandler]
 OB[OutputBuffer]
 CS[ChatSessionStore]
 LC[LifecycleHandler]
 end
 subgraph OpenCode[OpenCode 集成层]
 OC[OpencodeClientWrapper]
 EH[OpenCodeEventHub]
 end
 FE --> RR
 DC --> DH
 RR --> PH
 RR --> QH
 RR --> OB
 DH --> OC
 PH --> OC
 QH --> OC
 EH --> OB
 EH --> PH
 EH --> QH
 Domain <--> CS
 OC <--> EH
 OC <--> OpenCodeServer[(OpenCode Server)]
 LC --> CS

• 项目架构
• OpenCode-sdk-api

1. 平台接入层(Adapter)

   • Feishu: 长连接事件 + 卡片交互,能力完整(权限/问题/流式卡片)。
   • Discord: 网关消息接入 + 文本回复 + 编辑/删除 + 会话命令,默认关闭按需启用。

2. 入口与路由层(Ingress)

   • Feishu 走 RootRouter,维持既有权限卡片、问题卡片、双轨日志能力。
   • Discord 走 DiscordHandler,优先保证稳定问答闭环,不强行复制不适合 Discord 的卡片交互。

3. 领域服务层(Domain)

   • ChatSessionStore: 统一会话命名空间(platform:conversationId),解决多平台同 ID 冲突。
   • OutputBuffer: 流式输出合并与节流,避免高频更新触发平台限流。
   • PermissionHandler / QuestionHandler: 管理 OpenCode 交互状态机与回路由。

4. OpenCode 集成层

   • OpencodeClientWrapper: 会话创建、消息发送、权限/问题回复、目录实例管理。
   • OpenCodeEventHub: 单监听入口,统一分发事件到缓冲区与交互处理器。

• 优先落地:消息稳定收发、会话绑定、@ 触发治理、可观测日志与可回滚配置。
• 利用优势:Discord 文本链路低摩擦,先交付高可用问答与命令链路(///session、///new、///clear,并兼容旧前缀)。
• 避免短板硬上:对 Discord 不天然友好的"飞书式卡片工作流"不做粗暴复制,后续按组件交互逐步演进。

Linux/macOS:

./scripts/deploy.sh guide

Windows PowerShell:

.\scripts\deploy.ps1 guide

这条命令会自动完成:

• 检测 Node.js / npm(缺失时给安装引导)
• 检测 OpenCode 安装与端口状态
• 可一键安装 OpenCode(npm i -g opencode-ai)
• 安装项目依赖并编译桥接服务
• 若 .env 不存在,会自动由 .env.example 复制生成(不会覆盖已有 .env)
• 可在交互阶段直接输入 FEISHU_APP_ID / FEISHU_APP_SECRET 并写入 .env(支持回撤/跳过)

提醒:

• 不添加guide后缀执行命令为菜单。
• 这一条命令可以完成"部署与环境准备"。
• 但飞书密钥需要你自己填,脚本不会替你写入真实凭据;未填写时服务无法正常接收飞书消息。

cp .env.example .env

至少填写:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

推荐在菜单里执行"启动 OpenCode CLI(自动写入 server 配置)",或直接运行:

opencode

Linux/macOS:

./scripts/start.sh

Windows PowerShell:

.\scripts\start.ps1

开发调试可用:

npm run dev

npm install -g opencode-bridge
opencode-bridge

说明:

• npm 包主要提供 CLI 分发与版本管理便利,不替代 OpenCode 本地服务与飞书/Discord 配置。
• 运行前仍需准备 .env、本地 opencode serve,以及对应平台的机器人凭据。
• CLI 默认优先读取当前工作目录下的 .env;若当前目录没有 .env,会自动回退读取 ~/.config/opencode-bridge/.env。
• 你也可以显式指定配置目录:opencode-bridge --config-dir /path/to/config。
• 若你偏好源码部署,继续使用仓库里的 scripts/deploy.* / scripts/start.* 也完全没问题。

推荐的 npm CLI 配置方式:

mkdir -p ~/.config/opencode-bridge
# 若你是通过 npm 全局安装:
cp "$(npm root -g)/opencode-bridge/.env.example" ~/.config/opencode-bridge/.env
# 若你是源码仓库内运行:
# cp .env.example ~/.config/opencode-bridge/.env
# 直接使用默认配置目录启动
opencode-bridge
# 或者在当前目录放独立 .env
mkdir -p ~/opencode-bridge-prod
cp .env.example ~/opencode-bridge-prod/.env
cd ~/opencode-bridge-prod
opencode-bridge
# 也可以显式指定配置目录
opencode-bridge --config-dir ~/.config/opencode-bridge

说明:

• deploy.sh(Linux/macOS)和 deploy.ps1(Windows)会先自动检测 Node.js 与 npm。
• deploy / upgrade / guide / service-install 默认都会先执行一次清洁安装预处理:清理旧的 dist、node_modules、历史打包产物以及 logs/bridge.pid。
• 清洁安装默认保留用户个性化文件与数据:如 .env、.env.example、cron/、.chat-sessions.json、.user-sessions.json、logs/、scripts/。
• Windows:若未检测到 Node.js,会询问是否自动安装(优先使用 winget,其次 choco),安装后自动重试。
• Linux/macOS:若未检测到,会询问是否显示安装引导,再让用户确认是否重试检测。
• 菜单内已包含 OpenCode 的安装/检查/启动与首次引导,部署时会额外给出 OpenCode 安装与端口检查强提示(不阻断部署)。

管理菜单内提供以下操作:

• 安装并启动 systemd 服务
• 停止并禁用 systemd 服务
• 卸载 systemd 服务
• 查看运行状态

也可以直接命令行调用:

sudo node scripts/deploy.mjs service-install
sudo node scripts/deploy.mjs service-disable
sudo node scripts/deploy.mjs service-uninstall
node scripts/deploy.mjs status

日志默认在 logs/service.log 和 logs/service.err。

以 src/config.ts 与 src/index.ts 实际读取为准:

注意:TOOL_WHITELIST 做字符串匹配,权限事件可能使用 permission 字段值(例如 external_directory),请按实际标识配置。

如果 OpenCode 端开启了 OPENCODE_SERVER_PASSWORD,桥接端也必须配置同一组 OPENCODE_SERVER_USERNAME/OPENCODE_SERVER_PASSWORD,否则会出现 401/403 认证失败。

模型默认策略:仅当 DEFAULT_PROVIDER 与 DEFAULT_MODEL 同时配置时,桥接才会显式指定模型;否则由 OpenCode 自身默认模型决定。

ALLOWED_USERS 说明:

• 未配置或留空:不启用白名单;生命周期清理仅在群成员数为 0 时才会自动解散群聊。
• 已配置:启用白名单保护;当群成员不足且群内/群主都不在白名单时,才会自动解散。

手动绑定会话说明(ENABLE_MANUAL_SESSION_BIND=true 时):

• 通过 /session <sessionId> 或建群下拉卡片绑定已有会话后,会默认标记为"删除保护"。
• 自动清理与 /clear free session 仍可解散群聊并移除绑定,但会跳过 OpenCode deleteSession。

ENABLE_MANUAL_SESSION_BIND 取值语义:

• true:允许 /session <sessionId>,且建群卡片可选择"绑定已有会话"。
• false:禁用手动绑定能力;建群卡片仅保留"新建会话"。

ALLOWED_DIRECTORIES 说明:

• 未配置或留空:禁止用户通过 /session new <path> 自定义路径;仅允许使用默认目录、项目别名或从已知项目列表选择。
• 已配置:用户输入的路径经规范化与 realpath 解析后,必须落在允许根目录之下(含子目录),否则拒绝。
• 多个根目录用逗号分隔,如 ALLOWED_DIRECTORIES=/home/user/projects,/opt/repos。
• Windows 系统支持 Windows 格式路径,可使用正斜杠 / 或反斜杠 \ 作为路径分隔符,如 ALLOWED_DIRECTORIES=C:\Users\YourName\Documents,D:/Projects。

PROJECT_ALIASES 说明:

• JSON 格式映射短名到绝对路径,如 {"frontend":"/home/user/frontend"}。
• 用户可通过 /session new frontend 使用别名创建会话,无需记忆完整路径。
• 别名路径同样受 ALLOWED_DIRECTORIES 约束。

• 启动桥接服务后会自动初始化可靠性生命周期(心跳引擎 + Cron 调度 + 救援编排)。
• 默认情况下主动心跳关闭(RELIABILITY_PROACTIVE_HEARTBEAT_ENABLED=false);若开启后由 Bridge 定时器触发,不依赖飞书入站消息。
• 内置 Cron 任务默认启用:
  • watchdog-probe: 每 30 秒
  • process-consistency-check: 每 60 秒
  • stale-cleanup: 每 5 分钟(当前版本为调度占位)
  • budget-reset: 每天 0 点

当前提供三种入口,底层共用同一 RuntimeCronManager 与同一持久化文件:

• HTTP API:/cron/list|add|update|remove
• Feishu:/cron ...
• Discord:///cron ...
• 默认行为:Cron 任务会绑定"创建它的聊天窗口 + 当时绑定的 OpenCode 会话",到点后优先在原会话执行,并把结果回推到原聊天窗口。

同时支持 /cron 与 ///cron 的自然语言语义解析,例如:

• /cron 添加个定时任务,每天早上8点向我发送一份AI简报
• ///cron 生产AI简报,工作日记得发我
• /cron 暂停任务 <jobId>

通过本地 HTTP API 动态增删改查:

• GET /cron/list:列出任务
• POST /cron/add:新增任务
• POST /cron/update:更新任务
• POST /cron/remove:删除任务

任务持久化到 RELIABILITY_CRON_JOBS_FILE(默认 ~/cron/jobs.json),服务重启后自动恢复。若当前聊天没有绑定 OpenCode 会话,则 /cron add ... 会拒绝创建,避免后续退化成新开匿名会话执行。

/cron list 现在会额外展示目标窗口、孤儿状态和候选回退目标,例如:

🕒 运行时 Cron 任务列表
(状态基于本地绑定表;fallback 为候选目标)
- [启用] 7c0d... | 国际新闻简报 | 0 0 18 * * *
 text: 给我推送今天的国际新闻
 target: feishu:oc_xxx(本地绑定有效) | session: ses_xxx
 orphan: 否
 fallback: 候选 feishu:oc_private_xxx(创建者私聊)
- [启用] a19f... | 昨日总结 | 0 0 9 * * 1-5
 text: 当我们每天第一次沟通,记得给我发昨日总结
 target: feishu:oc_group_yyy(原会话已迁移到 feishu:oc_group_zzz) | session: ses_yyy
 orphan: 是(原会话已迁移到其他窗口)
 fallback: 候选 feishu:oc_private_xxx(创建者私聊);原会话已迁移,运行时不会直接回退

# 列出任务
curl http://127.0.0.1:4097/cron/list
# 新增任务(每分钟触发 systemEvent)
curl -X POST http://127.0.0.1:4097/cron/add \
 -H "Content-Type: application/json" \
 -d '{
 "name": "daily-check",
 "schedule": { "kind": "cron", "expr": "0 * * * * *" },
 "payload": {
 "kind": "systemEvent",
 "text": "执行例行检查",
 "sessionId": "ses_xxx",
 "delivery": {
 "platform": "feishu",
 "conversationId": "oc_xxx"
 }
 },
 "enabled": true
 }'
# 更新任务(禁用)
curl -X POST http://127.0.0.1:4097/cron/update \
 -H "Content-Type: application/json" \
 -d '{
 "id": "<job-id>",
 "enabled": false
 }'
# 删除任务
curl -X POST http://127.0.0.1:4097/cron/remove \
 -H "Content-Type: application/json" \
 -d '{ "id": "<job-id>" }'

如果配置了 RELIABILITY_CRON_API_TOKEN,请求需携带:

-H "Authorization: Bearer <token>"

# 建议保持本地 OpenCode,才能触发自动救援
OPENCODE_HOST=localhost
OPENCODE_PORT=4096
# Cron 基础开关
RELIABILITY_CRON_ENABLED=true
RELIABILITY_CRON_API_ENABLED=true
RELIABILITY_CRON_API_HOST=127.0.0.1
RELIABILITY_CRON_API_PORT=4097
# RELIABILITY_CRON_API_TOKEN=your-token
# RELIABILITY_CRON_JOBS_FILE=/absolute/path/jobs.json
# RELIABILITY_CRON_ORPHAN_AUTO_CLEANUP=false
# RELIABILITY_CRON_FORWARD_TO_PRIVATE=false
# RELIABILITY_CRON_FALLBACK_FEISHU_CHAT_ID=oc_xxx
# RELIABILITY_CRON_FALLBACK_DISCORD_CONVERSATION_ID=1234567890
# 主动心跳开关(默认关闭)
RELIABILITY_PROACTIVE_HEARTBEAT_ENABLED=false
RELIABILITY_INBOUND_HEARTBEAT_ENABLED=false
# 可靠性策略(默认即已生效,这里是显式写法)
RELIABILITY_LOOPBACK_ONLY=true
RELIABILITY_HEARTBEAT_INTERVAL_MS=1800000
RELIABILITY_FAILURE_THRESHOLD=3
RELIABILITY_WINDOW_MS=90000
RELIABILITY_COOLDOWN_MS=300000
RELIABILITY_REPAIR_BUDGET=3
# 心跳 Agent 与提示词(可选)
# RELIABILITY_HEARTBEAT_AGENT=companion
# RELIABILITY_HEARTBEAT_PROMPT=Read HEARTBEAT.md ... reply HEARTBEAT_OK
# 心跳异常时推送到飞书 chat_id(逗号分隔,可选)
# RELIABILITY_HEARTBEAT_ALERT_CHATS=oc_xxx,oc_yyy
# 宕机救援会读取并备份这个配置文件
OPENCODE_CONFIG_FILE=./opencode.json

0. 若要启用主动心跳,先设置 RELIABILITY_PROACTIVE_HEARTBEAT_ENABLED=true 并重启服务。
1. 打开 HEARTBEAT.md,按以下规则编辑检查项:
   • - [ ] failure_type: 描述 = 启用
   • - [x] failure_type: 描述 = 停用
2. Bridge 定时器按 RELIABILITY_HEARTBEAT_INTERVAL_MS 触发,主动向 Agent Session 发送心跳提示。
3. Agent 读取 HEARTBEAT.md 并执行检查:
   • 无异常:回复 HEARTBEAT_OK
   • 有异常:返回告警文本(可由桥接推送到 RELIABILITY_HEARTBEAT_ALERT_CHATS)
4. 查看 memory/heartbeat-session.json(心跳 session)与 logs/reliability-audit.jsonl(审计)。

flowchart TD
 A[Bridge 启动] --> B[加载内置 Cron 任务]
 B --> C[加载持久化 jobs.json]
 C --> D[注册到 CronScheduler]
 D --> E[按 cron expr 定时触发]
 E --> F{payload.kind}
 F -->|systemEvent| G[检查原聊天窗口与原会话绑定]
 G -->|绑定仍有效| H[在原 OpenCode 会话执行]
 H --> I[结果回推原聊天窗口]
 G -->|原窗口失效且允许转发| J[执行后转发到私聊/备用窗口]
 G -->|原窗口失效且禁止转发| K[跳过或清理僵尸任务]

flowchart TD
 A[Bridge 定时器每 N 分钟] --> B[发送心跳提示到 Agent Session]
 B --> C[Agent 读取 HEARTBEAT.md]
 C --> D{检查结果}
 D -->|无异常| E[回复 HEARTBEAT_OK]
 D -->|有异常| F[回复告警内容]
 E --> G[桥接静默记录]
 F --> H[桥接记录并可推送用户告警]

当前运行链路按"无限重连阈值"判定:

• 健康探针持续失败,且满足:
  • 连续失败次数 >= RELIABILITY_FAILURE_THRESHOLD
  • 失败窗口时长 >= RELIABILITY_WINDOW_MS
• 同时满足以下守卫:
  • 目标主机为 loopback(localhost/127.0.0.1/::1)
  • 修复预算未耗尽
  • 距离上次修复已过冷却窗口

命中后会执行:加锁与单实例检查 → 环境诊断 → 配置备份与两级回退 → 启动 OpenCode → 健康复检 → 自动下发修复上下文。

• 心跳 session 状态:memory/heartbeat-session.json
• 可靠性审计:logs/reliability-audit.jsonl
• 配置备份:<OPENCODE_CONFIG_FILE>.bak.<timestamp>.<sha256>
• 恢复通知:自动发送到 OpenCode 会话,消息内包含 failureReason、backupPath、nextAction

• RELIABILITY_CRON_ORPHAN_AUTO_CLEANUP=false:
  • 不在启动时自动扫描 Cron 孤儿任务。
  • 不在飞书群解散 / Discord 频道删除时自动删除对应 Cron。
  • 任务执行时若绑定失效,会直接跳过并记录日志。
• RELIABILITY_CRON_ORPHAN_AUTO_CLEANUP=true:
  • 启动时扫描并删除缺少原窗口绑定或缺少原 session 的僵尸 Cron。
  • 飞书群解散、Discord 频道删除时,联动删除绑定到该窗口的 Cron。
  • stale-cleanup 周期任务也会继续扫描僵尸 Cron。
• RELIABILITY_CRON_FORWARD_TO_PRIVATE=true:
  • 当原聊天窗口失效、但原 session 仍可执行且未绑定到别的活动窗口时,可把结果转发到私聊/备用窗口。
  • 备用目标优先级:任务显式 fallback > env fallback id > 同平台创建者私聊。

# 1) 检查 OpenCode 本地环境
node scripts/deploy.mjs opencode-check
# 2) 核验可靠性启动/清理链路
npm test -- tests/reliability-bootstrap.test.ts
# 3) 核验救援端到端场景
npm test -- tests/reliability-rescue.e2e.test.ts

补充:RELIABILITY_MODE 目前是预留策略字段,当前版本仍以"阈值 + 预算 + 冷却 + loopback 限制"作为实际触发条件。

启用 Discord 需要同时满足:

1. .env 中开启 DISCORD_ENABLED=true
2. 配置 DISCORD_TOKEN(或 DISCORD_BOT_TOKEN)
3. 建议配置 DISCORD_CLIENT_ID
4. 在 Discord Developer Portal 中开启 Message Content Intent

推荐同时配置:

• ENABLED_PLATFORMS=feishu,discord(显式控制启用平台)
• GROUP_REQUIRE_MENTION=true(降低群聊噪声,只在明确 @ 机器人时响应)

当前 Discord 侧的可用能力:

• 频道/私聊消息接入与自动会话绑定
• 文本问答闭环(请求 OpenCode 后回帖)
• 流式输出展示:分隔符 + 思维链路代码块 + 最终答复正文
• OpenCode 会话命名:Discord 私聊/群聊 <ID前6位> <频道ID前6位>
• 权限交互闭环:支持 Button/Select 组件交互,同时提供文本兜底(回复"允许/拒绝/始终允许")
• question 交互闭环(显示题干 + 下拉作答 + 文本自定义答案 + 跳过本题)
• 机器人消息发送、回复、编辑、删除
• 会话频道创建:///new-channel(频道名 opencode{sessionID前6位(去前缀)},权限不足自动回退当前频道绑定)
• 频道删除自动解绑:监听 ChannelDelete 自动清理本地会话映射
• 频道删除自动销毁会话:仅对 Discord 新建会话生效;外部绑定会话受保护不删除
• 未绑定自动建会话 onboarding:首次消息自动创建会话并发送帮助引导,同时提示当前会话未与opencode绑定,已新建会话并绑定如需切换请按照help提示操作
• 频道命令:///session、///new、///new-channel、///bind、///unbind、///rename、///sessions、///workdir、///send、///clear
• 下拉控制面板:///create_chat(同卡片多下拉:会话/模型/角色;强度使用命令行)

平台边界原则(不跨平台借调):

• Discord 与 Feishu 是独立平台,各自保持原生交互范式
• Discord 侧不硬复制"飞书式卡片工作流",而是利用 Discord 原生组件(Button/Select)逐步演进
• 两端会话体系独立,不支持跨平台会话借调或 UI 组件复用

建议使用长连接模式(WebSocket 事件)。

注意:飞书后台不同版本的权限名称可能略有差异,按上表接口能力逐项对齐即可;若只需文本对话且不处理附件,可暂不开启 im:resource。

• 可以复制下方参数保存至acc.json,然后在飞书开发者后台--权限管理--批量导入/导出权限

{
 "scopes": {
 "tenant": [
 "im:message.p2p_msg:readonly",
 "im:chat",
 "im:chat.members:read",
 "im:chat.members:write_only",
 "im:message",
 "im:message.group_at_msg:readonly",
 "im:message.group_msg",
 "im:message.reactions:read",
 "im:message.reactions:write_only",
 "im:resource"
 ],
 "user": []
 }
}

Discord 侧推荐命令(优先 /// 前缀,避免与原生 Slash 冲突):

说明:

• 已保留兼容命令:/session、/new、/new-session、/clear。

• ///create_chat 使用 Discord 下拉菜单与弹窗(Modal),用于补齐会话控制体验。

• ///clear 在会话频道(topic 带 oc-session:)中会尝试直接删除频道;若权限不足则只解绑。

• ! 透传仅支持白名单命令;vi/vim/nano 等交互式编辑器不会透传。

• 单条临时覆盖可在消息开头使用 #low / #high / #max / #xhigh(仅当前条生效)。

• 强度优先级:#临时覆盖 > ///effort 会话默认 > 模型默认。

• ///sessions 列表列顺序固定为:工作区目录 | SessionID | OpenCode侧会话名称 | 绑定群明细 | 当前会话状态。

• ///create_chat 下拉标签顺序固定为:工作区 / Session短ID / 简介,并按工作区聚合展示。

• 推荐使用 /panel 可视化切换角色(当前群即时生效)。
• 也可用命令:/agent(查看当前)、/agent <name>(切换)、/agent off(回到默认)。

• 支持自然语言直接创建并切换:

创建角色 名称=旅行助手; 描述=擅长制定旅行计划; 类型=主; 工具=webfetch; 提示词=先询问预算和时间,再给三套方案

• 也支持斜杠形式:

/role create 名称=代码审查员; 描述=关注可维护性和安全; 类型=子; 工具=read,grep; 提示词=先列风险,再给最小改动建议

• 类型 支持 主/子(或 primary/subagent)。

• 配置后如果 /panel 未立即显示新角色,重启 OpenCode 即可。

• permission.asked 里 tool 可能不是字符串工具名,实际白名单匹配可落在 permission 字段。
• 回传接口要求 response 为 once | always | reject,不是 allow | deny。

• 问题渲染为飞书卡片,答案通过用户文字回复解析。
• 解析后按 OpenCode 需要的 answers: string[][] 回传,并纳入撤回历史。

• 文本与思考分流写入输出缓冲;出现思考内容时自动切换卡片模式。
• 卡片支持展开/折叠思考,最终态保留完成状态。

• 需要同时删除飞书侧消息并对 OpenCode 执行 revert。
• 问答场景可能涉及多条关联消息,使用递归回滚兜底。

• 下拉选择动作仅记录会话选择,不依赖卡片重绘;行为与 /panel 的下拉交互保持一致。
• 点击"创建群聊"时才执行建群与绑定,避免因卡片状态同步导致误绑定。

• 该命令不做单独清理规则,而是复用生命周期扫描逻辑。
• 可在不重启进程时,手动触发一次"启动时清理"的同规则兜底扫描。

• /send <绝对路径> 直接调用飞书上传 API,不经过 AI,0 延迟。
• 图片(.png/.jpg/.gif/.webp 等)走图片通道(上限 10MB),其余走文件通道(上限 30MB),与飞书官方限制一致。
• 内置敏感文件黑名单(.env、id_rsa、.pem 等),防止误发。
• 安全策略:仅允许发送位于 ALLOWED_DIRECTORIES 白名单范围内的文件;未配置 ALLOWED_DIRECTORIES 时,/send 默认拒绝。

• 所有会话创建入口统一走 DirectoryPolicy.resolve() 9 阶段校验流水线。
• 校验顺序:优先级合并 → 格式校验 → 路径规范化 → 危险路径拦截 → 白名单校验 → 存在性预检 → realpath 解析 → Git 根目录归一化 → 归一后复检。
• 安全默认:未配置 ALLOWED_DIRECTORIES 时,用户不能自定义路径。
• 错误信息脱敏:用户侧只看到通用提示,完整路径仅写入服务端日志。
• 目录优先级:显式指定 > 项目别名 > 群默认 > 全局默认 > OpenCode 服务端默认。

注意: 本章节适用于 v2.9.0 版本,涉及路由器模式的灰度升级流程。

# 临时设置(命令行)
ROUTER_MODE=legacy node scripts/start.mjs
ROUTER_MODE=dual node scripts/start.mjs
ROUTER_MODE=router node scripts/start.mjs
# 永久设置(.env 文件)
echo "ROUTER_MODE=dual" >> .env

Legacy 模式:

[Config] 路由器模式: legacy

Dual 模式:

[Config] 路由器模式: dual
[Config] ⚠️ 双轨模式: 将记录新旧路由对比日志,不改变当前行为
[Config] 📝 如需回滚到旧版路由,设置 ROUTER_MODE=legacy 并重启服务

Router 模式:

[Config] 路由器模式: router

遵严格的三阶段验证流程,确保回滚路径清晰可控:

flowchart LR
 A[Legacy 模式] -->|启动验证| B[Dual 模式]
 B -->|观察 24h| C[Router 模式]
 C -->|无异常| D[全量上线]
 C -->|异常| E[立即回滚]
 B -->|异常| E

Phase 1: Legacy 验证

• 配置: ROUTER_MODE=legacy
• 验证内容: 基础消息流、权限流、卡片流
• 通过标准: 53 个单元测试 100% 通过

Phase 2: Dual 验证

• 配置: ROUTER_MODE=dual
• 验证内容: 双轨日志对比、行为一致性
• 关键日志: type: "[Router][dual]" 字段完整性
• 观察时间: ≥ 24 小时

Phase 3: Router 验证

• 配置: ROUTER_MODE=router
• 验证内容: 新路由事件分发、功能等价性
• 通过标准: 与 legacy 模式行为一致

功能验证:

• 私聊消息收发
• 群聊消息收发
• 权限卡片确认
• 提问卡片处理
• 消息撤回同步
• 会话绑定迁移

性能验证:

• 消息延迟 < 500ms
• 错误率 < 0.1%
• 卡片.update成功率 > 99%

日志验证:

• 双轨日志字段完整
• 无异常错误输出

出现以下任一情况时,立即执行回滚:

# 1. 停止服务
node scripts/stop.mjs
# 2. 设置回滚模式
echo "ROUTER_MODE=legacy" > .env
# 3. 重启服务
node scripts/start.mjs
# 4. 验证回滚成功
grep "路由器模式" logs/service.log
# 期望输出: [Config] 路由器模式: legacy

回滚后必须验证:

• 普通消息收发正常
• 权限卡片正确显示
• 提问卡片正确处理
• 撤回操作同步
• 会话绑定功能正常

{
 "type": "[Router][dual]",
 "event": "onMessage",
 "platform": "feishu",
 "conversationKey": "feishu:chat_id_xxx",
 "sessionId": "session_id_xxx",
 "routeDecision": "group",
 "chatType": "group",
 "chatId": "chat_id_xxx"
}

字段说明:

• conversationKey: 会话键(格式: {platform}:{chatId})
• sessionId: OpenCode 会话 ID
• routeDecision: 路由决策(p2p/group/card_action/opencode_event)

# 检查路由器模式
grep "路由器模式" logs/service.log
# 检查双轨日志(dual 模式)
grep "\[Router\]\[dual\]" logs/service.log
# 检查错误日志
tail -n 100 logs/service.err | grep -i error

注意: ROUTER_MODE 仅接受 legacy、dual、router 三个值,其他值将回退到 legacy。

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

GPL v3 意味着:

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

如果这个项目对你有帮助,请给个 ⭐️ Star!