Yunxiao Bug Fix

云效 Bug 处理通用技能

概述

本 Skill 定义了一套基于云效 MCP 的标准化 Bug 处理流程。提供可复用的工具调用流程、参数规范和输出格式。

前置条件

• 已配置云效 MCP 服务器（mcp_aliyun_yunxiao）
• 具有云效项目的访问权限
• 需要动态获取的环境信息：
  • organizationId（通过 mcp_aliyun_yunxiao_get_current_organization_info 获取）
  • userId（同上）
  • projectId（从链接提取或通过 mcp_aliyun_yunxiao_search_projects 获取）

执行流程

步骤 1: 环境初始化

每次开始前必须先获取用户和组织信息：

工具调用：

mcp_aliyun_yunxiao_get_current_organization_info()
// 返回: { organizationId, userId, ... }

可选调用（需要查找项目时）：

mcp_aliyun_yunxiao_search_projects({ 
  organizationId, 
  scenarioFilter: "participate" // 或 "manage", "favorite"
})

流程分支判断：

• 场景 A：用户提供具体 Bug 链接 → 从链接提取 Bug ID → 跳转到步骤 2.5（展示确认）
• 场景 B：用户模糊请求（如"我的Bug"） → 执行步骤 2（搜索）→ 步骤 2.5（展示列表）

步骤 2: 搜索工作项（仅场景 B）

工具调用： mcp_aliyun_yunxiao_search_workitems

关键词智能映射： 根据用户的自然语言自动构建查询参数：

必填参数：

{
  "organizationId": "<从步骤1获取>",
  "category": "Bug",
  "spaceId": "<projectId>"
}

常用过滤参数：

最佳实践：

• ✅ 默认使用 statusStage: "1,2" 排除已关闭项
• ✅ 始终启用 includeDetails: true 避免 N+1 查询
• ✅ 大数据量时使用分页

步骤 2.5: 展示Bug信息并等待用户确认（必须）

⚠️ 关键步骤：获取到Bug信息后，必须先展示给用户确认，不要直接开始修复！

场景 1：搜索后展示列表

## 🐛 你的待处理 Bug（共 X 个）

### TXRP-592 - [Bug标题]
**优先级：** [高/中/低] | **状态：** [状态名称] | **指派给：** [指派人姓名]

**问题描述：**
[从工作项获取的完整描述内容]

**截图：** [查看截图](链接)（如果有）

---

**请选择要修复的Bug：**
- 回复Bug编号（如 "TXRP-592" 或 "修复 TXRP-592"）开始修复
- 或告诉我你想先看哪个Bug的详细信息

场景 2：直接链接后展示确认

## 🐛 Bug 详情

**Bug ID:** [工作项ID]
**标题:** [Bug标题]
**状态:** [状态名称] | **优先级:** [高/中/低]
**指派给:** [指派人姓名] | **创建者:** [创建者姓名] | **验证者:** [验证者姓名]

**问题描述：**
[从工作项获取的完整描述内容]

**截图：** [查看截图](下载链接)（如果有）

**评论：** （如果有）
- **[评论人]** ([日期])：[评论内容]

---

**是否开始修复此 Bug？**
- 回复 **"开始修复"** 或 **"确认"** → 开始分析和修复
- 回复 **"取消"** → 不处理此 Bug

只有在用户明确确认后，才能继续步骤3。

步骤 3: 获取详情与上下文（针对用户确认的Bug）

⚠️ 前置条件：用户已确认要修复此 Bug。此步骤所有子步骤必须依次完整执行，不可跳过！

① 获取工作项详情（必须）：

mcp_aliyun_yunxiao_get_work_item({ organizationId, workItemId })

② 获取评论列表（必须）：

mcp_aliyun_yunxiao_list_work_item_comments({ organizationId, workItemId })

③ 获取附件列表（必须）：

mcp_aliyun_yunxiao_list_workitem_attachments({ organizationId, workItemId })

④ 下载并查看截图（必须）：

mcp_aliyun_yunxiao_get_workitem_file({ organizationId, workitemId, id })
// 返回临时下载链接，必须 curl 下载到本地后才能查看

• ❗ 截图附件包含关键的 UI 问题信息，必须查看，不可跳过
• ❗ 附件链接不能直接访问，必须 curl 下载到本地后再查看
• ❗ 即使 Bug 描述文字已清晰，也必须查看截图
• 如果确实没有附件，记录"无附件"后继续步骤 4

⚠️ 完成以上全部 ① ② ③ ④ 步骤后，才能进入步骤 4！

步骤 4: 代码定位

根据 Bug 信息定位相关代码：

1. 关键词搜索： 使用 grepSearch 搜索标题/描述中的关键词
2. 路径推断： 根据功能模块推断可能的文件路径
3. Git 历史： 查看相关功能的最近修改记录
4. 询问用户： 无法定位时请求用户提供线索

步骤 5: 分析与修复

输出格式规范：

**涉及文件：** `path/to/file`

