bug-patrol

name	bug-patrol
description	Bug 排查追踪系统。管理离散的 bug 排查会话，记录排查范围、发现和进度，避免依赖记忆追踪排查状态。
user-invocable	true

Bug Patrol — 排查追踪系统

功能定位

这是一个元级别的排查追踪工具，不是调试单个 bug 的方法论（那是 debug-guide 的职责）。

它解决的问题：

• 用户做离散的 bug 排查，需要精确记录"查过哪里、发现了什么"
• 跨会话（跨 AI 对话）保持排查进度的连续性
• 提供全局视角：哪些功能区域已排查、哪些未排查、哪些有已知问题

两种排查模式

模式 A：问题驱动排查（主要模式）

用户察觉到某个地方有问题，描述现象，AI 去排查定位。这是最常用的模式。

模式 B：系统性巡查（次要模式）

用户选择一个功能区域，AI 按检查点逐项排查。用于主动发现潜在问题。

文件位置

• 主追踪文件：00_bug-patrol/TRACKER.md
• 会话记录目录：00_bug-patrol/sessions/
• 功能区域地图：references/area-map.md

触发方式

用户说以下类似的话时触发：

• 问题驱动："XX 有问题"、"我发现 XX 不对"、"XX 功能好像有 bug"
• 系统巡查："开始排查"、"bug patrol"、"巡查 R1.2"
• 查看状态："排查进度"、"排查状态"、"哪些还没查"
• 结束会话："结束排查"、"收工"

---

模式 A：问题驱动排查

启动流程

触发：用户描述一个问题现象（如"代理请求偶尔超时"、"token 刷新有时候失败"）

执行步骤：

1. 读取追踪文件 00_bug-patrol/TRACKER.md
2. 执行 git rev-parse --short HEAD 获取当前 commit SHA
3. 根据用户描述的问题，判断涉及的功能区域（对照 references/area-map.md）
4. 向用户确认理解：
   • 复述问题现象
   • 说明将要排查的区域和核心文件
   • 询问是否有补充信息（复现条件、频率等）
5. 用户确认后，在 00_bug-patrol/sessions/ 创建会话文件

排查过程

1. 读取相关代码：根据问题现象，读取涉及的核心文件
2. 追踪执行路径：从用户描述的触发点出发，沿代码执行路径追踪
3. 定位可疑点：重点关注：
   • 与问题现象直接相关的逻辑分支
   • 异步回调的时序问题
   • 状态变更的一致性
   • 边界条件处理
   • 最近 commit 中修改过的相关代码
4. 逐步汇报：每排查一个文件/模块，向用户汇报发现：
   • 这段代码做了什么
   • 是否有可疑之处
   • 需要继续追踪的线索
5. 记录发现：将排查过程和发现记录到会话文件

排查结论

排查结束时，给出结论：

• 情况 1：通过代码审查定位到根因

  • 记录根因分析
  • 记录到 TRACKER.md 问题清单
  • 提示用户：如需修复，可启动 debug-guide 流程

• 情况 2：代码审查无法确定，需要运行时验证

  • 记录可疑点和排查思路
  • 标记为"待确认"
  • 提示用户：需要加调试日志验证，可启动 debug-guide 流程

• 情况 3：未发现问题

  • 记录排查范围和结论
  • 建议可能需要扩大排查范围或提供更多复现信息

会话文件格式（问题驱动）

文件命名：YYYY-MM-DD_问题关键词.md（如 2026-02-22_token刷新失败.md）

# 问题排查：[问题简述]

- 日期：YYYY-MM-DD
- 基线 commit：`SHA` (commit message)
- 问题描述：[用户原始描述]
- 涉及区域：[区域编号] [区域名]

## 排查过程

### 1. [排查的第一个文件/模块]

文件：`路径`

[排查内容和发现]

### 2. [排查的第二个文件/模块]

文件：`路径`

[排查内容和发现]

## 发现

