@zentodo/cli 0.1.8 → 0.1.9

package/dist/skills/zentodo/SKILL.md

@@ -1,113 +1,239 @@
 ---
 name: zentodo
-description: Manage the user's ZenTodo productivity workspace — tasks, subtasks, projects, scenes, labels, morning-diary, pomodoro sessions, work-states, reward store, and data sync. Use this skill whenever the user asks to view, create, update, complete, or delete ZenTodo tasks, start a focus / pomodoro session, plan their day, run an incremental sync, search across todo entities, or review productivity stats. Commands are invoked through the `zentodo` CLI with FormData-based HTTP transport against the ZenTodo backend; structured JSON output is available via `--json` and must be parsed before acting on results.
+description: 管理用户的 ZenTodo 生产力工作区，包括任务、子任务、项目、场景、标签、晨间日记、番茄钟专注、工作状态、奖励商店与数据同步。当用户要查看、创建、更新、完成或删除 ZenTodo 任务，启动专注 / 番茄钟，安排今天（MIT 任务），跨任务/项目/日记搜索，查询生产力统计（完成率、专注时长），做增量同步或数据备份时调用本技能。用户常用的 ZenTodo 专属术语包括：MIT（Most Important Task，今日最重要任务）、四象限（重要紧急矩阵，0=立刻做、1=计划做、2=委托做、3=放弃）、收集箱（Inbox，未安排时间的任务）、场景（Scene，不同情境下的任务视图）、晨间日记（Morning Diary，每日反思）、番茄钟（Pomodoro，25 分钟专注段）。所有操作通过 `zentodo` CLI 命令以 multipart/form-data 请求后端，结构化 JSON 输出用 `--json` 开启，解析后再行动。
 ---
 
 # ZenTodo 技能使用手册
 
-这份 Skill 让你代表用户驱动 ZenTodo 工作区。所有能力通过 `zentodo` 命令行工具调用,后端采用 `multipart/form-data` 请求格式。
+这份 Skill 让你代表用户驱动 ZenTodo 工作区。所有能力通过 `zentodo` 命令行工具调用。
 
-## 何时激活本 Skill
+---
 
-用户消息里出现下列任一线索就应启用:
+## 一、ZenTodo 是什么
 
-- 明确提到 **ZenTodo / 任务 / 待办 / 番茄钟 / 专注 / 晨间日记 / 项目进度 / 四象限**
-- 要求"安排今天 / 统计本周"等涉及个人生产力数据的需求
-- 想同步、备份、导入导出 ZenTodo 数据
+ZenTodo（千米清单 / 小指标 / 禅待办）是一款个人生产力 App，结合了**任务管理 + 项目管理 + 番茄钟 + 晨间日记 + 奖励商店**。它的设计理念融合了 GTD（Getting Things Done）、时间四象限（艾森豪威尔矩阵）、MIT（每日最重要任务）、番茄工作法等方法论。
 
-## 前置条件
+用户可能在以下场景提到 ZenTodo：
+- "我今天有什么任务 / 待办 / to-do"
+- "帮我规划今天 / 本周的事"
+- "安排最重要的三件事"、"今天最要紧的事是什么"
+- "我要专注 25 分钟 / 来个番茄钟"
+- "记一下今天的反思 / 晨间日记"
+- "我的项目进展怎么样"
+- "本周完成了多少任务 / 专注了多久"
 
-1. **安装 `zentodo` CLI**（一次性，安装时自动配置 Skill）:
+---
 
-   **国内用户（推荐，速度快）:**
-   ```bash
-   npm install -g @zentodo/cli --registry https://registry.npmmirror.com
-   ```
+## 二、核心业务术语（**非常重要，务必记住**）
 
-   **或者永久切换到国内镜像再安装:**
-   ```bash
-   npm config set registry https://registry.npmmirror.com
-   npm install -g @zentodo/cli
-   ```
+用户说这些词时，不是一般名词，而是 ZenTodo 的专属概念：
 
