chenmingxuan/EP-Hub-Skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
EP-Hub-Skill/.agents/skills/dingtalk-calendar/references/calendar.md
T
chenmingxuan 0c8fa2653e first commit
2026-09-02 11:44:52 +08:00

48 KiB
Raw Permalink Blame History

日历 (calendar) 命令参考

CLI 命令树与黄金路径

  • 二级子命令（必选其一）：event（日程）、attendee（参会人）、room（会议室）、busy（闲忙）、attachment（日程附件）、book（我能看哪些日历本）、acl（我的日历共享给了谁）。dws calendar 后必须紧跟上述之一；禁止只执行 dws calendar（无子命令）。
  • 个人日程 / 给自己留时间块 / 专注时段：统一走 dws calendar event create。当前没有单独的 personal schedule create / calendar create 命令。
  • 查日程列表：dws calendar event list --start "<ISO-8601>" --end "<ISO-8601>" --format json，或优先使用脚本 python scripts/calendar_today_agenda.py [today|tomorrow|week]（见文末「自动化脚本」）。
  • 查循环日程实例：dws calendar event instances --id <EVENT_ID> --start "<ISO-8601>" --end "<ISO-8601>" --format json，用于按时间范围展开重复日程的每一个实例。注意：此接口只能查询重复性日程；普通非循环日程将查不到任何实例信息。
  • 查用户日历本列表：dws calendar book list（返回主日历 id == "primary" 等）。重要可以查询他人共享给自己的日历本，根据日历本id可以进一步查询对方的日程信息。
  • CLI 不存在独立的 dws calendar list；若误跑无子命令的 dws calendar，会打印整段 Usage，切勿将该段 help 当作工具结果再次塞进对话（会急剧增加 token 与首字延迟）。
  • 必须遵循指令说明进行调用。绝对禁止使用虚构指令，使用虚构参数。

反模式（禁止）

  1. 禁止执行 dws calendar 且不带二级子命令（会刷出大量帮助文本）。合法二级子命令：event / attendee / room / busy / attachment / book / acl。
  2. 禁止使用不存在的子命令试探（如臆造 dws calendar list）；需要日程列表时一律使用 dws calendar event list（带 --start / --end，见下文「查询日程列表」示例）；需要日历本列表时使用 dws calendar book list。
  3. 禁止将完整 --help/Usage 输出作为「观察」重复提交给模型；若误触，应直接改用本节黄金路径中的合法命令并重试。
  4. 禁止为已有日程重新创建日程来预订会议室。若日程已存在（同一会话中刚创建、或用户明确指向某日程），必须使用 room add --event <已有EVENT_ID> --rooms <ROOM_ID> 追加会议室，绝不能再调一次 event create --rooms（会创建重复日程）。
  5. 禁止用 --location 替代会议室预订。--location 是纯文本地点备注字段，填入会议室名称不会完成任何预订或占用。预订会议室必须通过 room add --rooms <roomId> 或 event create --rooms <roomId>，roomId 来自 room search 返回；--location 与 --rooms 是两个独立字段，用途完全不同。
  6. 禁止只传 --recurrence-* 部分 flag 并不是彼此独立的参数：只传其中一项（比如只改 --recurrence-count、只设 --recurrence-type）会让服务端收到不完整的 recurrence 结构，CLI 现已前置校验并直接拒绝这类调用。修改已有周期日程的任何一个循环字段时，都必须重新提供完整的 pattern+range 字段集合——必要时先 event get 读取现有 recurrence，再在命令中整体重传。
  7. 禁止用一条 指令 实现串行调用。比如当用户要求一次性安排多场不同的日程（例如「上午 10 点开项目评审、下午 2 点开复盘会、晚上 7 点聚餐」）时，必须拆解成 N 条独立的 event create，依次串行执行；每条命令自己写完整的 --title / --start / --end，绝不能把多个标题或多段时间塞进同一行。

核心概念

日历（calendar）：日程的容器。每个用户有一个主日历（我的日历，id: primary），还可以订阅公共/团队日历，以及他人共享的日历。 日程（event）：日历中的单个日程，包含起止时间、地点、标题、参会人等属性。支持单次日程和重复日程(有recurrence rule的日程，又称SeriesMaster)，遵循RFC5545 iCalendar国际标准。 日程实例（event instance）：日程的具体时间实例，可以通过event list指令查询时间段内的所有实例。1个普通日程和对应1个Instance，而1个重复性日程(SeriesMaster)对应N个Instance（同属一个日程序列）。

  • 同一个日程序列具有相同的iCalUid，并且重复性日程，其eventId和iCalUid的值相同。因此可以通过重复性日程实例的iCalUid得到重复性日程(SeriesMaster)的eventId 重复规则（recurrence rule）：定义重复性日程的重复规则。 参会人（attendee）：日程的参与者。按姓名统一使用 dws aisearch person --query "姓名" --dimension name --format json 查询 userId。 响应状态（response）：参会人对日程的回应，包括：未响应、接受、待定、拒绝。 忙闲时间（busy）：查询用户在指定时间段的忙闲状态，查询会议室在指定时间段的预定状态，用于会议时间协调。 会议室（room）：room是 会议室 ，room可视为日程的资源类参会人，需要加入日程完成预订。注意和location区分，location只是地点，和room不同。 访问控制 (acl)：用户可通过设置acl将自己的日历访问权限授予给他人（即：共享日历），授予后，他人就可以查看日历下的日程信息。通过 dws calendar acl list 可查看当前要用户已经授权出去的权限。若 privilege >= reader，可查询此日历下的日程数据。若 privilege >= writer ，可操作（创建/修改/删除/响应等）此日历下的日程数据。 共享日历：将自己日历的访问权限授予给他人，用于协作。通过 dws calendar book list 查询当前用户日历列表，其中type == shared 即他人共享给当前用户的日历。 订阅日历：创建一个公共日历供他人订阅，他人订阅后即可查询日历下的日程数据。通过 dws calendar book list 查询当前用户日历列表，其中type == subscribed 即当前用户已订阅的日历。注意：订阅日历下的日程无参会人概念，无法执行 attendee 相关指令，也无法添加会议室。

