@zentodo/cli 0.1.10 → 0.1.12

package/dist/skills/zentodo/SKILL.md

@@ -208,14 +208,34 @@ zentodo doctor
 
 2. **不要误判 "Session 过期"**
    ZenTodo 后端用 Spring Security + Session Cookie。CLI 是无状态 HTTP，不带 Cookie。
-   大部分接口用 `usrKey` 参数就能工作。极少数旧接口走 Session，会 302 重定向——这**不是** session 过期，是本来就没 session。不要劝用户"重新登录"，请直接使用有 `usrKey` 参数的替代接口。
+   大部分接口用 `usrKey` 参数就能工作，**不需要** session。
+
+   如果 CLI 调用接口被 302 重定向到 `/login`，**99% 不是 session 过期**，而是下列原因之一：
+   - `config.json` 里 `user_key` 是坏对象（老版 CLI bug，值像 `{data:466,code:0,msg:"ok"}`），发出去变成 `[object Object]`，后端解析失败 → 302。**解决：升级 CLI 到最新版，启动时会自动修复。**
+   - 个别旧接口强依赖 Session Cookie，CLI 永远触发 302。**解决：换有 `usrKey` 参数的同类接口。**
+
+   诊断步骤：
+   ```bash
+   zentodo --dry-run --json project list
+   # 看 fields 里 usrKey 是不是纯数字，如果是 [object Object] 就是坏数据
+   zentodo auth whoami
+   # user_key 应该显示数字，不是 JSON 对象
+   ```
+
+   **不要**劝用户"重新登录"——CLI 根本不维护 session，重新登录也没用；只会再存一次坏数据。
 
 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`。
 
-4. **不要在未征得用户明确同意时做破坏性操作**
+4. **不要在查询返回空/失败时误导用户**
+   - ❌ 不要说："你的 ZenTodo 账号是空的 / 还没有数据 / 请先同步"
+   - ❌ 不要让用户跑 `zentodo sync incremental`（CLI 没有本地库，sync 对它无意义）
+   - ❌ 不要让用户"先去 App 建任务我再帮你查"——他的数据已经在服务器上
+   - ✅ 正确做法：按"故障排查"章节顺序检查（usrKey → dry-run → 换接口 → 升级 CLI）
+
+5. **不要在未征得用户明确同意时做破坏性操作**
    以下命令属于破坏性，即便用户话里带"删 / 清空 / 重置"也要先 dry-run 展示内容，确认后再加 `--yes` 真执行：
    - `zentodo task delete`
    - `zentodo auth delete-account`
@@ -225,9 +245,9 @@ zentodo doctor
    - `zentodo import --mode replace --yes`
    - `zentodo backup restore --yes`
 
-5. **不要在对话或日志里回显**密码、usrPwd、token、openid、umengToken。
+6. **不要在对话或日志里回显**密码、usrPwd、token、openid、umengToken。
 
-6. **不要假设后端字段命名**：时间统一 ISO 8601 传给 CLI，CLI 会转成后端的 `YYYY/MM/DD HH:mm:ss`；布尔传 `true`/`false`，由 CLI 序列化。
+7. **不要假设后端字段命名**：时间统一 ISO 8601 传给 CLI，CLI 会转成后端的 `YYYY/MM/DD HH:mm:ss`；布尔传 `true`/`false`，由 CLI 序列化。
 
 ---
 
@@ -481,23 +501,52 @@ zentodo --json backup list
 
 ---
 
-## 九、诊断命令
+## 十一、故障排查（重要）
 
-```bash
-zentodo doctor          # 配置 + 网络 + Token 体检
-zentodo auth whoami     # 查看当前身份
-zentodo --version       # CLI 版本
-zentodo sync status     # 每张表的本地 / 服务器版本对比
-zentodo audit log       # 本地命令历史
-```
+### 当查询返回空或 404 时，**不要**说 "用户账号是空的" 或 "请先同步"
 
-如果 CLI 命令找不到，先检查：
-```bash
-which zentodo      # POSIX
-where zentodo      # Windows
-```
+ZenTodo 是**远端服务**，数据一直在服务器数据库里。CLI 是无状态客户端，直接查后端，**不需要** `sync incremental` 这种本地对齐操作。
+
+查询结果异常时按以下顺序排查：
+
+1. **先确认 CLI 有 usrKey**：
+   ```bash
+   zentodo auth whoami
+   ```
+   输出里 `user_key` 应该是纯数字（例如 `466`），如果是对象 `{ data: 466, ... }` 就是老版 CLI 的 bug，升级到最新版：
+   ```bash
+   npm install -g @zentodo/cli@latest --registry https://registry.npmmirror.com
+   ```
+   升级后第一次运行任何命令会自动把 config.json 里的坏数据修正。
+
+2. **dry-run 看实际发的请求**：
+   ```bash
+   zentodo --dry-run --json task list
+   ```
+   如果 `fields` 里 `usrKey=[object Object]` 或者没有 `usrKey` → 走第 1 步升级。
+
+3. **绕过 CLI 直接验证**（仅限诊断，正常使用别这样）：
+   ```bash
+   curl -X POST "http://ztdfwq.qmlist.net:8082/zentodoserver/taskController/getAllTaskByUserId" \
+        -d "usrKey=你的usrKey" \
+        -H "Content-Type: application/x-www-form-urlencoded"
+   ```
+   如果这样能拿到数据但 `zentodo` 命令不行 → CLI 有 bug，升级或提 issue。
+
+4. **换接口试**：某些旧接口（极少数）依赖 Session Cookie，CLI 调会被 302 重定向到 `/login`。这**不是 session 过期**，是本来就没 session。直接换一个有 `usrKey` 参数的同义接口即可。常见替代：
+   - `project list-all` → 如果 302，说明是旧版后端，用 `project list-active` / `list-archived`
+   - `task calendar` → 等价于 `task list` 后客户端按日期过滤（最新版后端已改好直接支持 usrKey）
+
+5. **404 / 接口不存在**：新加的接口（如 `task.mit-list`、`task.overdue`、`task.inbox`、`task.stats`、`pomo.focus-stats`）需要后端更新。如果服务器是旧版，降级到用 `task list-all` 后在客户端过滤。但**不要**因此告诉用户"账号是空的"——空列表是空列表，404 是服务器没部署新接口，两回事。
+
+### **绝对不要**
+
+- **不要**在查不到数据时说"你的 ZenTodo 账号是空账号"或"请先在 App 里创建"——数据几乎一定在服务器上，是 CLI 或接口的问题
+- **不要**让用户运行 `sync incremental` 来"同步数据"——CLI 没有本地库，sync 对它没意义
+- **不要**让用户重新登录，除非 `zentodo auth whoami` 明确显示 `user_key` 为空
+
+---
 
-找不到就走"前置条件"的 npm install 再试。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zentodo/cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "ZenTodo 命令行工具 — 为 AI Agent 和开发者设计，覆盖任务、项目、番茄钟、日记、同步等全部能力。安装后自动配置 Claude Agent Skill。",
   "type": "module",
   "bin": {

package/skills/zentodo/SKILL.md

@@ -208,14 +208,34 @@ zentodo doctor
 
 2. **不要误判 "Session 过期"**
    ZenTodo 后端用 Spring Security + Session Cookie。CLI 是无状态 HTTP，不带 Cookie。
-   大部分接口用 `usrKey` 参数就能工作。极少数旧接口走 Session，会 302 重定向——这**不是** session 过期，是本来就没 session。不要劝用户"重新登录"，请直接使用有 `usrKey` 参数的替代接口。
+   大部分接口用 `usrKey` 参数就能工作，**不需要** session。
+
+   如果 CLI 调用接口被 302 重定向到 `/login`，**99% 不是 session 过期**，而是下列原因之一：
+   - `config.json` 里 `user_key` 是坏对象（老版 CLI bug，值像 `{data:466,code:0,msg:"ok"}`），发出去变成 `[object Object]`，后端解析失败 → 302。**解决：升级 CLI 到最新版，启动时会自动修复。**
+   - 个别旧接口强依赖 Session Cookie，CLI 永远触发 302。**解决：换有 `usrKey` 参数的同类接口。**
+
+   诊断步骤：
+   ```bash
+   zentodo --dry-run --json project list
+   # 看 fields 里 usrKey 是不是纯数字，如果是 [object Object] 就是坏数据
+   zentodo auth whoami
+   # user_key 应该显示数字，不是 JSON 对象
+   ```
+
+   **不要**劝用户"重新登录"——CLI 根本不维护 session，重新登录也没用；只会再存一次坏数据。
 
 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`。
 
