TickTick Power Skill

通过滴答清单（TickTick）API 管理任务和项目，支持 OAuth2 认证、批量操作、优先级、标签、到期时间和文件附件。

核心功能

| 功能 | 命令 | 说明 | |------|------|------| | 认证 | auth | OAuth2 浏览器认证或手动模式 | | 任务列表 | tasks | 列出所有任务，支持项目和状态过滤 | | 新建任务 | task | 创建任务，支持优先级/标签/到期时间 | | 更新任务 | task --update | 更新任务标题/内容/优先级/日期 | | 完成任务 | complete | 标记任务为已完成 | | 放弃任务 | abandon | 标记任务为"不会做" | | 批量放弃 | batch-abandon | 批量放弃任务（单次 API 调用） | | 项目列表 | lists | 列出所有项目 | | 新建项目 | list | 创建新项目 | | 更新项目 | list --update | 更新项目名称/颜色 | | 上传附件 | attach | 上传文件附件到任务 |

快速开始

1. 安装依赖

pip install -e ~/.workbuddy/skills/ticktickpower/
# 或直接安装 requests
pip install requests

2. 注册开发者应用

访问 TickTick Developer Center
创建新应用，设置重定向 URI 为 http://localhost:8080
记录 Client ID 和 Client Secret

3. 认证

# 交互式认证（自动打开浏览器）
python -m ticktick.cli auth --client-id <YOUR_CLIENT_ID> --client-secret <YOUR_CLIENT_SECRET>

# 检查认证状态
python -m ticktick.cli auth --status

# 手动认证（无浏览器 / Linux 服务器）
python -m ticktick.cli auth --client-id <ID> --client-secret <SECRET> --manual

# 退出登录（清除 Token，保留凭证）
python -m ticktick.cli auth --logout

4. 配置 WorkBuddy Skill 触发

WorkBuddy 会自动识别 Skill 目录 ~/.workbuddy/skills/ticktickpower/ 并加载本 Skill。无需额外配置，只需确保依赖安装完成。

常用任务示例

创建任务

# 基础任务
python -m ticktick.cli task "买咖啡" --list "个人"

# 带描述和优先级
python -m ticktick.cli task "Review PR" --list "工作" --content "检查新的认证改动" --priority high

# 带到期日期
python -m ticktick.cli task "提交报告" --list "工作" --due tomorrow
python -m ticktick.cli task "项目启动" --list "工作" --due "2026-04-20"
python -m ticktick.cli task "周会" --list "工作" --start "2026-04-26T14:00" --due "2026-04-26T15:00"

# 带标签
python -m ticktick.cli task "研究 AI 工具" --list "工作" --tag AI --tag research

# 带开始和到期时间（时间块）
python -m ticktick.cli task "深度工作时段" --list "工作" \
  --start "2026-04-20T09:00:00" --due "2026-04-20T12:00:00"

更新任务

# 修改优先级
python -m ticktick.cli task "买咖啡" --update --priority high

# 更新到期日期和描述
python -m ticktick.cli task "提交报告" --update --due "2026-04-25" --content "新报告内容"

# 重命名任务
python -m ticktick.cli task "旧标题" --update --new-title "新标题"

# 指定项目更新
python -m ticktick.cli task "Review PR" --update --list "工作" --priority medium

查看任务

# 列出所有任务
python -m ticktick.cli tasks

# 按项目过滤
python -m ticktick.cli tasks --list "工作"

# 按状态过滤
python -m ticktick.cli tasks --status pending
python -m ticktick.cli tasks --status completed

# JSON 输出（脚本使用）
python -m ticktick.cli tasks --list "工作" --json

完成任务 / 放弃任务

# 完成任务
python -m ticktick.cli complete "买咖啡"
python -m ticktick.cli complete "Review PR" --list "工作"

# 放弃任务
python -m ticktick.cli abandon "旧任务"
python -m ticktick.cli abandon "临时任务" --list "个人"

# 批量放弃（需要任务 ID）
python -m ticktick.cli batch-abandon abc123def456... xyz789... --json

项目管理

