名称： clickup
描述： "企业级 ClickUp 项目管理集成，具备高级报告、多工作区支持和客户/项目跟踪功能。核心能力包括：(1) 支持自动切换的多工作区任务管理；(2) 自动包含子任务和分页的高级分析与报告（任务计数、负责人细分、状态/优先级分析、每日站会报告）；(3) 客户文件夹组织与项目跟踪；(4) 对空间、文件夹、列表、任务和自定义字段的完整增删改查操作；(5) 支持计费的时间跟踪与计时器管理；(6) 文档创建与页面管理（API v3）；(7) 任务依赖、链接与关系映射；(8) 销售管道跟踪与潜在客户/项目状态；(9) 常客与周期性账单管理。专为在复杂工作区层级中管理多个客户的机构打造。"
env:
- name: CLICKUP_API_TOKEN
description: "ClickUp 个人 API 令牌。生成位置：ClickUp 设置 → 应用 → 生成 API 令牌"
required: true
dependencies:
- python3
- pip:requests

ClickUp 技能

面向机构工作流的企业级 ClickUp 集成。 通过高级报告、自动子任务处理和复杂的文件夹组织，管理多个客户、项目和工作区。

核心优势

快速开始

设置

设置您的 ClickUp API 令牌：

export CLICKUP_API_TOKEN="pk_your_token_here"

从以下位置获取令牌：ClickUp 设置 → 应用 → 生成 API 令牌

基本操作

列出所有工作区：

python scripts/clickup_client.py get_teams

创建任务：

python scripts/clickup_client.py create_task list_id="123" name="新任务" status="待办"

更新任务：

python scripts/clickup_client.py update_task task_id="abc" status="进行中"

工作区层级结构

团队 (工作区)
├── 空间
│   ├── 文件夹
│   │   └── 列表 → 任务
│   └── 列表 (无文件夹) → 任务
└── 文档

所有操作都需要通过 ID 明确指定工作区。

多工作区支持

此技能支持跨多个 ClickUp 工作区进行操作：

1. 使用 get_teams 列出可用工作区
2. 在操作中通过 team_id 引用工作区
3. 每个工作区维护独立的空间、文件夹和列表
4. 自定义任务 ID 需要同时设置 custom_task_ids=true 和 team_id

常用工作流

工作流：在特定工作区创建任务

1. 获取工作区 ID：get_teams
2. 获取目标空间：get_spaces team_id="xxx"
3. 获取或创建列表：get_folders space_id="yyy" → get_lists folder_id="zzz"
4. 创建任务：create_task list_id="aaa" name="任务" ...

工作流：配置空间状态

1. 获取空间：get_space space_id="xxx"
2. 更新空间状态：update_space space_id="xxx" statuses=[...]

状态配置格式请参阅 API 参考。

工作流：跟踪任务时间

选项 A - 手动录入：

python scripts/clickup_client.py create_time_entry \
  team_id="xxx" \
  task_id="yyy" \
  duration=3600000 \
  description="处理功能"

选项 B - 计时器：

# 启动计时器
python scripts/clickup_client.py start_timer team_id="xxx" task_id="yyy"

# 停止计时器 (停止用户当前运行的计时器)
python scripts/clickup_client.py stop_timer team_id="xxx"

工作流：创建文档结构

1. 创建文档：create_doc workspace_id="xxx" name="项目文档"
2. 添加页面：使用 ClickUp UI (页面 API 处于测试阶段)

注意：文档使用 ClickUp API v3 (使用 workspace_id 而非 team_id)。

工作流：报告与分析

获取任务计数（包含父任务/子任务细分）：

python scripts/clickup_client.py task_counts team_id="xxx"
# 返回：{"total": 50, "parents": 20, "subtasks": 30, "unassigned": 5}

按负责人获取工作量：

python scripts/clickup_client.py assignee_breakdown team_id="xxx"
# 返回：{"张三": 15, "李四": 12, "未分配": 8}

按状态获取任务：

python scripts/clickup_client.py status_breakdown team_id="xxx"
# 返回：{"待办": 20, "进行中": 10, "完成": 15}

按优先级获取任务：

python scripts/clickup_client.py priority_breakdown team_id="xxx"
# 返回：{"紧急": 2, "高": 5, "普通": 15, "低": 8, "无": 20}

