clickup

clickup

用途

此技能允许 AI 与 ClickUp 的 API 交互，以管理项目任务、空间、列表、文档、目标、仪表板、自动化、时间跟踪和集成。通过以编程方式获取或更新 ClickUp 数据来自动化工作流。

适用场景

在代码中处理生产力任务时使用此技能，例如与其他应用同步任务、根据 ClickUp 数据生成报告、根据事件自动创建任务，或与 CI/CD 管道集成。在项目管理自动化脚本中使用，或在需要实时更新的场景中使用，例如聊天机器人或监控工具。

主要功能

• 通过 API 端点管理任务，例如使用 POST /api/v2/list/{list_id}/task 创建任务。
• 使用 GET /api/v2/team/{team_id}/space 获取空间，以处理空间和列表。
• 使用 GET /api/v2/folder/{folder_id}/doc 访问文档和目标。
• 使用 POST /api/v2/task/{task_id}/time_entry 等端点跟踪时间。
• 通过 ClickUp 的自动化规则自动化工作流，并使用 GET /api/v2/space/{space_id}/automation 查询规则。
• 使用 GET /api/v2/team/{team_id}/dashboard 访问仪表板。
• 所有操作都需要在 Authorization 标头中通过 Bearer 令牌进行身份验证。
• 支持对大型数据集进行分页，例如使用 ?page=1&limit=50 等查询参数。

使用模式

始终使用存储在环境变量中的 API 令牌对请求进行身份验证，例如 $CLICKUP_API_TOKEN。使用 Python 中的 requests 等 HTTP 库发起调用。例如，使用基础 URL https://api.clickup.com/api/v2 构造请求，并处理 JSON 负载。模式：首先，使用 GET /api/v2/team 获取团队 ID，然后用它访问嵌套资源。如果遇到速率限制，请实现指数退避。对于 CLI 集成，可将输出传递给 jq 等工具来解析 JSON 响应。

常用命令/API

• 创建任务：使用 POST /api/v2/list/{list_id}/task，并提供 JSON 请求体 {"name": "New Task", "description": "Details"}。Python 示例：

  import requests; token = os.environ['CLICKUP_API_TOKEN']
  response = requests.post('https://api.clickup.com/api/v2/list/123/task', headers={'Authorization': token}, json={'name': 'Task'})
  

• 获取列表中的任务：GET /api/v2/list/{list_id}/task?subtasks=true。CLI 示例：curl -H "Authorization: $CLICKUP_API_TOKEN" https://api.clickup.com/api/v2/list/456/task。
• 更新任务：使用 PUT /api/v2/task/{task_id}，请求体为 {"status": "in progress"}。代码片段：

  requests.put('https://api.clickup.com/api/v2/task/789', headers={'Authorization': token}, json={'status': 'complete'})
  

• 获取空间：GET /api/v2/team/{team_id}/space。配置格式：将团队 ID 存储在 .env 文件中，格式为 CLICKUP_TEAM_ID=123。
• 时间跟踪：使用 POST /api/v2/task/{task_id}/time_entry，并提供 {"start": "2023-01-01T00:00:00Z"}。

集成说明

在 ClickUp 账户设置中导出 $CLICKUP_API_TOKEN，以设置身份验证。进行集成时，可使用 ClickUp 的 Webhook（例如通过 POST /api/v2/webhook 订阅），并在应用中处理传入的负载。与其他服务集成时，将 ClickUp ID（例如任务 ID）映射到外部键。配置格式：使用 JSON 配置文件，例如 {"api_base": "https://api.clickup.com/api/v2", "team_id": "123"}。避免将令牌硬编码；始终使用环境变量。如有需要，可将用户重定向到 ClickUp 的授权流程进行 OAuth；但访问 API 时，请使用基于令牌的身份验证。

错误处理

检查 HTTP 状态码：401 表示未授权（使用新令牌重试），429 表示速率受限（等待并退避重试），404 表示未找到（记录日志并跳过）。解析 JSON 错误，例如，如果 response.json()['err'] == 'Access denied'，则抛出自定义异常。在代码中使用 try-except 块包装请求：

try: response = requests.get(url, headers={'Authorization': token})
except requests.exceptions.RequestException as e: print(f"Error: {e}, Status: {response.status_code}")

通过检查响应中是否包含 'next_page' 来处理分页错误。验证输入，例如确保 list_id 在调用 API 前为整数。

具体使用示例

1. 自动创建任务：用户通过聊天请求创建新任务时，使用此技能在 ClickUp 中创建任务。例如，在脚本中解析用户输入，然后调用 POST /api/v2/list/123/task 并附上任务详情。代码：

   task_data = {'name': 'User-reported issue', 'description': user_input}
   requests.post('https://api.clickup.com/api/v2/list/123/task', headers={'Authorization': $CLICKUP_API_TOKEN}, json=task_data)
   

   这可与消息应用集成，实现实时任务管理。

2. 获取任务并生成报告：要生成每日摘要，请查询某个空间中的任务并按状态筛选。例如，使用 GET /api/v2/space/456/task?status=active，然后处理响应以统计未完成任务的数量。代码：

   response = requests.get('https://api.clickup.com/api/v2/space/456/task', headers={'Authorization': $CLICKUP_API_TOKEN})
   tasks = response.json()['tasks']; open_tasks = [t for t in tasks if t['status']['status'] == 'active']
   print(f"Open tasks: {len(open_tasks)}")
   

   这适用于更新生产力工具中的仪表板或发送提醒。

图关系

• 关联到集群：社区（例如，链接到 GitHub 或 Trello 等其他社区工具技能）。
• 标记为：clickup（直接匹配）、tasks（关联到项目管理技能）、project（链接到 Jira 或 Asana 的同类工具）、productivity（关联到时间跟踪或自动化技能）。