核心用法
ding-skills 是面向企业钉钉生态的完整自动化技能集，通过 Python 脚本封装钉钉开放平台 API，实现三大核心能力：
1. 组织人事管理
- 用户查询：支持按姓名、手机号、unionId 多维度检索，返回 userId 及完整档案
- 部门架构：部门搜索、层级遍历、成员列表获取，根部门 deptId 固定为 1
- 人员统计：在职/离职人数统计、未登录用户筛选、离职记录追溯
2. 沟通协作
- 智能消息：机器人单聊/群聊消息推送，robotCode 自动从环境变量读取
- 视频会议：即时创建或预约会议，自动同步钉钉日历，支持参会人管理
- 日程管理：查询、创建、删除日程，动态增减参与者
3. OA 审批
- 全流程覆盖：发起、审批（同意/拒绝/转交）、撤销、评论
- 多维查询：待办、已办、抄送、我发起的审批实例筛选
- 表单支持：自定义表单字段 JSON 提交
关键工作流约束
> 钉钉 API 存在 userId（企业内）与 unionId（全局）双标识体系。用户说人名时必须先调 search_user 获取 userId；会议/日程类 API 需额外调 get_user 转为 unionId。
显著优点
- 功能完备：38 个独立脚本覆盖钉钉核心 API，企业高频场景一站式解决
- 编排清晰：显式定义人名→ID 转换的工作流，降低多步骤任务出错率
- 环境隔离：敏感配置（appKey/appSecret/robotCode）全部外置环境变量
- 输出标准化：所有脚本统一 JSON 返回格式，含 success 标志与结构化数据
潜在缺点与局限性
| 维度 | 说明 |
|------|------|
| **前置成本** | 必须预先在钉钉开放平台创建应用，配置 IP 白名单、申请 API 权限，非即开即用 |
| **权限依赖** | 部分接口（如离职数据、全量用户列表）需管理员级 scope，普通员工应用无法调用 |
| **标识转换繁琐** | userId/unionId 双体系导致多步骤调用，并行查询多人时需处理异步或批处理逻辑 |
| **机器人限制** | 消息发送依赖特定机器人身份，群消息需已知 openConversationId，无法直接按群名发送 |
| **无沙箱模式** | 文档未提及测试环境或模拟数据机制，调试直接操作真实企业数据 |
适合人群
- 企业 IT 管理员：批量查询组织架构、导出人员报表
- 行政/HR 专员：代预约会议、群发通知、审批催办
- 开发者/集成工程师：作为钉钉 API 的中间层封装，嵌入更大自动化流程
常规风险
- 数据泄露风险：search_user 返回的 userId 及 get_user 返回的手机号（即使脱敏）需妥善存储
- 越权操作风险：机器人可代发消息、代审批，需严格控制 DINGTALK_ROBOT_CODE 的访问范围
- API 限流风险：部门用户列表等接口未实现内置限流保护，大数据量遍历可能触发钉钉流控
- 凭证泄露风险：appSecret 硬编码或日志打印会导致企业级安全事件
安全认证说明
> 附注：当前安全认证报告为系统占位文本，未执行实际安全扫描。生产环境部署前建议进行依赖审计（requirements.txt）、静态代码扫描及最小权限原则配置验证。