企业官网建设流程全解析

一本书省 51 倍上下文？book-to-skill 把资料变成按需技能

我最近遇到一个之前反复踩过的问题：想用 Claude Code 这类 AI 编程助手去理解我很喜欢的几本技术书，但每次把内容喂进去，要么很快把上下文窗口撑爆，要么前面聊过的东西后面全忘干净，甚至几轮对话之后，助手开始答非所问。

后来我换了个思路：既然模型的上下文窗口是有限的，为什么非要让它把整本书“背下来”？真正要解决的不应该是“能不能一次性装下更多内容”，而是“我需要的时候，能不能快速找到书里那一段”。这正是 book-to-skill 这类工具的价值所在。按它展示的案例和项目说明，一本书处理成 skill 之后，实际运行时的上下文占用大概能省一个量级以上，标题里的“51 倍”就是项目演示中比较有代表性的结果。这个数字当然会受书籍类型、内容密度和使用方式影响，但在真实工程里，方向完全正确：把“全文背诵”改成“按需查询”。

这篇文章我会先说清楚上下文浪费到底发生在哪里，再讲 book-to-skill 的核心原理、环境准备、完整实操步骤、验证方式、适用边界和常见坑。如果你也在用 AI 编程助手，并且想让它真正读懂那些几百页的技术参考书而不是吃掉你的 token，这篇文章值得耐心读完。

1. 一个我们每天都在交“上下文税”的场景

先来看一个真实场景。

假设你正在做一个支付系统的重构，支付渠道的签名规则、回调验签流程、对账文件格式都写在一本内部技术规范书里，大概 300 多页。你希望 AI 编程助手能帮你写对接代码，于是你把整本书的 PDF 转成文本，扔进对话里。

接下来会发生什么？

第一，上下文窗口很容易被占满。现在主流的大模型上下文窗口虽然已经从几万 token 发展到了几十万甚至上百万 token，但窗口大不等于效果好。模型在实际处理超长文本时，注意力会分散，关键细节反而容易被淹没。很多 AI 编程助手在上下文超过一定阈值后会自动做摘要，但摘要本身就是信息丢失的过程。

第二，你会为大量无关内容付费。一本 300 页的规范书，和你当前写的接口可能相关的只有不到 20 页。剩下的 280 页照样占 token、照样计费、照样挤占上下文空间。

第三，多轮对话之后，模型“忘了前面讲了什么”。这不是玄学，而是上下文窗口溢出后，最早的信息被丢弃或压缩后的必然结果。你不得不反复把同样的资料重新贴进去，陷入一个又贵又低效的循环。

这个问题不只是出现在“喂整本书”的场景。项目接入一个新框架时，你会把框架文档复制进来；接手一个老系统时，你会把需求文档贴给助手；做数据库选型时，你会把中间件手册塞进对话。整个过程本质上都是“上下文搬运工”，而不是在“使用 AI 提升开发效率”。

book-to-skill 出现的意义，就是想把这件事从“搬运”变成“索引”。

2. book-to-skill 是什么：不是“喂资料”，而是“编教材”

很多人第一次看到 book-to-skill 这个名称，会以为它只是一个格式转换工具：把 EPUB、PDF 或 TXT 变成模型能读的 Markdown 文件。如果只是这样，那它和普通的“文档解析工具”没有本质区别。

但它真正做的事，是“编教材”。

你可以回想一下自己读技术书的方式。你不会从头到尾逐字背完一章再去写代码，你会先看目录，再翻到需要的章节，复用里面的图表、代码和示例。你读哪一部分，是跟着你当前的问题走的。你手上那本书，本质上是你的一个外部索引，而不是你大脑的一份拷贝。

book-to-skill 做的事情是一样的。它会读取一本书的内容，然后按主题、章节、概念粒度把内容拆成一个个独立模块。这些模块被组织成模型可以按需加载的“技能文件”。技能文件之间通过描述文件、指令文件和知识文件配合工作，这样模型在看到任务时，会先判断“这个技能适不适用”，再主动加载和任务相关的部分，而不是在每一次对话里把整个文档从头看到尾。