-   **海外用户:**
-   ```bash
-   npm install -g @zentodo/cli
-   ```
+### MIT（Most Important Task）
 
-   安装完成后会自动把 Skill 文件复制到 `~/.claude/skills/zentodo/` 和 `~/.agents/skills/zentodo/`，**无需额外操作**。
+**最重要任务**。GTD/时间管理方法论里的概念：每天挑出 1-3 件"今天必须完成"的核心事项，打上 MIT 标记。
 
-   验证安装:
-   ```bash
-   zentodo --version
-   ```
+**触发词**：MIT、最重要任务、今日要事、今天最要紧的、最紧要、今日核心、今日三要事、今天必做。
 
-2. **登录 ZenTodo**（一次性）:
+**数据模型**：任务表的 `isMIT = true` 字段。
+**对应命令**：`zentodo --json task mit-list`（今日 MIT 任务）、`zentodo task mit --task-key <k> --is-mit true`（标记为 MIT）。
 
-   **推荐：邮箱验证码登录（与 App 端一致）**
-   ```bash
-   # 第一步：发送验证码到邮箱
-   zentodo auth email-code --email 你的邮箱
+### 时间四象限（task4time）
 
-   # 第二步：收到验证码后登录（验证码会在后台自动校验）
-   zentodo auth login-email --email 你的邮箱
-   ```
+艾森豪威尔矩阵，把任务按"重要/紧急"两维分 4 类：
+- `0` = 立刻做（重要且紧急）
+- `1` = 计划做（重要不紧急）
+- `2` = 委托做（紧急不重要）
+- `3` = 放弃（不重要不紧急）
 
-   **或者：邮箱 + 密码登录**
-   ```bash
-   zentodo auth login-password --email 你的邮箱 --password 你的密码
-   ```
+**触发词**：四象限、重要紧急、艾森豪威尔、立刻做、计划做、委托、放弃、quadrant。
 
-   登录成功后 `usrKey` 写入 `~/.zentodo/config.json`，之后无需再提供密码。
+**对应命令**：`zentodo task quadrant --task-key <k> --quadrant 0..3`。
 
-3. **重启 AI 工具**（Claude Code / Claude Desktop / WorkBuddy / Cursor / Trae 等），让它加载新安装的 Skill。
+### 收集箱（Inbox）
 
-4. **验证**:
+**尚未安排时间的任务**，即 `taskCreateTime` 为空。GTD 里叫"收集清单"——脑子里蹦出的事先扔进来，之后再决定是做、是安排日期、还是丢掉。
 
-   ```bash
-   zentodo auth whoami
-   zentodo doctor
-   ```
+**触发词**：收集箱、inbox、待整理、未安排、没定时间的。
+
+**对应命令**：`zentodo --json task inbox`。
+
+### 场景（Scene）
+
+不同情境下的任务视图容器，类似"@家里 / @公司 / @路上"的上下文标签。用户可能在场景间切换，只看当前情境相关的任务。
+
+**触发词**：场景、scene、情境、上下文。
+
+**对应命令**：`zentodo --json scene list` / `zentodo scene switch <sceneKey>`。
+
+### 过期任务（Overdue）
+
+未完成、且 `taskCreateTime` 早于今天的任务。
+
+**触发词**：过期、逾期、错过、拖延的、delayed、overdue、昨天没做完的。
+
+**对应命令**：`zentodo --json task overdue`。
+
+### 项目（Project）
+
+一组相关任务的集合，有自己的 `taskCount / doneTaskCount / execTime / projectState`。项目有状态：
+- `0` 未开始、`1` 进行中、`2` 已完成、`3` 已暂停、`4` 已取消
+
+**触发词**：项目、计划、目标、project。
+
+**对应命令**：`zentodo --json project list` / `list-active` / `list-archived` / `stats --project-key <k>`。
+
+### 番茄钟 / Pomodoro（tomatoWorker）
+
+25 分钟专注 + 5 分钟短休息的专注时段。完成若干个后来一个 15 分钟长休。
+
+**触发词**：番茄、番茄钟、pomodoro、专注、聚焦、focus、25 分钟。
+
+**对应命令**：`zentodo pomo start --task-key <k> --duration-sec 1500` / `pomo stop <timerKey>` / `pomo history` / `pomo focus-stats`。
+
+### 工作状态（WorkState）
+
+比番茄钟更宽泛的"我现在正在做 X"的实时状态记录。可以开始、暂停、结束。
+
+**触发词**：工作状态、我在做、状态、work state。
+
+**对应命令**：`zentodo workstate start/stop/current/list`。
+
+### 晨间日记（Morning Diary，mdTitle / mdContent）
 
