# AI-Native Todo — 操作说明书

用户只给了你一个域名和一个密码，没有别的。你能读到这里，说明你已经找对地方了。
你的任务：**把他随口说的话，直接落成这个待办清单里的任务**，不要让他自己打开网页手打。

## 认证（就这一步）

把用户给你的那串密码，放进请求头：

```
Authorization: Bearer <密码>
```

如果客户端不方便设请求头，拼在 URL 上也行：

```
?token=<密码>
```

密码错了会返回 401。不用注册、不用换 token、不用先调别的接口。

## 30 秒上手

```bash
# 1) 先问时间。不读这个，你不知道"明天"是几号
curl -s https://todo.xj-lab.cn/api/context -H "Authorization: Bearer <密码>"

# 2) 再写任务。一次可以传数组
curl -s -X POST https://todo.xj-lab.cn/api/tasks   -H "Authorization: Bearer <密码>"   -H "Content-Type: application/json"   -d '[{"title":"买笔","priority":3,"due":"2026-10-23T15:00"}]'
```

## 接口一览

| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /api/context | 当前时间、今天日期、周几、统计（**每次对话先读这个**） |
| GET | /api/tasks?status=open&from=2026-10-20&to=2026-10-26&q=关键词 | 查询 |
| POST | /api/tasks | 创建（单个对象或数组） |
| PATCH | /api/tasks/{id} | 修改（只传要改的字段） |
| DELETE | /api/tasks/{id} | 删除（软删除，可恢复） |
| POST | /api/tasks/{id}/complete | 标记完成 |
| POST | /api/tasks/{id}/uncomplete | 取消完成 |
| POST | /api/tasks/batch | 批量：{"action":"complete|delete|restore|update","ids":[...],"patch":{}} |
| GET | /api/audit?limit=50 | 操作历史（谁在什么时候改了什么） |
| POST | /api/audit/{id}/undo | 回滚某一次操作 |
| GET | /api/tasks/{id}/history | 单条任务的变更史 |

## 任务字段

```json
{
  "title": "买笔",                      // 必填，动词+对象，不要写成句子
  "notes": "顺便看看有没有 0.5 的",      // 可选，补充信息
  "priority": 3,                        // 0无 1低 2普通 3高 4紧急；也接受 "high"/"urgent"/"重要"
  "due": "2026-10-23T15:00",            // 截止时间，见下方说明
  "project": "生活",                    // 归属清单，不填默认「收件箱」
  "tags": ["购物"],                     // 可选
  "status": "open"                      // open / done / dropped
}
```

### 关于 due（最容易出错的地方）

- 有具体时刻 → 写完整时间：`"due": "2026-10-23T15:00"`
- 只有日期（全天任务）→ 只写日期：`"due": "2026-10-23"`
- 没有截止时间 → 不传 `due`，任务会留在「无日期」里
- **不要传相对时间**（"明天"、"3小时后"）。先用 /api/context 拿到今天日期，
  自己换算成绝对时间再传。服务器不会猜你的意思。
- 所有时间按 **Asia/Shanghai (UTC+8)** 理解。直接传本地时间字符串，不要转 UTC。

## 优先级怎么判

不要一律填 3。按用户语气和内容判断：

- 「重要」「必须」「别忘」→ 3
- 「紧急」「马上」「今天必须」→ 4
- 普通待办、没强调 → 2
- 「有空再说」「顺便」「不急」→ 1
- 纯记录、无行动 → 0 或干脆不建

## 完整示例

用户说：「明天下午三点提醒我买笔，挺重要的，顺便记一下周末要洗车」

先 `GET https://todo.xj-lab.cn/api/context`，假设返回 `{"now":"2026-10-22 21:10","today":"2026-10-22",...}`，
那么"明天"是 10-23，"周末"是 10-25。然后：

```bash
curl -X POST https://todo.xj-lab.cn/api/tasks   -H "Authorization: Bearer <密码>"   -H "Content-Type: application/json"   -d '[
    {"title":"买笔","priority":3,"due":"2026-10-23T15:00","project":"生活","tags":["购物"]},
    {"title":"洗车","priority":1,"due":"2026-10-25","project":"生活"}
  ]'
```

## 几条硬规矩

1. **不要编造 id**。修改/删除前先 `GET /api/tasks` 拿到真实 id。
2. **删除是软删除**，用户能在网页端恢复。但如果用户说「清空」，先确认一次。
3. **批量优先**。一次说三件事，就一次 POST 三条，不要发三次请求。
4. **标题要短**。「买笔」而不是「用户提醒我需要去商店购买一支笔」。
5. 想让操作日志看出是谁干的，加一个请求头：`X-Agent-Name: Claude`。

## 其他入口

- `GET https://todo.xj-lab.cn/api` — JSON 格式的接口自描述（机器更好解析）
- `GET https://todo.xj-lab.cn/api/docs` — 自动生成的交互式 API 文档