# 列出所有项目
python -m ticktick.cli lists --json

# 新建项目
python -m ticktick.cli list "新项目"
python -m ticktick.cli list "重要工作" --color "#FF5733"

# 更新项目
python -m ticktick.cli list "旧名称" --update --new-name "新名称"
python -m ticktick.cli list "工作" --update --color "#00FF00"

上传附件

# 通过任务名上传（需要 session cookie）
python -m ticktick.cli attach "买咖啡" /path/to/file.pdf --list "个人"

# 通过任务 ID 上传
python -m ticktick.cli attach abc123def456 /path/to/report.pdf --json

附件说明：附件上传使用 TickTick Web Session API（非 OAuth），需要 sessionCookie（t cookie）和 v2DeviceId。Cookie 有效期有限，过期后重新获取。

Agent 工作流

WorkBuddy Agent 调用此 Skill 的标准流程：

1. 确认项目 ID

python -m ticktick.cli lists --json

在 JSON 输出中找到目标项目的 id（24 字符字符串）。

2. 创建任务

python -m ticktick.cli task "Agent 任务" \
  --list "任务" \
  --priority high \
  --due tomorrow \
  --tag agent \
  --json

3. 完成任务

python -m ticktick.cli complete "Agent 任务" --list "任务" --json

4. 定期报告

# 获取待办任务（未完成）
python -m ticktick.cli tasks --status pending --json

配置说明

凭证存储在 ~/.clawdbot/credentials/ticktick-cli/config.json：

{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "accessToken": "...",
  "refreshToken": "...",
  "tokenExpiry": 1234567890000,
  "redirectUri": "http://localhost:8080"
}

安全注意：凭证明文存储，请设置文件权限 600。Token 过期时 CLI 会自动刷新。

日期格式

| 输入 | 说明 | |------|------| | today | 今天 23:59 | | tomorrow | 明天 23:59 | | in 3 days | 3 天后 23:59 | | next monday | 下周一 23:59 | | YYYY-MM-DD | 指定日期 23:59 | | YYYY-MM-DDTHH:MM | 精确时间（推荐使用时区） |

重要：始终使用明确时区的 ISO 日期（如 +08:00）以避免 UTC 转换问题。

优先级

| 值 | 说明 | |----|------| | none | 无优先级（默认） | | low | 低优先级 | | medium | 中优先级 | | high | 高优先级 |

API 限制

100 请求/分钟
300 请求/5 分钟

CLI 每个操作会发起多个 API 调用（如查找项目再查找任务），批量操作请注意限流。超过限制时 CLI 会自动等待并重试，最多重试 4 次。

故障排除

"Not authenticated"

运行 python -m ticktick.cli auth 重新认证。

"Project not found"

用 python -m ticktick.cli lists 确认项目名称。

"Task not found"

检查任务名称（大小写不敏感）
尝试使用任务 ID（24 位十六进制字符串）
加 --list 缩小搜索范围

Token 过期

CLI 自动刷新。如果持续失败，重新运行认证。

附件上传失败（401/403）

Session Cookie 已过期。在浏览器中打开 ticktick.com → F12 → Application → Cookies → 复制 t Cookie 值，更新到 config.json 的 sessionCookie 字段。不要提供密码。

技术架构

ticktickpower/
├── SKILL.md          # 本文件（Skill 说明）
├── pyproject.toml    # Python 包配置
├── ticktick/
│   ├── __init__.py
│   ├── api.py        # TickTick API 封装（含自动重试、限流处理）
│   ├── auth.py       # OAuth2 认证 + Token 管理
│   ├── cli.py        # CLI 入口 + argparse 定义
│   ├── util.py       # 日期解析、任务 ID 判断
│   └── commands/    # 各子命令实现
│       ├── task.py       # task create / update
│       ├── tasks.py      # tasks list
│       ├── complete.py   # 完成任务
│       ├── abandon.py    # 放弃任务
│       ├── batch_abandon.py  # 批量放弃
│       ├── list.py       # project create / update
│       ├── lists.py      # project list
│       └── attach.py     # 文件附件

Liubo's TickTick CLI