@wangjs-jacky/ticktick-cli 0.1.0

package/docs/superpowers/specs/2026-04-03-tt-cli-design.md

@@ -0,0 +1,142 @@
+# tt-cli 设计文档
+
+> 滴答清单（TickTick）命令行工具，TypeScript 实现
+
+## 项目信息
+
+| 项 | 值 |
+|---|---|
+| 项目名 | `tt-cli` |
+| npm 包名 | `@wangjs-jacky/tt-cli` |
+| CLI 命令 | `tt` |
+| 仓库 | `/Users/jiashengwang/jacky-github/tt-cli` |
+| GitHub | `https://github.com/wangjs-jacky/tt-cli` |
+
+## 技术栈
+
+| 包 | 用途 |
+|---|------|
+| `cac` | CLI 命令框架 |
+| `@clack/prompts` | 终端交互 UI |
+| `picocolors` | 终端颜色 |
+| `tsup` | 构建打包 |
+| `open` | 打开浏览器 |
+| `conf` | 跨平台配置存储（基于 XDG） |
+
+## 项目结构
+
+```
+tt-cli/
+├── src/
+│   ├── index.ts          # 入口，cac 命令注册
+│   ├── commands/
+│   │   └── auth.ts       # tt login / tt logout
+│   ├── api/
+│   │   ├── client.ts     # HTTP 客户端，自动附带 token
+│   │   └── oauth.ts      # OAuth2 流程（本地回调服务器）
+│   ├── utils/
+│   │   ├── config.ts     # token 存储管理 (~/.tt-cli/config.json)
+│   │   ├── server.ts     # 临时本地回调服务器
+│   │   └── open.ts       # 打开浏览器
+│   └── types.ts          # TypeScript 类型定义
+├── bin/
+│   └── cli.ts            # #!/usr/bin/env node 入口
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+└── README.md
+```
+
+## Token 存储
+
+位置：`~/.tt-cli/config.json`
+
+```json
+{
+  "accessToken": "...",
+  "refreshToken": "...",
+  "expiresAt": 1712121600000,
+  "clientId": "...",
+  "clientSecret": "..."
+}
+```
+
+## OAuth2 认证流程
+
+### tt login
+
+1. 检测 `~/.tt-cli/config.json` 是否有有效 token
+2. 首次使用：提示输入 Client ID + Client Secret
+3. 启动本地服务器 `http://localhost:{随机端口}/callback`
+4. 生成 state（防 CSRF），拼接授权 URL
+5. 自动打开浏览器 → 用户登录并授权
+6. TickTick 重定向到 `localhost/callback?code=xxx&state=yyy`
+7. 本地服务器捕获 code，验证 state
+8. `POST https://ticktick.com/oauth/token` 换取 access_token（Authorization: Basic base64(clientId:clientSecret)）
+9. 保存 token 到 config.json
+10. 终端显示登录成功，关闭本地服务器
+
+### Token 刷新（自动）
+
+1. API 调用前检查 expiresAt
+2. 即将过期时自动 `POST https://ticktick.com/oauth/token`，grant_type=refresh_token
+3. 更新 config.json 中的 token
+
+### tt logout
+
+删除 config.json 中的 token 数据。
+
+## CLI 命令（鉴权阶段）
+
+```bash
+tt login          # OAuth2 登录，获取 token
+tt logout         # 登出，清除 token
+tt whoami         # 显示当前登录状态和用户信息
+tt config         # 查看/设置 Client ID 和 Client Secret
+```
+
+### tt login 交互流程
+
+```
+◈ 滴答清单 CLI 登录
+
+◇ 尚未配置 OAuth 凭证
+│ 首次使用需要注册 TickTick 开发者应用
+│ 请访问 https://developer.ticktick.com/app 注册
+│ Redirect URI 设置为: http://localhost:3000/callback
+│
+◇ 请输入 Client ID: ________
+◇ 请输入 Client Secret: ________
+│
+◆ 正在打开浏览器进行授权...
+│ 如果浏览器没有自动打开，请访问：
+│ https://ticktick.com/oauth/authorize?...
+│
+✔ 登录成功！欢迎, <用户名>
+```
+
+### tt whoami 输出
+
+```
+✔ 已登录
+  用户: jacky
+  Token 有效期: 2026-04-03 18:30 (剩余 6 小时)
+```
+
+## TickTick OAuth2 关键参数
+
+| 参数 | 值 |
+|---|---|
+| 授权 URL | `https://ticktick.com/oauth/authorize` |
+| Token URL | `https://ticktick.com/oauth/token` |
+| API Base | `https://api.ticktick.com/open/v1/` |
+| Scopes | `tasks:read tasks:write` |
+| Redirect URI | `http://localhost:{port}/callback` |
+
+## 后续阶段（本次不实现）
+
+- `tt tasks` — 查看今日/明日任务
+- `tt add` — 创建任务
+- `tt done` — 完成任务
+- `tt projects` — 查看项目清单
+- `tt review` — 日程复盘

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@wangjs-jacky/ticktick-cli",
+  "version": "0.1.0",
+  "description": "滴答清单（TickTick）命令行工具",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "tt": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ticktick",
+    "dida",
+    "cli",
+    "todo",
+    "task"
+  ],
+  "author": "wangjs-jacky",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wangjs-jacky/tt-cli.git"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "cac": "^7.0.0",
+    "open": "^11.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/skills/tt-cli-guide/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: tt-cli-guide
+description: "滴答清单（TickTick）CLI 使用助手 — 将自然语言意图自动映射为 tt 命令并执行"
+---
+
+<role>
+你是 tt-cli（滴答清单命令行工具）的使用助手。将用户的自然语言请求翻译为正确的 `tt` 命令并执行，返回清晰的结果。
+</role>
+
+<purpose>
+当用户用自然语言表达任务管理需求时，自动解析意图、补全参数、构建并执行对应的 tt-cli 命令。
+</purpose>
+
+<trigger>
+```
+帮我查看任务 / 今天的任务 / 明天要做什么
+创建任务 / 新建任务 / 添加任务
+完成 / 删除 / 修改任务
+查看项目 / 创建项目
+tt / 滴答清单 / ticktick / todo
+任务管理 / 待办事项
+```
+</trigger>
+
+<yolo:config>
+  <yolo:mode>auto-advance</yolo:mode>
+  <yolo:safety-gates>
+    <gate>删除任务（tt task-delete）</gate>
+    <gate>删除项目（tt project-delete）</gate>
+    <gate>批量完成全部任务（tt task-batch-done --all）</gate>
+    <gate>批量完成带 --force 跳过确认</gate>
+    <gate>认证变更（tt login / logout / config --region）</gate>
+  </yolo:safety-gates>
+</yolo:config>
+
+<gsd:workflow>
+  <gsd:meta>
+    <name>tt-cli-guide</name>
+    <trigger>任务管理、待办、tt 命令、滴答清单</trigger>
+    <requires>Bash</requires>
+    <checkpoints>
+      <checkpoint order="1">登录状态已验证</checkpoint>
+      <checkpoint order="2">意图已解析，参数已补全</checkpoint>
+      <checkpoint order="3">安全门操作已确认</checkpoint>
+    </checkpoints>
+    <constraints>
+      <constraint>所有相对日期必须转为绝对日期（YYYY-MM-DD）再传入命令</constraint>
+      <constraint>安全门操作必须等待用户确认后才执行</constraint>
+      <constraint>用户说项目名称时，先 tt project-list 查找 ID</constraint>
+      <constraint>用户只说任务名称时，先 tt task-search 查找 projectId 和 taskId</constraint>
+      <constraint>YOLO 模式下安全门操作仍需人工确认</constraint>
+    </constraints>
+  </gsd:meta>
+
+  <gsd:goal>将用户的自然语言任务管理请求准确映射为 tt-cli 命令，执行并返回结果</gsd:goal>
+
+  <gsd:phase name="preflight" order="1">
+    <gsd:step>运行 tt whoami 验证登录状态</gsd:step>
+    <gsd:checkpoint>已登录且 Token 有效，否则引导 tt login</gsd:checkpoint>
+  </gsd:phase>
+
+  <gsd:phase name="parse" order="2">
+    <gsd:step>从用户输入中提取：操作类型、标题、日期、项目名、优先级</gsd:step>
+    <gsd:step>将相对日期（今天/昨天/这周等）转换为绝对日期</gsd:step>
+    <gsd:step>将项目名称解析为 projectId（需要时查 tt project-list）</gsd:step>
+    <gsd:step>将任务名称解析为 taskId + projectId（需要时查 tt task-search）</gsd:step>
+    <gsd:checkpoint>所有必需参数已就绪</gsd:checkpoint>
+  </gsd:phase>
+
+  <gsd:phase name="execute" order="3">
+    <gsd:step>根据意图映射表构建完整命令</gsd:step>
+    <gsd:step>安全门操作暂停等待用户确认</gsd:step>
+    <gsd:step>执行命令</gsd:step>
+  </gsd:phase>
+
+  <gsd:phase name="verify" order="4">
+    <gsd:step>检查命令执行结果</gsd:step>
+    <gsd:step>以清晰格式呈现给用户</gsd:step>
+    <gsd:step>建议可跟进的操作</gsd:step>
+  </gsd:phase>
+</gsd:workflow>
+
+# tt-cli 使用助手
+
+> YOLO 模式 — 自动推进查询和创建操作。删除和批量操作会暂停确认。
+
+## 执行流程
+
+### Phase 1: 预检
+
+**目标**：确认登录状态有效
+
+**步骤**：
+1. 运行 `tt whoami`
+2. 未登录 → 提示 `tt login` 并停止
+3. 已登录 → 继续
+
+### Phase 2: 解析意图
+
+**目标**：从自然语言中提取所有必需参数
+
+**步骤**：
+1. **识别操作类型**：查询 / 创建 / 更新 / 完成 / 删除 / 项目管理 / 认证
+2. **转换日期**：参考 `references/intent-mapping.md` 日期转换规则，将相对日期转为 `YYYY-MM-DD`
+3. **解析项目**：用户说了项目名称 → `tt project-list` 查找对应 ID
+4. **解析任务**：用户只说了任务名称 → `tt task-search "关键词"` 获取 taskId 和 projectId
+5. **映射优先级**：紧急/重要→5，一般→3，不急→1
+
+### Phase 3: 执行命令
+
+**目标**：构建并执行 tt 命令
+
+**步骤**：
+1. 根据 `references/intent-mapping.md` 意图映射表构建命令
+2. 安全门检查（删除、批量 --all、认证变更）→ 暂停等用户确认
+3. 执行命令
+
+### Phase 4: 验证与呈现
+
+**目标**：清晰展示结果并建议后续操作
+
+**步骤**：
+1. 检查命令输出，格式化呈现
+2. 根据结果建议可跟进操作（如：查到任务后建议完成/修改）
+
+## 快速意图识别
+
+| 关键词 | 操作 | 命令 |
+|--------|------|------|
+| 查看/看看/有什么/列出 | 查询 | `tt task-undone` / `tt task-list` / `tt task-search` |
+| 创建/新建/添加/安排 | 创建 | `tt task-add` |
+| 修改/更新/改 | 更新 | `tt task-update` |
+| 完成/做完/勾掉 | 完成 | `tt task-done` |
+| 删除/移除 | 删除 | `tt task-delete` |
+| 搜索/找一下 | 搜索 | `tt task-search` |
+| 项目/清单 | 项目 | `tt project-*` |
+| 登录/登出/配置 | 认证 | `tt login` / `tt logout` / `tt config` |
+
+## 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| 未登录 | 提示 `tt login` |
+| 找不到项目 | 列出所有项目供选择 |
+| 找不到任务 | 建议 `tt task-search "关键词"` |
+| Token 过期 | 提示 `tt login` |
+| 命令失败 | 展示错误，分析原因，给修复建议 |
+
+## 详细参考
+
+- 意图映射表、日期规则、Prompt 模板 → [references/intent-mapping.md](references/intent-mapping.md)
+- CLI 完整命令文档 → [docs/Reference/cli-usage-guide.md](../../docs/Reference/cli-usage-guide.md)

