@zentodo/cli 0.1.1 → 0.1.3

package/dist/skills/zentodo/SKILL.md

@@ -0,0 +1,249 @@
+---
+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.
+---
+
+# ZenTodo 技能使用手册
+
+这份 Skill 让你代表用户驱动 ZenTodo 工作区。所有能力通过 `zentodo` 命令行工具调用,后端采用 `multipart/form-data` 请求格式。
+
+## 何时激活本 Skill
+
+用户消息里出现下列任一线索就应启用:
+
+- 明确提到 **ZenTodo / 任务 / 待办 / 番茄钟 / 专注 / 晨间日记 / 项目进度 / 四象限**
+- 要求"安排今天 / 统计本周"等涉及个人生产力数据的需求
+- 想同步、备份、导入导出 ZenTodo 数据
+
+## 前置条件
+
+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
+   ```
+
+   **海外用户:**
+   ```bash
+   npm install -g @zentodo/cli
+   ```
+
+   安装完成后会自动把 Skill 文件复制到 `~/.claude/skills/zentodo/` 和 `~/.agents/skills/zentodo/`，**无需额外操作**。
+
+   验证安装:
+   ```bash
+   zentodo --version
+   ```
+
+2. **登录 ZenTodo**（一次性）:
+
+   **推荐：邮箱验证码登录（与 App 端一致）**
+   ```bash
+   # 第一步：发送验证码到邮箱
+   zentodo auth email-code --email 你的邮箱
+
+   # 第二步：收到验证码后登录（验证码会在后台自动校验）
+   zentodo auth login-email --email 你的邮箱
+   ```
+
+   **或者：邮箱 + 密码登录**
+   ```bash
+   zentodo auth login-password --email 你的邮箱 --password 你的密码
+   ```
+
+   登录成功后 `usrKey` 写入 `~/.zentodo/config.json`，之后无需再提供密码。
+
+3. **重启 AI 工具**（Claude Code / Claude Desktop / WorkBuddy / Cursor / Trae 等），让它加载新安装的 Skill。
+
+4. **验证**:
+
+   ```bash
+   zentodo auth whoami
+   zentodo doctor
+   ```
+
+   如果当前 shell 找不到 `zentodo`，设置环境变量 `ZENTODO_CLI` 指向绝对路径，并在所有命令前加 `node $ZENTODO_CLI`。
+
+## 通用输出契约(**关键**)
+
+所有命令加 `--json` 后,输出统一为:
+
+```json
+{
+  "ok": true,
+  "data": <业务数据>,
+  "error": null,
+  "meta": { "requestId": "...", "durationMs": 0, "scopeChecked": ["read"] }
+}
+```
+
+- 读取 `data` 前**务必**检查 `ok`。
+- 出错时 `ok=false`,`error.code` 是 `ErrXxx` 枚举(详见 `references/error-codes.md`)。
+- 进程退出码对应常见 HTTP 语义(见同一文件)。
+
+## 预演模式
+
+任何会写入的命令都支持 `--dry-run`,不会真正调用后端,只返回将要发送的 FormData 字段。**第一次代表用户改动数据前,建议先 dry-run 一次给用户看**。
+
+## 常见任务模板
+
+### 1. 今天的 MIT 任务
+
+```bash
+zentodo --json task mit-list
+```
+
+过滤条件已内置:`syncFlag != D`、`taskState != 0`、`isTemplete = false`、`isMIT = true`、`taskCreateTime <= today`。
+
+### 2. 创建任务
+
+```bash
+zentodo --json task add \
+  --title "写周报" \
+  --due 2025-09-05T18:00:00 \
+  --priority 3 \
+  --project-key 12 \
+  --labels "工作,周报"
+```
+
+- `--due` 用 ISO 8601,CLI 会自动转换成后端 `YYYY/MM/DD HH:mm:ss`。
+- **只传真正需要的参数**,未传字段不会被写入 FormData,避免把已有列置空(这与后端契约一致)。
+
+### 3. 更新任务
+
+```bash
+zentodo --json task update --task-key 4567 --title "新标题"
+```
+
+### 4. 完成 / 取消完成
+
+```bash
+zentodo task complete --task-key 4567
+zentodo task uncomplete --task-key 4567
+```
+
+### 5. 设置 MIT / 四象限
+
+```bash
+zentodo task mit --task-key 4567 --is-mit true
+zentodo task quadrant --task-key 4567 --quadrant 1
+```
+
+### 6. 日历视图(按日期范围)
+
+```bash
+zentodo --json task calendar --start-date 2025-09-01 --end-date 2025-09-30
+```
+
+### 7. 番茄钟
+
+```bash
+zentodo --json pomo start --task-key 4567 --duration-sec 1500
+zentodo pomo stop --timer-key <key>
+zentodo --json pomo history
+```
+
+### 8. 工作状态
+
+```bash
+zentodo --json workstate start --task-key 4567 --title "专注写作"
+zentodo workstate stop --work-state-key <key>
+zentodo --json workstate current
+```
+
+### 9. 晨间日记
+
+```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 "..."
+```
+
+### 10. 跨实体搜索
+
+```bash
+zentodo --json search "周报" --in task,project,diary --limit 20
+```
+
+### 11. 同步
+
+```bash
+zentodo --json sync status           # 对比本地 / 服务器版本
+zentodo --json sync incremental      # 拉取所有"服务器更新"的表
+zentodo --json sync full             # 忽略版本号,全量拉取
+```
+
+### 12. 统计
+
+```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              # 专注时长
+```
+
+### 13. 备份与导出
+
+```bash
+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)
+
+| Group | 用途 |
+| --- | --- |
+| `auth` | 登录 / 注册 / 找回 / 改密 / 销号 / 签发受限 Token |
+| `user` | 资料 / 头像 / 邀请码 / 奖励币 / VIP |
+| `task` / `subtask` | 任务与子任务增删改查 / 完成 / 批量 |
+| `project` / `subproject` | 项目与子项目管理 |
+| `scene` | 场景切换与管理 |
+| `target` | 长期目标 |
+| `label` / `toplabel` | 标签及背景图 |
+| `quadrant` | 四象限配置 |
+| `timeline` | 时间轴条目 |
+| `attach` | 任务 / 思维导图 / 奖励商店附件上传 |
+| `pomo` / `timer` | 番茄钟 / 自由计时 |
+| `workstate` | 工作状态记录 |
+| `diary` | 晨间日记标题 + 内容 |
+| `mindmap` | 思维导图元数据 |
+| `reward` | 奖励商店与兑换记录 |
+| `fasttime` | 快速时间记录 |
+| `wheel` | 滚轮视图配置 |
+| `invite` | 邀请列表 |
+| `app` | App 版本与服务器时间 |
+| `pay` | 价格 / 支付订单(只返回订单串,不代扣) |
+| `sync` | 同步编排 |
+
+详细命令清单见 `references/commands.md`。完整参数 JSON Schema 见 `references/tools.md`。
+
+## 诊断
+
+```bash
+zentodo doctor          # 配置 + 网络 + Token 体检
+zentodo auth whoami     # 查看当前身份
+zentodo audit log       # 本地命令历史
+```
+
+## 绝对不要做的事
+
+- 不要在 `--json` 响应解析成功前做任何副作用判断。
+- 不要在 `error.code == ErrUnauthorized` 时继续重试同一操作,先告诉用户重新 `zentodo auth login-password`。
+- 不要在未征得用户明确同意时调用任何带 `destructive` 标记的命令。
+- 不要在日志或对话里回显用户密码、token、openid、umengToken。
+- 不要假设后端字段格式:时间一律 ISO 8601 传入 CLI,由 CLI 转换;布尔值传 `true`/`false`,由 CLI 序列化。

package/dist/skills/zentodo/examples/plan-my-day.md

@@ -0,0 +1,12 @@
+# 示例:安排今天
+
+用户:"总结我今天的 MIT 任务,并为第一条开启番茄钟。"
+
+Agent:
+
+1. 调用 `zentodo.task.mit-list`,无需入参。
+2. 挑出第一条未完成(`taskState != 0`)的任务。
+3. 对它调用 `zentodo.pomo.start`,入参 `{ "task_key": <taskKey>, "duration_sec": 1500 }`。
+4. 输出一段总结:"已开启 25 分钟番茄钟,任务:_写周报_(#4567)。"
+
+读取 `data` 前一定要先检查 `ok`。

package/dist/skills/zentodo/examples/sync.md

@@ -0,0 +1,9 @@
+# 示例:检查同步状态
+
+用户:"我的任务数据是最新的吗?"
+
+Agent:
+
+1. 调用 `zentodo.sync.server-version`,入参 `{ "table_name": "task" }`。
+2. 与 Skill 本地缓存的 `client_version` 比较。若服务器版本更大,调用 `zentodo.task.sync-pull` 并传入缓存版本拉取增量。
+3. 汇报"数据已最新"或"已拉取 N 条任务,服务器版本现为 M"。