自动修复

---

一、功能概述

「自动修复」是 Bugly 推出的智能化质量提升能力，通过 AI 自动发现、分析、修复崩溃问题，并生成代码 MR（Merge Request），将开发者的人力投入降至最低——整个流程仅需两次人工确认：

1. 确认修复计划：审核 AI 的修复方案是否合理
2. 代码 CR（Code Review）：审核 AI 生成的修复代码

从而实现应用稳定性的规模化提升。

核心价值

• 规模化降低崩溃率：批量高效解决多类型问题，有限资源下提升整体稳定性
• 防患于未然：提前修复低频问题，避免突变为高频故障
• 极致降低人力成本：自动完成发现、分类、修复、MR 提交
• 智能决策支持：修复计划附带影响范围、风险评估、收益分析等上下文

---

二、适用场景

场景	说明	典型时机
新版本新增问题	新版本发布后，自动识别所有新增崩溃问题（Top + 长尾），快速批量处理	新版本发布后
指标告警应急修复	崩溃率/ANR率触发告警后，自动识别导致指标劣化的 Top 问题	告警触发时
历史长尾问题清理	定期扫描历史积压的长尾问题，优先修复低风险、高性价比的问题	每周/每月定期
开发版日常新增	开发版每日构建后，识别内部测试阶段发现的问题	每日构建后

当前版本支持

当前版本（MVP）聚焦「新版本发布后新增问题」场景，后续将逐步支持其他场景。

---

三、核心流程

整个自动修复流程分为以下几个阶段：

自动发现（圈定问题） → 本地分析（分析根因） → 确认计划（人工审核） → 本地修复（提交 MR） → 追踪效果（MR 状态）

flowchart LR
    A[自动发现<br/>圈定问题] --> B[本地分析<br/>分析根因]
    B --> C[确认计划<br/>人工审核]
    C --> D[本地修复<br/>提交 MR]
    D --> E[追踪效果<br/>MR 状态]

3.1 自动发现问题

Bugly 云端服务通过定时任务（每天执行），自动识别新版本的新增崩溃问题，并生成「自动修复报告」。

• 无需人工干预，系统自动圈定值得分析的问题
• 新版本发布后自动触发，持续监控新增问题

发现问题

当前版本开放了「新版本发布后新增问题」场景，后续将逐步开放其他问题发现场景。

3.2 本地分析（AI 生成修复方案）

系统圈定问题后，开发者通过 本地工具 对问题逐一进行 AI 分析：

• 根因分析：定位崩溃的直接原因
• 价值评估：评估修复的收益和优先级
• 修复方案：生成具体的修复逻辑
• 风险评估：评估修复可能引入的副作用
• 修复建议：判断是否推荐自动修复

开发者只需通过一句简单的命令即可启动对整个修复报告的本地分析，分析结果会自动同步到 Bugly 平台。

3.3 用户确认修复计划

分析结束后，开发者可以前往 Bugly Web 管理端查看「自动修复报告」：

• 审核 AI 生成的修复方案
• 批量选择要执行修复的问题
• 支持逐个查看详情后单独确认

3.4 本地修复（自动执行修复并提交 MR）

用户确认修复计划后，通过本地工具一键开启自动修复流程：

• 自动创建修复分支
• 生成修复代码
• 执行编译检查
• 自动提交代码并 push 到远端
• 自动发起 MR（一个问题对应一个独立 MR）

3.5 追踪 MR 状态

系统持续追踪所有已提交 MR 的合入情况：

• 待审核：MR 已提交，等待代码审核
• 已合入：MR 审核通过，修复完成
• 已拒绝：MR 被拒绝，需重新处理

---

四、使用指引

4.1 报告列表页

在 Bugly 管理端，进入 设置 → 自动修复 即可使用。页面展示所有历史报告的列表，每条报告对应一次自动修复任务，点击「查看报告」进入报告详情页。

系统在检测到新版本发布后，自动生成修复报告，并在后续 7 天内每日刷新，持续纳入新增问题。报告中各问题的分析进展与修复状态（方案生成、确认、执行、MR 提交等）均实时更新。

---

4.2 报告详情页

报告详情页展示该版本所有新增问题的修复进展，是日常使用的核心页面。

4.2.1 报告概要区

顶部展示报告的基本信息：

• 标签：报告类型（AI 自动修复报告）及当前状态（如「进行中」）
• 报告标题：格式为 {版本号}新增问题自动修复报告
• 报告 ID / APP 版本 / APP 版本发布时间 / 新增问题总数
• 操作按钮：刷新、分享、导出报告

