ClickUp 技能

与 ClickUp 的 REST API 进行交互，实现任务管理、报告和工作流自动化。

配置

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

- API 令牌： CLICKUPAPIKEY
团队/工作区 ID： CLICKUPTEAMID
空间 ID（可选，用于过滤）
列表 ID（可选，用于创建任务）

快速开始

使用辅助脚本

查询 ClickUp 的最快方式：

bash

设置环境变量

export CLICKUPAPIKEY=pk_...
export CLICKUPTEAMID=90161392624

获取所有未完成任务

./scripts/clickup-query.sh tasks

获取任务计数（父任务与子任务）

./scripts/clickup-query.sh task-count

获取负责人分布

./scripts/clickup-query.sh assignees

获取特定任务

./scripts/clickup-query.sh task

直接 API 调用

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

bash

获取所有未完成任务（包含子任务和分页）

curl https://api.clickup.com/api/v2/team/{teamid}/task?includeclosed=false&subtasks=true \
-H Authorization: {api_key}

关键规则

1. 始终包含子任务

永远不要在未设置 subtasks=true 的情况下查询任务：

bash

✅ 正确

?subtasks=true

❌ 错误

（无 subtasks 参数）

原因： 缺少此参数，您可能会遗漏 70% 以上的实际任务。父任务只是容器，真正的工作在子任务中完成。

2. 处理分页

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

bash
page=0
while true; do
result=$(curl -s ...&page=$page -H Authorization: $CLICKUPAPIKEY)

# 处理任务
echo $result | jq .tasks[]

# 检查是否完成
islast=$(echo $result | jq -r .lastpage)
[ $is_last = true ] && break

((page++))
done

原因： 包含 300+ 任务的工作区需要 3-4 页。遗漏页面 = 数据不完整。

3. 区分父任务与子任务

bash

父任务的 parent 为 null

jq .tasks[] | select(.parent == null)

子任务的 parent 不为 null

jq .tasks[] | select(.parent != null)

常见操作

获取任务计数

bash

使用辅助脚本（推荐）

./scripts/clickup-query.sh task-count

直接 API 配合 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

使用辅助脚本（推荐）

./scripts/clickup-query.sh assignees

直接 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 未分配 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: 任务名称,
description: 此处填写描述,
assignees: [user_id],
status: 待办,
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: 更新后的名称,
status: 进行中,
priority: 2
}

获取特定任务

bash

使用辅助脚本

./scripts/clickup-query.sh task {task_id}

直接 API

curl https://api.clickup.com/api/v2/task/{task_id} \ -H Authorization: {api_key}

高级查询

按空间过滤

bash
curl https://api.clickup.com/api/v2/team/{teamid}/task?spaceids[]={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/{teamid}/task?includeclosed=true&subtasks=true \
-H Authorization: {api_key}

参考文档

有关详细的 API 文档、查询模式和故障排除：

阅读： references/api-guide.md

涵盖内容：

- 完整 API 端点参考
响应结构详情
常见陷阱及解决方案
速率限制和最佳实践
任务对象模式

工作流模式

每日站会报告

bash

按负责人获取所有未完成任务

./scripts/clickup-query.sh assignees

获取特定团队成员的任务（使用用户 ID，而非用户名！）

curl https://api.clickup.com/api/v2/team/{teamid}/task?subtasks=true&assignees[]={userid} \ -H Authorization: {api_key}

任务审计

bash

按状态统计任务

./scripts/clickup-query.sh tasks | \
jq -r .tasks[].status.status | sort | uniq -c | sort -rn

查找未分配任务

./scripts/clickup-query.sh tasks | \ jq .tasks[] | select(.assignees | length == 0)

优先级分析

bash

按优先级统计

提示

- 优先使用辅助脚本： 常见操作使用 scripts/clickup-query.sh
自定义操作使用直接 API： 需要特定过滤或更新时使用 curl
始终阅读 api-guide.md： 包含完整端点参考和故障排除
检查 TOOLS.md： 获取工作区特定的 ID 和配置
先用小查询测试： 不确定时，先用 | head -n 5 测试
按用户 ID 过滤： 使用 assignees[]={user_id} 参数，而非 jq 用户名匹配

故障排除

- 缺少任务？ → 添加 subtasks=true
只返回 100 个任务？ → 实现分页循环
401 未授权？ → 检查 CLICKUPAPIKEY 是否正确设置
速率限制错误？ → 等待 1 分钟（每分钟 100 次请求限制）
负责人数组为空？ → 任务未分配（非错误）
负责人过滤返回的任务少于预期？ → 在 assignees[] 参数中使用用户 ID，而非 jq 文本匹配

clickupClickUp交互

clickup

ClickUp Skill

Configuration

Quick Start

Using the Helper Script

Direct API Calls

Critical Rules

1. ALWAYS Include Subtasks

2. Handle Pagination

3. Distinguish Parent Tasks vs Subtasks

Common Operations

Get Task Counts

Get Assignee Breakdown

Create a Task

Update a Task

Get Specific Task

Advanced Queries

Filter by Space

Filter by List

Include Closed Tasks

Reference Documentation

Workflow Patterns

Daily Standup Report

Task Audit

Priority Analysis

Tips

Troubleshooting

ClickUp 技能

配置

快速开始

使用辅助脚本

设置环境变量

获取所有未完成任务

获取任务计数（父任务与子任务）

获取负责人分布

获取特定任务

直接 API 调用

获取所有未完成任务（包含子任务和分页）

关键规则

1. 始终包含子任务

✅ 正确

❌ 错误

2. 处理分页

3. 区分父任务与子任务

父任务的 parent 为 null

子任务的 parent 不为 null

常见操作

获取任务计数

使用辅助脚本（推荐）

直接 API 配合 jq

获取负责人分布

使用辅助脚本（推荐）

直接 API

创建任务

更新任务

获取特定任务

使用辅助脚本

直接 API

高级查询

按空间过滤

按列表过滤

包含已关闭任务

参考文档

工作流模式

每日站会报告

按负责人获取所有未完成任务

获取特定团队成员的任务（使用用户 ID，而非用户名！）

任务审计

按状态统计任务

查找未分配任务

优先级分析

按优先级统计

提示

故障排除

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装