ailoushu666/dsh-feishu-bridge

dsh-feishu-bridge 横幅

dsh-feishu-bridge

CI

把飞书机器人接入 DeepSeek Harness（DSH） 的桥接插件：Feishu / Lark ↔ DeepSeek Harness。

在飞书里跟机器人对话，消息会被转成 DSH Agent 的一次任务；Agent 的最终回答和执行过程提示（例如调用了哪些工具）都会回到飞书里显示 —— 可以直接从飞书控制 DSH Agent。

- 无需公网：WebSocket 长连接接收事件，本地即可运行
- 会话保留上下文：每个飞书聊天 / 话题对应独立的 DSH Session
- 执行过程可见：Agent 调用工具时，过程提示实时回传飞书
- 飞书命令控制：/reset、/workspace、/mode、/model、/effort、/stop 等

快速安装

从 GitHub 安装（推荐）
npx @deepseek-ai/dsh plugin --profile web add git+https://github.com/ailoushu666/dsh-feishu-bridge.git

或从本地目录安装（开发调试）
npx @deepseek-ai/dsh plugin --profile web add ""

完整配置步骤见快速开始（部署进 DSH）；飞书后台配置见 docs/feishu-setup.md。

English: README.en.md

特性

- 使用飞书官方 @larksuiteoapi/node-sdk 的 WebSocket 长连接接收事件，无需公网 IP / 域名 / 内网穿透。
- 同一个飞书聊天（或话题）复用同一个 DSH Session，保留上下文；话题各自独立。
- 回复会关联到触发它的那条消息，话题里的回复留在原话题。
- 默认只接收单聊和群聊里 @机器人的消息。
- 执行过程可见：Agent 调用工具时出现 🔧 调用工具 ，工具之间的中间回复也会转发（💬），统一走节流队列发送、不会被飞书频控丢掉；最终回答单独回复到原消息。
- 收到消息先回“正在处理 / 排队中”的即时回执；单轮执行超过时限（turnTimeoutMs）自动停止并提示。
- DSH 自主轮次的结果会主动推回飞书：当 DSH 自己唤醒 Agent（目标轮询 / 定时任务 / 后台任务）产出结果时，飞书能收到，不再局限于“一条消息换一条回复”。
- 选项问答在飞书可交互：当 Agent 需要你确认/选择（ask_user_question）时，问题与选项会以 ❓ 列表发到飞书，你直接回复编号（如 1）、选项文字或自由文本即可命中选项，Agent 接着往下干；单选给了多个编号、编号越界等非法回复会被提示重答，不会污染 Agent。
- 内置一套飞书端控制命令：切项目目录、切工作模式、切模型与推理强度、停止任务、记录反馈、管理长任务目标、进入计划模式等。

支持的命令

在飞书里直接发（群聊里 @机器人，单聊直接发），大小写不敏感。

| 命令 | 参数 | 作用 | 是否打断当前对话 |
| --- | --- | --- | --- |
| /reset | — | 开启新对话（旧对话保留在 DSH 侧边栏）。别名：/new、/clear、重置、新会话、清空会话、重置会话 | 是 |
| /compact | — | 压缩上下文（把较早历史总结成摘要，降低 token 占用）。别名：/压缩、压缩上下文、压缩会话 | 否 |
| /workspace |  | 切换项目目录（目录不存在会提示，需先在本地创建） | 是 |
| /mode（= /permission） |  | 切换工作模式：只读 / 工作区写入 / 完整访问（即权限预设，含沙箱 + 审批策略） | 否（仅本会话生效） |
| /model |  | 切换模型（不支持的模型名会提示） | 否（下一轮生效） |
| /effort |  | 设置推理强度（只允许模型实际支持的档位） | 否（下一轮生效） |
| /stop | — | 立即停止当前正在运行的任务。别名：/cancel、/halt | — |
| /feedback |  | 记录对当前会话的反馈 | 否 |
| /goal | [目标\|clear\|edit \|pause\|resume] | 设置 / 查看 / 管理长任务目标 | 否 |
| /plan | [off\|描述] | 进入 / 退出计划模式（先规划再动手） | 否 |
| /export | — | 导出会话日志（网页端功能，飞书文字通道无法下发文件，会提示到网页端操作） | — |
| /session | [编号\|完整ID] | 不带参数列出未归档会话（含标题），带参数切换到指定会话 | 是（切换会话） |
| /help | — | 列出全部命令 | — |

不带参数时，/workspace、/mode、/model、/effort 会返回当前值或可选项；/mode 的短名 read / write / full 分别对应 read-only / workspace-write / danger-full-access，全名同样可用。

运行要求

