dingtalk-calendar

DingTalk Calendar Skill

Prerequisites — Must Read Before Performing Operations

**CRITICAL — Before performing any dws operation, you MUST first use the Read tool to fully read dingtalk-shared.** This lightweight file contains the global execution contract, security bottom lines, and on-demand loading navigation for shared references; do not preload all of its references.

For common paths, execute directly according to this file; do not pre-read the large and comprehensive calendar.md. Only read the corresponding sections on demand when recurring schedules, responding to invitations, sharing/ACL, attachments, calendars, or low-frequency parameters cannot be located from this file; only for the scope of booking meeting rooms and failure containment should you read 03-meeting.md。

Shortcuts (preferred when there is no dedicated script/recipe)

The following shortcuts enter both the public catalog and the Runtime Schema. Route according to this skill/recipe; when matched, Shortcuts take precedence over atomic commands. For parameters, check only dws schema --cli-path "calendar +<shortcut>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json; when only and already published result is needed, check --jq '{cli_path,outcomes:.result.outcomes,pagination}', and for field-level details check data_schema; if missing, do not infer from Help/examples. Only when the Schema is unavailable, read the known leaf Help once;unknown flag use the same leaf Help to correct once.unknown command Help is prohibited: for erroneous suggestions → the already loaded Skill/reference specifies the entry point; if neither exists, report drift. Full Catalog/root/parent/product Help is prohibited; omit only for mapping, interface, or provenance auditing --compact. Only when neither existing routing nor references can locate a low-frequency capability, use dws shortcut list --service calendar --format json for discovery.

