火一五 Markdown 视觉渲染管线 v0.1.0

Typora 不需要复刻——它的能力本来就是开源拼装的。这个 skill 把同一套拼装做成 AI 可调用的版本。

愿景: 加速企业向全场景人工智能机器人转变 理念: 打破信息孤岛,用一套系统驱动企业增长

〇、与 huo15-openclaw-office-doc 的边界(必读)

选择规则:用户给"目的+主题"让你写新文档 → office-doc;用户给一份已有的 .md 让你"导出/渲染/换主题/做长图" → 本 skill。

一、能干什么(7 个工具一图)

input.md ──┬──► md2pdf.sh        ──► input.pdf      Chromium 打印,7 主题
           │     └─ md2pdf-puppet.js  (推荐)
           │     └─ pandoc engine     (可选,需 weasyprint/xelatex)
           │
           ├──► md2docx.sh       ──► input.docx     Pandoc + reference.docx 模板
           │
           ├──► md2html.js       ──► input.html     单文件自包含,可邮件可离线
           │
           ├──► md2image.js      ──► input.png      1080px 长图(小红书/朋友圈)
           │
           ├──► md2wechat.js     ──► input.wechat.html  juice 内联,粘到公众号编辑器
           │
           ├──► md-preview.js    ──► http://localhost  改文件自动 reload + 主题热切换
           │
           └──► md-diff.sh <from> <to>  ──► changelog.pdf   git ref 之间的变更报告

二、最小可用流程

# 1. 第一次用先装依赖
bash scripts/install-deps.sh

# 2. 用样例文件试一发
node scripts/md2pdf-puppet.js examples/sample.md             # → examples/sample.pdf
node scripts/md2html.js       examples/sample.md             # → examples/sample.html
node scripts/md2image.js      examples/sample.md             # → examples/sample.png(小红书)
node scripts/md2wechat.js     examples/sample.md             # → examples/sample.wechat.html

# 3. 实时预览
node scripts/md-preview.js    examples/sample.md             # 浏览器开 http://127.0.0.1:7777

三、主题选择决策树(给 AI 用)

v0.4.0 起 11 套主题分两大流派阵营:信息密集(给信息读者)/ 视觉沉浸(给阅读者)。 设计规范完整版见 themes/DESIGN.md。

信息密集类(短段落 + 列表 + 代码)

视觉沉浸类(长段落 + 节奏 + 留白)

多端发布类(目标编辑器特殊)

用户没说就默认 typora-newsprint(报纸风为通用合理基线)。 做技术文档无脑选 anthropic-doc(2026 年行业主流审美)。

四、关键参数速查

md2pdf-puppet.js

node scripts/md2pdf-puppet.js <input.md> [output.pdf] \
  --theme typora-newsprint     # 11 选 1(见 §三 决策树)
  --paper A4                   # A4 / Letter / A3 / A5
  --margin 18                  # 四边等距 mm(默认 18)
  --header "我的文档"          # 自定义页眉(huo15-brand 主题已内置)
  --footer "{pageNumber} / {totalPages}"
  --print-urls                 # 链接后追加 (URL) 文本
  --no-mermaid                 # 跳过 mermaid 等待加速

md2docx.sh(需先装 pandoc)

bash scripts/md2docx.sh <input.md> [output.docx] \
  --no-toc                              # 不要目录
  --reference templates/reference.docx  # 自定义模板

md2image.js

node scripts/md2image.js <input.md> [output.png] \
  --theme xiaohongshu          # 默认 xiaohongshu
  --width 1080                 # 画幅宽度
  --scale 2                    # 倍清(2 = retina)

md-diff.sh

bash scripts/md-diff.sh <from-ref> <to-ref> [output.pdf] \
  --theme huo15-brand          # 默认 huo15-brand
  --repo /path/to/git/repo     # 默认当前目录

五、AI 调用模式(集成到对话流)

模式 A:一步导出

用户:"把这份分析报告导成 PDF 给我" AI:Bash → bash scripts/md2pdf.sh /tmp/report.md /tmp/report.pdf --theme huo15-brand

模式 B:导出 + 转发(联动 huo15-wecom)

用户:"复盘报告导成 PDF 发到运营群"

