名称： ticktick
描述： 通过命令行管理 TickTick 任务与项目，支持 OAuth2 认证、批量操作和速率限制处理。

TickTick CLI 技能

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

设置

1. 注册 TickTick 开发者应用

1. 访问 TickTick 开发者中心
2. 创建一个新应用
3. 将重定向 URI 设置为 http://localhost:8080
4. 记录你的 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

# 登出（清除令牌，保留凭证）
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 将打开浏览器以授权访问。批准后，令牌将存储在 ~/.clawdbot/credentials/ticktick-cli/config.json 中。

命令

列出任务

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

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

# 按状态筛选
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 "购买杂货" --list "个人"

# 包含描述和优先级
bun run scripts/ticktick.ts task "审查 PR" --list "工作" --content "检查新的认证变更" --priority high

# 包含截止日期
bun run scripts/ticktick.ts task "提交报告" --list "工作" --due tomorrow
bun run scripts/ticktick.ts task "计划假期" --list "个人" --due "in 7 days"
bun run scripts/ticktick.ts task "会议" --list "工作" --due "2024-12-25"

# 包含标签
bun run scripts/ticktick.ts task "研究" --list "工作" --tag research important

更新任务

# 通过任务名称或 ID 更新
bun run scripts/ticktick.ts task "购买杂货" --update --priority medium
bun run scripts/ticktick.ts task "abc123" --update --due tomorrow --content "更新后的笔记"

# 将搜索限制在特定项目
bun run scripts/ticktick.ts task "审查 PR" --update --list "工作" --priority low

完成任务

# 将任务标记为完成
bun run scripts/ticktick.ts complete "购买杂货"

# 带项目筛选的完成
bun run scripts/ticktick.ts complete "审查 PR" --list "工作"

放弃任务（不做）

# 将任务标记为“不做”
bun run scripts/ticktick.ts abandon "旧任务"

# 带项目筛选的放弃
bun run scripts/ticktick.ts abandon "过时项目" --list "待办"

批量放弃（多个任务）

# 在单个 API 调用中放弃多个任务
bun run scripts/ticktick.ts batch-abandon <taskId1> <taskId2> <taskId3>

# 带 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 "新项目"

# 带颜色
bun run scripts/ticktick.ts list "工作任务" --color "#FF5733"

更新项目

# 重命名项目
bun run scripts/ticktick.ts list "旧名称" --update --name "新名称"

# 更改颜色
bun run scripts/ticktick.ts list "工作" --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 代理使用技巧

将此技能用作 AI 代理时：

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

示例代理工作流：

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

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

# 3. 稍后，将其标记为完成
bun run scripts/ticktick.ts complete "代理任务" --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 }[]
}

使用 batch-abandon 可在一次 API 调用中放弃多个任务。批量 API 方法也暴露供编程使用。

其他限制

• 每个项目最多 500 个任务
• API 不支持某些高级功能（如专注时间、习惯）