dreamlonglll/mini-todo/minitodo

mini-todo Skill

让 Claude Code 通过云端 HTTP API 操作用户的 mini-todo 待办数据。底层数据通过 WebDAV 与 PC 端共享同一份 sync-data.json.gz：AI 的写入约 1.5 秒后（连续写入最多 攒 10 秒）推送到 WebDAV，PC 端下次同步即可见。

何时调用

用户说出下面意图时，先 Bash 调用本 skill 的 CLI：

• "今天有什么待办？" → python ~/.claude/skills/minitodo/minitodo.py today --json
• "未来 24h 有什么临期？" / 被 cron 唤起做提醒 → list --pending --json 后你自己按时间判断该推哪些
• "帮我加一个'买菜'到待办" → add
• "把 C3 / ID xxx 标记完成" → done C3（短码）或 done <i64-id>
• "看看所有未完成的高优先级" → list --pending --priority high
• "搜一下含'报告'的待办" → search
• "C3 / ID xxx 是什么？" → show C3
• "把 C3 / ID xxx 的截止时间改到 2026-05-20" → update C3 endTime=2026-05-20
• "删除 C3 / ID xxx" → delete C3

`C{seq}` 短码是 cloud 给每个 todo 分配的递增编号（响应 JSON 里 seq 字段），

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

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

非待办相关问题不要调用本 skill；它只覆盖 mini-todo 这一个领域。

安装

默认安装到 Claude Code 的 skill 目录；通过 --target 切到 openclaw 或两者都装。

bash install.sh                   # ~/.claude/skills/minitodo/（默认）
bash install.sh --target openclaw # ~/.openclaw/workspace/skills/minitodo/
bash install.sh --target both     # 两者都装

Windows 用户用 PowerShell 执行 .\install.ps1（参数相同：-Target claude/openclaw/both）， 或在 Git Bash / WSL / MSYS2 里执行上面的 bash 命令。脚本做三件事：

1. 把 SKILL.md / minitodo.py / config.example.toml 复制到目标 skill 目录
2. 如果 config.toml 不存在，把 config.example.toml 复制为 config.toml，并把权限收紧到

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

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

完成后必须确认本机有 Python 3 + requests：

python --version             # 3.10+ 推荐；3.10 需要 pip install tomli
pip install requests         # 必装
pip install tzdata           # 仅 Windows 且在 config.toml 里配置了 timezone 时需要

config.toml 字段：endpoint、api_key（必填）；timeout（秒，默认 10；sync 至少 90）； timezone（IANA 时区名，例如 Asia/Shanghai，today 用它计算"今天"；不填用本机时区， 建议与云端 / PC 一致）。

CLI 参考

全局 flag

• --config <path> 自定义 config.toml 路径
• --json 输出原始 JSON（AI 解析时务必使用）

退出码：0 成功（包括 health 报告同步降级）；2 配置 / 参数错误；3 网络错误（GET 已自动 重试 2 次）；4 服务端返回错误（stderr 是 HTTP <状态码>: <detail>），或 sync 的 pull / push 有一个失败（服务端回 207，JSON 照常输出）。

子命令

<ref> = C{seq} 短码（cloud 端 1, 2, 3... 自增）或完整 i64 id。C 大小写不敏感。

• --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 按字段类型解析：字符串字段（title / description / notes / color /

priority / 时间字段 / repeatType / repeatWeekdays）原样当字符串（title=2026 就是标题 "2026"），写 null 清空；其它字段自动解析 true / false / null / 数字 / JSON； quadrant= 接受别名（urgent_important 等）；字段名必须是下方字段表里的（或别名）， 否则服务端返回 400 并列出允许的字段。

常见任务 → 命令映射

直接调用 HTTP API（fallback）

CLI 不可用时，AI 可直接用 curl。所有请求都要 Authorization: Bearer <api_key>；写请求 body 是 JSON（Content-Type: application/json）。

排序字段白名单：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"。写入时也接受下面这些形式，服务端统一换成规范格式再保存：

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

只读 / 服务端维护的字段：id、createdAt、updatedAt、seq（cloud 短码）、subtasks、 subtaskCount（列表不嵌套时附带）。写入时这些字段会被忽略，所以把读到的对象改几个字段 后整包写回是安全的；对象里原样带回的 color / endTime / description 不会盖掉你对 priority / dueDate / notes 的修改（规范字段只有真的改了才优先于别名）。

其它任何字段一律 400（PC 端是强类型模型，不认识的字段会被静默丢掉）；类型不对同样 400。 错误体是 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 字段

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

图片

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

• 规范形式：![](minitodo-image://<name>) → 文件名就是 <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 里写 ![](minitodo-image://<name>) 引用。

alt 末尾可能带显示尺寸（PC 端拖动图片手柄写入，Obsidian 写法）：![截图|300](...) 显示宽 300、高按原图比例， ![截图|300x200](...) 宽高都指定。改写描述时原样保留；要指定大小也可以照这个写法写。

健康状态 /health

{
  "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"

curl 示例：

# 列表 + 排序
curl -H "Authorization: Bearer $KEY" \
  "https://minitodo.example.com/todos?completed=false&priority=high&sort=-dueDate"
 
# 新增（priority / dueDate 是别名，服务端存成 color / endTime）
curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title":"买菜","priority":"high","endTime":"2026-05-20 18:00:00"}' \
  https://minitodo.example.com/todos
 
# 部分更新（path 支持 C{seq} 短码或完整 i64 id）
curl -X PATCH -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"completed":true}' \
  https://minitodo.example.com/todos/C3
 
# 上传图片
curl -H "Authorization: Bearer $KEY" \
  -F "file=@/tmp/screenshot.png" \
  https://minitodo.example.com/images

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