inspecting-jira-issues

为 AI Agent 检查 Jira 问题

概述

Jira 摘要是了解 bug 最糟糕的方式。实际复现步骤几乎总是在附件、评论或关联问题中——这三个位置默认都不会显示在 acli jira workitem view 中。一个“根据摘要”开展工作的 AI Agent，只能猜出一半问题。

本技能是通过命令行完整阅读 Jira 工单的标准做法，也介绍如何下载 Agent 实际能够查看的附件文件（不太显而易见的一点是——acli 没有 attachment download 子命令）。

适用场景

• 你刚打开 Jira URL，正准备开始修复
• 描述只有 image-20260427-021811.png，没有文字
• Agent 说“我会根据摘要开展工作”，或者“你能把截图贴出来吗”
• curl 访问 Jira REST API 时返回 401/403/406

不要用于没有附件和关联问题的简单工单——acli jira workitem view KEY 就够了。

检查工作流

最快的方法只需一条命令。使用绝对路径——该技能安装在 ~/.claude/skills/inspecting-jira-issues/，默认不在 PATH 中：

JIRA_SITE=https://your-site.atlassian.net \
  ~/.claude/skills/inspecting-jira-issues/jira-to-markdown.py KGM-3320
# → /tmp/jira/KGM-3320/ticket.md
# → /tmp/jira/KGM-3320/attachments/*
# → /tmp/jira/KGM-3320/subtasks/<CHILD-KEY>/...   (every child, recursively)

默认情况下，它还会递归下载所有子工单——包括传统子任务以及父级/史诗工单的子项（通过 parent = <KEY> 搜索找到，因此即使史诗工单的子项不在 subtasks 字段中，也会一并获取）。每个子项都会完整导出到 subtasks/<KEY>/，并为其孙级工单创建自己的 subtasks/。传入 --no-subtasks，即可只获取顶层问题。

（按照 README 中的说明将其软链接到 ~/bin/ 后，也可以直接使用 jira-to-markdown.py KGM-3320。）

jira-to-markdown.py 会写入一个自包含目录：其中包含一个 ticket.md，将所有已填充字段渲染出来——表头涵盖所有标量字段（标准字段和自定义字段，标签通过 ?expand=names 解析），每个 ADF 文档字段则各自生成一个 ## Section（描述、环境以及所有 ADF 自定义字段）。随后是附件、关联问题、子任务和评论。每个附件都会下载到 attachments/ 下，并以内嵌形式引用，例如 ![alt](attachments/foo.png)；每个子工单都会递归下载到 subtasks/ 下（除非传入 --no-subtasks）。

为何要完整导出：TPT bug 工单中的实际复现步骤往往位于 fields.environment（发生阶段、复现步骤、平台等）中，而默认情况下，描述和 acli workitem view 都不会显示这些内容。Severity、Urgency、Epic Link 等自定义字段也一样。预先整理字段意味着不必每次查看一张工单时才重新发现遗漏的字段。

该脚本会处理那些不太显而易见的细节——存储在钥匙串中的 OAuth 令牌、ADF→Markdown 转换（段落、列表、标题、代码、链接、标记、提及、面板、表格、媒体）、文件名冲突消歧，以及绕过 406 Not Acceptable 的 Accept: */* 特性。

如果只需要其中一项，底层命令仍然可用：

KEY=KGM-3320

acli jira workitem view "$KEY" --fields '*all' --json     # full JSON
acli jira workitem attachment list --key "$KEY" --json    # attachment IDs
~/.claude/skills/inspecting-jira-issues/download-jira-attachment.sh 188469 /tmp/$KEY.png
acli jira workitem comment list --key "$KEY"              # comments alone

信息藏在哪里

你要找的内容	实际所在位置
Bug 复现步骤	评论中，而非描述中
显示 bug 的截图	附件
此工单的重要性／对客户的影响	自定义字段（严重程度、紧急程度）——使用 --fields '*all' 获取
修复是否已在其他地方发布	父级史诗工单的评论中，或关联的“被复制”问题中
实际症状	截图中，绝不在摘要中

下载附件——容易忽略的部分

acli 没有 attachment download 命令。直接对 *.atlassian.net/rest/api/3/attachment/content/<id> 使用 curl 通常会返回 403。每个 Agent 都会遇到以下四个陷阱：

陷阱	解决方法
OAuth 令牌在哪里？	在 macOS 钥匙串中（security find-generic-password -s acli），不在 ~/.config/acli/ 中。存储格式为 go-keyring-base64:<base64(gzip(JSON))>。
应该请求哪个 URL？	https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/attachment/content/<id>——这是 OAuth 代理。站点 URL 不接受 acli 的令牌。
cloudId 在哪里？	钥匙串账户名称就是 oauth:<cloudId>:<userId>。无需调用 getAccessibleAtlassianResources。
为什么我的请求返回 406？	Accept: image/png 会触发 406（“可接受的表示形式：[application/json]”）。请使用 Accept: */*（或省略 Accept）。

