html-to-docx

html-to-docx Skill

概述

html-to-docx 是一个 Python 转换引擎，支持：

• CSS 变量（var(--x)）预处理
• 10+ 种 HTML 元素精确映射（标题/段落/表格/列表/图片/blockquote 等）
• 14 种 CSS 属性映射（字体/颜色/缩进/行距/对齐等）
• 中文字体支持（宋体/黑体/仿宋/楷体，含 rFonts.eastAsia 设置）
• 4 种装饰组件（callout / divider / section-marker / data-card）+ data-card-grid
• 语义 <section role> 分节 + CSS @page 页眉页脚 + 动态域（PAGE/NUMPAGES/STYLEREF）
• TOC 目录渲染（3 级）
• 页眉/页脚渲染
• 图片嵌入（base64 / 本地路径 / 远程 URL）
• CLI 和 Python API 双模式调用

---

调用方式

前置条件：Python 环境与依赖安装

本 Skill 使用 托管 venv（默认 $HOME/.venv-html-to-docx）运行，避免污染系统 Python，也绕开 IDE safe-delete 拦截与跨机器 venv 二进制损坏。环境准备已封装为幂等脚本，首次 ~30s、之后 ~0.5s，agent 无需自行 python -m venv / pip install。

⚠️ 首次调用需要外网（幂等脚本首跑会连以下三处公网）：

• https://astral.sh/uv/install.sh — 装 uv（若本机未装）
• astral-sh/python-build-standalone GitHub Releases — 拉 Python 3.12 独立发行版（uv 托管）
• https://pypi.org/simple — 下载 python-docx / lxml / Pillow 等 wheel

私有化 / 无外网环境：请在首次调用前导出以下环境变量指向内网镜像（uv 与 pip 均遵循）：

export UV_INDEX_URL="https://<内网 PyPI 镜像>/simple"
export UV_PYTHON_INSTALL_MIRROR="https://<内网 python-build-standalone 镜像>"
# uv 本身请预先由运维分发到 $HOME/.local/bin/uv，脚本探测到已装则跳过 curl 安装

未配置镜像且无外网时，setup-html-to-docx.sh 首跑必然失败——这是已知交付前置条件，非 skill 缺陷。Agent 在私有化交付场景下调用本 skill 前，应先确认 IOA/运维已完成上述环境变量或离线 wheel 分发，否则应转 Markdown 降级（见"错误处理与降级"）而非重试。

统一入口（推荐，workbuddy / local 通道一键装齐）：

bash <plugin_root>/scripts/wb/local/setup.sh

单独准备本 Skill 的环境：

bash <plugin_root>/scripts/wb/local/setup-html-to-docx.sh

说明：环境安装脚本位于 plugin 根的 scripts/wb/local/setup-html-to-docx.sh（workbuddy 本地通道专属）。

脚本输出末尾会打印 Python runner: <venv>/bin/python，可直接 export HTML_TO_DOCX_PY=<那个路径> 供后续调用。

调用（首选：环境变量方式）：

bash <plugin_root>/scripts/wb/local/setup-html-to-docx.sh   # 幂等，已就绪则秒退
export HTML_TO_DOCX_PY="${HTML_TO_DOCX_VENV:-$HOME/.venv-html-to-docx}/bin/python"
cd <plugin_root>/skills/html-to-docx/scripts
"$HTML_TO_DOCX_PY" -m html_to_docx convert input.html -o output.docx [OPTIONS]