4.2.2 问题状态流转

概要区下方通过状态卡片展示各阶段的问题数量，直观呈现整体修复进度。每张卡片代表问题流转的一个阶段：

卡片	说明	子状态	操作
🔄 待生成修复计划	问题已被圈定，等待执行本地分析	待分析、分析中、需本地分析、失败	—
⏳ 待确认修复计划	AI 分析完成且置信度较高，推荐自动修复，等待用户审核确认	—	立即审核
👷 建议人工修复	AI 分析完成但置信度较低或风险较高，建议开发者人工处理	—	查看原因
✅ 自动修复	用户已确认修复计划的问题	已合入、执行中、待评审、被拒绝、修复失败	—
🚫 已忽略	用户主动忽略的问题，不再参与本次自动修复流程	—	—

一个问题被系统发现后，会按以下路径流转：

flowchart TD
    A[问题被发现] --> B[待生成修复计划]
    B -->|执行本地分析| C{分析结果}
    C -->|置信度高| D[待确认修复计划]
    C -->|置信度低/风险高| E[建议人工修复]
    D -->|用户确认修复| F[自动修复]
    E -->|用户强制修复| F
    F -->|执行本地修复| G[执行中/MR已提交]

流转说明：

1. 待生成修复计划：问题刚被系统圈定，尚未执行分析。开发者需通过本地工具（report-analyze）启动分析。
2. 分析完成后自动分流：
   • 置信度高 → 转入「待确认修复计划」，推荐自动修复
   • 置信度低 / 风险高 → 转入「建议人工修复」，由开发者自行判断
3. 待确认修复计划：这是开发者核心决策环节——审核 AI 的修复方案，决定是否执行修复。
4. 自动修复：用户确认修复计划后，问题转入此状态。但此时修复并未真正执行，开发者还需通过本地工具（report-repair）启动修复。

重要说明

• 只有分析完成后，系统才能判断一个问题属于「待确认修复计划」还是「建议人工修复」
• 只有用户确认了修复计划的问题，本地修复命令才会对其执行修复。未确认的问题不会被修复
• 本地修复需要在本地执行的原因是：代码在本地，没有代码无法执行修复（当前暂未对外开放云端修复能力）

4.2.3 确认修复计划（核心操作）

点击「待确认修复计划」卡片或 Tab 后，进入该状态的问题列表：

列表功能说明：

• 搜索与筛选：支持按 Issue ID/名称搜索，按问题类型、首次出现版本等条件筛选
• 批量选择：列表左侧提供复选框，可勾选需要修复的问题（默认全选）
• 查看详情：点击任意问题行可查看 AI 的分析详情（根因分析、修复方案、风险评估）
• 确认修复：勾选问题后，点击底部「确认修复」按钮提交
• 忽略：点击「忽略」按钮，问题移入「已忽略」列表，不再参与本次修复流程

确认后，问题状态转为「自动修复」。开发者需使用本地工具执行修复（参见 4.5 本地修复）。

4.2.4 建议人工修复的问题

对于 AI 评估置信度低或风险较高的问题，系统将其归入「建议人工修复」。开发者可选择：

操作	说明
强制修复	忽略风险提示，确认修复计划后通过本地工具执行修复
登记 MR	人工修复后，手动提供 MR 链接，接入自动化追踪流程

规划中

「登记 MR」功能即将上线——届时人工提交的 MR 也可接入统一的修复流程，自动追踪 MR 状态与修复效果。

开发者介入成本低

无论是本地分析还是本地修复，开发者只需启动命令并传入报告 ID，本地工具会自动拉取报告中处于相应状态的问题，逐个分析、逐个修复。整个过程无需手动指定具体问题，介入成本极低。

---

4.3 修复详情页

点击问题列表中任意 Issue 的「查看详情」按钮，可进入详情页，查看该问题的完整信息。

4.3.1 基本信息

展示 Issue 的核心数据：Issue ID、关键堆栈、完整堆栈、处理人、上报时间、版本范围、发生次数、影响用户/设备数、当前状态等。

4.3.2 修复方案（当前采纳）

详情页顶部展示当前采纳的修复方案，包含：修复风险等级、修复置信度评分、分析位置、使用模型、根因分析结论、修复方案内容等。

修复方案的显示条件

如果一个问题尚未采纳修复方案，则看不到「修复方案（当前采纳）」这块内容。你需要先从下方的归因分析记录中，选择一条分析并点击「采纳」，才会在此处展示当前采纳的方案。