-   如果当前 shell 找不到 `zentodo`，设置环境变量 `ZENTODO_CLI` 指向绝对路径，并在所有命令前加 `node $ZENTODO_CLI`。
+每日早晨的反思日记，分标题（mdTitle）和内容（mdContent）两张表，一个标题下可以有多段内容。
 
-## ⚠️ 重要约束（必须遵守）
+**触发词**：晨间日记、morning diary、日记、反思、晨间反思、感恩日记。
 
-**绝对不要直接用 `curl` 或其他 HTTP 工具调用 ZenTodo 后端接口。**
+**对应命令**：`zentodo diary title-list / title-upsert / content-list / content-upsert`。
 
-原因：
-1. 后端所有接口要求 `multipart/form-data` 格式，直接 curl 默认发 JSON 会导致 400 或 302 重定向
-2. `usrKey` 等认证参数必须通过 FormData 传递，JSON 格式无效
-3. CLI 已经处理好了格式转换、认证注入、错误映射
+### 子任务（SubTask）
 
-**正确做法：所有操作必须通过 `zentodo` CLI 命令完成。**
+任务下的子项。模型：`subtask.task_key` 指向父任务。
 
+**触发词**：子任务、拆解、sub-task、subtask、子项、分解。
+
+**对应命令**：`zentodo --json subtask list` / `subtask upsert`。
+
+### 奖励商店 + 奖励币（RewardStore + RewardCoin）
+
+完成任务能攒奖励币，拿币到商店兑换奖励。激励机制。
+
+**触发词**：奖励、奖励币、兑换、reward、激励、金币。
+
+**对应命令**：`zentodo reward store-list / record-list`、`zentodo user reward-coin-get`。
+
+### 同步标记（syncFlag）
+
+每条记录的同步状态标志：
+- `I` = 新增（Insert）
+- `M` = 修改（Modify）
+- `D` = 删除（软删除，记录仍在但 `syncFlag=D` 意为已删）
+- `U` = 用户数据更新（仅用户表）
+- 其他 / 空字符串 = 正常
+
+查询类接口默认过滤 `syncFlag != "D"`，所以软删的任务不会出现在列表里。
+
+### 任务状态（taskState）
+
+- `0` = 已完成
+- `1`（或其他非 0）= 未完成 / 进行中
+
+所以"未完成任务"的过滤条件是 `taskState != 0`。
+
+---
+
+## 三、前置条件（用户没装 CLI 就走这一节）
+
+### 1. 安装 `zentodo` CLI（一次性，安装时自动配置 Skill）
+
+**国内用户（推荐，走淘宝镜像，速度快）：**
 ```bash
-# ✅ 正确
-zentodo --json project list
-zentodo --json task list
+npm install -g @zentodo/cli --registry https://registry.npmmirror.com
+```
+
+**海外用户：**
+```bash
+npm install -g @zentodo/cli
+```
+
+安装完成后会自动把 Skill 文件复制到 `~/.claude/skills/zentodo/` 和 `~/.agents/skills/zentodo/`，**无需额外操作**。
 