此技能目录中的 jira-to-markdown.py（完整工单转储）和 download-jira-attachment.sh（下载单个附件）已将这四种处理方式全部整合在内。将它们复制到 $PATH 下（例如 ~/bin/）。

前提条件

brew tap atlassian/homebrew-acli
brew install acli
acli auth login        # one-time OAuth dance — also re-run if you change sites

首次运行 acli auth login 时，OAuth 令牌会存入 macOS 钥匙串。此技能中的两个脚本都会从那里读取令牌。

可选：解析 Excel 附件

如果工单附带 .xlsx / .xls / .xlsm 文件，jira-to-markdown.py 会通过 xlsx-to-markdown 技能将其解析为 Markdown（每个工作表生成 PNG + 提取文本），并将结果写入 attachments/<stem>-xlsx/ 下、与文件放在一起的位置，然后在“附件”部分添加链接。这是尽力而为的操作：如果未安装该技能（或其 CLI 依赖项），转储仍会完成，只会在标准错误中说明已跳过。启用方法如下：

npx skills add coolbit/excel-to-markdown      # installs as xlsx-to-markdown
brew install poppler imagemagick              # + LibreOffice (soffice) — see that skill's README

转换器会自动在 ~/.claude/skills/ 或 ~/.agents/skills/ 中查找（可通过 XLSX_TO_MD 环境变量覆盖）。

令牌过期

访问令牌的有效期约为 1 小时。脚本启动时会调用 acli auth status 来触发静默刷新，因此长时间间隔后的首次运行无需手动干预即可正常工作。如果 acli auth status 本身报告刷新令牌已过期，请重新运行 acli auth login。

常见错误

错误	修正方法
只看摘要就开始修复	摘要只是标签，不是错误本身。务必先获取 JSON 和附件。
因为“描述里有文字”就跳过附件	如果描述引用了图片，图片就是描述的一部分。请下载图片。
忽略评论	复现步骤、决策，以及“这个问题实际上已在 PR #123 中修复”等信息都在评论里。
跳过关联工单	“is duplicated by” 通常会指向包含实际修复计划的工单。
使用站点 URL 发送 OAuth 请求	使用 api.atlassian.com/ex/jira/<cloudId>/...。
使用 Accept: image/png	会返回 406。请使用 Accept: */*。
在 ~/.config/acli 中搜索令牌	令牌在 macOS 钥匙串中。配置文件中只有元数据。
将钥匙串数据块当作原始令牌	其格式为 go-keyring-base64:<base64(gzip(JSON))>。请解码并提取 access_token。
因为 acli 没有下载命令就放弃	这个技能存在的原因，正是为了绕过钥匙串。
让用户粘贴截图	API 就在眼前，不要麻烦用户。

危险信号——停止并重新检查

如果你发现自己正在想以下任何一句话，说明你还没有完整阅读工单：

• “根据摘要，我会……”
• “可以分享一下截图吗？”
• “我先假设这个错误是……”
• “描述没说太多，所以……”
• “这里有个附件，但我无法查看图片”

这些情况都意味着：运行上述检查工作流，然后再思考。

铁律

如果 Jira 工单提到了截图、附件、评论或关联工单，而你还没有读过相关内容，就说明你还不了解这个错误。

读完整个工单。然后再思考。