pp-outlook-calendar

Outlook Calendar — Printing Press CLI

前置条件：安装 CLI

此技能由 outlook-calendar-pp-cli 二进制文件驱动。调用此技能中的任何命令前，必须确认 CLI 已安装。 如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install outlook-calendar --cli-only
   

2. 验证：outlook-calendar-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），则改用直接通过 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/productivity/outlook-calendar/cmd/outlook-calendar-pp-cli@latest

如果安装后 --version 报告 "command not found"，则运行时无法在 $PATH 中找到二进制文件目录。在验证成功前，请勿执行技能命令。

何时使用此 CLI

当 Agent 需要以非交互方式读取或写入个人 Microsoft 365 日历时，请使用 outlook-calendar-pp-cli。它适用于 daily-brief、schedule-this-meeting、find-me-time、what-changed-this-week 和 prep-me-for-my-next-meeting 等任务。当你需要使用 Graph 端点无法通过单次调用提供的离线式查询（冲突、空闲时间计算、重复事件偏移）时，优先使用它，而不是直接调用 Microsoft Graph。

独特功能

其他任何用于此 API 的工具都不具备这些功能。

可累积的本地状态

• conflicts — 一次查找你所有 Outlook 日历中的重叠事件，也就是 Outlook 自带界面从不显示的重复预订。

  当 Agent 需要判断某个提议的时间是否会占用用户时间时，这是涵盖用户所有日历的权威信息来源。

  outlook-calendar-pp-cli conflicts --from today --to +7d --json --select pair_id,a.subject,b.subject,overlap_minutes
  

• freetime — 计算未来 K 天工作时间内长度为 N 分钟的空档，同时考虑所有日历，并可选择排除 OOF/暂定事件。

  当 Agent 需要提议会议时间时，此功能会给出确定的结果，并遵循用户的实际工作时间。

  outlook-calendar-pp-cli freetime --duration 60m --within 'Mon-Fri 9-17' --next 7d --exclude-oof --json
  

• review — 与上次增量同步快照进行比较：列出新增、改期、取消或 RSVP 状态发生变化的事件。

  让 Agent 无需扫描整周日历即可回答“自我上次查看以来发生了什么变化？”。

  outlook-calendar-pp-cli review --since last-sync --json
  

• pending — 按开始时间排序，列出 RSVP 仍待处理且开始时间在未来的事件。

  Agent 任务：“我还有哪些邀请需要回复？”——一次查询即可解答。

  outlook-calendar-pp-cli pending --json
  

• recurring-drift — 对每个重复系列的主事件，列出开始时间、结束时间、主题或地点偏离主事件模式的实例。

  捕捉组织者在你不知情时改期的事件，避免人们在错误的时间加入 Teams 通话。

  outlook-calendar-pp-cli recurring-drift --json
  

• with — 统计你与此人见面的频率，以及上次见面的时间。数据来自本地存储，包括次数和最近的 N 个事件。

  Agent 任务：“我和 X 多久见一次？”——无需读取整个日历。

  outlook-calendar-pp-cli with [email protected] --since 90d --json
  

• tz-audit — 显示开始时区与日历默认时区或自身结束时区不同的事件；这些事件可能会在其他设备上显示异常。

  Agent 任务：“我的事件是否有可能在其他人的设备上显示为错误时间？”——给出是/否及相关事件。

  outlook-calendar-pp-cli tz-audit --json
  

面向 Agent 的基础功能

• prep — 返回未来 N 小时内即将发生事件的详细资料：主题、地点、参会者邮箱、组织者、正文摘要、附件列表，以及重复事件/在线会议标记。

  一次工具调用即可向 Agent 提供向用户介绍即将发生事项所需的一切信息。

  outlook-calendar-pp-cli prep --next 4h --json
  

命令参考

attachments — 管理事件附件

• outlook-calendar-pp-cli attachments delete — 删除附件
• outlook-calendar-pp-cli attachments get — 按 ID 获取特定附件
• outlook-calendar-pp-cli attachments list — 列出事件中的附件

