v2.0.0 to v2.1.0

+ version: 2.1.0

+ WebDAV 与 PC 端共享同一份 `sync-data.json.gz`：AI 的写入约 1.5 秒后（连续写入最多

+ 攒 10 秒）推送到 WebDAV，PC 端下次同步即可见。

+ - "把 C3 / ID xxx 的截止时间改到 2026-05-20" → `update C3 endTime=2026-05-20`

+ > 比 16 位完整 i64 id 更适合用户口语反馈；删除后短码不会被复用。所有 `done` / `show` /

+ > `update` / `delete` 的 id 位置都同时接受 `C{seq}` / `c{seq}`（大小写不敏感）和完整 i64 id。

+ 2. 如果 `config.toml` 不存在，把 `config.example.toml` 复制为 `config.toml`，并把权限收紧到

+ 只有当前用户可读写（Linux/macOS `chmod 600`，Windows 去掉继承的访问权限、只留当前用户）

+ 3. 提示编辑 `config.toml` 填入 `endpoint` + `api_key`（可选 `timezone`，见下）

+ pip install tzdata # 仅 Windows 且在 config.toml 里配置了 timezone 时需要

+ `config.toml` 字段：`endpoint`、`api_key`（必填）；`timeout`（秒，默认 10；`sync` 至少 90）；

+ `timezone`（IANA 时区名，例如 `Asia/Shanghai`，`today` 用它计算"今天"；不填用本机时区，

+ 建议与云端 / PC 一致）。

+

+ 退出码：`0` 成功（包括 `health` 报告同步降级）；`2` 配置 / 参数错误；`3` 网络错误（GET 已自动

+ 重试 2 次）；`4` 服务端返回错误（stderr 是 `HTTP <状态码>: <detail>`）。

+

+ | `today` | 今日相关（今天到期 ∪ 今天开始 ∪ 已逾期未完成）；"今天"按 config 的 `timezone` | `python minitodo.py today --json` |

+ | `add <title>` | 新增待办；`--due` 写入 `endTime` | `python minitodo.py add "买菜" --priority high --due 2026-05-20` |

+ | `list` | 列表，可叠加 `--pending` / `--completed` / `--priority` / `--quadrant` / `--limit` / `--sort` | `python minitodo.py list --pending --priority high --json` |

+ | `search <kw>` | 关键词搜索（标题 + 描述） | `python minitodo.py search "报告" --json` |

+ | `update <ref> <key=val>...` | 修改字段，支持多个 | `python minitodo.py update C3 endTime="2026-06-01 18:00" priority=medium` |

+ | `health` | 健康检查（同步降级时照常输出 JSON，stderr 附一行提示） | `python minitodo.py health --json` |

+ - `--due`：规范格式 `YYYY-MM-DD HH:MM:SS`；也可写 `YYYY-MM-DD`（= 当天 `23:59:00`）或

+ `YYYY-MM-DD HH:MM`；带 `Z` / `±HH:MM` 时区后缀的值由服务端换算成它配置的时区。

+ - `--priority high|medium|low`：服务端映射成 PC 的颜色（见下方字段表）；同时给 `--color` 时以颜色为准。

+ - `update` 的 value 自动尝试解析为 `true` / `false` / `null` / 数字 / JSON，剩下当字符串；

+ `quadrant=` 接受别名（`urgent_important` 等）；字段名必须是下方字段表里的（或别名），

+ 否则服务端返回 400 并列出允许的字段。

+ | 把 C3 的截止时间改到下周一 18 点 | `python ~/.claude/skills/minitodo/minitodo.py update C3 endTime="2026-05-25 18:00" --json` |

+ | 清空 C3 的提醒时间 | `python ~/.claude/skills/minitodo/minitodo.py update C3 notifyAt=null --json` |

+ CLI 不可用时，AI 可直接用 curl。所有请求都要 `Authorization: Bearer <api_key>`；写请求

+ body 是 JSON（`Content-Type: application/json`）。

+ | `GET /health` | 服务健康与同步状态（降级时 **503**，见下文） |

