前言¶
在 DSH 里处理文档时，输入不一定都是干净的 Markdown：HTML 片段、邮件正文、导出文件、需要整理的表格都会出现。没有专门工具时，模型只能在提示词里临时拼转换逻辑，容易出现 HTML 实体处理不一致、表格结构不稳定、网页噪音混入等问题。
下面介绍 omdsh-dev/dsh-tool-markdown。它面向 HTML 与 Markdown 转换、GFM 表格规范化、目录生成等文档处理场景，作为 DSH 工具插件注册 markdown 工具。
插件定位¶
omdsh-dev/dsh-tool-markdown 是由 omdsh-dev 维护的 DSH Markdown 工具插件，MIT 许可。
它的能力可以概括为：
- HTML 转 GFM Markdown。
- Markdown 转白名单安全 HTML。
- HTML 表格或管道分隔文本规范化为 GFM 表格。
- Markdown 标题生成嵌套目录。
- 零依赖、纯函数、手写轻量解析器。
核心功能¶
插件注册 markdown 工具，通过 action 区分不同动作。
常见动作如下：
1、action=html2md：输入 HTML 片段，输出 GFM Markdown。
2、action=md2html：输入 Markdown，输出白名单安全 HTML。
3、action=table：输入 HTML <table> 或管道分隔文本，输出 GFM 表格。
4、action=toc：输入 Markdown 标题，输出嵌套目录。
工具参数包括：
action：选择html2md、md2html、table或toc。html：html2md的输入。markdown：md2html和toc的输入。text：table的输入。maxBytes：输入上限，默认 256KB，硬顶 1MB；超限报错不截断。
安全与边界¶
这个插件对输入和输出都做了比较明确的约束。
零执行面方面：
- 不
eval。 - 不
new Function。 - 不加载远程资源。
- 不解析 CSS 布局。
内容剥离方面：
scriptstyleiframeobjectnoscript
上述内容会整体剥离。
md2html 方面：
- 仅输出白名单标签。
- 文本一律 HTML 转义。
链接处理方面：
- 链接 scheme 白名单为
http、https、mailto。 javascript和data链接降级为纯文本。
资源上限方面：
- 嵌套深度达到 64 层时报错。
- 输入
maxBytes默认 256KB，硬顶 1MB。 - 输入超限时报错，不做截断。
安装与验证¶
安装¶
已核实的安装命令如下：
dsh plugin --profile headless add github:omdsh-dev/dsh-tool-markdown
需要注意，web 与 headless 是不同 profile。web 安装不会自动覆盖 headless。dsh run 默认使用 headless profile，因此一次性任务场景下，headless profile 安装更常见。
检查配置¶
可以用下面的命令检查 profile 配置中是否出现 tool-markdown：
dsh --profile web --dump-config | grep tool-markdown
运行验证¶
可以用 dsh run 触发一次简单转换：
dsh run "使用 markdown 工具把 <h1>标题</h1> 转成 Markdown"
典型用法¶
HTML 转 Markdown¶
适合用户贴来 HTML 片段、邮件正文、导出文件，希望得到 GFM Markdown 的场景。
调用方式：
action=html2md
html=<HTML 片段>
输出为 GFM Markdown。
Markdown 转 HTML¶
适合需要把 Markdown 渲染为受控 HTML 的场景。
调用方式：
action=md2html
markdown=<Markdown 文本>
输出为白名单安全 HTML。文本会进行 HTML 转义。
表格规范化¶
适合输入是 HTML <table> 或管道分隔文本，希望输出稳定 GFM 表格的场景。
调用方式：
action=table
text=<HTML <table> 或管道分隔文本>
输出为 GFM 表格。
目录生成¶
适合根据 Markdown 标题生成嵌套目录。
调用方式：
action=toc
markdown=<包含标题的 Markdown>
输出为嵌套目录。
兼容与运行要求¶
已核实的运行与依赖信息如下：
- Node engines：
^22.19.0 || >=24.0.0 - packageManager：
npm@11.16.0 peerDependencies：@deepseek-ai/cordis ^4.0.1@deepseek-ai/dsh-invariants >=0.0.1-rc.1 <0.2.0@deepseek-ai/dsh-tools >=0.0.1-rc.1 <0.2.0- 已迁移并验证 DSH
0.1.2-alpha.1兼容 package.json版本：0.0.1package.json中private: true- 启动方式：
npx -p @deepseek-ai/dsh@next dsh web
该启动方式属于 lib 生产模式，资料中注明不要 install -g 全局安装。
注意事项¶
插件会运行在当前 DSH 进程权限下，安装前应检查源码和许可证。
另外，工具参数会记入会话日志。不要把包含密钥、会话数据或其他敏感信息的 HTML 直接传入 html2md、md2html、table 等动作。
小结¶
omdsh-dev/dsh-tool-markdown 的价值在于把 HTML、Markdown、GFM 表格和目录这几类常见文档转换收敛到一个 markdown 工具里，同时通过白名单输出、内容剥离、scheme 过滤和输入上限，降低不可控渲染带来的风险。
GitHub 仓库：