availability — 空闲/忙碌状态和会议时间智能分析（在个人 Microsoft 账户上功能受限；仅查询自己的空闲时间时，优先使用 freetime）

• outlook-calendar-pp-cli availability find — 根据与会者的空闲情况和约束条件推荐会议时间
• outlook-calendar-pp-cli availability schedule — 获取用户列表的空闲/忙碌日程（在个人 Microsoft 账户上功能受限）

calendars — 管理账户中的 Outlook 日历

• outlook-calendar-pp-cli calendars create — 创建新日历
• outlook-calendar-pp-cli calendars default — 获取用户的默认日历
• outlook-calendar-pp-cli calendars delete — 删除日历
• outlook-calendar-pp-cli calendars get — 按 ID 获取日历
• outlook-calendar-pp-cli calendars list — 列出账户中的所有日历
• outlook-calendar-pp-cli calendars update — 更新日历

categories — 管理用于为事件添加标签的 Outlook 主类别

• outlook-calendar-pp-cli categories create — 创建新的主类别
• outlook-calendar-pp-cli categories delete — 删除主类别
• outlook-calendar-pp-cli categories list — 列出主类别

delta — 将事件增量同步到本地 SQLite 存储

• outlook-calendar-pp-cli delta events — 拉取自上次 delta 令牌以来的增量事件变更
• outlook-calendar-pp-cli delta view — 拉取指定时间范围内的增量日历视图变更

events — 默认日历或指定日历中的 Outlook 日历事件

• outlook-calendar-pp-cli events accept — 接受会议邀请
• outlook-calendar-pp-cli events cancel — 取消由你组织的事件（会通知与会者）
• outlook-calendar-pp-cli events create — 在默认日历中创建新事件
• outlook-calendar-pp-cli events decline — 拒绝会议邀请
• outlook-calendar-pp-cli events delete — 按 ID 删除事件
• outlook-calendar-pp-cli events dismiss — 关闭事件提醒
• outlook-calendar-pp-cli events forward — 将事件转发给其他与会者
• outlook-calendar-pp-cli events get — 按 ID 获取单个事件
• outlook-calendar-pp-cli events instances — 列出指定日期范围内重复事件的各次发生记录
• outlook-calendar-pp-cli events list — 列出默认日历中的事件
• outlook-calendar-pp-cli events range — 列出指定日期范围内发生的事件（calendarView；展开重复事件的各次发生记录）
• outlook-calendar-pp-cli events search — 在服务端搜索事件（$search 查询）
• outlook-calendar-pp-cli events snooze — 将事件提醒延后至指定时间
• outlook-calendar-pp-cli events tentative — 暂定接受会议邀请
• outlook-calendar-pp-cli events update — 更新现有事件的字段（主题、正文、时间、地点、与会者）

查找合适的命令

知道要做什么，但不知道该用哪个命令时，可以直接向 CLI 提问：

outlook-calendar-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help，或尝试更具体的查询。

用法示例

每日简报

outlook-calendar-pp-cli prep --next 24h --json --select subject,start,end,location,attendees

面向 Agent 的每日摘要，包含简报所需的所有字段，不包含其他内容。

查找下周的一小时空档

outlook-calendar-pp-cli freetime --duration 60m --within 'Mon-Fri 9-17' --next 7d --exclude-oof --json

返回工作时间内的空档（不包括 OOF）；可通过管道传给 jq '.[0]'，获取第一个空档。

查看自周一以来的变更

outlook-calendar-pp-cli review --since 'Mon 09:00' --json

按类别汇总差异（新增/重新安排/已取消/RSVP 已变更），以显示组织者一侧的重新安排情况。

待处理的 RSVP

outlook-calendar-pp-cli pending --json --select subject,start,organizer.email

所有 RSVP 仍待处理的未来活动 — 使用 --select 缩小输出范围，让 Agent 只看到所需字段。

使用深层 --select 扫描冲突

