outlook-calendar-management

Outlook 日历助手

通过对话管理 Outlook 日历（微软账户 / outlook.com），无需打开 Outlook 应用，手机、电脑、网页实时同步。

能做什么

小输出优先：只看"有什么/什么时候"用 list --summary 或 --json，不要动辄拉全量；不确定时间范围先用默认 7 天。

操作铁律

以下规则适用于每次操作，不可跳过：

1. 每次操作前先取"当前时间 + 当前时区"：任何操作开始前，先用命令行获取系统当前时间和时区——Windows（PowerShell）用 Get-Date + Get-TimeZone，Linux/macOS 用 date（如 date +"%F %T %Z"），绝不用旧会话里见过的日期或时区。需要核对"今天是几号"时可配合运行 status（输出里有当前日期，含年份与星期）。相对时间词可以直接传给命令（今天 14:00、本周五 15:00、今天下午2点），命令会在运行时刻按系统时钟解析，输出里会显示解析后的日期——确认不是昨天
2. 删除前先确认：向用户复述待删除的日程（标题+时间），获得明确同意后再执行
3. 修改前先查看现状：先执行 read 获取当前内容，再决定修改内容
4. 事件 ID 仅从输出获取：命令输出中的 🆔 行即事件 ID，严禁猜测或编造
5. 操作后回读验证再汇报：add/update/move/delete 执行后，用 read/list 回读一次核对实际结果（标题+时间），确认与意图一致后再向用户汇报；不能只凭命令返回值就断言"已完成"
6. 失败不盲目重试：命令非零退出时，先读 ❌ 行（--json 时读 error 字段），按提示处理——权限/登录问题 → 重跑 python outlook_setup.py；查不到 → 扩大时间范围或换搜索词；严禁原样重试同一命令。仍无法解决时对照 references/troubleshooting.md 处理，或如实上报用户

输出契约

命令输出是 agent 与脚本的接口，只依赖结构，不依赖文案：

1. 锚点 + 结构提取：🆔/✅/⚠️/🆕 锚点、缩进、HH:MM-HH:MM 时段、JSON 结构是语言无关的协议；行内文案随语言，不作为提取依据
2. 事件 ID 仅从 🆔 行获取（严禁猜测/编造）；定期系列主事件 ID 从 🆕 行取（"🆕 + 冒号"结构，冒号前文案随语言）
3. 失败信号：退出码 1 + stderr ❌ 行；--json 时 stdout 为 {"error": ..., "exit": 1}
4. 程序化/批量场景一律加 --json：stdout 纯净 JSON，无人类提示混入

常见任务

"看看我这周/下周的安排"

→ week 看本周，list --days 7 看未来 7 天。想看更久用 list --days 30；看过去的用 list --past 30。

"我昨天加的那件事，改到今天"

→ ① list --created-after <昨天的日期> 找到它，记下 🆔 → ② read 确认是这件 → ③ move --days 1（或 --to 今天，保留原时段）→ ④ 回读核对后告诉用户"已从昨天 X 点改到今天 X 点"。关键词足够独特时也可一步完成：move --search "关键词" --days 1（唯一匹配直接操作，多匹配会列出候选）。

"加一个周五下午的会，提前10分钟提醒"

→ add "会议名" "本周五 15:00" "本周五 16:00" --remind 10。 "今天下午两点的会" → add "会议名" "今天 14:00" "今天 15:00"。相对时间词由命令按系统当前日期解析，输出会显示具体日期，确认无误即可。只给日期没给具体时间会按全天处理；默认会提示时间冲突，不阻断。

"把每周例会改成周三"

→ 定期日程的"每次"和"整个系列"是两回事：先 read 拿系列主事件 ID（🆕 行）→ update <主ID> --repeat "每周三"。注意：改系列规则会重置之前单独改过的某几次，先提醒用户。

"周五下午几点有空"

→ free "2026-08-14" --from 09:00 --to 18:00，会列出空闲时间段。

"周五那个会找不到了"

→ ① list --search "会议" 无结果时，先确认搜索词与时间范围（默认只查未来 7 天）→ ② 用 list --days 14 或 --past 扩大范围 → ③ 仍无则如实告诉用户"没找到"并给出建议，不编造日程。

"日历连不上了 / 权限报错"

→ ① 跑 status 确认连接与登录状态 → ② 提示 invalid_grant/401/403 时按 references/troubleshooting.md 处理（通常重跑 python outlook_setup.py 重新授权）→ ③ 网络问题可稍后重试一次，仍失败如实上报。

关键概念

• 定期日程（每周例会、每月 15 日……）：对"某一次"执行的修改/删除仅影响该次；修改规则、删除整个系列须操作主事件。详见 references/recurring-events.md
• 运行环境：Windows / Linux / macOS 均可；命令示例中的 python 在部分系统（如 macOS）为 python3，按实际解释器名运行即可
• 时间输入：时段用 YYYY-MM-DD HH:MM（"下午3点" = 15:00），全天只给日期；支持相对时间（今天/明天/本周X/下周X 及英文 today/this friday 等，可带时刻），由命令按运行时刻系统时钟解析——不要自己推算日期（完整约定见 references/commands.md）。时区自动按电脑本地时区处理，跨时区自动换算；探测异常时用 TZ 环境变量指定（如 TZ=Asia/Shanghai）。全天日程按 Outlook 邮箱首选时区写入，机器时区与邮箱时区不同也不会跨天显示；此功能需要 MailboxSettings.Read 权限。完整授权共 3 个权限：Calendars.ReadWrite（日程读写）、MailboxSettings.Read（邮箱时区）、User.Read（登录身份），升级后请重跑一次 python outlook_setup.py 重新授权
• 确认与脚本交互：脚本默认会再次询问确认；agent 场景应直接使用 -y 跳过（非交互环境中输入不可用时，脚本会自动取消）
• 输出语言：默认按系统语言自动选择（中文系统 → 中文，其他 → 英文）；可用 --lang zh|en 或环境变量 OCAL_LANG 覆盖。提取信息只依赖「输出契约」中的锚点与结构，与语言无关
• 首次运行自动安装依赖：脚本首次运行缺少 requests/msal/tzdata 时会自动 pip 安装。tzdata 缺失会导致 Windows 时区解析失败、日程时间偏移，必须保留。安装失败时会给出手动命令；若提示"依赖仍缺失"，需重启终端

详细参考