| 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: 确定记录编号
- 使用 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
