工单获取器 是做什么的?
仅获取 — 不作分析、需求或规划。输出为自包含的 .TICKET.md 文件。
来源与访问
从输入中识别工单跟踪系统(URL 主机或 ID 形状),并通过匹配的 MCP 服务器获取——例如使用 Azure DevOps MCP 获取 ADO 工作项、使用 Atlassian MCP 获取 Jira 问题、使用 GitHub MCP / gh 获取 GitHub 问题。使用任何已连接的等效工具;工具名称前缀因配置而异。一次性解析 MCP 所需的任何句柄(例如 Atlassian cloudId、ADO 项目),然后复用。如果输入有歧义,请询问用户——不要猜测。如果没有匹配的 MCP 连接:公共工单可能从其 URL 抓取作为后备方案(你仍可建议安装匹配的 MCP,如果它效果更好);私有工单则无法抓取——URL 返回登录页面,而非工单——所以停止并告知用户安装并认证匹配的 MCP 服务器,然后重新运行。
你的任务
- 解析输入。 接受完整的工单 URL 或裸 ID/键;提取标识符。如果跟踪系统使用键前缀(例如
XX-1234),保留它;否则使用裸数字。如果输入无法识别,请询问。 - 获取工单。 获取工作项/问题及其完整的字段集、内联注释和扩展的相关链接/关系。捕获工单携带的所有内容——不要预先过滤到固定字段集。将你得到的任何富文本格式(HTML、ADF 等)转换为干净的 Markdown。
- 选择一个短标识。 从标题/摘要中提取长度为 3-5 个单词的短 kebab-case 标识——便于 grep,不要过度思考。
- 决定输出目录。 项目计划目录(例如
.claude/plans/)内的项目相对<id>-<slug>/子目录——遵循项目/用户对计划存放位置的约定;如果没有定义,请询问用户。切勿猜测。 如果该目录已存在,建议<id>-<slug>-v2、-v3等——切勿覆盖现有的计划目录;每次重新获取的历史记录是有意保留的。 - 编写工单文件 到
<输出目录>/<id>-<slug>.TICKET.md。 - 下载附件 到输出目录;对任何失败的附件发出警告(参见附件)。
- 打印结果 —— 项目相对路径和下一步操作行(参见下一步操作)。
工单文件结构
必须独立存在:工单的完整可读版本,包含足够的元数据,使一个新的会话无需重新获取即可识别来源。
头部
包含源元数据的纯 Markdown 头部;省略任何值缺失的行。包含跟踪系统提供的所有内容。示例:
# <标题 / 摘要>
> **来源** [<ID>](<URL>)
> **类型** {类型}
> **状态** {状态}
> **负责人** {显示名称或 "—"}
> **报告人 / 创建者** {显示名称}
> **标签 / 标记** {已合并或 "—"}
> **获取时间** {今天 YYYY-MM-DD}
正文部分
按此顺序输出,仅当存在且非空时:
## 描述## 验收标准—— 如果跟踪系统有专门的已填写的 AC 字段## <其他字段>—— 每个其他包含真实内容(技术说明、自定义字段等)的已填写字段一个部分,以字段的显示名称作为标题。捕获工单持有的所有内容。## 评论—— 最早的在最前面,每个### <作者> — <日期>然后是正文。尽力而为:如果未返回评论,简要说明或省略该部分。## 关联工单—— 见下文## 附件—— 见下文## 设计参考—— 见下文
保留标题层级、项目符号结构、强调和代码块;将字段内的子标题映射为 ####。省略空部分。逐字引用面向用户的字符串、代码标识符、文件路径、i18n 键和 URL —— 切勿更改或翻译它们。
关联工单
从响应的链接/关系(以及任何远程链接工具)中,对于每个唯一的链接工单(排除此工单),通过一次廉价调用仅获取标题 + 状态 + 类型 —— 而非完整正文。主要目标是记录所有相关工单的痕迹,以便将来需要时可以获取。每个工单一个项目符号,如果可用则包含关系:
- [<ID>](<URL>) — (<类型>, <状态>) <标题>
对于非工单的远程链接(例如 wiki/Confluence 页面),以纯项目符号形式输出标题和 URL。如果获取失败,将链接列在 (无法获取) 之后,而不是使整个运行失败。
附件
识别每个附件以及描述/字段中引用的每个内嵌图片,按首次出现顺序编号为 attachment-<N>.<ext>,保留原始扩展名。<N> 在两者之间连续计数。
始终尝试获取 —— 通过每个已连接的 MCP。 除了跟踪系统托管的附件,工单可能链接外部资产(例如 Confluence/ADO 资源 —— 对于设计工具链接如 Figma 或 Zeplin 请参见下文的设计参考),可通过它们自己的 MCP 访问,包括链接的 git 仓库中的规范/文档文件(通过 git 或仓库 MCP 获取其内容,以其自己的文件名保存到输出目录)。使用适合源的 MCP 下载它们;不要预先声明链接不可获取。如果合适的 MCP 已连接但未认证,不要静默跳过 —— 主动运行其认证流程(显示登录 URL,完成握手),无需等待被询问,然后获取。当不确定某个资产是否可以或应该下载时,请询问用户。
直接将每个附件保存到磁盘 —— curl -fSL <url> -o attachment-<N>.<ext>,或 MCP 附件工具的保存到路径变体。切勿将附件作为内联 base64 通过模型路由并重新输出:输出上限(约 100k 字符)会静默截断它 —— 有效的头部,缺失尾部,无法打开。某些附件 MCP 工具仅返回 base64,没有保存到路径选项(例如 ADO wit_get_work_item_attachment)—— 不要将它们用于二进制文件;而是使用承载令牌直接从跟踪系统的 REST API 获取到磁盘(ADO:az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv,然后 curl -H "Authorization: Bearer <token>" "<attachmentUrl>" -o attachment-<N>.<ext>)。(内容 URL 通常与 MCP 共享认证;如果返回 401,在可获取的情况下使用跟踪系统的承载令牌重试。)
验证完整性,而不仅仅是传输 —— 非空;如果发送了 Content-Length 则匹配;类型尾部存在(PNG IEND、JPEG FFD9、PDF %%EOF)。大小恰好是 3 的倍数且接近整数边界表示 base64 截断。失败时,重新下载到磁盘;如果仍然损坏,视为未下载并发出警告 —— 切勿引用已损坏的文件。然后,每个文件:
- 已下载 → 引用本地文件。
- 未下载(没有合适的 MCP/附件工具、无法完成的认证等)→ 仍然引用本地文件和源 URL,并将其添加到要警告的列表中。不要阻塞 —— 工单无论哪种方式都是可用的。
图片 → 嵌入;非图片(PDF、.docx 等)→ 改为链接:
### 附件 1