命令概览

event 相关三级子命令

# 针对单个日程： 创建 ｜ 修改 ｜ 单查询 ｜ 删除 ｜ 响应日程(接受、暂定、拒绝)
dws calendar event [create|update|get|delete|respond] [flags]
# 按时间范围批量查询
dws calendar event list [flags]
# 查询循环日程的实例列表（按时间范围展开重复日程）
dws calendar event instances [flags]
# 获取日程的分享信息（日程主题、组织人、地点、入会信息等，用于向他人分享日程）
dws calendar event share-info [flags]
# 对于非明确时间或一段时间范围的约会场景，可基于所有参会人的忙闲状态，推荐多个可用的时间块方案
dws calendar event suggest [flags]

attendee 相关三级子命令

# 日程中参会人操作：添加 ｜ 删除 ｜ 查询
dws calendar attendee [add|delete|list] [flags]

room 相关三级子命令

# 查询分组
dws calendar room list-groups [flags]
# 会议室搜索
dws calendar room search [flags]
# 预定会议室
dws calendar room add [flags]
# 释放会议室
dws calendar room delete [flags]

room是会议室，用于线下开会场景。

busy 相关三级子命令

# 按用户 / 会议室 + 时间窗查闲忙状态（--users 与 --rooms 至少其一），会议室的忙闲等同于预定记录
dws calendar busy search [flags]

attachment 相关三级子命令

# 把已上传到钉盘的文件挂到日程上（不负责上传，只负责挂载）
dws calendar attachment add [flags]

book 相关三级子命令（查"我能看哪些日历本"）

# 查询我拥有和可访问的所有日历本（含他人共享给我的）
dws calendar book list [flags]
# 查询指定日历本信息
dws calendar book get [flags]
# 按名称模糊搜索日历本
dws calendar book search [flags]
# 更新日历本信息（需 owner 权限）
dws calendar book update [flags]

acl 相关三级子命令（查"我的日历共享给了谁"）

# 查询我的日历共享给了哪些人、各自什么权限
dws calendar acl list [flags]
# 把我的日历共享给某人
dws calendar acl add [flags]
# 取消我的日历对某人的共享
dws calendar acl delete [flags]

说明: 可以通过 --help 进一步查看指令明细，也可以继续查看下一节 命令总览

命令总览

查询日程列表

Usage:
  dws calendar event list [flags]
Example:
  dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T18:00:00+08:00"
  dws calendar event list --start "2026-03-10T00:00:00+08:00" --end "2026-03-31T23:59:59+08:00" --limit 50
  dws calendar event list --calendar-id primary
  dws calendar event list --cursor "<nextCursor从上一次查询结果获取>"
Flags:
      --calendar-id string   日历 ID (默认 primary 主日历，仅在查询其他日历本时填写；通过 `book list` 获取)
      --cursor string        分页游标 (从上一次返回的 nextCursor 获取，首次查询无需传入)
      --end string           结束时间 ISO-8601 (例如 2026-03-10T18:00:00+08:00)
      --limit int            每页返回条数 (默认 100，最大 100)
      --start string         开始时间 ISO-8601 (例如 2026-03-10T14:00:00+08:00)

默认行为：不传 --start / --end 时，默认返回今天的日程（00:00:00 ~ 23:59:59）。 权限：查询共享日历下的日程时，至少要有reader权限。 分页：单次最多返回 --limit 指定的条数（默认/最大 100）；当结果超过 limit 时，返回体包含 nextCursor 字段。首次查询无需传 --cursor，仅在翻页时将上一次返回的 nextCursor 作为 --cursor 传入。

获取日程详情

Usage:
  dws calendar event get [flags]
Example:
  dws calendar event get --id <EVENT_ID>
  dws calendar event get --id <EVENT_ID> --calendar-id primary
Flags:
      --id string            日程 ID (必填)
      --calendar-id string   日历 ID (默认 primary 主日历)

查询循环日程实例

Usage:
  dws calendar event instances [flags]
Example:
  dws calendar event instances --id <EVENT_ID>
  dws calendar event instances --id <EVENT_ID> --start "2026-03-10T00:00:00+08:00" --end "2026-03-31T23:59:59+08:00"
  dws calendar event instances --id <EVENT_ID> --limit 50
  dws calendar event instances --id <EVENT_ID> --cursor "<nextCursor>"
Flags:
      --id string            日程 ID (必填，重复性日程 SeriesMaster 的 eventId)
      --calendar-id string   日历 ID (默认 primary 主日历，仅在查询其他日历本时填写；通过 `book list` 获取)
      --start string         开始时间 ISO-8601 (例如 2026-03-10T00:00:00+08:00，不传则默认今天 00:00:00)
      --end string           结束时间 ISO-8601 (例如 2026-03-31T23:59:59+08:00，不传则默认今天 23:59:59)
      --limit int            每页返回条数 (默认 100，最大 100)
      --cursor string        分页游标 (从上一次返回的 nextCursor 获取，首次查询无需传入)

