IT-lu/dsh-imbot

在飞书 / 钉钉群里直接与 DeepSeek Harness 的 agent 对话的 DSH 插件：群里发消息（@机器人）→ 消息进入 DSH 的一个独立 agent 会话 → agent 用完整能力（模型 / 工具 / 代码 / 搜索）处理 → 回复发回群里。每个群对应独立的 agent 会话，多群互不干扰。

特性

• 双向桥接：群里 @机器人 下任务，agent 回复发回群里；同群同工作区延续上下文，多群隔离。
• 无需公网：飞书走事件订阅长连接（WebSocket）、钉钉走 Stream Mode（WebSocket），都是出站连接——DSH 所在机器能出网即可，不需要公网 IP / 端口 / 回调 URL。
• 图形化配置：DSH 设置页「IM 机器人」卡片（飞书 / 钉钉两个 Tab）。
• 工作区制：每个任务在一个工作区（目录）里执行，必须显式选择或创建，无默认工作区。
• 会话管理：按工作区分组查看/切换会话、开启新会话、归档（与 DSH GUI 归档联动）。

---

跨平台支持

插件运行在 macOS / Linux / Windows 均可（Node ≥ 20）：

• 工作区路径：Unix 用 /Users/me/proj 或 ~/proj；Windows 用盘符路径 C:/Users/me/proj（C:\Users\me\proj 也可）——在 C:/Users/me/proj 任务 会正确识别为工作区指令。
• 目录创建/展开：mkdirSync(recursive)、~ 展开、realpath 均跨平台。
• 平台差异仅在于聊天消息里的路径写法（飞书/钉钉一致），插件本身逻辑与 DSH 宿主平台无关。

安装

插件是标准 npm 包，通过 DSH 命令行安装到 profile：

# 1) 从 npm 安装（发布后）
dsh plugin --profile web add dsh-imbot

# 或从 git 仓库安装
dsh plugin --profile web add <owner>/dsh-imbot

# 或本地目录（开发调试）
dsh plugin --profile web add file:/absolute/path/to/dsh-imbot

# 2) 确认已加入 profile 的 bundle 列表
cat ~/.dsh/profiles/web/package.json   # dsh.profile.bundles 应包含 "dsh-imbot"

# 3) 重启 dsh web
npx @deepseek-ai/dsh web

提示：插件依赖 @larksuiteoapi/node-sdk 与 dingtalk-stream，pnpm 会自动安装；若 pnpm 因供应链策略（minimumReleaseAge）拦截，可临时加 --config.minimumReleaseAge=0。 本地 file: 安装是拷贝不是软链——改代码后需重新 pnpm add file:... 再重启。

重启后 DSH 设置页出现「IM 机器人」配置卡片，开始对接：

---

对接流程

⚠️ 关键认知：要「接收」群消息，必须用企业自建应用 / 企业内部应用（App ID+Secret / AppKey+Secret）走长连接 / Stream 模式。自定义机器人 Webhook 是单向的（只能发不能收），不能用于对接本插件。

① 在开放平台创建应用并配置（15 分钟）
② 把机器人拉进目标群
③ 在 DSH 设置页填入凭证并启用
④ 群里 @机器人 验证

飞书对接流程

第 1 步：创建企业自建应用

1. 打开 飞书开放平台 → 右上角「创建企业自建应用」（需登录飞书账号）。
2. 填写应用名称（如「DSH 助手」）、图标、描述 → 创建。
3. 进入应用后台，左侧 凭证与基础信息 → 记下 App ID（cli_ 开头）和 App Secret（页面会要求先重置/确认一次）。

第 2 步：添加机器人能力

4. 左侧 应用功能 → 机器人 → 开启机器人能力 → 设置机器人名称、头像 → 保存。

第 3 步：开通权限并发布版本

5. 左侧 权限管理 → 开通以下权限（搜索后「批量开通」）：
   • im:message（获取与发送单聊、群组消息）
   • im:message:readonly（读取单聊、群组消息——事件里携带消息内容必需）
   • im:chat:readonly（获取群组信息，建议一并开通）
6. 左侧 版本管理与发布 → 创建版本 → 填写版本说明 → 申请发布（需要企业管理员在管理后台同意，通常几分钟到几小时）。

第 4 步：配置事件订阅（长连接）

7. 左侧 事件与回调 → 事件订阅：
   • 添加事件：搜索 接收消息（im.message.receive_v1）→ 添加。
   • 订阅方式选择 「使用长连接接收事件」（WebSocket）——不要选需要回调 URL 的方式。
8. 保存后确认页面提示「长连接」已生效（此模式下平台会主动推送，无需公网 URL）。

