Deveco Autobugfix

---
name: deveco-autobugfix
description: >
  自动执行鸿蒙应用 Bug 全流程修复，涵盖问题复现、根因分析、最小化代码修复、构建编译与运行验证。
  依赖 deveco-mcp 提供 verify_ui/build_project/start_app 等能力。
  使用场景：用户要求自动修复鸿蒙项目 Bug，或输入触发词：自动修复、auto fix、auto-fix、自动bug修复、autofix。
  提供熔断保护、3 次构建重试上限、修复经验沉淀机制。
license: MIT
metadata:
  author: harmonyos-dev-skills
  version: "1.0.0"
  created: "2026-05-06"
  keywords: ["bug-fix", "auto-fix", "deveco", "harmonyos", "mcp"]
compatibility: >
  需安装并正常连接 @deveco-codegenie/mcp；
  verify_ui 工具执行较慢，MCP 客户端需配置 ≥600000ms（600 秒）超时。
---

# 自动 Bug 修复

## 前置条件

本工作流依赖 `deveco-mcp` 提供构建、运行、UI验证等能力。使用前请确保：

1. 已正确安装 `@deveco-codegenie/mcp` 包
2. MCP 服务已配置并正常连接
3. MCP 工具超时配置：`verify_ui` 工具执行时间较长，在 MCP 配置时设置足够的超时时间
   - 推荐超时设置：至少 600 秒（600000ms）或更长
   - 如果遇到 "request timed out" 错误，说明 MCP 超时时间设置不足

安装与配置参考文档：https://www.npmjs.com/package/@deveco-codegenie/mcp

---

## 工作流

### 总则

- **全程自动执行，禁止中途等待或询问用户**
- 所有 UI 验证统一使用 `verify_ui`；若 `verify_ui` 完全不可用，全流程退回 `perform_ui_action`

### 阶段决策树

```text
阶段二 → 是否定位根因？
  ├─ 是 → 阶段三
  └─ 否 → 熔断，输出失败报告（终止阶段=阶段二）

阶段四 → 编译是否通过？
  ├─ 通过 → 阶段五
  ├─ 失败且重试次数 < 3 → 修复后重试
  └─ 失败且重试 ≥ 3 或重复错误 → 熔断，回滚改动（git checkout -- .）

阶段五 → verify_ui 是否成功？
  ├─ 是 → 阶段六
  └─ 否 → 回到阶段二
```

### 阶段零：源码与依赖准备

**在任何代码分析之前执行**，确保目标源码和依赖可用。

1. 根据任务描述判断可能涉及的模块/目录
2. 若项目存在子模块或外部依赖，先同步拉取源码（如 `git submodule update --init` 或项目特定的同步命令）
3. 确认目标源码目录存在且非空后，继续阶段一

> 若源码同步失败，立即终止并输出失败报告，不得继续。

### 阶段一：问题复现（不看代码）

1. 若问题涉及可运行的应用，且环境支持自动化测试：
   - 调用 `deveco-mcp` 的 `verify_ui` 工具，根据问题描述编写测试计划，自动执行复现步骤
   - `verify_ui` 会自动启动应用、执行操作、截图并验证，是问题复现的标准工具
   - 若需分析日志，调用 `get_ui_verification_log` 获取运行日志
   - 若需查看每步截图，调用 `save_ui_screenshot` 保存验证过程的截图
2. 若无法自动复现（无运行环境、无账号、纯逻辑问题等）：
   - 记录无法复现的原因
   - 结合用户提供的信息（截图、日志、堆栈）继续后续分析

注意：
1. 若 `verify_ui` 复现失败，先查看每步截图诊断原因（工具缺乏 APP 使用知识、未按问题描述执行步骤等），据此调整测试计划后重新调用
2. 如果存在较细微的 UI 组件问题，运行到目标页面后，使用 `deveco-mcp` 的 `get_app_ui_tree` 工具查看当前页面的组件信息
3. 如果没有提供账号，不要编造账号

### 阶段二：分析定位（只读，不改代码）

