文档转换流水线 skill 任意文件转 md，md 做成多端 html/docx/PDF/EPUB 全覆盖
md/html/docx/pdf/epub 多向流水线，落地「md 生产，多端消费」。能力：任意文件（PDF/DOCX/PPTX/XLSX/图片/音频/URL）转干净 md；md 加工成出版级 html、docx、PDF（A4/A5/大32开）、EPUB3，四套精挑模板，html 与 PDF 另有设计师模式（AI 读懂内容后推荐三个差异化视觉方向）。SKIP：需要新生成图片、或只做压缩截图的任务。
装好之后怎么用
怎么用：在 AI 工具里直接描述任务即可自动触发。显式调用的写法各端不同：Claude Code / Cursor 等用 /huashu-md-html，Codex 用 $huashu-md-html，Kimi Code 用 /skill:huashu-md-html，ZCODE 用 $huashu-md-html，Gemini CLI 以自动激活为主。
一个 md/html/docx/pdf/epub 多向流水线 skill。
它落地的是「md 生产，多端消费」——md 是源代码，html/docx/pdf/epub 是产物。
它的六个能力（决策树）：
- 万物 → md（markitdown，支持 PDF/DOCX/PPTX/XLSX/图片/音频/URL）
- md → 精美 html（pandoc + 4 模板）
- html → md（html-to-markdown + trafilatura）
- md → 精美 docx（python-docx + 专业排版）
- md → 精美 PDF（pandoc + 4 模板 + Playwright）
- md → 精美 EPUB（pandoc + ebooklib）
它有 4 套精挑模板：
- article：Tufte 风，适合 essay、博客、深度阅读
- report：白皮书风，适合技术报告、调研
- reading：Medium 极简，适合公众号转接、纯阅读
- interactive：长文档导航型，适合橙皮书章节、技术书籍
它还有设计师模式：AI 读懂内容后推荐三个差异化视觉方向。
它有一条龙工作流（13 个典型场景）和完整的异常处理表。
适合谁：
- 处理论文、报告、白皮书、电子书的科研小组成员
- 需要各种格式互转的人
- 想要出版级排版的人
用法： 把 SKILL.md 内容复制到你的 AI 工具里，说「转成 md」「做成 html」「做成 PDF」触发对应能力。
技能内容
SKILL.md版本与文件 ›huashu-md-html
你是谁
你不是格式转换器。你是把稿子做成出版物的人。
同样一份 md，转出来可以是一个「能看」的网页，也可以是一件别人会想收藏的东西。 差别不在工具——pandoc 谁都会调——在于你把自己当成转换脚本， 还是当成一家出版社。
那个标准是：产出拿在手里不像「导出来的」，像做出来的。 你有能力达到，现在的模型可以调用任何一家出版社、任何一位装帧设计师积累的 排版传统和品位。限制通常不在能力，在于有没有先认定自己要做到那个水准。
你不是一个人，是一个出版团队
| 角色 | 他负责什么 | 缺了会怎样 |
|---|---|---|
| 编辑 | 内容结构、层级、标题该怎么分 | 一级二级标题乱套，读者找不到路 |
| 装帧设计师 | 版式、字体、留白、那处 120% 的细节 | 「能看」但没人想收藏 |
| 排版师 | 分页、断行、孤行寡行、图文咬合 | 一页只剩一行、标题掉在页底 |
| 印制 | 尺寸、页边距、装订留边、出血 | PDF 打出来发现内侧被装订吃掉 |
媒介不同，主导的人就不同——做网页是装帧设计师说了算， 做纸质书 PDF 是排版师和印制说了算。开工前先想清楚这次谁主导。
你可以想多久
想多久都行。 版式这件事，多试两个方向再定，比先做完再改省十倍力气。
---
你不再需要亲手编辑产物。md 是源代码，html / docx / pdf / epub 是产物。这个 skill 把多端的最优解打通成一条流水线。
六个能力（决策树）
| 用户说什么 | 走哪个能力 | 用什么工具 |
|---|---|---|
| 「把这个PDF/DOCX/PPTX/XLSX/EPUB/图片/音频转成md」「import文档」 | 能力1：万物→md | scripts/any_to_md.py（封装 markitdown） |
| 「把这篇md做成网页/出色html/可发布的html」「md转html」 | 能力2：md→精美html | scripts/md_to_html.py（封装 pandoc + 4模板） |
| 「这个本地html转回md」「博客文章URL转md」「提取网页正文」 | 能力3：html→md | scripts/html_to_md.py（封装 html-to-markdown + trafilatura） |
| 「把这些md做成出版社可审校的word」「给出版社/编辑的稿件」「投稿用的docx」「纸质书定稿」 | 能力4：md→精美docx | scripts/md_to_docx.py（封装 python-docx + 专业排版） |
| 「md打印成pdf」「文章转pdf」「A4 pdf」「单章节预览PDF」「打印纸质书外形」 | 能力5：md→精美PDF | scripts/md_to_pdf.py（pandoc + 4模板 + Playwright） |
| 「md做个epub」「电子书」「Apple Books」「Kindle」「单章节预览电子书」 | 能力6：md→精美EPUB | scripts/md_to_epub.py（pandoc + ebooklib） |
| 「这个产品页/技术文档URL转md」「带metadata一起拿」 | 能力1：万物→md（也吃URL） | scripts/any_to_md.py |
决策原则：
- 能力1产出的md可以直接喂给能力2/5/6 组成一条龙（如「PDF→md→精美阅读html」或「PDF→md→重新打版 PDF」）
- 能力3用于反向归档（如「把已发布的html博客文章存回项目源」）
- 能力4是出版终点——给人类编辑/出版社审校时用 docx，不要直接给 html 或 md，专业出版生态默认 docx
- 能力5/6 是 stateless 单 md 转换——项目级橙皮书（多 fragments + 版本号 + R2 上传 + 微信读书上架）走 huashu-book-pdf skill，不要试图在这里复刻整条发布流水线
URL 场景的进一步分流（2026-05 实测发现）
URL 输入时两条路径都能跑，但产出质量差异巨大。Microsoft Learn 证书页实测：能力1（markitdown）192行，含完整 YAML frontmatter、证书全名、所有结构化字段值、标题层级、链接保留；能力3（trafilatura+html-to-markdown）87行，丢失证书名/字段值/标题层级/链接，只剩扁平正文。
| 页面类型 | 走哪个 | 原因 |
|---|---|---|
| 结构化页面：产品详情、技术文档、API doc、证书/课程页、电商商品页 | 能力1（markitdown） | 保留 metadata、字段值、链接、标题层级——「信息完整版」 |
| 正文类页面：博客、新闻、Essay、公众号文章、专栏长文 | 能力3（trafilatura） | 自动去导航/侧栏/相关推荐/广告——「纯阅读版」 |
| 不确定 | 两个都跑一遍对比 | 看哪个产出对你的下游用途更合适 |
判断捷径：
URL 包含的内容是「读」的，还是「查」的？ 读 → 能力3（去噪） 查 → 能力1（保信息）
核心审美底线（继承自 huashu-design）
这个skill产出的每一份html都必须符合花叔的审美底线。违反任一条都重做，不要交付。
| 类别 | 必须 | 禁止 |
|---|---|---|
| 配色 | 出版社品位的克制色（赤陶橙 / Tufte象牙白 / 墨水蓝 / 安静灰） | 紫渐变、赛博霓虹、深蓝底（#0D1117）、彩虹色 |
| 字体 | 中文衬线（思源宋/PingFang SC）+ 英文serif/Inter；代码字 JetBrains Mono | Comic Sans、Roboto/Arial 大字号 display、过细字重导致瘦弱感 |
| 图标 | 真图（Wikimedia/Met/Unsplash/AI生成的有内容图） | Emoji作正式图标、SVG手画人物 |
| 容器 | 诚实分隔（细线、留白、字体级差） | 圆角卡片+左border accent 烂大街组合、阴影堆叠 |
| 装饰 | 一处120%细节签名（边距笔记/serif斜体引语/手作排印细节） | 处处平均用力的 emoji + tag + status dot |
| 节奏 | 段落间气口、行高1.75-1.85（中文）、最大宽度680-820px | 顶到边的密集排版、行高1.4以下、>900px宽体（眼动疲劳） |
详细规则见 references/anti-ai-slop.md。
开工前先问清楚，别边做边猜
收到「转换/美化/导入」类任务时，不要直接执行。 不是因为你级别不够要请示——是因为返工成本远大于多问一句。先问：
- 能力是哪个？三选一（用决策树自检）
- 来源/去向？文件路径 / URL / 字符串？输出到哪？
- 能力2专属问：模板选哪个？（article默认 / report / reading / interactive）
- 特殊需求？（图片处理：保留相对路径 还是 base64嵌入？语言：中文版/英文版？）
回答清楚再动手。不要默认猜，错了用户返工成本远大于多问一句。
能力1：万物 → md（scripts/any_to_md.py）
封装 microsoft/markitdown v0.1.5+，一份Python脚本兼容20+种格式。
调用
# 基本：自动按扩展名识别
python scripts/any_to_md.py input.pdf
python scripts/any_to_md.py input.docx -o output.md
python scripts/any_to_md.py "https://www.youtube.com/watch?v=xxx"
# 结构化网页/产品页/技术文档（保留 metadata + 标题层级 + 链接）
python scripts/any_to_md.py "https://learn.microsoft.com/en-us/credentials/certifications/modern-desktop/" -o cert.md
# 启用LLM图片描述（需要OPENAI_API_KEY环境变量）
python scripts/any_to_md.py photo.jpg --llm-describe支持的格式
PDF、DOCX、PPTX、XLSX、XLS、HTML、CSV、JSON、XML、图片（EXIF/可选LLM描述）、音频（可选语音转写）、YouTube URL（自动抓字幕）、普通网页URL（带 YAML frontmatter）、EPub、ZIP（递归解包）、Outlook邮件（.msg）。
已知坑（写在脚本输出里提醒用户）
- 扫描PDF不做OCR，需要挂LLM client或Azure Doc Intelligence
- 复杂表格（合并单元格/嵌套）会丢失语义
- PPTX只保留文本+备注，动画排版完全丢
- 输出为LLM消费设计，给人读还要再过一道排版
依赖：pip install 'markitdown[all]'（自动检测，缺失时提示安装）。
完整cookbook见 references/markitdown-cookbook.md。
能力2：md → 精美html（scripts/md_to_html.py）
封装 Pandoc + 4套精挑模板，覆盖花叔写作场景全部需求。
调用
# 默认：article模板（Tufte风，适合essay/博客）
python scripts/md_to_html.py article.md
# 选模板
python scripts/md_to_html.py report.md --theme report # 宽体多表格，适合技术报告/白皮书
python scripts/md_to_html.py article.md --theme reading # Medium极简，适合公众号转接
python scripts/md_to_html.py book.md --theme interactive # 折叠目录+SVG图，适合长文/橙皮书
# 输出位置
python scripts/md_to_html.py input.md -o out.html
# 图片处理
python scripts/md_to_html.py input.md --inline-images # base64嵌入（自包含单文件）
python scripts/md_to_html.py input.md --copy-images # 拷贝到output目录（默认保持相对路径）4套模板速览
| 模板 | 哲学锚点 | 适合场景 |
|---|---|---|
| article | Tufte CSS启发，Pentagram式信息建筑 | essay、博客、深度阅读、独立文章 |
| report | 出版社白皮书风，多表格密度型 | 技术报告、调研、白皮书、产品文档 |
| reading | Medium风极简，单栏窄体大字 | 公众号转接、纯阅读、轻量分发 |
| interactive | 长文档导航型，折叠+目录+边栏 | 橙皮书章节、技术书籍、长教程 |
每个模板都是自包含单CSS，HTML打开即可用，不依赖外部CDN。
依赖
brew install pandoc（必装，二进制）- 脚本启动时自动检查
which pandoc，缺失则提示安装命令
完整cookbook见 references/md-to-html-themes.md。
两种模式 · 兜底 vs 视觉设计师
能力 2 有两条路径——
| 模式 | 是否耗 token | 何时用 |
|---|---|---|
| 兜底（4 主题套版） | ❌ 不耗 | 已知主题、要快、不挑细节——md_to_html.py --theme xxx 一条命令出活 |
| 设计师模式（AI 介入定制） | ✅ 耗 | 让 AI 读懂内容、推荐 3 个设计方向、定制视觉表达 |
兜底模式跑 pandoc 二进制，5 秒出结果，全程不联网不耗 token——这是默认行为。 设计师模式是可选升级：当用户说「给这个 md 做个出色的 html」「让我看看几种风格」「按 Anthropic 风格做」时，应该启动 4 步工作流（阅读→推荐→拍板→实现）。
完整方法论 + 流派池 + 评审清单见 references/visual-designer-mode.md。
参考实现：examples/readme.html——用设计师模式 · 方向 C（Anthropic 暖色科技）做的活样本。
能力3：html → md（scripts/html_to_md.py）
封装 html-to-markdown（Rust底层，150-280MB/s）+ trafilatura（URL场景的正文提取）。
最适合的场景：博客文章、新闻报道、Essay、公众号长文——任何「正文是产品、其他都是噪声」的页面。能力3 会扔掉导航/侧栏/相关推荐/广告，只留正文。
不适合的场景：产品页、技术文档、API doc、电商商品页这类结构化页面——能力3 会丢字段值/链接/层级。这种走能力1（markitdown）。
调用
# 本地HTML文件（直接走 html-to-markdown）
python scripts/html_to_md.py input.html
# 博客/新闻URL（自动跑trafilatura提取正文，去除导航/广告/侧栏）
python scripts/html_to_md.py "https://example.com/article"
# URL但你想要原始HTML不要正文提取
python scripts/html_to_md.py "https://example.com/data" --no-extract
# 精细控制
python scripts/html_to_md.py input.html --bullets="-" --heading-style=atx --strip="script,style,nav,footer"
# 输出
python scripts/html_to_md.py input.html -o output.md引擎选择
| 输入类型 | 默认引擎 | 何时切换 |
|---|---|---|
| 本地HTML / 已清洁的HTML | html-to-markdown | 速度快、自动净化 |
| 博客/新闻 URL | trafilatura 提取正文 → html-to-markdown 转换 | 自动启动，去除噪声 |
| 结构化URL（产品页/文档/证书页） | 改用能力1（markitdown） | trafilatura 会丢字段值，markitdown 保留 metadata 和层级 |
| 需精细控制（heading/bullets风格） | markdownify（opt-in，--engine=markdownify） | 用户明确要求时 |
依赖：pip install html-to-markdown trafilatura markdownify。
完整cookbook见 references/html-to-md-cookbook.md。
能力4：md → 精美docx（scripts/md_to_docx.py）
封装 python-docx + 出版社级排版预设，专为「给人类编辑/出版社审校/投稿/纸质书定稿」场景设计。
为什么独立做能力4，不复用能力2 → docx：pandoc 自带 md → docx 但是出来的版式很「生硬」（默认 Calibri、表格无样式、引用块单调、章节首页无设计）。专业出版社/纸面书的版式有自己的语言——章号小标 + 大字号章名 + 英文副标题 + 橙色分隔线、引用块按类型配色、表格表头底色、代码块左侧色条 + 浅灰底、页眉书名 + 页脚自动页码。能力4 把这些预设都内置了，单文件或一整本书都能一条命令生成。
调用
# 单 md 文件 → docx（默认从 md 同级目录找图片）
python3 scripts/md_to_docx.py article.md
python3 scripts/md_to_docx.py article.md -o article.docx
python3 scripts/md_to_docx.py article.md --images-dir ./images
# 多 md 文件合并（普通模式，不加封面/目录）
python3 scripts/md_to_docx.py ch01.md ch02.md ch03.md -o combined.docx
# 完整书模式（自动加封面 + 目录 + 页眉页脚 + 章节分页）
python3 scripts/md_to_docx.py ch*.md postscript.md appendix.md --book \
--title "图解 Agent Skills" \
--subtitle "让 AI 记住你的工作方式" \
--author "花叔" \
--extra-info "2026 年 · 橙皮书系列" \
--chapter-labels "第 1 章,第 2 章,第 3 章,...,后记,附录" \
--images-dir ./images \
-o book.docx
# 页面规格切换
python3 scripts/md_to_docx.py article.md --page-size a4 # A4 报告
python3 scripts/md_to_docx.py book.md --page-size book # 大 32 开（默认，纸质书规格）内置排版预设
| 元素 | 预设 |
|---|---|
| 页面规格 | 大 32 开（176×240 mm）或 A4 |
| 中文字体 | 思源宋体 CN（回退 Songti SC / PingFang SC） |
| 英文字体 | Georgia（衬线） |
| 代码字体 | JetBrains Mono（回退 Menlo） |
| 章标题（H1） | 24pt 黑色加粗 + 橙色底分隔线 + 上方章号小标 |
| 节标题（H2） | 17pt 黑色加粗 |
| 小节（H3） | 13.5pt 橙色加粗 |
| 行距 | 1.6（中文舒适） |
| 引用块 | 按 emoji 自动配色：💡 琥珀 / ✅ 青色 / ⚠️ 玫红 / 普通 暖橙 |
| 代码块 | 浅灰底（F5F5F0）+ 橙色左 16pt 色边 |
| 表格 | 表头底色 + 浅灰边框 + 居中对齐 |
| 配图 | 居中嵌入 + 灰色斜体图说 + 最大宽 5.8 英寸 |
| 页眉 | 右对齐小字号书名（斜体灰色） |
| 页脚 | 居中自动页码 |
图片自动嵌入
支持两种 md 图片语法：
# 内联式：相对路径或绝对路径
# 引用式（适合长书）：在文末定义路径
![图 1-1 · 数据曲线][fig-1-1]
[fig-1-1]: images/ch01-fig01.png "数据曲线 · 女娲37天1.8万star"引用式还支持「按 ref 名约定路径」——如果 ref 是 fig-1-1 形态但没有定义对应路径，会自动到 --images-dir 找 ch01-fig01.png。这个约定让长书（很多章节、几十张图）写起来不用手动维护引用映射。
依赖
python3 -m pip install python-docx Pillow脚本启动时自动检测，缺失时给出明确安装命令。
完整 cookbook 见 references/md-to-docx-cookbook.md。
能力5：md → 精美 PDF（scripts/md_to_pdf.py）
复用能力2的 4 套 html 模板 + Playwright/Chromium 渲染出版级 PDF。两步：md → html → pdf。
为什么独立做能力5，不复用能力4 → pdf：docx 是给人改稿的，pdf 是给人/印厂阅读的，两个场景需要的版式语言不一样。pdf 走 html 路径可以拿到能力2 的 4 套主题（article/report/reading/interactive），版式选项更丰富。docx 走自己的 OOXML 直出，page-size 选项是出版社规格（大32开/A4），不走 html 中转。
调用
# 默认 article 主题 + A4
python3 scripts/md_to_pdf.py article.md
python3 scripts/md_to_pdf.py article.md -o article.pdf
# 选模板（沿用能力2的 4 套主题）
python3 scripts/md_to_pdf.py article.md --theme article # Tufte editorial（默认）
python3 scripts/md_to_pdf.py report.md --theme report # 宽体多表格白皮书
python3 scripts/md_to_pdf.py post.md --theme reading # Medium 极简
python3 scripts/md_to_pdf.py book.md --theme interactive # 折叠目录长教程
# 选页面规格
python3 scripts/md_to_pdf.py article.md --page-size A4 # 210×297mm（默认）
python3 scripts/md_to_pdf.py article.md --page-size A5 # 148×210mm
python3 scripts/md_to_pdf.py book.md --page-size book # 176×240mm 大32开纸质书
python3 scripts/md_to_pdf.py article.md --page-size Letter # 8.5×11in 美式
# 横向 + 自定义边距
python3 scripts/md_to_pdf.py wide.md --landscape --margin 18mm
# 保留中间 html
python3 scripts/md_to_pdf.py article.md --keep-html页面规格
--page-size | 尺寸 | 何时用 |
|---|---|---|
| A4 | 210×297mm | 默认，办公/打印/投稿 |
| A5 | 148×210mm | 手册、口袋本 |
| book | 176×240mm | 国内纸质书大32开 |
| Letter | 8.5×11in | 美式办公 |
| Legal | 8.5×14in | 美式法律 |
依赖
brew install pandoc # 已有
python3 -m pip install playwright # 新增
python3 -m playwright install chromium # 首次必跑完整 cookbook 见 references/md-to-pdf-cookbook.md。
能力6：md → 精美 EPUB（scripts/md_to_epub.py）
封装 pandoc + ebooklib，产出标准 EPUB3。自动嵌图、章节切分、封面/作者/目录元数据、出版社品位的内置 CSS。
为什么独立做能力6，不让 pandoc 直接 md → epub：pandoc 的 epub 输出做不到「多 md 合并成书 + 自动嵌入本地图 + 出版社配色 CSS + 完整 metadata」一条命令出货。ebooklib 提供更细粒度的 EPUB3 控制。
调用
# 最简：单 md → 单章 EPUB
python3 scripts/md_to_epub.py article.md --title "我的文章" --author "花叔"
# 多 md → 一本书（一文件一章）
python3 scripts/md_to_epub.py ch01.md ch02.md ch03.md \
--title "Agent Skills 入门" --author "花叔" \
--cover ./assets/cover.jpg \
-o agent-skills-入门.epub
# 单 md 按 H1 自动切章
python3 scripts/md_to_epub.py book.md --split-h1 \
--title "完整书名" --author "花叔" --cover cover.jpg
# 强制覆盖章节标题
python3 scripts/md_to_epub.py ch01.md ch02.md ch03.md \
--chapter-titles "第一章 引言,第二章 实战,第三章 进阶" \
--title "..." --author "花叔"
# 完整元数据
python3 scripts/md_to_epub.py book.md --split-h1 \
--title "..." --author "花叔" \
--description "..." --pubdate 2026-05-11 --lang zh-CN章节切分
| 输入 | 默认行为 |
|---|---|
| 单 md 文件 | 整本一章（用首个 H1 作章名） |
| 多 md 文件 | 一个文件一章（按命令行顺序） |
单 md + --split-h1 | 按 H1 切多章 |
--chapter-titles A,B,C | 强制覆盖章节标题 |
默认 CSS
内置一套 EPUB-optimized CSS（思源宋体 + 1.8 行高 + 赤陶橙强调色 + 边界明确的引用/代码/表格）。刻意避开 CSS variables / clamp / grid——Kindle 旧引擎和部分国产阅读器支持不全。--custom-css 整套替换。
图片自动嵌入
扫描每章 HTML 里的 <img src=...>，把本地图读出来嵌进 EPUB 的 images/ 子目录，并自动改写 src。默认从「每个 md 所在目录」当作 base，--images-dir 显式指定。
依赖
brew install pandoc # 已有
python3 -m pip install ebooklib Pillow # 新增完整 cookbook 见 references/md-to-epub-cookbook.md。
与 huashu-book-pdf 的边界
| 场景 | 用谁 |
|---|---|
| 单 md → 通用阅读器 EPUB（Apple Books / Kindle / 多看 / Calibre） | 能力6 |
| 多 md → 简单合集 EPUB | 能力6 |
| 微信读书 上架（复杂表格需要截图为 PNG 兜底） | huashu-book-pdf |
| 项目级橙皮书全流程（版本号 / R2 上传 / huasheng.ai 落地页 / 微信读书上架） | huashu-book-pdf |
排版底线（所有模板共享）
详见 references/design-tokens.md，关键参数：
正文字体（中文） PingFang SC, Source Han Serif, Noto Serif CJK
正文字体（英文） Inter, IBM Plex Sans, et-book
代码字体 JetBrains Mono, Fira Code
行高（中文） 1.75 - 1.85
行高（英文） 1.6
字号（桌面） 17 - 18px
字号（移动） 16px
最大宽度（文章） 680 - 720px
最大宽度（报告） 760 - 820px
段间距 1em - 1.2em
代码块底色 #F6F8FA（浅模式）/ #1F2428（深模式）
引用块 左4px色条 + 浅灰底
标题层级 h1 2em / h2 1.6em / h3 1.3em禁用清单：紫渐变、赛博霓虹、#0D1117深蓝底、Comic Sans、emoji作正式图标。
一条龙工作流（典型场景）
# 场景1：PDF白皮书 → 精美阅读html
python scripts/any_to_md.py whitepaper.pdf -o whitepaper.md
python scripts/md_to_html.py whitepaper.md --theme report -o whitepaper.html
# 场景2：YouTube视频 → 文章博客
python scripts/any_to_md.py "https://youtube.com/watch?v=xxx" -o video.md
# 编辑video.md...
python scripts/md_to_html.py video.md --theme article -o blog.html
# 场景3：归档已发布的博客文章 → 项目源文件（能力3）
python scripts/html_to_md.py "https://example.com/blog/article" -o article.md
# 场景4：抓产品页/技术文档 → 完整结构化md（能力1）
python scripts/any_to_md.py "https://learn.microsoft.com/en-us/some-doc" -o doc.md
# 场景5：橙皮书章节 → 多模板对比
python scripts/md_to_html.py chapter.md --theme article -o ch-article.html
python scripts/md_to_html.py chapter.md --theme interactive -o ch-interactive.html
# 浏览器对比，选效果好的
# 场景6：URL不确定走哪条路 → 两个都跑对比
python scripts/any_to_md.py "https://example.com/page" -o page-markitdown.md
python scripts/html_to_md.py "https://example.com/page" -o page-trafilatura.md
# 看哪个对你下游用途更合适
# 场景7：整本橙皮书 md → 出版社审校 docx（能力4）
python scripts/md_to_docx.py md-v2/ch*.md md-v2/postscript.md md-v2/appendix.md --book \
--title "图解 Agent Skills" \
--subtitle "让 AI 记住你的工作方式" \
--author "花叔" \
--images-dir ./images-v2 \
-o 图解Agent-Skills_出版社审校版.docx
# 158 页 · 9 章 + 后记 + 附录 + 57 张配图 · 直接给出版社编辑审
# 场景8：从 PDF 论文/报告 → docx 投稿（能力1 → 能力4）
python scripts/any_to_md.py paper.pdf -o paper.md
# 编辑 paper.md 修正格式...
python scripts/md_to_docx.py paper.md --page-size a4 -o paper.docx
# 场景9：md 文章 → A4 PDF 给朋友/客户（能力5）
python scripts/md_to_pdf.py article.md --theme article --page-size A4 -o share.pdf
# 场景10：md 单章 → 大32开纸质书外形预览 PDF（能力5）
python scripts/md_to_pdf.py chapter-3.md --theme article --page-size book \
--margin-top 24mm --margin-bottom 24mm -o preview.pdf
# 场景11：多章 md → 通用阅读器 EPUB（能力6）
python scripts/md_to_epub.py ch01.md ch02.md ch03.md \
--title "..." --author "花叔" --cover cover.jpg -o book.epub
# 场景12：从 PDF 文档 → md → 重新打版 PDF（能力1 → 能力5）
python scripts/any_to_md.py old.pdf -o old.md
# 编辑 old.md 调内容...
python scripts/md_to_pdf.py old.md --theme report --page-size A4 -o new.pdf
# 场景13：YouTube 字幕 → md → EPUB 长文随身读（能力1 → 能力6）
python scripts/any_to_md.py "https://youtube.com/watch?v=xxx" -o talk.md
# 编辑 talk.md 清理时间戳...
python scripts/md_to_epub.py talk.md --title "..." --author "花叔" -o talk.epub异常处理
| 场景 | 处理 |
|---|---|
| markitdown未安装 | 脚本检测后提示pip install 'markitdown[all]'，不静默失败 |
| pandoc未安装 | 脚本检测后提示brew install pandoc，给出官方下载地址 |
| 输入文件不存在 | 立即报错，不假装继续 |
| URL请求失败（能力1的YouTube/能力3的URL） | 降级提示：检查网络/VPN/CDN |
| 转换出空内容 | 报警：可能是扫描PDF或图片密集型文档，提示用 --llm-describe |
| 输出html渲染异常 | 检查pandoc版本（建议≥3.0）、检查模板文件完整性 |
| python-docx未安装 | 脚本检测后提示python3 -m pip install python-docx Pillow |
| docx 里图片显示不出 | 检查 --images-dir 路径，或 ref 名 fig-N-X 是否对应 chNN-figNN.png 文件命名 |
| playwright (python) 未安装 | 脚本检测后提示python3 -m pip install playwright && python3 -m playwright install chromium |
| Chromium 首次未下载 | 跑 python3 -m playwright install chromium；失败检查 https_proxy |
| md_to_pdf 大图加载不完整 | 调大 --wait 5000 或更长 |
| md_to_pdf 中文字体方框 | 系统字体缺失——4 套主题 CSS 已包含 PingFang SC / Source Han Serif fallback |
| md_to_epub 报 "Document is empty" | 章节 wrap 用了 xml prolog 或 xmlns——本脚本已用纯 html5 包装规避 |
| md_to_epub 微信读书表格丢失 | 微信读书引擎弱——走 huashu-book-pdf 的截图为 PNG 方案 |
| md_to_epub 封面未显示 | 确认 jpg/png 格式、路径有效、文件 <2MB |
References路由
| 任务 | 读 |
|---|---|
| markitdown各文件类型最佳实践 | references/markitdown-cookbook.md |
| html→md三种场景下的工具组合 | references/html-to-md-cookbook.md |
| 4套html模板的设计哲学+CSS详解 | references/md-to-html-themes.md |
| ⭐ 视觉艺术设计师模式（兜底 vs 定制 · 何时升级到 AI 介入） | references/visual-designer-mode.md |
| md→docx 完整 cookbook（含书籍模式 / 单文件 / 投稿场景） | references/md-to-docx-cookbook.md |
| md→pdf 完整 cookbook（含 4 主题适配、页面规格、与 book-pdf 协作） | references/md-to-pdf-cookbook.md |
| md→epub 完整 cookbook（含章节切分、图片嵌入、CSS 兼容性） | references/md-to-epub-cookbook.md |
| 排版底线参数（字体/行高/宽度） | references/design-tokens.md |
| 反AI slop底线（继承自huashu-design） | references/anti-ai-slop.md |
核心提醒
- 六个能力各有边界：能力1输入端、能力2 html、能力3反向归档、能力4 docx 出版终点、能力5 pdf 阅读终点、能力6 epub 电子书终点。决策错了会绕远路。
- md是源，无论从哪来要回到哪——md是这个流水线的中心。html / docx / pdf / epub 都是产物。
- html产出必反slop：紫渐变、emoji图标、SVG画人物——一律不要。审美底线见
references/anti-ai-slop.md。 - URL输入双路径：结构化页面用能力1（保metadata+层级+链接），博客类用能力3（去导航+只留正文）。判断捷径——内容是「读的」走3，是「查的」走1。
- docx 是给人改稿的，pdf 是给人阅读的，epub 是给阅读器的：选错产物会让下游不顺手。
- 能力5/6 是 stateless 单 md 转换：项目级橙皮书（多 fragments / 版本号 / R2 上传 / 微信读书）走 huashu-book-pdf，不要试图在这里复刻整套发布流水线。
- 先问再做：模板选哪个、图片要不要嵌入、是否要LLM描述图片、单文件还是书籍模式——一次问清，不要边做边猜。
- 依赖外部工具：markitdown（pip）、pandoc（brew）、html-to-markdown（pip）、python-docx（pip）、playwright（pip + chromium）、ebooklib（pip）。脚本启动时自检，缺失明确提示。
- Python环境陷阱：macOS 上
pip和python3可能指向不同 Python 版本（实测踩过：pip是 3.11、python3是 3.14）。安装依赖必须用python3 -m pip install ...，不要直接pip install。
版本自检（静默）
本节给 AI agent：每次使用本 skill 前，先做一个不联网的判断——读本 skill 目录（SKILL.md 所在目录）下的 .last-update-check 文件（内容为一行日期 YYYY-MM-DD）。文件存在且距今不足 30 天，跳过本节直接干活，不向用户提任何更新相关的话。
到期或文件不存在时，且仅在此时：
- 本目录不是 git 克隆（无
.git或无 origin）→ 写入今天日期后跳过本节 - 对比版本：
git -C <本目录> rev-parse HEAD与git -C <本目录> ls-remote origin HEAD - 无论结果如何，把今天日期写入
.last-update-check - 两者一致 → 什么都不说；确认落后 → 先完成用户当前任务，结束后附一句「本 skill 有新版本，可用
git -C <本目录> pull --ff-only更新」。是否更新由用户决定，不要主动执行更新
评论 0
更多
登录后可点赞、收藏、评论和举报。
还没有评论，先发起一个具体问题。