1. AI 写 report.md 到 /tmp
2. AI 调本 skill 导 PDF → /tmp/report.pdf
3. AI 调 huo15-wecom 发文件到目标群

模式 C:多端并行(一份 md 多种产出)

用户:"这篇文章我要发公众号 + 小红书 + 个人博客" AI 并行:

• md2wechat.js article.md → 公众号粘贴版
• md2image.js article.md --theme xiaohongshu → 小红书长图
• md2html.js article.md --theme typora-newsprint → 博客 HTML

模式 D:AI 改主题

用户:"主题再暖一点,标题大一点" AI 用 Edit 工具直接改 themes/typora-newsprint.css 的 --accent 与 h1 font-size,不需要写新脚本——这是本 skill 的元能力。

模式 E:版本对比 PDF

用户:"v1.2 到 v1.3 都改了什么,出个 PDF 给客户" AI:bash scripts/md-diff.sh v1.2.0 v1.3.0 release-notes.pdf --theme huo15-brand

模式 F:企微/钉钉/微信对话渲染送达(配合 enhance,最常用)

用户(在企微对话框):"把这份复盘渲染成 PDF 发给我"

1. AI 调 bash scripts/md-share.sh report.md --mode pdf --label "Q1 复盘报告"
2. AI 拿到 stdout 的 JSON,看到 files[0].path = /tmp/.../report-20260505.pdf
3. AI 按 JSON.next_actions 顺序:优先调 enhance_share_file({filePath, label, expireHours: 24})
4. 拿到 structuredContent.url = https://keepermac.huo15.com/plugins/enhance-share/<token>-report-20260505.pdf
5. AI 把 url 作为 outbound 消息回到当前会话,企微用户在对话框点链接下载/查看 若无 enhance:JSON 的 priority=2 fallback,AI 把本地 path 告诉用户(降级,但不报错)

模式 G:发布 + 多端 + 自动归档(v0.3.0,复盘场景首选)

用户:"把 Q1 复盘发布出去,我可能要发企微 + 朋友圈 + 邮件" AI:bash scripts/md-publish.sh report.md --slug q1-summary --label "Q1 复盘"(默认 mode=all) → 一次渲染 4 端产物 + 写归档 ~/knowledge/huo15/<日期>-<slug>.md + JSON.post_share_actions → 4 个 file 各调一次 enhance_share_file 拿 URL → AI 用 Edit 把 URL 回写到 KB 归档 frontmatter share_urls: → 组装"多版本菜单"消息回当前会话(PDF / 长图 / HTML / 公众号 inline)— 用户自己决定转发哪个,不替用户广播 加 --with-qr 触发"二阶段二维码":AI 用 PDF URL 二刷 md2pdf-puppet --qr-url <url> 出打印版

模式 H:卡片预览(v0.3.0)

用户:"发个链接给同事,要在企微对话框里直接看到标题+摘要预览" AI:md2html.js 生成 HTML(默认从 markdown 抽 H1 + 首段作 OG title/description)→ enhance_share_file → 发企微 同事看到带卡片预览的链接(微信/企微/Slack/Twitter 都支持 OG)

模式 I:线下纸质 ↔ 线上文档(v0.3.0)

用户:"客户提案打印 50 份发线下,客户能扫码看在线版" 两阶段:① md-publish.sh proposal.md --mode pdf --with-qr 拿 PDF URL ② md2pdf-puppet --qr-url <PDF URL> --qr-label "扫码看完整在线版" 二维码进每页页脚 用户打印 → 客户扫码 → 跳 enhance 公网链接看高保真 PDF

六、自定义主题(给 AI 的)

用户说"我要 X 风格" → AI 直接改 CSS,不要重写脚本:

1. 先读 themes/DESIGN.md(8 大设计范式 + 红线清单 + 命名规范)
2. 复制最相近的主题到新文件:cp themes/typora-newsprint.css themes/<my-theme>.css
3. 改 :root 中的 token override(差异化变量,如 --font-body / --color-accent / --measure / --leading)— 不要复制 _tokens.css 的内容,render.js 自动 prepend
4. 写本主题独有的"特征"(双线 / drop cap / 边注 / 居中标题等)
5. 在 scripts/lib/render.js 的 AVAILABLE_THEMES 数组加新名字
6. 在本 SKILL.md 第三节决策树加一行
7. 立刻可用:--theme <my-theme>

