核心用法
zentao-api 技能通过调用禅道（ZenTao）官方 RESTful API v2.0，实现项目管理数据的自动化操作。用户可通过自然语言指令完成以下核心操作：
| 功能类别 | 具体操作 |
|---------|---------|
| **查询类** | 获取项目列表、执行（迭代/Sprint）、需求、Bug、任务、测试用例、用户列表等 |
| **写入类** | 创建/编辑/删除需求、Bug、任务；更新状态（解决 Bug、关闭需求、完成任务等） |
认证机制：采用 Token 持久化缓存策略。首次配置 ZENTAO_URL + ZENTAO_ACCOUNT/ZENTAO_PASSWORD 或 ZENTAO_TOKEN 后，自动写入 ~/.zentao-token.json，后续调用免重复登录。脚本 get-token.sh 自动处理缓存刷新与失效重连。
典型工作流：
1. 执行 eval "$(bash scripts/get-token.sh)" 获取认证环境变量
2. 根据用户意图匹配 API 端点（内置意图识别规则表）
3. 写操作前自动调用 GET 详情接口补全字段（禅道 PUT 需全量字段）
4. 向用户确认后执行，返回格式化结果
显著优点
- 全功能覆盖：完整支持禅道 v2.0 API，涵盖项目管理六大核心模块（产品、项目、执行、需求、Bug、任务）
- 智能缓存：Token 永久有效，自动缓存机制避免频繁登录，支持多账号切换
- 安全确认：写操作强制确认机制，防止误操作；支持
--force跳过确认 - 字段补全：自动处理禅道 PUT 接口需全量字段的局限性，降低用户使用门槛
- 意图识别：内置关键词映射表，快速解析用户自然语言指令
潜在局限
- 版本依赖：仅支持禅道 API v2.0，旧版 v1.0 需降级参考备用文档
- 字段覆盖风险：PUT 操作自动补全机制可能覆盖用户未注意到的现有字段，建议关键操作前人工复核
- 网络依赖：Token 缓存文件
~/.zentao-token.json若损坏需手动清除，无自动修复机制 - 权限边界：受限于禅道账号权限，无法操作无权限的项目或数据
适合人群
- 研发团队：需要批量查询项目进展、Bug 统计、迭代燃尽图的开发者
- 项目经理：需要自动化生成周报、同步多系统项目状态的 PM
- 测试工程师：需要批量创建/更新测试用例、同步缺陷状态的 QA
- DevOps 工程师：需要将禅道集成到 CI/CD 流水线、自动化运维脚本的 SRE
常规风险
| 风险等级 | 场景 | 缓解措施 |
|---------|------|---------|
| **高** | Token 泄露导致未授权访问 | Token 存储于用户目录，建议设置文件权限 600；生产环境优先使用一次性 Token |
| **中** | 写操作误删/误改数据 | 强制确认机制；建议生产环境配合禅道操作日志审计 |
| **中** | API 限流或版本变更导致失效 | 关注禅道官方 API 更新；保留降级至 v1.0 的能力 |
| **低** | 网络超时导致状态不一致 | 建议关键操作后二次校验；实现幂等重试逻辑 |