说明：用于按时间范围展开重复日程（SeriesMaster）的每一个实例。此接口只能查询重复性日程；若传入普通非循环日程，将查不到任何实例信息。--id 必须是重复性日程的 eventId，可通过 event list 获取。 默认行为：不传 --start / --end 时，默认返回今天的实例（00:00:00 ~ 23:59:59）。 分页：单次最多返回 --limit 指定的条数（默认/最大 100）；当结果超过 limit 时，返回体包含 nextCursor 字段。

获取日程分享信息

Usage:
  dws calendar event share-info [flags]
Example:
  dws calendar event share-info --id <EVENT_ID>
  dws calendar event share-info --id <EVENT_ID> --language zh-CN
  dws calendar event share-info --id <EVENT_ID> --calendar-id primary
Flags:
      --id string            日程 ID (必填)
      --calendar-id string   日历 ID (可选，默认 primary 主日历)
      --language string      语言代码 (可选，如 zh-CN)

说明：根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程（如发送到群聊、邮件）。中文内容建议传 --language zh-CN。

创建日程

Usage:
  dws calendar event create [flags]
Example:
  dws calendar event create --title "Q1 复盘会" \
    --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00"
  dws calendar event create --title "周会" \
    --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" \
    --attendees userId1,userId2
  dws calendar event create --title "项目评审" \
    --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" \
    --rooms roomId1,roomId2     # 创建时直接预定会议室
  dws calendar event create --title "每日站会" \
    --start "2026-03-10T09:00:00+08:00" --end "2026-03-10T09:30:00+08:00" \
    --recurrence-type daily --recurrence-interval 1 --recurrence-range-type numbered --recurrence-count 10
  dws calendar event create --title "团队周会" \
    --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" \
    --calendar-id <SHARED_CALENDAR_ID>     # 在指定日历本下创建日程
  dws calendar event create --title "重要会议" \
    --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" \
    --remind-minutes 5,10     # 开始前5分钟和10分钟各提醒一次
Flags:
      --title string                    日程标题 (必填，最大2048字符)
      --start string                    开始时间 ISO-8601 (必填，例如 2026-03-10T14:00:00+08:00)
      --end string                      结束时间 ISO-8601 (必填，例如 2026-03-10T15:00:00+08:00)
      --calendar-id string              日历 ID (可选，默认 primary 主日历；仅在共享/订阅日历本下创建时填写，通过 `book list` 获取)
      --timezone string                 时区 IANA 格式 (例如 Asia/Shanghai，默认 Asia/Shanghai)
      --desc string                     日程描述 (最大5000字符)
      --attendees string                参会人 userId 列表，逗号分隔 (最多500人) 日程组织人自动放入参会人列表，无需传入userId
      --open-dingtalk-ids string        openDingTalkId 列表，逗号分隔 (与 --attendees 至少传一个)
      --rooms string                    会议室 roomId 列表，逗号分隔 (创建时直接预定，roomId 必须来自 `room search` 返回，若是循环会议，必须设置recurrence-end-date，避免长期预订)
      # 以下 --recurrence-* 一旦使用任一 flag，必须同时提供完整的 pattern+range 字段（至少 --recurrence-type、--recurrence-interval(>0) 与 --recurrence-range-type）
      # 否则 CLI 会报 "recurrence 结构不完整" 并拒绝执行
      --recurrence-type string          循环类型: daily|weekly|absoluteMonthly|relativeMonthly|absoluteYearly
      --recurrence-interval int         循环间隔 (如 daily 时表示每N天)
      --recurrence-days-of-week string  周几: sunday,monday,...,saturday (weekly/relativeMonthly 时必填)
      --recurrence-day-of-month int     每月第几天 (absoluteMonthly/absoluteYearly 时必填)
      --recurrence-index string         每月第几周: first|second|third|fourth|last (relativeMonthly 时必填)
      --recurrence-first-day-of-week string  一周起始日，默认 sunday
      --recurrence-range-type string    循环范围: noEnd|endDate|numbered (与 --recurrence-type 必须成对出现)
      --recurrence-end-date string      循环结束时间 ISO-8601 (range-type=endDate 时必填)
      --recurrence-count int            循环次数 (range-type=numbered 时必填)
      --rich-text-desc string           html格式的富文本类型日程描述，用于复杂内容的展示
      --location string                 地点信息（纯文本备注，如‘3号楼A区’；**不等于**预订会议室）
      --free-busy string                此日程的忙碌状态，默认值为busy。busy - 在忙闲视图中，此日程时间段为忙碌; free - 此日程不占用忙闲
      --remind-minutes string           日程开始前提醒，逗号分隔分钟数 (可选，例如 5,10,15 表示开始前5/10/15分钟提醒；不传则默认15分钟提醒)

说明：个人日程也走 event create。如果只是给自己安排时间，不传 --attendees / --open-dingtalk-ids 即可。

修改日程

Usage:
  dws calendar event update [flags]
Example:
  dws calendar event update --id <EVENT_ID> --title "新标题"
  dws calendar event update --id <EVENT_ID> --desc "新描述" --timezone Asia/Tokyo
  dws calendar event update --id <EVENT_ID> --recurrence-type daily --recurrence-interval 1 \
    --recurrence-range-type numbered --recurrence-count 5
  dws calendar event update --id <EVENT_ID> --calendar-id <SHARED_CALENDAR_ID> --title "新标题"   # 修改其他日历本下的日程