用一句话来概括：

传统做法的上下文开销是 O(整本书)，book-to-skill 的上下文开销是 O(当前任务相关的章节)。

这也就是“一本 300 页的技术书，处理成技能后，日常使用时只需要占用几页对应内容的上下文”这句话后面的逻辑。同时，因为技能文件本身就是结构化的文本，存放在项目目录里，你可以随时增删内容、更新章节、单独针对某个模块做修订，不需要再把整本书重新喂给模型。

从这个角度看，book-to-skill 更像是一个“个人知识库的构建工具”，而不是一个简单的解析脚本。

2.1 它和“把文档塞进系统提示词”有什么区别？

这里有一个经常被混淆的点：把长文档处理成 skill 文件和“直接把文档写进 system prompt”到底有什么区别？

区别在于加载时机和上下文开销。

直接塞进 system prompt，意味着这次对话的每一个请求，都要带着这一大段文本一起发送给大模型。哪怕你只问一个“这个函数返回什么类型”，模型也得先把几百页文档和你的问题一起读完。上下文占用是常量级的，而且是非常高的常量。

而 skill 机制下，模型会基于当前任务先决定是否使用某个技能。如果使用，它会读取技能的描述文件，再根据描述决定是否进一步加载知识文件。整个过程是渐进式的、按需的。空闲状态下一个 skill 可能只占用几十行描述文本的上下文，只有真正用到的知识片段才会进入窗口。

这个差异，就是“省 51 倍上下文”的根本来源。

2.2 “按需技能”到底是什么？

“按需技能”是理解这个项目的第二个关键概念。

传统的“提示词工程”倾向于把话说全、把文档给全。按需技能则相反：它要求模型在正确的时间，找到正确的一小段资料，然后基于这一小段资料完成当前的任务。你可以把它理解成“懒加载”模式在提示词工程里的应用。

主流的 AI 编程工具中，Claude Code 对 skill 的支持是这个思路落地最典型的例子。Claude Code 会把工作目录下的.claude/skills或类似目录当作技能仓库，每个技能包含一个 SKILL.md 入口文件和多个可选的参考文件。模型在任务开始时看到的是技能清单和描述，执行到某一步时才去读取对应的参考文件。这个过程天然支持按需加载，也就天然避免了把整本书塞进上下文的问题。

book-to-skill 的价值，是把这个流程从“手动创建 skill 文件”变成了“从整本书自动生成 skill 文件”。

3. 核心原理：一本书为什么要拆成“技能”而不是“内容”

这一节我想把 book-to-skill 背后的原理讲透一点。不是因为它多复杂，而是因为理解了原理之后，你才能判断它到底适不适合你的场景，也才能在做参数调优时知道自己在干什么。

3.1 上下文窗口的成本结构

如果你只把上下文窗口理解成一个“容量”，那你很容易做出错误决策——既然窗口有 200K token，那我直接把 300 页 PDF 一次性塞进去不就好了？

但上下文窗口真正影响的是三件事：成本、速度和准确率。

成本上，每次发出请求时，系统提示词和对话历史都会被重复计费。一本地道的技术书转成文本之后通常有 30 万到 50 万 token，按照当前主流模型的输入价格，每次请求光“背稿子”就要花掉不少成本，这在本地模型场景下同样会带来显存和推理耗时的压力。

速度上，模型需要先处理超长前缀，再生成答案。输入越长，首 token 延迟越高。在实际交互中，你会明显感觉到助手“变迟钝了”。这也是为什么有时候你觉得自己本地跑模型结果很慢，原因不只是显卡不够强，而是你把太长太长的上下文塞给了它。

准确率上，基于已有的研究共识以及真实使用体验，大模型在超长上下文中的注意力分布会被长距离无关信息干扰。它不像人那样能跳读，而是期望对每个 token 都给予一定的注意力权重。无关信息越多，关键信息被“稀释”得越严重。

所以正确的做法并不是“想办法把窗口塞满”，而是“想办法让每次请求只携带最少的相关内容”。