4.3.3 归因分析记录

同一个 Issue 可能存在多次归因分析记录（多次本地分析、使用不同模型分析等）。所有记录按时间倒序排列，每条记录包含：

• 根因分析：崩溃的直接原因
• 修复方案：具体的修复逻辑
• 风险评估：修复风险等级（低/中/高）
• 修复置信度：AI 对修复方案的信心分数（0-100）
• 是否推荐自动修复：综合评估结果

采纳方案：对比不同分析结论后，点击「采纳此分析」将其设为当前修复方案。采纳后，顶部「修复方案（当前采纳）」模块会同步更新。

重新分析：如果对现有分析不满意，可通过本地工具重新执行一次分析。新分析结果会作为新的记录追加，不会自动替换当前采纳的结论，需用户手动确认采纳。

采纳规则

• 唯一性：同一时间只能采纳一条分析的方案。如果先采纳了分析 #1 的方案，后又切换为采纳分析 #2，则最终生效的是分析 #2 的方案。
• 可更换：在问题未开始执行修复前，可随时切换采纳不同的分析记录。
• 锁定：问题一旦开始执行修复（状态为「执行中」），修复方案将被锁定，不再允许更改。只有在问题未执行时，才允许调整修复方案。

4.3.4 确认执行修复

采纳修复方案后，可以点击「确认执行修复」按钮，提交修复计划。确认后，需通过本地工具执行修复（参见 4.5 本地修复）。

确认提交修复计划后，可以查看 执行任务 和 MR 详情这两块模块的信息来了解修复进度。

---

4.4 本地分析

当报告中的问题状态为「需本地分析」时，需要使用本地工具完成根因分析。本地分析结合本地源码进行更精准的归因，分析结果会自动同步到 Bugly 平台。

4.4.1 工具介绍

Bugly 本地工具以 Skills 的形式提供，核心 Skill 为 bugly-issue-analyze，它是一个问题分析与自动修复的 CLI Agent，支持从根因分析到代码修复的完整闭环。

Skill 目录结构：

bugly-issue-analyze/
├── bugly_agent/        # 核心 Agent 模块
├── cli/                # CLI 命令行模块
├── scripts/
│   └── run.py          # 入口脚本
├── requirements.txt    # Python 依赖
└── SKILL.md            # Skill 描述文件

前提条件：

• 已接入 Bugly 专业版，拥有产品 ID，并向 Bugly 申请开放产品的 AI 权限
• 本地已安装 Python ≥ 3.10
• 安装 CodeBuddy / WorkBuddy / Cursor / Claude Code 等 AI Agent（非必须，没有的话可通过命令行方式使用）
• 如需代码修复，本地需已 clone App 源码（自动修复模式适配 Git 管理的仓库，非 Git 仓库需额外适配）

获取 Token：

1. 登录 Bugly 平台：https://bugly.tds.qq.com
2. 进入个人中心 → Token 管理：https://bugly.tds.qq.com/v2/user/token
3. 生成并复制 Token（有效期 30 天）

4.4.2 安装与认证

安装 Skill：

# 解压并安装依赖
unzip bugly-issue-analyze.zip
cd bugly-issue-analyze
pip3 install -r requirements.txt

安装完成后，在 CodeBuddy / WorkBuddy / Cursor / Claude Code 中将 Skill 目录加入 Skill 列表即可使用。

配置 Token： 通过以下任一方式配置前面获取的 Token：

• 环境变量：export BUGLY_USER_TOKEN=<your_token>
• Secrets 密钥注入（加载 Skill 时自动触发）
• 首次运行时按提示输入，自动缓存到 ~/.bugly_token_cache.json

4.4.3 执行本地分析

方式一：通过 AI Agent 调用（推荐）

在 CodeBuddy 中加载 bugly-issue-analyze skill 后，使用自然语言指令：

使用 bugly-issue-analyze skill 的 report-analyze 命令，分析产品 {product_id} 的报告 {report_id} 中待分析的问题，代码目录为 {code_root}。

方式二：直接命令行调用

# 批量分析：对报告中的问题进行根因分析
python3 scripts/run.py report-analyze \
  --product-id <product_id> \
  --report-id <report_id> \
  --code-root <本地源码目录> \
  --limit 5

参数说明：

参数	说明
--product-id	Bugly 产品 ID（必填）
--report-id	报告 ID（必填）
--code-root	本地源码根目录（必填）
--limit	本次最多处理的问题数量（可选，默认 20）
--model	指定 LLM 模型（可选）

