如何用 book-to-skill 的 analyze-only 模式在生成 skill 前预览书籍结构-港品优选

如何用 book-to-skill 的 analyze-only 模式在生成 skill 前预览书籍结构

【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill

把一本书转成 skill 前，你可能想先确认两件事：提取出来的章节结构是否符合预期、能提炼出哪些框架和原则——尤其是大书，Full Conversion 的 token 开销不小，SKILL.md 的 Step 2.5 专门在生成前给出成本预估，就是为了让你有依据地决定要不要继续。book-to-skill 的 Analyze Only 模式（SKILL.md 中称为 Mode 2）就是为此设计的：它只执行 Steps 0–3（范围检查、输入校验、文本提取、结构分析），然后输出一份结构化提取报告就停止，不生成任何 skill 文件。本文适用于任何能运行该 skill 的宿主（Claude Code、GitHub Copilot CLI、Amp、Hermes Agent），说明如何触发该模式、报告会包含什么、以及如何核对预览结果。

安装 skill 并检查提取环境

先明确一点：Analyze Only 不是extract.py的命令行参数，而是/book-to-skillagent skill 流程中的一个模式，单独安装的 pip CLI 只提供文本提取，没有这个入口。所以第一步是把 skill 装进宿主对应的 skills 目录，docs/install.md 给出了各宿主的完整路径，以 Claude Code 为例：

git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill ~/.claude/skills/book-to-skill

其他宿主把克隆目标换成对应目录即可（Copilot CLI：~/.copilot/skills/；Amp：~/.agents/skills/；Hermes Agent：${HERMES_HOME:-$HOME/.hermes}/skills/<category>/），或者用一条命令让 skills CLI 按所选宿主安装：

npx skills add virgiliojr94/book-to-skill

装好后，在 skill 目录下运行一次预检（无需提供文件，只报告环境）：

python3 scripts/extract.py --check

它会按格式列出已安装的提取器，并给出缺失项的精确安装命令。纯文本、Markdown 等格式无额外依赖；PDF 依赖pdftotext（poppler）或docling，EPUB、DOCX、RTF 各有可选的更优提取器。

如何触发 Analyze Only 模式

在 agent 会话中用文档路径调用（~/path/to/your-book.pdf换成你的文档路径，也支持目录和 glob，支持格式见 docs/usage.md）：

/book-to-skill ~/path/to/your-book.pdf

接下来会发生三件事：

Step 1.5，内容类型提问。转换器会问这本书是 "Technical"（有代码块、表格、公式）还是 "Text-heavy"（以正文为主）。答案决定提取器：technical 的 PDF 走 Docling，约 1.5 秒/页，长文档要等几分钟；text 模式用最快的可用提取器，PDF 走 pdftotext。
Step 2，文本提取。agent 在已安装的 skill 目录下定位scripts/extract.py并执行，等效于（第一个参数是 skill 安装位置下的脚本路径，装在哪就解析到哪，例如 Claude Code 装在~/.claude/skills时即~/.claude/skills/book-to-skill/scripts/extract.py；--mode取technical或text，对应 Step 1.5 的答案）：
```
python3 ~/.claude/skills/book-to-skill/scripts/extract.py ~/path/to/your-book.pdf --mode text --install-missing ask
```
若检测到格式缺少更优提取器，--install-missing ask会提示你选择是否安装，非交互会话则默认退回 fallback（只有显式yes才自动安装）。完成时输出会打印Workdir ->、Text ->、Meta ->三行，给出本次运行的实际路径。
Step 2.5，成本预估。生成任何东西之前，agent 基于本次运行的metadata.json给出预估：来源数量、页数/词数/token 数、输入与输出 token 估算（输入 ≈estimated_tokens × 1.3，输出 ≈ 章节数 × 每章预算 + SKILL.md 4,000 tokens + glossary/patterns/cheatsheet 4,500 tokens），以及将要生成的文件清单。提示的结尾是：
```
➡ Proceed with Full Conversion / Update? (or type "analyze only" to preview first)
```
此时回答analyze only即切换到 Mode 2。也可以从一开始就表明意图——文档列出的触发说法包括 "analyze"、"just extract"、"I want to review before generating"。