3.2 book-to-skill 的两个核心环节：切分与索引

book-to-skill 要解决的核心问题有两个。

第一个叫做“切分”。它需要把一本书切成一个合理的结构化表示。一本技术书不是一个线性的文本，它有目录、章节、小节、代码块、参数表、示例和概念定义。合理的切分要保证每一块是自洽的、有独立意义的，并且块与块之间的交叉引用能够被保留或者转化。

第二个叫做“索引”。切分出来的块如果只是放在那里，模型并不知道什么时候该用哪一块。book-to-skill 会为每个块生成描述信息，让模型的调度机制能够根据当前任务特征，快速定位到合适的块。

举个例子，当你告诉 AI 助手“帮我把支付回调验签逻辑实现一下”时，AI 会先看到项目的技能目录。技能目录里有一个名为“payment-settlement-spec”的技能，它的描述是“支付结算系统的签约、签名、回调验签及对账文件说明”。这个描述和当前任务匹配，于是 AI 会加载该技能入口文件，入口文件里再进一步引导它去读取“验签与回调”的知识文件。整本书中关于性能优化、报表设计、历史版本说明的内容，这次请求完全不会进入上下文。

这里最关键的理念是：你省下来的不仅是 token，更是模型每次推理时的注意力广度和判断稳定性。

4. 环境准备与前置条件

在开始实操之前，先看一下需要准备的东西。

因为 book-to-skill 是一个开源工具，它的安装和使用方式可能随版本迭代发生调整。下面给出的步骤以通用思路为主，具体命令请以项目 README 为准。我在本文中只演示一个稳定的最小流程，不会写死版本号，避免你照抄后遇到版本不兼容的问题。

需要准备的环境如下：

另外，因为 book-to-skill 需要把一本书变成模型结构化的技能文件，如果你计划用它处理较大型文档，建议准备一个独立的项目目录，避免把生成的文件散落在系统各处。

一个比较推荐的目录结构是：

book-to-skill-workspace/ ├── books/ # 存放原始书籍文件 ├── skills/ # 存放生成的技能文件 └── config/ # 存放转换配置

5. 完整实操：把一本技术书变成按需技能

接下来是这篇文章的核心部分。我会以“把一本网络编程的电子书转换为可供 Claude Code 加载的 skill”为例，带你把整个流程走一遍。

5.1 安装 book-to-skill

第一步是获取工具本体。如果你使用的环境是 Node.js 生态，通常可以通过 npm 或 git clone 的方式安装。

# 方式一：通过 npm 全局安装 npm install -g book-to-skill # 方式二：克隆项目源码，本地安装 git clone https://github.com/your-target-repo/book-to-skill.git cd book-to-skill npm install npm link

安装完成后，可以通过下面的命令验证是否安装成功：

book-to-skill --version

如果命令能正常输出版本号，说明安装成功。如果提示“command not found”，大概率是 npm 全局安装路径没有加入 PATH，需要你自行检查环境变量。

5.2 准备书籍文件

book-to-skill 支持的输入格式一般包括 PDF、EPUB、TXT 和 Markdown。为了让转换效果更好，建议优先使用文字版 PDF 或 EPUB，而不是扫描版 PDF。扫描版 PDF 需要 OCR，转换质量会明显下降。

把书放到工作目录的 books 子目录里：

mkdir -p books skills cp /path/to/your/network-programming.pdf books/

5.3 运行转换命令

接下来执行核心转换命令。这里以常见的 CLI 参数为例：

book-to-skill convert \ --input books/network-programming.pdf \ --output skills/network-programming \ --format markdown \ --split-mode section \ --max-chunk-size 3000

参数含义解释如下：

• --input：指定输入的书籍文件路径。
• --output：指定生成技能文件的输出目录。
• --format：指定输出格式，一般使用 markdown。
• --split-mode：指定切分模式，section 表示按章节结构切分，page 表示按页切分。
• --max-chunk-size：指定每个知识块的最大字符数，防止单个文件过大。

如果你的项目 CLI 参数不一样，不要慌，直接在命令行里输入：

