modbender DingTalk API Skill
用于调用钉钉开放平台 API 的技能，提供完整的钉钉企业级集成功能，包括传统API调用和Stream模式事件推送。
核心功能模块
用户与组织管理
- 用户搜索、详情查询、手机号/unionid查询
- 部门管理（搜索、详情、子部门、用户列表、父部门）
- 企业员工统计、组织架构映射
- 离职记录查询、未登录用户列表
消息与机器人
- 机器人单聊消息发送
- 机器人群聊消息发送
- 群内机器人列表查询
- 消息内容格式化与发送
Stream模式事件推送（推荐）
- 实时消息接收：通过WebSocket长连接接收钉钉事件
- 多会话隔离：为每个用户/群聊成员创建独立的AI会话
- 上下文保持：每个会话保持完整的对话历史和个性化记忆
- 自动回复路由：AI生成的回复直接通过钉钉API发送，避免多通道冲突
OA审批管理
- 审批实例查询、详情获取
- 发起、终止、执行、转交审批任务
- 审批评论管理、待办数量统计
API版本支持
传统服务端API (兼容)
- 用户管理：用户查询、部门管理
- 消息发送：机器人消息
- 特点：稳定可靠、广泛使用、向后兼容
Stream模式API (推荐)
- 事件推送：实时接收钉钉消息和事件
- 长连接：基于WebSocket的持久连接
- 高并发：支持大量用户同时对话
- 低延迟：消息处理延迟毫秒级
权限说明
企业内部应用
- 支持所有功能：用户管理、消息、Stream模式、OA审批
- 权限配置：在钉钉开发者后台申请相应权限
- 认证方式：使用AppKey/AppSecret获取access_token
- Stream配置：需在开发者后台配置事件订阅和回调URL
第三方企业应用
- 部分功能支持：用户管理、消息
- 认证方式：OAuth2.0授权流程
- Stream模式：不支持
第三方个人应用
- 功能受限：仅支持基础用户查询
- 不支持：消息发送、Stream模式
前置要求
传统API模式
- 已设置环境变量
DINGTALK_APP_KEY和DINGTALK_APP_SECRET - 钉钉应用已创建并拥有相应 API 权限
- 对于企业内部应用，确保在钉钉管理后台已授权所需权限
Stream模式（推荐）
- 企业内部应用（必须）
- 公网可访问的HTTPS服务器（用于事件回调）
- 钉钉开发者后台已配置Stream模式事件订阅
- Python 3.8+ 环境（用于运行Stream Bridge）
环境变量配置
# 传统API和Stream模式都需要
export DINGTALK_APP_KEY="<your-app-key>"
export DINGTALK_APP_SECRET="<your-app-secret>"
# Stream模式额外配置（可选）
export DINGTALK_STREAM_LOG_LEVEL="INFO"
export DINGTALK_SESSION_MEMORY_DIR="./memory"
使用示例
1. 传统API调用
查询用户详情
npx ts-node scripts/get-user.ts "<userId>" [--debug]
发送单聊消息
npx ts-node scripts/send-user-message.ts "<userId>" "<robotCode>" "<消息内容>" [--debug]
获取部门用户列表
npx ts-node scripts/list-department-users.ts "<deptId>" [--debug]
搜索用户
npx ts-node scripts/search-user.ts "<keyword>" [--debug]
2. Stream模式部署（推荐）
启动Stream Bridge
# 创建虚拟环境
python3 -m venv dingtalk_venv
source dingtalk_venv/bin/activate
pip install dingtalk-stream
# 启动Stream服务
./start_dingtalk_stream.sh
会话管理特性
- 私聊会话：
dingtalk_private_{user_id}- 每个用户独立会话 - 群聊会话：
dingtalk_group_{group_id}_{user_id}- 群聊中每个用户独立会话 - 记忆持久化：会话记忆保存在
memory/目录下 - 自动清理：24小时无活动的会话自动清理
错误处理
所有脚本在错误时返回统一格式：
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "错误描述"
}
}
常见错误码：
MISSING_CREDENTIALS- 未设置环境变量INVALID_ARGUMENTS- 参数不足AUTH_FAILED- access_token 获取失败PERMISSION_DENIED- 权限不足UNKNOWN_ERROR- API 调用异常STREAM_CONNECTION_FAILED- Stream连接失败
最佳实践
- 权限最小化：只申请必要的API权限
- 错误处理：始终检查API响应的errcode
- 调试模式：使用
--debug参数查看详细请求/响应 - 批量操作：对于大量数据，使用批量API接口
- Stream模式优先：实时交互场景优先使用Stream模式
- 会话隔离：确保不同用户的对话上下文完全隔离
- 频率控制：遵守钉钉API调用频率限制
安全注意事项
- 不要在代码中硬编码AppKey/AppSecret
- 使用环境变量或安全的配置管理
- 敏感操作（如删除、修改）需要二次确认
- 遵循钉钉的安全最佳实践指南
- Stream模式安全：确保回调URL使用HTTPS，验证事件签名
- 数据隔离：不同用户的会话数据完全隔离，符合企业安全要求
架构优势
多会话隔离架构
- 用户识别：准确识别私聊和群聊中的不同用户
- 上下文保持：每个会话保持完整的对话历史
- 个性化记忆：支持用户偏好和历史记录的持久化
- 资源管理：自动清理过期会话，避免资源泄露
回复路由优化
- 通道隔离：钉钉回复只通过钉钉API，避免触发其他通道
- 性能优化：异步处理，支持高并发
- 可靠性：结果文件机制确保消息不丢失
- 错误恢复：网络错误自动重试，保证消息送达
项目结构
dingtalk-api/
├── scripts/ # 传统API脚本
│ ├── *.ts # 各类API调用脚本
├── stream/ # Stream模式相关文件
│ ├── dingtalk_stream_bridge.py # Stream Bridge主程序
│ ├── dingtalk_session_manager.py # 会话管理器
│ ├── dingtalk_reply_tool.py # 钉钉回复工具
│ └── *.sh # 启动/停止脚本
├── memory/ # 会话记忆文件（运行时生成）
├── types/ # TypeScript类型定义
├── SKILL.md # 技能文档
├── README.md # 详细使用说明
└── package.json # 依赖配置