钉钉机器人通道 838997125/dsh-plugin-dingtalk

dsh-plugin-dingtalk

🤖 DeepSeek Harness 钉钉机器人通道插件 — 在钉钉中与 DSH Agent 对话，支持多轮对话、工具调用、Markdown 渲染。

✨ 功能特性

- 🔌 Stream 模式：无需公网 IP / 域名 / 端口映射，机器人主动连接钉钉网关
- 💬 多轮对话：每个钉钉会话映射到独立 DSH Agent，保留完整上下文
- 🛠️ 工具调用：Agent 可在对话中调用所有 DSH 工具（终端、文件、MCP、浏览器等）
- 📝 Markdown 渲染：回复自动转为钉钉 Markdown 格式，标题、代码块、列表、链接等完美渲染
- 👥 群聊 @响应：群聊中 @机器人才响应，单聊直接对话
- 🔄 会话持久化：DSH 重启后自动恢复对话历史
- 🔌 自动重连：网络中断后指数退避自动重连
- ⏱️ 空闲回收：会话超时自动释放 Agent 资源

🏗️ 架构

钉钉用户发消息 │ ▼ 钉钉 Stream 网关 (WSS) │ ▼ dingtalk-stream SDK（自动心跳 / ACK / 重连） │ ▼ dsh-plugin-dingtalk（消息解析 · @提及判断 · Markdown 格式化） │ ▼ SessionBridge（钉钉 conversationId ↔ DSH Agent 映射） │ ├── agent.followup(message) ├── await agent.whenIdle() └── 读取 assistant/message 事件 │ ▼ sessionWebhook → 钉钉回复（Markdown 渲染）

📦 安装

前置条件

- DeepSeek Harness (DSH) Desktop 或 CLI
- Node.js >= 18
- 一个钉钉企业内部应用（已添加机器人能力并选择 Stream 模式）

安装插件

在 DSH 中运行：

dsh plugin --profile desktop add dsh-plugin-dingtalk

或手动安装：

cd ~/.dsh/profiles/desktop
pnpm add dsh-plugin-dingtalk

然后在 package.json 的 dsh.profile.bundles 数组中添加 "dsh-plugin-dingtalk"。

⚙️ 配置

在 ~/.dsh/profiles/desktop/cordis.patch.yml 中添加：

- insert:
- id: dingtalk-bot
name: 'dsh-plugin-dingtalk'
config:
appKey: "dingxxxxxxxxxxxx" # 钉钉应用 AppKey（必填） appSecret: "你的AppSecret" # 钉钉应用 AppSecret（必填） robotCode: "dingxxxxxxxxxxxx" # 可选，默认等于 appKey requireMentionInGroup: true # 可选，群聊是否需要@机器人，默认 true idleTimeoutMs: 1800000 # 可选，会话空闲超时(ms)，默认30分钟 thinkingIndicator: true # 可选，群聊"正在思考…"提示，默认 true

也可以通过环境变量配置：

export DINGTALK_APP_KEY="dingxxxxxxxxxxxx"
export DINGTALK_APP_SECRET="你的AppSecret"

🚀 钉钉应用设置

1. 打开钉钉开发者后台，创建企业内部应用
2. 进入「应用能力」→ 添加「机器人」能力
3. 机器人消息接收模式选择 Stream 模式
4. 发布应用并安装到企业
5. 记录 AppKey 和 AppSecret
6. 重启 DSH，日志中出现 ✅ 钉钉机器人已连接 即成功

💬 使用

- 单聊：在钉钉中搜索机器人名称，直接发消息
- 群聊：将机器人加入群聊，@机器人 + 消息内容

🔧 配置项

| 配置项 | 类型 | 默认值 | 说明 |
| appKey | string | $DINGTALK_APP_KEY | 钉钉应用 AppKey（必填） |
| appSecret | string | $DINGTALK_APP_SECRET | 钉钉应用 AppSecret（必填） |
| robotCode | string | 同 appKey | 机器人编码 |
| requireMentionInGroup | boolean | true | 群聊是否需要 @机器人 |
| idleTimeoutMs | number | 1800000 | 会话空闲超时（毫秒） |
| thinkingIndicator | boolean | true | 群聊思考提示 |
| presetId | string | 'standard' | Agent preset，决定可用的工具和 skill 列表。standard 包含完整的文件编辑、Shell、Skills、子代理等能力；设为 minimal/code/cordis 可切换为精简模式 |

🐛 常见问题

机器人不回复？
- 确认应用已发布并安装
- 确认机器人选择了 Stream 模式（不是 HTTP 模式）
- 检查 DSH 日志是否有 ✅ 钉钉机器人已连接
- 群聊中需要 @机器人（requireMentionInGroup 为 true 时）

Node.js 25 连接成功但收不到消息？
- 本插件已修复此问题：在导入 dingtalk-stream 前强制将 ws 包设为全局 WebSocket
- 如果自行集成，需确保 globalThis.WebSocket = require('ws')

钉钉机器人找不到 skill？
- 本插件默认挂载 standard agent preset，该 preset 包含 skill-filesystem 和 tool-skill，可自动发现 ~/.agents/skills/ 下的所有 skill
- 可通过 presetId 配置项切换 preset（如 minimal/code/cordis）
- 注意：DSH 的 dsh-web-app bundle 在 host 层面禁用了 skill-filesystem/tool-skill，必须通过 agent preset 挂载才能使用 skill 系统

📁 项目结构

dsh-plugin-dingtalk/
├── lib/
│ ├── index.js # 插件入口：SDK 启动、消息路由、@提及判断 │ ├── session-bridge.js # 会话桥接：钉钉 ↔ DSH Agent 多轮对话 │ └── dingtalk-api.js # API 辅助：sessionWebhook 回复 + Markdown 格式化 ├── cordis.patch.yml # DSH bundle 注册 ├── package.json ├── LICENSE └── README.md

📄 License

MIT

Features

- Stream Mode: No public IP/domain/port required — bot connects outbound to DingTalk gateway
- Multi-turn Chat: Each DingTalk conversation maps to a dedicated DSH Agent with full context
- Tool Calling: Agent can invoke all DSH tools (terminal, files, MCP, browser, etc.)
- Markdown Rendering: Replies are automatically formatted as DingTalk Markdown
- Group @mention: Responds only when @mentioned in groups; direct chats work instantly
- Session Persistence: Conversation history survives DSH restarts
- Auto-reconnect: Exponential backoff reconnection on network failures
- Idle Cleanup: Agents are disposed after configurable idle timeout

Install

dsh plugin --profile desktop add dsh-plugin-dingtalk

Quick Start

1. Create an enterprise internal app on DingTalk Open Platform
2. Add the Robot capability, set message receiving mode to Stream
3. Publish and install the app
4. Configure appKey and appSecret in cordis.patch.yml
5. Restart DSH — look for ✅ 钉钉机器人已连接 in logs
6. Message the bot on DingTalk!

License

MIT