html2md

面向 AI 代理的激进式 HTML 到 Markdown 转换器。采用 Mozilla Readability 提取主内容，Turndown 转换为 Markdown，再经重度后处理清除残留噪声。

完整参数说明与高级用法示例详见：references/usage.md

安装

cd /scripts
npm install
npm link        # 使 `html2md` 全局可用

需 Node.js 22 或更高版本。

快速上手

html2md https://example.com                    # 抓取并转换
html2md --file page.html                       # 转换本地 HTML 文件
cat page.html | html2md --stdin                # 从 stdin 管道输入
html2md --max-tokens 2000 https://example.com  # 按 token 预算截断
html2md --no-links https://example.com         # 移除 href 属性，保留链接文本
html2md --json https://example.com             # JSON 输出：{title, url, markdown, tokens}

核心特性

• Readability 内容提取 — 自动移除导航栏、侧边栏、广告、Cookie 提示横幅等干扰元素；当 Readability 提取结果过少（例如 Hacker News 的表格布局）时，自动回退至清理后的 内容。
• Token 预算控制 — 使用 --max-tokens N 参数可确保所有标题均被保留，并按文档顺序填充剩余预算，末尾追加 [truncated — N more tokens] 标记。估算依据为：1 token ≈ 4 字符。
• 后处理能力 — 清除 HTML 注释、零宽字符、社交类行动号召（CTA）、面包屑导航、空标题，并合并多余空白行。
• 错误处理机制 — 对无效 URL、超时（默认 15 秒）、非 HTML 响应内容、缺失文件等异常情况，统一返回退出码 1，并在 stderr 输出明确的错误描述。
• 多种输出模式 — 支持纯 Markdown 输出，或启用 --json 模式以供程序化调用。

何时选用 html2md，而非 web_fetch

安全注意事项

html2md 的职责即为获取 URL 内容及读取本地文件。若传入不可信输入，请注意：

• URL 抓取：该工具将无条件请求所给 URL。若您的威胁模型包含 SSRF（服务器端请求伪造），请勿在未经校验的情况下直接使用用户可控的 URL。
• 文件读取：--file 可读取进程有权限访问的任意路径。在代理工作流中，路径由代理自身控制——其风险等级等同于代理直接调用 cat 命令。
• 不执行 shell 命令：工具本身绝不会派生 shell 进程或执行任意命令。若在脚本中调用，请使用 execFileSync（而非 execSync）以规避 shell 注入风险。
• 无数据外泄行为：所有输出仅发送至 stdout；除单次目标 URL 抓取外，不发起任何其他网络请求；不采集遥测数据、不收集分析信息、不进行任何形式的“回传”（phone-home）。
• 依赖项：jsdom（Mozilla 实现的 DOM 库）、Readability（Mozilla 内容提取器）、Turndown（HTML→Markdown 转换器）。上述均为经过广泛审计的开源库。

使用示例

# 在 2000 token 预算内读取 Paul Graham 的一篇随笔
html2md --max-tokens 2000 https://paulgraham.com/greatwork.html

# 获取 Hacker News 首页的干净文本，去除链接干扰
html2md --no-links --no-images https://news.ycombinator.com

# 在提交前获取 token 数量统计
html2md --json https://example.com | jq .tokens

# 将输出重定向至文件
html2md https://docs.example.com/api > api-docs.md