核心用法
zentao-api技能提供对禅道项目管理系统的完整API封装，基于RESTful API v2.0协议，覆盖项目集、产品、项目、执行、需求（Story/Epic/Requirement）、Bug、任务、测试用例等20个核心模块。使用时需配置ZENTAO_URL服务器地址，通过scripts/get-token.sh自动获取认证token并缓存至~/.zentao-token.json。
关键操作流程：
1. 执行eval "$(bash scripts/get-token.sh)"获取凭证
2. 根据用户意图匹配API端点（内置意图识别规则表）
3. PUT更新需先GET全量数据，再覆盖指定字段提交
4. 写操作前向用户确认（用户明确要求免确认除外）
显著优点
- 全模块覆盖：从战略层项目集到执行层任务/Bug，支持研发全流程管理
- 状态机封装：内置需求（change/close/activate）、Bug（resolve/close/activate）、任务（start/finish/close）等标准状态流转API
- 智能缓存机制：token自动持久化，避免重复登录
- 意图识别完备：20+关键词映射规则，降低使用门槛
潜在局限
- 强依赖禅道实例：需自建或购买禅道服务，无法独立运行
- PUT接口全量字段要求：更新操作需先查询再合并，增加API调用次数
- Token失效处理：401错误需手动清除缓存文件后重试
- 无批量操作接口：大量数据场景下需循环调用，效率受限
适合人群
- 研发团队Leader/PM：自动化项目进度追踪、报表生成
- DevOps工程师：集成CI/CD流水线，自动创建Build/Release记录
- 测试团队：批量导入测试用例、自动同步Bug状态
- 需要二次开发的企业：基于禅道数据构建内部管理系统
常规风险
| 风险类型 | 说明 | 缓释措施 |
|---------|------|---------|
| 凭证泄露 | Token存储于本地JSON文件，可能被其他进程读取 | 设置文件权限600，生产环境改用`ZENTAO_TOKEN`环境变量 |
| 误操作数据 | 写操作影响真实项目数据 | 强制确认机制，建议先在测试环境验证 |
| API限流 | 高频调用可能触发服务端限流 | 增加调用间隔，使用批量接口（如有） |
| 版本兼容性 | 依赖禅道v2.0 API，旧版本可能不兼容 | 确认禅道版本≥12.0，参考官方文档降级至1.0 API |
| 数据一致性 | 并发PUT操作可能覆盖他人修改 | 关键操作前加乐观锁校验或业务层协调 |