主题文件不允许:

• 塞 <script> / 远程 @import 字体(打印会卡)/ JS
• 用 Inter / Roboto 默认字体(反 AI Slop 红线 — 见 DESIGN.md §1.7)
• h2/h3 加左竖条装饰(同上,2023 ChatGPT 卡片风泛滥)
• 渐变背景 / 大 box-shadow 红紫光晕(同上)

七、依赖说明

默认路线(puppeteer)只需 npm install,不依赖 pandoc;企微集成所需的 enhance 也是可选,无 enhance 仍能用本机渲染。

八、踩坑提示(给 AI 的预防针)

1. 微信公众号粘贴丢样式:必须用 md2wechat.js(已 juice 内联),不能直接用 md2html.js 的输出粘
2. mermaid 渲染需要联网:md2pdf-puppet.js 默认从 jsdelivr CDN 加载 mermaid 运行时,离线环境加 --no-mermaid
3. 小红书长图过长会被压缩:超过 5000px 时拆成两张,先用 markdown 二级标题分段后分别导
4. 学术 PDF 中文断行:academic 主题用衬线英文优先,中文长段落建议手动加空格断词,或改用 huo15-brand 主题
5. 品牌页眉页脚只在 huo15-brand 主题生效:其他主题想要页眉用 --header 参数手动加
6. reference.docx 不存在不报错:Pandoc 自动用内置默认。想要品牌 Word → 见 templates/README.md
7. 严禁手写 enhance-share URL:配合 enhance 时,必须从 enhance_share_file 工具的 structuredContent.url 取真实链接。不能手写、拼接、猜测、回忆类似 http://localhost:18789/<file>、/plugins/enhance-share/<filename>(缺 token)等任何形式——它们都不是真实链接,用户点了只会 404。这条与 enhance v5.7.24+ 的规则一致
8. md-preview.js 不要直接暴露给企微用户:它绑 127.0.0.1,内网穿透看不见。企微场景必用 md-share.sh + enhance_share_file 链路
9. md-share.sh / md-publish.sh 不调 enhance:本 skill 输出 JSON 的 next_actions 是指示,不是直接调用——独立装本 skill(没装 enhance)依然能跑(降级 priority=2 输出本地路径)
10. md-publish 不替用户广播:即使用户说"发到所有群",也只输出 4 个 URL 让用户自己转发。严禁 AI 主动调 wecom 类工具广播——这是 §6.5 + memory lesson_wecom_at_all_broadcast.md v2.8.1 @all 事故的红线
11. OG 卡片需要公网 URL 才显示完整:HTML 自包含可粘到本地预览,但只有把 HTML 通过 enhance_share_file 暴露到公网,微信/企微/Slack 抓 OG meta 时才会渲染卡片(本机 file:// 不会触发卡片抓取)
12. 二维码两阶段不能合一:md2pdf-puppet --qr-url 必须传一个已存在的公网 URL——不能在第一阶段渲染 PDF 时就嵌"未来这个 PDF 的 URL"(鸡生蛋问题)。正确流程:第一阶段 publish 拿 PDF URL → 第二阶段用该 URL 重渲染带 QR 的 PDF
13. KB 归档 frontmatter 的 share_urls 由 AI 回写:md-publish 写归档时 share_urls 留空数组,AI 拿到 enhance URL 后用 Edit 工具回写——脚本不调 enhance,所以脚本自己写不出 URL(capability detection 设计的代价)

九、企微 / 钉钉 / 微信场景:capability detection 集成 enhance

设计原则(与 §11.4 红线 + memory feedback_plugins_must_be_independently_installable.md 一致)

• ✅ 本 skill 不 import / 不依赖 enhance
• ✅ md-share.sh 仅渲染 + 输出标准 JSON
• ✅ 由调用 skill 的 AI 在运行时检测 enhance 是否在场:enhance_share_file 工具可见 → 调它拿 URL;不可见 → 给本地路径
• ❌ 不写跨插件 import,不写"if enhance 装了"的硬判断,不在脚本里 spawn 任何 plugin

工作流图

企微用户:"把这份分析报告导成 PDF 发我"
        │
        ▼
   OpenClaw inbound
        │
        ▼
   AI 看到 SKILL.md §九 模式 F
        │
        ▼
   bash scripts/md-share.sh report.md --mode pdf --label "..."
        │
        │ stdout: {"files":[{"path":"/tmp/.../report-TS.pdf",...}], "next_actions":[...]}
        ▼
   AI 按 next_actions priority=1 尝试:
   enhance_share_file({filePath, label, expireHours: 24})
        │
        ├─ 工具可见 ─→ 拿 structuredContent.url ─→ outbound 发链接到企微 ─→ ✓
        │
        └─ 工具不可见 / 调用失败 ─→ priority=2 fallback ─→
                                 outbound 把 file.path 告诉用户(降级)

md-share.sh 用法速查

# 单一格式
bash scripts/md-share.sh report.md --mode pdf --label "Q1 复盘报告"
bash scripts/md-share.sh post.md   --mode image --theme xiaohongshu  # 小红书长图
bash scripts/md-share.sh news.md   --mode wechat                      # 公众号 inline

# 一份 md 多端并行(企微一次给齐 PDF + 长图 + 网页 三个链接)
bash scripts/md-share.sh report.md --mode all --label "战略分析报告"

# 长效链接(客户 30 天内可访问)
bash scripts/md-share.sh proposal.md --mode pdf --expire-hours 720 --label "客户提案 v1"

md-publish.sh 用法速查(v0.3.0,比 md-share 多了 KB 归档 + 多端默认)

# 默认:mode=all,自动归档到 ~/knowledge/huo15/<日期>-<slug>.md
bash scripts/md-publish.sh report.md --slug q1-summary --label "Q1 复盘报告"

# 客户提案(打印场景):带二维码,二阶段 AI 自动二刷 PDF
bash scripts/md-publish.sh proposal.md --slug client-proposal-v1 \
  --label "客户提案 v1" --with-qr --expire-hours 720

# 不归档(纯发布,不写知识库)
bash scripts/md-publish.sh quick-note.md --no-archive

# 自定义归档目录
bash scripts/md-publish.sh internal.md --kb-dir ~/work/wiki/2026-q2

# 仅 PDF + 归档
bash scripts/md-publish.sh report.md --mode pdf --slug q1-summary

md-publish vs md-share 选择:

• 一次性"发我看看" → md-share(轻量)
• "发布出去 + 留档案" → md-publish(归档 + 多端默认 + 二维码可选)
• 复盘 / 客户提案 / 周月报 / 公司公告 → md-publish

v0.3.0 新增能力(简表)

• OG 卡片:md2html 默认从 H1 + 首段抽 og:title/description;显式覆盖用 --og-title/--og-description/--og-image/--og-url。HTML 粘到企微/微信/Slack 自动渲染卡片
• PDF 二维码:两阶段 — ①拿 PDF URL ②md2pdf-puppet --qr-url <URL> --qr-label "扫码看在线版",二维码进每页右下角页脚(huo15-brand 主题最佳)

输出 JSON(stdout)始终遵循 schema:

{
  "status": "render_complete",
  "files": [{ "path": "/tmp/.../xxx.pdf", "kind": "pdf", "label": "...", "size_kb": 234, "mime": "...", "theme": "huo15-brand" }],
  "next_actions": [
    { "priority": 1, "tool": "enhance_share_file", "args_per_file": {...}, "result_field": "structuredContent.url", "warning": "严禁手写 URL" },
    { "priority": 2, "tool": null, "fallback": "把 path 告诉用户" }
  ],
  "ai_instruction": "对每个 file 优先 priority=1,失败降级 priority=2"
}

AI 触发判断(给读 SKILL.md 的 AI)

用户出现以下意图就走模式 F:

• "发给我 / 发给客户 / 发到群里" — outbound 意图
• "链接给我 / 给我个链接 / 公网链接 / 分享链接" — URL 需求
• "给我看看 / 看效果 / 预览" + 渠道在 IM(企微/钉钉/微信)— 视觉送达
• 当前会话来自企微/钉钉/微信 inbound — 渠道天然适配 enhance

如果用户只是说"导出 PDF" 而没有发送/链接意图,走模式 A(纯本机文件输出);用户后续说"发我" 再切到模式 F。

十、文件清单

huo15-markdown-export/
├── SKILL.md / README.md / package.json / _meta.json / LICENSE
├── scripts/
│   ├── install-deps.sh / install-to-workspaces.sh
│   ├── md2pdf.sh + md2pdf-puppet.js   # PDF
│   ├── md2docx.sh                      # Word(Pandoc)
│   ├── md2html.js                      # HTML 自包含 + OG 卡片
│   ├── md2image.js                     # 长图 PNG
│   ├── md2wechat.js                    # 微信公众号 inline
│   ├── md-preview.js                   # 127.0.0.1 live preview
│   ├── md-share.sh / md-publish.sh    # 对接 enhance(JSON)
│   ├── md-diff.sh                      # git → changelog PDF
│   └── lib/render.js                   # 共享渲染核心
├── themes/
│   ├── DESIGN.md   ⭐ v0.4.0          # 设计规范(必读)
│   ├── _tokens.css ⭐ v0.4.0          # design tokens
│   ├── typora-newsprint / -night / github / academic / huo15-brand
│   ├── anthropic-doc / editorial-magazine / manuscript-book / tufte-handout  ⭐ v0.4.0
│   └── wechat / xiaohongshu           # hardcode(目标编辑器剥 var)
├── templates/{pdf-print.css, README.md}
└── examples/{sample.md, chart-demo.md}

十一、版本

• v0.4.0(2026-05-07):主题系统重构 + 4 个新预设
  • 抽 themes/_tokens.css(全局 design tokens:字体栈 / 字号阶梯 1.25 Major Third / 行高档位 / 留白 8pt grid / 容器宽 / 语义色)
  • render.js 自动为 9 个支持 token 的主题 prepend _tokens.css,wechat / xiaohongshu 因目标编辑器剥 var 保留 hardcode
  • 新增 themes/DESIGN.md — 8 大设计范式 + 反 AI Slop 红线 + 主题选择决策树 + 新主题 7 步 checklist + 发版前红线 grep 自查
  • 重构 5 旧主题(newsprint / night / github / academic / brand)用 token,代码量 ~40% 收缩
  • 修 3 处 AI Slop 红线:typora-night 字体 Inter → system-ui + 暗底 #1f2329 → #121212;huo15-brand 去 h2 左竖条 + 改 60-30-10(strong / h3 不再染主色,主色降到 ≤10%);xiaohongshu 去渐变背景 + 去 strong 渐变高亮 + 去图片红光晕
  • 新增 4 个预设:
    • anthropic-doc — Anthropic / Stripe 技术文档风,衬线正文 + 灰底代码 + 极少装饰(2026 年技术文档主流审美)
    • editorial-magazine — 商业杂志体,Playfair Display 大字 + drop cap + 满版图 + 大留白(品牌故事 / 深度长文)
    • manuscript-book — 书稿 / 小说体,单一衬线 + 1.95 行高 + 章标居中 + 0 装饰 + 段首缩进(无干扰沉浸阅读)
    • tufte-handout — Tufte 边注体,窄主文 + 右挂边注(≥1100px)+ 三线表 + ET Book 衬线感(数据分析 / 研究报告)
  • 主题决策树拆"信息密集 / 视觉沉浸 / 多端发布"三阵营(更易选)
• v0.3.1(2026-05-06):scripts/install-to-workspaces.sh 治本多 workspace 安装陷阱(双层 root + node_modules symlink)
• v0.3.0(2026-05-06):md-publish.sh 多端发布 + KB 归档;HTML OG 卡片;PDF --qr-url 二维码;qrcode 依赖
• v0.2.0(2026-05-05):md-share.sh + capability detection 集成 enhance(企微对话拿公网 URL)
• v0.1.0(2026-05-05):首发。7 主题 + 7 脚本 + KaTeX + mermaid + highlight.js + 品牌页眉页脚

详细 changelog 见 git log / cnb.cool 仓库 commit history

公司: 青岛火一五信息科技有限公司 · postmaster@huo15.com · QQ群 1093992108