钉钉日程技能
负责钉钉日历（Calendar）API 的操作。本文件为策略指南；完整请求格式见 references/api.md。
dt_helper.sh位于本SKILL.md同级目录的scripts/dt_helper.sh。
核心概念
- 路径中的
userId：日程 API 路径/v1.0/calendar/users/{userId}/...中的{userId}为 unionId（与待办、文档一致），不是 staffId。 - 主日历：个人默认日历的
calendarId固定使用字符串primary（小写）。创建/查询/列表/更新/删除均针对.../calendars/primary/events...。 - 时间格式：
start/end、闲忙的startTime/endTime、列表的timeMin/timeMax须使用 UTC ISO8601 且含毫秒，例如2026-03-24T07:02:48.000Z。省略毫秒易触发ParsedISO8601TimestampError。 - 修改日程：HTTP 方法为 PUT（与「部分更新」语义对应的路径相同），请求体需包含日程
id及要改的字段（如summary）。 - 视频会议：创建日程时在请求体中加
"onlineMeetingInfo":{"type":"dingtalk"}，响应含onlineMeetingInfo.url等。 - 会议室：先通过 会议室忙闲 接口按
roomIds+ 时间窗查询；再在已有日程上 添加会议室（需企业内会议室roomId，管理后台或开放平台可查）。集成测试可用环境变量TEST_MEETING_ROOM_IDS（逗号分隔）。 - 签到/签退：日程创建后，可 GET 签到/签退链接 分发参会人；组织者/参与者 POST 签到；详情用 GET signin / signOut 列表接口（见 api.md）。是否与线下会议、审批流联动以钉钉侧能力为准。
场景路由（先分类再调 API）
| 用户意图 | 优先接口方向 |
|---|---|
| 订会议室、查会议室有没有空 | POST .../meetingRooms/schedules/query |
| 给已有日程加会议室 | POST .../events/{eventId}/meetingRooms |
| 要签到码、签退链接 | GET .../signInLinks、GET .../signOutLinks |
| 每周重复、每天重复 | 创建日程时带 recurrence（见 api.md） |
| 只看人忙闲（不针对会议室） | POST .../querySchedule |
工作流程（每次执行前）
- 识别任务 → 按上表归类后，再选具体 API（见
references/api.md）。 - 校验配置 →
bash scripts/dt_helper.sh --get读取DINGTALK_APP_KEY、DINGTALK_APP_SECRET、DINGTALK_MY_USER_ID、DINGTALK_MY_OPERATOR_ID（缺 unionId 时--to-unionid）。 - 收集缺失项 → 一次性询问并
--set写入~/.dingtalk-skills/config。 - 获取新版 Token →
NEW_TOKEN=$(bash scripts/dt_helper.sh --token)，请求头x-acs-dingtalk-access-token。 - 执行 API → 多行逻辑写入
/tmp/<task>.sh再执行；禁止 heredoc。
按任务校验配置
- 通用必需：
DINGTALK_APP_KEY、DINGTALK_APP_SECRET、DINGTALK_MY_USER_ID；调用前需 unionId（DINGTALK_MY_OPERATOR_ID或通过--to-unionid生成）。
未通过校验前不得调用 API。凭证展示仅前 4 位 +
****。
所需配置
| 配置键 | 必填 | 说明 |
|---|---|---|
DINGTALK_APP_KEY | ✅ | Client ID（AppKey） |
DINGTALK_APP_SECRET | ✅ | Client Secret |
DINGTALK_MY_USER_ID | ✅ | 当前用户 userId（管理后台通讯录） |
DINGTALK_MY_OPERATOR_ID | ✅ | 当前用户 unionId（--to-unionid 可写入） |
身份标识说明
| 标识 | 说明 |
|---|---|
userId | 企业员工 ID，管理后台可见 |
unionId | 日程路径参数与 body 中的用户标识均使用 unionId |
userId → unionId：使用旧版 access_token 调 POST https://oapi.dingtalk.com/topapi/v2/user/get（见 references/api.md），取 result.unionid（无下划线）。
执行脚本模板
bash#!/bin/bash set -e HELPER="./scripts/dt_helper.sh" NEW_TOKEN=$(bash "$HELPER" --token) UNION_ID=$(bash "$HELPER" --get DINGTALK_MY_OPERATOR_ID) CAL_ID="primary" curl -s -X POST "https://api.dingtalk.com/v1.0/calendar/users/${UNION_ID}/calendars/${CAL_ID}/events" \ -H "x-acs-dingtalk-access-token: $NEW_TOKEN" \ -H "Content-Type: application/json" \ -d '{"summary":"周会","start":{"dateTime":"2026-03-25T02:00:00.000Z","timeZone":"UTC"},"end":{"dateTime":"2026-03-25T03:00:00.000Z","timeZone":"UTC"}}'
Token 异常时：
bash "$HELPER" --token --nocache
references/api.md 查阅索引
bashgrep -A 35 "^## 1. 创建日程" references/api.md grep -A 25 "^## 2. 查询单个日程" references/api.md grep -A 30 "^## 3. 查询日程列表" references/api.md grep -A 25 "^## 4. 更新日程" references/api.md grep -A 15 "^## 5. 删除日程" references/api.md grep -A 28 "^## 6. 查询闲忙" references/api.md grep -A 22 "^## 7. 视频会议" references/api.md grep -A 28 "^## 8. 查询会议室忙闲" references/api.md grep -A 25 "^## 9. 添加与移除会议室" references/api.md grep -A 18 "^## 10. 签到与签退链接" references/api.md grep -A 22 "^## 11. 签到与签退详情列表" references/api.md grep -A 18 "^## 12. 签到与签退操作" references/api.md grep -A 35 "^## 13. 循环日程" references/api.md grep -A 15 "^## 14. 订阅日历" references/api.md grep -A 15 "^## 错误码" references/api.md grep -A 18 "^## 所需应用权限" references/api.md
