dreamlonglll/minitodo

mini-todo Skill

让 Claude Code 通过云端 HTTP API 操作用户的 mini-todo 待办数据。底层数据通过 WebDAV 与 PC 端共享同一份 sync-data.json.gz，AI 写入 1 秒内会回写 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 dueDate=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 用户在 Git Bash / WSL / MSYS2 里执行同样的命令即可。脚本做三件事：

1. 把 SKILL.md / minitodo.py / config.example.toml 复制到目标 skill 目录
2. 如果 config.toml 不存在，把 config.example.toml 复制为 config.toml
3. 提示编辑 config.toml 填入 endpoint + api_key

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

python --version             # 3.10+ 推荐；3.10 需要 pip install tomli
pip install requests         # 必装

CLI 参考

全局 flag

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

子命令

| 子命令 | 说明 | 示例 | |---|---|---| | today | 今日相关（今天到期 ∪ 今天开始 ∪ 已逾期未完成） | python minitodo.py today --json | | add <title> | 新增待办 | python minitodo.py add "买菜" --priority high --due 2026-05-20 | | done <ref> | 标记完成 | python minitodo.py done C3 或 done 1734567890123456 | | list | 列表，可叠加 --pending / --completed / --priority / --limit / --sort | python minitodo.py list --pending --priority high --json | | search <kw> | 关键词搜索（title + notes） | python minitodo.py search "报告" --json | | show <ref> | 详情（默认含 subtasks） | python minitodo.py show C3 --json | | update <ref> <key=val>... | 修改字段，支持多个 | python minitodo.py update C3 dueDate=2026-06-01 priority=medium | | delete <ref> | 删除（连带 subtasks） | python minitodo.py delete C3 | | health | 健康检查 | python minitodo.py health --json | | sync | 手动触发 WebDAV 同步（pull + push） | python minitodo.py sync --json | | sync pull | 仅从 WebDAV 拉取最新数据 | python minitodo.py sync pull --json | | sync push | 仅推送本地变更到 WebDAV | python minitodo.py sync push --json |

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

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

常见任务 → 命令映射

| 用户问 | 一行命令 | |---|---| | 今天有什么 | python ~/.claude/skills/minitodo/minitodo.py today --json | | 还有几个高优先级没完成 | python ~/.claude/skills/minitodo/minitodo.py list --pending --priority high --json | | 新增"周五开会准备 PPT" | python ~/.claude/skills/minitodo/minitodo.py add "周五开会准备 PPT" --priority medium --json | | 完成 C3 | python ~/.claude/skills/minitodo/minitodo.py done C3 --json | | 把 C3 的截止日改到下周 | python ~/.claude/skills/minitodo/minitodo.py update C3 dueDate=2026-05-20 --json | | 删掉一周前完成的所有 | 先 list --completed --sort -updatedAt --json，再分别 delete C{seq} | | 确保数据是最新的 | python ~/.claude/skills/minitodo/minitodo.py sync --json |

直接调用 HTTP API（fallback）

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

| Method | Path | 用途 | |---|---|---| | GET /health | 服务健康（含 sync 状态） | | GET /todos?... | 列表；query: completed=true/false, priority=high/medium/low, quadrant=1-4 或 urgent_important 等别名, dueDateBefore, dueDateAfter, startDate=YYYY-MM-DD, q=<keyword>, sort=[+-]<field>, limit, offset, withSubtasks=true | | GET /todos/:id?withSubtasks=true | 详情 | | POST /todos | 创建；body 必填 title | | PATCH /todos/:id | merge 更新；未提及字段保留 | | DELETE /todos/:id | 删除（连带 subtasks） | | POST /todos/:id/subtasks | 创建子任务；body 必填 title | | PATCH /subtasks/:id | merge 更新子任务 | | DELETE /subtasks/:id | 删除子任务 | | GET /images/:name | 取图片 bytes | | POST /images | multipart 上传，file 字段；返回 {name} | | POST /sync | 手动触发 pull + push；返回 {pull, push, pullError?, pushError?} | | POST /sync/pull | 仅 pull；返回 {status: "ok"} | | POST /sync/push | 仅 push；返回 {status: "ok"} |