执行结果： 分析完成后，结果自动同步到 Bugly 平台，对应问题状态从「需本地分析」变为「待确认修复计划」，开发者可在报告详情页查看并审核修复方案。

---

4.5 本地修复

当用户在报告详情页确认修复计划后，问题状态变为「待本地修复」，此时需要使用本地工具执行自动修复。本地修复会自动创建分支、生成修复代码并 push 到远端。

4.5.1 执行本地修复

方式一：通过 AI Agent 调用（推荐）

在 CodeBuddy 中加载 bugly-issue-analyze skill 后，使用自然语言指令：

使用 bugly-issue-analyze skill 的 report-repair 命令，修复产品 {product_id} 的报告 {report_id} 中可自动修复的问题，代码目录为 {code_root}。

方式二：直接命令行调用

# 批量修复：对已确认方案的问题执行代码修复
python3 scripts/run.py report-repair \
  --product-id <product_id> \
  --report-id <report_id> \
  --code-root <本地源码目录> \
  --limit 5

参数说明：

参数	说明
--product-id	Bugly 产品 ID（必填）
--report-id	报告 ID（必填）
--code-root	本地源码根目录（必填）
--limit	本次最多处理的问题数量（可选，默认 20）
--include-failed	包含之前修复失败的问题进行重试（可选）
--model	指定 LLM 模型（可选）

执行结果： 修复完成后，本地工具会为每个问题自动创建独立分支、push 到远端并发起 MR。修复状态自动同步到 Bugly 平台。

4.5.2 推荐工作流

完整的本地使用流程如下：

1. report-analyze（批量分析根因 → 输出方案 → 自动同步到平台）
       ↓
2. 在 Bugly 平台审核并确认修复方案
       ↓
3. report-repair（批量执行修复 → 创建分支 → push → 自动发起 MR）
       ↓
4. 代码 CR（Code Review）→ 合入

小贴士

• 建议每次分析/修复时通过 --limit 控制处理数量，避免一次性处理过多问题
• 可使用 --include-failed 参数重试之前修复失败的问题
• 修复过程中如需切换 AI 模型，可通过 --model 参数指定

---

4.6 分析和修复指定问题（plan/apply 模式）

除了批量处理整个报告，本地工具还支持对单个问题进行分析和修复，即 plan（分析）和 apply（修复）模式。适用于开发者想针对某个特定崩溃问题快速定位根因并修复的场景。

4.6.1 分析指定问题（plan 模式）

方式一：通过 AI Agent 调用（推荐）

在 CodeBuddy 中加载 bugly-issue-analyze skill 后，直接用自然语言描述：

请帮我分析一下产品 {产品ID} 的这个崩溃问题 {问题ID}，生成修复方案，代码目录为 {代码目录}。

AI Agent 会自动加载 Skill 并执行 plan 命令进行根因分析，最终输出完整的崩溃根因分析报告和修复方案。

方式二：直接命令行调用

python3 -m cli plan \
  --product-id <product_id> \
  --code-root <本地源码目录> \
  "分析 feature=<issue_id> 的崩溃根因，给出修复方案"

参数说明：

参数	说明
--product-id	Bugly 产品 ID（必填）
--code-root	本地源码根目录（必填）
最后的字符串参数	分析任务描述，需包含 feature=<issue_id>（必填）

执行结果： 工具会自动获取 Issue 详情、下载附件、分析崩溃堆栈、查询根因知识库，最终生成完整的根因分析报告和修复方案，并同步到 Bugly 平台。分析完成后，输出中会给出修复方案的保存路径和可直接复制使用的 apply 命令，例如：

修复方案已保存：/Users/xxx/work/Project/.bugly_plans/plan_DB66A74E_20260612_094746.md
执行修复：python3 -m cli apply --product-id 5511654fcf --code-root . "基于 /Users/xxx/work/Project/.bugly_plans/plan_DB66A74E_20260612_094746.md 中的修复方案执行代码修改"

用户可以直接复制该命令执行修复。

4.6.2 修复指定问题（apply 模式）

在 plan 模式生成修复方案并确认后，可以执行修复。

方式一：通过 AI Agent 调用（推荐）

在 plan 分析完成后，直接告诉 AI Agent：

请用 apply 模式采用这个方案修复一下。

AI Agent 会自动使用分析生成的方案执行代码修复、创建分支并提交 MR。

方式二：直接命令行调用