Flags:
      --id string                       日程 ID (必填)
      --calendar-id string              日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取)
      --title string                    新标题
      --start string                    新开始时间 ISO-8601
      --end string                      新结束时间 ISO-8601
      --desc string                     新描述 (最大5000字符)
      --timezone string                 时区 IANA 格式 (例如 Asia/Shanghai)
      # 以下 --recurrence-* 在 修改周期日程的循环规则时必须**整体**传入：MCP 不合并部分字段，只改其中一项（例如只传 --recurrence-count）会把规则覆盖成不完整状态
      # 若只想微调已有规则，请先 `event get --id <ID>` 读取现有 recurrence，再在本命令重传完整的 pattern+range
      --recurrence-type string          循环类型: daily|weekly|absoluteMonthly|relativeMonthly|absoluteYearly
      --recurrence-interval int         循环间隔 (如 daily 时表示每N天)
      --recurrence-days-of-week string  周几: sunday,monday,...,saturday (weekly/relativeMonthly 时必填)
      --recurrence-day-of-month int     每月第几天 (absoluteMonthly/absoluteYearly 时必填)
      --recurrence-index string         每月第几周: first|second|third|fourth|last (relativeMonthly 时必填)
      --recurrence-first-day-of-week string  一周起始日，默认 sunday
      --recurrence-range-type string    循环范围: noEnd|endDate|numbered (与 --recurrence-type 必须成对出现)
      --recurrence-end-date string      循环结束时间 ISO-8601 (range-type=endDate 时必填)
      --recurrence-count int            循环次数 (range-type=numbered 时必填)
      --rich-text-desc string           html格式的富文本类型日程描述，用于复杂内容的展示
      --location string                 地点信息（纯文本备注，如‘3号楼A区’；**不等于**预订会议室）
      --free-busy string                修改此日程的忙碌状态，无需修改则不传。busy - 在忙闲视图中，此日程时间段为忙碌; free - 此日程不占用忙闲

支持修改标题、描述、时间、地点、忙碌状态等。如需修改会议室，请使用 dws calendar room [add|delete]；如需修改参会人，请使用 dws calendar attendee [add|delete]

删除日程

CAUTION: 不可逆操作 — 所有参会人同步取消，必须先向用户确认。

Usage:
  dws calendar event delete [flags]
Example:
  dws calendar event delete --id <EVENT_ID> --yes
  dws calendar event delete --id <EVENT_ID> --calendar-id <SHARED_CALENDAR_ID> --yes   # 删除其他日历本下的日程
Flags:
      --id string            日程 ID (必填)
      --calendar-id string   日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取)

查看参会人

Usage:
  dws calendar attendee list [flags]
Example:
  dws calendar attendee list --event <EVENT_ID>
  dws calendar attendee list --event <EVENT_ID> --calendar-id <SHARED_CALENDAR_ID>   # 查看其他日历本下日程的参会人
Flags:
      --event string         日程 ID (必填)
      --calendar-id string   日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取, 注意：订阅日历下的日程无参会人，因此不可查看)

添加参会人

Usage:
  dws calendar attendee add [flags]
Example:
  dws calendar attendee add --event <EVENT_ID> --attendees <USER_ID_1>,<USER_ID_2>
  dws calendar attendee add --event <EVENT_ID> --attendees <USER_ID> --optional
  dws calendar attendee add --event <EVENT_ID> --attendees <USER_ID> --calendar-id <SHARED_CALENDAR_ID>   # 给其他日历本下的日程添加参会人
Flags:
      --event string         日程 ID (必填)
      --attendees string     参会人 userId 列表，逗号分隔 (必填，最多500人)
      --optional             参会人可选 (默认必选参会人)
      --calendar-id string   日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取，注意：订阅日历下的日程无参会人，因此不可添加)

移除参会人

CAUTION: 写操作 — 执行前须用户确认。

Usage:
  dws calendar attendee delete [flags]
Example:
  dws calendar attendee delete --event <EVENT_ID> --attendees <USER_ID> --yes
  dws calendar attendee delete --event <EVENT_ID> --attendees <USER_ID> --calendar-id <SHARED_CALENDAR_ID> --yes   # 移除其他日历本下日程的参会人
Flags:
      --event string         日程 ID (必填)
      --attendees string     参会人 userId 列表，逗号分隔 (必填)
      --calendar-id string   日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取，注意：订阅日历下的日程无参会人，因此不可移除)

搜索会议室

此指令支持两种模式：按名称搜索（不传 --start/--end）和按时间段搜索可用会议室（传 --start/--end 或不传任何参数）。 此指令搜索到的会议室结果中，有两个值需要注意：

  • customApprovalProcess: true - 表示该会议室设置了自定义审批流程，只能通过客户端完成预订。
  • supportRecurring: true - 表示该会议室支持循环预定；false - 表示不支持循环预定，直接加入到循环日程会失败。

模式路由规则：

  • 按名称搜索：仅传 --room-name，不传 --start/--end → 返回所有匹配名称的会议室，不检查可用性。适用于「找到某个会议室」的场景。
  • 按时间段搜索可用会议室：传 --start/--end，或不传任何参数 → 返回指定时间段内可用的会议室。不传时间时默认当前时间起 1 小时。
Usage:
  dws calendar room search [flags]
Example:
  # 按名称搜索（不检查可用性，返回所有匹配的会议室）
  dws calendar room search --room-name 永澄亭   # 注意：用户即使说「永澄亭会议室」，也应仅传「永澄亭」

  # 按时间段搜索可用会议室
  dws calendar room search --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00"
  dws calendar room search --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" --group-id <GROUP_ID>
  dws calendar room search   # 不传 --start/--end 时默认当前时间起 1 小时

  # 名称 + 时间段：搜索指定名称的可用会议室
  dws calendar room search --room-name 永澄亭 --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00"

  # 分页（仅按时间段搜索时有效）
  dws calendar room search --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" --limit 20 --page 0