排序字段白名单：dueDate / startTime / priority / quadrant / sortOrder / updatedAt / createdAt / title。前缀 - 倒序、+ 或省略正序。

todo JSON 字段速查

GET /todos / GET /todos/:id 返回的对象是 PC 端 todo 原样透传（KV-style， PC 加新字段云端自动透传，不需要发版）。下面是临期提醒最常用到的一组字段：

| 字段 | 类型 | 说明 | |---|---|---| | seq | int（≥ 1） | cloud-only 短码。用户/LLM 反馈用 #C{seq} 引用，简短易读 | | id | int（i64 时间戳变体） | 跨设备唯一稳定的内部 id；推送时优先用 #C{seq}，缺时降级到 #{id} | | title | 字符串 | 任务名称 | | priority | "high" / "medium" / "low" / null | 优先级 | | completed | bool | 完成态；list --pending 已筛 false | | startTime | YYYY-MM-DD HH:MM:SS / 空 | 开始时间 | | endTime 或 dueDate | YYYY-MM-DD HH:MM:SS / 空 | 结束 / 截止时间。新版用 endTime，老数据可能用 dueDate | | notifyAt | YYYY-MM-DD HH:MM:SS / 空 | 下一次提醒时间。重复任务每次触发后只更新这个字段，endTime 不变 | | repeatEnabled | bool | 是否开启重复 | | repeatType | "daily" / "weekly" / "monthly" / null | 重复类型 | | repeatInterval | int，缺省 1 | 间隔；weekly + interval=2 = 每两周 | | repeatWeekdays | "1,3,5" / null | 仅 weekly：星期几（1=周一 … 7=周日） | | repeatMonthDay | int / null | 仅 monthly：每月几号 | | description | 字符串 | 备注 / 富文本说明 | | quadrant | 1-4 / null | 四象限分类 | | subtaskCount | int | 子任务数量（withSubtasks=false 时附带） |

重复任务的人话描述（用于 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 → dueDate → notifyAt 顺序取第一个非空值。

curl 示例：

# 列表 + 排序
curl -H "Authorization: Bearer $KEY" \
  "https://minitodo.example.com/todos?completed=false&priority=high&sort=-dueDate"

# 新增
curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title":"买菜","priority":"high","dueDate":"2026-05-20"}' \
  https://minitodo.example.com/todos

# merge 更新（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

响应头永远包含：

• X-Sync-Status: healthy | stale | offline —— 与 WebDAV 的同步状态
• X-Last-Sync-At: <时间字符串> —— 最近一次成功 pull/push
• Warning: 110 "sync offline" —— offline 时附带

X-Sync-Status=offline 时仍可读写，但写入暂不会反映到 PC（恢复后自动回写）。

在 openclaw 中启用临期提醒

整体范式：cron 定时唤起一个 isolated session，session prompt 让你 agent 自己 拉所有未完成 todo、根据用户偏好的临期窗口判断哪些该推、组织好格式后通过 --announce 推到 default channel（session history 中最近用过的 channel）。

为什么不让 skill 内置一个 due-soon 子命令？ mini-todo 的重复提醒只更新 notifyAt、不动 dueDate；而服务端 query 又只能按 dueDate 筛——客户端硬 编码规则永远会有漏推或误推。让 agent 看到原始 JSON、自己判断，更稳。

详细的安装 / 配置 / cron message 模板见仓库根 cloud/openclaw.md。

最简核心步骤（具体 prompt 见 cloud/openclaw.md）：

# 1. 装 skill 到 openclaw workspace
bash install.sh --target openclaw

# 2. 编辑 ~/.openclaw/workspace/skills/minitodo/config.toml 填 endpoint + api_key