package/skills/tt-cli-guide/references/intent-mapping.md

@@ -0,0 +1,169 @@
+# tt-cli 意图映射参考表
+
+> 本文件为 `tt-cli-guide` skill 的详细参考，包含所有自然语言到命令的映射关系。
+
+## 日期转换规则
+
+**所有相对日期必须先转换为绝对日期（格式 `YYYY-MM-DD`）**，用 JavaScript `new Date()` 获取当前日期计算。
+
+| 用户说法 | 转换规则 | 示例（假设今天是 2026-04-04） |
+|----------|----------|------|
+| 今天 | 当天日期 | `2026-04-04` |
+| 昨天 | 当天 -1 | `2026-04-03` |
+| 前天 | 当天 -2 | `2026-04-02` |
+| 明天 | 当天 +1 | `2026-04-05` |
+| 后天 | 当天 +2 | `2026-04-06` |
+| 这周 | 本周一 ~ 本周日 | `2026-03-30` ~ `2026-04-05` |
+| 上周 | 上周一 ~ 上周日 | `2026-03-23` ~ `2026-03-29` |
+| 下周 | 下周一 ~ 下周日 | `2026-04-06` ~ `2026-04-12` |
+| 本月 | 本月1日 ~ 月末 | `2026-04-01` ~ `2026-04-30` |
+| 上月 | 上月1日 ~ 上月末 | `2026-03-01` ~ `2026-03-31` |
+
+### 日期预设快捷值
+
+`tt task-undone --query` 支持以下预设（无需计算日期）：
+
+| 预设值 | 含义 |
+|--------|------|
+| `today` | 今天 |
+| `tomorrow` | 明天 |
+| `last24hour` | 过去 24 小时 |
+| `next24hour` | 未来 24 小时 |
+| `last7day` | 过去 7 天 |
+| `next7day` | 未来 7 天 |
+
+> `--query` 与 `--start/--end` 互斥，优先使用 `--query`。
+
+---
+
+## 意图映射表
+
+### 查询任务
+
+| 用户意图 | 命令 | 说明 |
+|----------|------|------|
+| 查看今天的任务 | `tt task-undone --query today` | 今日未完成 |
+| 查看明天的任务 | `tt task-undone --query tomorrow` | 明日未完成 |
+| 未来一周的任务 | `tt task-undone --query next7day` | 未来 7 天 |
+| 过去一周的任务 | `tt task-undone --query last7day` | 过去 7 天 |
+| 查看昨天的任务 | `tt task-undone --start "YYYY-MM-DD" --end "YYYY-MM-DD"` | 需计算日期 |
+| 查看前天的任务 | `tt task-undone --start "YYYY-MM-DD" --end "YYYY-MM-DD"` | 需计算日期 |
+| 查看某天的任务 | `tt task-undone --start "日期" --end "日期"` | 日期范围查询 |
+| 查看已完成任务 | `tt task-completed` | 默认所有 |
+| 某段时间完成的任务 | `tt task-completed --start "开始" --end "结束"` | 带日期范围 |
+| 所有未完成任务 | `tt task-list --status 0` | 全部待办 |
+| 高优先级任务 | `tt task-list --status 0 --priority 5` | 高优先级待办 |
+| 按关键词搜索 | `tt task-search "关键词"` | 模糊搜索标题和内容 |
+| 某项目的任务 | `tt project-tasks <projectId>` | 需先知道项目 ID |
+| 任务详情 | `tt task-find <taskId>` | 按 ID 查找 |
+
+### 创建任务
+
+| 用户意图 | 命令模板 |
+|----------|----------|
+| 创建任务（只说标题） | `tt task-add "标题"` |
+| 创建到指定项目 | `tt task-add "标题" -p <projectId>` |
+| 高优先级任务 | `tt task-add "标题" --priority 5` |
+| 带截止日期 | `tt task-add "标题" --due-date "YYYY-MM-DDTHH:mm:ss.000Z"` |
+| 全天任务 | `tt task-add "标题" --all-day` |
+| 带详细内容 | `tt task-add "标题" --content "详细说明"` |
+| 完整创建 | `tt task-add "标题" -p <projectId> --priority 3 --start-date "..." --due-date "..."` |
+
+**创建规则**：
+- 用户没指定项目 → 不加 `-p`，让 CLI 交互选择
+- 用户说了项目名称（非 ID）→ 先 `tt project-list` 查找 ID
+- 用户说了项目 ID → 直接使用
+
+### 更新任务
+
+| 用户意图 | 命令模板 |
+|----------|----------|
+| 修改标题 | `tt task-update <taskId> -p <projectId> --title "新标题"` |
+| 修改优先级 | `tt task-update <taskId> -p <projectId> --priority 3` |
+| 修改截止日期 | `tt task-update <taskId> -p <projectId> --due-date "..."` |
+| 修改内容 | `tt task-update <taskId> -p <projectId> --content "新内容"` |
+
+**更新规则**：如果用户只提供了任务名称，先用 `tt task-search` 查找，获取 `projectId` 和 `taskId`。
+
+### 完成和删除
+
+| 用户意图 | 命令模板 | 风险等级 |
+|----------|----------|----------|
+| 完成任务 | `tt task-done <projectId> <taskId>` | 低 |
+| 删除任务 | `tt task-delete <projectId> <taskId>` | **高** |
+| 批量完成（指定） | `tt task-batch-done <projectId> --task-ids "id1,id2,id3"` | 中 |
+| 批量完成（全部） | `tt task-batch-done <projectId> --all` | **高** |
+
+### 项目管理
+
+| 用户意图 | 命令模板 |
+|----------|----------|
+| 查看所有项目 | `tt project-list` |
+| 查看项目详情 | `tt project-get <projectId>` |
+| 创建项目 | `tt project-create "项目名"` |
+| 修改项目名称 | `tt project-update <projectId> --name "新名称"` |
+| 删除项目 | `tt project-delete <projectId>` | **高** |
+
+### 认证和配置
+
+| 用户意图 | 命令模板 |
+|----------|----------|
+| 登录 | `tt login` |
+| 登出 | `tt logout` |
+| 查看登录状态 | `tt whoami` |
+| 查看配置 | `tt config` |
+| 切换到国内版 | `tt config --region cn` |
+| 切换到国际版 | `tt config --region global` |
+| 查看用户偏好 | `tt user-pref` |
+
+---
+
+## 优先级映射
+
+| 值 | 含义 | 触发词 |
+|----|------|--------|
+| `0` | 无优先级 | （默认） |
+| `1` | 低优先级 | "低优先级"、"不急" |
+| `3` | 中优先级 | "中优先级"、"一般" |
+| `5` | 高优先级 | "高优先级"、"紧急"、"重要" |
+
+## 任务状态
+
+| 值 | 含义 | 图标 |
+|----|------|------|
+| `0` | 待办 | ○ |
+| `2` | 已完成 | ✓ |
+
+---
+
+## 常用 Prompt 模板
+
+以下是用户可以直接使用的自然语言示例：
+
+### 查询类
+- "帮我查看今天的任务"
+- "今天有什么待办事项"
+- "看看我明天要做什么"
+- "未来一周有哪些任务"
+- "昨天的任务完成了吗"
+- "帮我查一下上周完成了哪些任务"
+- "有哪些高优先级的任务还没完成"
+- "搜索一下关于 XX 的任务"
+- "看看 XX 项目里有什么任务"
+
+### 创建类
+- "帮我创建一个任务：明天开会"
+- "新建一个高优先级任务：提交报告，截止到本周五"
+- "在'工作'项目下添加任务：准备会议材料"
+- "帮我安排明天的任务：上午开会，下午写文档"
+
+### 操作类
+- "帮我把 XX 任务标记为完成"
+- "完成今天所有的任务"
+- "把 XX 任务移到'生活'项目"
+- "修改 XX 任务的截止日期到下周一"
+
+### 分析类
+- "帮我统计一下这周完成了多少任务"
+- "看看我哪些任务快到期了"
+- "帮我整理一下当前所有未完成的任务，按优先级排序"

