运行前提
需要 Node.js ≥ 22。下文示例统一简写为 pickdone——装机用户实际调用 node "%LOCALAPPDATA%\Programs\PickDone\resources\cli\pickdone.js"，开发者在仓库 pickdone/ 目录下：
node cli/pickdone.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 改了什么」时引用它。
读取命令
| pickdone … | 作用 | 示例 |
|---|---|---|
| overview | 今日总览：完成度 / 逾期 / 无日期 / 回收站计数 | pickdone overview --json |
| list | 列任务：支持 --all|today|tomorrow|week|overdue|future、--done|--undone、--category、--keyword、--limit | pickdone list today --undone --json |
| search | 全库搜索：按关键词搜内容与描述 | pickdone search "周报" --json |
| get | 查看单个任务完整字段（支持 taskId 或关键词定位） | pickdone get "写周报" --json |
| categories | 分类列表（id 与名称） | pickdone categories --json |
| stats | 统计：每日完成量 + 专注分钟（默认近 7 天，可 --from/--to 指定区间） | pickdone stats --from 2026-08-01 --json |
| recycle | 回收站列表 | pickdone recycle --json |
| doctor | 环境自检（数据目录、依赖与配置体检） | pickdone doctor |
| log | 审计流水查询：外部写操作历史（--n 条数，--action 过滤） | pickdone log --n 20 --json |
写入命令
| pickdone … | 作用 | 示例 |
|---|---|---|
| add | 新增任务：--desc 描述、--date、--reminder、--category、--difficulty | pickdone add "写周报" --date friday --category 工作 |
| done | 完成任务（写 completedAt） | pickdone done "周报" --json |
| undo | 撤销完成 | pickdone undo "周报" |
| edit | 编辑：--content 新标题、--desc、--date、--reminder、--category | pickdone edit "周报" --date monday |
| delete | 删除（进回收站，可恢复） | pickdone delete "旧任务" |
| restore | 从回收站恢复 | pickdone restore "旧任务" |
| import | 从其他应用一键迁移：滴答清单 / TickTick / Todoist 备份 CSV；--dry-run 先预览，重复任务自动去重 | pickdone import ticktick-backup.csv --dry-run |
番茄命令
| pickdone tomato … | 作用 | 示例 |
|---|---|---|
| start | 开始专注（可 --task 附着任务、--minutes 自定义时长） | pickdone tomato start --task "写周报" --json |
| stop | 停止 / 放弃（默认按已专注时长落账，--reason 记原因） | pickdone tomato stop --reason "被人打断" |
| attach | 给进行中的番茄换绑 / 取消附着任务（--none） | pickdone tomato attach "新任务" |
| status | 查看番茄状态（倒计时 / 附着任务 / 今日收成） | pickdone tomato status --json |
接入 AI 助手
装好拾事与 Node.js 后，把 CLI 的调用契约交给你的 AI 工具，它就能直接替你管任务。人和 AI 读写同一个本地库，不存在第二份需要同步的数据。
node "%LOCALAPPDATA%\Programs\PickDone\resources\cli\pickdone.js" skill install
Claude Code / ZCode 一条命令即完成接入；Cursor、Codex CLI、OpenCode、Gemini CLI 等其他工具，见「AI 接入」页的分平台方法。