book-to-skill convert --help

查看具体支持哪些参数。

5.4 查看生成后的技能目录结构

转换完成后，进入输出目录，你会看到类似下面的结构：

skills/network-programming/ ├── SKILL.md ├── references/ │ ├── chapter-01-introduction.md │ ├── chapter-02-tcp-ip-basics.md │ ├── chapter-03-socket-api.md │ ├── chapter-04-http-protocol.md │ ├── ... │ └── chapter-12-network-security.md └── assets/ └── diagrams/

这里的SKILL.md是技能入口文件，references目录下是各个章节的知识文件。

打开SKILL.md，你会看到类似这样的内容：

--- name: network-programming description: 网络编程基础知识，包括 TCP/IP、Socket API、HTTP 协议和网络安全。 usage: 当用户询问 Socket 编程、HTTP 协议细节、网络分层或常见的网络调试问题时，使用本技能。 --- # Network Programming Skill 本技能由《网络编程实战》一书自动生成，按章节拆分为知识模块。 ## 目录 - [第 1 章 网络编程概述](references/chapter-01-introduction.md) - [第 2 章 TCP/IP 协议基础](references/chapter-02-tcp-ip-basics.md) - [第 3 章 Socket API](references/chapter-03-socket-api.md) - [第 4 章 HTTP 协议详解](references/chapter-04-http-protocol.md) - ... ## 使用指引 - 当需要查询 Socket 相关问题时，优先加载 `chapter-03-socket-api.md`。 - 当需要排查网络问题时，结合 `chapter-02-tcp-ip-basics.md` 和 `chapter-12-network-security.md`。

这就是整个机制能够“按需加载”的核心文件。

5.5 把技能接入 Claude Code

如果你使用的是 Claude Code，只需要把生成的技能目录复制到项目的技能目录下。

# 在你的项目目录下创建 skills 目录 mkdir -p .claude/skills # 将生成的技能目录复制过去 cp -r skills/network-programming .claude/skills/

如果你用的是其他支持 agent skills 的 AI 编程工具，请按该工具的官方文档，把技能目录放到对应的约定位置。

启动 Claude Code 后，你可以直接问一个和这本书相关的问题：

请用 Node.js 写一个 TCP 客户端，连接到远程服务器后先发送一个 JSON 请求，再读取响应。

如果技能加载成功，Claude Code 会主动读取chapter-03-socket-api.md中 Socket 编程相关的章节，并结合这本书里的代码风格来生成答案。此时你实际上已经“按需使用”了整本书的内容，而不是把它全文塞进上下文。

6. 运行结果与效果验证

工具安装好、技能也接入了，怎么判断它是不是真的有效？这里分享几个验证维度。

6.1 验证技能是否被正确识别

你可以在 Claude Code 里主动输入一条命令查看当前已加载的技能：

/plugin

或者直接问助手“你有哪些可用的技能”，观察它是否能列举出 network-programming 这个技能，并能正确说出这个技能的用途。

如果连技能列表里都没有，说明技能目录放错位置，或者 SKILL.md 的 frontmatter 格式不对。先检查 yaml 头部是否完整，再检查目录层级。

6.2 验证回答质量

接下来做一个质量测试。找一个只有书里才会讲清楚的细节问题来问。

比如，如果这本书里有一章讲了“TCP 拆包和粘包问题以及处理方法”，你就可以问：

在 Node.js 的 TCP 编程中，如何处理粘包问题？基于我项目里的网络程序给出具体方案。

回答里如果引用了这本书特有的一些术语、代码结构或异常情况下的处理建议，说明技能加载是有效的。如果回答变得非常泛泛，或者完全没有涉及书里的细节，就要重新检查技能的引用路径是否写错了。

6.3 验证上下文占用

如果要量化对比，可以在工具的调试模式下观察上下文占用情况。

常见的做法是开启 Claude Code 的 verbose 或 debug 输出，查看每次请求发送了多少 token。你可以分别做两次测试：

