介绍
# ClickUp Skill
与 ClickUp 的 REST API 交互，进行任务管理、报告和工作流自动化。
## 配置
在使用此技能之前，请确保在 `TOOLS.md` 中配置了以下内容：
- **API 令牌：** `CLICKUP_API_KEY` - **团队/工作区 ID：** `CLICKUP_TEAM_ID` - **空间 ID**（可选，用于筛选） - **列表 ID**（可选，用于创建任务）
## 快速开始
### 使用辅助脚本
查询 ClickUp 最快的方式：
```bash # Set environment variables export CLICKUP_API_KEY="pk_..." export CLICKUP_TEAM_ID="90161392624"
# Get all open tasks ./scripts/clickup-query.sh tasks
# Get task counts (parent vs subtasks) ./scripts/clickup-query.sh task-count
# Get assignee breakdown ./scripts/clickup-query.sh assignees
# Get specific task ./scripts/clickup-query.sh task <task-id> ```
### 直接 API 调用
对于辅助脚本未涵盖的自定义查询或操作：
```bash # Get all open tasks (with subtasks and pagination) curl "https://api.clickup.com/api/v2/team/{team_id}/task?include_closed=false&subtasks=true" \ -H "Authorization: {api_key}" ```
## 关键规则
### 1. 始终包含子任务
**切勿**在查询任务时不带 `subtasks=true`：
```bash # ✅ CORRECT ?subtasks=true
# ❌ WRONG (no subtasks parameter) ```
**原因：** 如果不带此参数，你可能会遗漏 70% 以上的实际任务。父任务只是容器；实际工作是在子任务中进行的。
### 2. 处理分页
ClickUp API 每页最多返回 100 个任务。**始终**循环直到 `last_page: true`：
```bash page=0 while true; do result=$(curl -s "...&page=$page" -H "Authorization: $CLICKUP_API_KEY") # Process tasks echo "$result" | jq '.tasks[]' # Check if done is_last=$(echo "$result" | jq -r '.last_page') [ "$is_last" = "true" ] && break ((page++)) done ```
**原因：** 拥有 300+ 任务的工作区需要 3-4 页。漏掉页面 = 数据不完整。
### 3. 区分父任务与子任务
```bash # Parent tasks have parent=null jq '.tasks[] | select(.parent == null)'
# Subtasks have parent != null jq '.tasks[] | select(.parent != null)' ```
## 常见操作
### 获取任务计数
```bash # Using helper script (recommended) ./scripts/clickup-query.sh task-count
# Direct API with jq curl -s "https://api.clickup.com/api/v2/team/{team_id}/task?subtasks=true" \ -H "Authorization: {api_key}" | \ jq '{ total: (.tasks | length), parents: ([.tasks[] | select(.parent == null)] | length), subtasks: ([.tasks[] | select(.parent != null)] | length) }' ```
### 获取负责人细分
```bash # Using helper script (recommended) ./scripts/clickup-query.sh assignees
# Direct API curl -s "https://api.clickup.com/api/v2/team/{team_id}/task?subtasks=true" \ -H "Authorization: {api_key}" | \ jq -r '.tasks[] | if .assignees and (.assignees | length) > 0 then .assignees[0].username else "Unassigned" end' | sort | uniq -c | sort -rn ```
### 创建任务
```bash curl "https://api.clickup.com/api/v2/list/{list_id}/task" \ -X POST \ -H "Authorization: {api_key}" \ -H "Content-Type: application/json" \ -d '{ "name": "Task Name", "description": "Description here", "assignees": [user_id], "status": "to do", "priority": 3 }' ```
### 更新任务
```bash curl "https://api.clickup.com/api/v2/task/{task_id}" \ -X PUT \ -H "Authorization: {api_key}" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Name", "status": "in progress", "priority": 2 }' ```
### 获取特定任务
```bash # Using helper script ./scripts/clickup-query.sh task {task_id}
# Direct API curl "https://api.clickup.com/api/v2/task/{task_id}" \ -H "Authorization: {api_key}" ```
## 高级查询
### 按空间筛选
```bash curl "https://api.clickup.com/api/v2/team/{team_id}/task?space_ids[]={space_id}&subtasks=true" \ -H "Authorization: {api_key}" ```
### 按列表筛选
```bash curl "https://api.clickup.com/api/v2/list/{list_id}/task?subtasks=true" \ -H "Authorization: {api_key}" ```
### 包含已关闭任务
```bash curl "https://api.clickup.com/api/v2/team/{team_id}/task?include_closed=true&subtasks=true" \ -H "Authorization: {api_key}" ```
## 参考文档
有关详细的 API 文档、查询模式和故障排除：
**阅读：** `references/api-guide.md`
涵盖内容： - 完整的 API 端点参考 - 响应结构详细信息 - 常见陷阱和解决方案 - 速率限制和最佳实践 - 任务对象架构
## 工作流模式
### 每日站会报告
```bash # Get all open tasks grouped by assignee ./scripts/clickup-query.sh assignees
# Get specific team member's tasks (use user ID, not username!) curl "https://api.clickup.com/api/v2/team/{team_id}/task?subtasks=true&assignees[]={user_id}" \ -H "Authorization: {api_key}" ```
### 任务审计
```bash # Count tasks by status ./scripts/clickup-query.sh tasks | \ jq -r '.tasks[].status.status' | sort | uniq -c | sort -rn
# Find unassigned tasks ./scripts/clickup-query.sh tasks | \ jq '.tasks[] | select(.assignees | length == 0)' ```
### 优先级分析
```bash # Count by priority ./scripts/clickup-query.sh tasks | \ jq -r '.tasks[] | .priority.priority // "none"' | sort | uniq -c | sort -rn ```
## 提示
- **优先使用辅助脚本：** 使用 `scripts/clickup-query.sh` 进行常见操作 - **自定义操作使用直接 API：** 当你需要特定的筛选或更新时使用 curl - **始终阅读 api-guide.md：** 包含完整的端点参考和故障排除指南 - **检查 TOOLS.md：** 获取特定于工作区的 ID 和配置 - **使用小查询进行测试：** 当不确定时，先使用 `| head -n 5` 进行测试 - **按用户 ID 筛选：** 使用 `assignees[]={user_id}` 参数，而不是 jq 用户名匹配
## 故障排除
- **缺少任务？** → 添加 `subtasks=true` - **仅返回了 100 个任务？** → 实现分页循环 - **401 未授权？** → 检查 `CLICKUP_API_KEY` 是否设置正确 - **速率限制错误？** → 等待 1 分钟（每分钟 100 次请求限制） - **负责人数组为空？** → 任务未分配（这不是错误） - **负责人筛选返回的任务少于预期？** → 在 `assignees[]` 参数中使用用户 ID，而不是 jq 文本匹配