每日站会报告（按状态分组）：

# 所有团队成员
python scripts/clickup_client.py standup_report team_id="xxx"

# 特定人员 (使用用户 ID)
python scripts/clickup_client.py standup_report team_id="xxx" assignee_id="12345"

获取所有任务（自动分页）：

python scripts/clickup_client.py get_all_tasks team_id="xxx"
# 始终自动包含子任务 (至关重要！)

按空间或负责人筛选报告：

# 特定空间
python scripts/clickup_client.py task_counts team_id="xxx" space_ids='["90172290075"]'

# 特定负责人
python scripts/clickup_client.py get_all_tasks team_id="xxx" assignees='["12345"]'

# 包含已关闭任务
python scripts/clickup_client.py task_counts team_id="xxx" include_closed="true"

报告关键规则：
1. 始终包含子任务 — 我们的方法通过 subtasks=true 自动实现
2. 自动处理分页 — get_all_tasks 会循环直到获取所有页面
3. 父任务与子任务 — 父任务 parent: null，子任务 parent: "task_id"
4. 速率限制 — 100 次请求/分钟；我们的分页机制会遵守此限制

工作流：将文档链接到任务

选项 A - 作为附件添加：

python scripts/clickup_client.py link_doc_to_task \
  task_id="xxx" \
  doc_id="yyy"

选项 B - 在描述中提及：

python scripts/clickup_client.py mention_doc_in_task \
  task_id="xxx" \
  doc_id="yyy"

两者都会在任务中创建指向文档的可点击链接。

工作流：任务依赖关系

设置阻塞关系：

# 任务 B 被任务 A 阻塞/等待任务 A
python scripts/clickup_client.py add_dependency \
  task_id="TASK_B_ID" \
  depends_on="TASK_A_ID"

# 检查依赖关系
python scripts/clickup_client.py get_dependencies \
  task_id="TASK_B_ID"

# 移除依赖关系
python scripts/clickup_client.py remove_dependency \
  task_id="TASK_B_ID" \
  depends_on="TASK_A_ID"

设置反向依赖（任务正在阻塞另一个）：

# 任务 A 正在阻塞任务 B
python scripts/clickup_client.py add_dependency \
  task_id="TASK_A_ID" \
  waiting_on="TASK_B_ID"

工作流：链接相关任务（非依赖）

对于不相互阻塞的相关任务：

# 将任务 A 链接到任务 B (任意关系)
python scripts/clickup_client.py link_tasks \
  task_id="TASK_A_ID" \
  links_to="TASK_B_ID"

# 移除链接
python scripts/clickup_client.py unlink_tasks \
  task_id="TASK_A_ID" \
  links_to="TASK_B_ID"

注意：link_tasks 创建“链接任务”关系（显示在任务的“链接任务”部分），而 add_dependency 创建阻塞/等待关系。

工作流：批量任务操作

对于批量操作，请循环处理任务：

# 获取任务
TASKS=$(python scripts/clickup_client.py get_tasks list_id="xxx")

# 处理每个任务 (解析 JSON 并循环)

脚本参考

scripts/clickup_client.py

ClickUp 操作的主要 CLI 接口。

用法：

python scripts/clickup_client.py <命令> [键=值 ...]

命令：

工作区操作

• get_teams - 列出所有可访问的工作区

空间操作

• get_spaces team_id="xxx" - 列出空间
• create_space team_id="xxx" name="名称" [选项...] - 创建空间
• update_space space_id="xxx" [选项...] - 更新空间

文件夹操作

• get_folders space_id="xxx" - 列出文件夹
• create_folder space_id="xxx" name="名称" - 创建文件夹

列表操作

• get_lists folder_id="xxx" - 文件夹中的列表
• get_space_lists space_id="xxx" - 无文件夹的列表
• create_list folder_id="xxx" name="名称" [选项...] - 在文件夹中创建
• create_space_list space_id="xxx" name="名称" [选项...] - 创建无文件夹列表

任务操作

• get_task task_id="xxx" - 获取任务详情（包含依赖关系、链接任务）
• get_tasks list_id="xxx" [筛选条件...] - 列出任务
• create_task list_id="xxx" name="名称" [选项...] - 创建任务
• update_task task_id="xxx" [选项...] - 更新任务