Flags:
      --start string        开始时间 ISO-8601 (可选，不传则默认当前时间+1分钟缓冲）
      --end string          结束时间 ISO-8601 (可选，不传则默认当前时间+1 小时)
      --group-id string     会议室分组ID（可选，留空查根目录；超100条时需按分组查询；仅按时间段搜索时有效）
      --room-name string    会议室名称（按名称搜索时必填；按时间段搜索时可选，用于过滤）
      --limit string        页大小 (可选，不填默认 100，超过 100 按 100 处理；仅按时间段搜索时有效)
      --page string         分页起始位置 (可选，不填默认 0；仅按时间段搜索时有效)

时间约束（API 限制）：start 必须是未来的时间（服务端校验：start can not less current time）。

  • 若传入的 --start 早于当前时间，CLI 会自动修正为 now + 1min，调用方无需额外处理。
  • 若传入的 --end 早于当前时间，CLI 直接报错——无法检索已过去的时间段。
  • 最佳实践：调用方在组装时间参数时应确保 start/end 都是未来时间；若不确定，可省略 --start/--end 让 CLI 使用默认值（当前时间起 1 小时）。
  • 注意：时间约束仅在「按时间段搜索」模式下生效。按名称搜索（仅传 --room-name）不受时间约束。

名称过滤使用规范：--room-name 适用于用户说「预定永澄亭」「约西湖厅」这类按名找会议室的场景。

  • 服务端是模糊匹配，但匹配词越精简命中率越高，关键疗法：调用方必须在调用 CLI 前自行精简名称，CLI 不会再做任何删减。
  • 常见需要剔除的用户口语后缀（仅示例，实际场景由模型自行判断）：「会议室」「大会议室」「小会议室」「厅」「房」等。
  • 示例对映：
    • 用户：「帮我订永澄亭会议室」 → --room-name 永澄亭
    • 用户：「西湖厅有空吗」 → --room-name 西湖厅（本身就是专名，不删即可）
    • 用户：「预定贡嘎山大会议室」 → --room-name 贡嘎山

优先路径：

  • 当用户仅给出会议室名称、未指定时间段时，用 room search --room-name <核心专名> 快速找到会议室（不检查可用性）。
  • 当用户给出会议室名称且指定了时间段时，用 room search --room-name <核心专名> --start <开始时间> --end <结束时间> 查询该名称的可用会议室。
  • 若返回空列表，再降级使用 list-groups 定位分组再查。--room-name 可与 --group-id 同时使用（仅按时间段搜索时），表示「在指定分组内按名称过滤」。

roomId 与用户说的话不是一回事：用户说的「C6-4-06-N 贡嘎山」等是展示名/编号文案，绝不能直接填进 room add --rooms。--rooms 只接受上一步 room search（或同类接口）返回 JSON 里的 rooms[].roomId。形态上多为小写十六进制串（长度以接口为准，例如 e6b7b65b8b30fb707afcf6c3b699f028003e6834fdd7fee7）。含中文、空格、连字符拼接的楼层编号、或凭空调 UUID/纯数字「试格式」——一律视为非法，必须先搜房再取返回字段。

如果知道roomId，想查该会议室的预订记录，直接用dws calendar busy search 指令

预定会议室

Usage:
  dws calendar room add [flags]
Example:
  dws calendar room add --event <EVENT_ID> --rooms <ROOM_ID>
  dws calendar room add --event <EVENT_ID> --rooms <ROOM_ID> --calendar-id <SHARED_CALENDAR_ID>   # 给其他日历本下的日程预定会议室
Flags:
      --event string         日程 ID (必填)
      --rooms string         会议室 ID 列表 (必填)
      --calendar-id string   日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取，注意：订阅日历下的日程不可添加会议室)

room是会议室，用于线下开会场景。将room加入到日程完成预订 重复性日程，预订会议室时，必须设置 循环结束时间（recurrence-end-date），noEnd 或者 指定循环次数 都无法完成预定。

移除会议室

CAUTION: 写操作 — 执行前须用户确认。

Usage:
  dws calendar room delete [flags]
Example:
  dws calendar room delete --event <EVENT_ID> --rooms <ROOM_ID> --yes
  dws calendar room delete --event <EVENT_ID> --rooms <ROOM_ID> --calendar-id <SHARED_CALENDAR_ID> --yes   # 移除其他日历本下日程的会议室
Flags:
      --event string         日程 ID (必填)
      --rooms string         会议室 ID 列表 (必填)
      --calendar-id string   日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取。注意：订阅日历下的日程不可添加会议室)

会议室分组列表

Usage:
  dws calendar room list-groups [flags]
Example:
  dws calendar room list-groups
  dws calendar room list-groups --limit 20 --page 0
Flags:
      --limit string       页大小 (可选，不填默认 100，超过 100 按 100 处理)
      --page string        分页起始位置 (可选，不填默认 0)

添加日程附件

Usage:
  dws calendar attachment add [flags]
Example:
  dws calendar attachment add --event <EVENT_ID> --files <FILE_ID>:report.pdf,<FILE_ID2>:slides.pptx
  dws calendar attachment add --event <EVENT_ID> --files <FILE_ID>:report.pdf --calendar-id <SHARED_CALENDAR_ID>   # 给其他日历本下的日程添加附件
Flags:
      --event string         日程 ID (必填)
      --files string         附件列表，格式 <fileId>:<name>，多项逗号分隔 (必填)
      --calendar-id string   日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取，注意：订阅日历下的日程不可添加附件)

上传文件得到 fileId 需配合钉盘相关流程；本命令只负责把已上传的文件挂载到日程上。

查询我能看的所有日历本

Usage:
  dws calendar book list [flags]
Example:
  dws calendar book list

