SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场jira-bug

jira-bug

编程与开发

查看项目

更新于 10-22 16:17

技能介绍

用途

jira-bug 是一个面向 AI 代理的技能，用于为指定的 Jira 缺陷工单生成「Bug 修复代码评审摘要」，并在用户要求时以评论形式发布到该工单。它把 Jira 工单中的缺陷描述与已核实的 Git 变更范围进行对照，输出结构化的评审总结，帮助开发、BA 与 QA 理解修复内容、影响范围与验证状态。该技能可独立安装和使用，但需依赖可用的 Jira 工具与仓库访问能力。

主要能力

  • 工单信息获取：按能力发现可用的 Jira 工具（站点发现、问题检索、评论列表、评论创建），从用户和项目上下文确定目标站点与问题键；若存在多个可能站点，会先询问。支持跟随评论分页，直到找到相关历史摘要或检查完所有评论；访问不完整时会明确说明限制，不会断言不存在历史摘要。
  • 历史摘要识别：扫描已有评论，通过横幅行（首次摘要为 "AI-generated Bug CR summary"，更新为 "Updated Bug CR summary"）或任意级别的 Bug 标题识别此前的 Bug CR 摘要；不依赖字面 # 前缀，也不把仅以 "Bug" 开头的评论当作匹配。存在多条时取最近一条，并记录其评论 ID、发布日期、语言以及无法从 diff 重新生成的信息（如截图、热修复版本列表）。
  • 变更范围解析：检查仓库指令、Git 状态、分支与远程；优先遵循用户明确指定的暂存区、提交、分支、MR/PR 范围。支持暂存区（git diff --cached）、特定提交（含父提交补丁）、提交范围、分支（验证基线并比较完整分支 diff）、MR/PR（获取相关 refs 后读取已验证的源/目标 refs 与完整 diff）。未指定范围时，从当前任务、匹配的工单分支和现有 MR/PR 推断；暂存区 diff 为空不作为实现缺失的证据；多个可能范围会产生不同摘要时会提出一个聚焦问题。记录仓库、范围模式、适用的 base/head SHA 与变更文件数。
  • 对比与分析：将选定的代码变更与 Jira 工单中的缺陷细节和预期对比，说明触发条件、预期/实际行为、已确认原因或剩余假设，以及变更如何解决该问题；区分代码检查与复现/回归测试证据。按产品术语描述受影响区域（配置、模块、功能/问题、组件），模板中不出现文件名和类名。报告实际运行的检查、结果与未运行的检查；仅代码检查不足以确立运行时正确性或完整验收。对 API 相关工作，在代码支持的前提下描述端点/方法、请求字段、授权、处理与源数据解析、重复行为、响应状态与范围，未知契约需明确标注。
  • 模板化摘要：保持固定标题与表格结构，不添加其他章节。模板包含 # Bug、Summary、Affected Areas、Summary/Screenshots 表以及 Affected Areas 描述表（Configurations、Modules、Features / Issues、Components、Version）。Version 行模板文字是给开发者的指令，需在工单、用户或历史摘要提供版本列表时替换；未知时保留指令文字并在回复中告知用户未提供列表，不推断版本。Bug 行以编号条目加四个短要点撰写：发生什么、原因、修复什么、修复后如何。原因未确认时标注为假设并说明未检查项；不把仅隐藏错误的防护当作修复，除非符合领域契约。面向全体团队写作，从用户视角描述操作与所见，使用屏幕名称；不可避免的技术术语需解释。状态用摘要语言平实书写（泰语可用 ทดสอบผ่าน、ทดสอบไม่ผ่าน、ยังไม่ได้ทดสอบ、ยังยืนยันไม่ได้），仅在实际运行或报告过检查时使用已测试状态，并写明结果与范围；读代码不算测试。截图单元格在前后截图都存在时放置成对截图。Features / Issues 单元格可加入「ควรทดสอบซ้ำ:」行，列出修复可能影响的邻近屏幕或功能；未检查调用方时省略该行。缺陷未要求的行为用「(เพิ่มนอกบั๊กนี้)」标注，供 BA 与 QA 确认。发布前重读评论，删除填充内容、重复点和机器感措辞。
  • 草稿与发布：首次摘要需在顶部加一行说明这是基于已检查变更范围生成的 AI Bug CR 摘要。已有历史摘要时，新评论需引用旧评论以便追踪更新历史，以更新横幅开头并尽可能链接旧评论（https://<site>.atlassian.net/browse/<TICKET>?focusedCommentId=<commentId>#comment-<commentId>）；不添加变更章节，就地更新表格；若历史摘要与当前代码矛盾，在表格中更正并在横幅行说明；延续仍有效且 diff 无法重新生成的信息（如截图、热修复版本列表），明确说明仍适用而非静默丢弃；除非用户要求，保持与历史摘要相同的语言。首次摘要默认使用团队模板示例语言（泰语，产品与 UI 名称用英文），除非用户或仓库指令另有说明。有图片时添加：截图，或无屏幕的修复用前后测试输出、API 响应或数据库记录；并非每行都需图片，但单元格不能留空；预期有图但未附时写 รอแนบภาพ 并注明待附内容（如 รอแนบภาพ: ผลรัน test）；无需图片时写 ไม่มีภาพ；沿用历史图片时写 ภาพเดิมใน comment <id>。通过或失败结果保留在 Summary 单元格，不为此文本着色。先准备完整评论；仅要求总结或评审时以本地草稿结束，除非明确要求发布；用户已要求发布时则继续而不再询问；需要发布但未授权时，仅就已完成可审阅的草稿请求批准。发布前确认问题并重读相关历史摘要，避免重复或覆盖更新的更新；若选定变更在分析后发生移动，先刷新证据与草稿。保留现有评论，工作流创建带链接的后续评论，而非删除或覆盖历史。使用可用的 Jira 评论创建工具及其支持的正文格式发布到已验证问题。
  • 发布后验证：发布后检索新建评论，验证其问题、正文与链接；写入结果不确定时先检查现有评论再重试，避免重复发布。返回评论链接与发布状态，或将结果标注为草稿；明确报告检查/测试限制，没有证据不声称发布成功。