- 🐛 [P1] [问题描述] — 已确认 / 待确认
- ⚠️ [P2] [问题描述] — 待确认

## 根因分析

[根因分析，或"需要运行时验证"的说明]

## 结论

[总结和后续建议]

---

模式 B：系统性巡查

启动流程

触发词："开始排查"、"bug patrol"、"巡查 [区域编号]"

执行步骤：

1. 读取追踪文件 00_bug-patrol/TRACKER.md（不存在则初始化）
2. 读取功能区域地图 references/area-map.md
3. 执行 git rev-parse --short HEAD 获取当前 commit SHA
4. 变更检测：如果 TRACKER.md 中记录了上次排查的基线 commit，执行 git diff --name-only <上次基线>..HEAD 找出变更文件，将涉及的已排查区域标记为 🔄 需复查
5. 展示当前排查状态摘要
6. 建议优先排查方向（高风险 + 未排查 > 需复查 > 中风险 + 未排查）
7. 用户选择区域后，创建会话文件

排查过程

1. 读取目标区域的核心文件
2. 按 area-map 中的检查点逐项引导
3. 主动提示关注：
   • 边界条件（空值、极端输入、集合为空）
   • 异步时序（回调顺序、竞态条件、取消处理）
   • 状态一致性（多处状态是否同步、状态转换是否完整）
   • 错误处理（unwrap 使用、Result 传播、panic 风险）
4. 发现问题时：
   • 只记录，不修复
   • 标记严重程度（P0-P3）和确认状态
5. 每个检查点排查完后记录结果

会话文件格式（系统巡查）

文件命名：YYYY-MM-DD_区域编号_区域名.md（如 2026-02-22_R1.1_Token管理.md）

# 系统巡查：[区域编号] [区域名]

- 日期：YYYY-MM-DD
- 基线 commit：`SHA` (commit message)
- 排查区域：[区域编号] [区域名]
- 核心文件：（从 area-map 复制）

## 排查过程

### 检查：[检查点名称]

文件：`路径`

- ✅ [正常项描述]
- ⚠️ [P2] [问题描述] — 待确认
- 🐛 [P1] [问题描述] — 已确认

## 发现

（汇总所有问题）

## 结论

（区域质量评估）

---

通用命令

结束排查会话

触发词："结束排查"、"排查结束"、"收工"

执行步骤：

1. 汇总本次会话的排查成果
2. 补全会话文件的"发现"和"结论"部分
3. 更新 00_bug-patrol/TRACKER.md：
   • 更新涉及区域的排查状态
   • 将新发现的问题添加到问题清单
   • 在会话索引中添加本次会话的链接
4. 展示更新后的全局进度摘要
5. 所有文件更新必须先展示内容，等待用户确认后写入

查看排查状态

触发词："排查进度"、"排查状态"、"哪些还没查"

执行步骤：

1. 读取 00_bug-patrol/TRACKER.md
2. 展示全局排查进度（各区域状态，按风险等级分组）
3. 展示未修复问题清单（按严重程度排序）
4. 建议下一步排查方向

---

与 debug-guide 的协作

• bug-patrol 负责"发现问题"和"记录问题"（通过代码审查）
• debug-guide 负责"调试问题"和"修复问题"（通过运行时日志）
• 排查中发现 bug 只记录，不启动修复流程
• 当代码审查无法确定根因、需要运行时验证时，提示用户可切换到 debug-guide
• 用户决定修复某个问题时，切换到 debug-guide 流程
• 修复完成后，回到 TRACKER.md 更新问题状态：
  • 将问题从"已发现问题"移到"已修复问题"
  • 记录修复 commit SHA

文件更新规范

• 所有对追踪文件和会话文件的修改，必须先展示变更内容，等待用户确认后写入（遵循 protocol-dev 的"先谋后动"原则）
• TRACKER.md 的进度总览和问题清单是可更新的；会话索引是 append-only 的
• 会话文件创建后，排查过程中持续追加内容
• 不要删除历史会话记录