@jiyeqian/md2pdf 1.4.0

package/skill/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: md-to-pdf
+description: 把 Markdown 文件排成优雅的中文 A4 PDF（报头＋元信息条＋表格/代码/引用排版＋页脚页码＋PDF 书签大纲），支持 elegant 与 minimal 两套主题、可点击目录与批量转换。当用户要求"把 md 转成 PDF""导出成 PDF""打印成 PDF""生成优雅的 PDF""PDF 要有目录/书签"时使用。
+agent_created: true
+---
+
+# Markdown → 优雅 PDF
+
+有现成命令 `md2pdf`，直接用，不要临时手写 HTML + 调 Chrome。
+
+## 直接用
+
+```bash
+md2pdf 文件名.md                    # 同目录同名输出 .pdf
+md2pdf 文件名.md --open             # 转完直接打开
+md2pdf a.md b.md -o 输出目录/       # 批量（目录不存在会自动创建）
+md2pdf 文件名.md --theme minimal --toc
+```
+
+## 程序在哪
+
+- **命令入口**：npm 全局 bin 目录里的 `md2pdf`
+- **程序本体**：npm 全局包 `@jiyeqian/md2pdf`（`node_modules/@jiyeqian/md2pdf/`）
+- **源码仓库**：https://cnb.cool/jiyeqian/md2pdf （Public，唯一实现的源头）
+- **本说明书**：仓库里的 `skill/SKILL.md`，安装时由 npm `postinstall` 复制到技能目录
+  （WorkBuddy 下即 `~/.workbuddy/skills/md-to-pdf/SKILL.md`）
+
+**没装过 / 换了机器** —— 一条命令（命令与说明书一起装好）：
+
+```bash
+npm install -g @jiyeqian/md2pdf
+```
+
+若 `command -v md2pdf` 为空，就是没装，跑上面这条即可。
+
+**升级**：`npm update -g @jiyeqian/md2pdf` · **卸载**：`npm uninstall -g @jiyeqian/md2pdf`
+
+环境变量：`MD2PDF_SKILL=0` 不装说明书；`MD2PDF_SKILL_DIR=<dir>` 指定技能目录。
+
+## 常用选项
+
+| 选项 | 作用 |
+| --- | --- |
+| `-o, --output <path>` | 输出路径；多文件或目标是目录时作为输出目录 |
+| `--theme <name>` | `elegant`（默认，墨蓝＋古铜）｜ `minimal`（黑白公文风） |
+| `--title` / `--kicker` | 覆盖标题 / 报头小标题 |
+| `--no-meta` / `--no-lead` | 去掉元信息条 / 首段不作为导语 |
+| `-t, --toc` | 文首插入目录页（取自 H2），条目可点击跳转 |
+| `--no-outline` | 不生成 PDF 书签（默认生成） |
+| `--link-urls` | 链接后附 URL |
+| `--landscape` / `--font-size` / `--margin` | 横向 / 字号（默认 10.5pt）/ 页边距（默认 20mm） |
+| `--no-footer` / `--footer-left` / `--footer-right` | 页脚控制 |
+| `--keep-html` / `--open` | 留中间 HTML 调样式 / 转完打开 |
+| `--html-only` | 只出 HTML 不启动浏览器（调样式、CI 校验用） |
+
+布尔选项支持 `--flag=false`。环境变量：`MD2PDF_CHROME`、`MD2PDF_NODE`、`MD2PDF_WS=mini`。
+完整列表见 `md2pdf --help` 或项目 README。
+
+## 排版规则（需要解释效果时看这里）
+
+首个 H1 提升为报头大标题、其后首段成为导语；frontmatter 的 name/description 生成元信息条
+（"适用于…""不用于…"自动拆两栏）；H2 自动分节并加 id 锚点；相对路径图片转 file://；
+页脚页码由 CDP `Page.printToPDF` 生成（CLI `--print-to-pdf` 不支持页眉页脚模板）。
+
+**目录页与书签是两件事**，别混：
+- **目录页**（`-t`，默认关）＝ 文首排的一张目录，条目是文档内可点击的内链
+- **PDF 书签**（默认开，`--no-outline` 关）＝ 阅读器侧边栏的章节大纲树
+  由 Chrome 按 HTML 的 h1–h6 结构生成（报头标题为根，H2/H3 嵌套）；阅读器侧栏
+  需用户自己展开（macOS 预览按 ⌘⌥3）。用户问"为什么侧栏是空的"时先确认是不是
+  老版本 Chrome 没生成（参数不被支持时会静默退回无书签渲染）。
+
+验一份 PDF 到底有没有书签：
+
+```bash
+node ci/inspect-pdf.mjs out.pdf   # 打印书签树、内链/外链数量
+```
+
+改样式：`assets/base.css`（骨架）与 `assets/theme-*.css`（配色）。
+用户态改 npm 全局包里的 `assets/`；开发态（见下）改仓库即时生效。
+
+## 开发这个工具
+
+源码仓库就是唯一实现：
+
+```bash
+git clone https://cnb.cool/jiyeqian/md2pdf.git
+cd md2pdf && npm link           # 切到开发态：命令指回仓库，改代码立即生效
+```
+
+
+改完代码跑校验（几秒钟、无需浏览器）：
+
+```bash
+bash ci/validate.sh              # 本地与 CNB 云原生构建跑的是同一套
+```
+
+推送后 CNB 自动跑同一套校验；打 tag 则自动 `npm publish` 发新版，用户 `npm update -g` 即可拿到。
+发版前记得同步 `src/md2pdf.mjs` 的 `VERSION` 与 `package.json` 的 `version`（校验会检查一致）。

