dingtalk-calendar

name	dingtalk-calendar
description	当用户提到'日历'、'日程'、'会议'、'约会'、'日报'、'周报'、'待办'、'任务'、'todo'，或要求生成工作汇报、查看本周安排时使用此技能。管理钉钉日历事件和待办任务，辅助自动生成日报周报。
version	0.1.0
metadata	{"openclaw":{"emoji":"📅","requires":{"env":["DINGTALK_APP_KEY","DINGTALK_APP_SECRET"],"bins":["curl","jq"]},"primaryEnv":"DINGTALK_APP_KEY"}}

钉钉日历与待办技能

通过钉钉开放平台日历 API 和待办 API，管理日程事件和待办任务。常用于自动生成日报/周报。

获取 Access Token

钉钉新版 API（api.dingtalk.com）使用 Header 鉴权：

ACCESS_TOKEN=$(curl -s "https://oapi.dingtalk.com/gettoken?appkey=${DINGTALK_APP_KEY}&appsecret=${DINGTALK_APP_SECRET}" | jq -r '.access_token')

新版 API 调用时在 Header 中传入：x-acs-dingtalk-access-token: ${ACCESS_TOKEN}

日历操作

1. 查询日历事件列表

获取用户某时间段内的日程：

curl -s -X GET "https://api.dingtalk.com/v1.0/calendar/users/<userId>/calendars/primary/events?timeMin=2026-03-01T00:00:00%2B08:00&timeMax=2026-03-07T23:59:59%2B08:00&maxResults=50" \
  -H "x-acs-dingtalk-access-token: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" | jq '.events'

返回值关键字段：

• summary: 事件标题
• start.dateTime / end.dateTime: 开始/结束时间
• attendees: 参与人列表
• location: 地点
• isAllDay: 是否全天事件

2. 创建日历事件

curl -s -X POST "https://api.dingtalk.com/v1.0/calendar/users/<userId>/calendars/primary/events" \
  -H "x-acs-dingtalk-access-token: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "项目评审会",
    "start": {"dateTime": "2026-03-05T14:00:00+08:00", "timeZone": "Asia/Shanghai"},
    "end": {"dateTime": "2026-03-05T15:00:00+08:00", "timeZone": "Asia/Shanghai"},
    "attendees": [{"id": "<参与人userId>"}],
    "location": {"displayName": "3楼会议室A"},
    "description": "Q1项目进度评审"
  }'

待办操作

3. 查询用户待办列表

curl -s -X POST "https://api.dingtalk.com/v1.0/todo/users/<userId>/tasks/query?nextToken=&maxResults=50" \
  -H "x-acs-dingtalk-access-token: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "roleTypes": ["creator", "executor"]
  }' | jq '.todoCards'

返回值关键字段：

• subject: 任务标题
• status: TODO / DONE
• dueTime: 截止时间（毫秒时间戳）
• createdTime: 创建时间

4. 创建待办任务

curl -s -X POST "https://api.dingtalk.com/v1.0/todo/users/<userId>/tasks" \
  -H "x-acs-dingtalk-access-token: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "提交Q1项目报告",
    "dueTime": 1741363200000,
    "description": "包含预算使用情况和风险项",
    "executorIds": ["<负责人userId>"],
    "participantIds": ["<参与人userId>"]
  }'

5. 完成/更新待办

curl -s -X PUT "https://api.dingtalk.com/v1.0/todo/users/<userId>/tasks/<taskId>" \
  -H "x-acs-dingtalk-access-token: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"done": true}'

自动日报/周报生成工作流

1. 调用日历 API 获取本周所有事件 → 提取会议标题和参与人
2. 调用待办 API 获取已完成任务（status=DONE，本周创建或完成的）
3. 如有外部数据源（GitHub commits 等），一并采集
4. 将数据整理后交给 LLM 生成结构化周报，分为：
   • 本周完成：已完成的待办 + 已结束的会议
   • 进行中：未完成的待办
   • 下周计划：下周日历中的事件
5. 输出为 Markdown 格式，可选发送到群聊或创建为钉钉文档

注意事项

• 新版 API 路径以 api.dingtalk.com/v1.0/ 开头，鉴权在 Header
• 旧版 API 路径以 oapi.dingtalk.com/topapi/ 开头，鉴权在 query param
• 日历 API 的 userId 格式为钉钉用户 ID（非手机号）
• 时间戳统一使用毫秒级 Unix 时间或 ISO 8601 格式