pi-dingtalkbot

钉钉智能机器人 Stream 长连接扩展 for pi

使用钉钉官方 dingtalk-stream SDK 实现。

功能特性

• 🔗 Stream 长连接 - 自动重连，断线无忧
• 🤖 多机器人支持 - 支持配置多个机器人，快速切换
• 🏠 全局配置共享 - 机器人列表全局共享，所有会话可见
• 🎯 会话独立选择 - 每个会话独立选择启用哪个机器人
• 👥 多人会话管理 - 按 messageId 区分不同用户
• 🔄 消息自动转发 - 收到 @机器人 的消息自动处理
• 📤 回复自动发送 - AI 回复自动发送到钉钉

安装

通过 npm（推荐）

pi install npm:pi-dingtalkbot

通过 Git

pi install git:github.com/huang-x-h/pi-dingtalkbot

本地开发

pi install ./D:/codebase/github/pi-dingtalkbot

快速开始

1. 获取钉钉机器人凭证

1. 登录 钉钉开发者后台
2. 创建企业内部应用
3. 在应用功能中添加机器人能力
4. 选择 Stream 模式 并发布
5. 在应用详情获取：
   • ClientID（即 AppKey）
   • ClientSecret（即 AppSecret）

2. 添加机器人（全局配置）

/dingtalkbot-add
# 机器人名称(可选): 我的助手
# ClientID (AppKey): dingxxxxxxxxxxxxxxxx
# ClientSecret (AppSecret): xxxxxxxxxxxxxxx

添加后所有会话都能看到这个机器人

3. 查看机器人列表（全局）

/dingtalkbot-list

输出示例：
全局机器人列表（共 2 个）：
▶ ✅ 我的助手...  ← ▶ 表示本会话正在使用
○ 测试助手...
本会话启用: 我的助手...

4. 选择本会话使用的机器人

/dingtalkbot-use
# 选择机器人（仅本会话）: 测试助手

✅ 本会话已切换到 测试助手...

配置参数说明

钉钉 Stream 模式只需要两个核心参数：

| 参数 | 说明 | 获取位置 | |------|------|----------| | ClientID | 即 AppKey，应用的唯一标识 | 钉钉开发者后台 → 应用详情 | | ClientSecret | 即 AppSecret，应用的密钥 | 钉钉开发者后台 → 应用详情 |

⚠️ 注意：需要在应用中开通"机器人"能力，并选择 Stream 模式 发布后才能使用。

完整命令说明

全局配置命令

/dingtalkbot-add - 添加机器人（全局）

添加机器人到全局配置，所有会话都能使用。

/dingtalkbot-add
  机器人名称(可选): 工作助手
  ClientID (AppKey): dingxxxxxxxxxxxxx
  ClientSecret (AppSecret): xxxxxxxxxxxxxxx

✅ 已添加 工作助手...（全局配置）

/dingtalkbot-list - 列出机器人（全局）

显示全局机器人列表，带本会话启用标记：

• ▶ - 本会话正在使用的机器人
• ○ - 其他机器人
• ✅ - 当前已连接

/dingtalkbot-remove - 删除机器人（全局）

从全局配置删除机器人，所有会话都将失去该机器人。

会话配置命令

/dingtalkbot-use - 切换机器人（本会话）

选择本会话使用哪个机器人，不影响其他会话。

/dingtalkbot-enable - 启用机器人（本会话）

启用本会话的机器人连接。

/dingtalkbot-disable - 禁用机器人（本会话）

禁用本会话的机器人连接，不影响其他会话。

/dingtalkbot-status - 查看状态

显示混合信息：全局机器人数量 + 本会话详细状态。

✅ 工作助手...
状态: 已连接
ClientID: dingxxxxxxxxxxxxx
全局机器人: 3 个
本会话活跃会话: 2 个
会话ID: abc12345

/dingtalkbot-session-info - 会话信息

显示本会话的配置详情。

Tools

dingtalkbot-send

发送消息到钉钉。

{
  message: string;      // 要发送的消息内容
  format?: "text" | "markdown";  // 消息格式，默认 text
}

示例：

使用 dingtalkbot-send 发送消息 "你好" 到钉钉
使用 dingtalkbot-send 发送 markdown 格式消息 "# 标题\n这是内容" 到钉钉

dingtalkbot-attach

发送文件列表到钉钉（钉钉机器人不支持直接发送文件附件，将转为消息列表形式通知）。

{
  paths: string[];  // 文件路径列表（最多10个）
}

示例：

使用 dingtalkbot-attach 发送文件 "D:/documents/report.pdf"
使用 dingtalkbot-attach 发送多个文件 ["file1.txt", "file2.txt"]

⚠️ 重要限制

同一机器人（ClientID）只能在一个会话中连接

钉钉官方限制：同一个 ClientID 同时只能有一个 Stream 连接。

冲突场景

Session A (已连接工作助手)     Session B
├─ 状态: ✅ 工作助手            ├─ 执行 /dingtalkbot-use 工作助手
├─ 运行中                      ├─ 连接成功
│                              │
│  ◄──── 被踢掉 ──────────────┤
│
└─ 状态: ❌ 被其他会话连接      └─ 状态: ✅ 工作助手

解决方式

1. 不同会话使用不同机器人（推荐）

   • Session A: 工作助手 (ClientID-A)
   • Session B: 个人助手 (ClientID-B)

2. 手动切换

   • 在 Session A 执行 /dingtalkbot-disable 断开
   • 在 Session B 执行 /dingtalkbot-enable 连接

配置存储

| 类型 | 路径 | 内容 | 共享方式 | |------|------|------|---------| | 全局配置 | ~/.pi/agent/dingtalk-bot/config.json | 机器人列表 (clientId, clientSecret, name) | 所有会话共享 | | 会话配置 | ~/.pi/agent/dingtalk-bot/sessions/{sessionId}.json | activeBotId, enabled | 仅本会话 | | 临时文件 | ~/.pi/agent/dingtalk-bot/tmp/{id}/ | 上传文件等 | 仅本会话 |

工作原理

┌─────────────────────────────────────────────────────────────┐
│                         pi 会话 A                            │
│  ┌─────────────────┐        ┌─────────────────────────────┐ │
│  │  全局配置加载    │◄───────│  ~/.pi/agent/dingtalk-bot.json│ │
│  │  bots: [...]    │        │  机器人列表（共享）          │ │
│  └─────────────────┘        └─────────────────────────────┘ │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐        ┌─────────────────────────────┐ │
│  │  会话配置加载    │◄───────│ dingtalk-bot-session-A.json   │ │
│  │  activeBotId    │        │  activeBotId, enabled       │ │
│  │  enabled        │        │  （本会话独立）              │ │
│  └─────────────────┘        └─────────────────────────────┘ │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐                                       │
│  │   DWClient      │◄──────────────┐                       │
│  │   Stream 连接    │               │                       │
│  └─────────────────┘               │                       │
│           │                        │                       │
│           ▼                        │                       │
│  ┌─────────────────┐               │                       │
│  │   钉钉           │◄──────────────┘                       │
│  │   Stream 网关    │                                      │
│  └─────────────────┘                                       │
│                                                              │
│  回复消息:                                                   │
│  ┌─────────────────┐                                       │
│  │   HTTP API      │────────► 钉钉服务器                   │
│  │   sessionWebhook │     (通过消息中的 webhook 地址)       │
│  └─────────────────┘                                       │
└─────────────────────────────────────────────────────────────┘

参考

• 钉钉智能机器人开发文档
• 钉钉消息接口文档
• Stream 模式介绍
• dingtalk-stream SDK

License

MIT