核心用法
zentao-api 是禅道（ZenTao）项目管理系统的官方 API 集成技能，面向 DevOps 和项目管理场景设计。用户通过环境变量配置服务器地址与认证令牌后，可调用 20 余个核心模块的 RESTful API，覆盖项目集、产品、项目、执行、需求（Story/Epic/Requirement）、Bug、任务、测试用例、测试单、版本、发布等完整项目管理链路。
该技能采用 Token 认证机制，首次登录后自动缓存凭证至 ~/.zentao-token.json，后续免重复配置。所有列表接口支持统一的分页与筛选参数（browseType/status、orderBy、recPerPage、pageID），写操作前需向用户确认内容，PUT 编辑建议先 GET 详情再覆盖提交。
显著优点
- 官方背书：由禅道母公司青岛易软天创（Sun Hao）维护，代码仓库托管于 GitHub，版本迭代规范
- 覆盖全面：20+ 模块的 CRUD 及状态流转操作，支持 Scrum/瀑布/看板等多种项目模式
- 认证友好：自动 Token 缓存机制，配合
scripts/get-token.sh脚本降低配置门槛 - 枚举完备：提供 Bug 类型、解决方案、需求关闭原因、任务类型等 15+ 组常用枚举值速查表
潜在局限
- 字段不一致：部分接口存在命名差异（如 POST builds 用
executionID，PUT builds 用execution；moudule拼写问题），需格外注意 - 层级敏感：创建 Epic/Requirement/Story 时若未显式传递
grade字段，某些实例会出现层级标签显示异常 - 依赖环境：需预装
curl和node以运行认证脚本，对纯容器环境不够友好 - 无独立列表接口：部分模块（如 Project）不支持全局列表，需通过关联查询获取
适合人群
- 使用禅道进行项目管理的研发团队 TL、产品经理、Scrum Master
- 需要将禅道数据接入内部 BI 或自动化工作流的平台工程师
- 追求国产替代、关注数据主权的中大型企业 IT 部门
常规风险
- Token 失效：401 响应时需手动清除缓存重新认证，未做自动刷新机制
- 写操作确认：虽然规范要求写操作前确认，但用户明确拒绝确认时直接执行，存在误操作风险
- 数据一致性：PUT 编辑若未先 GET 详情，可能导致字段覆盖丢失
- 版本兼容性：v2.0 与旧版 1.0 API 并存，部分端点行为可能存在差异