Skip to main content

dsh-tool-markdown/packages/dsh-tool-markdown

24Stars1Forks1Issues0Watchers

Converts between Markdown and structured data, enabling formatted text generation and parsing.

Categories⇄ Integrations
Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the omdsh-dev/dsh-toolkit monorepo — stars and activity count the whole repository.

omdsh-devomdsh-dev
·omdsh-dev/dsh-toolkit
Language
TypeScript
License
MIT
Branch
main
collectiondshdsh-plugintoolkitzero-dependency

Install

cmdweb profile
$ dsh plugin --profile web add github:omdsh-dev/dsh-toolkit#path:packages/dsh-tool-markdown

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin omdsh-dev/dsh-toolkit/packages/dsh-tool-markdown for me: review the repository at https://github.com/omdsh-dev/dsh-toolkit first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

一句话定位

DSH 工具插件 tool-markdown，给模型提供 HTML↔Markdown 互转、HTML/管道表格转 GFM 表格、从 Markdown 标题生成目录这四类确定性文本转换能力。零依赖、手写解析器、纯函数运行不联网，适合让模型在拿到网页源码、邮件导出或用户粘贴的 HTML 时给出可预测、可校验的 Markdown 结果。

核心能力

  • 把 HTML 片段或完整文档转成 GFM 风格的 Markdown（块级/行内全映射、表格转 GFM、实体解码、script/style 等标签剥离）
  • 把 Markdown 转回白名单安全的 HTML（只输出允许的标签，文本一律 HTML 转义，不可能逃逸出 <script> 之类危险标签）
  • 规范化表格：HTML <table> 或管道分隔文本统一转成 GFM 表格（自动列补齐、| 转义、识别分隔行）
  • 从 Markdown 标题生成嵌套目录列表（GitHub 风格锚点、重复标题自动加 -1/-2 后缀、跳过代码围栏内的伪标题）
  • 解析时自动剥离 script/style/iframe/object/noscript/template 等危险或噪音标签，提升安全性和可读性
  • 输入大小保护：超过 maxBytes 默认 256KB、硬顶 1MB 直接报错不截断；HTML 嵌套深度 > 64 层报错

技术实现

  • 语言: TypeScript（ESM）
  • 关键依赖: @deepseek-ai/cordis@^4.0.1、@deepseek-ai/dsh-tools（peer）、@deepseek-ai/dsh-invariants（peer）；无运行时 npm 依赖，HTML 解析器与 Markdown 解析器均为手写
  • 架构模式: Cordis 插件——apply(ctx) 中通过 ctx.tools.register(defineTool({...})) 注册名为 markdown 的工具；inject = ['tools']；通过包内 cordis.patch.yml 将 row id tool-markdown 插入 profile layer stack
  • 入口文件: packages/dsh-tool-markdown/src/index.ts（同时导出 invariant.ts 注册一个空的 invariant companion）

适用场景

当模型在 DSH 中处理用户贴过来的网页源码、邮件 HTML 导出、或者想把已写好的 Markdown 渲成安全 HTML 时调用本插件。它解决模型硬编码 HTML 处理时常见的实体错误、表格错乱和网页噪音（导航/脚本/广告）混入输出的痛点。如果你需要的是网页正文抽取（去掉导航广告只留文章），这个工具做不到，应该另寻带 Readability 能力的方案。

前置依赖与兼容性

依赖最低版本说明
DSH0.1.0-rc.8+README 标注已迁移并验证 @deepseek-ai/[email protected]
Node.js^22.19.0 或 >=24.0.0package.json#engines.node
@deepseek-ai/cordis^4.0.1peerDependency，类型/运行时契约
@deepseek-ai/dsh-tools>=0.0.1-rc.1 <0.2.0peerDependency，提供 defineTool / ctx.tools.register
@deepseek-ai/dsh-invariants>=0.0.1-rc.1 <0.2.0peerDependency，invariant companion 注册
平台跨平台无 os/cpu 限制、无原生模块

安装方式

dsh plugin --profile web add github:omdsh-dev/dsh-toolkit/packages/dsh-tool-markdown

配置项

