clickup

核心用法

ClickUp Skill 是一个面向代理机构的企业级项目管理集成工具，通过封装 ClickUp API 提供完整的项目生命周期管理能力。核心操作围绕工作区层级展开：Team（工作区）→ Space → Folder → List → Task。用户需先通过 get_teams 获取工作区 ID，再逐级定位到目标列表创建或管理任务。技能支持完整的 CRUD 操作，涵盖任务、文档、时间记录、依赖关系等全维度项目管理需求。

高级功能包括：自动包含子任务的报告生成（解决 70% 工作量被忽略的问题）、多工作区无缝切换、客户文件夹结构化组织、销售管道跟踪、计时器与计费管理。报告模块提供任务统计、负责人负载分析、状态/优先级分布、每日站会报告等开箱即用的分析能力，且自动处理分页和速率限制。

显著优点

1. 子任务自动包含：所有报告和查询默认包含子任务，避免工作量统计严重偏低
2. 企业级多工作区支持：专为管理多个客户环境的代理机构设计，支持 Elevated、Atrium 等工作区切换
3. 完善的报告体系：任务计数、负载分布、状态分析、站会报告一键生成
4. 时间追踪原生集成：支持手动记录和计时器两种模式，满足计费场景
5. 依赖关系管理：完整的阻塞/等待依赖和任意任务链接能力
6. API v3 文档支持：支持 ClickUp 最新文档创建和管理功能

潜在缺点与局限性

1. ID 依赖繁琐：所有操作需要显式传递 workspace/space/folder/list/task ID，学习曲线陡峭
2. 页面创建受限：文档页面 API 仍处于 Beta 阶段，需配合 UI 使用
3. 速率限制约束：100 请求/分钟的限制对大规模批量操作构成瓶颈
4. 无实时同步：纯请求-响应模式，无 Webhook 或实时更新能力
5. 自定义字段复杂：需要预先获取字段定义 ID，配置门槛较高

适合的目标群体

• 数字代理机构：管理多客户、多项目的复杂工作区环境
• 项目经理：需要跨团队工作量分析和报告生成
• 运营团队：依赖结构化客户文件夹和标准化流程
• 自由职业者：需要时间追踪和计费支持的专业服务者

使用风险

• API Token 泄露风险：Token 存储于环境变量，团队共享环境需格外注意
• 误操作跨工作区：多工作区场景下可能因 team_id 错误修改错误环境
• 速率限制中断：批量操作可能触发 429 错误，需实现重试逻辑
• 数据一致性延迟：API 缓存可能导致刚创建的资源短暂不可见

核心用法

ClickUp Skill 是一款面向代理机构的企业级项目管理集成工具，通过 Python CLI 客户端与官方 ClickUp API 深度对接，实现跨工作区的统一任务管理。

主要功能模块：

1. 多工作区管理：自动识别并切换多个 ClickUp 工作区（如 Elevated、Atrium、Winch Life 等），支持独立的 Spaces、Folders、Lists 层级结构

2. 高级报表分析：

• 任务统计（总量/父任务/子任务/未分配）
• 人员工作负载分布
• 状态与优先级维度分析
• 每日站会报告（按状态分组）
• 关键特性：自动包含子任务（70%+ 工作量常被忽略），自动处理分页

3. 完整 CRUD 操作：Spaces、Folders、Lists、Tasks、Custom Fields 的全生命周期管理

4. 时间跟踪与计费：内置计时器、手动时间条目、计费支持，适用于按小时计费场景

5. 文档管理（API v3）：创建 Documents 与 Pages，支持任务-文档双向链接

6. 任务关系映射：Dependencies（阻塞/等待）、Linked Tasks（任意关联）

7. 销售管道与计费：潜在客户跟踪、项目生命周期管理、预付费与周期性计费

典型工作流：

• 获取工作区 → 定位 Space → 查找/创建 Folder/List → 创建任务 → 设置依赖 → 跟踪时间 → 生成报表

显著优点

| 维度 | 优势 |

|------|------|

| **企业级设计** | 专为管理多客户的代理机构设计，支持复杂的工作区层级 |

| **数据完整性** | 强制包含子任务，避免 70%+ 工作量统计遗漏 |

| **自动化** | 分页、子任务包含、报表生成均自动处理，减少人工干预 |

| **多工作区原生支持** | 无需切换上下文即可操作多个工作区 |

| **安全合规** | 仅通过环境变量读取 API Token，无硬编码密钥 |

| **API 覆盖全面** | 涵盖 ClickUp v2/v3 API，包括实验性的 Documents v3 |

潜在缺点与局限性

1. 依赖管理缺失：无 requirements.txt，需手动安装 requests
2. 许可证未声明：缺少开源许可证文件
3. 输入验证有限：CLI 参数缺乏严格的格式校验（如 ID 格式）
4. 无本地缓存：高频报表调用可能触发 API 速率限制（100 req/min）
5. Pages API 限制：文档页面创建需通过 ClickUp UI，API 尚处于 Beta
6. 时间单位要求：所有时长/时间戳需使用毫秒，易产生转换错误

适合人群

• 数字代理机构：管理多个客户、复杂项目层级的团队
• 项目经理：需要跨工作区统一视图与自动化报表
• 按小时计费的专业服务：律师、咨询顾问、开发团队
• ClickUp 高级用户：已使用多 Spaces、Custom Fields、Dependencies 等高级功能

常规风险

| 风险类型 | 说明 | 缓解措施 |

|----------|------|----------|

| **API 速率限制** | 100 请求/分钟，批量操作易触发 | 代码已内置分页延迟，避免高频循环 |

| **ID 混淆** | 多工作区场景下易误操作错误工作区 | 操作前显式确认 `team_id` |

| **数据权限** | API Token 权限等同于生成用户 | 使用最小权限的专用集成账户 |

| **毫秒时间戳** | 易与秒级时间戳混淆导致错误 | 严格遵循文档要求，使用毫秒 |

| **子任务嵌套** | 过度嵌套影响性能与可读性 | 建议不超过 3 层嵌套 |

安全评估结论

该 Skill 通过完整安全扫描（CLS-Certify v2.1.0），获得 S 级（91 分） 评级：

• 无危险函数（eval/exec/system）
• 无硬编码密钥
• 仅访问官方 api.clickup.com（TLS 1.2+）
• 符合 GDPR 数据最小化原则
• 依赖纯净（仅 Python 标准库 + requests）

信任等级：T2（可信组织/GitHub 组织账号）