TickTick Power Skill

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

核心功能

快速开始

1. 安装依赖

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

2. 注册开发者应用

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

3. 认证

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

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

# 手动认证（无浏览器 / Linux 服务器）
python -m ticktick.cli auth --client-id \x3CID> --client-secret \x3CSECRET> --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 会自动刷新。

日期格式

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

优先级

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     # 文件附件

相关链接

• TickTick Developer Center
• TickTick Open API v1
• dida365.com
• GitHub: liuboacean/ticktick-cli