Jira

通过自然语言与 Jira 交互。支持多种后端。

后端检测

请首先执行此检查，以确定应使用哪种后端：

1. 检查 jira CLI 是否可用：
   → 执行：which jira
   → 若找到：使用 CLI 后端

2. 若无 CLI，检查 Atlassian MCP 是否可用：
   → 查找 mcp__atlassian__* 工具
   → 若存在：使用 MCP 后端

3. 若两者均不可用：
   → 引导用户完成配置

快速参考（CLI）

若使用 MCP 后端，请跳过本节。

快速参考（MCP）

若使用 CLI 后端，请跳过本节。

完整 MCP 使用模式详见 references/mcp.md。

触发词

• “创建一个 jira ticket”
• “展示 PROJ-123”
• “列出我的 tickets”
• “将 ticket 移至 done 状态”
• “当前 sprint 中有哪些内容？”

问题编号（Issue Key）识别

问题编号遵循格式：[A-Z]+-[0-9]+（例如：PROJ-123、ABC-1）。

当用户在对话中提及问题编号时：

• CLI：调用 jira issue view KEY 或 jira open KEY
• MCP：使用该编号调用 mcp__atlassian__jira_get_issue

工作流

创建 ticket：

1. 若用户提到了代码、已有 ticket 或 PR，需先调研上下文
2. 草拟 ticket 内容
3. 与用户共同审阅内容
4. 使用合适的后端正式创建

更新 ticket：

1. 首先获取问题详情
2. 检查当前状态（尤其注意“进行中”类 ticket）
3. 对比并展示当前状态与拟变更内容
4. 获得用户明确批准后再执行更新
5. 添加评论说明本次变更原因

任何操作前必问

请自问以下问题：

1. 当前状态是什么？ — 务必先获取问题最新信息。切勿假设状态、负责人或字段值与用户认知一致。

2. 还有哪些人会受影响？ — 检查关注者（watchers）、关联问题（linked issues）、父级史诗（parent epics）。一次“简单编辑”可能触发多达 10 人的通知。

3. 该操作是否可逆？ — 状态转换可能存在单向限制；某些工作流要求必须经过中间状态。“To Do” → “Done” 可能因缺少“In Progress”步骤而静默失败。描述字段编辑无撤销机制。

4. 我是否使用了正确的标识符？ — 必须使用 Issue Key、Transition ID、Account ID 等精确标识。显示名称（Display Name）无法用于分配操作（MCP 场景下）。

严禁行为（NEVER）

• 严禁未获取当前状态即执行状态转换 — 工作流可能强制要求中间状态。“To Do” → “Done” 若跳过 “In Progress”，可能静默失败。

• 严禁在 MCP 中使用显示名称（Display Name）执行分配 — 仅 Account ID 有效。务必先调用 lookupJiraAccountId，否则分配将静默失败。

• 严禁未展示原始内容即编辑描述字段 — Jira 不提供撤销功能。用户必须清楚看到即将被替换的内容。

• 严禁在 CLI 中使用 --no-input 且未提供全部必需字段 — 此操作将静默失败并报出难以理解的错误。请先查阅对应项目的必填字段。

• 严禁假定状态转换名称具有通用性 — “Done”、“Closed”、“Complete” 等名称因项目而异。务必先获取当前项目支持的状态转换列表。

• 严禁未经显式授权执行批量修改 — 每次 ticket 修改均会通知其关注者；10 次修改 = 10 轮通知风暴。

安全性原则

• 运行任意命令 / 工具调用前，必须先向用户展示完整调用内容
• 修改 ticket 前，必须获得用户明确批准
• 编辑时须保留原始信息（如非覆盖式更新）
• 应用更新后，须验证结果是否符合预期
• 认证失败等异常必须清晰暴露给用户，以便其及时修复

无可用后端

若 CLI 与 MCP 均不可用，请引导用户完成配置：

要使用 Jira，您需配置以下任一方式：

1. **jira CLI**（推荐）：
   https://github.com/ankitpokhrel/jira-cli

   安装：brew install ankitpokhrel/jira-cli/jira-cli
   初始化：jira init

2. **Atlassian MCP**：
   在您的 MCP 设置中，使用 Atlassian 凭据完成配置。

深入指南（Deep Dive）

应在以下情形加载参考文档：

• 创建含复杂字段或跨行内容的问题
• 构建超越基础过滤器的 JQL 查询
• 排查错误或认证相关问题
• 处理状态转换、问题关联或迭代（Sprint）管理

无需加载参考文档的情形：

• 简单的查看 / 列表操作（上方“快速参考”已足够）
• 基础状态检查（如 jira issue view KEY）
• 在浏览器中打开问题

参考文档：

• CLI 使用模式：references/commands.md
• MCP 使用模式：references/mcp.md