_原始文件名:image.png_
### 附件 2
[attachment-2.pdf](attachment-2.pdf) — _原始文件名:design-spec.pdf_
对于无法下载的文件,附加其来源以便用户手动获取:— 未下载;从 <url> 获取并保存到此路径为 attachment-<N>.<ext>。
设计参考
对于描述/评论中的设计工具链接(Figma、Zeplin、Sketch、Adobe XD 等),不要将它们编号为 attachment-<N> —— 它们是实时引用,而非附着的文件。通过该工具的 MCP(例如 Figma MCP get_screenshot)捕获每个引用的画框/屏幕,将返回的短时 URL 直接下载到磁盘,命名为 <工具>-<ID>-<标识>.png(如果需要,首先认证其 MCP —— 参见附件)。如果没有该工具的 MCP 连接,仍然记录条目及其名称和源 URL,并将其添加到警告列表 —— 与未下载的附件相同。每个链接记录一个条目,包含本地预览以及在工具中重新打开所需的标识符:
### <设计名称>

_Figma · 文件 `<fileKey>` · 节点 `<nodeId>` · [来源](<url>)_
边界
- 不要分析、规划或探索代码库以获取上下文 —— 这不排除工单明确链接的文件,你仍然需要获取它们(参见附件)。
- 不要在其跟踪系统中修改工单 —— 获取是只读的(不添加评论、不改变状态、不编辑、不记录工作日志)。
- 你创建的唯一文件:
.TICKET.md、其附件以及你获取的任何链接文档。
下一步操作
完成后明确说明,使用项目相对路径(切勿使用绝对路径):输出目录、工单文件以及任何附件。如果任何附件无法下载,首先发出明确警告,列出每个缺失的 attachment-<N>.<ext> 及其源 URL,指示用户下载并将其保存到该确切名称下,以便嵌入能够解析。然后作为单条可复制粘贴的启动命令移交下一阶段 —— 会话名称和提示组合在一起,以便一次粘贴即可启动会话。使用正在使用的代理工具的启动语法(与厂商无关 —— 下面的 claude 仅是示例),将会话命名为 refine-<标识>:
claude --name refine-<标识> "/refine-ticket <输出目录>/<id>-<标识>.TICKET.md"
然后提供替代方案 —— 清除当前会话(与厂商无关 —— 下面的 /clear 仅是示例;使用正在使用的代理工具的清除命令):
或 /clear 并运行:
/refine-ticket <输出目录>/<id>-<标识>.TICKET.md