第 5 步：把机器人拉进目标群

9. 打开飞书群聊 → 右上角设置（…）→ 群机器人 → 添加机器人 → 在列表中选择你的应用机器人（若找不到，确认第 3 步的版本已发布成功）。

第 6 步：DSH 设置页配置并验证

10. 打开 DSH 设置页 → 「IM 机器人」卡片 → 飞书 Tab：
    • 启用：打开
    • App ID：填第 1 步的 App ID
    • App Secret：填第 1 步的 App Secret
    • （其余保持默认）→ 保存
11. 查看 dsh 终端日志，应出现 [imbot] 已启用平台: 飞书 和 [imbot] 飞书长连接已建立，等待群消息（@机器人 触发）。
12. 在群里 @机器人 发消息（如 帮我查一下今天的天气）：
    • 正常：先收到「⏳ 已收到，agent 处理中…」，agent 处理完收到最终回复。

钉钉对接流程

第 1 步：创建企业内部应用

1. 打开 钉钉开放平台 → 开发者后台 → 应用开发 → 企业内部应用 → 创建应用。
2. 填写应用名称（如「DSH 助手」）、描述 → 创建。
3. 进入应用详情 → 凭证与基础信息 → 记下 AppKey（ding 开头）和 AppSecret。

第 2 步：添加机器人（Stream 模式）

4. 左侧 应用能力 → 机器人 → 创建机器人：
   • 机器人名称、头像自定义；
   • 接收消息模式 选择 「Stream 模式」（出站长连接，无需公网回调 URL）→ 保存。
5. （Stream 模式的机器人上线后会自动建立长连接通道。）

第 3 步：申请权限并发布

6. 左侧 权限管理 → 申请以下权限：
   • robot:groupMessages（群消息发送）
   • robot:OTO（企业内单聊消息发送）
7. 左侧 版本管理与发布 → 发布版本（企业内部应用发布后生效；若企业开启了权限审批，需管理员同意）。

第 4 步：把机器人拉进目标群

8. 打开钉钉群聊 → 群设置 → 机器人 → 添加机器人 → 选择你的应用机器人（若找不到，确认第 3 步发布完成且你在应用「可用范围」内）。

第 5 步：DSH 设置页配置并验证

9. 打开 DSH 设置页 → 「IM 机器人」卡片 → 钉钉 Tab：
   • 启用：打开
   • AppKey：填第 1 步的 AppKey
   • AppSecret：填第 1 步的 AppSecret
   • （其余保持默认）→ 保存
10. 查看 dsh 终端日志，应出现 [imbot] 已启用平台: 钉钉 和 [imbot] 钉钉 Stream 已连接（自动重连开启），等待群消息（@机器人 触发）。
11. 在群里 @机器人 发消息：正常流程同上（⏳ 处理中 → 最终回复）。

---

飞书 vs 钉钉：不同点

维度	飞书	钉钉
应用类型	企业自建应用	企业内部应用
凭证	App ID（cli_）+ App Secret	AppKey（ding）+ AppSecret
接收方式	事件订阅长连接（WebSocket）	机器人 Stream Mode（WebSocket）
事件/消息订阅	im.message.receive_v1	TOPIC_ROBOT（/v1.0/im/bot/messages/get）
发送 API	SDK channel.send	开放平台 robot/groupMessages、robot/oToMessages
交互方式	交互卡片（开箱即用）	纯文本（会话/工作区/归档均为文本编号列表）
@机器人 响应	需在设置开启「仅 @机器人 时响应」；群聊默认开启	钉钉群聊天然仅上行 @机器人 的消息
回调（点击卡片）	长连接内 cardAction 事件	TOPIC_CARD（/v1.0/card/instances/callback）
需要公网	否（长连接出站）	否（Stream 出站）
飞书消息示例	@机器人 在 /path 帮我…	同上

交互差异说明

• 飞书：工作区、会话、归档 命令发交互卡片（点按钮切换/归档）；会话 卡片按工作区分组，点会话即切换。
• 钉钉：同样命令走文本——工作区 列出编号（发 工作区 N 切换）、会话 列出编号（发 会话 N 切换）、归档本会话 归档当前段。钉钉交互卡片需要开发者后台配置卡片模板，本插件以文本为主保证开箱即用。
• 帮助：@机器人 帮助 按平台显示对应说明。

---

配置说明