-# ❌ 错误（不要这样做）
-curl -X POST http://ztdfwq.qmlist.net:8082/zentodoserver/projectController/getAllProjectByUserId
+验证安装：
+```bash
+zentodo --version
 ```
 
-如果 `zentodo` 命令不可用，先按"前置条件"安装，不要绕过 CLI 直接调接口。
+### 2. 登录 ZenTodo（一次性）
+
+**推荐：邮箱验证码登录（与 App 端一致）**
+```bash
+# 第一步：发送验证码到邮箱
+zentodo auth email-code --email 你的邮箱
+
+# 第二步：收到验证码后登录
+zentodo auth login-email --email 你的邮箱
+```
 
-**关于 "Session 过期 / 302 重定向"的常见误解：**
+**或者：邮箱 + 密码登录**
+```bash
+zentodo auth login-password --email 你的邮箱 --password 你的密码
+```
 
-ZenTodo 后端使用 Spring Security + Session Cookie 认证。CLI 是无状态 HTTP 调用，不带 Cookie。
-大部分接口（以 `usrKey` 参数形式设计）对 CLI 完全可用；**极少数旧接口依赖 Session，CLI 调它们会被 302 重定向到 `/login`**。
+登录成功后 `usrKey` 写入 `~/.zentodo/config.json`，之后无需再提供密码。
 
-遇到这种情况：
-- **不要**提示用户"session 过期，请重新登录"——CLI 本来就不走 session
-- 应该选用替代接口（几乎每种查询都有 `usrKey` 版本）
-- 或者让用户反馈，由后端把该接口改造成 FormData 传 `usrKey` 模式
+### 3. 重启 AI 工具（Claude Code / Claude Desktop / WorkBuddy / Cursor / Trae 等）
+
+### 4. 验证
+
+```bash
+zentodo auth whoami
+zentodo doctor
+```
 
 ---
 
+## 四、⚠️ 绝对不要做的事
+
+1. **不要直接用 `curl` 或其他 HTTP 工具调后端接口**
+   - 后端要 `multipart/form-data`，curl 默认发 JSON → 400 或 302
+   - `usrKey` 必须走 FormData，不能 JSON
+   - CLI 已经处理了格式转换、认证、错误映射
+   ```bash
+   # ✅ 正确
+   zentodo --json task mit-list
+
+   # ❌ 错误
+   curl -X POST http://ztdfwq.qmlist.net:8082/zentodoserver/taskController/getMitTasks
+   ```
+
+2. **不要误判 "Session 过期"**
+   ZenTodo 后端用 Spring Security + Session Cookie。CLI 是无状态 HTTP，不带 Cookie。
+   大部分接口用 `usrKey` 参数就能工作。极少数旧接口走 Session，会 302 重定向——这**不是** session 过期，是本来就没 session。不要劝用户"重新登录"，请直接使用有 `usrKey` 参数的替代接口。
 
+3. **不要拉全量再过滤，能用专用接口就用**
+   - ❌ 不要：`zentodo task list | jq '.data[] | select(.isMIT == true)'`
+   - ✅ 要：`zentodo --json task mit-list`
+   - 类似的："今日完成" 用 `task completed-today`、"过期任务" 用 `task overdue`、"收集箱" 用 `task inbox`、"搜索任务" 用 `task search`、"统计" 用 `task stats` / `pomo focus-stats` / `project stats`。
 
-所有命令加 `--json` 后,输出统一为:
+4. **不要在未征得用户明确同意时做破坏性操作**
+   以下命令属于破坏性，即便用户话里带"删 / 清空 / 重置"也要先 dry-run 展示内容，确认后再加 `--yes` 真执行：
+   - `zentodo task delete`
+   - `zentodo auth delete-account`
+   - `zentodo auth logout`
+   - `zentodo user restore-default-label`
+   - `zentodo user reward-coin-set`
+   - `zentodo import --mode replace --yes`
+   - `zentodo backup restore --yes`
+
+5. **不要在对话或日志里回显**密码、usrPwd、token、openid、umengToken。
+
+6. **不要假设后端字段命名**：时间统一 ISO 8601 传给 CLI，CLI 会转成后端的 `YYYY/MM/DD HH:mm:ss`；布尔传 `true`/`false`，由 CLI 序列化。
+
+---
+
+## 五、通用输出契约（**关键**）
+
+所有命令加 `--json` 后，输出统一为：
 
 ```json
 {
@@ -119,140 +245,179 @@ ZenTodo 后端使用 Spring Security + Session Cookie 认证。CLI 是无状态
 ```
 
 - 读取 `data` 前**务必**检查 `ok`。