-4. **不要在未征得用户明确同意时做破坏性操作**
+4. **不要在查询返回空/失败时误导用户**
+   - ❌ 不要说："你的 ZenTodo 账号是空的 / 还没有数据 / 请先同步"
+   - ❌ 不要让用户跑 `zentodo sync incremental`（CLI 没有本地库，sync 对它无意义）
+   - ❌ 不要让用户"先去 App 建任务我再帮你查"——他的数据已经在服务器上
+   - ✅ 正确做法：按"故障排查"章节顺序检查（usrKey → dry-run → 换接口 → 升级 CLI）
+
+5. **不要在未征得用户明确同意时做破坏性操作**
    以下命令属于破坏性，即便用户话里带"删 / 清空 / 重置"也要先 dry-run 展示内容，确认后再加 `--yes` 真执行：
    - `zentodo task delete`
    - `zentodo auth delete-account`
@@ -225,9 +245,9 @@ zentodo doctor
    - `zentodo import --mode replace --yes`
    - `zentodo backup restore --yes`
 
-5. **不要在对话或日志里回显**密码、usrPwd、token、openid、umengToken。
+6. **不要在对话或日志里回显**密码、usrPwd、token、openid、umengToken。
 
-6. **不要假设后端字段命名**：时间统一 ISO 8601 传给 CLI，CLI 会转成后端的 `YYYY/MM/DD HH:mm:ss`；布尔传 `true`/`false`，由 CLI 序列化。
+7. **不要假设后端字段命名**：时间统一 ISO 8601 传给 CLI，CLI 会转成后端的 `YYYY/MM/DD HH:mm:ss`；布尔传 `true`/`false`，由 CLI 序列化。
 
 ---
 
