TickTick CLI — TickTick 命令行工具

TickTick Power 技能

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

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

• 安装依赖

pip 安装 -e ~/.workbuddy/技能s/ticktickpower/ # 或直接安装 请求s pip 安装 请求s

• 注册开发者应用

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

• 认证

# 交互式认证（自动打开浏览器） python -m ticktick.命令行工具 auth --命令行工具ent-id --命令行工具ent-secret

# 检查认证状态 python -m ticktick.命令行工具 auth --状态

# 手动认证（无浏览器 / Linux 服务器） python -m ticktick.命令行工具 auth --命令行工具ent-id --命令行工具ent-secret --manual

# 退出登录（清除 令牌，保留凭证） python -m ticktick.命令行工具 auth --记录out

• 配置 WorkBuddy 技能 触发

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

常用任务示例 创建任务 # 基础任务 python -m ticktick.命令行工具 task "买咖啡" --列出 "个人"

# 带描述和优先级 python -m ticktick.命令行工具 task "Review PR" --列出 "工作" --content "检查新的认证改动" --priority high

# 带到期日期 python -m ticktick.命令行工具 task "提交报告" --列出 "工作" --due tomorrow python -m ticktick.命令行工具 task "项目启动" --列出 "工作" --due "2026-04-20" python -m ticktick.命令行工具 task "周会" --列出 "工作" --启动 "2026-04-26T14:00" --due "2026-04-26T15:00"

# 带标签 python -m ticktick.命令行工具 task "研究 AI 工具" --列出 "工作" --tag AI --tag re搜索

# 带开始和到期时间（时间块） python -m ticktick.命令行工具 task "深度工作时段" --列出 "工作" \ --启动 "2026-04-20T09:00:00" --due "2026-04-20T12:00:00"

更新任务 # 修改优先级 python -m ticktick.命令行工具 task "买咖啡" --更新 --priority high

# 更新到期日期和描述 python -m ticktick.命令行工具 task "提交报告" --更新 --due "2026-04-25" --content "新报告内容"

# 重命名任务 python -m ticktick.命令行工具 task "旧标题" --更新 --new-title "新标题"

# 指定项目更新 python -m ticktick.命令行工具 task "Review PR" --更新 --列出 "工作" --priority medium

查看任务 # 列出所有任务 python -m ticktick.命令行工具 tasks

# 按项目过滤 python -m ticktick.命令行工具 tasks --列出 "工作"

# 按状态过滤 python -m ticktick.命令行工具 tasks --状态 pending python -m ticktick.命令行工具 tasks --状态 completed

# JSON 输出（脚本使用） python -m ticktick.命令行工具 tasks --列出 "工作" --json

完成任务 / 放弃任务 # 完成任务 python -m ticktick.命令行工具 complete "买咖啡" python -m ticktick.命令行工具 complete "Review PR" --列出 "工作"

# 放弃任务 python -m ticktick.命令行工具 abandon "旧任务" python -m ticktick.命令行工具 abandon "临时任务" --列出 "个人"

# 批量放弃（需要任务 ID） python -m ticktick.命令行工具 batch-abandon abc123def456... xyz789... --json

项目管理 # 列出所有项目 python -m ticktick.命令行工具 列出s --json

# 新建项目 python -m ticktick.命令行工具 列出 "新项目" python -m ticktick.命令行工具 列出 "重要工作" --color "#FF5733"

# 更新项目 python -m ticktick.命令行工具 列出 "旧名称" --更新 --new-name "新名称" python -m ticktick.命令行工具 列出 "工作" --更新 --color "#00FF00"

上传附件 # 通过任务名上传（需要 会话 cookie） python -m ticktick.命令行工具 attach "买咖啡" /path/to/file.pdf --列出 "个人"

# 通过任务 ID 上传 python -m ticktick.命令行工具 attach abc123def456 /path/to/报告.pdf --json

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

代理 工作流

WorkBuddy 代理 调用此 技能 的标准流程：

• 确认项目 ID

python -m ticktick.命令行工具 列出s --json

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

• 创建任务

python -m ticktick.命令行工具 task "代理 任务" \ --列出 "任务" \ --priority high \ --due tomorrow \ --tag 代理 \ --json

• 完成任务

python -m ticktick.命令行工具 complete "代理 任务" --列出 "任务" --json

• 定期报告

# 获取待办任务（未完成） python -m ticktick.命令行工具 tasks --状态 pending --json

配置说明

凭证存储在 ~/.clawd机器人/凭证s/ticktick-命令行工具/config.json：

{ "命令行工具entId": "YOUR_命令行工具ENT_ID", "命令行工具entSecret": "YOUR_命令行工具ENT_SECRET", "访问令牌": "...", "refresh令牌": "...", "令牌Expiry": 1234567890000, "redirectUri": "http://localhost:8080" }

安全注意：凭证明文存储，请设置文件权限 600。令牌 过期时 命令行工具 会自动刷新。

日期格式 输入 说明 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 分钟

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

故障排除 "Not 认证d"

运行 python -m ticktick.命令行工具 auth 重新认证。

"Project not found"

用 python -m ticktick.命令行工具 列出s 确认项目名称。

"Task not found" 检查任务名称（大小写不敏感） 尝试使用任务 ID（24 位十六进制字符串） 加 --列出 缩小搜索范围 令牌 过期

命令行工具 自动刷新。如果持续失败，重新运行认证。

附件上传失败（401/403）

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

技术架构 ticktickpower/ ├── 技能.md # 本文件（技能 说明） ├── pyproject.toml # Python 包配置 ├── ticktick/ │ ├── __init__.py │ ├── API.py # TickTick API 封装（含自动重试、限流处理） │ ├── auth.py # OAuth2 认证 + 令牌 管理 │ ├── 命令行工具.py # 命令行工具 入口 + arg解析 定义 │ ├── util.py # 日期解析、任务 ID 判断 │ └── commands/ # 各子命令实现 │ ├── task.py # task 创建 / 更新 │ ├── tasks.py # tasks 列出 │ ├── complete.py # 完成任务