第零世界 · 电子实体书转换器（zeroworld-ebook）

把任意格式文档（PDF / Markdown / Word / PPT / Excel / HTML / EPUB / TXT / 图片）转成一本
第零世界品牌样式的电子实体书 PDF：A5 开本、深墨蓝封面 + 朱砂红印章、思源宋体
Medium/SemiBold 正文、封面/扉页/版权页/编者序/目录/章节页/附录/结语/封底俱全。

> <skill-directory> 指本 skill 的目录，不是用户项目目录。

品牌规范（必须遵守）

装帧主题卡组（7 套皮肤）

像游戏选皮肤一样，让用户为这本书挑一套"衣服"；拿不定主意就开盲盒。每套主题是一组配色变量，一键换掉封面、印章、纸张与正文墨色的整体气质。

> 交互建议：生成前问一句——"这本书想穿哪套衣服？我可以盲盒随机抽一套给你惊喜。"
> 查看全部皮肤：python3 <skill-directory>/assets/build_book.py --list-themes

环境前置（首次使用一键搞定）

开箱即用：跑一次 install.py，自动检测并安装全部环境。

python3 <skill-directory>/assets/install.py           # 检测 + 自动安装 + 报告
python3 <skill-directory>/assets/install.py --check   # 只检测，不安装

它会自动处理三件事：
1. Python 依赖：weasyprint / pdfplumber / python-docx / python-pptx / openpyxl / beautifulsoup4（缺则自动 pip install）
2. GTK3 运行时（仅 Windows，WeasyPrint 硬依赖）：检测到缺失会提示 winget 安装命令
3. 中文字体（思源宋体 Noto Serif SC）：检测到缺失会给出下载/apt 命令

跑完看到 ✅ 环境全部就绪 即可出书。若仍有报错，按脚本末尾的提示逐条处理。

手动安装（不想用脚本时，按平台二选一）

通用 Python 依赖（两个平台都要）：

pip3 install weasyprint pdfplumber python-docx python-pptx openpyxl beautifulsoup4

Linux（Debian/Ubuntu）：

# 中文字体全字重（清晰度核心，含 Medium/SemiBold/Black）
DEBIAN_FRONTEND=noninteractive apt-get install -y fonts-noto-cjk-extra
# FontConfig 全开 hinting（可选优化，提升小字号锐利度；install.py 会给出配置内容）
sudo tee /etc/fonts/local.conf >/dev/null <<'EOF'
<?xml version="1.0"?>
<fontconfig>
  <match target="font">
    <edit name="hinting" mode="assign"><bool>true</bool></edit>
    <edit name="hintstyle" mode="assign"><const>hintfull</const></edit>
    <edit name="autohint" mode="assign"><bool>false</bool></edit>
    <edit name="antialias" mode="assign"><bool>true</bool></edit>
    <edit name="rgba" mode="assign"><const>none</const></edit>
    <edit name="lcdfilter" mode="assign"><const>lcddefault</const></edit>
  </match>
</fontconfig>
EOF
sudo fc-cache -f

Windows：

# 1. 安装 GTK3 运行时（必装！WeasyPrint 在 Windows 依赖 Pango/GLib，没有它 import 就报 OSError: cannot load library 'libgobject-2.0-0'）
winget install --id=tschoonj.GTKForWindows -e --source winget --silent
# 装完默认在 C:\Program Files\GTK3-Runtime Win64\bin

# 2. 每次运行前把 GTK 的 bin 加进 PATH（新装的运行时不会自动进当前进程的 PATH）
#    PowerShell:  $env:PATH = "C:\Program Files\GTK3-Runtime Win64\bin;" + $env:PATH
#    Bash:        export PATH="C:/Program Files/GTK3-Runtime Win64/bin:$PATH"

# 3. 安装思源宋体：推荐 Google Fonts 的 Noto Serif SC（可变字体，含 400/600/700 字重）
#    下载 .ttf 后双击安装，或复制到 %LOCALAPPDATA%\Microsoft\Windows\Fonts（当前用户）
#    地址：https://fonts.google.com/noto/specimen/Noto+Serif+SC
#    ⚠️ 注意字体名差异：Windows 上装的多是可变字体，family 名是 "Noto Serif SC"，
#       而 Linux 的 fonts-noto-cjk-extra 装的是 "Noto Serif CJK SC"。两个名字不一样！
#       assets/book.css 的字体栈已同时包含两者做回退，无需手动改。

> Windows 没有 FontConfig，跳过 hinting 配置这一步。三个关键依赖：GTK3 运行时（含 PATH）+ Noto Serif SC 字体 + Python 包，缺一都会失败或字体回退成雅黑。

执行流程（五步）

> ⚠️ 执行顺序固定，不可跳步：Step 1 → 2 → 3 → 4（定制台）→ 5（生成）。
> Step 4 的 3D 定制台是强制必经环节，不是可选项：book.md 生成后，必须立即执行 prepare_designer.py 生成定制台副本，并用 present_files 打开给用户；等用户在定制台里点「审阅/正式生成」拿到 book_params.json 后，才进入 Step 5 生成 PDF。除非用户在你准备打开定制台之前就明确说"不用调/直接出书"，否则一律先开定制台。看到"生成 book.md 后"这句话，你接下来的动作就是打开定制台，而不是生成 PDF。