+ | `GET /todos?...` | 列表；query: `completed=true/false`, `priority=high/medium/low`（按颜色派生）, `quadrant=1-4` 或 `urgent_important` 等别名, `dueDateBefore` / `dueDateAfter`（按 `endTime`；见下）, `startDate=YYYY-MM-DD`, `q=<keyword>`（标题 + 描述）, `sort=[+-]<field>`, `limit`, `offset`, `withSubtasks=true` |

+ | `GET /todos/:id?withSubtasks=true` | 详情（默认嵌套 subtasks） |

+ | `POST /todos` | 创建；body 必填 `title`，其它字段见字段表 |

+ | `PATCH /todos/:id` | 部分更新；未提及字段保留；内容没变化时不刷新 `updatedAt` |

+ | `PATCH /subtasks/:id` | 部分更新子任务 |

+ | `POST /sync` | 手动触发 pull + push；全部成功 200，部分失败 207；返回 `{pull, push, pullError?, pushError?}` |

+ | `POST /sync/pull` | 仅 pull；返回 `{status, changed, repushScheduled, todosUpserted, ...}` |

+ | `POST /sync/push` | 仅 push；返回 `{status, pushed, attempts, dirtyCleared, ...}` |

+ 排序字段白名单：`dueDate`（= `endTime`）/ `startTime` / `priority`（high > medium > low >

+ 自定义颜色）/ `quadrant` / `sortOrder` / `updatedAt` / `createdAt` / `title`。前缀 `-` 倒序、

+ `+` 或省略正序；不在白名单的字段按 `sortOrder` 排序。

+ `dueDateBefore` / `dueDateAfter` / `startDate` 接受与写入相同的时间格式；仅日期时

+ `dueDateBefore=D` 表示"D 当天 23:59:59 及以前"（含当天），`dueDateAfter=D` 表示"D 当天

+ 00:00:00 及以后"。格式不对 → 400。

+ ### 时间格式

+ 所有时间字段（`notifyAt` / `startTime` / `endTime` / `createdAt` / `updatedAt`）都是

+ **`YYYY-MM-DD HH:MM:SS`**：服务端（与 PC）配置时区的墙钟时间，无时区后缀，例如

+ `"2026-05-20 18:30:00"`。写入时也接受下面这些形式，服务端统一换成规范格式再保存：

+

+ | 输入 | 保存为 |

+ |---|---|

+ | `2026-05-20 18:30` / `2026-05-20T18:30` / `2026-05-20T18:30:00.123` | `2026-05-20 18:30:00` |

+ | `2026-05-20T10:30:00Z` / `2026-05-20T18:30:00+08:00` | 换算成服务端时区的墙钟 |

+ | `2026-05-20`（仅日期） | `startTime` → `00:00:00`；`endTime` / `dueDate` → `23:59:00`；`notifyAt` → `09:00:00` |

+ | `null` 或 `""` | 清空该字段 |

+

+ ### todo 字段（写入契约，与 PC 端模型一致）

+

+ | `title` | 非空字符串 | 任务名称（创建时必填） |

+ | `description` | 字符串 / null | 备注（Markdown）。别名 `notes`（只在没给 `description` 时生效） |

+ | `color` | `"#RRGGBB"` | 颜色，PC 用它表示优先级：`#EF4444` 高、`#F59E0B` 中、`#10B981` 低（新建默认 `#10B981`）；其它颜色是用户自定义色 |

+ | `priority` | `"high"` / `"medium"` / `"low"` | **写入时是 `color` 的别名**（high→#EF4444、medium→#F59E0B、low→#10B981；同时给了 `color` 以 `color` 为准；写 `null` 被忽略）。**读取时是派生字段**：由 `color` 映射，自定义颜色为 `null`；不入库 |

+ | `quadrant` | 1-4 | 四象限：1 重要紧急、2 重要不紧急、3 紧急不重要、4 不紧急不重要（默认）。也接受别名 `urgent_important` / `important_not_urgent` / `urgent_not_important` / `not_urgent_not_important`，保存为整数 |

+ | `completed` | bool | 完成态 |

