# 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 | 单条任务的变更史 |
| GET | /api/tasks/{id}/remarks | 该任务的原话记录（倒序） |
| POST | /api/tasks/{id}/remarks | 单独追加一条原话 {"text":"..."} |

## 任务字段

```json
{
  "title": "改词缀系统",                 // 必填，任务名，15 字以内
  "notes": "改造点：1. 列表排序：初级词汇、补充词放最前面；2. 每个词加特殊标红符",  // 内容：你整理后的具体说明
  "raw": "帮我把词缀系统改一下，初级词汇和补充词放最前面，每个词还要加个标红的符号",   // 用户原话，原封不动
  "priority": 3,                        // 1低 2中 3高 4紧急；也接受 "high"/"urgent"/"重要"
  "due": "2026-10-23T15:00",            // 截止时间，见下方说明
  "project": "考研英语",                 // 归属清单，不填默认「收件箱」
  "tags": ["词缀"],                     // 可选
  "status": "open"                      // open / done / dropped
}
```

### 三个文本字段，别搞混

| 字段 | 放什么 | 谁来写 |
|---|---|---|
| `title` | 任务名，扫一眼就懂，15 字以内 | 你提炼 |
| `notes` | **内容**：把用户的话整理成结构化的要点、步骤、条件，可以换行，最多 2 万字 | 你整理 |
| `raw` | **用户的原话**，一个字都不要改，不要总结，不要加标点 | 原样抄 |

`raw` 会进「备注」里的一条时间线，用户平时折叠着不看，但需要翻的时候能翻到当初自己是怎么说的。
**每次**帮用户建任务或改任务，都带上 `raw`（这次的这句原话）。同一件事说第二遍，就会多一条记录。

`raw` 的别名：`said` / `utterance` / `raw_text` / `quote` / `原话`，任选一个都行。

例：用户说「明天上午去趟医院，带上上次的化验单，顺便问医生那个药还要不要继续吃」

```json
{
  "title": "去趟医院",
  "notes": "带上次的化验单
问医生那个药还要不要继续吃",
  "raw": "明天上午去趟医院，带上上次的化验单，顺便问医生那个药还要不要继续吃",
  "due": "2026-10-23T09:00"
}
```

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

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

## 优先级怎么判（只有四档）

1 = 低（灰）　2 = 中（蓝）　3 = 高（橙）　4 = 紧急（红）

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

- 「紧急」「马上」「今天必须」「来不及了」→ 4
- 「重要」「必须」「别忘」「关键」→ 3
- 普通待办、没强调 → 2（不传也行，默认就是 2）
- 「有空再说」「顺便」「不急」「想起来再」→ 1

系统只有这四档，传 0、负数、超过 4 的数字都会被收敛，别浪费时间去猜别的值。

## 完整示例

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

先 `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":["购物"],
     "raw":"明天下午三点提醒我买笔，挺重要的"},
    {"title":"洗车","priority":1,"due":"2026-10-25","project":"生活",
     "raw":"顺便记一下周末要洗车"}
  ]'
```

用户说：「下周要交开题报告，帮我记一下，得先把第三章的实验补完，还有参考文献格式要统一，导师说周日前发给他」

这句里有三件事，但真正的任务是「交开题报告」，其余是细节 → 一条任务 + 长备注：

```json
{
  "title": "交开题报告",
  "notes": "先把第三章的实验补完
参考文献格式要统一
导师要求周日前发给他",
  "raw": "下周要交开题报告，帮我记一下，得先把第三章的实验补完，还有参考文献格式要统一，导师说周日前发给他",
  "priority": 3,
  "due": "2026-10-25"
}
```

后来用户又说「开题报告的参考文献让用 GB/T 7714」，改同一条时把这句话也带上：

```bash
curl -X PATCH https://todo.xj-lab.cn/api/tasks/<id>   -H "Authorization: Bearer <密码>"   -H "Content-Type: application/json"   -d '{"notes":"先把第三章的实验补完
参考文献按 GB/T 7714 格式统一
导师要求周日前发给他",
       "raw":"开题报告的参考文献让用 GB/T 7714"}'
```

「备注」里就会多一条 10-23 的记录，原来的那句还在。

## 几条硬规矩

1. **不要编造 id**。修改/删除前先 `GET /api/tasks` 拿到真实 id。
2. **删除是软删除**，用户能在网页端恢复。但如果用户说「清空」，先确认一次。
3. **批量优先**。一次说三件事，就一次 POST 三条，不要发三次请求。
4. **标题要短**。「买笔」而不是「用户提醒我需要去商店购买一支笔」。
5. **每次都带 `raw`**，把用户这句话原样抄进去。这是他日后回溯「当初到底怎么说的」的唯一凭据，
   改了就不再是原话了。同一条任务说第二次，就再带一次 `raw`，会追加成第二条记录。
6. 想让操作日志看出是谁干的，加一个请求头：`X-Agent-Name: Claude`。

## 其他入口

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