查询"我能看哪些日历本"，包含：我的主日历、他人共享给我的日历、订阅的公共/团队日历。注意区分：acl list 是查"我的日历共享给了谁"，方向相反。 共享日历本中有来自 xxx 的，且权限大于reader，那么通过 event list --calendar-id <xxx的日历本id> 可查到xxx完整的日程安排。 主日历 id 固定为 primary，绝大多数日程操作都默认走主日历，只有当用户明确要求查/写其他日历本时才需要带 --calendar-id。

查询指定日历本

Usage:
  dws calendar book get [flags]
Example:
  dws calendar book get --id primary
  dws calendar book get --id CALENDAR_ID
Flags:
      --id string   日历 ID (必填，主日历固定为 primary)

说明：根据日历 id 查询指定日历的详细信息。用户主日历本 id 固定为 primary。

搜索日历本

Usage:
  dws calendar book search [flags]
Example:
  dws calendar book search --query "项目"
  dws calendar book search --query "团队周报"
Flags:
      --query string   按日历本名称模糊检索 (必填)

说明：搜索当前用户拥有的日历本，支持按日历本名模糊搜索。获取全部日历请使用 book list。

更新日历本

Usage:
  dws calendar book update [flags]
Example:
  dws calendar book update --id CALENDAR_ID --summary "新日历名"
  dws calendar book update --id CALENDAR_ID --desc "日历描述"
Flags:
      --id string        日历 ID (必填)
      --summary string   日历标题
      --desc string      日历描述

说明：更新日历信息，最低权限要求：privilege == "owner"。注意：用户主日历本 以及 他人共享的日历本 不支持更新。

查询我的日历共享给了谁

Usage:
  dws calendar acl list [flags]
Example:
  dws calendar acl list

说明：查询"我的日历共享给了哪些人、各自什么权限"（即主日历的访问控制列表）。注意区分：book list 是查"我能看哪些日历本"，方向相反。

把我的日历共享给某人

Usage:
  dws calendar acl add [flags]
Example:
  dws calendar acl add --user USER_ID --privilege reader
  dws calendar acl add --user USER_ID --privilege writer --no-notification
Flags:
      --user string        授予权限的目标用户 ID (必填)
      --privilege string   授予的日历权限 (必填): free_busy_reader(查看忙闲)|title_reader(查看标题)|reader(查看详情)|writer(创建和编辑)
      --no-notification    不向被授权用户发送提醒 (默认发送)

说明：把我的日历共享给指定用户，授予对方相应权限。--privilege 可选值：free_busy_reader（查看忙闲）、title_reader（查看标题）、reader（查看详情）、writer（创建和编辑）。

取消我的日历对某人的共享

Usage:
  dws calendar acl delete [flags]
Example:
  dws calendar acl delete --acl-id ACL_ID
Flags:
      --acl-id string   已授予权限的 ID (必填，可通过 acl list 查询)

说明：取消我的日历对某人的共享（撤回已授予的访问权限）。aclId 可通过 acl list 获取。

查询用户 / 会议室闲忙状态

Usage:
  dws calendar busy search [flags]
Example:
  # 查用户闲忙
  dws calendar busy search --users <USER_ID_1>,<USER_ID_2> \
    --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T18:00:00+08:00"
  # 查会议室闲忙
  dws calendar busy search --rooms <ROOM_ID_1>,<ROOM_ID_2> \
    --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T18:00:00+08:00"
  # 同时查用户 + 会议室
  dws calendar busy search --users <USER_ID> --rooms <ROOM_ID> \
    --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T18:00:00+08:00"
Flags:
      --end string     结束时间 ISO-8601 (必填)
      --start string   开始时间 ISO-8601 (必填)
      --users string   用户 ID 列表，逗号分隔 (与 --rooms 至少其一)
      --rooms string   会议室 ID 列表，逗号分隔 (与 --users 至少其一)

说明：

  • --users 与 --rooms 必须至少指定其一，可以同时指定；CLI 会做前置校验，两者都为空会直接报错。
  • 查询会议室闲忙前，可先用 dws calendar room search 或 dws calendar room list-groups 拿到 roomId。
  • 返回结果中的忙碌时段仅包含粗粒度的时间信息，不包含日程内容细节（如标题、参会人、地点），以保护隐私。

建议日程时间

Usage:
  dws calendar event suggest [flags]
Example:
  dws calendar event suggest --users userId1,userId2 --duration 60
  dws calendar event suggest --start "2026-03-10T09:00:00+08:00" --end "2026-03-10T18:00:00+08:00" --users userId1
  dws calendar event suggest --users userId1 --duration 30 --timezone Asia/Tokyo
Flags:
      --start string      推荐时间范围开始 ISO-8601 (默认当前时间)
      --end string        推荐时间范围结束 ISO-8601 (默认次日18点)
      --timezone string   时区 IANA 格式 (默认 Asia/Shanghai)
      --users string      参会人 userId 列表，逗号分隔
      --duration string   日程持续时间，单位分钟 (默认30)

> 对于非明确时间或一段时间范围的约会场景，可基于所有参会人的忙闲状态，推荐多个可用的时间块方案，用于解决会议时间协调问题。

响应日程

Usage:
  dws calendar event respond [flags]
Example:
  dws calendar event respond --id <EVENT_ID> --status accepted
  dws calendar event respond --id <EVENT_ID> --status declined
  dws calendar event respond --id <EVENT_ID> --status tentative
  dws calendar event respond --id <EVENT_ID> --status accepted --calendar-id <SHARED_CALENDAR_ID>   # 响应其他日历本下的日程