使用方式

用户通过 /jira-bug 显式调用该技能，例如要求「为 PROJ-001 创建 bug CR」或「对 [Ticket ID] 运行 jira-bug」。技能会从当前任务解析仓库与 Jira 站点，按上述工作流获取信息、读取变更、撰写摘要，并在明确要求时发布。

评论格式

Atlassian Document Format（ADF）的 Markdown 模板定义内容与顺序，而非字面正文语法。当评论工具接受 ADF 时，发送 version: 1、type: "doc" 及有序内容节点的 JSON 文档；使用 heading、paragraph 节点做章节，使用 table、tableRow、tableHeader、tableCell 节点做两个表格；对一级 Bug 标题同时应用 strong 与 textColor 标记，颜色为 #ff5630；每个 bug 行的编号放在 Summary 表格单元格内的段落中，后跟一个 bulletList，每个详情一个 listItem。发布前检查实际评论工具 schema：仅在工具接受 ADF 时发送 ADF 对象；不要假定 contentFormat: adf，也不要把 ADF 序列化为字符串。当前 Atlassian MCP 评论工具接受 Markdown 或 HTML 字符串，而非原始 ADF 对象；HTML 表格需遵循该工具的 getContentFormatGuide（针对 addOrEditJiraIssueComment），仅当指南支持所需表格结构与格式时使用 HTML。Markdown 回退时，表格单元格为一行，每个 bug 一行，单元格各部分用 / 连接，不使用嵌套列表或单元格内换行；格式丢失时告知用户。若用户明确要求 ADF 且无工具接受，则返回 ADF 草稿而非发布 Markdown。

适用场景

适用于需要为 Jira 缺陷工单生成结构化修复评审摘要的团队协作场景，尤其是希望将代码变更与工单描述对照、记录验证状态、维护更新历史并发布到工单评论的工作流。

限制

  • 该技能依赖可用的 Jira 工具与仓库访问；工具名称因代理而异，需使用已配置的等效工具，不能假定固定 MCP 命名空间或 shell 工具名。
  • 仅代码检查不能确立运行时正确性或完整验收；未实际运行或报告的测试不能标记为已测试。
  • 不推断未知的版本列表、契约或未检查的调用方影响。
  • 评论正文格式受实际工具支持能力限制；格式丢失时需告知用户。
  • 发布需明确授权；未授权时仅输出草稿。