• 第一次：直接把整本书的 Markdown 文本放入系统提示词或作为附件传给模型，然后发同一个问题。
• 第二次：不手动传书，只依赖 book-to-skill 生成的技能文件，发同一个问题。

观察两次请求的输入 token 数。通常第二次会小一个数量级。这个指标就是“省 51 倍上下文”的实际体现，不需要你从零到一复现项目演示，只需要对比同一个任务两种做法即可。

另外，还可以对比显存占用。如果你在本地跑模型，上下文越长，KV Cache 占用越高。把整本书塞进去和一本书只加载几个章节，显存差异会非常直观。

6.4 如果失败，第一步排查哪里

如果发现技能没有被加载，不要急着怀疑转换工具。按这个顺序排查：

1. 确认技能目录位置是否正确，尤其是 Claude Code 这类工具对目录名大小写和层级有约定。
2. 确认 SKILL.md 的元数据格式是否完整，缺少name或description字段会导致技能被忽略。
3. 确认 references 目录下的引用路径和 SKILL.md 里写的是否一致，大小写错误在 Linux/macOS 上会直接 404。
4. 确认书的内容是否被过度切分，导致每个 chunk 都太碎，描述无法覆盖完整语义。

7. 典型使用场景与边界

book-to-skill 不是万能的。它适合某些场景，但在另外一些场景下你可能会白忙活。

7.1 适合哪些内容

第一，适合“参考型”资料。比如框架文档、协议规范、API 手册、运维手册。这类内容的特点是：用户不会从头到尾连续阅读，而是在某个具体问题发生时，去查阅对应的章节。它天然适合按需加载。

第二，适合“规范型”资料。比如公司内部编码规范、数据库设计规范、接口开发规范。这类内容需要高频被引用，但每次往往只需要其中一两条规则。把它做成技能后，模型能在写代码的过程里随时看到相关规则，而不用每次开会前临时抱佛脚。

第三，适合“知识体系固定”的经典书籍。比如《TCP/IP 详解》《算法导论》这类长期不太会变的技术书籍。转换一次，就能用很久。

7.2 不适合哪些内容

第一，不适合“高度依赖上下文连贯性”的内容。比如小说，或者需要从头到尾理解人物关系、剧情推进的材料。按需加载会破坏这种连贯性，导致模型只能看到局部而忽略前后文。

第二，不适合频繁更新的资料。如果你的这本书每个月都会出新版，你得同步重新生成技能文件，否则内容会过期。这一般出现在在线文档动态导出的场景。如果你直接把某个在线文档站导出成 PDF 再转技能，你得建立自动化的更新机制。

第三，不适合以“图”为核心价值的书。如果书里的核心知识全在 UML 图、架构图、流程图里，而你的转换工具没有 OCR 和图表理解能力，那生成的知识文件就只留下了图片说明文字，丢失了真正有价值的内容。

7.3 常见的理解误区

很多人会把“节省上下文”理解成“可以同时加载越来越多的书”。这个方向是错的。book-to-skill 的核心是减少不必要的上下文，而不是让你无限扩大上下文。如果你给 Claude Code 挂了 50 个技能，每个技能的描述文件也有几百字，模型在每次任务开始时仍然要过滤大量技能描述。技能太多也是一种上下文噪音。

正确的用法是在一个项目里只放与该领域强相关的技能。尽量保持技能目录的精简和聚焦。

8. 常见问题与排查思路

下面把我在实践过程中遇到过的、以及比较有代表性的问题列成表：

这里也要特别提醒一下：使用这类工具时，请只处理你有权阅读和使用的资料。不要拿它去转换盗版电子书，也不要在生产环境里把非公开资料直接喂给外部模型服务。涉及公司内部规范、客户隐私等敏感内容时，优先选择支持本地模型的服务，并且注意最小权限原则，只让必要时的工作会话访问对应资料。

9. 最佳实践与工程建议

9.1 不要把整本书塞成一个技能

一本书内容很多，技能文件太多也会让模型犯迷糊。更好的做法是：先按“主题”切分。比如把《JavaScript 高级程序设计》按照“语言基础、DOM、异步编程、模块化、性能优化”拆成几个独立的技能，而不是一本书生成一个巨型技能。

