一个让 AI 真正"教会你"代码的 Skill —— 不是甩给你一段解释，而是从你当前的水平出发，逐行讲清楚每一个概念。
你有没有过这种体验：
- 让 DeepSeek / Claude 写了段代码，能跑，但看不懂
- 问 AI"这段代码什么意思"，得到一堆术语解释术语 —— 更晕了
- 网上搜解释，要么太浅（"这是一个函数"），要么太深（直接上源码分析）
- 同样的概念，每次问都要重新解释一遍
代码学习伴侣就是为这个场景做的。它让 AI 在讲解代码时：
- 先说人话，再讲概念 —— 每行先用大白话说"这行干什么"，再引入术语
- 按你的水平调整深度 —— 不是固定一套讲法，而是 3 档可选
- 长程讲解导出 PDF —— 内容长了不在对话框刷屏，直接给你一份文档
| 模式 | 什么时候用 | 你会得到什么 |
|---|---|---|
🟢 quick |
代码很短（1-3 行），或你只想快速知道干啥用 | 一句话概览 + 每行一句 +（如有）一个坑 |
🟡 standard |
默认。一个函数或一段逻辑（4-30 行） | 完整 5 步：概览 → 逐行 → 为什么 → 常见错误 → 实际应用 |
🔴 deep |
代码复杂、多函数、异步、你想理解设计权衡 | 5 步框架 + 逐行按段分块 + 设计权衡 + 延伸方向 |
模式怎么选：
- 直接说"简短讲""深入讲""只说重点" → 听你的
- 不指定 → 按代码复杂度自动选
- 用户意图优先：30 行代码 + "简短讲" → 依然走
quick - 讲完会问"要不要调整深度"
1. 📋 概览 做什么 + 输入→输出（用比喻）+ 为什么需要
2. 🔍 逐行解释 每行 → 做什么（大白话开头）+ 关键概念 + 为什么
3. 🎯 为什么这样写 好处 + 替代方案 + 性能/最佳实践
4. ⚠️ 常见错误 2-3 个坑，每个含错误代码 + 症状 + 正确方式
5. 💡 实际应用 一个生活场景类比
这是 v2.2 加的核心规则，专门治"AI 用术语解释术语"的毛病：
- ❌ "定义异步函数" → ✅ "先声明一个工具，叫 fetchAndCache，它将来会去取数据"
- 一行有多个新概念 → 拆开讲，别塞进一句话
- 给"如果不写这行会怎样"的对照，帮理解为什么需要
- 首次出现的术语 → 先用比喻定义，再附原术语
- 避免抽象动词（"进行处理""执行操作"）→ 换成具体动作（"取出来""存进去"）
- 数字/符号先翻译成人话：
!res.ok→ "响应不正常（比如 404、500）"
| 你是 | 适不适合 | 说明 |
|---|---|---|
| 跟着 AI 写代码但看不懂生成结果的学习者 | ⭐⭐⭐⭐⭐ | 这就是这个 Skill 的核心受众 |
| 编程新手，正在补基础 | ⭐⭐⭐⭐ | 比喻库 + 大白话原则对零基础友好 |
| 有基础、想理解某段复杂代码的设计 | ⭐⭐⭐⭐ | deep 模式专门做设计权衡分析 |
| 资深开发者，只想要快速确认 | ⭐⭐⭐ | quick 模式够用，但可能觉得讲解偏啰嗦 |
| 纯零基础、连"变量"都不知道 | ⭐⭐ | 比喻能帮上忙，但最好配合系统课程 |
把整个 code-learning-companion 文件夹放到：
~/.workbuddy/skills/code-learning-companion/
下次对话里说类似这些话，Skill 会自动激活：
- "解释这段代码"
- "看不懂这行"
- "DeepSeek 给我写了这段代码，讲讲"
- "深入讲讲这段的设计"
- "简短说下这行干啥"
放到：
~/.claude/skills/code-learning-companion/
用法一样。
讲解过程中随时可以调：
- "太详细了" → 降一档
- "太浅了" → 升一档
- "多用中文术语 / 英文术语" → 调术语密度
- "这个比喻不好懂" → 换一个
长程讲解（deep 模式完成、或你说"导出""生成文档""太长了别在对话框显示"）会自动生成 PDF 文件，不在对话框里贴长文。
触发：
- 走了
deep模式且讲解超过约 60 行 Markdown - 你说"导出""生成 PDF""存成文档""给我一份完整的"
退出（不导出，回到对话框）：
- 你说"直接看""就在这说""不用导出"
quick/standard模式默认不导出（内容短，对话框够用）
对话框里只会看到：
📄 已生成 PDF：代码讲解_async-await.pdf
路径：/Users/you/project/代码讲解_async-await.pdf
内容概览：异步请求函数 fetchUsers 的设计与容错
章节：
1. 概览
2. 逐行讲解
3. 为什么这样设计
4. 常见错误
5. 延伸阅读
技术细节：依赖 fpdf2，中文字体自动探测（Windows 微软雅黑 / Mac PingFang / Linux Noto CJK），支持标题、代码块（灰底等宽）、列表、引用、行内代码、加粗、自动分页。
code-learning-companion/
├── SKILL.md # Skill 主逻辑（模式系统、5步框架、大白话原则、PDF模式）
├── README.md # 你正在看的这个
├── generate_pdf.py # Markdown → PDF 渲染脚本（fpdf2）
├── test_cases.json # 7 个测试用例，覆盖三种模式 + 边界情况
└── LICENSE
| 版本 | 日期 | 改了什么 |
|---|---|---|
| v2.3 | 2026-07-04 | 🆕 长程输出：PDF 文档模式。deep 完成或用户要求"导出"时调 generate_pdf.py 生成带样式 PDF，对话框只给摘要+路径。附退出机制 |
| v2.2 | 2026-07-03 | 🆕 "逐行解释的大白话原则"（6 条），治 AI 用术语解释术语的毛病 |
| v2.1 | 2026-07-03 | 🔧 模式选择冲突仲裁、deep 框架结构、quick 不硬凑坑、比喻库扩充 |
| v2.0 | 2026-07-03 | 🔧 重构：加模式切换、省 token、双平台适配 |
| v1.0 | 2026-06-18 | 🎉 初版，固定 5 步框架，定位零基础 |
这个 Skill 背后有两条信念：
-
讲解不是堆信息，是搭台阶。 同一段代码，对新手和对老手该讲的不一样。固定一套讲法，要么太浅要么太深。所以做了 3 档可调。
-
术语是结果，不是入口。 很多人卡住，不是因为笨，是因为 AI 一上来就甩"Promise 是一个异步操作对象"这种话。先用比喻把画面建立起来，术语自然就挂上去了。所以定了"大白话原则"。
MIT —— 随便用，改了更好用的话欢迎提 PR。