Tab	字段	说明
飞书	启用	打开后建立飞书长连接
飞书	App ID / App Secret	飞书企业自建应用凭证（必填，见对接流程）
飞书	仅 @机器人 时响应	群聊默认开启；关闭则群内所有消息都会进入 agent（建议保持开启）
飞书	Agent 预设	创建会话用的预设，默认 standard（可用 code / cordis / minimal 等）
钉钉	启用	打开后建立钉钉 Stream 连接
钉钉	AppKey / AppSecret	钉钉企业内部应用凭证（必填，见对接流程）
钉钉	仅 @机器人 时响应	钉钉群聊天然仅 @机器人 的消息会上行，默认开启
钉钉	Agent 预设	创建会话用的预设，默认 standard

（设置持久化到命名空间 imbot。保存后自动生效，无需重启 dsh web。App Secret / AppSecret 字段为密码形式（输入时打点），点旁边的 👁 按钮可预览明文。）

---

使用

在群里 @机器人 并发送消息，例如：

@机器人 帮我查一下今天的天气

机器人会先回复「⏳ 已收到，agent 处理中…」（含工作区 / 会话段号 / 已聊轮次），agent 完成回合后把结果发回群里。同一群内同一工作区的后续消息会自动延续同一段对话上下文。

工作区

使用前必须选择或创建工作区（没有默认工作区）：

• 工作区 → 飞书：卡片点选 / 浏览本机目录；钉钉：文本编号列表，发 工作区 N 切换
• 用 <名字> 任务 → 用已注册的工作区（名字 = 标题或目录名）
• 在 /路径 任务 → 指定目录（不存在自动创建 + 注册）
• 新会话 在 /路径 → 切换工作区 + 开新会话

例：@机器人 在 /Users/me/myproj 帮我初始化项目

会话

• 会话 / 会话列表 → 飞书：按工作区分组卡片（点会话切换）；钉钉：文本编号列表（发 会话 N 切换）
• 全局会话 → 只看运行中的会话（按工作区分组，显示首条任务名）
• 新会话 → 同工作区开全新一段（旧段保留，不归档）
• 状态 → 查看当前工作区与会话

归档

• 归档本会话 → 归档当前段 + 清空本聊天选择，需重新选工作区
• 归档 → 飞书：卡片（点某段即归档）；钉钉：文本列表（归档本会话 归档当前段）
• 会话在 DSH GUI 里归档后，群里再下任务会自动开新会话（不继续用已归档会话）；点卡片切到已归档会话会提示无法恢复

---

原理

飞书群 ──(事件订阅长连接/WebSocket)──► createLarkChannel(transport:'websocket')
钉钉群 ──(Stream Mode/WebSocket)──────► dingtalk-stream DWClient(TOPIC_ROBOT)
                                           │ 归一化消息 { chatId, text, kind }
                                           ▼
                                     本插件 (Host)
                                           │ agents.create / resume / followup / whenIdle
                                           ▼
                                     DSH agent 会话
                                      （每群一个，会话 id 稳定复用）
                                           │ assistant/message 事件收集回复
                                           ▼
            飞书：channel.send(chatId, { text })  ──► 群
            钉钉：robot/groupMessages|oToMessages/send API ──► 群

---

故障排查

日志以 [imbot] 前缀输出在 dsh 宿主日志中（运行 dsh web 的终端）。

设置页没有「IM 机器人」卡片

• 确认 dsh-imbot 已在 profile 的 dsh.profile.bundles 列表，并重启过 dsh web。

配置保存了但日志没有「已启用平台」

• 检查所选平台 Tab 的 启用 是否打开、凭证是否已填（飞书 App ID/App Secret，钉钉 AppKey/AppSecret）。缺凭证时日志会提示「未启用或缺少凭证」。

日志有「启动失败 / 长连接错误」

• 凭证错误：核对 App ID/Secret（飞书）或 AppKey/AppSecret（钉钉）是否抄对。
• 飞书：确认应用已发布版本、事件订阅是长连接模式、im.message.receive_v1 已添加。
• 钉钉：确认机器人是 Stream 模式、应用已发布。

连接正常但 @机器人 没反应

• 确认机器人已在群里（群设置 → 机器人里能看到它）。
• 确认消息**@了机器人**（仅 @机器人 时响应 开启时，未 @ 的消息不会触发）。
• 飞书：确认事件订阅是长连接（Webhook 回调方式收不到）。
• 钉钉：确认 Stream 连接建立（日志「钉钉 Stream 已连接」）；钉钉群聊天然只上行 @机器人 的消息。

收到「⏳ 处理中」但最终回复失败

• 发送权限缺失：飞书 im:message、钉钉 robot:groupMessages（群）/ robot:OTO（单聊）——确认已开通并发布。

---

Roadmap

• 长任务期间流式输出（飞书卡片 / 钉钉卡片）
• 同一会话在双平台间共享上下文

License

MIT