Markdown 转换器 omdsh-dev/dsh-tool-markdown

dsh-tool-markdown

DSH Markdown 工具插件 —— HTML↔Markdown 转换、GFM 表格规范化、目录生成。零依赖、纯函数、手写轻量解析器。

License

动机

模型最常见的文档场景：用户贴一段 HTML（网页源码、邮件、导出文件）、贴表格要求整理、或要求“转成 markdown”。没有工具时模型只能硬编码处理——HTML 实体会错、表格会乱、网页噪音（导航/脚本/广告）会混入。本插件提供确定性转换，与 dsh-tool-csv 互补：csv 管结构化表格，markdown 管文档/网页。

安全模型

- 零依赖：手写递归下降 HTML 解析器（不引入 cheerio/jsdom——净增数十 MB 且是攻击面）
- 零执行面：不 eval、不 new Function、不加载远程资源、不解析 CSS 布局
- 内容剥离：script/style/iframe/object/noscript 内容整体剥离（安全 + 噪音）
- md2html 白名单：只输出 p h1-h6 ul ol li blockquote pre code a img strong em br hr table thead tbody tr th td；文本一律 HTML 转义——markdown 内嵌 只会显示为文本
- 链接 scheme 白名单：http/https/mailto；javascript:/data: 链接降级为纯文本
- 资源上限：嵌套深度 64 层报错（防栈溢出）；输入 maxBytes 默认 256KB、硬顶 1MB（超限报错不截断）
- 工具参数会记入会话日志，不要传入含密钥/会话数据的 HTML

工具声明

注册 markdown 工具（@deepseek-ai/dsh-tool-markdown，row id tool-markdown），统一输出文本。

| 参数 | 类型 | 必填 | 说明 |
| action | string | ✅ | html2md / md2html / table / toc |
| html | string | | html2md 输入（片段或完整文档） |
| markdown | string | | md2html/toc 输入 |
| text | string | | table 输入（HTML 或管道分隔文本） |
| baseUrl | string | | 相对 href/src 解析基准（naive join） |
| maxBytes | integer | | 输入上限，默认 256000，硬顶 1000000 |

Actions

| action | 功能 |
| html2md | HTML → GFM Markdown：块级/行内全映射、表格转 GFM（colspan 占位补齐）、实体解码、script/style 剥离、链接 scheme 过滤（不做 readability 正文选择，nav/header/footer 默认透传） |
| md2html | Markdown → 白名单安全 HTML：全文本转义，无标签可逃逸 |
| table | HTML 或含未转义 \| 的管道分隔文本 → GFM 表格（列补齐、\| 转义、分隔行识别；无管道输入报错） |
| toc | Markdown 标题 → 嵌套目录列表（简化 GitHub 风格锚点：重复标题自动 -1/-2 后缀、跳过代码围栏内伪标题） |

示例

markdown { action: "html2md", html: "标题你好 世界" }
→ # 标题\n\n你好 世界

markdown { action: "md2html", markdown: "x)" }
→ x ← javascript: 链接降级为纯文本

markdown { action: "table", text: "a|b\n1|2" }
→ | a | b |\n| --- | --- |\n| 1 | 2 |

markdown { action: "toc", markdown: "# 标题一\n## 小节" }
→ - 标题一\n - 小节

边界行为

| 情况 | 处理 |
| 未闭合标签 | EOF 自动闭合（与浏览器方向一致）； 中遇块级自动关闭 |
| 大小写 | 标签/属性名归一为小写 |
| 注释/DOCTYPE/CDATA | 剥离 |
| 实体 | 命名 + 数字实体解码；未知实体按字面保留（< → <，不二次解码） |
| 嵌套列表 | li 只被新 li 关闭——嵌套 ul/ol 合法（2 空格/层缩进） |
| 空白 | 行内折叠为单空格；pre/code 原样保留 |
| 表格 | 首行（thead th 或首行 td）为表头；colspan=N 补 N-1 个占位单元格 |
| 深度 > 64 层 | markdown: HTML nesting exceeds 64 levels |
| 输入超限 | markdown: exceeds N bytes（不截断） |
| md2html 内嵌 HTML | 原样转义为文本，绝无白名单外标签输出 |

DSH 0.1.5-rc.1 兼容（已验证）

本插件已迁移到 DSH 0.1.5-rc.1 依赖线，并在 local harness 0.1.5-rc.1 的隔离 consumer 中完成全链路验证：

- 类型/运行时：@deepseek-ai/cordis@^4.0.1 + @deepseek-ai/dsh-tools@>=0.0.1-rc.1 =0.0.1-rc.1 ⚠️ web 与 headless 是不同 profile：web 安装不会自动覆盖 headless；dsh run 默认使用 headless profile。

npm pack tarball 安装

npm pack # 生成 dsh-tool-markdown-.tgz
dsh plugin --profile web add ./dsh-tool-markdown-.tgz
dsh plugin --profile headless add ./dsh-tool-markdown-*.tgz

验证安装

dsh --profile web --dump-config | grep tool-markdown

运行验证

dsh run "使用 markdown 工具把 标题 转成 Markdown"

手动安装与旧版本兼容

仅适用于不支持 Profile Bundle 的旧快照或插件开发调试环境（本地 junction/symlink、手动编辑 profile 层）。
测试

node /node_modules/vitest/vitest.mjs run tests

- html.spec.ts：解析器边界（嵌套/未闭合/大小写/自闭合/注释/script 剥离/实体/畸形属性/深度守卫）
- html2md.spec.ts：块级与行内映射全表、表格（colspan/表头/转义）、scheme 过滤、baseUrl
- md2html.spec.ts：白名单结构 + 安全（内嵌 script 转义、javascript: 降级、引号转义）
- table.spec.ts：HTML/管道输入、列补齐、\| 转义；toc.spec 目录与 slugify
- register.spec.ts：注册契约（AUDIT-CROSS-02 风格）

许可

MIT