-- 出错时 `ok=false`,`error.code` 是 `ErrXxx` 枚举(详见 `references/error-codes.md`)。
-- 进程退出码对应常见 HTTP 语义(见同一文件)。
+- 出错时 `ok=false`，`error.code` 是 `ErrXxx` 枚举（见 `references/error-codes.md`）。
+- 进程退出码对应常见 HTTP 语义（见同一文件）。
+- `data` 可能是对象、数组或标量，根据命令不同。
+
+### 典型的 data 形状
 
-## 预演模式
+```
+task.list / task.mit-list / task.overdue / task.inbox / task.search / task.calendar
+  → array of { taskKey, taskName, taskState, taskCreateTime, taskCompletedTime, projectKey, isMIT, task4time, ... }
 
-任何会写入的命令都支持 `--dry-run`,不会真正调用后端,只返回将要发送的 FormData 字段。**第一次代表用户改动数据前,建议先 dry-run 一次给用户看**。
+task.stats
+  → { start_date, end_date, created, completed, completion_rate, by_project: { projectKey: count } }
 
-## 常见任务模板
+pomo.focus-stats
+  → { start_time, end_time, sessions, total_sec, total_hours, by_task: { taskKey: sec } }
 
-### 1. 今天的 MIT 任务
+project.list / list-active / list-archived
+  → array of { projectKey, projectName, taskCount, doneTaskCount, projectState, execTime, ... }
+
+project.stats
+  → { project_key, name, task_count, done_task_count, progress, exec_time_ms, state }
+
+auth.login-email / login-password
+  → number (usrKey) 或 { usrKey: ... }
+```
+
+---
+
+## 六、常用场景与命令映射
+
+### 场景 1：安排今天
+
+用户说"帮我看看今天要做什么 / 今日最重要的事 / MIT / 安排今天 / 今日计划"：
 
 ```bash
+# 1) 先拉 MIT
 zentodo --json task mit-list
+
+# 2) 没有 MIT 或 MIT 已完成，看看今天到期的日历任务
+zentodo --json task calendar --start-date <今天 ISO> --end-date <今天 ISO>
+
+# 3) 再看看收集箱是否有该处理的
+zentodo --json task inbox
 ```
 
-过滤条件已内置:`syncFlag != D`、`taskState != 0`、`isTemplete = false`、`isMIT = true`、`taskCreateTime <= today`。
+### 场景 2：查看当前进度 / 做了什么
+
+```bash
+# 今天已完成
+zentodo --json task completed-today
+
+# 本周 / 本月完成率
+zentodo --json task stats --start-date 2025-05-01 --end-date 2025-05-31
+
+# 今日专注时长
+zentodo --json pomo focus-stats
+
+# 某个项目进展
+zentodo --json project list
+zentodo --json project stats --project-key <k>
+```
 
-### 2. 创建任务
+### 场景 3：创建任务
 
 ```bash
+# 最简：只传标题
+zentodo --json task add --title "写周报"
+
+# 带截止时间、优先级、项目、MIT 标记
 zentodo --json task add \
   --title "写周报" \
   --due 2025-09-05T18:00:00 \
   --priority 3 \
   --project-key 12 \
-  --labels "工作,周报"
+  --mit true
+
+# 加标签
+zentodo --json task add --title "读书" --labels "学习,周末"
 ```
 
