![dsh-feishu-bridge banner](docs/assets/dsh-feishu-bridge-banner.png)

dsh-feishu-bridge

![CI](https://github.com/ailoushu666/dsh-feishu-bridge/actions/workflows/ci.yml)

把飞书机器人接入 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）](#快速开始部署进-dsh)；飞书后台配置见 [docs/feishu-setup.md](docs/feishu-setup.md)。

> English: README.en.md

---

特性

使用飞书官方 @larksuiteoapi/node-sdk 的 WebSocket 长连接接收事件，无需公网 IP / 域名 / 内网穿透。
同一个飞书聊天（或话题）复用同一个 DSH Session，保留上下文；话题各自独立。
回复会关联到触发它的那条消息，话题里的回复留在原话题。
默认只接收单聊和群聊里 @机器人的消息。
执行过程可见：Agent 调用工具时，飞书里会先出现 🔧 调用工具 <名称> 的过程提示。
内置一套飞书端控制命令：切项目目录、切工作模式、切模型与推理强度、停止任务、记录反馈、管理长任务目标、进入计划模式等。

---

支持的命令

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

| 命令 | 参数 | 作用 | 是否打断当前对话 | | --- | --- | --- | --- | | /reset | — | 开启新对话（旧对话保留在 DSH 侧边栏）。别名：/new、/clear、重置、新会话、清空会话、重置会话 | 是 | | /compact | — | 压缩上下文（把较早历史总结成摘要，降低 token 占用）。别名：/压缩、压缩上下文、压缩会话 | 否 | | /workspace | <目录绝对路径> | 切换项目目录（目录不存在会提示，需先在本地创建） | 是 | | /mode（= /permission） | <read\|write\|full> | 切换工作模式：只读 / 工作区写入 / 完整访问（即权限预设，含沙箱 + 审批策略） | 否（仅本会话生效） | | /model | <模型名> | 切换模型（不支持的模型名会提示） | 否（下一轮生效） | | /effort | <off\|high\|max> | 设置推理强度（只允许模型实际支持的档位） | 否（下一轮生效） | | /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](docs/feishu-setup.md)。

---

快速开始（部署进 DSH）

第 1 步：飞书后台准备

按 [docs/feishu-setup.md](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）：

``yaml FEISHU_APP_SECRET: <你的 App Secret> ``

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

``yaml - 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`	否	`10`	单个 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](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）、文件、卡片等未支持。
回答为一次性发送，非流式输出；执行过程只回传“工具调用开始”，不回传工具结果。
没有持久化的 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 配置。

---

文档

[飞书开发者后台配置指南](docs/feishu-setup.md)
[技术文档](docs/technical.md)

许可证

[MIT](LICENSE)

dsh-feishu-bridge-ailoushu

Install

Check the source files

dsh-feishu-bridge

快速安装

特性

支持的命令

运行要求

快速开始（部署进 DSH）

第 1 步：飞书后台准备

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

第 3 步：写入凭据与启用

第 4 步：启动

第 5 步：验证

配置文件与凭据位置

配置项

飞书权限

项目结构

安全说明

已知限制（MVP）

常见问题

卸载

文档

许可证

Source facts

Install

Check the source files

dsh-feishu-bridge

快速安装

特性

支持的命令

运行要求

快速开始（部署进 DSH）

第 1 步：飞书后台准备

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

第 3 步：写入凭据与启用

第 4 步：启动

第 5 步：验证

配置文件与凭据位置

配置项

飞书权限

项目结构

安全说明

已知限制（MVP）

常见问题

卸载

文档

许可证

More related plugins

dsh-mobile

dsh-qqbot

deepseek-harness-remote

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