这样做的另一个好处是，后续做增量更新时，你只需要重新处理变化的那部分内容，不需要把整本书重新转一遍。

9.2 为每个技能写一个高质量描述

SKILL.md 里的 description 字段就是模型的“索引”。描述越准确，模型越能在正确的时候找到它。写描述的原则是：要包含触发条件和使用场景，而不要太长的内容概述。

比如：

description: 支付系统的签名、验签、回调规范。当需要实现支付接口、排查回调验签失败或修改签名逻辑时，使用本技能。

这样写，比“本技能包含支付系统的相关知识”要强大得多。

9.3 为大模型版本预留兼容方案

不同模型的 tool/skill 机制实现方式不一样。Claude Code 的 skill 目录和文件约定，不一定适用于其他模型。

一个比较稳妥的工程化做法是：用 book-to-skill 生成“内容层”的 Markdown 文件，然后用一个适配层把你的内容文件映射到不同工具的 skill 目录结构。内容层是最稳定的，适配层随工具变化，这样即使工具升级了，你的知识库也不至于从头再来。

9.4 建立更新流程

书本类资料相对静态，但如果你处理的是在线文档、项目手册这类持续更新的资料，建议写一个自动化脚本，每天或每次文档更新后自动重新执行转换命令，并把你变更的内容同步到技能目录。否则你的技能库里会存留着大量过期内容，做决策时会产生误导。

9.5 结合上下文压缩与摘要机制

如果你已经在用带自动摘要或上下文压缩的 AI 编程工具，可以配合 book-to-skill 一起使用。它的价值在于让你的项目一开始就保持精简的上下文，而不是在上下文已经很大时才去压缩。等到上下文已经装满再压缩，很多细节就已经丢失了。

正确的使用顺序是：

1. 先把资料转成技能，用索引代替全文；
2. 再把技能挂到项目目录，让模型按需加载；
3. 最后配合工具的压缩能力，处理对话历史积累导致的增长。

9.6 安全与合规优先

最后一个建议，也是最重要的建议：无论工具多好用，都要把权限和安全边界放在第一位。不要给技能文件授予过高的文件系统权限，不要让它自动读取工作目录外部的敏感文件，不要在生产环境变更前跳过测试验证。如果你在团队内部推广这套流程，先制定好“哪些资料可以转、哪些不可以转、转换后的技能文件存放在哪里、谁有权限修改”的规范。

10. 总结

回到标题：book-to-skill 省下的到底是什么？

答案不是简单的一个 token 数字，而是模型在每一个任务上的注意力空间、你的对话成本、以及 AI 助手给出可靠回答的稳定性。把整本书塞进上下文的思路，表面上是“喂得多”，实际上是在制造噪音；而按需技能的思路，是让模型在正确的时间只看它该看的那一页。

按照这篇文章的流程，你现在可以动手复制一本你手头经常查阅的技术书，把它转换成技能文件，挂到你的 AI 编程工具里，然后对比一下同一个问题上下面两种做法的输入 token 开销：

# 方案一：手动把整本书塞入上下文（不推荐） cat book.md | ask-model "请根据书中内容回答 XXX" # 方案二：用 book-to-skill 生成的技能回答（推荐） ask-model "请按书中 Socket 章节的约定，帮我实现一个 TCP 客户端"

实际跑一轮，你才会真正理解“按需技能”和“静态上下文”的区别。

在项目落地的过程中，记得先从小书、小章节开始测试切分效果，确认技能描述和引用路径准确之后，再扩展到整本资料；对于成熟度比较高的团队，更值得投入精力做技能目录的自动同步、更新对比和权限规范。工具解决了“资料如何进上下文”的问题，但“哪些资料值得进、什么时候进、进完之后如何保持更新”，仍然需要你根据自己的项目情况持续调整。

毕竟，AI 编程助手再聪明，也不会自动替你判断什么才是当前任务真正需要的那一部分。为它建立一个高效的“知识索引”，是把 AI 用出生产力的关键一步。