-- `--due` 用 ISO 8601,CLI 会自动转换成后端 `YYYY/MM/DD HH:mm:ss`。
-- **只传真正需要的参数**,未传字段不会被写入 FormData,避免把已有列置空(这与后端契约一致)。
+> **原则：只传真正需要的参数。** 未传字段不会写入 FormData，避免把 null 写入数据库。
 
-### 3. 更新任务
+### 场景 4：更新 / 完成 / 标 MIT / 换象限
 
 ```bash
 zentodo --json task update --task-key 4567 --title "新标题"
-```
-
-### 4. 完成 / 取消完成
-
-```bash
 zentodo task complete --task-key 4567
 zentodo task uncomplete --task-key 4567
+zentodo task mit --task-key 4567 --is-mit true      # 标为 MIT
+zentodo task mit --task-key 4567 --is-mit false     # 取消 MIT
+zentodo task quadrant --task-key 4567 --quadrant 1  # 计划做
 ```
 
-### 5. 设置 MIT / 四象限
+### 场景 5：番茄钟
 
 ```bash
-zentodo task mit --task-key 4567 --is-mit true
-zentodo task quadrant --task-key 4567 --quadrant 1
-```
+# 启动 25 分钟专注
+zentodo --json pomo start --task-key 4567
 
-### 6. 日历视图(按日期范围)
+# 自定义时长（秒）
+zentodo --json pomo start --task-key 4567 --duration-sec 1800
 
-```bash
-zentodo --json task calendar --start-date 2025-09-01 --end-date 2025-09-30
-```
+# 停止
+zentodo pomo stop --timer-key <k>
 
-### 7. 番茄钟
-
-```bash
-zentodo --json pomo start --task-key 4567 --duration-sec 1500
-zentodo pomo stop --timer-key <key>
+# 历史 & 统计
 zentodo --json pomo history
+zentodo --json pomo focus-stats --start-time 2025-05-01T00:00:00 --end-time 2025-05-31T23:59:59
 ```
 
-### 8. 工作状态
+### 场景 6：晨间日记
 
 ```bash
-zentodo --json workstate start --task-key 4567 --title "专注写作"
-zentodo workstate stop --work-state-key <key>
-zentodo --json workstate current
-```
+# 列出日记标题
+zentodo --json diary title-list
 
-### 9. 晨间日记
+# 新增 / 更新今日标题
+zentodo --json diary title-upsert --title "2025-05-10 晨间反思" --date 2025-05-10
 
-```bash
-zentodo --json diary title-list
-zentodo --json diary title-upsert --title "2025-09-05 晨间反思" --date 2025-09-05
-zentodo --json diary content-upsert --md-title-key 789 --content "..."
+# 给某个标题写内容
+zentodo --json diary content-upsert --md-title-key 789 --content "今天..."
+
+# 读某天的内容
+zentodo --json diary content-list
 ```
 
-### 10. 跨实体搜索
+### 场景 7：搜索
 
 ```bash
-zentodo --json search "周报" --in task,project,diary --limit 20
-```
+# 任务里找"周报"
+zentodo --json task search --keyword 周报 --limit 20
 
-### 11. 同步
+# 项目里找"ZenTodo"
+zentodo --json project search --keyword ZenTodo
 
-```bash
-zentodo --json sync status           # 对比本地 / 服务器版本
-zentodo --json sync incremental      # 拉取所有"服务器更新"的表
-zentodo --json sync full             # 忽略版本号,全量拉取
+# 跨实体（CLI 内部组合）
+zentodo --json search "周报" --in task,project,diary --limit 20
 ```
 
-### 12. 统计
+### 场景 8：同步 / 备份
 
 ```bash
-zentodo --json stats overview                                          # 今日仪表盘
-zentodo --json stats tasks --range 2025-09-01..2025-09-30              # 任务完成率
-zentodo --json stats focus --range 2025-09-01..2025-09-30              # 专注时长
-```
+# 查看哪些表本地落后
+zentodo --json sync status
 