Shortcut	Risk	Applicable Scenarios
dws calendar +agenda	read	Query the schedule list (defaults to querying today if no time is passed)
dws calendar +attendee-list	read	View schedule attendees
dws calendar +book	write	Create a schedule and invite attendees by name (automatically resolve userId; automatically roll back and delete the schedule on failure)
dws calendar +book-list	read	Query a user's calendar list
dws calendar +book-search	read	Fuzzy search calendars by name
dws calendar +cancel-event	high-risk-write	Cancel (delete) an existing schedule (confirm it actually exists before deleting)
dws calendar +conflicts	read	Detect time conflicts in my schedule on a certain day (overlap/double booking, defaults to today)
dws calendar +free	read	Query a person's busy/free status within a specified time period by name (automatically resolve userId)
dws calendar +free-slots	read	Find my free time slots within working hours on a certain day (defaults to today 09:00-18:00)
dws calendar +freebusy	read	Query busy/free status of users / meeting rooms (at least one of --users and --rooms)
dws calendar +invite	write	Add attendees to an existing schedule by name (automatically resolve userId, then batch add)
dws calendar +my-free	read	Check my own busy/free status within a certain time period (defaults to today, no name input required)
dws calendar +next-event	read	View the nearest upcoming schedule (defaults to scanning the next 7 days)
dws calendar +reschedule	write	Change the time of an existing schedule (only moves the start/end time; other fields remain unchanged)
dws calendar +room-find	read	Search available meeting rooms by time period (defaults to 1 hour from the current time if no time is passed)
dws calendar +room-groups	read	Meeting room group list
dws calendar +room-search	read	Fuzzy search meeting rooms by name (does not check availability)
dws calendar +suggest-time	read	Resolve multiple participants by name and recommend meeting time slots when everyone is available (automatically resolve userId)
dws calendar +today	read	List my schedule for today (automatically calculate today's start and end times; no need to manually fill in the time range)
dws calendar +tomorrow	read	List my schedule for tomorrow (automatically calculate tomorrow's start and end times; no need to manually fill in the time range)
dws calendar +week	read	List my schedule for this week (automatically calculate this week's start and end times using Monday as the first day of the week; no need to manually fill in the time range)

Intent Table

User says	Command
"Today / Tomorrow / This week's schedule"	python scripts/calendar_today_agenda.py [today|tomorrow|week]
"Schedule a meeting (including attendees + meeting room)"	First search for rooms to get roomId, then once event create --attendees <ids> --rooms <roomId>; only use for complex fallback calendar_schedule_meeting.py
"Multiple people's common free time"	python scripts/calendar_free_slot_finder.py --users <ids> --date <yyyy-MM-dd>
"Check free/busy"	dws calendar busy search --users <userIds> --start "<ISO>" --end "<ISO>"
"Add attendee" / "Book room" / "Cancel"	dws calendar attendee add / room add / event delete

Common fast paths (omit Help / Reference)

When the following parameters are already determined, execute directly,do notcall again --help, Schema, or read calendar.md：

Intent	Direct command
Recommend common times by name	dws calendar +suggest-time --with "姓名1,姓名2" --start "<ISO>" --end "<ISO>" --duration <分钟> --format json
Create a meeting by name (no meeting room)	dws calendar +book --title "<主题>" --start "<ISO>" --end "<ISO>" --with "姓名1,姓名2" --format json; Runtime requires confirmation before precisely replaying and adding --yes
Check for conflicts on day N	dws calendar +conflicts --in-days <N> --format json(today N=0）
Check free windows on day N	dws calendar +free-slots --from <开始小时> --to <结束小时> --in-days <N> --format json
Search for available meeting rooms	dws calendar room search --start "<ISO>" --end "<ISO>" [--group-id <ID>] --available --format json
Schedule details/attendees	dws calendar event get --id <EVENT_ID> --format json / dws calendar attendee list --event <EVENT_ID> --format json

In the same state, the same command and the same parameters are called only once; re-querying is allowed only when a write operation occurs, a new cursor is obtained, or the first result is clearly incomplete. When searching for a schedule by title, start from the most likely and narrowest time window; once a unique match is obtained, stop immediately and do not continue scanning other months.

Standard SOP (mandatory process)

If the following intents are matchedmustexecute in the order of the corresponding SOP;forbiddento skip steps, replace commands, or fabricate userId/eventId. Each command must include --format json, time parametersmustbe ISO-8601 (e.g. 2026-07-03T14:00:00+08:00）。

SOP-1 Check schedule (list-events)

Trigger: today/tomorrow/this week's schedule/what meetings do I have/schedule for a certain period.

1. Preferred script (mandatory)：python scripts/calendar_today_agenda.py today|tomorrow|week(aggregate today's agenda).
2. Fallback CLI (mandatory): when the script is unavailable dws calendar event list --start "<起始ISO>" --end "<结束ISO>" --format json; if not passed --start/--end defaults to checking today (00:00:00~23:59:59). When it returns nextCursor you must continue paging until the cursor is empty; a "single-page success" cannot be treated as a complete query.
3. Parsing (mandatory): take the real eventId、attendees[]、start/end; extract as needed,forbiddento paste the entire JSON verbatim. When the user wants a summary or count, complete the aggregation locally and output only the counts for each group and necessary details, to avoid filling the reply item by item and causing the latter part to be truncated.

Forbidden: use event list instead of free/busy queries (for free/busy checks, follow SOP-3), fabricate time windows, or use non-ISO time formats.

SOP-2 Create schedule (create-event)

Trigger: create schedule/schedule a meeting/add schedule.

1. Parse attendees (mandatory): for each name dws aisearch person --query "<姓名>" --dimension name --format json take userId, multiple people comma-separated.
2. Execute (required)：dws calendar event create --title "<主题>" --start "<ISO>" --end "<ISO>" --attendees <userId1,userId2> --format json(add as needed --location/--desc/--rooms）。
3. Verify (once as needed): from the create response result.id get the schedule ID (downstream parameter semantics call it eventId). When the create response already includes the title, description, and time range requested by the user, reuse them directly; do not run an extra list just to "look again"; only when the response is missing fields, the user explicitly asks to check back, or the subsequent state changes, run one event get/narrow time window event list。

Prohibited: skipping attendee userId resolution and passing names directly, or fabricating a meeting room roomId.

SOP-3 Check busy/free (check-busy)

Trigger: whether a person/meeting room is free / finding free time slots / avoiding conflicts.

1. Resolve target (required): name → dws aisearch person --query "<姓名>" --dimension name --format json get userId; for meeting rooms use roomId。
2. Narrow time range (required)：--start/--end mustbe given by the user or explicitly narrowed; if the time range is unclearmust first ask，prohibitedto default to an all-day window.
3. Execute (required)：dws calendar busy search --users <userId1,userId2> --start "<ISO>" --end "<ISO>" --format json(for meeting rooms switch to --rooms <roomId...>, can be passed at the same time).Prohibitedto use event list to scan schedules instead of the busy/free query.
4. Free time slots (required): to find common free time use python scripts/calendar_free_slot_finder.py。

If there is indeed no common free time satisfying the duration within the specified window, explicitly provide the longest common free window and ask whether to shorten the duration, expand the time range, or change the date; without user confirmation, do not arbitrarily change the time, and do not claim the meeting has been arranged.

Prohibited: use event list to impersonate busy search, or default to an all-day query without confirming the time range.

Execution hard constraints

• Check requirements first, then clean up resources: first extract and temporarily store from the structured response the details, conflict pairs, attendees, meeting rooms, and verification conclusions that the user requested to see; even if temporary resources are subsequently deleted, the final reply must still present these results item by item. A successful tool call does not mean the result has been delivered to the user.
• Target verification must name the conclusion: when conflict/busy-free/search returns many records or the output is truncated, verification must be narrowed and checked by the current case's title,eventId, personnel, or resource ID; do not just say "the check was run". For example, a conflict task must explicitly indicate the overlapping start and end times of targets A/B, and whether back-to-back adjacency was excluded.
• New schedule + new meeting room should preferably be completed in two steps: when the user from the start asks to create a schedule and book a room, and there is no intermediate operation depending on the created eventId , first room search get the real roomId, then use one event create ... --rooms <ROOM_ID> to complete creation and booking; attendees can also be brought in at the same time with --attendees . Only when the schedule already exists, the user asks to see the schedule before booking a room, or one-step creation fails, use room add; do not go through "create → room add" two writes without reason.
• Multi-turn schedule tasks must retain eventId, and subsequent adding people, removing people, booking rooms, changing rooms, modifying descriptions, and deleting are all performed based on the same eventId ; do not recreate duplicate schedules.
• When the user explicitly says "help me book a free meeting room",room search After returning available meeting rooms, directly select the first one that can be booked and does not require custom approval roomId Execute room add; do not throw the choice back to the user and cause the task to stall.
• Existing schedule room booking:dws calendar room search --start ... --end ... --format json → dws calendar room add --event <EVENT_ID> --rooms <ROOM_ID> --format json → event get or room/busy verify.
• Change meeting room: first room delete --event <EVENT_ID> --rooms <OLD_ROOM_ID>, then room add --event <EVENT_ID> --rooms <NEW_ROOM_ID>, and finally check back; do not only update --location。
• For attendee changes use attendee add/delete, for schedule description changes use event update --desc, to delete a schedule use event delete --id. If the user's current message has explicitly requested deletion/cancellation, it can be executed directly; otherwise confirm first.
• For the deletion final state, check back once as needed: when the user explicitly requests "confirm deletion/no residue",event delete after success, use the original eventId, title, calendar book, and original start/end time to do a narrow-window active list check; for an ordinary "cancel after done", the structured deletion success is the final state, and no extra get/list is needed.event get may still return a historical object or tombstone; unless there is actually a status=cancelledin the return, you must not claim "the status has changed to cancelled".
• When the script fails or the parameters are incomplete, immediately fall back to an explicit dws calendar event/attendee/room command; do not stop at "I want to check the usage".
• All dws commands include --format json; query time must be explicit --start / --end。

Cross-product collaboration

• Video meeting initiation / join link / invitation to join / in-meeting control → current CLI not supported; please complete in the DingTalk client
• Post-meeting summary / to-dos → switch to dingtalk-minutes
• Attendees by name → first use dingtalk-aisearch to resolve

Note

For an ordinary "given time period + any free meeting room", directly follow the two-step fast path in this file; only when the user restricts to a building/floor/specific meeting room, the search is empty, or the scope needs to be relaxed, read 03-meeting.md for the range early stop and failure gate. Any path is prohibited from assuming roomId。

Local intent and short flow

• Local intent disambiguation；short flow。