Dingtalk Bot Publish

调用钉钉开放平台API，支持用户搜索/详情/查询、部门管理（搜索/详情/子部门/用户列表/父部门）、机器人单聊消息发送、群聊消息发送、群内机器人列表查询、Stream模式事件推送、多会话隔离管理等核心功能。Use when needing to search DingTalk users or departmen...

Security Scan

The code and runtime instructions match a DingTalk integration, but the skill metadata and install/dependency declarations are inconsistent with the files and SKILL.md (missing declared credentials, mismatched dependencies and script names), so review and fixes are needed before trusting it.

Purpose & Capability

The name/description and the included scripts clearly implement DingTalk/OpenAPI features (user/department management, robot messages, Stream mode). The requested capabilities (accessing DingTalk APIs using AppKey/AppSecret) are coherent with the stated purpose.

Instruction Scope

SKILL.md and the scripts instruct the agent to read DINGTALK_APP_KEY / DINGTALK_APP_SECRET, call oapi.dingtalk.com (DingTalk), and optionally run a Stream bridge locally. The instructions are scoped to DingTalk integration and do not instruct reading unrelated system secrets or exfiltrating data to unexpected endpoints.

Install Mechanism

This is instruction-only (no platform install spec) which reduces risk, but package.json lists only axios and ws while many scripts import @alicloud/dingtalk, @alicloud/openapi-client and other alicloud SDK packages that are not declared—this mismatch will break installation and suggests sloppy packaging. SKILL.md also references pip package dingtalk-stream and a startup script name (start_dingtalk_stream.sh) that does not exactly match included script filenames, another mismatch. These inconsistencies are not evidence of malware but increase operational risk and require manual verification.

Credentials

The skill needs DingTalk credentials (DINGTALK_APP_KEY and DINGTALK_APP_SECRET) according to SKILL.md and multiple scripts (they read process.env.*). However the skill registry metadata declared no required env vars and no primary credential—this is an explicit metadata omission/inconsistency. The requested secrets themselves are proportionate to the purpose, but the metadata failing to declare them is a red flag for deploy-time surprises.

Persistence & Privilege

The skill does not request always:true, does not ask to modify other skills, and has no install spec that would write arbitrary binaries. It may persist session memory to a local memory/ directory at runtime per SKILL.md, which is normal for session management but should be considered by operators (ensure the memory path is acceptable).

What to consider before installing

What to check before installing or running this skill: 1) Credentials: SKILL.md (and scripts) require DINGTALK_APP_KEY and DINGTALK_APP_SECRET. The registry metadata does NOT declare these—don't run the skill until you set these in a secure vault or environment and understand where they will be used. 2) Dependencies: package.json only lists axios and ws, but the TypeScript scripts import @alicloud/dingtalk, @alicloud/openapi-client, @alicloud/tea-util, etc. Verify and install the missing SDK packages before running. This mismatch is likely an oversight but will break execution. 3) Script names and Stream setup: SKILL.md references a start script name and pip package names that don't exactly match included filenames. Inspect scripts/start-stream.sh, stream-bridge.py, and any start/stop shells to confirm what will execute, and run them in an isolated environment first (container or VM). 4) Network reachability & endpoints: Code calls oapi.dingtalk.com (expected). Confirm your environment permits outbound HTTPS to DingTalk and that you are comfortable granting the AppKey/AppSecret the requested DingTalk scopes. 5) Secrets handling & logs: Scripts print debug info and may log full API responses to stderr when --debug is used. Avoid running with debug enabled in production and ensure logs do not leak secrets. 6) Data persistence: Session memory is stored under a memory/ directory by default. If this contains sensitive conversation history, secure or relocate it and review retention/cleanup behavior. 7) Minimal privilege: When creating the DingTalk app, grant only the minimal scopes needed. Test in a non-production tenant first. 8) If you want higher confidence: ask the author for a corrected package.json and updated registry metadata declaring required env vars; run the code in an isolated environment and perform a dependency audit (npm list / npm audit) before granting credentials.

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连接失败

最佳实践

1. 权限最小化：只申请必要的API权限
2. 错误处理：始终检查API响应的errcode
3. 调试模式：使用--debug参数查看详细请求/响应
4. 批量操作：对于大量数据，使用批量API接口
5. Stream模式优先：实时交互场景优先使用Stream模式
6. 会话隔离：确保不同用户的对话上下文完全隔离
7. 频率控制：遵守钉钉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               # 依赖配置