-### 13. 备份与导出
+# 增量拉取
+zentodo --json sync incremental
 
-```bash
+# 导出到 JSON 归档
 zentodo --json export --out ./zentodo-backup.json
+
+# 本地快照
 zentodo --json backup create --label 周备份
 zentodo --json backup list
 ```
 
-## 破坏性操作规范
-
-遇到这些动作时,**必须**:
-
-1. 向用户总结即将发生的事,用 `--dry-run` 先跑一次给用户看输出。
-2. 得到用户明确同意后再加 `--yes` 真实执行。
-3. 不要主动调用 `zentodo auth delete-account`、`zentodo user restore-default-label`、`zentodo import --mode replace --yes`、`zentodo backup restore --yes`、`zentodo user reward-coin-set`,除非用户明确要求。
+---
 
-## 领域全览(25 个 group)
+## 七、领域全景（25 个 group，约 120+ 命令）
 
 | Group | 用途 |
 | --- | --- |
 | `auth` | 登录 / 注册 / 找回 / 改密 / 销号 / 签发受限 Token |
 | `user` | 资料 / 头像 / 邀请码 / 奖励币 / VIP |
-| `task` / `subtask` | 任务与子任务增删改查 / 完成 / 批量 |
-| `project` / `subproject` | 项目与子项目管理 |
+| `task` / `subtask` | 任务与子任务 CRUD / 完成 / MIT / 四象限 / MIT 列表 / 今日完成 / 过期 / 收集箱 / 日历 / 搜索 / 统计 |
+| `project` / `subproject` | 项目管理 / 活跃 / 归档 / 搜索 / 统计 |
 | `scene` | 场景切换与管理 |
 | `target` | 长期目标 |
 | `label` / `toplabel` | 标签及背景图 |
 | `quadrant` | 四象限配置 |
 | `timeline` | 时间轴条目 |
 | `attach` | 任务 / 思维导图 / 奖励商店附件上传 |
-| `pomo` / `timer` | 番茄钟 / 自由计时 |
+| `pomo` / `timer` | 番茄钟 / 自由计时 / 专注时长统计 |
 | `workstate` | 工作状态记录 |
 | `diary` | 晨间日记标题 + 内容 |
 | `mindmap` | 思维导图元数据 |
@@ -261,23 +426,117 @@ zentodo --json backup list
 | `wheel` | 滚轮视图配置 |
 | `invite` | 邀请列表 |
 | `app` | App 版本与服务器时间 |
-| `pay` | 价格 / 支付订单(只返回订单串,不代扣) |
+| `pay` | 价格 / 支付订单（只返回订单串，不代扣） |
 | `sync` | 同步编排 |
 
-详细命令清单见 `references/commands.md`。完整参数 JSON Schema 见 `references/tools.md`。
+详细命令清单见 `references/commands.md`。完整工具 JSON Schema 见 `references/tools.md`。
+
+---
+
+## 八、典型对话示例
+
+### 示例 A：用户问"我今天有什么重要的事"
+
+**你应该：**
+1. 识别"重要的事"→ MIT
+2. 调 `zentodo --json task mit-list`
+3. 解析 `data` 数组，挑 `taskState != 0` 的项目
+4. 用 Markdown 列表展示：标题、优先级、所属项目
+
+**不要**：直接回答"你需要告诉我有哪些任务"——这个问题的信息源就是 ZenTodo。
 