package/src/api/client.ts

@@ -0,0 +1,61 @@
+import { getOAuth, getToken, isTokenValid, getRegion } from '../utils/config.js';
+import { getEndpoints } from '../utils/endpoints.js';
+import { refreshAccessToken } from './oauth.js';
+
+/** 获取有效的 access token（自动刷新） */
+async function getValidToken(): Promise<string> {
+  const oauth = getOAuth();
+  const token = getToken();
+
+  if (!oauth || !token) {
+    throw new Error('未登录，请先运行 tt login');
+  }
+
+  if (isTokenValid()) {
+    return token.accessToken;
+  }
+
+  const newToken = await refreshAccessToken();
+  return newToken.accessToken;
+}
+
+/** 发送 API 请求 */
+export async function apiRequest<T>(path: string, options?: RequestInit): Promise<T> {
+  const token = await getValidToken();
+  const endpoints = getEndpoints(getRegion());
+
+  const response = await fetch(`${endpoints.apiBase}${path}`, {
+    ...options,
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      ...options?.headers,
+    },
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`API 请求失败: ${response.status} ${text}`);
+  }
+
+  if (response.status === 204) {
+    return undefined as T;
+  }
+
+  // 读取响应文本，处理空 body（TickTick 部分 API 返回 200 + 空 body）
+  const text = await response.text();
+  if (!text || text.trim() === '') {
+    return undefined as T;
+  }
+
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(
+      `API 响应 JSON 解析失败 (HTTP ${response.status})\n` +
+        `路径: ${path}\n` +
+        `原始响应: ${text.substring(0, 500)}\n` +
+        `建议: 请检查 API 端点是否正确，或尝试 tt task-search 验证数据`
+    );
+  }
+}