dsh-tool-markdown

中文

DSH Markdown tool plugin — HTML↔Markdown conversion, GFM table normalization, table-of-contents generation. Zero dependencies, pure functions, hand-written lightweight parser.

Motivation

The most common document scenarios for models: the user pastes a block of HTML (web page source, email, exported file), pastes a table asking for cleanup, or asks to "convert to markdown". Without a tool, the model can only hard-code the handling — HTML entities go wrong, tables get mangled, and web noise (nav/scripts/ads) leaks in. This plugin provides deterministic conversion and complements dsh-tool-csv: csv handles structured tables, markdown handles documents/web pages.

Security model

• Zero dependencies: hand-written recursive-descent HTML parser (no cheerio/jsdom — they add tens of MB and are an attack surface)
• Zero execution surface: no eval, no new Function, no remote resource loading, no CSS layout parsing
• Content stripping: script/style/iframe/object/noscript contents are stripped entirely (security + noise)
• md2html whitelist: only outputs p h1-h6 ul ol li blockquote pre code a img strong em br hr table thead tbody tr th td; all text is HTML-escaped — a <script> embedded in markdown is only displayed as text
• Link scheme whitelist: http/https/mailto; javascript:/data: links degrade to plain text
• Resource limits: nesting deeper than 64 levels errors (prevents stack overflow); input maxBytes defaults to 256 KB with a hard cap of 1 MB (errors on exceeding, never truncates)
• Tool arguments are recorded in session logs; do not pass in HTML containing secrets/session data

Tool declaration

Registers the markdown tool (@deepseek-ai/dsh-tool-markdown, row id tool-markdown) with unified text output.

Actions

Examples

markdown { action: "html2md", html: "<h1>标题</h1><p>你好 <b>世界</b></p>" }
  → # 标题\n\n你好 **世界**

markdown { action: "md2html", markdown: "[x](javascript:alert(1))" }
  → <p>x</p>          ← javascript: 链接降级为纯文本

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

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

Edge-case behavior

DSH 0.1.5-rc.1 compatibility (verified)

This plugin has been migrated to the DSH 0.1.5-rc.1 harness and fully verified in an isolated consumer of local harness 0.1.5-rc.1:

• Types/runtime: @deepseek-ai/cordis@^4.0.1 + @deepseek-ai/dsh-tools@>=0.0.1-rc.1 <0.2.0 + @deepseek-ai/dsh-invariants@>=0.0.1-rc.1 <0.2.0 (peer); no longer depends on unscoped cordis
• Standalone build: npm install (devDependencies are self-contained: typescript/vitest/@types/node) → npm run typecheck → npm test → npm run build → npm pack
• Consumption verification: tarball installed into the 0.1.5-rc.1 consumer → dsh --profile compat --dump-config shows this plugin's row → the tool actually registers and executes
• Startup: npx -p @deepseek-ai/dsh@next dsh web (lib production mode; do not install -g globally)

Installation

Plugin source repository: https://github.com/omdsh-dev/dsh-tool-markdown (public).

Profile Bundle (recommended)

Install this plugin as a standalone bundle into a profile (DSH 0.1.5-rc.1, npm):

# 交互式（web）profile
dsh plugin --profile web add github:omdsh-dev/dsh-tool-markdown
# 一次性任务（headless）profile —— dsh run 默认使用 headless
dsh plugin --profile headless add github:omdsh-dev/dsh-tool-markdown

The dsh.bundle.patch inside the package automatically adds the plugin to the profile's layer stack after installation (row id: tool-markdown).

⚠️ web and headless are different profiles: installing into web does not automatically cover headless; dsh run uses the headless profile by default.

Install via npm pack tarball

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

Verify installation

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

Run verification

dsh run "使用 markdown 工具把 <h1>标题</h1> 转成 Markdown"

Manual installation and legacy compatibility

Only for legacy snapshots that do not support Profile Bundle, or plugin development/debugging environments (local junction/symlink, manually editing profile layers).

Testing

node <monorepo>/node_modules/vitest/vitest.mjs run tests

• html.spec.ts: parser boundaries (nesting/unclosed/case/self-closing/comments/script stripping/entities/malformed attributes/depth guard)
• html2md.spec.ts: full block/inline mapping table, tables (colspan/header/escaping), scheme filtering, baseUrl
• md2html.spec.ts: whitelist structure + security (embedded script escaping, javascript: degradation, quote escaping)
• table.spec.ts: HTML/pipe inputs, column padding, \| escaping; toc.spec TOC and slugify
• register.spec.ts: registration contract (AUDIT-CROSS-02 style)

License

MIT