把整本非虚构书籍转成一份"读者语言"的单文件 HTML 导读报告。AI 负责按规范撰写 Markdown 内容，程序负责把它渲染成带左导航、章节折叠、杂志风的可阅读报告；最终交付一个 HTML，不把原书正文嵌入报告。
读完整本书是件重事。book-xray 想做的是：先用一段"概览"回答全书在讲什么、值不值得读、怎么读；再为每一章写一份"透析"，说清本章结论、问题缘起、论证展开、关键概念、实践方法与局限。
整个流程分两边：AI 按规范写 Markdown，程序按规则合成 HTML。AI 不写 JSON、不碰样式；分组、顺序、标题这类结构信息只维护在 manifest.json 里。这一分工让内容输出可以重复利用、可以人工修改、也可以让别的渲染器代为消费。
- 单文件 HTML 产出：一份自包含的 HTML 文件，桌面与移动端均可阅读。
- 杂志风版式：左侧导航、章节折叠卡片、概览在页面内滚动展示。
- AI 与渲染分离：AI 只产 Markdown，程序负责样式与校验，便于替换与二次渲染。
- 多书源支持：EPUB、TXT、Markdown 与文本型 PDF（扫描版需先做 OCR）。
- 结构化产出：概览层六个固定模块，每章六段固定结构，全书判断必须有章节证据支撑。
整套流水线分成六步：
- 提取与建档：运行
scripts/extract_book.py解析书脊与正文，生成manifest.json、metadata.json、抽取后的章节文本与工作目录。 - 确认分析目录：优先采用原书自带目录；不可靠时通读全文重建。导航的分组与顺序完全跟随原书，一次性写入
manifest.json。 - 逐章精读：按原书顺序逐章精读，每章一次性写一份 Markdown，每章六段（本章结论、问题缘起、论证展开、关键概念、实践方法、局限与批判）。
- 撰写概览：所有章节完成后，再综合全书写概览六模块（全书主旨、核心结论、全书架构、价值评估、阅读指南、概念速览），每条判断必须有章节证据。
- 渲染：运行
scripts/render_md.py把 manifest 与 Markdown 合成最终单文件 HTML。 - 自检与收尾：运行
scripts/check_report.py校验模块齐全、版式合规。
book-xray 是一个通用的 AI Agent 技能（Skill）：以 SKILL.md 为入口，任何遵循 Agent Skills 约定的 AI 环境都可以直接调用，WorkBuddy 是其中之一。
把本仓库克隆或下载到技能的安装目录即可。以 WorkBuddy 为例：
git clone https://github.com/tunggian/book-xray.git ~/.workbuddy/skills/book-xray/其它支持 Agent Skills 的环境，把仓库放到各自约定的技能目录（以 SKILL.md 所在目录为单位）即可。触发方式与入口配置见 agents/openai.yaml。渲染报告需要 Python 3.10+ 与 markdown 库（pip install markdown），缺失时脚本会给出提示。
book-xray/
├── SKILL.md # 技能入口与硬性原则
├── agents/
│ └── openai.yaml # 技能调用配置
├── scripts/
│ ├── extract_book.py # 提取书脊与正文，生成 manifest
│ ├── render_md.py # 渲染 Markdown 为单文件 HTML
│ └── check_report.py # 自检脚本
├── references/
│ ├── workflow.md # 工作流细则
│ ├── analysis-schema.md # 分析 schema 说明
│ ├── chapter.schema.json # 章节 JSON schema
│ ├── report.schema.json # 报告 JSON schema
│ ├── evidence-rules.md # 证据规则
│ └── quality-checklist.md # 质检清单
├── assets/
│ └── report-template.html # 渲染模板
├── examples/
│ ├── 刘擎西方现代思想讲义-全书导读.html # 真实演示报告
│ └── demo-screenshot.png # 演示截图
├── README.md
├── CHANGELOG.md # 更新日志
└── .gitignore
全书主旨、核心结论、全书架构、价值评估、阅读指南、概念速览。每模块用一级标题，模块内部用三级标题加正文段落，不使用无序列表。
本章结论、问题缘起、论证展开、关键概念、实践方法、局限与批判。每段对应一个二级标题，论证展开与关键概念等核心模块用三级标题组织。
完整的 schema、证据规则与质检清单见 references/ 目录。
下面截图来自一份真实的导读报告，《刘擎西方现代思想讲义》。完整 HTML 在 examples/刘擎西方现代思想讲义-全书导读.html，下载后用浏览器打开即可阅读。
可读性：新增"好读性五则"，约束导读从信息摘要转向可读的叙述。钩子开场（禁止平铺与"你有没有发现"式万能套话）、少而深（每章只讲透 1-3 个关键点）、例子用原书的不发明比喻、口语化克制、金句意识余味收尾。明确"导读不是内容压缩包"的定位。
移动端：目录按钮按需出现，向下滚动隐藏、向上滚动显示；侧边栏支持点击非侧边栏区域（遮罩或正文）直接关闭，打开时自动隐藏目录按钮。
其他：概览层与每章透析的模块写作要求逐项细化；质检清单新增好读性五则逐条自查。
完整变更历史见 CHANGELOG.md。
- 不支持扫描 PDF 的 OCR，需先做文字识别。
- 不处理 DRM、加密或严重乱码的书籍。
- 单章长度超过模型可靠上下文时，按作者小节切分，再综合，本过程不暴露在最终报告里。
- 渲染依赖
markdown库，缺失时给出提示，不会静默降级。 - 报告内含的评论与判断由 AI 基于原书内容生成，存在误读与遗漏的可能，请以原书为准。
本项目使用 MIT 许可证。
examples/ 下演示报告（刘擎西方现代思想讲义）对应的原书版权归原作者所有，仓库中收录的是 AI 对原书的分析性导读，仅作为本工具的演示用途。