python3 -m cli apply \
  --product-id <product_id> \
  --code-root <本地源码目录> \
  --allow-path <允许修改的路径> \
  "基于 <修复方案文件路径> 中的修复方案执行代码修改"

其中修复方案文件路径为 plan 模式生成的方案文件，通常位于项目目录下的 .bugly_plans/ 目录中，格式为 plan_<问题ID>_<时间戳>.md。

参数说明：

参数	说明
--product-id	Bugly 产品 ID（必填）
--code-root	本地源码根目录（必填）
--allow-path	限制可修改的路径范围（可选，可重复指定多个路径）
最后的字符串参数	修复任务描述，需指定 plan 模式生成的修复方案文件路径（必填）

执行结果： 工具会基于指定的修复方案文件自动执行代码修复，创建独立分支、push 到远端并发起 MR。

plan/apply 与 report-analyze/report-repair 的区别

• plan/apply：针对单个问题的分析和修复，适合定点排查特定崩溃
• report-analyze/report-repair：针对整个报告的批量分析和修复，适合批量处理新版本新增问题

---

五、问题状态说明

整个自动修复流程中，用户需要参与的关键环节有 4 个：

需用户参与的环节	时机	操作说明
本地分析	问题圈定后	使用本地工具执行 report-analyze
确认修复方案	分析完成后	在 Bugly 平台审核 AI 方案，确认执行（支持批量）
本地修复	确认方案后	使用本地工具执行 report-repair
MR 评审	修复 push 后	在代码仓库进行 Code Review，合入或打回

每个问题在流程中会经历以下状态：

状态	含义	用户需要做什么
新发现	系统刚圈定的问题，还未开始分析	等待系统处理
需本地分析	需要使用本地工具完成分析	使用本地工具执行 report-analyze
分析中	AI 正在生成修复方案	等待分析完成
待确认	修复方案已就绪，等待用户确认	审核方案，确认执行修复
需本地修复	需要使用本地工具完成修复	使用本地工具执行 report-repair
执行中	AI 正在生成修复代码	等待完成
MR 已提交	修复代码已 push 到远端	发起 MR 并进行代码 CR
MR 已合入	修复完成	无需操作
MR 被拒绝	MR 审核未通过	重新修复或手动处理
建议人工修复	AI 评估不推荐自动修复	选择强制修复或人工处理
已忽略	用户主动忽略	如需恢复可「重新激活」

---

六、常见问题

Q1：哪些问题会被自动发现？

当前版本针对新版本发布后的新增崩溃问题，系统每天通过定时任务自动扫描和识别。

Q2：AI 修复的代码可靠吗？

AI 生成的修复方案会附带风险评估和置信度分数。所有修复代码最终都需要通过 MR 的代码审核（CR）才能合入，确保代码质量。

Q3：不信任 AI 的分析结论怎么办？

你可以：

• 使用本地工具结合不同 AI 模型重新分析（通过 --model 参数切换模型）
• 对比多次分析记录，选择「采纳」你认可的结论
• 手动在平台触发「重新分析」

Q4：如何获取 product_id 和 report_id？

• product_id：Bugly 平台页面 URL 中 productId= 后的值
• report_id：在自动修复报告列表页，每个报告都会展示对应的报告 ID

Q5：MR 被拒绝后怎么办？

你可以选择：

• 重新执行修复：通过本地工具重新生成修复代码
• 登记 MR：人工修复后，手动提供 MR 链接接入自动追踪
• 切换到其他归因分析结论后再重试

Q6：常见报错与解决方法

问题	解决方法
提示「未找到 BUGLY_USER_TOKEN」	配置环境变量 export BUGLY_USER_TOKEN=<your_token>
找不到 product-id	Bugly 平台页面 URL 中 productId= 后的值
report-analyze 报错「code_root does not exist」	--code-root 路径不存在，请先 clone 项目源码
report-repair 报错「no git repositories found」	确认 --code-root 目录下有 .git 文件夹
Auto Fix Report 报告为空	该功能需开通，请联系 Bugly 商务申请
Python 版本报错	需要 Python >= 3.10

---

七、关键链接

资源	地址
Bugly 平台	https://bugly.tds.qq.com
获取 Token	https://bugly.tds.qq.com/v2/user/token
Auto Fix Reports	https://bugly.tds.qq.com/v2/setting/auto-fix-reports?productId={product_id}

---

八、联系我们

如果您所在的业务想体验这个功能，或者对功能有任何疑问，欢迎联系我们：Bugly小助手 。