本插件无需额外配置（没有 ctx.config Schema）。所有参数都是 markdown 工具的入参，按 action 分发：

配置类型说明默认值
actionenum要执行的操作：html2md / md2html / table / toc必填
htmlstringhtml2md 的输入，可以是 HTML 片段或完整文档—
markdownstringmd2html / toc 的输入—
textstringtable 的输入，可以是 HTML <table> 或管道分隔文本（必须含未转义的 |）—
baseUrlstring解析相对 href/src 的基准地址（naive join，不处理 query/hash 合并细节）空
maxBytesinteger输入大小上限（字节），超过抛错不截断256000（硬顶 1000000）

工具超时：timeoutMs = 2000（src/index.ts:130）。

常见问题

Q: 这个工具能自动抽取网页正文（去掉导航/广告/页脚）吗？

A: 不能。html2md 只做字面映射，nav/header/footer 默认全部透传。需要正文抽取请另寻带 Readability/Mozilla Readability 能力的工具。

Q: 输入超大时会被悄悄截断吗？

A: 不会。maxBytes 默认 256KB、硬顶 1MB，超过直接抛错（markdown: <label> exceeds N bytes）。如果你的 HTML 经常超过 1MB，请先用其他工具分块再传入。

Q: md2html 输出可以直接 dangerouslySetInnerHTML 渲染吗？

A: 可以。所有文本内容都经过 HTML 转义（< > & " ' 五字符），输出标签严格限定在 p h1-h6 ul ol li blockquote pre code a img strong em br hr table thead tbody tr th td 这 18 个白名单标签，javascript:/data: 链接降级为纯文本，markdown 里内嵌的 <script> 只会显示为可见文本不会执行。

Q: HTML 实体字符会被双重解码吗？

A: 不会。命名实体（&amp; &lt; &copy; 等子集）和数字实体（&#x...; / &#...;）会解码一次；未知实体按字面保留——所以 &amp;lt; 解码后是 &lt;，文本里看到的还是 &lt;，不会被错解成 <。

Q: 工具参数会不会泄露到日志？

A: 会。工具参数会写进 DSH 会话日志，和模型调用记录在一起。所以不要把含密钥、session cookie、个人隐私数据的 HTML 当入参传入——任何能读会话日志的人都会看到。

Q: 装到 web profile 之后 dsh run 能直接用吗？

A: 不一定。dsh run 默认使用 headless profile。web 与 headless 是两个独立 profile，互不覆盖。要让 dsh run 也用上，需要再执行一次 dsh plugin --profile headless add ...。

Q: HTML 表格里 colspan="3" 怎么办？

A: 转换时会被展平成 N-1 个空单元格占位，整体行宽按最大行补齐，确保 GFM 表格列对齐。GFM 本身不支持合并单元格，这种展平是约定。

上手难度

入门 — 只有一个工具、四个动作，参数不超过 6 个；没有需要理解的配置 schema；安装后通过 DSH 的工具调用机制直接使用，普通用户不需要读源码。

已知问题与限制

  • 不做 Readability 类正文抽取，网页导航/页头/页脚会原样透传到 Markdown 输出中
  • HTML 嵌套深度上限 64 层，超出会抛 markdown: HTML nesting exceeds 64 levels 错误（防栈溢出，非静默）
  • 输入超过 maxBytes（默认 256KB、硬顶 1MB）直接报错，不会截断也不重试
  • baseUrl 是 naive join：不解析协议相对 URL //host/path、不合并 query/hash、不处理相对路径 .. 解析
  • 工具参数会写进会话日志，传入含密钥/会话数据的 HTML 等于泄露——这是设计上的取舍，不是 bug
  • HTML 解析器覆盖约 95% 模型场景的语法子集（h1-h6/p/ul/ol/li/table/blockquote/pre/code/a/img/strong/em/br/hr 等），CSS/SVG/MathML 等不解析，遇到未知容器元素直接递归透传
  • md2html 只实现 CommonMark 子集（标题/围栏代码/引用/列表/表格 + 行内 code/**bold**/*italic*/[text](url)/![alt](url)），不支持嵌套列表、任务列表、删除线、脚注等扩展语法

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-toolkit/packages/dsh-tool-markdown)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory