核心用法
ClickUp Skill 是一个基于 REST API 的项目管理自动化工具，主要用于与 ClickUp 平台进行深度集成。核心功能包括：
任务管理：查询任务列表（支持分页、子任务嵌套）、获取特定任务详情、创建新任务、更新任务状态/优先级/负责人
数据报告：生成任务统计（父任务 vs 子任务）、负责人工作负载分析、状态分布统计、优先级分析
工作流自动化：支持每日站会报告生成、任务审计、未分配任务识别等常见场景
使用方式分为两类：推荐通过 ./scripts/clickup-query.sh 辅助脚本快速执行常见操作（tasks/task-count/assignees/task）；需要自定义过滤条件或更新操作时，可直接使用 curl 调用 ClickUp API。
关键配置：需提前设置 CLICKUP_API_KEY（API 令牌）和 CLICKUP_TEAM_ID（团队ID）环境变量，可选配置 Space ID 和 List ID 用于范围过滤。
显著优点
1. 官方 API 直连：仅访问 ClickUp 官方域名 api.clickup.com，HTTPS 加密传输，数据源可信
2. 子任务完整性：强制要求 subtasks=true 参数，避免遗漏 70%+ 的实际工作任务（子任务才是真正执行单元）
3. 分页自动化：内置完整的分页处理逻辑，自动遍历所有页面直至 last_page: true，确保大数据集完整性
4. 代码质量优秀：采用 set -euo pipefail 严格模式，含完善的错误处理、参数校验和使用文档
5. 零依赖设计：仅依赖 curl 和 jq 系统标准工具，无第三方包引入风险
6. 灵活查询模式：同时提供封装脚本（快速场景）和原生 API 调用（高级定制）两种模式
潜在缺点与局限性
1. 网络依赖性强：完全依赖 ClickUp 官方服务可用性，离线场景无法使用
2. API 速率限制：ClickUp 限制 100 请求/分钟，大规模数据操作需控制频率
3. 环境变量配置门槛：需用户自行获取并配置 API Key 和 Team ID，对非技术用户有学习成本
4. 功能边界明确：专注任务 CRUD 和查询统计，不包含 ClickUp 全部功能（如文档、聊天、白板等）
5. 返回数据量限制：单页最大 100 条，超大规模工作区（数千任务）分页耗时较长
适合人群
- 项目经理/团队负责人：需要批量生成任务报告、监控团队工作负载、识别瓶颈
- 研发团队：集成到 CI/CD 流程，自动创建/更新与代码提交关联的任务
- 数据分析师：提取原始任务数据进行二次分析（配合 jq 灵活处理 JSON）
- 自动化运维：构建每日站会、周报应等自动化工作流
- ClickUp 重度用户：需要突破 Web 界面限制，进行批量操作或复杂查询
常规风险
| 风险类型 | 等级 | 说明 |
|---------|------|------|
| 凭证泄露 | 中 | API Key 存储于环境变量，若终端/脚本权限配置不当可能被其他用户读取 |
| 数据泄露 | 低 | 通过 HTTPS 传输，但任务数据（含标题、描述）会经过 ClickUp 服务器 |
| 误操作风险 | 中 | 批量更新任务状态、负责人等操作不可逆，建议先测试小范围数据 |
| 服务可用性 | 低 | ClickUp API 变更可能导致 Skill 功能失效，需关注官方 API 公告 |
| 速率限制 | 低 | 频繁调用可能触发 429 错误，脚本已建议实现重试/等待机制 |
特别注意事项：
- API Key 建议设置最小权限范围（如仅读权限用于报告场景）
- 生产环境使用前务必在测试工作区验证
- 涉及任务删除/关闭的操作建议二次确认机制