jira-transitions

用途

jira-transitions 技能用于在 Jira 中推动工单（issue）流转状态，获取可用转换并执行状态变更。适用场景包括：将工单移动到不同状态（To Do → In Progress → Done）、获取某个工单的可用转换、批量转换工单，以及在关闭工单时设置 resolution（解决结果）。

主要能力

• 获取指定工单当前可用的转换列表。
• 按转换名称或目标状态名称查找转换。
• 执行转换，可选择设置 resolution、添加评论或传入其它字段。
• 提供高层辅助函数 moveIssueTo 将工单移动到目标状态。
• 提供 bulkTransition 批量转换工单，并返回成功与失败列表。
• 提供 discoverWorkflow 工作流发现模式，打印当前状态下可用的转换。

使用方式

技能文档给出了 TypeScript 的实现模式：

1. 定义类型 Transition 与 TransitionsResponse。
2. 通过 client.request 请求 /issue/${issueKeyOrId}/transitions?expand=transitions.fields 获取可用转换。
3. 按转换名或目标状态名（不区分大小写）查找转换。
4. 构造请求体执行转换：设置 transition.id；若需要 resolution 或其它字段，则设置 fields；若有评论，则使用 update.comment 添加 ADF 格式文档内容。
5. 使用 moveIssueTo 作为高层封装；如果转换要求 resolution 且未提供，代码会默认使用 { name: 'Done' }。
6. 使用 bulkTransition 遍历工单列表逐个执行并收集结果。

文档中的 curl 示例展示了如何直接调用 Jira REST API（/rest/api/3/issue/.../transitions）获取转换、执行简单转换、带上 resolution 转换到 Done，以及带评论进行转换。成功转换返回 204 No Content，响应体为空。

适用场景

• 自动化推动 Jira 工单状态，例如在开发流程中自动把工单从待办推进到进行中或完成。
• 需要先探查工作流、再根据实际可用转换执行变更的场景。
• 批量更新多个工单状态的场景。
• 关闭工单时设置解决结果（Done、Won't Do、Duplicate、Cannot Reproduce 等）。

限制与注意事项

• 转换 ID 不是标准化的，会因 Jira 实例、项目和工作流配置而异，因此必须先查询可用转换再尝试转换。
• 使用前提是已认证的 JiraClient（参见 jira-auth 技能）、拥有工单转换权限，并了解工作流结构。
• 常见错误包括：使用未先行查询的转换 ID（400）、移动到 Done 时忘记 resolution（400）、无转换权限（403）、工单不存在（404）。文档提醒不要假设转换 ID 在各项目间一致，并注意 204 空响应体表示成功。

版本记录

资料记载：2025-12-10 创建。