TickTick CLI 技能

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

设置

1. 注册 TickTick 开发者应用

1. 前往TickTick 开发者中心
2. 创建一个新的应用
3. 将重定向 URI 设置为http://localhost:8080
4. 记下您的客户端 ID和客户端密钥

2. 身份验证

# Set credentials and start OAuth flow
bun run scripts/ticktick.ts auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

# Check authentication status
bun run scripts/ticktick.ts auth --status

# Logout (clear tokens, keep credentials)
bun run scripts/ticktick.ts auth --logout

无头 / 手动身份验证

# Use manual mode on headless servers
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 将打开您的浏览器以授权访问。批准后，令牌将存储在~/.clawdbot/credentials/ticktick-cli/config.json中。

命令

列出任务

# List all tasks
bun run scripts/ticktick.ts tasks

# List tasks from a specific project
bun run scripts/ticktick.ts tasks --list "Work"

# Filter by status
bun run scripts/ticktick.ts tasks --status pending
bun run scripts/ticktick.ts tasks --status completed

# JSON output
bun run scripts/ticktick.ts tasks --json

创建任务

# Basic task creation
bun run scripts/ticktick.ts task "Buy groceries" --list "Personal"

# With description and priority
bun run scripts/ticktick.ts task "Review PR" --list "Work" --content "Check the new auth changes" --priority high

# With due date
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"

# With tags
bun run scripts/ticktick.ts task "Research" --list "Work" --tag research important

更新任务

# Update by task name or 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"

# Limit search to specific project
bun run scripts/ticktick.ts task "Review PR" --update --list "Work" --priority low

完成任务

# Mark task as complete
bun run scripts/ticktick.ts complete "Buy groceries"

# Complete with project filter
bun run scripts/ticktick.ts complete "Review PR" --list "Work"

放弃任务（将不做）

# Mark task as won't do
bun run scripts/ticktick.ts abandon "Old task"

# Abandon with project filter
bun run scripts/ticktick.ts abandon "Obsolete item" --list "Do"

批量放弃（多个任务）

# Abandon multiple tasks in a single API call
bun run scripts/ticktick.ts batch-abandon <taskId1> <taskId2> <taskId3>

# With JSON output
bun run scripts/ticktick.ts batch-abandon abc123def456... xyz789... --json

注意：批量放弃需要任务ID（24位十六进制字符串），而非任务名称。请先使用tasks --json命令获取任务ID。

列出项目

# List all projects
bun run scripts/ticktick.ts lists

# JSON output
bun run scripts/ticktick.ts lists --json

创建项目

# Create new project
bun run scripts/ticktick.ts list "New Project"

# With color
bun run scripts/ticktick.ts list "Work Tasks" --color "#FF5733"

更新项目

# Rename project
bun run scripts/ticktick.ts list "Old Name" --update --name "New Name"

# Change color
bun run scripts/ticktick.ts list "Work" --update --color "#00FF00"

选项参考

优先级级别

• 无- 无优先级（默认）
• 低- 低优先级
• 中- 中优先级
• 高- 高优先级

截止日期格式

• 今天- 今天截止
• 明天- 明天截止
• N天内- N天内截止（例如："3天内"）
• 下周一- 下一个工作日
• ISO日期格式 -YYYY-MM-DD或完整ISO格式

全局选项

• --json- 以JSON格式输出结果（适用于脚本处理）
• --help- 显示任何命令的帮助信息

智能体使用提示

当将此功能作为AI智能体使用时：

1. 始终使用--json标志以获取机器可读的输出
2. 首先列出项目与以JSON格式列出项目以获取有效的项目ID
3. 使用项目ID尽可能使用项目ID而非名称以确保可靠性
4. 检查任务状态在完成任务前检查状态以避免错误

示例代理工作流：

# 1. Get available projects
bun run scripts/ticktick.ts lists --json

# 2. Create a task in a specific project
bun run scripts/ticktick.ts task "Agent task" --list "PROJECT_ID" --priority high --json

# 3. Later, mark it complete
bun run scripts/ticktick.ts complete "Agent task" --list "PROJECT_ID" --json

配置

令牌存储在~/.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会在令牌过期时自动刷新。

故障排除

"未认证"错误

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

"项目未找到"错误

使用bun run scripts/ticktick.ts lists查看可用的项目及其ID。

"找不到任务"错误

• 检查任务标题是否完全匹配（不区分大小写）
• 尝试改用任务ID
• 使用--list将搜索范围限定到特定项目

令牌过期错误

CLI应自动刷新令牌。如果问题持续存在，请再次运行bun run scripts/ticktick.ts auth。

API说明

此CLI使用TickTick开放API v1。

速率限制

• 每分钟100个请求
• 每5分钟300个请求

CLI每次操作（如列出项目以查找任务）会进行多次API调用，因此批量操作可能很快触及限制。

批量端点

此CLI支持TickTick的批量端点以执行批量操作：

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

使用批量放弃功能，可以在一次API调用中放弃多个任务。该批量API方法也支持通过编程方式使用。

其他限制

• 每个项目最多500个任务
• 部分高级功能（如专注时间、习惯追踪）暂不支持API调用