Flags:
      --id string            日程 ID (必填)
      --status string        响应状态: needsAction(未操作)|accepted(接受)|declined(拒绝)|tentative(暂定) (必填)
      --calendar-id string   日历 ID (可选，默认 primary 主日历；指定其他日历本时填写，可通过 `book list` 获取。注意：订阅日历下的日程无参会人，因此不可响应)

说明：作为日程参会人，设置自己的响应状态（接受、拒绝、暂定）。--status 可选值：needsAction（未操作，默认值）、accepted（接受）、declined（拒绝）、tentative（暂定）。

意图判断

用户说"日程/会议/约会/日历":

  • 查看 → event list
  • 详情 → event get
  • 创建/约/给自己留时间块/个人日程 → event create（带参会人时加 --attendees，循环日程加 --recurrence-*，自定义提醒加 --remind-minutes）
  • 修改/改时间/改描述 → event update（支持修改标题、时间、描述、时区、循环规则）
  • 取消/删除 → event delete
  • 推荐时间/什么时候有空/协调时间 → event suggest
  • 接受/拒绝/暂定日程 → event respond
  • 查询循环日程/重复日程的每次实例/展开循环日程 → event instances
  • 分享日程/把日程发给别人/获取日程分享信息或入会信息 → event share-info

用户说"参会人/与会者":

  • 查看 → attendee list
  • 邀请/添加 → attendee add --attendees <USER_ID>（可选参会人加 --optional）
  • 移除 → attendee delete --attendees <USER_ID>

用户说"会议室/订会议室":

  • 哪个空闲 → room search（默认查当前时间起 1 小时内可用会议室）
  • 按名找会议室（如「永澄亭」「永澄亭会议室」「约西湖厅」，未提时间段）→ 先在模型层精简名称（剔除「会议室」等通用后缀），再用 room search --room-name <核心专名>（按名称搜索，不检查可用性）
  • 按名找可用会议室（如「永澄亭下午 2 点有空吗」）→ room search --room-name <核心专名> --start <开始时间> --end <结束时间>（按名称+时间段搜索可用会议室）
  • 预订
    • 给已有日程订会议室 → room add --event <已有EVENT_ID> --rooms <ROOM_ID>
    • 创建新日程并订会议室 → event create --rooms（仅当日程尚不存在时）
  • 取消预定 → room delete
  • 分组 → room list-groups，取 groupId 后 room search --group-id（需配合 --start/--end 按时间段搜索；可再叠加 --room-name 在分组内过滤）

用户说"有空吗/忙不忙/闲忙":

  • 查询用户闲忙 → busy search --users <USER_ID>
  • 查询会议室闲忙 → busy search --rooms <ROOM_ID>
  • 用户 + 会议室一起查 → busy search --users <USER_ID> --rooms <ROOM_ID>

用户说"日程附件/给会议加文件/上传日程材料":

  • 添加 → attachment add（先用钉盘上传得 fileId，再 attachment add --files <fileId>:<name>）

用户说"我有几个日历/查所有日历/别人共享给我的日历/他人共享给我的日历本":

  • 列表 → book list（返回用户拥有和订阅的所有日历本，包括他人共享给自己的；主日历 id 固定为 primary）
  • 查指定日历本 → book get --id <CALENDAR_ID>
  • 按名称搜索日历本 → book search --query "关键词"
  • 修改日历本名称/描述 → book update --id <CALENDAR_ID> --summary "新名"

用户说"我的日历共享给了谁/谁能看我日历/日历权限/取消共享/把日历分享给xxx":

  • 查看我共享出去的情况（即谁有权访问我的日历） → acl list
  • 把我的日历共享给他人 → acl add --user <USER_ID> --privilege reader
  • 取消我的日历对某人的共享 → acl delete --acl-id <ACL_ID>（aclId 来自 acl list）

易混淆辨析：book list 查的是"我能看哪些日历本"（包含别人共享给我的）；acl list 查的是"我的日历共享给了谁"（我的主日历的访问控制列表）。两者方向相反，不可混用。

用户说"查下xxx的日程安排":

  • 查询是否有共享关系 -> book list
    • 场景1: 共享日历本中有来自 xxx 的，且权限大于reader，那么通过 event list --calendar-id <xxx的日历本id> 可查到xxx完整的日程安排
    • 场景2: 共享日历本中没有来自 xxx 的。那么通过 busy search -- <USER_ID>，查询xxx的忙闲安排

核心工作流

创建会议 + 邀请参会人 + 预订会议室

event create 支持 --attendees 在创建时直接指定参会人，自 calendar MCP v2 起也支持 --rooms 在创建时一并预定会议室；旧流程的「先创建日程再 room add」依然有效。

关键区分：event create --rooms 仅在日程尚不存在时使用；若日程已存在（同一会话刚创建、或用户指向已有日程），必须走「给已有日程订会议室」流程（见下方），禁止重复 event create。

方式一：创建时一步完成（仅当日程尚不存在时推荐）

# Step 1: 搜索空闲会议室，记下 roomId
dws calendar room search --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" --format json
# 若返回错误(会议室超100条)，先查分组再按分组搜索:
#   dws calendar room list-groups --format json
#   dws calendar room search --start ... --end ... --group-id <GROUP_ID> --format json

# Step 2: 创建日程时直接指定参会人 + 会议室
dws calendar event create --title "Q1 复盘会" \
  --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" \
  --attendees userId1,userId2 \
  --rooms <ROOM_ID_FROM_STEP1> --format json

方式二：先创建日程，再单独添加参会人 / 会议室

# Step 1: 创建日程 — 从 result.id 提取日程 ID
dws calendar event create --title "Q1 复盘会" \
  --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" --format json