1. **检索经验**：在项目记忆文件中搜索关键词（模块名、错误信息、功能名）。仅阅读命中段落，不读取整个文件
2. **判断范围**：
   - 用户指定了路径 → 直接定位
   - 用户未指定路径 → 根据问题关键词在项目目录下搜索相关代码
   - 若子模块存在独立的规范目录，优先查阅
3. 分析错误信息（日志/截图/堆栈），明确复现条件和预期行为
4. 定位源码，追踪调用链；检查模块注册表、路由配置、服务声明等元数据文件
5. 根因分析：区分中间件误用、生命周期问题、平台 API 问题、数据流异常等
6. 简要输出分析结论（根因、关键文件、修复思路），然后**直接进入下一阶段**

**熔断**：若无法定位根因（信息不足、无法复现、涉及多模块联动无法确定），立即终止并输出失败报告，不得猜测性修复。

### 阶段三：编码修复

1. 阅读相关规范：必读项目内的代码风格规范文件；按需读取中间件使用规范、UI 组件规范等
2. **最小修复原则**——仅改与 bug 直接相关的代码，不做额外重构
3. 验证修复覆盖所有复现路径，检查是否引入新问题

### 阶段四：构建验证

调用 `deveco-mcp` 的 `build_project` 工具编译整个工程。若编译失败，根据错误信息修复后重新编译。

注意：
- `build_project` 仅编译生成 HAP 文件，不会自动安装到设备
- 构建成功后，必须调用 `start_app` 才能安装运行

**保护机制**：
- **最多重试 3 次**：超过 3 次编译仍失败则终止
- **重复错误检测**：若连续两次出现相同错误信息，说明修复方向有误，立即终止
- 终止时回退所有改动（如 `git checkout -- .`），输出失败报告

### 阶段五：运行验证


验证流程：
1. 调用 `deveco-mcp` 的 `start_app` 工具将新构建的包安装到设备并启动应用
2. 调用 `deveco-mcp` 的 `verify_ui` 工具进行功能验证：
   - 使用与阶段一相同或相似的测试计划
   - 测试计划应包含修复后的预期结果验证，确保问题修复，且没有引入新问题。
   - 如果存在问题，返回“阶段二：分析定位”重新修复
3. 如果 verify_ui 验证成功，说明修复有效，继续阶段六；如果 verify_ui 验证失败，返回“阶段二：分析定位”重新分析和修复

注意：
- 不要跳过 verify_ui 直接人工判断修复效果

### 阶段六：经验沉淀

修复完成后，判断是否值得沉淀：
- **追加**：非显而易见的根因、易踩的坑、涉及框架/中间件特殊行为、多人可能遇到的问题
- **跳过**：简单拼写错误、明显的逻辑疏忽、一次性配置问题等简单问题

需要追加时，将经验写入项目的记忆文件，格式参考：

```markdown
## [模块名] 简短标题

- **现象**: 用户看到的问题表现
- **根因**: 问题的根本原因
- **修复方案**: 具体的修复方法和关键代码变更
- **关键文件**: 涉及的核心文件路径
- **日期**: YYYY-MM-DD
```

## 修复完成前自检清单

### Critical（必须全部满足，否则视为修复未完成）
- [ ] 阶段四 `build_project` 编译通过
- [ ] 阶段五 `verify_ui` 验证通过
- [ ] 修改限于 bug 直接相关代码，无附加重构
- [ ] 项目记忆文件中已搜索过相关关键词

### Warning（建议满足）
- [ ] 复现路径全部覆盖，无遗漏
- [ ] 已查阅项目代码风格规范
- [ ] 检查是否引入回归（其他功能未受影响）

### Info（可选）
- [ ] 经验沉淀文件已根据阶段六判定更新
- [ ] 修改涉及的关键文件路径已记录

## 失败报告格式

任何阶段触发熔断时，输出以下结构化报告后终止：

```
## 自动修复失败

- **问题描述**: {原始问题}
- **终止阶段**: {阶段零/阶段一/阶段二/阶段三/阶段四/阶段五}
- **终止原因**: {无法定位根因 / 编译重试超限 / 重复错误 / 无法复现}
- **已尝试**: {已执行的修复操作，若有}
- **残留状态**: 已回退所有改动 / 无改动
- **建议**: {人工排查方向}
```