learning-docslisted
Install: claude install-skill XuHenghenglumia/learning-docs
# Learning Docs:技术学习文档生成
生成帮助**用户学习理解**的技术文档网站(docsify)。核心纪律:由浅及深、实例先行、关键事实必须核实。
## 第 0 步:判定模式
- **调研型**:无特定目标项目,针对一个技术主题(如"agent 沙箱实现")做外部调研并讲解。
- **项目讲解型**:用户指定了一个已有项目(本地代码仓库或知名开源项目),目标是让用户读懂它。
无法从上下文判断时,向用户问一次。优先用当前 agent 的提问工具(pi 是 `ask_user`,Claude Code 是 `AskUserQuestion`);没有这类工具就直接在回复里提问。大纲确认同理——用不了交互式提问工具时,把大纲贴在回复里等确认即可。
## 第 1 步:大纲先行(动笔前必须完成)
先列出章节大纲给用户确认,再开始写。大纲使用以下固定骨架:
### 调研型骨架
```
1. 为什么需要 X ← 从具体问题/危险场景切入,不要抽象定义开场
2. 现有实例盘点 ← 真实产品/项目的真实做法,表格总览 + 逐个展开
3. 底层原理拆解 ← 把实例背后的技术逐层剥开,弱→强排列
4. 优劣分析 ← 每种实现能做到什么 vs 牺牲了什么,核心权衡表
5. 理论/本质 ← 数学或第一性原理层面的论述(主题适合时)
6. 总结 ← 异同对照表、选型决策树、原则清单
```
### 项目讲解型骨架
```
1. 这个项目是什么 ← 解决什么问题、给谁用、一句话定位
2. 整体架构与目录导览 ← 模块划分图 + 关键目录/文件的职责说明
3. 开发思路与设计决策 ← 为什么选这些技术/这么分层,权衡了什么
4. 核心流程走读 ← 挑 1~3 条主线流程,带 文件:行号 的代码走读
5. 关键技术原理深挖 ← 项目依赖的核心技术在更基础的层面是怎么回事
6. 如何运行与实验 ← 让用户自己动手验证理解的步骤
7. 总结与延伸阅读 ← 回顾主线 + 推荐进一步材料
```
允许根据主题增删章节,但"实例 → 原理 → 分析 → 总结"的递进顺序保持不变。
## 第 2 步:素材收集
### 调研型
- 用联网检索工具多角度查询(不同 agent 下叫 `web_search` / `WebSearch` / `WebFetch` 等;不同措辞 2~4 组查询),覆盖实例、原理、对比、批评四个面。
- **关键事实必须核实到官方文档或源码层面**。博客/搜索摘要与官方来源冲突时,以官方为准并在文中注明差异。
- 引用来源:文内标注产品名+机制,章末汇总参考链接。
### 项目讲解型
- 通读 README、入口文件、配置、构建脚本,建立地图后再深入。
- 看 git log 找演进脉络(早期 commit 往往揭示设计动机)。
- 跑一遍构建/测试,确认对行为的描述来自实际运行而非猜测。
- 所有结论必须给出 `文件路径:行号` 引用;没读懂的部分明确标注"待确认",禁止编造。
## 第 3 步:写作
写作细则见 [references/writing-style.md](references/writing-style.md)(动笔前读取)。核心规则:
- 由浅及深:每个概念 = 直觉比喻 → 具体例子 → 形式化/源码级定义。
- 实例先行:先展示