book-to-skill 使用指南
定位：把技术书 / 文档（PDF、EPUB、DOCX、Markdown、HTML、纯文本、RTF、MOBI）蒸馏成可复用的 Agent Skill —— 提取书里的框架、心智模型、原则、技巧、反模式，而不是做摘要。
- 仓库：
virgiliojr94/book-to-skill（⭐32k，MIT）- 本机状态：已安装
v1.4.0→~/.agents/skills/book-to-skill- 核心价值：回答书里的问题时，比把整本书塞进上下文省 24–51 倍 token
一、它和「做笔记 / 做摘要」有什么不同
| 传统摘要 | book-to-skill | |
|---|---|---|
| 产出 | 一段总结 | 结构化技能：命名框架 + 可执行原则 + 技巧 + 反模式 |
| 用法 | 你自己回头看 | Agent 按需加载（问什么读哪章） |
| 精度 | 容易丢失细节 | 保留作者原话的精确表述（如「5 Whys」不写成「多问几次为什么」） |
| 成本 | 每次要重新喂原文 | 一次蒸馏，长期复用 |
三步走：
1. 指向 —— 给一个文件 / 文件夹 / glob 模式
2. 蒸馏 —— 自动提取结构，生成 SKILL.md + 分章文件
3. 按需加载 —— 之后问 /<书名> 复制策略，Agent 只读相关章节，不幻觉
二、本机安装状态
| 项目 | 状态 |
|---|---|
| 版本 | v1.4.0 |
| 位置 | ~/.agents/skills/book-to-skill（Codex 自动识别） |
| 大小 | 2.0 MB |
| 安全评估 | Snyk Low Risk ✅ |
| 许可 | MIT |
三、支持的格式与依赖现状
| 格式 | 状态 | 说明 |
|---|---|---|
| PDF（常规文本） | ✅ 就绪 | pdftotext（Poppler 26.05）+ pypdf 双通道 |
| DOCX | ✅ 就绪 | python-docx |
| HTML | ✅ 就绪 | trafilatura / beautifulsoup4 |
| Markdown / 纯文本 | ✅ 就绪 | 秒级完成 |
| EPUB | ⚠️ 可用 | 有 stdlib 降级解析；装 ebooklib 质量更好 |
| RTF | ⚠️ 可用 | 有基础清洗降级 |
| PDF（表格/公式技术书） | ⚠️ 需 docling |
仅 --mode technical 需要 |
| MOBI / AZW（Kindle） | ❌ 需 Calibre | 无降级方案，必须装 |
自检命令（随时查看环境状态）：
cd ~/.agents/skills/book-to-skill
/usr/local/bin/python3 scripts/extract.py --check
四、四种工作模式
| # | 模式 | 触发方式 | 产出 |
|---|---|---|---|
| 1 | 完整转换（默认） | 直接给出文档路径，不加别的说明 | 完整技能：SKILL.md + chapters/ + 术语表 + 模式库 + 速查表 |
| 2 | 仅分析 | 说「分析」「只提取」「我想先看看再生成」 | 结构化分析报告（框架/原则/技巧清单），不生成技能文件 |
| 3 | 从既有分析生成 | 提供已有的分析笔记 | 跳过提取阶段，直接生成技能文件 |
| 4 | 更新 / 合并 | 给新资料 + 指明要更新哪个已有技能 | 把新内容合并进现有技能（更新章节、索引、术语表） |
建议：第一次处理一本重要书时，先用模式 2 看提取质量，满意后再用模式 3 生成技能。
五、怎么用
方式一：自然语言（推荐）
# 完整转换（默认模式）
用 book-to-skill 把 /path/to/book.pdf 变成一个技能
# 仅分析（先看质量）
用 book-to-skill 分析这本 /path/to/book.pdf，先给我提取报告
# 从分析生成
按照我上面的分析，生成技能
# 更新已有技能
把 /path/to/new-chapters.pdf 合并进 my-book 这个技能
方式二：命令行（提取引擎）
scripts/extract.py 是文本提取引擎，负责把书变成可读文本；技能文件由 Agent 按 SKILL.md 流程生成（所以日常建议用「方式一：自然语言」）。
cd ~/.agents/skills/book-to-skill
PY=/usr/local/bin/python3
# 环境自检（只看依赖，不处理文件）
$PY scripts/extract.py --check
# 提取文本（--mode text 为默认值）
$PY scripts/extract.py /path/to/book.pdf --mode text
# 技术书模式（表格/代码/公式还原更好，需要 docling）
$PY scripts/extract.py /path/to/technical-book.pdf --mode technical
# 批量：整个目录 / 通配符（支持 .pdf .epub .docx .md .html .rtf .txt .mobi 等）
$PY scripts/extract.py ./books/*.pdf
真实参数（来自 --help）：
| 参数 | 取值 | 作用 |
|---|---|---|
--mode |
text（默认）| technical |
提取模式；technical 需 docling |
--install-missing |
ask | yes | no |
缺依赖时：询问 / 自动装 / 跳过 |
--check |
— | 只做环境自检，不处理文件 |
支持的输入格式：
.adoc .asciidoc .azw .azw3 .docx .epub .htm .html .markdown .md
.mobi .pdf .rst .rtf .text .txt .xhtml
六、生成物长什么样
一个转换完成的技能通常是这个结构（放在 SKILLS_HOME，默认 ~/.agents/skills/）：
~/.agents/skills/<你的技能名>/
├── SKILL.md # 主文件：核心框架、原则、何时用哪章
├── chapters/ # 按章节拆分的详细内容（按需加载）
├── glossary.md # 术语表（作者的定义，不是通用定义）
├── patterns.md # 可复用模式 / 决策规则
└── cheatsheet.md # 速查表
为什么这样组织省 token：Agent 先读轻量的 SKILL.md 判断「该看哪章」，只加载相关章节——而不是每次把整本书灌进上下文。
七、典型使用场景
| 场景 | 用法 |
|---|---|
| 学一本技术书 | 转成技能后，随时提问、按章深挖，不用重读全书 |
| 工作中套用方法论 | 如「按《重构》的手法分析这段代码」——Agent 直接调书里的框架 |
| 多本书交叉参考 | 每本书一个技能，让 Agent 对比不同作者的观点 |
| 把论文/规范变可用 | 除了书，也支持文档文件夹、批量 glob |
| 团队知识库 | 蒸馏后的技能可复制给团队成员共用 |
| 大书（>50k tokens） | 内置分块读取机制，按行区间抽取，不会一次性爆上下文 |
八、⚠️ 注意事项
- 扫描版 PDF 无效：图片型 PDF 没有文本层，提取会失败（脚本会做预检识别并提示）。需要先做 OCR。
- 版权提醒：蒸馏产物包含原书的实质性内容（框架、章节摘要），个人学习使用没问题，公开发布需注意版权。
- 首次处理较慢：大部头书需要提取 + 分析，属正常。脚本会给出成本预估再继续。
- 技术书建议单独走
technical模式：普通模式对表格/公式的还原有限，需装docling。 - Kindle 格式需 Calibre：MOBI/AZW 无降级方案，必须装 Calibre 才能处理。
九、与其他技能配合
| 配合对象 | 怎么用 |
|---|---|
| pdf / docx / markitdown | 先做格式转换或文本提取，再交给 book-to-skill 蒸馏 |
| memory | 把蒸馏出的关键框架存入长期记忆 |
| markdown-mermaid-writing | 把框架可视化（流程图/关系图） |
| web-access | 需要书以外的联网资料时补充 |
相关
- 主库文档：Codex Skills 完整清单
- 同类文档：web-access 联网能力指南
- 仓库：https://github.com/virgiliojr94/book-to-skill
- 安装文档：https://github.com/virgiliojr94/book-to-skill/blob/main/docs/install.md
