Daniel Calendar · Agent Guide

本指南适用于任何可发起标准 HTTP 请求的智能体。只能通过用户明确提供的 Bearer Token 使用日历 API；不得使用 SSH、数据库、服务器文件或其他旁路访问用户日历。

连接与权限

API Base: https://calendar.hdaniel.studio/api/v1
Authorization: Bearer <用户提供的 Token>

首次连接：
1. GET /token/me
2. GET /calendars
3. GET /events?start=YYYY-MM-DD&end=YYYY-MM-DD

• 以 /token/me 返回的 username、timezone 与 scopes 为准。
• 不要在回复、链接、事件内容或日志中展示完整 Token。
• Token 权限以 scopes 为准；读取成功不代表一定拥有写入权限。

时间与查询

• 未标明时区的时间按账户时区解释；若接口未返回时区，默认 Asia/Shanghai。
• “本周”指账户时区下的周一至周日，不能以服务器 UTC 推断。
• 日期范围查询优先使用 YYYY-MM-DD，end 是不包含该日的结束边界。
• 涉及实时日程时先回读 API，不要仅依赖对话历史。

创建日程

单条创建：POST /api/v1/events。字段名为 calendar，但它的值必须是 GET /calendars 返回的日历 id，绝不能使用显示名称。

{"calendar":"calendar_id_from_GET_calendars","title":"早八课程","start":"2026-09-08T08:00:00+08:00","end":"2026-09-08T09:40:00+08:00","all_day":false,"location":"","description":"","reminder_minutes":15}

reminder_minutes 可选。重要写入完成后，应查询相同时间范围，核验标题、时间、日历、描述、全天状态和提醒。

批量创建（优先）

多个互相独立的日程应使用 POST /api/v1/events/batch，避免逐条慢速请求。

{"events":[{"calendar":"calendar_id_from_GET_calendars","title":"睡觉","start":"2026-09-08T23:00:00+08:00","end":"2026-09-09T07:00:00+08:00","all_day":false,"location":"","description":""}],"duplicate_policy":"skip","atomic":true,"dry_run":false}

• 先对完整覆盖范围查询一次，检查冲突与重复。
• dry_run: true 仅预演；只有用户要求预览时才使用。
• duplicate_policy: "skip" 会跳过明显重复项。
• 分别报告 created、skipped、failed，不得把失败计作成功。

修改与删除

• 修改：PATCH /api/v1/events/{event_id}，仅提交用户要求改变的字段。
• 删除：DELETE /api/v1/events/{event_id}。
• 先读取并唯一定位目标事件；标题重复或删除对象不明确时必须确认。
• 操作后回读受影响的日期范围。

常见问题

• 422：该请求未创建成功。检查字段名、日历 ID、ISO 时间与结束时间，再修正重试。
• 查询为空：优先改用 YYYY-MM-DD 范围；不要混用 UTC 判断今天或本周。
• 日历不存在：重新读取 /calendars，使用返回的 id，而非显示名称。
• 目标不唯一：列出匹配项，请用户选择后再编辑或删除。

工作原则

1. 信息明确时直接执行，不重复询问已知信息。
2. 日期、时间、目标日历或删除对象存在关键歧义时再确认。
3. 不预设用户的日历名称、个人习惯或导入规则。
4. 写入结果用简洁自然语言说明；失败时如实说明原因。

传输兼容与稳定交互

• 通过命令行或代码直接调用 API 时，优先使用 HTTPS + HTTP/1.1；例如 curl 添加 --http1.1。HTTP/2 也受支持。认证 API 不得使用明文 HTTP。
• 协议选择不能绕过 Work 的网络审批或出站网络策略。
• 遇到可由安全、有限次数重试解决的瞬时传输或服务异常时，应静默重试，不向用户展示中间诊断过程。
• 若适当检查后仍无法完成操作，只提供可执行的结果说明，不臆测服务器故障。ChatGPT Work 在收到 HTTP 响应前即失败时，应优先排查用户本地的 Work 网络设置、工作区策略或执行环境。