# Step 2: 添加参会人（必须用 Step 1 返回的 result.id）
dws calendar attendee add --event <EVENT_ID> --attendees userId1,userId2 --format json

# Step 3: 搜索空闲会议室
dws calendar room search --start ... --end ... --format json

# Step 4: 预定会议室
dws calendar room add --event <EVENT_ID> --rooms <ROOM_ID> --format json

给已存在的日程加附件

# Step 1: 用钉盘上传文件，得到 fileId（参见 dws drive 系列命令）
# Step 2: 把附件挂到指定日程
dws calendar attachment add --event <EVENT_ID> --files <FILE_ID>:report.pdf,<FILE_ID2>:slides.pptx --format json

查看日程列表

dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" --format json

上下文传递表

操作 从返回中提取 用于
event create result.id attendee/room/attachment 操作的 --event
event list result.events[].id, nextCursor event get/update/delete/respond 的 --id；下一页 --cursor
event suggest 推荐的时间段 event create 的 --start/--end
event respond 响应结果 —
event instances result.events[].id, nextCursor event get/update/delete/respond 的 --id；下一页 --cursor
event share-info 日程分享信息（主题、组织人、地点、入会信息等） 分享给他人（如 chat/mail 发送）
room search rooms[].roomId room add 的 --rooms 或 event create 的 --rooms
room list-groups groups[].groupId room search 的 --group-id
book list id（如 primary） event list/get 的 --calendar-id, book get/update 的 --id
book get 日历详细信息 —
book search 匹配的日历列表 book get/update 的 --id
acl list aclId acl delete 的 --acl-id
acl add 新增的权限记录 —
钉盘上传 文件 fileId attachment add 的 --files <fileId>:<name>

注意事项

  • 时间格式: event create/update、event list、busy search 和 event suggest 用 ISO-8601
  • 时区: event create/update 和 event suggest 支持 --timezone 指定 IANA 时区（如 Asia/Shanghai、America/New_York），不传默认 Asia/Shanghai
  • 创建日程时可通过 --attendees 直接指定参会人（最多500人），也可创建后用 attendee add --attendees ... 单独添加
  • --attendees 和 --open-dingtalk-ids 至少传一个（如果需要指定参会人）
  • 添加参会人时可通过 --optional 设为可选参会人（默认必选）
  • event suggest 根据参会人闲忙自动推荐合适时间，适合会议时间未确定时使用
  • 创建日程支持通过 --rooms 一步预定会议室（event create --rooms roomId1,roomId2）；若创建后再加，仍可用 room add
  • room search 不带 --group-id 时查根目录；企业会议室超过 100 条会报错，此时需先 room list-groups 获取分组，再按分组逐一查询
  • room list-groups 支持 --limit / --page 分页（schema 类型为字符串）
  • event create --rooms / room add --rooms 的唯一合法来源：最近一次（同一会话、同一时段窗口）room search 返回体中的 roomId；禁止把用户自然语言会议室名当 roomId 传入（否则会 roomId invalid 等错误）
  • 搜房无结果：在符合早停/用户限定范围内，room search（含按分组逐组查）全部返回空或无空闲 → 应直接向用户报错/说明失败并结束订房；禁止假设 roomId、禁止无合法 roomId 时调用 room add / event create --rooms 试探、禁止用 event get 等绕路推断 roomId
  • 自动化校验：凡涉及 room add / event create --rooms 的流程，--rooms 只能填上游 room search（或等价接口）返回 JSON 中的 rooms[].roomId；不得以会议室展示名、楼层文案或用户口语当作 roomId
  • 附件：attachment add 仅负责挂载，不上传文件；fileId 必须先通过钉盘流程取得；--files 多附件用 <fileId>:<name> 元素逗号分隔
  • 日历本：book list 返回的 id 才是合法 calendarId；如无明确说明，event list / event get 都不要带 --calendar-id，让接口默认走 primary 主日历
  • 分页查询：event list / event instances 均支持 --limit（控制每页条数，默认/最大 100）和 --cursor（翻页游标）；首次查询无需传 --cursor，仅当返回体中包含 nextCursor 时，将其作为 --cursor 传入可获取下一页
  • 循环日程实例：event instances 用于按时间范围展开重复日程（SeriesMaster）的每一个实例；普通非循环日程调用该命令将查不到任何实例信息
  • 日程分享：event share-info 获取日程的分享信息（主题、组织人、地点、入会信息等）；--language 控制文案语言（中文场景传 zh-CN）
  • 日程提醒：event create 支持 --remind-minutes 设置开始前提醒，逗号分隔多个分钟数（如 --remind-minutes 5,10,15），不传则默认15分钟提醒
  • 会议室分页：room search 支持 --limit（每页条数，默认100，最大100）和 --page（分页起始位置，默认0），与 room list-groups 分页风格一致

自动化脚本

脚本 场景 用法
calendar_today_agenda.py 查看今天/明天/本周日程安排 python calendar_today_agenda.py today
calendar_schedule_meeting.py 一键创建日程+添加参会人+预定会议室；搜房失败时输出明确原因并返回非零退出码 python calendar_schedule_meeting.py --title "复盘会" --start "2026-03-15T14:00" --end "2026-03-15T15:00" --users userId1 --book-room
calendar_free_slot_finder.py 查询多人共同空闲时段 python calendar_free_slot_finder.py --users userId1,userId2 --date 2026-03-15

相关产品

  • conference（视频会议预约） — 仅视频会议预约（返回入会链接），不含参会人/会议室管理
  • contact — 搜索同事 userId，用于 attendee add --attendees
Reference in New Issue View Git Blame Copy Permalink