package/src/install-skill.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * npm postinstall —— 把 skill/SKILL.md 装进 Agent 技能目录（WorkBuddy）。
+ *
+ * 纯 Node、零依赖。默认只在存在 ~/.workbuddy 时安装，保持与旧 install.sh 一致：
+ *   MD2PDF_SKILL=0        跳过安装
+ *   MD2PDF_SKILL_DIR=<d>  覆盖落点（默认 ~/.workbuddy/skills/md-to-pdf）
+ *
+ * 技能安装失败只告警、不失败 —— 不能让 npm install 因为装技能而整体失败。
+ */
+
+import { mkdir, copyFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SRC = path.join(ROOT, 'skill', 'SKILL.md');
+
+if (process.env.MD2PDF_SKILL === '0') process.exit(0);
+if (!existsSync(SRC)) process.exit(0);
+
+const home = process.env.HOME || os.homedir();
+let skillDir = process.env.MD2PDF_SKILL_DIR;
+if (!skillDir && home && existsSync(path.join(home, '.workbuddy'))) {
+  skillDir = path.join(home, '.workbuddy', 'skills', 'md-to-pdf');
+}
+if (!skillDir) process.exit(0);
+
+try {
+  await mkdir(skillDir, { recursive: true });
+  await copyFile(SRC, path.join(skillDir, 'SKILL.md'));
+  console.log(`md2pdf: 已安装技能说明书 → ${path.join(skillDir, 'SKILL.md')}`);
+} catch (e) {
+  console.warn(`md2pdf: 技能说明书安装失败（${e.message}），命令本身不受影响`);
+}

package/src/md2pdf.mjs

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+/**
+ * md2pdf —— 把 Markdown 排成优雅的 A4 PDF（无头 Chrome + CDP）
+ *
+ * 用法：md2pdf <file.md> [file2.md ...] [选项]
+ *
+ * 选项：
+ *   -o, --output <path>   输出 PDF（单文件时可用；多文件时忽略）
+ *       --theme <name>    elegant（默认）| minimal
+ *       --title <text>    覆盖标题（默认取正文首个 H1，其次 frontmatter.title，其次文件名）
+ *       --kicker <text>   报头小标题（如"专利实务 · 技能文档"）
+ *       --no-meta         不生成元信息条
+ *       --no-lead         首段不作为导语放大
+ *   -t, --toc             生成目录（取自 H2）
+ *       --link-urls       正文链接后附 URL
+ *       --landscape       横向页面
+ *       --font-size <pt>  正文字号，默认 10.5
+ *       --margin <mm>     页边距，默认 20（上下同为 18/20，左右同值）；可写 "20,18"
+ *       --no-footer       不输出页脚页码
+ *       --footer-left  <text>   页脚左文字（默认空）
+ *       --footer-right <text>   页脚右文字（默认空）
+ *       --colophon <text> 文末落款（默认：来源文件名）
+ *       --keep-html       保留中间 HTML，便于调样式
+ *       --open            完成后打开 PDF
+ *   -h, --help
+ *
+ * 环境变量：
+ *   MD2PDF_CHROME  指定 Chrome/Edge/Chromium 可执行文件路径
+ *   MD2PDF_WS=mini 强制使用内置 WebSocket 实现（Node < 22 时自动启用）
+ */
+
+import { readFile, writeFile, mkdtemp, rm, mkdir } from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import http from 'node:http';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ASSETS = path.join(ROOT, 'assets');
+
+const VERSION = '1.4.0';
+
+// Node ≥ 22 有全局 WebSocket；更老的版本退回到内置的极简实现
+let _WS;
+async function getWSClass() {
+  if (_WS) return _WS;
+  if (process.env.MD2PDF_WS === 'mini' || typeof WebSocket === 'undefined') {
+    _WS = (await import('./ws.mjs')).MiniWebSocket;
+  } else {
+    _WS = WebSocket;
+  }
+  return _WS;
+}
+
+const HELP = `
+md2pdf ${VERSION} —— Markdown → 优雅 PDF
+
+  md2pdf <file.md> [file2.md ...] [选项]
+
+选项：
+  -o, --output <path>      输出路径（默认与输入同目录同名 .pdf）
+      --theme <name>       elegant（默认，墨蓝+古铜）| minimal（黑白公文）
+      --title <text>       覆盖标题
+      --kicker <text>      报头小标题
+      --no-meta            不生成元信息条
+      --no-lead            首段不作为导语
+  -t, --toc                在文首插入目录页（取自二级标题，可点击跳转）
+      --no-outline         不生成 PDF 书签（默认生成，阅读器侧边栏按标题成树）
+      --link-urls          正文链接后附 URL
+      --landscape          横向
+      --font-size <pt>     正文字号（默认 10.5）
+      --margin <mm>        页边距（默认 20；可写 "20,18" = 上下,左右）
+      --no-footer          不要页脚页码
+      --footer-left/--footer-right <text>
+      --colophon <text>    文末落款
+      --keep-html          保留中间 HTML
+      --html-only          只生成 HTML，不启动浏览器（调试样式 / CI 校验用）
+      --open               完成后打开 PDF
+  -h, --help
+
+示例：
+  md2pdf SKILL.md
+  md2pdf notes.md --theme minimal --toc --open
+  md2pdf a.md b.md -o /tmp/   # 多文件时 -o 视为输出目录
+`;
+
+/* ---------------- 参数 ---------------- */
+
+// 展开 --flag=value / --flag=false 写法
+function expandArgs(argv) {
+  const out = [];
+  for (const a of argv) {
+    const m = /^(--[a-z][a-z-]*)=(.*)$/i.exec(a);
+    if (m && !['--output', '--footer-left', '--footer-right'].includes(m[1])) {
+      const falsey = /^(false|0|no)$/i.test(m[2]);
+      out.push(falsey ? `--no-${m[1].slice(2)}` : m[1]);
+      if (!falsey && m[2] !== '') out.push(m[2]);
+    } else out.push(a);
+  }
+  return out;
+}
+
+function parseArgs(argv) {
+  const o = {
+    inputs: [], theme: 'elegant', fontSize: 10.5,
+    marginTop: 20, marginSide: 18, marginBottom: 18,
+    footer: true, footerLeft: '', footerRight: '',
+    meta: true, lead: true, toc: false, linkUrls: false, outline: true,
+    landscape: false, keepHtml: false, htmlOnly: false, open: false, help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    switch (a) {
+      case '-h': case '--help': o.help = true; break;
+      case '-o': case '--output': o.output = next(); break;
+      case '--theme': o.theme = next(); break;
+      case '--title': o.title = next(); break;
+      case '--kicker': o.kicker = next(); break;
+      case '--no-meta': o.meta = false; break;
+      case '--no-lead': o.lead = false; break;
+      case '-t': case '--toc': o.toc = true; break;
+      case '--link-urls': o.linkUrls = true; break;
+      case '--landscape': o.landscape = true; break;
+      case '--font-size': o.fontSize = parseFloat(next()); break;
+      case '--margin': {
+        const v = next(); const m = String(v).split(',').map(s => parseFloat(s.trim()));
+        o.marginTop = m[0]; o.marginBottom = m[0]; o.marginSide = m[1] ?? m[0];
+        break;
+      }
+      case '--no-footer': o.footer = false; break;
+      case '--footer-left': o.footerLeft = next(); break;
+      case '--footer-right': o.footerRight = next(); break;
+      case '--colophon': o.colophon = next(); break;
+      case '--keep-html': o.keepHtml = true; break;
+      case '--html-only': o.htmlOnly = true; break;
+      case '--no-html-only': o.htmlOnly = false; break;
+      case '--open': o.open = true; break;
+      case '--no-open': o.open = false; break;
+      case '--no-toc': o.toc = false; break;
+      case '--outline': o.outline = true; break;
+      case '--no-outline': o.outline = false; break;
+      case '--no-landscape': o.landscape = false; break;
+      case '--no-link-urls': o.linkUrls = false; break;
+      case '--no-keep-html': o.keepHtml = false; break;
+      case '--version': o.version = true; break;
+      default:
+        if (a.startsWith('-')) { console.warn(`md2pdf: 忽略未知选项 ${a}`); }
+        else o.inputs.push(a);
+    }
+  }
+  return o;
+}
+
+/* ---------------- 工具 ---------------- */
+
+const esc = s => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const stripTags = s => String(s).replace(/<[^>]+>/g, '').trim();
+
+function splitFrontmatter(src) {
+  const m = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(src);
+  if (!m) return { fm: {}, body: src };
+  const fm = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*)$/.exec(line);
+    if (kv) {
+      let v = kv[2].trim().replace(/^["']|["']$/g, '');
+      fm[kv[1]] = v;
+    } else if (/^\s+/.test(line) && Object.keys(fm).length) {
+      const k = Object.keys(fm).at(-1);
+      fm[k] = (fm[k] + ' ' + line.trim()).trim();
+    }
+  }
+  return { fm, body: src.slice(m[0].length) };
+}
+
+function buildMeta(fm, isSkill) {
+  if (!fm.name && !fm.description) return '';
+  const items = [];
+  if (fm.name) {
+    items.push([isSkill ? 'SKILL NAME' : 'NAME', `<code>${esc(fm.name)}</code>`]);
+  }
+  if (fm.description) {
+    const d = fm.description;
+    const suit = /适用于([^；。]+)/.exec(d);
+    const notsuit = /不用于([^；。]+)/.exec(d);
+    if (suit || notsuit) {
+      if (suit) items.push(['适用', esc(suit[1].trim())]);
+      if (notsuit) items.push(['不适用', esc(notsuit[1].trim())]);
+    } else if (fm.name) {
+      items.push(['说明', esc(d)]);
+    } else {
+      items.push(['DESCRIPTION', esc(d)]);
+    }
+  }
+  if (!items.length) return '';
+  const html = items.map(([l, v]) =>
+    `<div class="meta-item"><span class="meta-label">${esc(l)}</span><span class="meta-value">${v}</span></div>`
+  ).join('\n  ');
+  return `<div class="meta">\n  ${html}\n</div>`;
+}
+
+function sectionize(html) {
+  return html.split(/(?=<h2[\s>])/)
+    .map(p => (p.trim().startsWith('<h2') ? `<section>\n${p}\n</section>` : p))
+    .join('\n');
+}
+
+/* ---------------- Chrome ---------------- */
+
+function findChrome() {
+  if (process.env.MD2PDF_CHROME && existsSync(process.env.MD2PDF_CHROME)) return process.env.MD2PDF_CHROME;
+  const candidates = [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/snap/bin/chromium',
+  ];
+  for (const c of candidates) if (existsSync(c)) return c;
+  for (const name of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser']) {
+    const w = spawnSync('which', [name], { encoding: 'utf8' });
+    if (w.status === 0 && w.stdout.trim()) return w.stdout.trim();
+  }
+  throw new Error('未找到 Chrome/Edge/Chromium，请用环境变量 MD2PDF_CHROME 指定路径');
+}
+
+const getJson = (port, p) => new Promise((res, rej) => {
+  const req = http.get({ host: '127.0.0.1', port, path: p }, r => {
+    let d = ''; r.on('data', c => d += c); r.on('end', () => { try { res(JSON.parse(d)); } catch (e) { rej(e); } });
+  });
+  req.on('error', rej);
+  req.setTimeout(2000, () => req.destroy(new Error('timeout')));
+});
+
+async function waitDevTools(port, ms) {
+  const t0 = Date.now();
+  while (Date.now() - t0 < ms) {
+    try { await getJson(port, '/json/version'); return true; } catch { await new Promise(r => setTimeout(r, 200)); }
+  }
+  throw new Error('Chrome DevTools 启动超时');
+}
+
+class Chrome {
+  constructor(bin, tmpRoot) { this.bin = bin; this.tmpRoot = tmpRoot; }
+  async start() {
+    this.userDataDir = await mkdtemp(path.join(this.tmpRoot, 'chrome-'));
+    const port = 9200 + Math.floor(Math.random() * 700);
+    this.port = port;
+    this.proc = spawn(this.bin, [
+      '--headless=new', '--disable-gpu', '--no-sandbox', '--disable-extensions',
+      '--disable-background-networking', '--no-first-run', '--no-default-browser-check',
+      '--disable-features=Translate,OptimizationHints',
+      `--user-data-dir=${this.userDataDir}`,
+      `--remote-debugging-port=${port}`,
+      'about:blank',
+    ], { stdio: 'ignore' });
+    this.proc.on('error', () => {});
+    await waitDevTools(port, 20000);
+    const list = await getJson(port, '/json/list');
+    const page = list.find(t => t.type === 'page');
+    if (!page) throw new Error('未找到可打印的页面目标');
+    const WS = await getWSClass();
+    this.ws = new WS(page.webSocketDebuggerUrl);
+    await new Promise((res, rej) => { this.ws.onopen = res; this.ws.onerror = rej; });
+    this.id = 0; this.pending = new Map();
+    this.ws.onmessage = e => {
+      const m = JSON.parse(e.data);
+      if (m.id && this.pending.has(m.id)) { this.pending.get(m.id)(m); this.pending.delete(m.id); }
+    };
+    await this.send('Page.enable');
+  }
+  send(method, params) {
+    const id = ++this.id;
+    return new Promise((res, rej) => {
+      this.pending.set(id, m => (m.error ? rej(new Error(m.error.message)) : res(m.result)));
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+  async print(htmlPath, opts) {
+    const loaded = new Promise(res => {
+      const h = ev => {
+        const m = JSON.parse(ev.data);
+        if (m.method === 'Page.loadEventFired') { this.ws.removeEventListener('message', h); res(); }
+      };
+      this.ws.addEventListener('message', h);
+    });
+    await this.send('Page.navigate', { url: pathToFileURL(htmlPath).href });
+    await loaded;
+    await new Promise(r => setTimeout(r, 250));
+    const base = {
+      printBackground: true,
+      preferCSSPageSize: true,
+      landscape: !!opts.landscape,
+      displayHeaderFooter: !!opts.footer,
+      headerTemplate: '<span></span>',
+      footerTemplate: opts.footerTemplate || '<span></span>',
+      marginTop: 0, marginBottom: 0, marginLeft: 0, marginRight: 0,
+    };
+    // PDF 书签：Chrome 按 h1–h6 结构写成 /Outlines 树，阅读器侧边栏可点击跳转。
+    // 老版本 Chrome 不认这个参数，出错就退回不带书签的渲染（页脚页码仍保留）。
+    let res;
+    if (opts.outline) {
+      res = await this.send('Page.printToPDF', { ...base, generateDocumentOutline: true });
+      if (res.error) res = await this.send('Page.printToPDF', base);
+    } else {
+      res = await this.send('Page.printToPDF', base);
+    }
+    if (res.error) throw new Error(`渲染失败：${res.error.message}`);
+    return Buffer.from(res.data, 'base64');
+  }
+  async stop() {
+    try { this.ws && this.ws.close(); } catch {}
+    try { this.proc && this.proc.kill('SIGKILL'); } catch {}
+    try { this.userDataDir && await rm(this.userDataDir, { recursive: true, force: true }); } catch {}
+  }
+}
+
+/* ---------------- 渲染 ---------------- */
+
+async function renderOne(mdPath, opts, chrome, marked, tmpRoot) {
+  const src = await readFile(mdPath, 'utf8');
+  const { fm, body } = splitFrontmatter(src);
+  const isSkill = path.basename(mdPath) === 'SKILL.md' || !!fm.name;
+
+  let html = marked.parse(body, { gfm: true, breaks: false, async: false });
+
+  // 标题：正文首个 H1 → 报头
+  let title = opts.title || fm.title || '';
+  const h1 = /<h1(?:\s[^>]*)?>([\s\S]*?)<\/h1>/.exec(html);
+  if (h1) {
+    const t = stripTags(h1[1]);
+    if (!title) title = t;
+    html = html.replace(h1[0], '');
+  }
+  if (!title) title = path.basename(mdPath, path.extname(mdPath));
+
+  // 导语：移除 H1 后的第一段
+  let lead = '';
+  if (opts.lead) {
+    const p = /<p(?:\s[^>]*)?>([\s\S]*?)<\/p>/.exec(html);
+    if (p && stripTags(p[1]).length > 12 && p.index < 2000) {
+      lead = p[1];
+      html = html.replace(p[0], '');
+    }
+  }
+
+  // 链接 / 图片
+  html = html.replace(/<a\s+href="([^"]*)"([^>]*)>/g, (m, href, rest) =>
+    `<a href="${href}" class="ref"${rest}>`);
+  if (opts.linkUrls) {
+    html = html.replace(/<a\s+href="(https?:\/\/[^"]*)"[^>]*>([\s\S]*?)<\/a>/g,
+      (m, href, text) => `${m} <span class="link-url">(${esc(href)})</span>`);
+  }
+  const dir = path.dirname(path.resolve(mdPath));
+  html = html.replace(/<img\s+([^>]*?)src="([^"]+)"([^>]*)>/g, (m, pre, src, post) => {
+    if (/^(https?:|data:|file:)/.test(src)) return m;
+    const abs = path.resolve(dir, src);
+    return `<img ${pre}src="${pathToFileURL(abs).href}"${post}>`;
+  });
+
+  // 章节锚点：给二级标题补 id，供目录内链与（Chrome 生成的）PDF 书签定位
+  const secIds = [];
+  html = html.replace(/<h2(\s[^>]*)?>([\s\S]*?)<\/h2>/g, (m, attrs = '', inner = '') => {
+    const has = /\sid="/.test(attrs);
+    if (has) {
+      secIds.push({ id: /\sid="([^"]+)"/.exec(attrs)[1], text: stripTags(inner) });
+      return m;
+    }
+    const id = `sec-${secIds.length + 1}`;
+    secIds.push({ id, text: stripTags(inner) });
+    return `<h2${attrs} id="${id}">${inner}</h2>`;
+  });
+
+  // 目录：文首一张可点击的目录页（仅当二级标题多于一个才值得排）
+  let toc = '';
+  if (opts.toc && secIds.length > 1) {
+    toc = `<div class="toc"><div class="toc-title">目 录</div><ol>` +
+      secIds.map(s => `<li><a href="#${s.id}">${esc(s.text)}</a></li>`).join('') + `</ol></div>`;
+  }
+
+  html = sectionize(html);
+
+  // CSS
+  const themeFile = path.join(ASSETS, `theme-${opts.theme}.css`);
+  if (!existsSync(themeFile)) throw new Error(`未知主题：${opts.theme}（可用：elegant, minimal）`);
+  const base = await readFile(path.join(ASSETS, 'base.css'), 'utf8');
+  const theme = await readFile(themeFile, 'utf8');
+  const css = (base + '\n' + theme)
+    .replace(/\{\{PAGE_SIZE\}\}/g, opts.landscape ? 'A4 landscape' : 'A4')
+    .replace(/\{\{MARGIN_TOP\}\}/g, `${opts.marginTop}mm`)
+    .replace(/\{\{MARGIN_BOTTOM\}\}/g, `${opts.marginBottom}mm`)
+    .replace(/\{\{MARGIN_SIDE\}\}/g, `${opts.marginSide}mm`)
+    .replace(/\{\{FONT_SIZE\}\}/g, `${opts.fontSize}pt`);
+
+  const kicker = opts.kicker || fm.kicker || fm.category || (isSkill ? '技能文档' : '');
+  const colophonLeft = opts.colophon ?? (isSkill && fm.name ? `SKILL · ${fm.name}` : path.basename(mdPath));
+  const colophonRight = opts.colophon ? '' : title;
+
+  // 用函数形式替换：既支持多处占位符，也避免用户文本里的 $& 被当作替换模式
+  const fill = (tpl, map) => Object.entries(map).reduce(
+    (s, [k, v]) => s.split(k).join(v), tpl);
+
+  const shell = await readFile(path.join(ASSETS, 'shell.html'), 'utf8');
+  const out = fill(shell, {
+    '{{TITLE}}': esc(title),
+    '{{CSS}}': css,
+    '{{KICKER}}': esc(kicker),
+    '{{LEAD}}': lead,
+    '{{META}}': opts.meta ? buildMeta(fm, isSkill) : '',
+    '{{TOC}}': toc,
+    '{{BODY}}': html,
+    '{{COLOPHON_LEFT}}': esc(colophonLeft),
+    '{{COLOPHON_RIGHT}}': esc(colophonRight),
+  });
+
+  if (opts.htmlOnly) return { title, html: out };
+
+  const tmpDir = await mkdtemp(path.join(tmpRoot, 'doc-'));
+  const htmlPath = path.join(tmpDir, 'index.html');
+  await writeFile(htmlPath, out, 'utf8');
+
+  const footerTemplate = `<div style="width:100%;font-size:8px;color:#8a8578;font-family:-apple-system,'PingFang SC',sans-serif;letter-spacing:.5px;display:flex;justify-content:space-between;padding:0 12mm;">
+      <span style="flex:1;text-align:left;">${opts.footerLeft || ''}</span>
+      <span style="flex:1;text-align:center;"><span class="pageNumber"></span> / <span class="totalPages"></span></span>
+      <span style="flex:1;text-align:right;">${opts.footerRight || ''}</span>
+    </div>`;
+
+  const buf = await chrome.print(htmlPath, { footer: opts.footer, footerTemplate, landscape: opts.landscape, outline: opts.outline });
+
+  if (opts.keepHtml) {
+    await writeFile(mdPath.replace(/\.md$/i, '.html'), out, 'utf8');
+  } else {
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+  return { title, buf };
+}
+
+/* ---------------- main ---------------- */
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+function resolveOutput(mdPath, opts) {
+  const ext = opts.htmlOnly ? '.html' : '.pdf';
+  if (!opts.output) return mdPath.replace(/\.md$/i, ext);
+  const o = path.resolve(opts.output);
+  if (opts.inputs.length > 1 || isDir(o) || o.endsWith(path.sep)) {
+    return path.join(o, path.basename(mdPath, path.extname(mdPath)) + ext);
+  }
+  return o;
+}
+
+async function main() {
+  const opts = parseArgs(expandArgs(process.argv.slice(2)));
+  if (opts.help) { console.log(HELP); return; }
+  if (opts.version) { console.log(VERSION); return; }
+  if (!opts.inputs.length) { console.log(HELP); process.exitCode = 1; return; }
+
+  const { Marked } = await import(pathToFileURL(path.join(ROOT, 'vendor', 'marked.esm.js')).href);
+  const marked = new Marked({ gfm: true });
+
+  const tmpRoot = await mkdtemp(path.join(os.tmpdir(), 'md2pdf-'));
+  // --html-only 不需要浏览器（CI / 调样式时用）
+  const chrome = opts.htmlOnly ? null : new Chrome(findChrome(), tmpRoot);
+  let failed = false;
+  try {
+    if (chrome) await chrome.start();
+    for (const input of opts.inputs) {
+      const mdPath = path.resolve(input);
+      if (!existsSync(mdPath)) { console.error(`✗ 找不到文件：${input}`); failed = true; continue; }
+      try {
+        const res = await renderOne(mdPath, opts, chrome, marked, tmpRoot);
+        const out = resolveOutput(mdPath, opts);
+        await mkdir(path.dirname(out), { recursive: true });
+        if (opts.htmlOnly) {
+          await writeFile(out, res.html, 'utf8');
+          console.log(`✓ ${path.basename(out)}  (HTML ${(res.html.length / 1024).toFixed(0)} KB)`);
+          continue;
+        }
+        const buf = res.buf;
+        await writeFile(out, buf);
+        let pages = '';
+        const info = spawnSync('pdfinfo', [out], { encoding: 'utf8' });
+        if (info.status === 0) {
+          const m = /Pages:\s+(\d+)/.exec(info.stdout);
+          if (m) pages = `，${m[1]} 页`;
+        }
+        console.log(`✓ ${path.basename(out)}  (${(buf.length / 1024).toFixed(0)} KB${pages})`);
+        if (opts.open) {
+          const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          spawn(cmd, [out], { stdio: 'ignore' });
+        }
+      } catch (e) {
+        console.error(`✗ ${input}：${e.message}`);
+        failed = true;
+      }
+    }
+  } finally {
+    if (chrome) await chrome.stop();
+    await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+  }
+  if (failed) process.exitCode = 1;
+}
+
+main().catch(e => { console.error('md2pdf 失败：', e.message); process.exit(1); });