介绍
# Jira
与 Jira 的自然语言交互。支持多种后端。
## 后端检测
**首先运行此检查** 以确定使用哪个后端：
``` 1. Check if jira CLI is available: → Run: which jira → If found: USE CLI BACKEND
2. If no CLI, check for Atlassian MCP: → Look for mcp__atlassian__* tools → If available: USE MCP BACKEND
3. If neither available: → GUIDE USER TO SETUP ```
| 后端 | 何时使用 | 参考 | |---------|-------------|-----------| | **CLI** | `jira` 命令可用 | `references/commands.md` | | **MCP** | Atlassian MCP 工具可用 | `references/mcp.md` | | **None** | 两者均不可用 | CLI 安装指南 |
---
## 快速参考 (CLI)
> 如果使用 MCP 后端，请跳过此部分。
| 意图 | 命令 | |--------|---------| | 查看问题 | `jira issue view ISSUE-KEY` | | 列出我的问题 | `jira issue list -a$(jira me)` | | 我的进行中问题 | `jira issue list -a$(jira me) -s"In Progress"` | | 创建问题 | `jira issue create -tType -s"Summary" -b"Description"` | | 移动/流转 | `jira issue move ISSUE-KEY "State"` | | 指派给我 | `jira issue assign ISSUE-KEY $(jira me)` | | 取消指派 | `jira issue assign ISSUE-KEY x` | | 添加评论 | `jira issue comment add ISSUE-KEY -b"Comment text"` | | 在浏览器中打开 | `jira open ISSUE-KEY` | | 当前冲刺 | `jira sprint list --state active` | | 我是谁 | `jira me` |
---
## 快速参考 (MCP)
> 如果使用 CLI 后端，请跳过此部分。
| 意图 | MCP 工具 | |--------|----------| | 搜索问题 | `mcp__atlassian__searchJiraIssuesUsingJql` | | 查看问题 | `mcp__atlassian__getJiraIssue` | | 创建问题 | `mcp__atlassian__createJiraIssue` | | 更新问题 | `mcp__atlassian__editJiraIssue` | | 获取流转状态 | `mcp__atlassian__getTransitionsForJiraIssue` | | 流转 | `mcp__atlassian__transitionJiraIssue` | | 添加评论 | `mcp__atlassian__addCommentToJiraIssue` | | 用户查询 | `mcp__atlassian__lookupJiraAccountId` | | 列出项目 | `mcp__atlassian__getVisibleJiraProjects` |
完整的 MCP 模式请参见 `references/mcp.md`。
---
## 触发词
- "create a jira ticket" (创建一个 Jira 工单) - "show me PROJ-123" (给我看 PROJ-123) - "list my tickets" (列出我的工单) - "move ticket to done" (移动工单到已完成) - "what's in the current sprint" (当前冲刺里有什么)
---
## 问题键检测
问题键遵循以下模式：`[A-Z]+-[0-9]+`（例如 PROJ-123, ABC-1）。
当用户在对话中提到问题键时： - **CLI:** `jira issue view KEY` 或 `jira open KEY` - **MCP:** 使用该键调用 `mcp__atlassian__jira_get_issue`
---
## 工作流
**创建工单：** 1. 如果用户引用了代码/工单/PR，请研究上下文 2. 起草工单内容 3. 与用户复核 4. 使用适当的后端创建
**更新工单：** 1. 首先获取问题详情 2. 检查状态（注意进行中的工单） 3. 展示当前与拟议的更改 4. 更新前获得批准 5. 添加评论解释更改
---
## 执行任何操作之前
问问你自己：
1. **当前状态是什么？** — 始终先获取问题。不要假设状态、经办人或字段就是用户认为的那样。
2. **还有谁会受到影响？** — 检查关注者、关联的问题、父级史诗。一次“简单的编辑”可能会通知 10 个人。
3. **这可以撤销吗？** — 流转可能存在单向闸。某些工作流需要中间状态。描述编辑无法撤销。
4. **我有正确的标识符吗？** — 问题键、流转 ID、账户 ID。显示名称无法用于指派 (MCP)。
---
## 切勿
- **切勿在未获取当前状态的情况下流转** — 工作流可能需要中间状态。如果需要先进行“In Progress”，“To Do” → “Done” 可能会静默失败。
- **切勿使用显示名称进行指派 (MCP)** — 只有账户 ID 有效。始终先调用 `lookupJiraAccountId`，否则指派会静默失败。
- **切勿在未显示原始内容的情况下编辑描述** — Jira 没有撤销功能。用户必须看到他们正在替换的内容。
- **切勿在缺少所有必填字段时使用 `--no-input` (CLI)** — 会静默失败并报出难以理解的错误。请先检查项目的必填字段。
- **切勿假设流转名称是通用的** — “Done”、“Closed”、“Complete” 因项目而异。始终先获取可用的流转。
- **切勿未经明确批准就批量修改** — 每个工单更改都会通知关注者。10 次编辑 = 10 次通知风暴。
---
## 安全性
- 在运行之前始终显示命令/工具调用 - 在修改工单之前始终获得批准 - 编辑时保留原始信息 - 应用更新后进行验证 - 始终清晰地提示身份验证问题，以便用户解决
---
## 无可用后端
如果 CLI 和 MCP 均不可用，请引导用户：
``` To use Jira, you need one of:
1. **jira CLI** (recommended): https://github.com/ankitpokhrel/jira-cli
Install: brew install ankitpokhrel/jira-cli/jira-cli Setup: jira init
2. **Atlassian MCP**: Configure in your MCP settings with Atlassian credentials. ```
---
## 深入探究
**加载参考文档，当：** - 创建包含复杂字段或多行内容的问题时 - 构建超出简单筛选器的 JQL 查询时 - 排查错误或身份验证问题时 - 处理流转、关联或冲刺时
**不要加载参考文档，当：** - 简单的查看/列表操作（上面的快速参考已足够） - 基本的状态检查 (`jira issue view KEY`) - 在浏览器中打开问题
| 任务 | 是否加载参考？ | |------|-----------------| | 查看单个问题 | 否 | | 列出我的工单 | 否 | | 创建并附带描述 | **是** — CLI 需要 `/tmp` 模式 | | 流转问题 | **是** — 需要流转 ID 工作流 | | JQL 搜索 | **是** — 用于复杂查询 | | 关联问题 | **是** — MCP 限制，需要脚本 |
参考文档： - CLI 模式：`references/commands.md` - MCP 模式：`references/mcp.md`