book-to-skill的discovery_tax.py工具全解：亲手复现24-51倍Token节省

book-to-skill的discovery_tax.py工具全解亲手复现24-51倍Token节省【免费下载链接】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-skillbook-to-skill是一个把技术书籍PDF/EPUB 等转成 AI 智能体技能的开源工具而其中的 tools/discovery_tax.py 正是用来量化「Token 节省」的测量器它能算出回答同一个问题时「整本书塞进上下文」「让智能体现场翻书」「加载预编译技能」三种方式各烧掉多少 Token——也就是那个被官方宣称的24-51 倍 Token 节省的出处。本文手把手带你复现这套测量。一、什么是「发现循环税」Discovery Loop Tax想象你有一个关于第 5 章的问题智能体有三种回答方式策略发生了什么成本特征 上下文倾倒context-dump整本书十几万 Token常驻上下文每一轮对话都重新计费 发现循环discovery-loop现场读目录 → 拉取原始章节 → 缺定义再回退读上一章一次性成本但会进历史记录⚡ book-to-skill约 4K Token 的常驻 SKILL.md 核心 按需加载 1 个预编译章节约 1K总计约 5,000 Token核心直觉你问的是一个问题却要为一整本书付账。discovery_tax.py 做的就是把这三笔账精确算出来。二、复现第一步准备一本书的 full_text.txtdiscovery_tax.py 不直接吃 PDF它吃的是提取后的纯文本。有两种拿到它的方式走完整流程安装后运行/book-to-skill 你的书.pdf提取阶段会生成/tmp/book_skill_work/full_text.txt流程详见 docs/how-it-works.md只要文本直接运行提取脚本 scripts/extract.py它同样会输出合并后的full_text.txt。如果本地没有这份文件先克隆仓库git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill cd book-to-skill 小贴士书籍最好有明确的「Chapter N / Capítulo N」章节标题否则工具会提示检测不到章节并退出。三、复现第二步一行命令跑测量python3 tools/discovery_tax.py --full-text /tmp/book_skill_work/full_text.txt --target-chapter 5四个参数都很直观参数作用默认值--full-text提取后的全书纯文本必填--target-chapter N假设问题指向第 N 章5--skill-dir传入已生成的技能目录用真实的 SKILL.md 和章节文件计费无--core-tokens不传 skill-dir 时按设计上限估算常驻核心4000最严谨的做法是加上--skill-dir这样「book-to-skill 一栏」用的不是你拍的 4000 估算值而是真实生成的 SKILL.md 和真实章节文件的 Token 数。四、内部机制它凭什么算得准读懂 tools/discovery_tax.py 的三处设计你就明白了1. 双档 Token 计数器安装了tiktoken时用cl100k_base 真实 BPE 分词计数没装时退化为单词数 ÷ 0.75的启发式与提取器使用的常数一致。报告会打印当前用的是哪种方法——数字可复现的前提是方法透明。2. 复用主流程的章节检测而不是另写一套它直接从 book_to_skill/utils.py 导入_chapter_number和_TOC_PATTERN保证测量工具和转换管道对「什么算一章」「什么算目录」的判断完全一致覆盖多语言含 CJK标题。3. 「最大正文」规则防止目录行冒充章节「Chapter 5」这个字符串在书里会出现两次目录里一行、正文里一章。best_chapter函数在多个同名段落中挑正文最大的那个确保计入的是真正的章节而不是目录条目——这个细节在 tests/test_discovery_tax.py 中有专门的属性测试守护。五、读懂报告24-51 倍与 2.4-15.6 倍的区别运行后报告类似这样数值以你的书为准Cost to answer ONE targeted question (tokens entering context): context-dump : 119,264 (resident, re-billed EVERY turn) discovery (best) : 12,152 ToC raw target chapter discovery (loop) : 12,152 1 prior chapter for a missing definition book-to-skill : 5,000 core compiled chapter book-to-skill advantage: vs context-dump : 24.0x fewer tokens vs discovery loop : 2.4x fewer tokens官方实测数据见 docs/performance.md书上下文倾倒发现循环book-to-skill相对节省Think Python 2小119,26412,152~5,00024×/ 2.4×Working Backwards中175,25333,444~5,00035×/ 6.7×AI Engineering大256,28777,866~5,00051×/ 15.6×⚠️ 复现时请注意两个「诚实性声明」工具文档里写得明明白白24-51 倍是「每轮都发生」的成本对比整本书倾倒每轮对话都要重新计费这是最强的一档论据发现循环的数值是一个模型它使用该书真实的目录与章节 Token 尺寸假设「读目录 读目标章必要时回退一章」是对行为的可辩护估计而非对某个具体智能体的实测轨迹。六、验证工具本身不变式测试tests/test_discovery_tax.py 不锁死具体数字数字取决于是否装了 tiktoken而是断言排序不变式book-to-skill 成本 discovery(best) context-dump且discovery(best) ≤ discovery(loop)这是测量工具的正确姿势测逻辑而非快照。想本地跑一遍测试套件的话pytest tests/test_discovery_tax.py七、复现常见坑速查 症状原因解法提示 No chapters detected技术类 PDF 标题被提取压平用 technical 模式Docling重新提取数字和别人对不上Token 计数方法不同先pip install tiktoken统一用 cl100k_base想更精确用了默认的 4000 估算传--skill-dir指向真实生成的技能目录写在最后discovery_tax.py 的价值不只是复现一个 24-51 倍的数字而是让你亲眼看见常驻整本书的成本每轮翻倍叠加而「常驻核心 按需章节」的结构成本是一次性的、有上限的。跑一次命令你就有了说服自己或你的团队把书变成技能的完整证据链 相关入口完整基准数据见 docs/performance.md工具架构说明见 docs/architecture.md。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考