+ | `startTime` | 时间 / null | 开始时间 |

+ | `endTime` | 时间 / null | 截止时间。别名 `dueDate`（旧版字段名，只在没给 `endTime` 时生效） |

+ | `notifyAt` | 时间 / null | 下一次提醒时间。**重复任务每次触发后只更新这个字段**，`endTime` 不变。改了它而没显式给 `notified` 时，`notified` 自动重置为 `false`（与 PC 一致） |

+ | `notifyBefore` | 整数 ≥ 0 | 提前多少分钟提醒 |

+ | `notified` | bool | 本次提醒是否已触发 |

+ | `sortOrder` | 整数 | 列表排序 |

+ | `repeatEnabled` | bool | 是否开启重复（开启且没给 `notifyBefore` 时，`notifyBefore` 置 0，与 PC 一致） |

+ | `repeatInterval` | 整数 ≥ 1 | 间隔；`weekly` + `interval=2` = 每两周 |

+ | `repeatWeekdays` | `"1,3,5"` / null | 仅 `weekly`：星期几（1=周一 … 7=周日）；也接受数组 `[1,3,5]` |

+ | `repeatMonthDay` | 1-31 / null | 仅 `monthly`：每月几号 |

+ 只读 / 服务端维护的字段：`id`、`createdAt`、`updatedAt`、`seq`（cloud 短码）、`subtasks`、

+ `subtaskCount`（列表不嵌套时附带）。写入时这些字段会被**忽略**，所以把读到的对象改几个字段

+ 后整包写回是安全的；对象里原样带回的 `color` / `endTime` / `description` 不会盖掉你对

+ `priority` / `dueDate` / `notes` 的修改（规范字段只有真的改了才优先于别名）。

+ **其它任何字段一律 400**（PC 端是强类型模型，不认识的字段会被静默丢掉）；类型不对同样 400。

+ 错误体是 JSON：

+ ```json

+ {

+ "error": "bad_request",

+ "detail": "unknown field(s): tags; allowed: title, description, color, ...; quadrant: must be 1-4 or one of urgent_important, ...",

+ "unknownFields": ["tags"],

+ "invalidFields": {"quadrant": "must be 1-4 or one of ..."},

+ "allowedFields": ["title", "description", "color", "quadrant", "..."]

+ }

+ ```

+ 其它错误码：`unauthorized`（401）、`not_found`（404）、`unsupported_media_type`（415，

+ 缺 `Content-Type: application/json`）、`internal`（500，详情只在服务端日志）、`sync_failed`

+ （500，`/sync/pull` / `/sync/push` 失败；detail 给出 WebDAV 层面的原因）。

+

+ ### subtask 字段

+

+ | 字段 | 类型 | 说明 |

+ |---|---|---|

+ | `title` | 非空字符串 | 创建时必填 |

+ | `content` | 字符串 / null | Markdown 内容 |

+ | `completed` | bool | 完成态 |

+ | `sortOrder` | 整数 | 排序 |

+ | `parentId` | 只读 | 所属 todo 的 id。**不能修改**（要移动就删掉再在另一个 todo 下新建）；写入时给了不同的值 → 400，相同的值忽略 |

+

+ `id` / `createdAt` / `updatedAt` 写入时忽略，其它字段 400。

+

+ ### 图片

+

+ 描述 / 子任务内容里的图片引用有两种形式，都用 `GET /images/<name>` 取图（需要 Bearer）：

+

+ - 规范形式：`` → 文件名就是 `<name>`

+ - 旧数据：`http://asset.localhost/<URL 编码的本机绝对路径>` 或 `asset://localhost/<...>`

+ （PC 端本机路径）→ 先 URL 解码，再按 `/` 或 `\` 切分取**最后一段**作为文件名，例如

+ `http://asset.localhost/C%3A%5CUsers%5Cme%5CAppData%5CLocal%5Cmini-todo%5Cimages%5C1715000000000_ab12cd.png`

+ → `1715000000000_ab12cd.png`

+

+ 文件名只含字母、数字、`.`、`_`、`-`（以字母或数字开头、不含 `..`、最长 128 字符），其它名字返回 400。

