Community写作与编辑github.com

工单获取器

仅获取工单,不作分析、需求或规划,输出为自包含的 .TICKET.md 文件。

工单获取器 是什么?

该技能“工单获取器”(源文件:SKILL.md)旨在为AI编码助手(如Claude Code、Cursor或其他MCP兼容工具)提供一种极简、可重复使用的工单获取能力。其主要功能是从Jira、Azure DevOps或GitHub等平台获取完整工单/issue信息,并将所有内容(包括字段、注释、附件、关联链接)转换为一份独立的Markdown文件,不进行任何分析、需求推导或代码探索。它强调“只读”操作,不会修改远程工单系统。用户可提供工单URL或ID,技能会通过对应的MCP服务器自动获取数据,如果MCP未连接,则尝试从公共URL抓取。输出文件遵循固定结构,包含标题、元数据、描述、验收标准、注释、关联工单和附件,所有附件直接保存到本地磁盘,而非通过模型传递,以避免输出截断。最终,技能会提示下一步操作建议,例如使用`/refine-ticket`命令继续处理。该技能特别适用于需要快速获取工单上下文、但不希望AI对其进行初步分析的开发场景。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add FrancescoBorzi/agent-toolkit

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

attachment-1
figma-<nodeId>

文档

工单获取器 是做什么的?

仅获取 — 不作分析、需求或规划。输出为自包含的 .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 服务器,然后重新运行。

你的任务

  1. 解析输入。 接受完整的工单 URL 或裸 ID/键;提取标识符。如果跟踪系统使用键前缀(例如 XX-1234),保留它;否则使用裸数字。如果输入无法识别,请询问。
  2. 获取工单。 获取工作项/问题及其完整的字段集、内联注释和扩展的相关链接/关系。捕获工单携带的所有内容——不要预先过滤到固定字段集。将你得到的任何富文本格式(HTML、ADF 等)转换为干净的 Markdown。
  3. 选择一个短标识。 从标题/摘要中提取长度为 3-5 个单词的短 kebab-case 标识——便于 grep,不要过度思考。
  4. 决定输出目录。 项目计划目录(例如 .claude/plans/)内的项目相对 <id>-<slug>/ 子目录——遵循项目/用户对计划存放位置的约定;如果没有定义,请询问用户。切勿猜测。 如果该目录已存在,建议 <id>-<slug>-v2、-v3 等——切勿覆盖现有的计划目录;每次重新获取的历史记录是有意保留的。
  5. 编写工单文件 到 <输出目录>/<id>-<slug>.TICKET.md。
  6. 下载附件 到输出目录;对任何失败的附件发出警告(参见附件)。
  7. 打印结果 —— 项目相对路径和下一步操作行(参见下一步操作)。

工单文件结构

必须独立存在:工单的完整可读版本,包含足够的元数据,使一个新的会话无需重新获取即可识别来源。

头部

包含源元数据的纯 Markdown 头部;省略任何值缺失的行。包含跟踪系统提供的所有内容。示例:

# <标题 / 摘要>

> **来源** [<ID>](<URL>)
> **类型** {类型}
> **状态** {状态}
> **负责人** {显示名称或 "—"}
> **报告人 / 创建者** {显示名称}
> **标签 / 标记** {已合并或 "—"}
> **获取时间** {今天 YYYY-MM-DD}

正文部分

按此顺序输出,仅当存在且非空时:

  1. ## 描述
  2. ## 验收标准 —— 如果跟踪系统有专门的已填写的 AC 字段
  3. ## <其他字段> —— 每个其他包含真实内容(技术说明、自定义字段等)的已填写字段一个部分,以字段的显示名称作为标题。捕获工单持有的所有内容。
  4. ## 评论 —— 最早的在最前面,每个 ### <作者> — <日期> 然后是正文。尽力而为:如果未返回评论,简要说明或省略该部分。
  5. ## 关联工单 —— 见下文
  6. ## 附件 —— 见下文
  7. ## 设计参考 —— 见下文

保留标题层级、项目符号结构、强调和代码块;将字段内的子标题映射为 ####。省略空部分。逐字引用面向用户的字符串、代码标识符、文件路径、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

![attachment-1](attachment-1.png)
_原始文件名: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-<nodeId>](figma-<nodeId>-<标识>.png)
_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

相关技能