ticktick, dida365, 滴答清单, 任务管理, 新建任务, 完成任务, 创建任务, 列出任务, 查看任务, 更新任务, 删除任务, 放弃任务, 批量放弃, 任务提醒, 任务优先级, 任务标签, 任务到期, 任务开始时间, 滴答项目, 滴答列表, 创建项目, 更新项目, 滴答附件, 上传附件, tic...
---
name: ticktickpower
description: >
ticktick, dida365, 滴答清单, 任务管理, 新建任务, 完成任务, 创建任务,
列出任务, 查看任务, 更新任务, 删除任务, 放弃任务, 批量放弃,
任务提醒, 任务优先级, 任务标签, 任务到期, 任务开始时间,
滴答项目, 滴答列表, 创建项目, 更新项目, 滴答附件, 上传附件,
ticktick auth, 滴答认证, 滴答登录, 任务导入, 任务导出,
add task, create task, list tasks, complete task, abandon task,
ticktick project, ticktick list, ticktick reminder, ticktick oauth
---
# TickTick Power Skill
通过滴答清单(TickTick)API 管理任务和项目,支持 OAuth2 认证、批量操作、优先级、标签、到期时间和文件附件。
## 核心功能
| 功能 | 命令 | 说明 |
|------|------|------|
| 认证 | `auth` | OAuth2 浏览器认证或手动模式 |
| 任务列表 | `tasks` | 列出所有任务,支持项目和状态过滤 |
| 新建任务 | `task` | 创建任务,支持优先级/标签/到期时间 |
| 更新任务 | `task --update` | 更新任务标题/内容/优先级/日期 |
| 完成任务 | `complete` | 标记任务为已完成 |
| 放弃任务 | `abandon` | 标记任务为"不会做" |
| 批量放弃 | `batch-abandon` | 批量放弃任务(单次 API 调用) |
| 项目列表 | `lists` | 列出所有项目 |
| 新建项目 | `list` | 创建新项目 |
| 更新项目 | `list --update` | 更新项目名称/颜色 |
| 上传附件 | `attach` | 上传文件附件到任务 |
## 快速开始
### 1. 安装依赖
```bash
pip install -e ~/.workbuddy/skills/ticktickpower/
# 或直接安装 requests
pip install requests
```
### 2. 注册开发者应用
1. 访问 [TickTick Developer Center](https://developer.ticktick.com/manage)
2. 创建新应用,设置重定向 URI 为 `http://localhost:8080`
3. 记录 `Client ID` 和 `Client Secret`
### 3. 认证
```bash
# 交互式认证(自动打开浏览器)
python -m ticktick.cli auth --client-id <YOUR_CLIENT_ID> --client-secret <YOUR_CLIENT_SECRET>
# 检查认证状态
python -m ticktick.cli auth --status
# 手动认证(无浏览器 / Linux 服务器)
python -m ticktick.cli auth --client-id <ID> --client-secret <SECRET> --manual
# 退出登录(清除 Token,保留凭证)
python -m ticktick.cli auth --logout
```
### 4. 配置 WorkBuddy Skill 触发
WorkBuddy 会自动识别 Skill 目录 `~/.workbuddy/skills/ticktickpower/` 并加载本 Skill。
无需额外配置,只需确保依赖安装完成。
## 常用任务示例
### 创建任务
```bash
# 基础任务
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"
```
### 更新任务
```bash
# 修改优先级
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
```
### 查看任务
```bash
# 列出所有任务
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
```
### 完成任务 / 放弃任务
```bash
# 完成任务
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
```
### 项目管理
```bash
# 列出所有项目
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"
```
### 上传附件
```bash
# 通过任务名上传(需要 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
```bash
python -m ticktick.cli lists --json
```
在 JSON 输出中找到目标项目的 `id`(24 字符字符串)。
### 2. 创建任务
```bash
python -m ticktick.cli task "Agent 任务" \
--list "任务" \
--priority high \
--due tomorrow \
--tag agent \
--json
```
### 3. 完成任务
```bash
python -m ticktick.cli complete "Agent 任务" --list "任务" --json
```
### 4. 定期报告
```bash
# 获取待办任务(未完成)
python -m ticktick.cli tasks --status pending --json
```
## 配置说明
凭证存储在 `~/.clawdbot/credentials/ticktick-cli/config.json`:
```json
{
"clientId": "YOUR_CLIENT_ID",
"clientSecret": "YOUR_CLIENT_SECRET",
"accessToken": "...",
"refreshToken": "...",
"tokenExpiry": 1234567890000,
"redirectUri": "http://localhost:8080"
}
```
**安全注意**:凭证明文存储,请设置文件权限 `600`。Token 过期时 CLI 会自动刷新。
## 日期格式
| 输入 | 说明 |
|------|------|
| `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 分钟**
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](https://developer.ticktick.com/manage)
- [TickTick Open API v1](https://developer.ticktick.com/api)
- [dida365.com](https://dida365.com)
- [GitHub: liuboacean/ticktick-cli](https://github.com/liuboacean/ticktick-cli)
don't have the plugin yet? install it then click "run inline in claude" again.
restructured original chinese and english mixed docs into implexa's 6-component format, added explicit decision points for auth failure/token expiry/rate limits/name ambiguity, documented oauth2 and session cookie external connections, formalized task/project json schemas, added edge cases (headless auth, expired cookies, task lookup priority), applied lowercase punchy voice and removed em-dashes.
manage tasks and projects in ticktick (dida365) via oauth2-authenticated cli. create, update, complete, abandon tasks with priorities, tags, due dates, and file attachments. list and manage projects. supports batch operations and automatic token refresh.
use this skill to programmatically interact with ticktick task management. run this when you need to create tasks, mark tasks complete or abandoned, update task metadata (priority, due date, tags, descriptions), list tasks filtered by project or status, manage projects, or upload file attachments. typical use cases: agent workflows that generate or track tasks, syncing external data into ticktick, bulk task operations, periodic task status reports.
external connection: ticktick oauth2
http://localhost:8080credentials storage location
~/.clawdbot/credentials/ticktick-cli/config.json600 (owner read/write only)environment / context
rate limits to track
input: client id, client secret (from developer center)
output: access token, refresh token, expiry timestamp written to ~/.clawdbot/credentials/ticktick-cli/config.json
steps:
python -m ticktick.cli auth --client-id <ID> --client-secret <SECRET>python -m ticktick.cli auth --status prints current auth statepython -m ticktick.cli auth --logoutinput: none (uses stored credentials)
output: json array of project objects with fields: id (24-char hex), name (string), color (hex string)
steps:
python -m ticktick.cli lists --jsoninput:
output: task object json with fields: id, title, priority, dueDate, startDate, tags, projectId
steps:
python -m ticktick.cli task "<TITLE>" --list "<PROJECT>" --priority <PRIORITY> --due "<DATE>" --content "<DESC>" --tag "<TAG1>" --tag "<TAG2>" --jsoninput:
output: updated task object json
steps:
python -m ticktick.cli task "<IDENTIFIER>" --update --list "<PROJECT>" --new-title "<NEW>" --priority <P> --due "<D>" --content "<DESC>" --jsoninput:
output: json array of task objects with fields: id, title, priority, dueDate, startDate, status, projectId, tags
steps:
python -m ticktick.cli tasks --list "<PROJECT>" --status <STATUS> --jsoninput:
output: success message or updated task object
steps:
python -m ticktick.cli complete "<IDENTIFIER>" --list "<PROJECT>" --jsoninput:
output: success message or updated task object
steps:
python -m ticktick.cli abandon "<IDENTIFIER>" --list "<PROJECT>" --jsoninput:
output: success message with count of abandoned tasks
steps:
python -m ticktick.cli batch-abandon <ID1> <ID2> <ID3> --jsoninput:
output: project object json with fields: id, name, color
steps:
python -m ticktick.cli list "<NAME>" --color "<HEXCOLOR>" --jsoninput:
output: updated project object json
steps:
python -m ticktick.cli list "<IDENTIFIER>" --update --new-name "<NEWNAME>" --color "<HEXCOLOR>" --jsoninput:
output: success message with attachment metadata (attachment id, filename, size)
steps:
python -m ticktick.cli attach "<IDENTIFIER>" /path/to/file --list "<PROJECT>" --jsonif user not authenticated: cli returns "not authenticated" error. user must run auth flow (step 1) before any task operations.
if project name not found: cli returns "project not found" error. user should run lists --json to verify correct project name and then use returned project id instead of name.
if task name not found: cli tries case-insensitive match on task title. if still no match, cli returns "task not found". user should try tasks --list <PROJECT> --json to list all tasks and find exact title or id.
if task id provided instead of name: cli uses id directly without lookup, skipping name-based search entirely. id is 24-character hexadecimal string.
if access token expired: cli detects expiry via api 401 response, automatically calls refresh endpoint with refresh token, stores new access token to disk, and retries original request. if refresh token also expired, user must re-run auth flow.
if rate limit hit (429 response): cli pauses, waits with exponential backoff (1s, 2s, 4s, 8s), and retries up to 4 times. if still failing after 4 retries, cli returns rate limit error. user should wait 1-5 minutes before retrying.
if attachment upload fails with 401/403: session cookie (web api, not oauth) has expired. user must manually obtain fresh session cookie from browser (open ticktick.com, f12 dev tools, application tab, cookies, copy t cookie value) and update sessionCookie field in config.json. do not provide password.
if no browser available (headless server): user can run auth with --manual flag: python -m ticktick.cli auth --client-id <ID> --client-secret <SECRET> --manual. cli prints auth url; user visits url in any browser, grants permission, and copy-pastes auth code back to cli prompt.
if due date string is ambiguous (e.g., "04-20"): cli assumes YYYY-MM-DD format. always provide full 4-digit year or use unambiguous strings (today, tomorrow, in N days, next monday) to avoid parsing errors.
if task has no due date set: due date fields in json output will be null or omitted. update operations should not include --due if no change desired.
if multiple tasks match name in same project: cli returns first match (oldest created first, typically). to avoid ambiguity, use task id (24-char hex) instead of name.
all commands support --json flag for machine-readable output.
task object schema:
{
"id": "6f52a3d1c2b4e8f9a1d3c5e7",
"title": "Buy coffee",
"content": "Optional description here",
"priority": "high",
"status": "pending",
"dueDate": "2026-04-20T23:59:59+08:00",
"startDate": "2026-04-20T09:00:00+08:00",
"tags": ["shopping", "urgent"],
"projectId": "6f52a3d1c2b4e8f9a1d3c5e7",
"createdTime": "2026-04-18T10:30:00+08:00",
"modifiedTime": "2026-04-18T11:45:00+08:00"
}
project object schema:
{
"id": "6f52a3d1c2b4e8f9a1d3c5e7",
"name": "Work",
"color": "#FF5733",
"kind": "LIST",
"sortOrder": 1
}
list tasks output: json array of task objects
list projects output: json array of project objects
create/update task output: single task object json
create/update project output: single project object json
batch abandon output:
{
"success": true,
"abandonedCount": 3,
"taskIds": ["id1", "id2", "id3"]
}
error output:
{
"error": "error message here",
"code": "TASK_NOT_FOUND"
}
credentials file location: ~/.clawdbot/credentials/ticktick-cli/config.json (json format, file perms 600)
authentication success: auth --status returns "authenticated" and shows token expiry timestamp.
task created: cli returns json object with non-null id field. task appears in ticktick app immediately.
task updated: cli returns json object with updated fields reflecting changes (title, priority, due date, etc.).
task completed: task status field in returned json is "completed". task moves to completed section in ticktick app.
task abandoned: task status field in returned json is "canceled". task removed from pending view in ticktick app.
project created: cli returns json object with non-null id and name matching input.
project updated: cli returns json object with updated name or color matching input.
file attachment uploaded: cli returns attachment metadata json with non-null attachment id. file appears in task attachments in ticktick app.
list tasks: cli returns json array with 1+ task objects. if no tasks match filter, returns empty array [].
list projects: cli returns json array with 1+ project objects. if no projects, returns empty array [].
cli operation failure: cli returns error json with "error" and "code" fields. check error message for specific cause (not authenticated, project not found, rate limited, etc.). see troubleshooting section of original docs for remediation.
date format support:
priority levels:
task status values:
api rate limits:
file attachment notes:
t cookie (session cookie) in config, not oauth tokengithub repository: https://github.com/liuboacean/ticktick-cli