+ 上传：`POST /images`（multipart `file` 字段）返回 `{name}`，在 Markdown 里写

+ `` 引用。

+

+ ### 健康状态 `/health`

+

+ ```json

+ {

+ "status": "healthy",

+ "sync": "healthy",

+ "pull": "healthy",

+ "push": "healthy",

+ "lastPullAt": "2026-05-13 12:34:56",

+ "lastPullError": null,

+ "lastPushOkAt": "2026-05-13 12:30:01",

+ "lastPushError": null,

+ "dirty": false,

+ "dirtySince": null,

+ "imageQueueLength": 0

+ }

+ ```

+

+ - `sync` = `pull` 与 `push` 中较差者：`healthy` | `stale` | `offline`。`pull` 看最近一次成功拉取距今；

+ `push` 看本地待推送的写入（`dirty` / 图片队列）积压了多久

+ - 不是 healthy 时 `status = "degraded"`，HTTP 状态码 **503**，`lastPullError` / `lastPushError` /

+ `dirtySince` / `imageQueueLength` 说明原因。**降级只是信息**：API 仍可读写，写入会在

+ WebDAV 恢复后自动推送；读到的数据可能不是 PC 端的最新状态。CLI 的 `health` 照常输出 JSON、

+ 退出码 0，并在 stderr 打一行提示

+ - 每个鉴权通过的响应都带 `X-Sync-Status: healthy | stale | offline` 与

+ `X-Last-Sync-At: <最近一次成功拉取>`；offline 时还带 `Warning: 110 - "sync offline"`

+

+ # 新增（priority / dueDate 是别名，服务端存成 color / endTime）

+ -d '{"title":"买菜","priority":"high","endTime":"2026-05-20 18:00:00"}' \

+ # 部分更新（path 支持 C{seq} 短码或完整 i64 id）

+ **重复任务的人话描述**（用于 channel 推送）：

+ | 字段组合 | 描述 |

+ |---|---|

+ | `repeatType=daily, interval=1` | 每天 |

+ | `repeatType=daily, interval=N` | 每 N 天 |

+ | `repeatType=weekly, interval=1, weekdays="1,3,5"` | 每周的周一、周三、周五 |

+ | `repeatType=weekly, interval=2` | 每 2 周 |

+ | `repeatType=monthly, interval=1, monthDay=14` | 每月 14 号 |

+ | `repeatType=monthly, interval=3, monthDay=1` | 每 3 月 1 号 |

+ > 当 `repeatEnabled=true` 且 `notifyAt` 非空时，直接用 `notifyAt` 作为时间锚。

+ > 若 `notifyAt` 为空，则根据 `repeatType` 推算本期应触发时间（见 cron 流程步骤 2b）。

+ > 非重复任务按 `endTime` → `notifyAt` 顺序取第一个非空值。

+ `notifyAt`、不动 `endTime`；而服务端 query 只能按 `endTime` 筛——客户端硬

+ # 2. 编辑 ~/.openclaw/workspace/skills/minitodo/config.toml 填 endpoint + api_key（建议填 timezone）

+ 2. **对每条 todo，按以下优先级取"时间锚"**（所有时间都是 `YYYY-MM-DD HH:MM:SS`，服务端时区的墙钟）：

+ c. 否则按 `endTime` → `notifyAt` 顺序取第一个非空值

+ - 优先级映射：`priority` 字段 high → 高、medium → 中、low → 低；`priority` 为 null（自定义颜色）就省略 `[...]`

+ - 写入约 1.5 秒后推送到 WebDAV（连续写入最多攒 10 秒），PC 端要在自己的同步周期内才能拉到

+ - 删除会留下墓碑并双向同步，30 天内能拦截其它端把已删除记录"复活"；离线超过 30 天的设备

+ 再上线时，它手里的旧记录仍可能被恢复

+ - 同一条记录两端同时修改时按 `updatedAt` 整条取较新的一方（不做字段级合并）；写后立刻 `show` 校验最稳

+ └── config.toml # 你自己填，仅当前用户可读，gitignore 掉