TickTick CLI_知识管理 skill-PHP中文网

TickTick CLI

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

通过命令行管理 TickTick 任务与项目，支持 OAuth2 认证、批量操作及速率限制处理。

TickTick CLI 技能

功能概述

TickTick CLI 技能是一项面向实际任务的技能，主要用于管理 TickTick 任务和来自命令行的项目；Setup. 注册一个 TickTick 开发者 App.；

核心要点

Go to TickTick 开发者中心.；
Go Create a new application. 选择重定向 URI t。
它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

使用与执行

使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。

结果检查与注意事项

执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。该技能适合用于一次性任务，也可以接入自动化工作流，与其他技能或上层代理配合完成更完整的业务链路；在组合使用时，应明确每一步的输入输出关系，并避免不同步骤之间出现参数冲突。

TickTick CLI 技能

通过命令行管理 TickTick 任务与项目。

配置

1. 注册 TickTick 开发者应用

访问 TickTick 开发者中心
创建一个新应用
将重定向 URI（Redirect URI）设为 http://localhost:8080
记录下你的 Client ID 和 Client Secret

2. 认证

# 设置凭证并启动 OAuth 流程
bun run scripts/ticktick.ts auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

# 检查认证状态
bun run scripts/ticktick.ts auth --status

# 注销（清除 token，保留凭证）
bun run scripts/ticktick.ts auth --logout

无头环境 / 手动认证

# 在无头服务器上使用手动模式
bun run scripts/ticktick.ts auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --manual

该命令会打印一条授权 URL。请在浏览器中打开此链接，批准访问权限后，复制完整的重定向 URL（形如 http://localhost:8080/?code=XXXXX&state=STATE），然后将其粘贴回 CLI 中。

CLI 将自动在浏览器中打开授权页面。授权完成后，token 将保存至 ~/.clawdbot/credentials/ticktick-cli/config.json。

命令

列出任务

# 列出所有任务
bun run scripts/ticktick.ts tasks

# 列出指定项目中的任务
bun run scripts/ticktick.ts tasks --list "Work"

# 按状态过滤
bun run scripts/ticktick.ts tasks --status pending
bun run scripts/ticktick.ts tasks --status completed

# 输出 JSON 格式
bun run scripts/ticktick.ts tasks --json

创建任务

# 基础任务创建
bun run scripts/ticktick.ts task "Buy groceries" --list "Personal"

# 指定描述与优先级
bun run scripts/ticktick.ts task "Review PR" --list "Work" --content "Check the new auth changes" --priority high

# 指定截止日期
bun run scripts/ticktick.ts task "Submit report" --list "Work" --due tomorrow
bun run scripts/ticktick.ts task "Plan vacation" --list "Personal" --due "in 7 days"
bun run scripts/ticktick.ts task "Meeting" --list "Work" --due "2024-12-25"

# 添加标签
bun run scripts/ticktick.ts task "Research" --list "Work" --tag research important

更新任务

# 通过任务名称或 ID 更新
bun run scripts/ticktick.ts task "Buy groceries" --update --priority medium
bun run scripts/ticktick.ts task "abc123" --update --due tomorrow --content "Updated notes"

# 限定在特定项目中搜索并更新
bun run scripts/ticktick.ts task "Review PR" --update --list "Work" --priority low

完成任务

# 将任务标记为已完成
bun run scripts/ticktick.ts complete "Buy groceries"

# 在指定项目中完成任务
bun run scripts/ticktick.ts complete "Review PR" --list "Work"

放弃任务（Won't Do）

# 将任务标记为 Won't Do
bun run scripts/ticktick.ts abandon "Old task"

# 在指定项目中放弃任务
bun run scripts/ticktick.ts abandon "Obsolete item" --list "Do"

批量放弃（多个任务）

# 单次 API 调用批量放弃多个任务
bun run scripts/ticktick.ts batch-abandon   

# 输出 JSON 格式
bun run scripts/ticktick.ts batch-abandon abc123def456... xyz789... --json

注意：batch-abandon 需要传入任务 ID（24 位十六进制字符串），而非任务名称。请先使用 tasks --json 获取任务 ID。

列出项目

# 列出所有项目
bun run scripts/ticktick.ts lists

# 输出 JSON 格式
bun run scripts/ticktick.ts lists --json

创建项目

# 创建新项目
bun run scripts/ticktick.ts list "New Project"

# 指定颜色
bun run scripts/ticktick.ts list "Work Tasks" --color "#FF5733"

更新项目

# 重命名项目
bun run scripts/ticktick.ts list "Old Name" --update --name "New Name"

# 修改颜色
bun run scripts/ticktick.ts list "Work" --update --color "#00FF00"

选项参考

优先级等级

none — 无优先级（默认）
low — 低优先级
medium — 中优先级
high — 高优先级

截止日期格式

today — 今日截止
tomorrow — 明日截止
in N days — N 天后截止（例如："in 3 days"）
next monday — 下一个指定工作日（如周一）
ISO 日期格式 — YYYY-MM-DD 或完整 ISO 时间格式

全局选项

--json — 以 JSON 格式输出结果（适用于脚本调用）
--help — 查看任意命令的帮助信息

AI Agent 使用建议

将本技能作为 AI Agent 使用时，请注意：

始终使用 --json 参数，确保输出为机器可读格式
首先执行 lists --json 获取有效的项目 ID
尽可能使用项目 ID 而非项目名，以提升操作可靠性
完成任务前请先检查其状态，避免因状态不匹配导致错误

示例 Agent 工作流：

# 1. 获取可用项目列表
bun run scripts/ticktick.ts lists --json

# 2. 在指定项目中创建任务
bun run scripts/ticktick.ts task "Agent task" --list "PROJECT_ID" --priority high --json

# 3. 后续将其标记为已完成
bun run scripts/ticktick.ts complete "Agent task" --list "PROJECT_ID" --json

配置

Token 存储于 ~/.clawdbot/credentials/ticktick-cli/config.json：

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

注意：凭证以明文形式存储。CLI 会尝试将文件权限设为 700（目录）或 600（文件），请将该文件视为敏感信息妥善保管。

CLI 在 token 过期时会自动刷新。

故障排查

“未认证”错误

运行 bun run scripts/ticktick.ts auth 完成认证。

“项目未找到”错误

运行 bun run scripts/ticktick.ts lists 查看当前可用的项目及其 ID。

“任务未找到”错误

确认任务标题完全匹配（不区分大小写）
尝试改用任务 ID
使用 --list 参数将搜索范围限定在特定项目内

Token 过期错误

CLI 应能自动刷新 token。若问题持续存在，请再次运行 bun run scripts/ticktick.ts auth。

API 说明

本 CLI 使用 TickTick Open API v1。

速率限制

每分钟最多 100 次请求
每 5 分钟最多 300 次请求

由于 CLI 的每个操作可能涉及多次 API 调用（例如：先列出项目再查找任务），批量操作容易快速触达限制。

批量接口（Batch Endpoint）

CLI 支持 TickTick 的批量接口用于执行批量操作：

POST https://api.ticktick.com/open/v1/batch/task
{
  "add": [...],    // CreateTaskInput[]
  "update": [...], // UpdateTaskInput[]
  "delete": [...]  // { taskId, projectId }[]
}

使用 batch-abandon 可单次 API 调用放弃多个任务。该批量 API 方法也对外暴露，支持程序化调用。