禅道

解决什么问题

团队把需求、任务和 Bug 都放在禅道里，但 Agent 通常只能读写文件或调用通用 HTTP 接口。直接拼 RESTful 请求会遇到几个实际问题：认证 token 会过期，创建接口的参数名和列表接口不一致，PUT 请求会重置未传字段，Bug 状态流转和普通更新也不是同一个端点。结果是要么调用失败，要么把现有数据改坏。

这个技能的目标是把禅道 API 封装成一组可预期的脚本，让 Agent 用自然语言完成常见研发流程操作，同时避开这些已知坑。

核心能力

脚本覆盖产品、项目、需求、任务、执行、Bug 和测试用例：

• 查询与获取：列表、详情、按项目/执行筛选。
• 生命周期操作：创建、更新、启动、暂停、完成、关闭、激活、删除。
• 批量安全控制：--dry-run 预览写入，--yes 确认删除，列表分页由 --limit / --page 控制。
• 认证由 auth.js 管理：首次自动登录，本地缓存 token，遇到 401 自动刷新。

自然语言会先匹配意图，再组装脚本命令。例如「产品 1 的 Bug」「开始任务 12」「迭代 5 的需求」，Agent 应提取 ID 和筛选条件，映射到对应 --action。当用户说「敏捷项目」「短期迭代」「严重 Bug」时，技能会把关键词转成 model、lifetime、severity 等透传参数。

关键注意点

禅道 API v2 的 PUT 请求会把未包含字段重置为默认值。因此更新前必须先读取当前值，再合并本次修改；脚本内部按这个流程处理，不要绕过脚本直接请求。

创建操作应一次性携带所有已知参数，而不是先创建再逐项更新。这样既能减少 API 调用，也避免中间状态和字段被意外重置。

字段格式限制要留意：需求描述 --spec 和验收标准 --verify 使用 HTML；测试用例 --steps 使用纯文本 JSON，type 仅支持 step。

状态流转不要混用更新接口。Bug 的解决、关闭、激活要走专用动作，bug update --status 不会生效；需求关闭必须传 --reason，变更必须传 --reviewer；任务完成必须传 --consumed；执行必须关联项目。

删除默认只提示，必须加 --yes 才会执行。遇到 403 时，先检查参数名是否带 ID 后缀、用户角色是否存在，以及角色是否拥有对应模块权限。

凭证只放在环境变量 CHANDAO_URL、CHANDAO_ACCOUNT、CHANDAO_PASSWORD 中，不要在对话、文件、日志里输出。项目集、发布版本和系统管理尚未实现；史诗模块也未实现，相关指令没有对应脚本。