dsh-feishu-bridge

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

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

English: README.en.md

特性

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

支持的命令

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

不带参数时，/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 查看完整命令列表。

配置文件与凭据位置

配置项

完整示例：

- 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.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 网页端能力，飞书文字通道无法下发文件。
• 一个飞书应用只应跑一个长连接实例。

常见问题

卸载

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

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

文档

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

许可证

MIT