**问题代码（行号）：**
\```language
// 有问题的代码片段
\```

**问题描述：** 
解释为什么会导致 Bug，包括逻辑错误、边界条件等。

**修复方案表格：**
| 涉及模块 | 代码问题 | 方案 | 手动验证步骤 |
|---------|---------|------|------------|
| 模块路径 | 问题简述 | 修复方法 | 1. 步骤1<br>2. 步骤2<br>3. 预期结果 |

**修复类型：** ✅ 纯前端修复 / ⚠️ 需要后端配合

⚠️ 修复代码后，必须执行步骤 6 的用户确认流程，不要自动更新云效！

步骤 6: 用户确认（必须）

⚠️ 关键步骤：修复代码后必须等待用户明确确认，不要自动更新云效！

修复完成后，向用户展示修复内容并询问：

✅ 代码已修复完成

**修复内容：**
- [列出修改的文件和关键改动]

**验证步骤：**
1. [操作步骤1]
2. [操作步骤2]
3. [预期结果]

---

**请确认是否完成修复？**
- 回复 **"确认"** → 我将更新云效状态为"开发完成"并添加修复评论
- 回复 **"需要调整"** → 我将重新修复
- 回复 **"仅更新代码"** → 不更新云效，仅保留代码修改

用户回复处理：

• "确认" / "可以" / "没问题" → 执行步骤 7
• "需要调整" / 提出修改意见 → 返回步骤 5 重新修复
• "仅更新代码" / "不更新云效" → 跳过步骤 7，流程结束

步骤 7: 更新云效状态与评论（需用户确认）

⚠️ 此步骤仅在用户明确确认后执行

更新工作项：

// 1. 先读取当前状态
const workItem = await mcp_aliyun_yunxiao_get_work_item({ organizationId, workItemId })

// 2. 更新字段（只更新需要改的字段）
mcp_aliyun_yunxiao_update_work_item({
  organizationId,
  workItemId,
  updateWorkItemFields: {
    status: "<新状态ID>",
  }
})

添加评论：

mcp_aliyun_yunxiao_create_work_item_comment({
  organizationId,
  workItemId,
  content: "Markdown 格式的评论内容"
})

状态 ID 获取（自动容错）：

1. 动态查询：调用 mcp_aliyun_yunxiao_get_work_item_workflow 查询实际状态流
2. 自动容错：若状态 ID 更新失败，重新查询并重试
3. 动态适配：使用查询到的实际状态 ID 进行更新

常见状态 ID 参考：

注意：状态 ID 可能因项目而异，建议使用动态查询。

步骤 8: 验证与记录

• 运行相关测试验证修复效果
• 确认云效状态已更新
• 确认评论已成功添加

输出规范

Bug 列表输出格式

## 🐛 Bug 列表（共 X 个）

### PROJ-123 - 问题标题 优先级(高)

**问题内容：** 简要描述

**截图：** [链接]（如果有）

**评论：** 
- **评论人** (日期)：评论内容

---

评论内容格式

默认评论模版：

✅ 已修复 | ⏱️ 修复时间：YYYY-MM-DD HH:mm
❗ 感谢测试同学 @{验证者姓名} 精准报 Bug，定位准确，帮助快速修复！
⭐ 测试人，YYDS！每一个被你点亮的缺陷，都是产品进步的台阶。

**⬇️ 验证步骤**
1. [操作步骤1]
2. [操作步骤2]
3. [预期结果]

**⚠️ 问题原因**
[详细描述导致 Bug 的根本原因]

**⚡ 修复方案**
- [修复点1：具体的代码修改说明]
- [修复点2：具体的代码修改说明]

**➡️ 涉及文件**
`path/to/file1.vue`

最佳实践

必须遵守

• ✅ 所有 ID 必须动态获取，绝不硬编码
• ✅ 默认使用 statusStage: "1,2" 排除已关闭项
• ✅ 使用 includeDetails: true 避免 N+1 查询
• ✅ 获取到Bug信息后，必须先展示给用户确认
• ✅ 用户确认后，必须完整执行步骤3全部子步骤
• ✅ 附件截图必须 curl 下载到本地查看
• ✅ 修复代码后必须等待用户确认
• ✅ 更新前先读取当前状态
• ✅ 状态 ID 更新失败时，自动查询 workflow 并重试

避免做法

• ❌ 硬编码 organizationId、projectId、状态 ID
• ❌ 获取到Bug信息后直接开始修复
• ❌ 用户确认后跳过步骤3
• ❌ 跳过截图查看步骤
• ❌ 通过 URL 直接访问截图
• ❌ 修复代码后未经确认就自动更新云效

工具参考

本 Skill 使用的云效 MCP 工具（前缀 mcp_aliyun_yunxiao_）：

• get_current_organization_info - 获取当前组织信息
• search_projects - 搜索项目
• search_workitems - 搜索工作项
• get_work_item - 获取工作项详情
• update_work_item - 更新工作项
• list_work_item_comments - 获取评论列表
• create_work_item_comment - 创建评论
• list_workitem_attachments - 获取附件列表
• get_workitem_file - 获取附件文件
• get_work_item_workflow - 获取工作流状态

扩展资源

需要更详细的示例和高级用法，请查看：

• references/工作流示例.md - 真实场景示例
• references/状态映射指南.md - 状态 ID 映射指南
• scripts/download-screenshot.sh - 截图下载脚本