# 3. 注册 cron（msg 里要求 agent 自己拉 list --pending --json + 判断）
openclaw cron add \
  --name minitodo-due-soon \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "<见 cloud/openclaw.md §7>" \
  --announce

agent 在 cron session 里要做的事

你被 cron 唤起做 mini-todo 临期提醒。严格按下面流程，不要做任何步骤外的事：

1. 获取数据：

   python ~/.openclaw/workspace/skills/minitodo/minitodo.py --json list --pending
   

2. 对每条 todo，按以下优先级取"时间锚"：

   a. 若 repeatEnabled == true 且 notifyAt 非空 → 用 notifyAt

   b. 若 repeatEnabled == true 且 notifyAt 为空 → 根据 repeatType 推算本次应触发时间：

   • monthly：取当月 repeatMonthDay 日的 00:00。若该日已过 → 算逾期。 逾期天数 = 当月当前日号 − repeatMonthDay。
   • weekly：如果 repeatWeekdays 包含今天 → 时间锚 = 今天 00:00。 若不包含今天，找 repeatWeekdays 中下一个最近的星期几，算出天数差。
   • daily：时间锚 = 今天 00:00。

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

   d. 全空则跳过该 todo（纯备忘类不推送）

3. 判断临期——用当前墙钟时间 now（Asia/Shanghai）和窗口 H = 12 小时：

   • 时间锚 < now → "已逾期"（显示逾期多久）
   • now ≤ 时间锚 ≤ now + 12h → "未来 12h 到期"（显示还有多久）
   • 时间锚 > now + 12h → 跳过

4. 仅当 repeatEnabled == true 时，把 repeat* 字段翻译成中文：

   | 条件 | 描述 | |---|---| | monthly, interval=1, monthDay=D | 每月 D 号 | | weekly, interval=1, weekdays="1,3,5" | 每周的周一、周三、周五 | | daily, interval=1 | 每天 | | interval=N（N > 1） | 每 N 天 / 周 / 月 |

   weekdays 映射：1=周一、2=周二、3=周三、4=周四、5=周五、6=周六、7=周日。

5. 严格按下面格式输出，不要加任何解释 / 翻译 / 总结：

   mini-todo 临期提醒｜YYYY-MM-DD HH:MM
   已逾期（N）：
   - #C{seq} [优先级] 标题 (MM-DD HH:MM，已逾期 X 小时｜重复描述)
   未来 12h 到期（M）：
   - #C{seq} [优先级] 标题 (MM-DD HH:MM，X 小时后｜重复描述)
   

   • 优先级映射：high → 高、medium → 中、low → 低，没有就省略 [...]
   • 前缀优先用 #C{seq}（短码，用户回复"完成 C3"更顺手）；若 JSON 缺 seq 字段则降级用 #{id} 完整 i64 id
   • 非重复任务省略 ｜重复描述
   • 时间差显示规则：< 60 分钟用 "X 分钟后"，< 24h 用 "X 小时后"，≥ 24h 用 "X 天后"；逾期同理
   • 示例：- #C3 [中] 月度回顾 (05-14 09:00，已逾期 3 小时｜每月 14 号)

6. 如果两组都为空，只输出一行 12h 内无临期事项，不要再加任何字。

已知限制

• 单用户、单 API key（云端 config.toml 配）
• 写入 ~1s 延迟才能反映到 WebDAV，PC 端要在自己的同步周期内才能拉到
• 删除会留下软删除墓碑（7 天内会拦截远端"复活"），跨 7 天的离线设备复活该 ID 仍可能恢复
• 不支持移动端
• 同字段同时改可能丢一方（mini-todo 单用户极少触发；写后立刻 show 校验最稳）

安装目录约定

最终运行时结构：

~/.claude/skills/minitodo/
├── SKILL.md
├── minitodo.py
├── config.example.toml
└── config.toml          # 你自己填，gitignore 掉