Step 1 — 提取文本

按输入格式选择提取方式：

Step 2 — 审读与改写（正文默认不动，两种模式）

提取出的文本往往有两个问题：结构残缺和AI 腔。这一步由你（Claude）来做，但要遵循一条铁律：

> 用户的正文内容默认不能动。 改的是结构、排版和个别明显的 AI 腔措辞，不是重写内容。所有事实、数字、观点、案例一律原样保留。任何改动前先向用户确认。

两种改写模式（先问用户选哪种）：

• 模式 A · 维持正文（默认，首选）：只做最小整理——补全残缺结构、清掉格式残留（表情符号、编号）、拆开大段流水、删掉个别过重词（"赋能/闭环/碾压/降维打击"等）。内容一字不改。 适合文稿质量本身不错的情况。
• 模式 B · AI 结合出版格式补充修改：用户明确要求时，才在维持原文干货的基础上，按正式出版书的格式补写——加章节引语、过渡句、小标题、结语，把口语化段落整理成书面语。但补写部分要标注或单独列出给用户过目，不得悄悄塞进正文。

具体做法：

1. 先通读全文，列出处理建议清单（展示给用户，不要直接改）：
   - 结构缺口：哪些章节只有标题没正文、表格丢失、结语被截断 → 逐条列出"第 X 章缺 XX，我打算按上下文补写 XX 大意"
   - AI 腔重灾区：挑出最典型的 5–10 处（空洞金句、对仗口号、"你应该"式说教），每处给出"原文 → 拟改为"的对照
   - 拿不准的事实/数据：明确标注"此处原文缺失，我将标注为示例"而不是编造
2. 用户确认后，才动笔：
   - 拆散"不是 X，而是 Y"的对仗句式
   - 用第一人称 + 具体场景替代抽象口号
   - 长短句交错，避免每段等长
   - 删除"赋能 / 闭环 / 抓手 / 复利效应会越来越明显"等空洞金句
   - 祈使句"你应该"改为"如果你…会比较好"
   - 保留全部干货信息，只改表达，不增删事实
3. 结构化：按下方"规范化书稿"格式整理。

Step 3 — 规范化为 book.md

书稿需包含 YAML front-matter 与结构化的 Markdown：

---
title: 书名
subtitle: 副标题
tagline: 封面一句话
author: 作者
publisher: 第零世界
year: 2026
isbn: "978-7-XXXX-XXXX-X"
price: "49.80 元"
seal: 印章四字
blurb: |
  欢迎大家来知识星球，搜索第零世界，我是星主福流，欢迎您的到访。
---

# 编者序（可选）

# 前言（可选）

# 第一章 章名（支持"第一章"与章名同行，或分两行 ##）
> 章首引语（可选）

### 1.1 节号
#### 节名（可选，支持 h3/h4 结构）
正文段落、列表、表格、引用块…

# 附录一（可选）

# 结语（可选）

> 封面信息单元（# 书名 + 副标题 + tagline）可保留在 front-matter 之后，
> 脚本会自动跳过与 title 相同的一级标题单元。

> 🛑 Step 3 到此结束。现在停下，不要生成 PDF。下一步是 Step 4 打开定制台。

Step 4 — 【强制】3D 定制台（封面定制 + 正文定制）→ 审阅 → 正式生成

这是 v2 的核心交互环节，强制必经，禁止跳过。生成 book.md 后，你的下一个动作必须是：执行 prepare_designer.py 生成定制台副本，然后 present_files 打开给用户。不要直接跑 build_book.py 生成 PDF——等用户在定制台里点「审阅/正式生成」拿到 book_params.json 后，才生成 PDF。定制台把封面和正文的定制都收进来，用户在浏览器里一次搞定，最后点按钮出书。

① 生成"带正文"的定制台副本（关键：先把书稿注入预览器）：

python3 <skill-directory>/assets/prepare_designer.py book.md

这会读 designer.html 模板 + book.md 内容，生成 <书名>_定制台.html。然后必须用 present_files 打开这个生成的副本文件（路径是 book.md 同目录下的 <书名>_定制台.html），不要打开 assets/designer.html 模板——模板里没有注入书稿，正文区会是空的。

> ⚠️ 正文加载三重保障（正文区若为空，按顺序用后两种）：
> 1. 自动注入：prepare_designer.py 把 book.md 全文 base64 编码替换模板占位符，前端 atob 解码填入。
> 2. 手动导入：定制台正文区上方有「📂 导入 book.md」按钮，点它选 book.md 文件即可读入正文（最可靠，不依赖任何注入机制）。
> 3. 直接粘贴：正文区是文本框，直接把 book.md 全文粘贴进去也行。
>
> Claude 生成 book.md 后，务必把 book.md 也作为产物一并告知用户（或 present_files 出来），这样用户无论走哪种方式都能把正文弄进定制台。若自动注入在用户环境失效，明确提示"点『导入 book.md』选这个文件"。