@@ -481,23 +501,52 @@ zentodo --json backup list
 
 ---
 
-## 九、诊断命令
+## 十一、故障排查（重要）
 
-```bash
-zentodo doctor          # 配置 + 网络 + Token 体检
-zentodo auth whoami     # 查看当前身份
-zentodo --version       # CLI 版本
-zentodo sync status     # 每张表的本地 / 服务器版本对比
-zentodo audit log       # 本地命令历史
-```
+### 当查询返回空或 404 时，**不要**说 "用户账号是空的" 或 "请先同步"
 
-如果 CLI 命令找不到，先检查：
-```bash
-which zentodo      # POSIX
-where zentodo      # Windows
-```
+ZenTodo 是**远端服务**，数据一直在服务器数据库里。CLI 是无状态客户端，直接查后端，**不需要** `sync incremental` 这种本地对齐操作。
+
+查询结果异常时按以下顺序排查：
+
+1. **先确认 CLI 有 usrKey**：
+   ```bash
+   zentodo auth whoami
+   ```
+   输出里 `user_key` 应该是纯数字（例如 `466`），如果是对象 `{ data: 466, ... }` 就是老版 CLI 的 bug，升级到最新版：
+   ```bash
+   npm install -g @zentodo/cli@latest --registry https://registry.npmmirror.com
+   ```
+   升级后第一次运行任何命令会自动把 config.json 里的坏数据修正。
+
+2. **dry-run 看实际发的请求**：
+   ```bash
+   zentodo --dry-run --json task list
+   ```
+   如果 `fields` 里 `usrKey=[object Object]` 或者没有 `usrKey` → 走第 1 步升级。
+
+3. **绕过 CLI 直接验证**（仅限诊断，正常使用别这样）：
+   ```bash
+   curl -X POST "http://ztdfwq.qmlist.net:8082/zentodoserver/taskController/getAllTaskByUserId" \
+        -d "usrKey=你的usrKey" \
+        -H "Content-Type: application/x-www-form-urlencoded"
+   ```
+   如果这样能拿到数据但 `zentodo` 命令不行 → CLI 有 bug，升级或提 issue。
+
+4. **换接口试**：某些旧接口（极少数）依赖 Session Cookie，CLI 调会被 302 重定向到 `/login`。这**不是 session 过期**，是本来就没 session。直接换一个有 `usrKey` 参数的同义接口即可。常见替代：
+   - `project list-all` → 如果 302，说明是旧版后端，用 `project list-active` / `list-archived`
+   - `task calendar` → 等价于 `task list` 后客户端按日期过滤（最新版后端已改好直接支持 usrKey）
+
+5. **404 / 接口不存在**：新加的接口（如 `task.mit-list`、`task.overdue`、`task.inbox`、`task.stats`、`pomo.focus-stats`）需要后端更新。如果服务器是旧版，降级到用 `task list-all` 后在客户端过滤。但**不要**因此告诉用户"账号是空的"——空列表是空列表，404 是服务器没部署新接口，两回事。
+
+### **绝对不要**
+
+- **不要**在查不到数据时说"你的 ZenTodo 账号是空账号"或"请先在 App 里创建"——数据几乎一定在服务器上，是 CLI 或接口的问题
+- **不要**让用户运行 `sync incremental` 来"同步数据"——CLI 没有本地库，sync 对它没意义
+- **不要**让用户重新登录，除非 `zentodo auth whoami` 明确显示 `user_key` 为空
+
+---
 
-找不到就走"前置条件"的 npm install 再试。
 
 ---