Imported from crayon-ai/book-to-webpage (SKILL.md). Install upstream with npx skills add crayon-ai/book-to-webpage. Copyright stays with the author.

book-to-webpage

把书变成可交互的学习页。两阶段：先拆全书成本地知识库（<书名>.kb/），再据请求生成单页 HTML。

哲学

展示层是核心差异化：不是读书摘要，是把书中某主题做成可点击、可探索的页面。组件可交互，内容成叙事。
拆解逻辑复用 book-to-skill：提取器和拆解流程整体复制，不重新发明；但产出本地知识库（<书名>.kb/），不生成 skill、不安装到 ~/.claude/skills/。
散布内容要全面聚合：某主题散布全书时，用 Topic Index 定位所有相关章，全部纳入，不遗漏。

两种运行入口

首次处理一本书：跑阶段 1，生成 <书名>.kb/ 知识库。
已有知识库后生成网页：跑阶段 2，按请求产出单页 HTML。

文件结构

本 skill 附带以下预制资产，Agent 在渲染时引用：

文件	作用	用法
`templates/base.html`	①骨架层：页面壳、CSS 变量、布局、移动端断点、所有组件基础样式	抄，替换 `{{...}}` 槽位（含 `{{theme_style}}`/`{{theme_name}}`）
`templates/components.md`	②组件层：每个组件的 HTML/CSS/JS 范式 + 数据槽位	按 signature 挑范式，抄+填数据
`templates/themes/`	③主题层：4 个 `.css`（暖纸典藏/极简学术/夜读深空/东方水墨）+ `README.md` 目录	选一个，整段注入 `{{theme_style}}`
`scripts/extract.py`	提取器入口（复制自 book-to-skill）	阶段 1 跑
`scripts/extractor/`	提取器包（复制自 book-to-skill）	阶段 1 用

阶段 1：全书拆解（复制 book-to-skill 流程，改产出物）

前提： 用户提供了书文件（PDF/Markdown/EPUB等）。

Step 1.0 校验输入

支持格式同 book-to-skill：.pdf、.epub、.docx、.txt、.md、.html、.rtf、.mobi、.azw。

无输入则提示：book-to-webpage 需要一本书的文件路径。

Step 1.1 提取全文

SCRIPT="$HOME/.claude/skills/book-to-webpage/scripts/extract.py"
python3 "$SCRIPT" <书文件路径> --mode text

产出 <workdir>/book_skill_work/full_text.txt + metadata.json。读 metadata.json 确认页数、字数、token、章节数。

如果提取失败，跑 python3 "$SCRIPT" --check 诊断依赖，给安装建议。

Step 1.2 成本预估并确认

报页数/字数/预估 token 与价格，等用户确认再继续。

Step 1.3 分析结构（复制 book-to-skill Step 3）

读 full_text 前 8000 字 + metadata 章节检测，识别：

书名、作者
章节结构（中文"第X章"或英文"Chapter N"、ToC）
核心领域

Step 1.4 REPL 式切片拆解

全书 >50k token 时禁止整体读入。 用 grep 定位章节边界，sed 只切当前要写的那章：

grep -n -E "^\s*(第[一二三四五六七八九十百零0-9]+[章节回]|Chapter [0-9]+)" full_text.txt | head -60
sed -n '<start>,<end>p' full_text.txt

Step 1.5 生成章节摘要（复制 book-to-skill Step 7 模板）

每章生成 <书名>.kb/chapters/ch<NN>-<slug>.md，字段：

Core Idea（1-2 句）
Frameworks Introduced（命名框架 + 何时用 + 怎么用，保留作者精确命名）
Key Concepts（5-10 个术语，各一句定义）
Mental Models（"用 X 当 Y"）
Anti-patterns（要避免什么 + 为什么失败）
Worked Example（重现作者亲算的一个例子）
Key Takeaways（3-7 条）
Connects To（关联其他章/外部概念）

自适应深度（默认中文社科书 = text + study = 1000-1800 token/章）：

	reference	study
text	800-1200	1000-1800
technical	1200-1800	2000-3000

Step 1.6 生成支撑文件（复制 book-to-skill Step 8 规范）

glossary.md：全部术语序排，**术语** — 定义（第N章），≤1500 token
patterns.md：全部技术/模式，## 模式名 / 何时用 / 怎么做 / 权衡，≤2000 token
cheatsheet.md：决策层——决策规则（当X做Y因为Z）、决策树、权衡矩阵、阈值，≤1200 token

Step 1.7 生成 INDEX.md（取代 book-to-skill 的 SKILL.md，不注册为 skill）

关键改动：book-to-skill 这里生成 SKILL.md；我们生成 INDEX.md（知识库导航）。含：

书名/作者/页数/章数/生成日期
Core Frameworks（~2000 token：最重要命名框架）
Chapter Index（表：章号→标题→关键框架）
Topic Index（序排：术语/框架 → 出现在哪几章）★阶段 2 关键
支撑文件链接

Step 1.8 质量规则

提取结构非摘要；保留作者精确命名；密度优先于完整度；从业者口吻（"用 X 当 Y"）；前置重要内容；章节按需加载；绝不照抄原文。

产物结构

<书名>.kb/
  INDEX.md          ← 知识库导航（常驻核心 ~4K）
  chapters/ch<NN>-*.md  ← 章节摘要
  glossary.md  patterns.md  cheatsheet.md
  full_text.md     ← 原文（供阶段 2 grep）
  metadata.json

这是本地知识库，不写到 ~/.claude/skills/，不生成 SKILL.md。

阶段 2：请求 → 网页

前提

阶段 1 已生成 <书名>.kb/。如果不存在，先跑阶段 1。

运行模式：常驻核心 + 按需深挖

INDEX.md 是常驻小核心（~4K），含 Core Frameworks + 章节索引 + 主题索引。章节文件按需加载，不全读。这与 book-to-skill 的查询机制一致；区别仅在我们把"文字回答"换成"交互 HTML"。

Step 2.1 判定请求模式（三选一）

模式	触发条件	取材来源	产出
① 全书概述	用户说"概述全书/讲讲这本书"，无主题	读 INDEX.md Core Frameworks + cheatsheet	概述页（骨架视图）
② 主题聚合（默认）	用户指定主题 / 说"做一页xxx"	查主题索引 → 两级检索（§2.2）	主题深度页
③ 单章深读（可选）	用户指定章号	读该章摘要 + 该章原文	单章页

用户指定主题时，先 grep full_text.md 验证书中确有相关内容；命中 0 → 明确告知"本书未涉及该主题，建议尝试以下相关主题：…"，绝不瞎编。

Step 2.1b 主题处理（无需用户选择）

HTML 页面内置全部 6 套主题（warm-paper/minimal/dark/ink-wash/vintage-editorial/paper-ink），通过右上角下拉菜单实时切换，默认使用 warm-paper。用户可在浏览器里自己切换，无需 Agent 生成前询问。

如果用户明确点名某主题（如"用极简风格"）→ 把 HTML 中 <body data-theme="..."> 的初始值设为对应主题，<select> 的 selected 同步调整。否则默认暖纸典藏。

6 套主题的完整 CSS（:root 基准 + 5 个 [data-theme="X"] 覆盖块）直接写入 HTML 的 <style> 中，不依赖外部文件。主题目录见 templates/themes/README.md。

Step 2.2 主题聚合的两级检索（关键差异化）

第一级（结构化）：读 chapters/ 里主题索引指向的章节摘要
                  → 框架/概念/反模式等结构化要点
第二级（原汁原味）：grep full_text.md 原文散落表述
                  → 具体论述/作者原话/数据
合并去重重组 → 完整主题视图

两级都要：第一级保结构，第二级保全面。这是相对 book-to-skill（只读摘要）的强化，确保主题页囊括书中所有对该主题的论述。

Step 2.3 重组（散碎 → 流畅叙事）

