jira

Jira 工作项管理

使用 Atlassian CLI（acli）查看、搜索、筛选、创建和更新 Jira 项目中的工作项。

前置条件

运行任何命令前，先检查这两项依赖是否可用。在会话开始时检查一次即可，无需每次运行命令前都检查。

1. acli — 运行 acli --version。如果未安装，请阅读 references/prerequisites.md 中的安装说明。
2. mdadf — 运行 mdadf --version。如果未安装，请阅读 references/prerequisites.md 中的安装说明。

如果缺少任一工具且无法安装（例如无法访问网络），请准确告知用户需要运行哪些命令，然后停止。

操作限制

• 项目只读：绝不修改 Jira 项目本身。只能在项目中创建、更新或删除工作项。

• 变更意图：对于创建、编辑、转换、分配、评论或删除操作，只有在用户明确要求进行相应变更时才修改 Jira。如果请求含糊，请先确认再修改。

• 优先使用工作项键：如果用户提供了类似 MYPROJECT-1455 的工作项键，请直接使用，不要编写 JQL。具体 CLI 语法因子命令而异（view 使用位置参数；edit、transition、assign 和 comment 使用 --key 标志）——请参阅 references/commands.md。

• JQL：在适用时，使用 --jql 选择、搜索或筛选工作项。

• 已配置的默认项目：如果用户未指定项目，请按下方的项目解析链进行解析（工作区 .jira-skill.json → 用户全局 ~/.config/jira-skill/config.json → 询问用户）。

• 工作项类型：Bug、Task、Story、Epic

• 富文本：先用 Markdown 起草 Jira 描述和评论正文，再使用 mdadf --compact 将其转换为 ADF，然后再调用 acli：

  acli jira workitem create \
    --summary "Fix the login page" \
    --project "MYPROJECT" \
    --type "Bug" \
    --description-file <(mdadf --compact <<'MD'
  **Short Description**
  The login page returns a 500 on empty email.
  MD
  )
  

  对于 Windows PowerShell 或其他平台专用模式，请阅读 references/mdadf-usage.md。

项目解析

每次收到请求时都要解析项目键——不要在不同请求间缓存，因为用户可能会切换仓库。

1. 如果用户提供了 Jira 问题键，例如 MYPROJECT-1455，请使用其前缀作为项目键。
2. 如果用户明确指定了项目键，例如 MYPROJECT，请使用该键。
3. 否则，从当前工作目录开始向上遍历父目录，直到到达仓库根目录（包含 .git 的目录），搜索 .jira-skill.json。如果找到且其中包含有效的 defaultProject，请使用它。
4. 否则，读取 ~/.config/jira-skill/config.json。这是适用于所有仓库的用户全局备用配置。
5. 如果没有找到配置，必须停止并在继续前询问用户以下两项：
   • 哪个项目？（通过 acli jira project list --recent）列出可用项目，并请用户确认。不要猜测或自动选择项目，即使只返回了一个项目也不行。
   • 保存到哪里？询问是否将默认值保存到全局配置（~/.config/jira-skill/config.json，适用于所有仓库）或项目级配置（仓库根目录下的 .jira-skill.json）。默认建议使用全局配置，因为大多数用户一次只在一个项目上工作。只有在用户回答这两个问题后才写入配置。如果用户只确认了项目，但未指定保存位置，则使用全局配置。

.jira-skill.json 是工作区本地配置——不同仓库可以使用不同的默认值。如果不应共享此文件，请将其添加到 .gitignore。~/.config/jira-skill/config.json 是用户全局配置，在技能更新后仍会保留。

配置结构：

{
  "defaultProject": "YOUR_PROJECT_KEY"
}

安全规则

这些规则旨在避免常见的 Jira 操作失误。必须严格遵守。

1. 在获取当前状态之前，绝对不要执行状态转换。 Jira 工作流可能要求经过中间状态（例如：待办 → 进行中 → 审核中 → 已完成）。跳过某个步骤可能会静默失败，也可能抛出令人困惑的错误。执行任何状态转换前，务必运行 acli jira workitem view <KEY> --fields "status"。

2. 未经用户明确批准，绝对不要批量修改。 每次编辑都会通知关注者。编辑 10 张工单意味着会触发 10 次通知风暴。操作多个工作项前，务必先向用户确认。

3. 未经展示原始内容，绝对不要编辑描述。 Jira 不支持撤销。替换描述前，先显示当前内容，以便用户确认没有遗漏。

4. 绝对不要假设状态转换名称通用。 “Done”“Closed”“Complete”“Resolved”会因项目和工作流方案而异。如有疑问，请使用 acli jira workitem view <KEY> --fields "status" 检查当前状态，并询问用户要使用哪个目标状态。

5. 绝对不要为新工单设置 Priority、Technical Impact 或 Business Urgency。 这些字段供负责人或产品人员进行分流处理。未经授权创建“Critical”工单会破坏分流流程。如果用户明确要求设置优先级，请予以确认，并说明优先级通常在分流过程中设置。

执行步骤

1. 如果请求会修改数据，请先查看上述安全规则，并在运行任何命令前确定适用哪些规则。
2. 使用上述项目解析规则确定项目键。
3. 如果请求针对特定工作项键，请直接使用该键，而不是使用 JQL。查看 references/commands.md，确认子命令是将键作为位置参数，还是使用 --key 标志。仅在搜索或针对多个工作项时使用 JQL。
4. 如果请求需要富文本，请使用 Markdown 编写内容，并在运行 acli 前使用 mdadf --compact 将其转换为 ADF。如需平台特定语法，请阅读 references/mdadf-usage.md。
5. 如果要创建或重写工作项，请遵循 references/ticket-drafting.md 中的撰写格式。
6. 运行相应的 acli 命令。完整的标志参考请阅读 references/commands.md。
7. 阅读并分析输出。如果发生错误，请运行 acli --help 或相关子命令的帮助信息以获取指引。

输出格式

• 创建、编辑、状态转换、评论或分配操作后，始终附上 Jira 直接链接。 从 acli 输出中解析 URL（例如：✓ Work item MYPROJECT-100 created: https://…/browse/MYPROJECT-100），并将其作为可点击链接呈现。绝不能只报告问题键而不附上 URL。
• 报告搜索结果或调查发现时，请使用包含工作项链接的表格格式。