ClickUp 技能

与 ClickUp 的 REST API 交互，用于任务管理、报告和工作流自动化。

配置

使用此技能前，请确保已在TOOLS.md文件中配置好以下内容：

• API 令牌： CLICKUP_API_KEY
• 团队/工作区 ID： CLICKUP_TEAM_ID
• 空间 ID（可选，用于筛选）
• 列表 ID（可选，用于创建任务）

快速开始

使用辅助脚本

查询 ClickUp 的最快方式：

# 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 调用

对于辅助脚本未涵盖的自定义查询或操作：

# 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. 务必包含子任务

切勿在查询任务时子任务 = 真:

# ✅ CORRECT
?subtasks=true

# ❌ WRONG
(no subtasks parameter)

原因：如果没有此参数，您可能会遗漏超过70%的实际任务。父任务只是容器；真正的工作发生在子任务中。

2. 处理分页

ClickUp API 每页最多返回100个任务。始终循环直到last_page: true:

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. 区分父任务与子任务

# Parent tasks have parent=null
jq '.tasks[] | select(.parent == null)'

# Subtasks have parent != null
jq '.tasks[] | select(.parent != null)'

常见操作

获取任务数量

# 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)
}'

获取负责人细分

# 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

创建任务

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
  }'

更新任务

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
  }'

获取特定任务

# 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}"

高级查询

按空间筛选

curl "https://api.clickup.com/api/v2/team/{team_id}/task?space_ids[]={space_id}&subtasks=true" \
  -H "Authorization: {api_key}"

按列表筛选

curl "https://api.clickup.com/api/v2/list/{list_id}/task?subtasks=true" \
  -H "Authorization: {api_key}"

包含已关闭任务

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 端点参考
• 响应结构详情
• 常见问题及解决方案
• 速率限制与最佳实践
• 任务对象模式

工作流模式

每日站会报告

# 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}"

任务审计

# 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)'

优先级分析

# 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 次请求）分配者数组为空？
• Assignee过滤器返回的任务数量少于预期？→ 在assignees[]参数中使用用户ID，而非jq文本匹配