去重：同一观点在多章重复的，合并成一处
归类：按因果/对比/演进逻辑排，不按章节顺序
改写：用自己的话重述，但保留作者精确命名（框架名/术语不改）
补衔接：观点间加过渡句，形成可读叙事，不是观点清单

Step 2.4 结构化为 JSON 内容契约

按模式产出 JSON。meta.mode 字段标识模式，决定后续组件挑选。

theme 模式 JSON：

{
  "meta": {"book": "...", "author": "...", "mode": "theme", "theme": "...", "sources": ["ch03","ch05"]},
  "hero": {"eyebrow": "...", "title": "...", "lede": "...", "thesis": "..."},
  "sections": [
    {
      "id": "past", "label": "过去20年",
      "lead": "...",
      "notes": [{"title": "需求被释放", "body": "..."}],
      "signature": "causal_chain",
      "chain": [{"id": "tax", "label": "分税制", "body": "..."}]
    }
  ],
  "questions": [{"title": "...", "hint": "..."}]
}

sections[].signature：决定该分区用哪个特色组件（causal_chain / type_selector / matrix / timeline / decision_tree / questions）
sections[].lead：段首引语（衔接层，Agent 现写）

overview 模式 JSON：

{
  "meta": {"book": "...", "author": "...", "mode": "overview"},
  "hero": {"eyebrow": "...", "title": "...", "thesis": "..."},
  "frameworks": [{"name": "土地财政", "oneLine": "...", "when": "..."}],
  "chapterMap": [{"ch": "ch01", "title": "...", "role": "..."}],
  "conceptMap": [{"term": "土地财政", "links": ["ch03","ch05"]}],
  "decisionRules": [{"when": "...", "do": "...", "because": "..."}]
}

每个顶层数组对应一个概述专用组件。

Step 2.5 挑组件（按内容性质决策，非简单映射）

先判断内容性质，再选最合适的组件。 一套主题内容往往适配多种组件，Agent 需要根据内容的逻辑结构来挑选 1-2 个。

内容性质 → 组件决策矩阵

内容性质	判断依据	首选组件	备选
因果推进	有明显的"A→B→C→D"链条	`causal_chain`	accordion
历史演进	按时间顺序展开的事件	`timeline`	story_card
多类别并列	几类事物各有特点，适合分类比较	`type_selector`	matrix
多维权衡	需要对比选项在多个维度上的优劣	`matrix`	before_after
决策分叉	"如果X则Y，如果A则B"的条件逻辑	`decision_tree`	accordion
案例叙事	有具体人物/事件/情境的生动故事	`story_card`	quote_card
政策/制度变迁	同一个事物在某个节点前后的状态对比	`before_after`	timeline
核心论述（分层）	"先给结论再给论证"，需控制信息密度	`accordion`	decision_tree
重要原话	需要保留作者精确表述、有冲击力的原文	`quote_card`	story_card
读者自检	从知识到行动的转化	`questions`	decision_tree

挑选逻辑：

优先看内容的主要逻辑结构（因果/时间/分类/对比/条件），选最匹配的组件
如果内容中有特别生动的案例故事，优先用 story_card 呈现
如果想引用作者原话增加说服力，搭配 quote_card
多数主题配 2 个特色组件（一主一辅，互补呈现）

theme 模式固定：

核心固定（每页必有）：Hero + 一句话总论 + 分区导航（sticky Tab）

overview 模式固定：

核心固定 + 概述专用：frameworks 卡片网格 + chapterMap + conceptMap + decisionRules

从 templates/components.md 取对应范式，填入 JSON 数据。

Step 2.5b 嵌入追问入口（方案2 — 每个内容块内置深挖按钮）

每个带 data-source 的内容块（note / story / timeline-item / ba-col / accordion details / quote / explain / question）必须在内部末尾加上追问按钮：

<button class="deep-dive-btn" title="追问这个概念"
  onclick="openDeepDive('{{概念名}}','{{data-source值}}')">?</button>