-## 诊断
+### 示例 B：用户说"记一下今天专注写周报 25 分钟"
+
+**你应该：**
+1. 这是一个**启动番茄钟**的请求
+2. 先看是否已经有"写周报"的任务：`zentodo --json task search --keyword 周报`
+3. 如果有 → 拿 `taskKey` 调 `zentodo --json pomo start --task-key <k>`
+4. 如果没有 → 先 `zentodo --json task add --title "写周报"`，拿返回的 `taskKey`，再 `pomo start`
+5. 告诉用户已经开始
+
+### 示例 C：用户说"我上周做了多少事"
+
+**你应该：**
+1. 理解为任务完成统计 + 专注时长
+2. 算出上周的 ISO 日期范围（周一到周日）
+3. 并行调两个接口：
+   - `zentodo --json task stats --start-date <周一> --end-date <周日>`
+   - `zentodo --json pomo focus-stats --start-time <周一 00:00> --end-time <周日 23:59:59>`
+4. 给一份小报告：完成率、专注时长、按项目分组的任务数
+
+### 示例 D：用户说"删掉那个周报任务"
+
+**你应该：**
+1. 先搜到对应任务：`zentodo --json task search --keyword 周报`
+2. 列给用户看，让他指认是哪一条（多条时）
+3. 得到明确指示后：先 `zentodo --dry-run task delete --task-key <k>` 展示将要做的事
+4. 用户再确认后 → `zentodo task delete --task-key <k> --yes`
+
+### 示例 E：用户说"我 session 过期了"或"登录失败"
+
+**你应该：**
+1. 先判断是不是真的没登录：`zentodo auth whoami`
+2. 如果有 usrKey → 那不是 session 问题，是 CLI 调了 session 依赖的接口。告诉用户"CLI 无需维护 session，你已经是登录状态。刚才那个查询我换一个接口重试"
+3. 如果确实没 usrKey → 引导重新登录（`auth email-code` + `auth login-email`）
+
+---
+
+## 九、诊断命令
 
 ```bash
 zentodo doctor          # 配置 + 网络 + Token 体检
 zentodo auth whoami     # 查看当前身份
+zentodo --version       # CLI 版本
+zentodo sync status     # 每张表的本地 / 服务器版本对比
 zentodo audit log       # 本地命令历史
 ```
 
-## 绝对不要做的事
+如果 CLI 命令找不到，先检查：
+```bash
+which zentodo      # POSIX
+where zentodo      # Windows
+```
+
+找不到就走"前置条件"的 npm install 再试。
+
+---
+
+## 十、命令速查（最常用的 20 条）
+
+```bash
+# 今天
+zentodo --json task mit-list                    # 今日 MIT
+zentodo --json task completed-today             # 今日已完成
+zentodo --json task overdue                     # 过期任务
+zentodo --json task inbox                       # 收集箱
+
+# CRUD
+zentodo --json task add --title "..." --due <ISO> --priority 3
+zentodo --json task update --task-key <k> --title "..."
+zentodo task complete --task-key <k>
+zentodo task delete --task-key <k> --yes
+zentodo task mit --task-key <k> --is-mit true
+zentodo task quadrant --task-key <k> --quadrant 0..3
+
+# 查询
+zentodo --json task search --keyword "..." --limit 20
+zentodo --json task calendar --start-date <ISO> --end-date <ISO>
+zentodo --json project list-active
+zentodo --json project stats --project-key <k>
+
+# 专注
+zentodo --json pomo start --task-key <k>
+zentodo --json pomo focus-stats --start-time <ISO> --end-time <ISO>
+
+# 统计
+zentodo --json task stats --start-date <ISO> --end-date <ISO>
+
+# 同步
+zentodo --json sync status
+zentodo --json sync incremental
+
+# 导出
+zentodo --json export --out ./backup.json
+```
 
-- 不要在 `--json` 响应解析成功前做任何副作用判断。
-- 不要在 `error.code == ErrUnauthorized` 时继续重试同一操作,先告诉用户重新 `zentodo auth login-password`。
-- 不要在未征得用户明确同意时调用任何带 `destructive` 标记的命令。
-- 不要在日志或对话里回显用户密码、token、openid、umengToken。
-- 不要假设后端字段格式:时间一律 ISO 8601 传入 CLI,由 CLI 转换;布尔值传 `true`/`false`,由 CLI 序列化。
+完整参数见 `references/commands.md` 和 `references/tools.md`。