时间跟踪

• get_time_entries team_id="xxx" [筛选条件...] - 列出时间条目
• create_time_entry team_id="xxx" task_id="yyy" duration=3600000 [...] - 创建时间条目
• start_timer team_id="xxx" task_id="yyy" - 启动计时器
• stop_timer team_id="xxx" - 停止计时器

文档 (API v3)

• get_docs workspace_id="xxx" - 列出文档
• create_doc workspace_id="xxx" name="名称" [选项...] - 创建文档
• get_doc doc_id="xxx" - 获取文档详情

关于页面的说明： 文档页面 API 处于测试阶段。页面可能需要通过 ClickUp UI 创建。

文档-任务链接

• link_doc_to_task task_id="xxx" doc_id="yyy" - 将文档 URL 附加到任务
• mention_doc_in_task task_id="xxx" doc_id="yyy" - 将文档链接添加到任务描述

任务依赖关系 (阻塞/等待)

• add_dependency task_id="xxx" depends_on="yyy" - 任务被另一个任务阻塞/等待另一个任务
• add_dependency task_id="xxx" waiting_on="yyy" - 另一个任务被此任务阻塞/等待此任务
• remove_dependency task_id="xxx" depends_on="yyy" - 移除依赖关系
• get_dependencies task_id="xxx" - 列出任务的所有依赖关系

任务链接 (任意关系)

• link_tasks task_id="xxx" links_to="yyy" - 在任务间创建任意链接
• unlink_tasks task_id="xxx" links_to="yyy" - 移除任务链接

报告与分析

• get_all_tasks team_id="xxx" [include_closed="true"] [space_ids='["id1"]'] [assignees='["uid1"]'] - 所有任务，自动分页 (始终包含子任务)
• task_counts team_id="xxx" [筛选条件...] - 计数细分：总计、父任务、子任务、未分配
• assignee_breakdown team_id="xxx" [筛选条件...] - 按负责人分配的工作量分布
• status_breakdown team_id="xxx" [筛选条件...] - 按状态分组的任务
• priority_breakdown team_id="xxx" [筛选条件...] - 按优先级分组的任务
• standup_report team_id="xxx" [assignee_id="yyy"] - 按状态分组的每日站会报告

文档

• get_docs team_id="xxx" - 列出文档
• create_doc team_id="xxx" name="名称" [选项...] - 创建文档

高级配置

自定义字段

要使用自定义字段：

1. 获取字段定义：GET /list/{list_id}/field (参见 API 参考)
2. 在创建/更新任务时设置值：
   bash python scripts/clickup_client.py update_task \ task_id="xxx" \ 'custom_fields=[{"id":"field_id","value":"value"}]'

状态配置

在创建/更新空间或列表时：

python scripts/clickup_client.py update_space \
  space_id="xxx" \
  'statuses=[{"status":"待办","type":"open"},{"status":"完成","type":"closed"}]'

优先级级别

• 1 - 紧急
• 2 - 高
• 3 - 普通
• 4 - 低

错误处理

常见错误及解决方案：

Python 客户端使用

对于复杂操作，可直接导入客户端：

from scripts.clickup_client import ClickUpClient

client = ClickUpClient()

# 获取所有工作区
teams = client.get_teams()

# 创建任务，完全控制
task = client.create_task(
    list_id="123",
    name="复杂任务",
    description="详细描述",
    assignees=[123, 456],
    tags=["紧急", "客户"],
    priority=2,
    due_date=1704067200000,
    time_estimate=14400000
)

参考

• API 详情：完整端点文档、请求/响应格式和字段类型，请参阅 references/api_reference.md。
• ClickUp API 文档：https://clickup.com/api

最佳实践

1. 存储 ID：工作区/空间/文件夹/列表 ID 很少更改。将其存储在 TOOLS.md 中以供快速参考。
2. 自定义任务 ID：如果使用自定义 ID，在任务操作中始终包含 custom_task_ids=true 和 team_id。
3. 速率限制：间隔进行批量操作，避免 429 错误。
4. 时间跟踪：所有持续时间/时间戳值使用毫秒。
5. 多工作区：跨工作区操作时，始终仔细检查 team_id，避免修改错误的工作区。