- Node.js ^22.19.0 或 >= 24（与 Harness 一致）。
- 已能运行 DeepSeek Harness（dsh web）。
- 一个飞书企业自建应用，且已：启用机器人能力、使用长连接订阅 im.message.receive_v1、开通必要权限。
飞书后台的完整配置步骤见 docs/feishu-setup.md。

快速开始（部署进 DSH）

第 1 步：飞书后台准备

按 docs/feishu-setup.md 完成：创建自建应用 → 启用机器人能力 → 开通权限 → 配置长连接订阅 im.message.receive_v1 → 发布并安装应用。记下 App ID 和 App Secret。

第 2 步：安装插件到 DSH 的 web Profile

npx @deepseek-ai/dsh plugin --profile web add ""

安装后，插件会在 bundle 层创建一个默认禁用的 feishu-bridge 实例。

第 3 步：写入凭据与启用

App ID（非敏感）和 App Secret（敏感）分开存放：

1. 把 App Secret 写进 DSH 的凭据文件 ~/.dsh/.credentials.yaml（Windows：C:\Users\\.dsh\.credentials.yaml），键名与 appSecretEnv 一致（默认 FEISHU_APP_SECRET）：

FEISHU_APP_SECRET:

2. 编辑 Profile 补丁 ~/.dsh/profiles/web/cordis.patch.yml（Windows：C:\Users\\.dsh\profiles\web\cordis.patch.yml），用同样的 id 覆盖为启用并填入 App ID：

- id: feishu-bridge
disabled: false
config:
appId: cli_xxxxxxxxxxxxxxxx        # App ID（非敏感）
appSecretEnv: FEISHU_APP_SECRET    # App Secret 的引用名，值在 ~/.dsh/.credentials.yaml
domain: feishu                     # 中国版 feishu；国际版 Lark 用 lark
requireMention: true               # 群聊需要 @机器人
dmMode: open                       # 单聊：open / allowlist / disabled

不要用 insert 再创建一个同名实例，否则会报 duplicate loader entry id: feishu-bridge。

第 4 步：启动

npx @deepseek-ai/dsh web

看到下面这行表示飞书长连接建立成功：

feishu-bridge: WebSocket connected

第 5 步：验证

- 单聊：给机器人发消息，机器人回复最终回答；继续发会保留上下文。
- 群聊：@机器人 你的问题。
- 发 /help 查看完整命令列表。

配置文件与凭据位置

| 内容 | 文件 |
| --- | --- |
| 启用实例 + 插件配置 | ~/.dsh/profiles/web/cordis.patch.yml（Windows：C:\Users\\.dsh\profiles\web\cordis.patch.yml） |
| App Secret（凭据） | ~/.dsh/.credentials.yaml（Windows：C:\Users\\.dsh\.credentials.yaml） |

配置项

| 配置项 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| appId | 是 | 无 | 飞书应用 App ID（非敏感，直接写明文） |
| appSecretEnv | 是 | FEISHU_APP_SECRET | App Secret 的凭据引用名，真正的值在 ~/.dsh/.credentials.yaml |
| domain | 否 | feishu | feishu（中国版）/ lark（国际版） |
| requireMention | 否 | true | 群聊是否必须 @机器人 |
| dmMode | 否 | open | 单聊策略：open / allowlist / disabled |
| groupAllowlist | 否 | [] | 群 chat_id 白名单，空 = 不限制 |
| dmAllowlist | 否 | [] | dmMode: allowlist 时允许的用户 open_id |
| botOpenId | 否 | 无 | 机器人 open_id，用于精确判断“是否 @机器人”；不填则退化为“mentions 非空” |
| provider / model | 否 | Harness 默认 | 为飞书渠道单独指定模型 |
| reasoningEffort | 否 | 模型默认 | 为飞书渠道指定推理强度（如 off/high/max，取决于模型支持） |
| workspace | 否 | 第一个 Workspace | Agent 的工作目录 |
| agentPreset | 否 | 默认 Preset | Agent 使用的 Preset（决定工具/系统提示组合） |
| streamProgress | 否 | true | 是否把执行过程（工具调用）回传飞书 |
| maxProgressMessages | 否 | 0（不限制） | 单个 turn 内最多回传多少条过程消息（工具调用 + 中间回复合计）；0 = 有多少转多少 |
| processingNotice | 否 | true | 收到普通消息时先回一句“正在处理 / 排队中”的即时回执 |
| turnTimeoutMs | 否 | 900000（15 分钟） | 单个 turn 最长执行时间（毫秒），超时自动取消本轮并提示 |
| resetCommand | 否 | /reset | 重置会话的指令 |
| compactCommand | 否 | /compact | 手动压缩上下文的指令 |
| requireAdminForGroupReset | 否 | true | 群聊重置是否要求群主/管理员（需 im:chat:readonly 权限；设为 false 则群成员也能重置） |
| errorMessage | 否 | 内置中文提示 | Agent 出错时返回给用户的统一提示（最长 500 字符） |

