dsh-feishu-bridge

把飞书机器人接入 DeepSeek Harness（DSH） 的桥接插件。

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

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。

---

快速开始（部署进 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: <你的 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	否	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：

权限标识	用途	是否必需
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 配置。

---

文档

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

许可证

MIT