outlook-calendar-pp-cli conflicts --from today --to +14d --json --select pair.a.subject,pair.b.subject,overlap_minutes,calendar.a,calendar.b

使用多个日历的用户（顾问 + 个人）可先让 Agent 调用 conflicts，了解实际发生冲突的事项；带点号的 --select 可让负载保持精简。

身份验证设置

身份验证通过 https://login.microsoftonline.com/common 使用 OAuth 2.0 设备代码流。运行一次 outlook-calendar-pp-cli auth login --device-code；在任意设备上访问显示的网址，输入代码即可完成。令牌会缓存到 ~/.config/outlook-calendar-pp-cli/config.toml（模式为 0600）。访问令牌过期后，CLI 会使用存储的刷新令牌自动续期，因此后续命令无需交互即可运行。默认客户端 ID 是 Microsoft 发布的 Graph PowerShell 客户端（开箱即支持个人 Microsoft 账户）；传入 --client-id 可使用你自己的 Azure 应用注册。个人 Microsoft 账户（Outlook.com、Hotmail、Live、MSA）受到一等支持并经过测试。

运行 outlook-calendar-pp-cli doctor 验证设置。

Agent 模式

在任意命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。带点号的路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这对缩小上下文至关重要：

  outlook-calendar-pp-cli attachments list mock-value --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不发送

• 支持离线 — 可用时，同步/搜索命令可以使用本地 SQLite 存储

• 非交互式 — 从不提示输入，所有输入都通过标志提供

• 显式重试 — 仅当已存在的创建结果也应视为成功时才使用 --idempotent；仅当缺少的删除目标也应视为成功时才使用 --ignore-missing

响应封装

从本地存储或 API 读取的命令会将输出封装在一个来源信息对象中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时来源还是本地。当 stdout 连接到终端时，才会将人类可读的 N results (live) 摘要输出到 stderr；通过管道传输或由 Agent 消费时，stdout 只包含纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有异常之处时，请记录下来：

outlook-calendar-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
outlook-calendar-pp-cli feedback --stdin < notes.txt
outlook-calendar-pp-cli feedback list --json --limit 10

条目会存储在本地 ~/.outlook-calendar-pp-cli/feedback.jsonl。只有在设置了 OUTLOOK_CALENDAR_FEEDBACK_ENDPOINT 且传入 --send 或设置 OUTLOOK_CALENDAR_FEEDBACK_AUTO_SEND=true 时，才会通过 POST 发送。默认情况下仅保存在本地。

写下让你感到意外的地方，而不是提交错误报告。简短、具体、单行：这些细节会不断累积。

输出传递

每条命令都接受 --deliver <sink>。输出会发送到指定目标，同时输出到 stdout，或替代 stdout 输出，因此 Agent 无需手动通过管道传输即可路由命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

遇到未知方案时会拒绝处理，并返回结构化错误，列出支持的方案。Webhook 失败时返回非零状态码，并将 URL 和 HTTP 状态码记录到 stderr。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。适用于定时 Agent 每次运行时都使用相同配置调用同一命令的场景 — HeyGen 的 “Beacon” 模式。

outlook-calendar-pp-cli profile save briefing --json
outlook-calendar-pp-cli --profile briefing attachments list mock-value
outlook-calendar-pp-cli profile list --json
outlook-calendar-pp-cli profile show briefing
outlook-calendar-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便能够自省的 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 outlook-calendar-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并带上 --agent）

安装 MCP 服务

从此 CLI 发布的公共库条目或预构建版本中安装 MCP 二进制文件，然后注册：

claude mcp add outlook-calendar-pp-mcp -- outlook-calendar-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which outlook-calendar-pp-cli 如果未找到，提供安装选项（参见此技能顶部的先决条件）。
2. 将用户查询与上文“独特功能”和“命令参考”中的最佳命令匹配。
3. 使用 --agent 标志执行：

   outlook-calendar-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，查看子命令帮助：outlook-calendar-pp-cli <command> --help。