dsh-html-toolkit

dsh-html-toolkit

零运行时依赖的 HTML 工具箱，用于 DeepSeek Harness 生态：容错 HTML 解析 + DOM 树，支持正文抽取（HTML→纯文本）、HTML→Markdown 反向转换、HTML 清洗消毒。不依赖任何第三方库，仅用 Node 内置模块。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-html-toolkit
• npm：https://www.npmjs.com/package/dsh-html-toolkit
• 协议：MIT

功能说明

• html_to_text：HTML → 纯文本（正文抽取）。容错解析 DOM 后去标签取正文：自动剔除 script/style/nav 等噪音、解码 HTML 实体、块级元素分段、列表转 - / 1. 标记（含嵌套缩进）、表格转竖线行、pre 原样保留、图片取 alt、链接默认只留文字（keep_links=true 附 URL）；main_only=true 只取 article/main 主内容；underline_headings=true 标题转下划线风格。
• html_to_markdown：HTML → Markdown 反向还原。标题、段落、加粗/斜体/删除线、行内代码、围栏代码（自动识别 language-xxx）、链接（含 title）、图片、嵌套列表（有序支持起始号）、引用、hr、GFM 表格（align / style 对齐保留）、br 硬换行。
• clean_html：HTML 清洗/消毒。删除 script/style/iframe/form 等危险标签（含子树）、剥离 on* 事件属性、剥离 javascript: / vbscript: / data:text/html 危险 URL、删除注释（可关）；标签白名单外的元素解包保留文本；支持 allowed_tags 自定义白名单、keep_style 保留内联样式。

安装

# 从 npm 安装
dsh plugin --profile web add dsh-html-toolkit

# 本地开发调试（Debug patch）
# 新建 debug.patch.yml：
# - insert:
#     - id: html-toolkit
#       name: "E:/dsh-plugins/dsh-html-toolkit/index.js"
dsh web --patch ./debug.patch.yml

使用说明

1. html_to_text —— 正文抽取

参数	类型	必填	说明
html	string	是*	HTML 源文本
from	string	是*	从本地 .html/.htm 文件读取
keep_links	boolean	否	链接是否附 URL，默认 false 只留文字
main_only	boolean	否	只取主内容（article/main/#content 启发式），默认 false
underline_headings	boolean	否	标题转 文本+下划线 风格，默认 false
max_chars	number	否	输出字符数上限（超出截断），默认 20000

* html 与 from 二选一。

2. html_to_markdown —— 反向还原 Markdown

参数	类型	必填	说明
html	string	是*	HTML 源文本
from	string	是*	从本地 .html/.htm 文件读取
main_only	boolean	否	只转换主内容，默认 false
keep_images	boolean	否	是否保留图片，默认 true
max_chars	number	否	输出字符数上限，默认 20000

3. clean_html —— 清洗/消毒

参数	类型	必填	说明
html	string	是*	HTML 源文本
from	string	是*	从本地 .html/.htm 文件读取
allowed_tags	string[]	否	允许保留的标签白名单，默认内置约 70 个安全标签
strip_comments	boolean	否	是否删除注释，默认 true
keep_style	boolean	否	是否保留 style 属性，默认 false
max_chars	number	否	输出字符数上限，默认 20000

典型场景

• 网页正文抽取：抓取的页面 HTML 用 html_to_text + main_only 提取干净正文，去掉导航、页脚、脚本噪音。
• 内容二次编辑：CMS / 邮件里的富文本 HTML 用 html_to_markdown 转回 Markdown 进编辑器或版本库。
• 用户输入消毒：评论、富文本提交内容先过 clean_html 再入库/展示，剥掉脚本与危险链接。
• 数据入库前规整：批量 HTML 抽成纯文本后交给 dsh-fulltext-index 建索引，避免标签污染分词。
• 格式互转链路：Markdown → HTML（dsh-markdown-render）→ Markdown（本插件）往返校验内容一致性。

安全边界

• 只读 / 纯计算：无写文件、无网络请求；from 仅读本地文件；解析全程是纯字符串处理，不执行任何脚本。
• clean_html 是消毒器不是完整安全沙箱：剥离脚本/事件/危险 URL/注释可显著降低 XSS 面，但输出到浏览器时仍建议配合 CSP 与服务端校验。
• 危险子树整体移除：script/style/iframe/form/input 等交互与可执行内容连子树一并删除；需要表单里的文本可先用 html_to_text 抽取。
• 输入上限：单次输入 50 万字符；输出默认 2 万字符截断（可调至 10 万），防止刷屏。

版本说明

版本	日期	说明
0.1.0	2026-10-18	首个版本：html_to_text / html_to_markdown / clean_html，容错解析 + DOM 树，86 断言测试

RoadMap

• 语义化正文抽取（文本密度 / 链接密度启发式，自动去广告与侧栏）
• 属性白名单细粒度控制（保留 data-* / aria-*）
• Markdown 反向转换支持定义列表、脚注、行内 HTML 透传
• HTML 规范化输出（可选 pretty-print 缩进）
• html_to_text 表格多输出模式（对齐列 / 制表符 / JSON 行）
• 往返保真度报告（HTML→MD→HTML 差异摘要）

其他插件集成说明

• dsh-markdown-render：它做 Markdown→HTML 正向渲染，本插件做 HTML→Markdown 反向还原，两者构成往返链路。
• dsh-xml-toolkit：XML 严格解析（SOAP/配置文件），本插件专攻容错 HTML，输入形态互补。
• dsh-fulltext-index：本插件抽正文后再建倒排索引，格式符号不污染分词。
• dsh-table-render / dsh-sql-query：HTML 表格转竖线行或 Markdown 表后可继续走表格渲染/查询链路。

FAQ

Q1：这是浏览器的 DOM 吗？ 不是。是自研的容错 HTML 解析器（tokenize + 隐式闭合恢复），构建轻量节点树，纯字符串处理，不执行脚本、不加载资源。

Q2：未闭合或错配的标签怎么办？ 按浏览器习惯恢复：未闭合标签随父级收尾、li/td/tr 等兄弟隐式闭合、块级标签隐式闭合 <p>、游离闭合标签忽略、错配闭合就地截断，不抛错不丢文本。

Q3：clean_html 默认保留哪些标签？ 约 70 个内容型安全标签（p/div/h1-h6/ul/ol/li/table/a/img/pre/code 等）；script/style/iframe/form 及交互控件整体移除；白名单外的标签解包保留文字。可用 allowed_tags 完全自定义。

Q4：clean_html 能防住所有 XSS 吗？ 它是「降风险」不是「绝对防御」：脚本、事件属性、危险协议 URL 都会剥掉，但输出进浏览器仍建议配合 CSP、服务端校验与编码习惯使用。

Q5：HTML 实体会解码吗？ 会。命名实体与十进制/十六进制数字实体都会解码；未知实体原样保留，不会弄丢内容。序列化输出时再统一转义，保证安全。

Q6：main_only 怎么找主内容？ 启发式顺序：article/main 标签 → role=main → id 为 content/main → class 含 article/content/post/entry → 兜底 body。找不到就退回全文。

许可证

MIT