dsh-feishu-bridge banner
dsh-feishu-bridge
把飞书机器人接入 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） | <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（敏感）分开存放：
-
把 App Secret 写进 DSH 的凭据文件 ~/.dsh/.credentials.yaml（Windows：C:\Users\<你>\.dsh\.credentials.yaml），键名与 appSecretEnv 一致（默认 FEISHU_APP_SECRET）：
FEISHU_APP_SECRET: <你的 App Secret>
-
编辑 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 |
完整示例：
- 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