{{概念名}} = 该块的标题/核心概念（如 隐性担保、土地财政）
{{data-source值}} = 与所在元素的 data-source 属性相同

按钮默认 opacity:0，hover 父元素时浮现。点击后弹出全局遮罩层，用户输入追问内容，提交后自动将上下文 prompt 复制到剪贴板。

base.html 已内置完整 JS（openDeepDive() 函数 + overlay + toast），Agent 只需在组件内加这行 HTML。

Step 2.5c 标注出处来源

每个内容块必须标注原文出处。 这既是学术诚信，也帮助读者溯源深入阅读。

出处信息格式

第X章 第Y节 · 约第N-M页

例如：第二章第二节 · 约第95-110页

标注方法（A + B 混合方案）

A — Margin 标记（默认可见，低调）： 每个有出处的 HTML 元素加上 data-source 属性：

<article class="note" data-source="第二章 第二节 · 约第95-110页">

样式自动处理：左侧 3px 细色条（hover 变蓝）、hover 时弹出 tooltip 显示来源。

B — 全局"显示出处"开关： 页面右上角固定按钮 "显示出处"，点击后所有内容块下方浮现灰色小字出处行。base.html 已内置此按钮和 JS 逻辑（srcToggle → body.show-sources），Agent 无需额外处理。

标注规则

每块内容必标：note、story、timeline-item、question、accordion details、quote、explain、ba-col 等都要带 data-source
页数估算方法：从 metadata.json 取总页数，按章节在全文中的位置比例估算页码范围。例如 306 页的书，第 2 章从全文 13% 位置开始、26% 位置结束 → 约第 40-80 页
精度要求：标注到"节约N-M页"即可，不要求精确到具体页数
同一来源合并：同一 Panel 内多个内容块来源相同时，每块仍标注（方便读者逐条溯源）

Step 2.6 三层渲染产出 HTML

三层叠加（关键！组件不够，还要衔接层）：

层	来源	谁做	占页面比例
① 骨架	`templates/base.html`	照抄，替换 `{{lang}}`/`{{title}}` 等	~20%
② 组件	`templates/components.md` 对应范式	照抄 + 填数据	~35%
③ 衔接	Agent 现写，受下方规则约束	生成：段首引语、过渡句、卡片标题重写	~45%

衔接层写作规则（必须遵守，决定页面质量）：

段首必有引语：每个分区/Panel 开头一句提纲挈领的话，不直接堆组件
卡片标题口语化重写：不照搬原文小标题，改成读者一眼懂的短句（如"土地变成财源"而非"地方政府土地出让收入机制"）
正文综合而非拼接：grep 来的散碎原文必须去重合并改写成连贯段落，禁止直接堆多段原文
组件间过渡：组件前后用一两句话承接，不让交互组件孤立出现
配色强调克制：红字只用在 eyebrow 和总论标记，不滥用

拼装流程：

读 templates/base.html 骨架
内联全部 6 套主题：把 :root 默认变量（暖纸典藏）+ 5 个 [data-theme="X"] 覆盖块整段写入 <style>，并设 <body data-theme="warm-paper">（用户点名某主题则改初始值）；同时加入主题下拉菜单 HTML + JS（<select class="theme-picker"> + localStorage 记忆）
设置 {{lang}}（中文书="zh-CN"）
设置 {{title}} = 《书名》- 主题
把 Hero HTML 片段填入 {{hero}}
把 Tab 按钮填入 {{tabs}}（{{component_styles}} 里设置 tabs 列数）
把各 Panel HTML 填入 {{panels}}
把 {{component_styles}} 设为组件专用 CSS
把 {{component_scripts}} 设为所有交互 JS
把 {{footer_note}} 设为脚注
输出 <书名>-<主题>.html
同步保存文本版：把 Step 2.3 重组后的完整叙事正文（连贯文本 + 作者原话 + 案例），另存为 <书名>-<主题>.md，与 HTML 同目录。内容含：Hero 标题/总论 + 各 Section 正文（去组件标记、纯可读叙事）+ 追问问题列表 + 出处来源标注。这是渲染前的那道完整叙事——不依赖 HTML 组件即可独立阅读，也方便后续引用/复用。

JS 安全规则（CRITICAL — 违反会导致页面按钮全部失效）：

用 function() 而非 =>：箭头函数在脚本标签内可能导致解析差异。始终用 document.querySelectorAll(".tab").forEach(function(t){ ... });
JS 字符串内禁用中文引号 ""："硬资产" 这种中文引号在 JS 字符串中可能被误读为字符串边界，导致 JS 执行中断。改为直接写 硬资产（去掉引号）或改用其他符号。
DOM 操作前加 null 守卫：var el = document.getElementById("x"); if (el) { el.onclick = ...; }
用 var 声明变量：不用 const/let，最大化浏览器兼容性。

Step 2.7 自检

自动化验证（Playwright）

生成 HTML 后，必须运行验证脚本：

node ~/.claude/skills/book-to-webpage/scripts/verify-page.js <输出文件路径>

该脚本自动检查：占位符残留、Tab 切换、Causal Chain、Type Selector、Accordion、Timeline、Before/After、Story Card、Quote Card、Questions、Source Toggle、移动端响应式、data-source 属性。

人工逐项验证

所有 Tab 可切换、所有按钮可点且有响应
无残留占位符（无 {{...}}、TODO、xxx、空数据块）
JSON 里每个声明的组件都真实渲染在 HTML 中
移动端（≤880px / ≤520px）不溢出
衔接层齐全（每分区有段首引语、卡片标题口语化、组件间有过渡）
每个内容块有 data-source 属性，出处格式正确（"第X章第Y节 · 约第N-M页"）
页数估算合理（根据 metadata.json 总页数按章节位置比例推算）
页面右上角"显示出处"开关可切换、tooltip hover 可显示

Step 2.8 清理工作目录

rm -rf "<workdir>/book_skill_work"

风格系统（主题换肤）

页面布局/交互完全不变，只通过 CSS 变量换皮。templates/base.html 把字体/底色/纸面 tint/强调色全部抽成变量（--font-body/--font-display/--bg/--surface/--ink/--red/--blue/--green/--gold/…），组件 CSS 只引用变量、不写死颜色。

6 套主题全部内联于每个生成的 HTML 页面中（templates/themes/*.css）：warm-paper（暖纸典藏·默认）/ minimal（极简学术）/ dark（夜读深空）/ ink-wash（东方水墨）/ vintage-editorial（复古编辑）/ paper-ink（纸墨风）。详见 templates/themes/README.md。
默认 = 暖纸典藏：宋体正文 + PingFang 标题、暖纸色纸面 #f8f2e7、红蓝绿金强调、径向金光晕背景。
实时切换：页面右上角内置主题下拉菜单，用户可在浏览器中一键切换 6 套皮肤，选择自动记忆（localStorage）。Agent 生成前无需询问用户偏好——除非用户明确指名某主题。
换肤机制：:root 保存默认变量（暖纸典藏），5 个 [data-theme="X"] 选择器覆盖对应主题的全部变量+组件微调。<body data-theme="..."> 控制当前生效主题。
单文件、零依赖：CSS/JS 全部内联
移动端自适应：≤880px 单列、取消 sticky；≤520px 字号缩减、chain 单列
无外部字体/图标/CDN：仅用系统字体

错误处理

场景	处理
PDF 多级回退全失败	报错 + 跑 `python3 scripts/extract.py --check` + 安装建议
提取出空文本	提示"可能是扫描版，建议用 Nutrient OCR"
用户主题书里没有	明确告知"本书未涉及该主题" + 列相关候选（grep 相邻关键词）
主题内容过少（<3处提及）	提示"仅 N 处提及，内容较少，建议换主题或合并相关主题"，不硬凑

不在本次范围

语义搜索（当前只用关键词 grep）
多主题站点（当前只做单主题单页）
主题内可调子参数（字号/圆角等微调，当前每主题一套固定美学）

About