@puwenhui/dsh-md2pdf 0.1.0

package/README.md

@@ -0,0 +1,168 @@
+# @puwenhui/dsh-md2pdf
+
+DSH 插件：**把 Markdown 转成 PDF**（同时产出同名单文件 HTML）。在对话里直接说「把某个 .md 转成 PDF」即可，也可在浏览器里点链接预览/下载产物。
+
+定位：把原 `webphone-frontend-sdk/tools/md2pdf.mjs` 的能力**插件化**——同一套渲染管线（markdown-it + highlight.js + guide-style.css + 本机 Chromium 打印），从「命令行/拖拽」升级为「对话即用」。
+
+## 能力一览
+
+| 面 | 说明 |
+|---|---|
+| 模型工具 `md2pdf_convert` | 对话中把 1 个或多个 .md（或目录）转成 PDF |
+| HTTP 端点 `/dsh-md2pdf/download` | 浏览器直接预览/下载刚生成的 PDF/HTML |
+
+**页眉自动生成**：取文档**第一个一级标题**（`# xxx`），没有则回退文件名主干；页脚固定为「当前页 / 总页数」。页眉无需人工指定。
+
+## 安装
+
+从 npm 安装（已发布）：
+
+```sh
+dsh plugin --profile web add @puwenhui/dsh-md2pdf
+```
+
+也可以从本地目录安装（开发中/未发布时）：
+
+```sh
+dsh plugin --profile web add file:D:/ds-harness/dsh-md2pdf-plugin
+```
+
+包内声明了 `dsh.bundle.patch`，`dsh` 会**自动**把本包追加进 profile 的 `dsh.profile.bundles`，无需手改任何 profile 清单。
+
+安装后**重启 `dsh web`**（bundle 层只在启动时组装）：
+
+```powershell
+& node D:\deepseek-harness\apps\cli\lib\bin.js web
+```
+
+验证是否挂上（不必启动服务）：
+
+```powershell
+& node D:\deepseek-harness\apps\cli\lib\bin.js --profile web --dump-config | Select-String md2pdf
+```
+
+### ⚠️ 安装时实测到的坑：`dsh plugin add` 会剪掉 profile 的安装回退链接
+
+本插件是在**真实 web profile** 上实测安装的，过程中踩到一个 DSH 层面的坑，记录在此以免重踩：
+
+- `dsh plugin add` 会在 profile 目录里跑一次 `pnpm`。pnpm 的默认行为是**清理 extraneous（不在 lockfile 里的）条目**。
+- `$DSH_HOME/profiles/web/node_modules` 里除了 pnpm 管的依赖，还可能有 DSH 安装器放的**安装回退链接**（指向 dsh 安装目录里的内置包）。这些不在 profile 的 lockfile 里，于是会被 pnpm 当作 extraneous 删掉。
+- 后果：profile 下次启动时报
+  `Cannot find package '@deepseek-ai/dsh-api-session-controller' imported from ...\profiles\web\`，**整个宿主起不来**（报错只提内置包，容易被误判为插件问题）。
+
+**判断方法**：把 composed config 里每个插件行的 `name` 逐个从 profile 目录解析一遍，
+只要有一个解析不到，宿主就一定起不来：
+
+```powershell
+& node D:\deepseek-harness\apps\cli\lib\bin.js --profile web --dump-config   # 取全部 name
+```
+
+**修复**：把缺失的内置包补回 `$DSH_HOME/profiles/node_modules/@deepseek-ai/`
+（该目录是「安装依赖闭包的镜像」，由 `healProfilesModuleFallback` **只增不删**地维护；
+而 pnpm 只作用于 `profiles/web`，不会碰它 —— 所以补在这里既正确又不会被下次安装再次剪掉）。
+本次实测缺失的 7 个及其来源：
+
+| 包 | 指向 |
+|---|---|
+| `@deepseek-ai/dsh-api-session-controller` | `packages/api/session-controller` |
+| `@deepseek-ai/dsh-api-settings-controller` | `packages/api/settings-controller` |
+| `@deepseek-ai/dsh-api-workspace-controller` | `packages/api/workspace-controller` |
+| `@deepseek-ai/dsh-client-ui-session` | `packages/client/ui-session` |
+| `@deepseek-ai/dsh-client-ui-approval` | `packages/client/ui-approval` |
+| `@deepseek-ai/dsh-client-ui-chat` | `packages/client/ui-chat` |
+| `@deepseek-ai/dsh-client-ui-schedule` | `packages/client/ui-schedule` |
+
+（`packages/` 指 dsh 安装/检出目录，例如 `D:\deepseek-harness\packages\`。）
+
+> 该问题与插件内容无关：任何 `dsh plugin add` 都可能触发。若 `dsh plugin add` 被中断
+> （例如网络卡在某个 optional 包的拉取上而超时），更容易留下这种半成品状态。
+
+## 用法
+
+对话里直接说，例如：
+
+- 「把 `D:\docs\手册.md` 转成 PDF」
+- 「把 `docs/` 目录下所有 md 都转成 PDF」
+- 「转这个 md，页眉写『某某手册』」
+
+工具参数：
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `inputs` | ✅ | 一个或多个 .md 文件路径，或包含 .md 的目录（取其中一层全部 .md） |
+| `out_dir` | | 输出目录；**缺省与源 .md 同目录**（沿用原脚本行为） |
+| `title` | | 强制指定页眉标题（缺省自动取文档一级标题） |
+| `label` | | 页眉右侧标签（缺省用插件配置 `headerLabel`，通常为空） |
+
+产物与源文件同名：`手册.md` → `手册.pdf` + `手册.html`。相对路径按**会话工作目录**解析。
+
+返回结果里带 `downloadUrl`，形如
+`http://127.0.0.1:3080/dsh-md2pdf/download?path=...&disposition=inline`，
+浏览器打开即预览（`disposition=attachment` 则下载）。
+
+## 配置（可选，全部有默认值）
+
+改 `cordis.patch.yml` 的 `config` 段：
+
+```yaml
+- insert:
+    - id: md2pdf
+      name: "@puwenhui/dsh-md2pdf"
+      config:
+        chromePath: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
+        cssPath: "C:\\path\\to\\your.css"
+        headerLabel: "263 云通信"
+        pageFormat: "A4"
+        downloadBaseUrl: "http://127.0.0.1:3080"
+```
+
+也可用环境变量 `MD2PDF_CHROME` 指定浏览器。
+
+## 依赖与本机要求
+
+- 运行时依赖：`markdown-it`、`highlight.js`、`puppeteer-core`（装在插件自己的 `node_modules`，随包解析，不依赖宿主）。
+- **需要本机已装 Chrome 或 Edge**（`puppeteer-core` 不下载浏览器）。未探测到时报错会列出全部候选路径与三种解决办法。
+- 自动探测顺序：`MD2PDF_CHROME` → `config.chromePath` → Chrome 常见安装位 → Edge 常见安装位 → Playwright 的 chromium 缓存。
+
+## 自检
+
+```sh
+cd D:\ds-harness\dsh-md2pdf-plugin
+node scripts/smoke.mjs        # 29 项断言：模块契约→工具注册→真渲染→下载端点→DSH schema 校验
+node scripts/convert.mjs <a.md> [--out <dir>] [--title <t>] [--label <l>]   # 命令行直转（等价原 md2pdf.mjs）
+```
+
+smoke 用假 `ctx` 把整条链路跑一遍，退出码即结果；convert 是不走 DSH 宿主的 CLI 入口，用于脚本批处理或工具尚未加载时。
+
+## 与原 `tools/md2pdf.mjs` 的关系
+
+渲染管线、页眉页脚版式、A4 页边距、`guide-style.css` 全部保持一致，产物外观相同。移植过程中**修掉了原脚本的两个真实缺陷**：
+
+1. **标题渲染成了 `<hh1>`**：原 `heading_open` 规则写 `` `<h${tokens[idx].tag} ...>` ``，而 markdown-it 的 `token.tag` 已经是 `h1`，于是产出 `<hh1>`——未知元素会退化成 `inline`，**所有标题的一级/二级样式全部丢失**（实测原稿 h1 与正文同字号）。现改为 `<${tokens[idx].tag} ...>`，标题按 CSS 正常缩放（h1 = 1.9em）。
+2. **带 UTF-8 BOM 的 .md 取不到页眉标题**：BOM 让首行 `#` 前多一个 `\uFEFF`，`^#` 匹配失败，页眉退化成文件名。现读取时统一去 BOM，并把正则放宽到允许 ATX 标题前最多 3 个空格。注意：**本仓库的《SDK 接入手册》正是带 BOM 的文件**，所以这个 bug 在原脚本下是必然触发的。
+
+两项均已在 `scripts/smoke.mjs` 里加了回归断言。
+
+## 已知边界
+
+- 目录输入只取**一层** `.md`，不递归。
+- 下载端点只服务**本进程本次运行中由本插件产出**的文件（内存白名单），宿主重启后旧链接失效；端点同时限定 loopback 直连、无代理转发头、Origin 与 Host 同源，**无法读取任意文件**。
+- 单个 .md 过大（几十 MB 级）时 Chromium 打印会明显变慢；工具 `timeoutMs` 设为 180 秒。
+
+## 目录结构
+
+```
+dsh-md2pdf-plugin/
+├── package.json          # 声明 dsh.bundle.patch（决定 dsh plugin 自动加入 bundles）
+├── cordis.patch.yml      # 本插件贡献的插件行 + 可选 config
+├── lib/
+│   ├── plugin.mjs        # 宿主半边：md2pdf_convert 工具 + 下载端点
+│   └── guide-style.css   # 默认导出样式（与原 tools/guide-style.css 同源）
+└── scripts/               # 不随包发布（files 未包含）
+    ├── smoke.mjs         # 自检
+    └── convert.mjs       # 命令行直转入口
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# 本组合包贡献的插件行。声明了 dsh.bundle 后，`dsh plugin --profile web add <本包>`
+# 会自动把本包加进 profile 的 dsh.profile.bundles，无需手改 profile 清单。
+#
+# 全部配置项都有内置默认值，因此这里默认不覆盖任何字段；
+# 需要固定页眉右侧标签等再打开下面的 config。
+- insert:
+    - id: md2pdf
+      name: "@puwenhui/dsh-md2pdf"
+      # config:
+      #   headerLabel: "263 云通信"     # 页眉右侧固定标签（缺省空）
+      #   pageFormat: "A4"              # A4 / Letter / A3 ...
+      #   chromePath: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
+      #   cssPath: "C:\\path\\to\\your.css"

package/lib/guide-style.css

@@ -0,0 +1,104 @@
+/**
+ * 导出样式（HTML 与 PDF 共用 —— 一致性由同一条渲染管线保证）
+ *
+ * 与 D:\workspace-frontend\webphone-frontend-sdk\tools\guide-style.css 同源：
+ * 插件默认样式即该文件，保证「插件产物」与「原 md2pdf.mjs 产物」逐像素一致。
+ *
+ * - 屏幕态（HTML 单文件）：GitHub 风格、居中栏宽；
+ * - 打印态（Chromium → PDF）：A4、页边距由 page.pdf() 控制，此处处理
+ *   分页友好（表格/代码块尽量不跨页断裂、标题不孤行）。
+ * - 中文字体栈：Windows 优先微软雅黑，macOS 苹方。
+ */
+
+:root {
+  --fg: #1f2329;
+  --fg-dim: #57606a;
+  --border: #d0d7de;
+  --bg-code: #f6f8fa;
+  --accent: #0969da;
+}
+
+* { box-sizing: border-box; }
+
+html { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+
+body {
+  font: 14px/1.75 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',
+        'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
+  color: var(--fg);
+  margin: 0 auto;
+  padding: 40px 32px;
+  max-width: 880px;
+}
+
+@media print {
+  body { max-width: none; padding: 0; font-size: 12px; }
+  a { color: var(--accent); text-decoration: none; }
+  h1, h2, h3, h4 { break-after: avoid; }
+  table, pre, .hljs { break-inside: avoid; }
+  tr, td, th { break-inside: avoid; }
+}
+
+h1, h2, h3, h4 { line-height: 1.35; break-after: avoid; }
+h1 { font-size: 1.9em; border-bottom: 2px solid var(--border); padding-bottom: .35em; }
+h2 { font-size: 1.45em; border-bottom: 1px solid var(--border); padding-bottom: .3em; margin-top: 2em; }
+h3 { font-size: 1.2em; margin-top: 1.6em; }
+h4 { font-size: 1.05em; }
+
+p, li { color: var(--fg); }
+strong { color: #000; }
+
+code, pre {
+  font-family: ui-monospace, 'Cascadia Code', Consolas, 'Courier New', monospace;
+}
+code {
+  background: var(--bg-code);
+  padding: .15em .4em;
+  border-radius: 4px;
+  font-size: .92em;
+}
+pre {
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 12px 14px;
+  overflow-x: auto;
+  line-height: 1.6;
+}
+pre code { background: none; padding: 0; font-size: .88em; }
+
+table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 1em 0;
+  font-size: .95em;
+}
+th, td {
+  border: 1px solid var(--border);
+  padding: 6px 10px;
+  text-align: left;
+  vertical-align: top;
+}
+th { background: var(--bg-code); font-weight: 600; }
+
+blockquote {
+  margin: 1em 0;
+  padding: 4px 16px;
+  border-left: 4px solid var(--accent);
+  background: #f0f6ff;
+  color: var(--fg);
+}
+blockquote p { margin: .5em 0; }
+
+hr { border: none; border-top: 1px solid var(--border); margin: 2em 0; }
+
+ul, ol { padding-left: 1.6em; }
+li { margin: .25em 0; }
+
+/* highlight.js（浅色主题内联要点，避免额外主题文件） */
+.hljs-keyword, .hljs-selector-tag, .hljs-built_in { color: #cf222e; }
+.hljs-string, .hljs-attr { color: #0a3069; }
+.hljs-comment { color: #6e7781; }
+.hljs-number, .hljs-literal { color: #0550ae; }
+.hljs-title, .hljs-name { color: #8250df; }
+.hljs-tag { color: #116329; }

package/lib/plugin.mjs

@@ -0,0 +1,519 @@
+/**
+ * @puwenhui/dsh-md2pdf —— DSH 插件：Markdown → 单文件 HTML + A4 PDF
+ *
+ * ⭐ 一致性：HTML 与 PDF 出自同一条渲染管线（markdown-it + highlight.js + guide-style.css），
+ *   PDF 即该 HTML 在 Chromium 里的打印快照，二者所见一致。
+ *   默认样式即 lib/guide-style.css，与原 tools/guide-style.css 同源 —— 插件产物与
+ *   原 `node tools/md2pdf.mjs` 产物保持一致。
+ *
+ * ⭐ 页眉自动生成：取文档第一个 `# 一级标题`；没有则回退文件名主干。
+ *   页脚固定为「当前页 / 总页数」。
+ *
+ * ⭐ 本插件只注册一个模型工具 `md2pdf_convert`，外加一个 loopback 限定的
+ *   HTTP 端点 `/dsh-md2pdf/download`，供浏览器直接预览/下载刚生成的产物。
+ *
+ * ⚠️ PDF 打印用本机已装 Chrome/Edge（puppeteer-core，不下载浏览器）。
+ *   探测失败时给出候选路径清单，可用 MD2PDF_CHROME 或 config.chromePath 指定。
+ *
+ * 依赖解析：本模块只 import 自身依赖与 node: 内置模块，不 import 任何
+ * `@deepseek-ai/dsh-*` 包 —— 保证作为外部插件加载时零解析风险
+ * （parameters/output 已按 dsh-tools 的 JSON Schema 白名单子集手写）。
+ */
+
+import { createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import z from '@deepseek-ai/schemastery'
+import hljs from 'highlight.js'
+import MarkdownIt from 'markdown-it'
+import puppeteer from 'puppeteer-core'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const DEFAULT_CSS = resolve(HERE, 'guide-style.css')
+
+/** 下载端点路径（与 apply 里注册的路由、工具返回的 URL 共用同一常量）。 */
+const DOWNLOAD_PATH = '/dsh-md2pdf/download'
+
+/* ── 本机浏览器探测 ─────────────────────────────────────────── */
+
+/**
+ * 候选浏览器可执行文件。环境变量优先，其后是 Windows 常见安装位，
+ * 最后兜底扫描 Playwright 的 chromium 缓存（本机可能已存在）。
+ * @returns 候选绝对路径（可能不存在，按顺序探测）。
+ */
+function chromeCandidates() {
+  const explicit = process.env.MD2PDF_CHROME?.trim()
+  const candidates = [
+    explicit === undefined || explicit === '' ? undefined : explicit,
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+    'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  ]
+  for (const path of playwrightChromiumCandidates()) candidates.push(path)
+  return candidates.filter((candidate) => candidate !== undefined)
+}
+
+/** 扫描 `%LOCALAPPDATA%\ms-playwright` 下的 chromium 缓存（版本目录名不固定）。 */
+function playwrightChromiumCandidates() {
+  const root = process.env.LOCALAPPDATA === undefined
+    ? undefined
+    : join(process.env.LOCALAPPDATA, 'ms-playwright')
+  if (root === undefined || !existsSync(root)) return []
+  const found = []
+  try {
+    for (const entry of readdirSync(root)) {
+      if (entry.startsWith('chromium-')) {
+        found.push(join(root, entry, 'chrome-win64', 'chrome.exe'))
+      } else if (entry.startsWith('chromium_headless_shell-')) {
+        found.push(join(root, entry, 'chrome-headless-shell-win64', 'chrome-headless-shell.exe'))
+      }
+    }
+  } catch {
+    /* 缓存目录不可读时静默跳过：候选清单本就可选 */
+  }
+  return found
+}
+
+/**
+ * 取第一个存在的浏览器可执行文件。
+ * @param preferred - 显式指定的路径（config.chromePath），优先于自动探测。
+ * @returns 可执行文件绝对路径，或 undefined。
+ */
+function findChrome(preferred) {
+  if (preferred !== undefined && preferred !== '' && existsSync(preferred)) return preferred
+  return chromeCandidates().find((candidate) => existsSync(candidate))
+}
+
+/** 未探测到浏览器时的报错文案（含候选清单与两种解决办法）。 */
+function chromeMissingMessage() {
+  return '未找到本机 Chrome/Edge。'
+    + '解决办法：① 安装 Chrome/Edge；② 设环境变量 MD2PDF_CHROME=<chrome.exe 路径>；'
+    + '③ 在插件行的 config.chromePath 指定。已探测：' + chromeCandidates().join(' | ')
+}
+
+/* ── Markdown 渲染（标题锚点 + 代码高亮）────────────────────── */
+
+let markdownSingleton
+
+/** 惰性创建并复用 markdown-it 实例（render 本身无状态，可安全复用）。 */
+function markdown() {
+  if (markdownSingleton !== undefined) return markdownSingleton
+  const md = new MarkdownIt({
+    html: true,
+    linkify: true,
+    highlight(code, lang) {
+      if (lang !== '' && hljs.getLanguage(lang) !== undefined) {
+        try {
+          return hljs.highlight(code, { language: lang, ignoreIllegals: true }).value
+        } catch {
+          /* 高亮失败回退纯文本 */
+        }
+      }
+      return ''
+    },
+  })
+  md.renderer.rules.heading_open = (tokens, idx) => {
+    const text = tokens[idx + 1]?.content ?? ''
+    const id = text
+      .toLowerCase()
+      .replace(/[^\p{L}\p{N}\s-]/gu, '')
+      .trim()
+      .replace(/\s+/g, '-')
+    // token.tag 已经是完整标签名（'h1'/'h2'…），不能再补一个 'h'，
+    // 否则渲染出 <hh1> —— 未知元素会退化成 inline，标题样式全部丢失。
+    return `<${tokens[idx].tag} id="${id}">`
+  }
+  markdownSingleton = md
+  return md
+}
+
+/**
+ * 读取 Markdown 原文并去掉可能存在的 UTF-8 BOM。
+ * Windows 上大量 .md 带 BOM（本仓库的接入手册就是），若不去掉：
+ * ① 首行的 `#` 前面多一个 \uFEFF，一级标题正则匹配不到，页眉会退化成文件名；
+ * ② BOM 会被当作正文渲染出来。
+ * @param path - .md 绝对路径。
+ * @returns 去 BOM 后的 UTF-8 文本。
+ */
+function readMarkdown(path) {
+  return readFileSync(path, 'utf8').replace(/^\uFEFF/, '')
+}
+
+/**
+ * 页眉/`<title>` 用标题：取文档第一个一级标题，没有则回退文件名主干。
+ * 允许 ATX 标题前最多 3 个空格（CommonMark）；`##` 不会被误判为一级标题。
+ * @param source - Markdown 原文（应已去 BOM）。
+ * @param fallback - 回退标题（通常为文件主干名）。
+ * @returns 文档标题。
+ */
+function docTitle(source, fallback) {
+  const matched = source.match(/^ {0,3}#\s+(.+)$/m)
+  return matched?.[1]?.trim() ?? fallback
+}
+
+/** HTML 转义（页眉/页脚模板与 `<title>` 共用）。 */
+function escapeHtml(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/* ── 渲染与打印 ─────────────────────────────────────────────── */
+
+/** 组装单文件 HTML（样式内联，产物可离线分发）。 */
+function buildHtml(body, title, css) {
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${escapeHtml(title)}</title>
+<style>
+${css}
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>`
+}
+
+/** 页眉模板：左标题、右标签（标签缺省为空）。 */
+function headerTemplate(title, label) {
+  return `
+    <div style="width:100%;font-size:8px;color:#8a94a6;
+                font-family:'Microsoft YaHei',sans-serif;
+                padding:0 14mm;display:flex;justify-content:space-between;">
+      <span>${escapeHtml(title)}</span>
+      <span>${escapeHtml(label)}</span>
+    </div>`
+}
+
+/** 页脚模板：当前页 / 总页数。 */
+const FOOTER_TEMPLATE = `
+    <div style="width:100%;font-size:8px;color:#8a94a6;text-align:center;
+                font-family:'Microsoft YaHei',sans-serif;">
+      <span class="pageNumber"></span> / <span class="totalPages"></span>
+    </div>`
+
+/**
+ * 用已启动的浏览器把一个 Markdown 渲染成 HTML + PDF 两个文件。
+ * @param browser - 复用的 puppeteer 浏览器实例。
+ * @param job - 单文件作业（已解析的绝对路径与页眉参数）。
+ * @returns 产物信息。
+ */
+async function renderOne(browser, job) {
+  const source = readMarkdown(job.input)
+  const title = job.headerTitle ?? docTitle(source, basename(job.input, '.md'))
+  const html = buildHtml(markdown().render(source), title, job.css)
+
+  mkdirSync(dirname(job.htmlPath), { recursive: true })
+  writeFileSync(job.htmlPath, html, 'utf8')
+
+  const page = await browser.newPage()
+  try {
+    await page.setContent(html, { waitUntil: 'load' })
+    // 不传 path：直接取回字节自行落盘，避免不同 puppeteer 版本对 path 的差异。
+    const pdf = await page.pdf({
+      format: job.pageFormat,
+      printBackground: true,
+      displayHeaderFooter: true,
+      margin: { top: '20mm', bottom: '18mm', left: '14mm', right: '14mm' },
+      headerTemplate: headerTemplate(title, job.headerLabel),
+      footerTemplate: FOOTER_TEMPLATE,
+    })
+    writeFileSync(job.pdfPath, pdf)
+  } finally {
+    await page.close()
+  }
+
+  return {
+    input: job.input,
+    title,
+    htmlPath: job.htmlPath,
+    pdfPath: job.pdfPath,
+    htmlBytes: statSync(job.htmlPath).size,
+    pdfBytes: statSync(job.pdfPath).size,
+  }
+}
+
+/**
+ * 单文件便捷入口（与原 tools/md2pdf.mjs 的库调用等价，自带浏览器生命周期）。
+ * 插件工具内部走批量路径复用同一个浏览器，不经此函数。
+ *
+ * @param options - `{ input, outDir?, headerTitle?, headerLabel?, cssPath?, chromePath?, pageFormat? }`
+ * @returns 产物信息（含 pdfPath/htmlPath）。
+ */
+export async function exportMarkdownToPdf(options) {
+  const input = resolve(options.input)
+  assertMarkdownFile(input)
+  const chrome = findChrome(options.chromePath)
+  if (chrome === undefined) throw new Error(chromeMissingMessage())
+
+  const outDir = resolve(options.outDir ?? dirname(input))
+  const stem = basename(input, '.md')
+  const css = readFileSync(options.cssPath ?? DEFAULT_CSS, 'utf8')
+  const browser = await puppeteer.launch({ executablePath: chrome, headless: true })
+  try {
+    return await renderOne(browser, {
+      input,
+      htmlPath: resolve(outDir, `${stem}.html`),
+      pdfPath: resolve(outDir, `${stem}.pdf`),
+      headerTitle: options.headerTitle,
+      headerLabel: options.headerLabel ?? '',
+      css,
+      pageFormat: options.pageFormat ?? 'A4',
+    })
+  } finally {
+    await browser.close()
+  }
+}
+
+/** 校验输入是一个存在的 .md 文件。 */
+function assertMarkdownFile(input) {
+  if (!existsSync(input)) throw new Error(`输入文件不存在：${input}`)
+  if (!statSync(input).isFile()) throw new Error(`输入不是文件：${input}`)
+  if (extname(input).toLowerCase() !== '.md') throw new Error(`只支持 .md 文件，收到：${input}`)
+}
+
+/**
+ * 把模型给的每个输入展开成 .md 文件清单：文件直接用，目录取其中一层 .md（按名排序）。
+ * @param inputs - 模型提供的输入项。
+ * @param cwd - 相对路径的解析基准（会话工作目录）。
+ * @returns 去重后的绝对路径清单。
+ */
+function expandInputs(inputs, cwd) {
+  const files = []
+  for (const raw of inputs) {
+    const path = resolve(cwd, raw)
+    if (!existsSync(path)) throw new Error(`输入不存在：${raw} → ${path}`)
+    if (statSync(path).isDirectory()) {
+      const found = readdirSync(path)
+        .filter((name) => extname(name).toLowerCase() === '.md')
+        .sort()
+        .map((name) => resolve(path, name))
+      if (found.length === 0) throw new Error(`目录下没有 .md 文件：${path}`)
+      files.push(...found)
+    } else {
+      assertMarkdownFile(path)
+      files.push(path)
+    }
+  }
+  return [...new Set(files)]
+}
+
+/* ── 插件配置 ───────────────────────────────────────────────── */
+
+/** 插件配置（全部可省略；省略即用内置默认值）。 */
+export const Config = z.object({
+  chromePath: z.string().description('浏览器可执行文件路径（缺省自动探测 Chrome/Edge）'),
+  cssPath: z.string().description('导出样式 CSS 路径（缺省用插件内置 guide-style.css）'),
+  headerLabel: z.string().default('').description('页眉右侧固定标签（缺省空）'),
+  pageFormat: z.string().default('A4').description('纸张规格：A4 / Letter / A3 …'),
+  downloadBaseUrl: z.string().description('下载链接的基址（缺省读 DSH_WEB_URL，再缺省 http://127.0.0.1:3080）'),
+})
+
+/** 插件稳定标识（Loader 诊断用）。 */
+export const name = 'dsh-md2pdf'
+
+/** 注册模型工具需要 tools 服务。 */
+export const inject = ['tools']
+
+/* ── 模型工具与 HTTP 端点 ───────────────────────────────────── */
+
+/**
+ * 注册 `md2pdf_convert` 工具与浏览器下载端点。
+ * @param ctx - 插件上下文（需含 tools；webServer 可选）。
+ * @param config - 经 Config 校验的插件配置。
+ */
+export function apply(ctx, config = {}) {
+  const settings = {
+    chromePath: config.chromePath,
+    cssPath: config.cssPath,
+    headerLabel: config.headerLabel ?? '',
+    pageFormat: config.pageFormat ?? 'A4',
+    downloadBaseUrl: (config.downloadBaseUrl ?? process.env.DSH_WEB_URL ?? 'http://127.0.0.1:3080').replace(/\/+$/, ''),
+  }
+
+  /**
+   * 本次进程内由本插件产出过的文件（绝对路径）白名单。
+   * 下载端点只服务这个集合 —— 端点无法读取任意文件。
+   */
+  const generated = new Set()
+
+  ctx.tools.register({
+    name: 'md2pdf_convert',
+    description: '把 Markdown(.md) 转成 PDF（同时产出同名单文件 HTML）。'
+      + 'PDF 为 A4、含页眉与页码；页眉左侧取文档第一个一级标题（没有则用文件名），'
+      + '故页眉无需人工指定。输入可以是单个 .md 文件，也可以是目录（取其中一层全部 .md）。'
+      + '默认写到与源 .md 同目录，可用 out_dir 覆盖。相对路径按会话工作目录解析。'
+      + '返回 PDF/HTML 绝对路径，以及可在浏览器直接预览/下载的链接。',
+    parameters: {
+      type: 'object',
+      properties: {
+        inputs: {
+          type: 'array',
+          items: { type: 'string' },
+          description: '一个或多个 .md 文件路径，或包含 .md 的目录路径',
+        },
+        out_dir: {
+          type: 'string',
+          description: '输出目录（缺省：与源 .md 同目录）',
+        },
+        title: {
+          type: 'string',
+          description: '强制指定页眉标题（缺省自动取文档第一个一级标题）',
+        },
+        label: {
+          type: 'string',
+          description: '页眉右侧标签（缺省用插件配置 headerLabel，通常为空）',
+        },
+      },
+      required: ['inputs'],
+      additionalProperties: false,
+    },
+    output: {
+      // 空 schema = 无约束 JSON（dsh-tools 支持的注解型 schema），
+      // 由 render 负责把结果讲给模型听。
+      schema: {},
+      render: (_args, value) => {
+        const lines = value.results.map((item) => item.ok
+          ? `✅ ${item.input}\n   PDF ：${item.pdfPath}（${Math.round(item.pdfBytes / 1024)} KB）\n`
+            + `   HTML：${item.htmlPath}\n   预览/下载：${item.downloadUrl}`
+          : `❌ ${item.input}\n   ${item.error}`)
+        if (value.failedCount > 0 && value.count > 0) {
+          lines.push(`\n共 ${value.results.length} 项：成功 ${value.count}，失败 ${value.failedCount}。`)
+        }
+        return [{ type: 'text', text: lines.join('\n\n') }]
+      },
+    },
+    timeoutMs: 180_000,
+    async execute(args, exec) {
+      // 相对路径按会话工作目录解析：宿主进程的 cwd 未必是用户的工作区。
+      const cwd = exec?.agent?.session?.header?.cwd ?? process.cwd()
+      const inputs = Array.isArray(args?.inputs) ? args.inputs : []
+      if (inputs.length === 0) throw new Error('inputs 不能为空：请给出至少一个 .md 文件或目录')
+
+      const files = expandInputs(inputs, cwd)
+      const chrome = findChrome(settings.chromePath)
+      if (chrome === undefined) throw new Error(chromeMissingMessage())
+
+      const css = readFileSync(settings.cssPath ?? DEFAULT_CSS, 'utf8')
+      const outDir = args.out_dir === undefined ? undefined : resolve(cwd, args.out_dir)
+      const headerLabel = args.label ?? settings.headerLabel
+
+      const results = []
+      const browser = await puppeteer.launch({ executablePath: chrome, headless: true })
+      try {
+        for (const input of files) {
+          try {
+            const targetDir = outDir ?? dirname(input)
+            const stem = basename(input, '.md')
+            const produced = await renderOne(browser, {
+              input,
+              htmlPath: resolve(targetDir, `${stem}.html`),
+              pdfPath: resolve(targetDir, `${stem}.pdf`),
+              headerTitle: args.title,
+              headerLabel,
+              css,
+              pageFormat: settings.pageFormat,
+            })
+            generated.add(produced.pdfPath)
+            generated.add(produced.htmlPath)
+            results.push({
+              ...produced,
+              ok: true,
+              downloadUrl: downloadUrl(settings.downloadBaseUrl, produced.pdfPath, 'inline'),
+              htmlUrl: downloadUrl(settings.downloadBaseUrl, produced.htmlPath, 'inline'),
+            })
+          } catch (error) {
+            results.push({ input, ok: false, error: String(error?.message ?? error) })
+          }
+        }
+      } finally {
+        await browser.close()
+      }
+
+      const succeeded = results.filter((item) => item.ok)
+      if (succeeded.length === 0) {
+        throw new Error(results.map((item) => `${item.input}：${item.error}`).join('；'))
+      }
+      return { results, count: succeeded.length, failedCount: results.length - succeeded.length }
+    },
+  })
+
+  // 浏览器预览/下载端点（可选：仅有 webServer 时注册）。
+  ctx.inject(['webServer'], (hostCtx) => {
+    hostCtx.effect(() => hostCtx.webServer.register({
+      kind: 'exact',
+      path: DOWNLOAD_PATH,
+      handler: (request, response) => serveGenerated(request, response, generated),
+    }), 'dsh-md2pdf: download')
+  })
+}
+
+/** 拼一个下载链接（路径整体转义，兼容中文文件名）。 */
+function downloadUrl(base, path, disposition) {
+  return `${base}${DOWNLOAD_PATH}?path=${encodeURIComponent(path)}&disposition=${disposition}`
+}
+
+/** 扩展名 → Content-Type。 */
+const CONTENT_TYPES = {
+  '.pdf': 'application/pdf',
+  '.html': 'text/html; charset=utf-8',
+}
+
+/**
+ * 下载端点处理器：只服务 `generated` 白名单内的文件，且仅限 loopback 直连。
+ * 信任边界与 dsh-email 的 SSE 端点同款：loopback 对端、无代理转发头、
+ * 无 Origin 放行、有 Origin 必须与 Host 同源。
+ * @param request - 入站请求。
+ * @param response - 响应（本函数独占其生命周期）。
+ * @param generated - 本进程产出过的文件绝对路径集合。
+ */
+function serveGenerated(request, response, generated) {
+  const loopback = ['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(request.socket.remoteAddress ?? '')
+  const noProxy = request.headers.forwarded === undefined
+    && request.headers['x-forwarded-for'] === undefined
+    && request.headers['x-real-ip'] === undefined
+  let sameOrigin = true
+  if (typeof request.headers.origin === 'string' && typeof request.headers.host === 'string') {
+    try {
+      sameOrigin = new URL(request.headers.origin).host === request.headers.host
+    } catch {
+      sameOrigin = false
+    }
+  }
+  if (!loopback || !noProxy || !sameOrigin) {
+    response.writeHead(403)
+    response.end('forbidden')
+    return
+  }
+
+  const url = new URL(request.url ?? '/', 'http://localhost')
+  const target = url.searchParams.get('path')
+  if (target === null || target === '') {
+    response.writeHead(400)
+    response.end('missing path')
+    return
+  }
+
+  // 白名单是这个端点唯一且充分的访问控制：它只能读本插件刚写出的文件。
+  const absolute = resolve(target)
+  if (!generated.has(absolute) || !existsSync(absolute)) {
+    response.writeHead(404)
+    response.end('not found (only files generated by this plugin during this session are served)')
+    return
+  }
+
+  const disposition = url.searchParams.get('disposition') === 'attachment' ? 'attachment' : 'inline'
+  const filename = basename(absolute)
+  const contentType = CONTENT_TYPES[extname(absolute).toLowerCase()] ?? 'application/octet-stream'
+  response.writeHead(200, {
+    'content-type': contentType,
+    'content-length': String(statSync(absolute).size),
+    // RFC 5987：中文文件名必须走 filename*，否则头部非法。
+    'content-disposition': `${disposition}; filename*=UTF-8''${encodeURIComponent(filename)}`,
+    'cache-control': 'no-store',
+  })
+  createReadStream(absolute).pipe(response)
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@puwenhui/dsh-md2pdf",
+  "version": "0.1.0",
+  "description": "DSH 插件：Markdown → 单文件 HTML + A4 PDF（同一条渲染管线，页眉按文档首个一级标题自动生成）",
+  "type": "module",
+  "main": "lib/plugin.mjs",
+  "exports": {
+    ".": "./lib/plugin.mjs",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "author": "puwenhui",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "markdown",
+    "pdf",
+    "md2pdf",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "highlight.js": "^11.12.0",
+    "markdown-it": "^15.0.2",
+    "puppeteer-core": "^25.11.0"
+  },
+  "license": "MIT"
+}