前言¶
在 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 倉庫：