用户打开后看到两个功能块：

• 🎨 封面定制：装帧主题（7 皮肤点选/盲盒抽卡）、微调配色（封面深/浅色、印章色、描金色）、书籍信息（书名/副标题/作者/出版方/年份/定价/印章/ISBN/封底简介）
• 📖 正文定制：正文排布（纸张底色、正文墨色、字号 11–15pt、行距 1.5–2.0、首行缩进）+ 正文内容编辑区（书稿 Markdown 全文，可直接预览和修改文字）

左侧始终是一本可拖拽旋转的 3D 书，调封面/纸张色时实时换肤、纸页变色。

> 💾 定制台的参数（主题/配色/排布/书籍信息/正文修改）会自动保存到浏览器 localStorage，切换窗口、刷新页面都不会丢；只要在同一个浏览器/预览面板里，回来时设置仍在。

② 用户确认后点按钮：

想让点按钮直接出 PDF（免去手动传 json）？先起本地生成服务：

# 生成定制台副本的同时，后台起一个本地服务（Windows 记得先 export GTK PATH）
python3 <skill-directory>/assets/generate_server.py 8899 &
# 或前台起一个，另开终端： python3 <skill-directory>/assets/generate_server.py

服务跑起来后，定制台点「审阅 / 正式生成」会直接 fetch 本地服务，由服务调 build_book.py 生成 PDF 并回传下载，用户不用再手动把 json 丢给 Claude。服务没起时，按钮自动回退到导出 book_params.json（下面第 ③ 步流程仍可用）。

导出的 book_params.json 包含：theme + custom（含正文排布）+ meta + body（用户在定制台里改完的正文全文）。

③ 回退路径：Claude 手动执行（服务直出 PDF 时此步可跳过；拿到 book_params.json 后，无需再指定 --md，正文从 body 字段来）：

python3 <skill-directory>/assets/build_book.py --params book_params.json

--params 一次吃进 theme + custom + meta + body，等价于"用户定好的所有东西"打包传入。不走定制台时，也可纯命令行：

python3 <skill-directory>/assets/build_book.py --md book.md \
  [--theme zeroworld] \
  [--custom "brand=#c9a05a" --custom "body-size=14pt" --custom "body-leading=1.8"] \
  [--out 输出.pdf] \
  [--title 书名] [--author 作者] [--publisher 第零世界] \
  [--tagline 一句话] [--price 定价] [--seal 印章四字] [--blurb 封底简介]

• 换肤：--theme zeroworld|ink|minimal|forest|ocean|ember|royal（默认 zeroworld）
• 开盲盒：--theme random（从全部主题里随机抽一套，生成时打印"抽中了 XX"）
• 微调：--custom "变量=值" 可多次传入。封面变量：brand（印章/强调色）、cover-accent（描金）、cover-faint（浅金）、cover-bg（封面渐变底）；正文排布变量：paper（纸张色）、ink（正文墨色）、body-size（字号）、body-leading（行距）、body-indent（首行缩进）
• 看卡组：python3 <skill-directory>/assets/build_book.py --list-themes
• 元数据优先：CLI 参数 > --params 的 meta > front-matter > 默认值（作者=福流，出版=第零世界）
• 不写 --out 时输出到 book.md 同目录 <书名>_实体书版.pdf
• 样式默认读取 book.md 同目录的 book.css，缺失时回退到 assets/book.css

> 默认必须先打开定制台（走上面的 ①→②→③ 流程）。只有用户明确说"直接用默认/别调了/直接出书"时，才跳过定制台，直接 --theme zeroworld 生成 PDF。

Step 5 — 质检（必须，跨平台统一用 Python）

Poppler 工具（pdfinfo/pdffonts）只在 Linux/macOS 有，Windows 没有，所以质检统一走 Python（依赖已装的 pdfplumber）：

python3 -c "
import pdfplumber, sys
pdf = pdfplumber.open(sys.argv[1])
w, h = pdf.pages[0].width, pdf.pages[0].height
print(f'页数: {len(pdf.pages)}, 尺寸: {w:.0f}x{h:.0f}pt (A5≈420x595pt)')
print('封面文字抽查:', (pdf.pages[0].extract_text() or '')[:80])
" 输出.pdf

再抽查两项：
- 用 Read 工具打开输出 PDF，目视确认封面、扉页、目录、正文页、封底无排版崩坏（这是跨平台最可靠的核对方式）。
- 页数/尺寸符合预期（A5 = 420×595pt，页数与 book.md 体量匹配）。

全部通过后，用 present_files 把 PDF 呈给用户预览。

常见问题

交付物

• 最终：<书名>_实体书版.pdf（默认输出到 book.md 同目录，或用 --out 指定到用户想要的目录）
• 书稿：book.md（务必一并交给用户，可编辑，也是定制台"导入正文"的输入文件）
• 定制台副本：<书名>_定制台.html（present_files 打开供用户调封面/正文）
• 调试：book.html（可选）