bug-debug-log

name	bug-debug-log
description	Bug 调试记录技能：将调试过程标准化写入 docs/test_book.md，包含问题发现、描述、根因分析、解决方案、效果、知识点与面试问答。触发词：总结这次调试, 总结这个bug, 记录bug, 记录调试, debug log, 写入test_book, 调试记录, log this bug, summarize debug
license	MIT
compatibility	React + TypeScript + Electron 项目，适用于 ImmerseAI 及同类技术栈
metadata	{"author":"qoobee","version":"1.0","project":"ImmerseAI"}

Bug Debug Log Skill

将每次调试过程标准化记录到 docs/test_book.md，形成面向面试展示的技术调试档案。

触发词（任意匹配即激活）：总结这次调试 / 总结这个bug / 记录bug / 记录调试 / debug log / 写入test_book / 调试记录 / log this bug / summarize debug

---

Step 1: 信息收集

从当前对话上下文中提取以下字段。若某字段上下文中已明确，直接使用，不要重复询问。若关键字段缺失，使用 ask_questions 工具补充：

字段	说明	是否必须询问
bug 标题	一句话描述问题	若上下文不明确则询问
严重程度	高 / 中 / 低	必须询问（用户最了解影响范围）
发现方式	如何触发/复现的	若上下文无则询问
是否已完全修复	是 / 部分 / 否	若上下文不明确则询问

询问格式（使用 ask_questions 工具）：

严重程度（此 bug 对用户的影响范围）？
  - 高：核心功能不可用
  - 中：功能受损但有绕过方式
  - 低：视觉/体验问题，不影响功能

修复状态？
  - 已完全修复
  - 部分修复（仍有遗留问题）
  - 尚未修复（仅记录分析）

---

Step 2: 确定记录编号

1. 使用 Read 工具读取 docs/test_book.md
   • 若文件不存在（报错或空），记录编号为 001，标记需要创建文件头
   • 若文件存在，统计其中 ## BUG- 出现的次数，新编号 = 次数 + 1，格式化为三位数（如 002, 010）

---

Step 3: 生成知识点与面试题

根据 bug 涉及的技术领域，自动生成内容。必须覆盖实际 bug 相关的知识域，不得生成与 bug 无关的内容。

技术领域映射参考（根据实际情况选择 2-4 个）：

关键词	对应知识域
useState / 组件卸载 / 重挂载	React 组件生命周期与本地状态
useEffect / 依赖数组 / 闭包	React Hooks 闭包与副作用
Zustand / persist / store	全局状态管理与持久化策略
navigate / router / 路由跳转	React Router 路由机制
IPC / preload / contextBridge	Electron 进程间通信安全模型
Worker / postMessage	Web Worker 与主线程通信
TypeScript / 类型守卫 / unknown	TypeScript 类型系统
async/await / Promise / 竞态	异步编程与竞态条件
useCallback / useMemo / 依赖	React 性能优化

面试题生成要求：

• 2-3 道题，从概念原理和实战场景两个维度出发
• 答案要简洁但完整，面向高级前端/全栈岗位
• 至少 1 道题直接与本次 bug 场景强相关（如"组件重新挂载时如何保留数据？"）

---

Step 4: 写入 docs/test_book.md

4.1 若文件不存在，先写入文件头：

# ImmerseAI Bug 调试记录

> 技术栈：React + TypeScript + Electron | 项目：ImmerseAI
> 本文档记录开发过程中遇到的 bug，包含根因分析、解决方案与面向面试的知识总结。

---

4.2 Append 新记录（严格按以下模板，不得省略任何章节）：

## BUG-{编号}: {标题}

**日期**: {YYYY-MM-DD} | **技术栈**: {涉及技术，如 React / Zustand / Electron} | **严重程度**: {高/中/低} | **状态**: {已修复/部分修复/记录中}

### 问题发现

{描述怎么触发的，具体操作步骤，如："打开书籍后点击返回按钮，书架页面显示空白"}

### 问题描述

{表象是什么，用户视角的感知，不涉及代码}

### 根因分析

{技术层面的根本原因，层层递进说明，可包含代码片段}

```{相关代码片段（可选，选取最能说明问题的部分）}

解决方案

修改文件: {文件路径}

{说明改了什么，为什么这样改}

- {修改前的关键代码}
+ {修改后的关键代码}

解决效果

{修复后的表现；若有遗留问题也在此说明}

---

涉及知识点

{知识点标题} {2-4 句话解释核心概念，要能独立成文，面向不熟悉此概念的读者}

{知识点标题} {同上}

（共 2-4 个知识点）

---

面试问答

Q: {问题}

{标准答案，3-6 句话，包含关键术语}

Q: {问题}

{标准答案}

（共 2-3 道题）

---

### 4.3 写入方式

- 使用 Write 工具时：**先 Read 原文件全部内容，再将原内容 + 新记录合并后整体写入**（因工具不支持原生 append）
- 新记录追加在文件末尾，与上一条记录之间保留一个空行

---

## Step 5: 完成确认

写入完成后，向用户输出：

已将 BUG-{编号} 记录写入 docs/test_book.md

记录摘要：

• 标题：{标题}
• 根因：{一句话}
• 知识点：{知识点标题列表}
• 面试题：{题目列表}

可通过 git diff docs/test_book.md 确认写入内容。

---

## Guardrails

- **NEVER 覆盖历史记录** — 始终 append，不得删除或修改已有的 BUG-* 条目
- **NEVER 省略模板章节** — 即使信息不完整，也要保留章节标题并注明"待补充"
- **ALWAYS 生成知识点和面试题** — 这是本 Skill 的核心价值，不得跳过
- **知识点必须与 bug 相关** — 不得生成套话，每个知识点都要能解释"为什么会有这个 bug"
- **日期取当天** — 使用系统当前日期，格式 YYYY-MM-DD