Timeleaf（时光手帐）是用户的私有待办、日历与每日手记。网页、REST 和 MCP 共用数据。只操作当前 Key 授权的项目；可用工具随权限变化。
先用 context_get 确认账号时区和今日日期，再使用 projects_list 选择项目。收集箱是尚未安排 plannedDate 或具体时间段的待办；due 是截止日期，与执行日期独立。创建时间段时关联具体 taskId，同一待办可以分多次安排；移除一个时间段会保留待办。完成任务通过 tasks_update 设置 done:true，不会因时间过去自动完成。
重复支持 daily/weekly/monthly、interval 与 until。系列 id 是 UUID，单次实例 id 是 UUID~YYYY-MM-DD，后缀是原始发生日，改期后不变。查询会展开日期范围中的实例。只修改或取消本次，使用实例 id；修改或删除整个系列，使用 seriesId，先 get 系列以取得当前版本。不要凭实例版本修改系列。每月遇到短月份落在最后一天，下个月恢复原始日号；日程使用 IANA 时区，夏令时不存在的发生时刻会跳过。
所有写操作传 operation_id，同次重试复用相同 ID 和参数；已有事项修改、删除、恢复还需 expected_version，先 get 最新记录。发生 VERSION_CONFLICT 后重读并合并，再用新 operation_id。删除待办会同时移除其关联时间安排，需要 events:delete；不要擅自扩大到整个重复系列。改项目可能需要 events:write。恢复用 delete 返回的最新 version。写响应只返回 id/version，不隐含读取权限。未提供账号、密钥管理、提醒或内置大模型工具。

访问与认证
REST API https://timeleaf.kele.best/api/v1，MCP https://timeleaf.kele.best/mcp。MCP 使用 Streamable HTTP POST 和 Authorization: Bearer API_KEY。网页创建 Key，完整值只显示一次；不要放进 URL。

API 资源
GET/POST /projects、/tasks、/events；GET/PATCH/DELETE /资源/:id；POST /资源/:id/restore。写入 JSON 提供 operation_id，修改/删除/恢复再提供 expected_version。GET /journals/:date，PUT 同地址保存 text、mood、expected_version（新建为0）、operation_id。GET /calendar/busy?from=YYYY-MM-DD&to=YYYY-MM-DD。

分页与日期
列表支持 limit 1–100，offset 0–100000，query，project。任务/日程支持 from、to，最大124天；默认前30天至后90天。任务 status=all/open/completed/inbox。响应 items,total,next_offset。查询只包含已授权内容。

重复规则
recurrence={frequency:daily|weekly|monthly,interval:1,until:null或YYYY-MM-DD}。仅本次使用实例 id；整个系列使用 seriesId 并先读取系列版本。修改系列保留单次覆盖。重复待办的 due 按与起始执行日期的天数差逐次移动。

日程字段
calendar 为项目 UUID，date/start/end 是本地日期和HH:mm，timezone 是 IANA 时区，endDate 省略为同日。allDay=true 时 endDate 为不包含的结束日，省略为次日。taskId 可关联具体一次待办，不会自动完成；有 taskId 的时间块不另设重复。

权限
projects:read, projects:write, tasks:read, tasks:write, tasks:delete, events:read, events:write, events:delete, journals:read, journals:write。写入权限不隐含读取。Key 可限定 projectIds；限定项目的 Key 不提供个人手记。凭据撤销立即生效。删除待办会移除关联安排，有关联安排时还需 events:delete；跨项目移动关联安排需 events:write。

安全与恢复
账号数据独立；修改版本冲突返回409。暂无站外提醒、内置模型、匿名共享、日历外部双向同步。密码至少10字符，注册默认邀请码模式。备份由服务器管理。