技能介绍

要解决的问题

Markdown 适合当源代码，HTML 和 DOCX 才是读者与编辑真正拿到的产物。现实中这两类转换散落在多个工具里：markitdown 能吃二十多种格式，pandoc 能渲染网页，trafilatura 擅长抽正文，python-docx 负责排版 Word。问题在于没人把它们串起来，也没人替你判断「这个输入该走哪条路」。结果要么转换后丢了字段与层级，要么版式根本没法直接交给出版社。

核心能力：一条围绕 md 的流水线

四个方向的转换统一以 md 为中心：

能力1 万物 → md：scripts/any_to_md.py 封装 markitdown，支持 PDF、DOCX、PPTX、XLSX、EPUB、图片、音频、YouTube 与网页 URL。
能力2 md → 精美 html：scripts/md_to_html.py 基于 Pandoc 与 4 套自包含模板（article / report / reading / interactive）。
能力3 html → md：scripts/html_to_md.py 用 html-to-markdown 与 trafilatura 做反向归档，剥离导航、侧栏与推荐位。
能力4 md → 精美 docx：scripts/md_to_docx.py 内置出版社级排版预设，面向编辑审校与投稿。

最关键的决策是 URL 输入要分两条路。结构化页面（产品详情、API 文档、证书页）走能力1，markitdown 会保留 YAML frontmatter、字段值、标题层级与链接；博客、新闻、公众号长文走能力3，让 trafilatura 把噪声全部去掉。内容是要「读」的走能力3，是要「查」的走能力1；拿不准就两个都跑一遍再对比。能力1 的输出可以直接喂给能力2，串成「PDF → 精美阅读页」这样的一条龙。

审美与排版底线

生成的每份 HTML 都有硬性约束：禁用紫渐变、赛博霓虹、#0D1117 深蓝底与 Comic Sans；正文使用中文衬线加英文 serif，代码用 JetBrains Mono；容器靠细线与留白分隔，不堆圆角卡片和阴影。行高设在 1.75–1.85，最大宽度 680–820px，保证中文阅读节奏。详细规则集中在 references/anti-ai-slop.md 与 references/design-tokens.md。

适用边界

能力1 不做 OCR。扫描版 PDF 需要外挂 LLM client 或 Azure Document Intelligence；输出为空时脚本会报警并提示加 --llm-describe。
复杂表格与 PPTX 会丢语义。合并单元格、嵌套表格、动画和版式信息不在转换范围内。
能力1 的产物面向 LLM 消费，给人直接读还得再过一道排版。
能力3 不适合结构化页面，它会丢掉字段值与标题层级。
能力4 才是出版终点。给编辑和出版社审校用 docx，不要拿 HTML 或 MD 直接投。
图片是否嵌入、模板选哪个、单文件还是整本书模式，技能要求先问清楚再动手，而不是边做边猜。