BookLeme 是什么
BookLeme，中文名“读了么”，是一套把书籍编译成 Agent Skill 的工具链。它关注的不是生成普通摘要，而是提取书中的工作方式，例如提问顺序、判断条件、证据规则、流程状态和不适用边界，再将其组织成可安装、可调用、可验证的产物。
项目把书籍处理分为编译期与运行期：编译时读取并处理原书，运行时只按需加载生成的知识分片。这样可以避免每次调用 Skill 都重新读取整本书。
注意：“提炼结构而非摘要”是项目采用的工程设计选择，但 README 明确将其标记为尚未由项目验证的假设，而不是已经证实的结论。
BookLeme 会生成什么
BookLeme 提供两个生成引擎。它们共享提取和校验阶段的中间表示，只在渲染阶段分流，因此选择同时生成两类产物时，不需要把一本书处理两遍。
知识包 knowledge_pack
知识包是一套可查阅的结构化知识库，主要包含 Topic Index 路由表、按需加载的框架分片、决策速查和出处清单。它适合回答“书中的某个框架如何使用”一类问题。
行为 Skill behavior_skill
行为 Skill 用于运行完整流程，可包含角色定义、硬约束、状态机、具名输出契约、反模式和情绪护栏。它适合执行教练对话等多步骤任务，而不仅是查询知识。
核心特性
- 双引擎自动路由：根据 12 个确定性体裁特征选择知识包或行为 Skill，也可以手动指定引擎。
- 可插拔体裁插件：新增体裁时可在用户插件目录中增加一个 Python 文件，无需修改核心流水线。
- 逐字忠实度回验：引文必须是原文中的精确子串，并通过多项可测指标检查。
- 版权硬门：安装和发布前执行确定性版权检查，第三方书籍生成的 Skill 默认保持私有。
- 运行时零第三方依赖：核心实现只使用 Python 标准库。
- 阶段级幂等：流水线使用 SHA-256 支持续跑；删除某个阶段的产物后，只需补跑相应阶段。
安装与环境准备
BookLeme 要求 Python 3.9 或更高版本。克隆仓库后，可以直接通过 Python 模块入口运行，无需先安装第三方运行时依赖。
git clone https://github.com/bookleme/bookleme.git
cd bookleme
python3 -m bookleme --version如果命令能够输出版本信息，说明基本环境已经可用。仓库声明支持 PDF、EPUB、DOCX、Markdown、HTML、RTF 和 MOBI 等输入格式；下面使用项目自带的 Markdown 合成书稿演示完整流程。
第一次编译：从书稿生成 Skill
运行 run 子命令，并通过 --input 指定书稿，通过 --title 设置标题：
python3 -m bookleme run \
--input evals/cases/synthetic/coach_book.md \
--title "我的第一本书"默认情况下，BookLeme 会分析书稿的体裁特征，并自动选择适合的生成引擎。编译过程经过输入登记、文本提取、中文分段、体裁路由、原子能力抽取、忠实度校验、渲染、综合校验、安装与冒烟评测等阶段。
建议：第一次体验时优先使用仓库提供的合成测试书稿。处理第三方书籍前，应先确认自己拥有相应的使用权，并理解生成产物的分发限制。
选择生成引擎
使用 --engine 可以控制输出类型：
python3 -m bookleme run \
--input evals/cases/synthetic/coach_book.md \
--title "教练对话示例" \
--engine behavior_skill可用值包括：
auto：让路由器自动选择。knowledge_pack：只生成结构化知识包。behavior_skill：只生成可运行的行为 Skill。both：同时生成两类产物。
如果希望关闭路由并让双引擎全部输出，可以使用 --no-router：
python3 -m bookleme run \
--input evals/cases/synthetic/coach_book.md \
--title "双引擎示例" \
--no-router指定体裁插件
体裁插件决定产物的状态机、输出契约、硬约束和表达方式。当前已经实现的插件包括：
coach_dialogue：用于教练或自我对话，支持一问一答状态机、情绪护栏、中断和续聊。knowledge_reference：用于框架速查，通过 Topic Index 路由内容；遇到书中未提供的信息时必须拒答。
professional_analysis 和 decision_checklist 仍属于后续 M4 路线图内容，当前不应把它们视为已经完成的功能。
可以通过 --genre 强制选择已实现的插件：
python3 -m bookleme run \
--input evals/cases/synthetic/coach_book.md \
--title "人生设计对话" \
--engine behavior_skill \
--genre coach_dialogue校验生成产物
生成完成后，应使用项目提供的校验命令检查产物。README 中以 examples/coach 为例：
python3 -m bookleme validate examples/coach该步骤会执行官方校验器、自有 lint 和版权硬门。BookLeme 将忠实度拆分成可检查指标，包括引文解析率、逐字违规率、负例拒答率、触发词命中率、产物合规率、shingle 重叠上限和覆盖率。
项目还保留 groundedness 启发式指标，但 README 明确说明 LLM judge 尚未接入，因此该值目前只报告，不作为硬门。
运行回归测试
在修改核心代码、插件或模板后，运行完整测试：
python3 -m unittest discover -s tests -v如果正在开发插件，还可以检查状态 schema，并单独验证插件文件：
python3 -m bookleme schema --state
python3 -m bookleme plugin validate bookleme/plugins/builtin/coach_dialogue.py安装产物与使用权声明
默认情况下，生成命令不会把产物写入技能真源。需要安装时，应显式加入 --install。同时可以使用 --user-rights 声明输入内容的权利状态：
python3 -m bookleme run \
--input path/to/book.md \
--title "内部知识 Skill" \
--engine both \
--install \
--user-rights owned--user-rights 支持以下值：
owned：用户拥有内容权利。licensed：已获得相应许可。public_domain：内容属于公有领域。unknown：权利状态未知。
权利声明不能替代法律判断。MIT 许可证只覆盖 BookLeme 转换器的代码和技能定义，不覆盖输入的书籍，也不会自动授予用户分发衍生产物的权利。
理解版权硬门
BookLeme 的输出定位是结构化衍生笔记，而不是原文复现。项目设置了六条版权硬门，任意一条失败都会阻止安装或发布：
- 单条引文不超过 150 字，并且能够逐字追溯到输入原文。
- 总引文比例不超过 0.03。
- 连续复制内容不超过 150 字。
- 13 字 shingle 重叠不超过 0.10。
- 产物不得包含全文或原始切片。
contains_original_text必须为false。
第三方书籍生成的 Skill 默认私有且不得分发。若确实拥有公开分发权，仍需要显式提供双重确认参数：
--public --confirm-public PUBLISH公开参数是一道工程确认门，不等同于版权授权。使用者仍需自行确认许可范围、适用法律和输入材料的权利状态。
高级技巧：利用阶段级幂等续跑
BookLeme 的 S0 至 S9 流水线采用阶段级幂等设计，并使用 SHA-256 识别已有结果。长文档处理意外中断时，可以保留已经完成的阶段产物；如果只删除某一阶段的输出，工具会补跑对应阶段，而不必重新处理整本书。
这一设计也适合调试插件或渲染逻辑。由于两类引擎共享前面的提取、分段、能力抽取和忠实度校验结果，修改渲染层时无需重复读取书稿。
高级技巧：开发自定义体裁插件
自定义插件应放在 bookleme/plugins/user/<genre_id>.py。项目要求插件声明关键字段；缺少必要字段时会拒绝加载。
state_machine：定义流程状态与转换。output_contract：定义产物必须提供的输出。hard_constraints：定义不可违反的规则。anti_patterns：列出应避免的错误行为。voice_calibration：定义语气、称谓、禁用语和结论归属。copyright_profile：声明与版权控制相关的配置。trigger_words：提供 3 至 5 个中文触发词。eval_prompts：提供评测提示，其中至少包含一个负例。
在编写插件前，建议阅读插件规范；完成后使用 plugin validate 进行验证。不要通过插件绕过忠实度检查、版权硬门或负例拒答要求。
S0–S9 流水线如何工作
- S0–S2：登记输入、确定性提取、归一化并进行中文分段，不依赖固定的英文 Chapter 标记。
- S3：根据 12 个特征进行体裁路由；遇到歧义时可以自动选择双引擎。
- S4：抽取原子能力，可使用确定性抽取器和可选的 OpenAI 兼容 LLM 抽取器；缺少配置时会自动回退。
- S5：逐字校验引文，维护 claim ledger，并计算忠实度指标。
- S6：根据插件渲染知识包或行为 Skill，这是双引擎真正分流的位置。
- S7–S9：执行综合校验、幂等安装和冒烟评测。
S3 与 S4 都以 S2 的结果为输入，并可并行工作。两种引擎共享 S1、S2、S4 和 S5 的中间表示，避免重复读取和抽取。
实践建议
- 先用项目自带的合成书稿熟悉命令，再处理真实书籍。
- 不确定产物类型时使用
--engine auto；需要同时比较两种结果时使用both或--no-router。 - 每次修改插件或模板后都运行产物校验和单元测试。
- 对书中没有提供的信息保留拒答能力，不要用模型常识补齐来源缺口。
- 不要提交书籍原文、封面或扫描件到仓库，也不要将默认私有的第三方书籍产物直接公开。
- 阅读忠实度文档与版权文档，了解指标和发布边界。
当前边界
BookLeme 当前处于 M0–M3 阶段。coach_dialogue 和 knowledge_reference 已实现，但专业分析与决策清单插件仍在后续路线图中。LLM judge 尚未接入，部分相关指标仍为 null。使用时应区分已经实现、已经实测和仍待验证的能力。
结语
BookLeme 将“读书”转化为一条可测试的工程流水线：先提取和分段，再抽取能力、校验忠实度，最后渲染为知识包或行为 Skill。完成首次编译后，建议把校验、测试、权利声明和版权检查纳入固定流程，从而在复用书中方法的同时保留来源边界与可验证性。