进入 Mode 2 后，流程只走到 Step 3：Step 4 的用途提问（决定DEPTH）和其后所有生成步骤都被跳过，不会创建任何 skill 目录。

Analyze Only 的产物：工作目录与提取报告

提取输出位于按运行隔离的工作目录：默认<tempdir>/book_skill_work-<pid>/，或环境变量BOOK_SKILL_WORKDIR指定的路径。内含两个文件：

full_text.txt— 所有来源合并的提取文本，首行带SOURCE:头标明来源；
metadata.json— 总大小、词数、页数、token 数、被丢弃的 EPUB 图片数量、本次运行的workdir，以及逐来源的明细列表。

目录名按运行区分，目的是让同一机器上的并发提取互不覆盖，所以实际路径要从输出的Workdir ->行（或metadata.json的workdir字段）读取，不要假定固定位置。

结构分析（Step 3）读取full_text.txt的前 8,000 字符，识别书名、作者、章节结构（"Chapter N"、"PART I"、编号标题、目录）和主题域，再依据目录映射全部章节。完成后 agent 输出提取报告，其结构由 SKILL.md Step 3 定义，其中<...>是模板占位符，由 agent 从本次提取结果填充：

## Extraction Report — <Title> ### Author's Core Frameworks - **<Framework Name>**: <what it is and when to apply> ### Key Principles - <Principle>: <actionable rule> ### Techniques & Methods - <Technique>: <step-by-step or how-to> ### Anti-patterns - <What to avoid>: <why> ### Suggested Skill Name `{author-lastname}-{core-concept}` — e.g. `cialdini-influence` ### Chapters Detected | # | Title | Main Frameworks |

"Chapters Detected" 表格加各框架列表就是"书籍结构预览"的核心：它告诉你检测到了多少章、各章标题、以及从每章提炼出的框架。

如何核对预览结果

核对分三层，都来自文档明确给出的检查项：

确认提取的是你指定的文档。看metadata.json的filename/source_file字段，或full_text.txt首行的SOURCE:头。机器上有并发提取时尤其重要——盯错 run 的工作目录会读到别人那本书的结果。
确认报告覆盖了你关心的结构。有目录的书，"Chapters Detected" 表应列出全部章节；Suggested Skill Name 按{author-lastname}-{core-concept}格式给出，供后续生成时命名参考。
确认没有生成 skill 文件。Mode 2 的定义就是在报告后停止（"Stop — do NOT generate skill files"），任何宿主的 skills 目录下都不会出现新的 skill 目录——这是它与 Full Conversion 的边界。

两个会直接影响预览结果的已知限制（docs/how-it-works.md 与 docs/faq.md）：

章节自动检测依赖显式标题。检测依赖Chapter N/Capítulo N这类标题；只用章节题名或罗马数字编号的书（文档举例 Pro Git 和 Moby-Dick）无法自动分段——提取和转换照常工作，但需要人工指认章节。如果报告里的章节表是空的或不完整，先对照书的标题风格检查是否属于这种情况。
扫描版 PDF 会提前停止。没有文本层的 PDF（拍照、扫描件）会在前几页就被识别并立即停止，而不是跑完全书产出空结果。遇到这种情况先做 OCR 再转换（input.pdf不被修改，结果写入output.pdf）：
```
ocrmypdf input.pdf output.pdf
```
book-to-skill 本身不执行 OCR，这一步由你完成。

如果提取质量异常，怀疑环境问题时，重新跑python3 scripts/extract.py --check确认各格式实际使用的提取器。

预览之后的下一步：基于分析结果生成 skill

报告看完、决定继续时，文档定义了配套的Generate from Prior Analysis模式（Mode 3）：当用户已有分析笔记、或此前跑过 analyze-only 时，跳过 Steps 0–3，直接把提供的分析作为输入，执行 Steps 4–9——不再重新提取，从确定 skill 名称开始，生成章节摘要、glossary/patterns/cheatsheet 和主 SKILL.md。所以 analyze-only 报告的自然用法是：核对无误后把它交回 agent，作为生成阶段的输入。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析