运行前提
需要 Node.js ≥ 20；命令在仓库的 todo-app 目录下执行：
node cli/todo-cli.js <command> [args] [--json]
给 AI 助手用时始终加 --json：输出 {ok, command, data} 包络，写操作附带 next 字段提示后续命令。
应用正在运行时，CLI 写入约 2 秒内自动同步到界面，无需重启。
通用约定
日期参数
日期参数统一支持：today / tomorrow / +3d / YYYY-MM-DD / "YYYY-MM-DD HH:mm"。
错误与退出码
错误走 stderr 并带非零退出码。常见错误码：AMBIGUOUS_MATCH（关键词命中多条，换更精确关键词或用完整 taskId，不要猜）、TASK_NOT_FOUND、NEEDS_CONFIRM（危险操作缺确认）。
返回与级联
list / search 默认最多返回 200 条（--limit 可调，上限 500）；完成父任务默认连带勾选全部子任务（--no-sub-cascade 关闭）。
审计流水
每次写操作自动落审计流水（数据目录 cli-audit.jsonl），log 命令可查询——向别人汇报「AI 改了什么」时引用它。
读取命令
| todo-cli … | 作用 | 示例 |
|---|---|---|
| overview | 今日总览：完成度 / 逾期 / 无日期 / 回收站计数 | todo-cli overview --json |
| list | 列任务：支持 --all|today|tomorrow|week|overdue|future、--done|--undone、--category、--keyword、--limit | todo-cli list today --undone --json |
| search | 全库搜索：按关键词搜内容与描述 | todo-cli search "周报" --json |
| get | 查看单个任务完整字段（支持 taskId 或关键词定位） | todo-cli get "写周报" --json |
| categories | 分类列表（id 与名称） | todo-cli categories --json |
| stats | 统计：每日完成量 + 专注分钟（默认近 7 天，可 --from/--to 指定区间） | todo-cli stats --from 2026-08-01 --json |
| recycle | 回收站列表 | todo-cli recycle --json |
| doctor | 环境自检（数据目录、依赖与配置体检） | todo-cli doctor |
| log | 审计流水查询：外部写操作历史（--n 条数，--action 过滤） | todo-cli log --n 20 --json |
写入命令
| todo-cli … | 作用 | 示例 |
|---|---|---|
| add | 新增任务：--desc 描述、--date、--reminder、--category、--difficulty | todo-cli add "写周报" --date friday --category 工作 |
| done | 完成任务（写 completedAt） | todo-cli done "周报" --json |
| undo | 撤销完成 | todo-cli undo "周报" |
| edit | 编辑：--content 新标题、--desc、--date、--reminder、--category | todo-cli edit "周报" --date monday |
| delete | 删除（进回收站，可恢复） | todo-cli delete "旧任务" |
| restore | 从回收站恢复 | todo-cli restore "旧任务" |
| import | 从其他应用一键迁移：滴答清单 / TickTick / Todoist 备份 CSV；--dry-run 先预览，重复任务自动去重 | todo-cli import ticktick-backup.csv --dry-run |
purge 是本接口唯一不可恢复的操作。清空回收站前必须：先跑 purge --dry-run 看清单 → 用户明确确认 → 带 --yes 执行。三者缺一不可。
番茄命令
| todo-cli tomato … | 作用 | 示例 |
|---|---|---|
| start | 开始专注（可 --task 附着任务、--minutes 自定义时长） | todo-cli tomato start --task "写周报" --json |
| stop | 停止 / 放弃（默认按已专注时长落账，--reason 记原因） | todo-cli tomato stop --reason "被人打断" |
| attach | 给进行中的番茄换绑 / 取消附着任务（--none） | todo-cli tomato attach "新任务" |
| status | 查看番茄状态（倒计时 / 附着任务 / 今日收成） | todo-cli tomato status --json |
接入 AI 助手
把 CLI 注册成 Claude、Cursor 等 AI 助手的工具，它就能直接替你管任务。仓库内附带现成的技能描述文件（todo-app/cli/SKILL.md），助手的接入配置可直接引用。人和 AI 读写同一个本地库，不存在第二份需要同步的数据。