完整示例：

- id: feishu-bridge
disabled: false
config:
appId: cli_xxxxxxxxxxxxxxxx
appSecretEnv: FEISHU_APP_SECRET
domain: feishu
requireMention: true
dmMode: open
可选：
provider: deepseek-official
model: deepseek-v4-flash
reasoningEffort: high
workspace: C:\Project\my-repo
agentPreset: coding
streamProgress: true
maxProgressMessages: 10

飞书权限

默认配置（单聊 + 群聊 @机器人 + 回复）需要以下权限，详细步骤见 docs/feishu-setup.md：

| 权限标识 | 用途 | 是否必需 |
| --- | --- | --- |
| im:message.p2p_msg:readonly | 获取单聊消息 | 是 |
| im:message.group_at_msg:readonly | 获取群组中 @机器人的消息 | 是 |
| im:message:send_as_bot | 以应用身份发消息（回复） | 是 |
| im:chat:readonly | 读取群信息（判断群主/管理员） | 仅群聊 /reset 需管理员权限时 |

事件订阅：接收方式选长连接，订阅 im.message.receive_v1。

项目结构

dsh-feishu-bridge/
├── package.json          # 包元数据 + dsh.bundle 声明
├── cordis.patch.yml      # bundle patch：默认禁用的插件实例
├── lib/
│   ├── index.js          # 插件入口（name/inject/Config/apply + 命令分发）
│   ├── config.js         # 配置 Schema + 校验
│   ├── feishu.js         # 飞书长连接 + 发消息/回复
│   └── bridge.js         # 会话映射 + Agent 驱动 + 渠道状态 + 命令执行
├── docs/
│   ├── technical.md      # 技术文档
│   └── feishu-setup.md   # 飞书开发者后台配置指南
└── .env.example          # 说明凭据存放位置（实际部署无需 .env）

安全说明

- App Secret 只放在 DSH 的凭据文件 ~/.dsh/.credentials.yaml 里，插件不记录、不落盘到项目目录。
- 内部错误只回统一的 errorMessage，不把异常堆栈 / 敏感信息发给飞书用户。
- Session ID 用 SHA-256 摘要派生，不包含原始 chat_id / thread_id。
- 一个飞书应用不要同时跑多个长连接消费者（例如同时开着 DSH 桥和 OpenClaw 的飞书通道）——飞书平台会把事件随机分发给其中一个连接，导致消息被“抢走”、表现为时好时坏或完全没反应。

已知限制（MVP）

- 只处理文本消息；图片、富文本（post）、文件、卡片等未支持。
- 回答为一次性发送，非流式输出；执行过程回传“工具调用开始 + 中间回复”，不回传工具结果。
- 过程消息、中间回复、自主轮次结果、❓ 问题都发到群聊根消息——话题（thread）内的会话也不例外（飞书 API 限制，只有 reply 能留在话题内）。
- 没有持久化的 chatId → sessionId 映射：DSH 重启后，已有飞书聊天会重建新 Session（旧 Session 仍在磁盘，但不再被复用）。
- 模型 / 推理强度 / 项目目录的运行时切换是内存态，DSH 重启后回到配置默认。
- /export（导出 ZIP）是 DSH 网页端能力，飞书文字通道无法下发文件。
- 一个飞书应用只应跑一个长连接实例。

常见问题

| 现象 | 排查 |
| --- | --- |
| 启动时鉴权失败 | App ID / Secret 是否同属一个应用；FEISHU_APP_SECRET 是否写进了 ~/.dsh/.credentials.yaml |
| 显示已连接但收不到消息 | 应用是否发布并安装；机器人是否在群里；是否订阅 im.message.receive_v1；接收方式是否长连接；权限是否已通过审批；群聊是否 @机器人 |
| 能收到但不能回复 | 是否开通 im:message:send_as_bot；查看终端里的飞书 API 报错 |
| 长连接反复重连 | 检查能否访问飞书 HTTPS/WebSocket；是否同时跑了多个长连接消费者 |
| 改了配置不生效 | 停止并重启 Harness（实例在 Profile 启动时创建） |
| 群聊 /reset 提示“只有群主或群管理员” | 要么开通 im:chat:readonly 权限，要么配置 requireAdminForGroupReset: false |
| 连续对话偶发“没反应” | 多为 DeepSeek API 速率/并发限制（TPM/RPM）；稍等重试，或用 /effort off 降低推理开销 |

卸载

npx @deepseek-ai/dsh plugin --profile web remove dsh-feishu-bridge

然后清掉 ~/.dsh/profiles/web/cordis.patch.yml 里残留的 feishu-bridge 配置。

文档

- 飞书开发者后台配置指南
- 技术文档

许可证
MIT