# 待办 · AI 接入说明

个人待办系统。任何 AI 或脚本都能通过下面的接口读写，网页（https://todo.manmanlang.cc）会自动同步显示。今天是 2026-11-03（Asia/Shanghai）。

## 结构
- **项目**：独立的长期事项板块。start_date / end_date 为起止日期；goal 为目标；criteria 为完成标准；participants 为 [{name,role}]；milestones 为 [{id,title,date,done}]。status 为 planned（未开始）、active（进行中）、paused（暂停）、completed（已完成）。pinned 置顶，priority 为 0 未分级、3 最高、2 中、1 低。修改人员或里程碑时提交整个数组，并保留已有里程碑 id。完成项目会记录 done_at；待办全部完成不会自动完成项目。
- **待办**：只有一个主标题。area 分 工作(work) / 生活(life)；pinned=置顶；due=日期（可选，有日期的会同步到日历）。
  - 不属于项目的待办（project_id=null）在网页分「待办」(soon) /「以后」(later) 两个状态，跟日期无关；「全部待办」同时显示两种状态。
  - 项目待办的 owner 默认为“我”；我负责的未完成项目待办也出现在主页，同一份数据。phase 为分组阶段，workflow 为 todo / doing / waiting / done。其他负责人待办在项目内查看。
- **视频项目**里的待办：stage 阶段 选题 → 脚本 → 拍摄 → 剪辑 → 待发布 → 已发布；platforms 平台 抖音 / 小红书 / 视频号；due = 计划发布日。stage 设为「已发布」会自动标记完成。
- **已完成**：网页分「已完成工作」「已完成生活」。

## 认证
所有 /api 和 /mcp 请求都要带密钥（部署时设置的 API_TOKEN）：
    Authorization: Bearer <API_TOKEN>
也可以用 X-API-Key 请求头，或 URL 参数 ?key=<API_TOKEN>（日历订阅就是这样用的）。

## 方式一：MCP（支持 MCP 的 AI 工具首选）
地址：https://todo.manmanlang.cc/mcp    （Streamable HTTP，无状态）
工具：get_summary, list_tasks, list_projects, get_project, add_tasks, update_task, complete_tasks, delete_tasks, restore_tasks, create_project, update_project, delete_project, apply_batch

## 方式二：REST API
完整定义：https://todo.manmanlang.cc/openapi.json

    GET    /api/summary                    概览（先调这个）
    GET    /api/tasks?view=open            view: open|soon|later|done|trash|all
                                           可加 project=<id>|none  area=work|life  q=  due_from=  due_to=  pinned=  stage=
    POST   /api/tasks                      新建：一个对象；或数组 / {"tasks":[...]}
    PATCH  /api/tasks/{id}                 修改：只传要改的字段
    POST   /api/tasks/{id}/complete        完成（/reopen 恢复未完成，/restore 从回收站恢复）
    DELETE /api/tasks/{id}                 删除（进回收站）
    GET    /api/tasks/{id}/ics             单条导出为日历事件
    GET    /api/projects?status=active     项目列表（active|done|all|trash）
    GET    /api/projects/{id}              项目 + 名下待办
    POST   /api/projects                   新建项目
    PATCH  /api/projects/{id}              修改项目（done=true 即整体完成）
    POST   /api/projects/{id}/complete     完成项目（/reopen /restore）
    DELETE /api/projects/{id}              删除项目（名下待办一起进回收站）
    GET    /api/projects/{id}/calendar.ics 项目日历订阅，scope=milestones（节点+截止日，默认）|tasks（带日期待办）|span（项目周期）；完成项目后清空此项目订阅的事件
    POST   /api/batch                      {"ops":[...]} 原子批量
    GET    /api/sync                       全部数据（网页用）
    GET    /api/calendar.ics               日历订阅（所有带日期的未完成待办）；加 ?date=YYYY-MM-DD 导出当天事项
    GET    /api/export                     全量导出

## 数据结构
待办：
    { "id": "a1b2c3d4e5f6", "title": "改小程序首页", "note": "", "area": "work", "bucket": "soon",
      "pinned": false, "due": "2026-10-30", "project_id": null, "stage": "拍摄", "platforms": ["抖音"],
      "done": false, "done_at": null, "created_at": "...", "updated_at": "..." }
项目：
    { "id": "miniapp", "name": "小程序", "note": "", "area": "work", "kind": "normal", "longterm": false, "done": false }

- due 写入时也可用 "today" "tomorrow" "+3"。时间戳一律 UTC。
- area 也接受 "工作"/"生活"，bucket 接受 "待办"/"以后"，kind 接受 "普通"/"视频"。
- 写未知字段会报错，不会悄悄丢数据。

## 批量示例：建一个项目并加三条待办
    POST /api/batch
    {"ops":[
      {"op":"create_project","id":"miniapp","project":{"name":"小程序","area":"work"}},
      {"op":"create","task":{"title":"定首页结构","project_id":"miniapp","due":"+3"}},
      {"op":"create","task":{"title":"找开发报价","project_id":"miniapp"}},
      {"op":"create","task":{"title":"买机票","area":"life","bucket":"soon","pinned":true}}
    ]}

## 给 AI 的约定
1. 改动前先拿到真实 id，不要猜 id。
2. 标题写成可执行的短句（动词开头），细节放 note。
3. 用户没说日期就不要编日期；没说待办/以后时，默认放在「待办」。
4. 置顶只给用户明确说重要/置顶的事。
5. 删除是软删除，误删可恢复；多处改动用 /api/batch 一次提交。