Name: baoyu-markdown-to-html
Author: JimLiu/baoyu-skills

1实现原理 · 为什么它能做到

主体是本地 Bun 脚本 + 仓库内共享包：渲染用 baoyu-md（marked/juice/highlight.js 管线），Mermaid 出图用 baoyu-chrome-cdp 的 headless Chrome 渲染器。

skills/baoyu-markdown-to-html/scripts/main.ts

import { closeRenderer, renderMermaidToPng } from "baoyu-chrome-cdp/mermaid";

注：依赖在 scripts/package.json 声明并由 bun.lock 锁定（baoyu-md ^0.1.1、baoyu-chrome-cdp ^0.1.1）；脚本本身只做参数解析、mermaid 预处理、图片占位符改写、落盘与 JSON 汇报。

Mermaid 代码块被渲染成本地 PNG（headless Chrome + CDP），带内容哈希缓存；Chrome 缺失或渲染失败则回退为 <pre class="mermaid">，转换整体不失败。

skills/baoyu-markdown-to-html/SKILL.md

Code blocks fenced as ` ```mermaid ` are rendered to PNGs via headless Chrome (CDP) and cached at `imgs/.mermaid-cache/mermaid-<hash>.png`.

注：缓存键包含代码/主题/scale/目标宽度/背景/mermaid 版本；依赖包内自带 mermaid.min.js（本地读取，无 CDN 拉取）。

PlantUML 代码块默认由公共 PlantUML 服务渲染：管线注册了 markedPlantUML，默认 serverUrl 指向 plantuml.com，因此图表源码会出网到第三方服务。

packages/baoyu-md/src/extensions/plantuml.ts

serverUrl: options.serverUrl || `https://www.plantuml.com/plantuml`,

注：注册点在 packages/baoyu-md/src/renderer.ts（`markedPlantUML({`），而本 skill 的 renderMarkdownDocument → initRenderer 会经过该渲染器（packages/baoyu-md/src/document.ts 调用 initRenderer）。SKILL.md 也把 PlantUML 列为支持特性，故这是默认可用路径。

文档里的远程图片会被下载到临时目录，再在 HTML 里改写为带 data-local-path 的 img 标签（便于下游平台/客户端再上传）。

packages/baoyu-md/src/images.ts

await downloadFile(imagePath, localPath);

注：触发条件：图片源以 http(s):// 开头（`if (imagePath.startsWith("http://") || imagePath.startsWith("https://")) {`）；本 skill 只在存在远程图片时才建临时目录（main.ts 的 hasRemoteImages 分支）。下载走 node:http/https，UA 为 Mozilla/5.0，跟随 301/302。

输出与备份纪律：HTML 写回与源文件同目录同名（.html），已存在则先重命名备份，最后把结果作为 JSON 打到 stdout。

skills/baoyu-markdown-to-html/scripts/main.ts

backupPath = `${finalHtmlPath}.bak-${formatTimestamp()}`;

注：SKILL.md 写明冲突处理：`Backup: /path/to/article.html.bak-YYYYMMDDHHMMSS`，JSON 输出含 htmlPath/backupPath/contentImages/mermaidImages 等字段。

主题/颜色/字号/引用模式是外部可配的显式选项；--cite 会把普通外链收成底部编号引用，但微信自家链接保持原位。

skills/baoyu-markdown-to-html/SKILL.md

`https://mp.weixin.qq.com/...` links stay as direct links and are not moved to the bottom.

注：主题解析顺序：CLI --theme > 本 skill EXTEND.md default_theme > baoyu-post-to-wechat EXTEND.md default_theme（跨 skill 回退）> 询问用户；--cite 默认关闭（SKILL.md：'Default: Off. Do not ask by default.'）。

流程前置会做中文检测，并在用户同意时先调用 baoyu-format-markdown 清洗（修 CJK 加粗解析失败与中英间距）。

skills/baoyu-markdown-to-html/SKILL.md

**If user agrees**: Invoke `baoyu-format-markdown` skill to format the file, then use formatted file as input.

注：Step 0 仅在输入含 CJK 时触发；用户拒绝则用原文件继续——这是一处跨 skill 的可选调用，会引入 baoyu-format-markdown 自身的行为（含其 npx 依赖）。

配置面是 EXTEND.md（默认主题、自定义 CSS 变量、代码块样式、mermaid 主题/scale/背景），三级路径首个命中即用，未找到则用默认值、不做首次安装流程。

skills/baoyu-markdown-to-html/SKILL.md

**EXTEND.md supports**: default theme, custom CSS variables, code block style, mermaid defaults (`mermaid_theme`, `mermaid_scale`, `mermaid_background`).

注：与其他 baoyu skill（image-gen/wechat 会强制首次配置）不同，本 skill 无 EXTEND.md 也可直接工作。

2核心能力

01Markdown → 内联 CSS 的样式化 HTML（四套主题 default/grace/simple/modern + 13 个颜色预设 + 字体/字号选项）

02Mermaid 渲染为本地 PNG（headless Chrome/CDP + 哈希缓存 + 失败回退 `<pre class="mermaid">`）

03外部链接转底部引用（--cite，可选），微信链接与纯 URL 链接除外

04图片占位符改写与本地路径回报（contentImages 含 placeholder/localPath/originalPath）

05丰富的 Markdown 方言支持：GFM 表格、代码高亮、alert、脚注、ruby 注音、数学、PlantUML

06结果以 JSON 汇报（htmlPath/backupPath/contentImages/mermaidImages），便于 agent 继续下游流程

3外部依赖

类型	依赖
package	baoyu-md（npm，仓库 packages/ 内的共享包；marked/juice/highlight.js/remark 管线）
package	baoyu-chrome-cdp（npm，仓库 packages/ 内共享包；提供 CDP 与 mermaid 渲染器）
network	PlantUML 公共渲染服务（默认 serverUrl，图表源码经 GET 送出）
network	Markdown 中出现的任意 http(s) 图片主机（下载到本地临时目录）
cli	本地 Chrome/Chromium/Edge（headless 渲染 Mermaid；缺失则回退）
cli	bun（首选运行时；无 bun 时 npx -y bun）

4风险提醒风险提醒：橙色 · 评估后使用

风险提醒：橙色 · 评估后使用

PlantUML 源码默认出网到第三方公共服务器 — 含 plantuml 代码块的文档会把图表源码 GET 到 www.plantuml.com；若图表含内部架构/表结构等敏感信息即等于主动外发。规避：不使用 plantuml 块，或在依赖层覆盖 serverUrl（当前 skill 未暴露该 CLI 开关）。
文档中的远程图片会被本机抓取 — 脚本会按文档里的任意 http(s) URL 下载图片到临时目录（UA 伪装为 Mozilla/5.0、跟随重定向）。处理来源不明的 Markdown 时相当于让本机按对方指示访问任意地址（含内网地址）。
Mermaid 以 securityLevel: loose 在本机无头 Chrome 中渲染文档内容 — 渲染的是用户文档里的图表代码（可含 HTML 标签/交互定义），运行于本地 headless Chrome；无凭证环境但与浏览器其他进程共享机器，建议只转换可信来源的文档。
跨 skill 依赖与偏好回退 — 前置可选调用 baoyu-format-markdown（会引入其 npx autocorrect-node 行为），主题又可能回退读 baoyu-post-to-wechat 的 EXTEND.md；链路上任一偏好文件被改写都会改变本 skill 的默认主题。

风险提醒：橙色，评估后使用。三段自证：① 判级对象是本 skill 目录（SKILL.md + scripts/main.ts + main.test.ts + bun.lock；共享包逻辑在仓库 packages/ 内，且被 SKILL.md 作为官方支持特性声明）；② 目录内自身行为＝本地脚本 + 本地 headless Chrome 出图 + 本地写盘（.html 与 imgs/.mermaid-cache/*.png，覆盖前备份）；③ 判橙的关键＝按 SKILL.md 执行时用户内容会出网到外部服务后端：SKILL.md 明列 PlantUML 支持，其渲染经依赖包注册的 markedPlantUML 走默认公共渲染服务 `serverUrl: options.serverUrl || `https://www.plantuml.com/plantuml`,`（图表源码外发），另 `const protocol = url.startsWith("https://") ? https : http;` 会把文档里的任意 http(s) 图片下载到本地。无凭证读取、无逆向/冒充、无 TLS 降级、Chrome 未禁用沙箱也未打反检测补丁（对比同仓 post-to-wechat/post-to-weibo 的 `--disable-blink-features=AutomationControlled`，本 skill 的 Chrome 启动参数里没有），故不升红；若文档既无 plantuml 块也无远程图片，则行为退化为纯本地（蓝级）。

5第二遍独立确认

[ok] 共享包依赖与版本锁定 — scripts/package.json 仅声明 baoyu-md ^0.1.1 与 baoyu-chrome-cdp ^0.1.1，bun.lock 有锁定条目；两包在本仓 packages/ 内有源码（psync 可读），非黑盒。
[ok] Mermaid 本地渲染且无 CDN — packages/baoyu-chrome-cdp/src/mermaid.ts 从包内 assets 读 mermaid.min.js（`if (fs.existsSync(path.join(candidate, "mermaid.min.js"))) return candidate;`）并注入本地页面，无外部脚本地址。
[ok] PlantUML 默认出网到公共服务器（判橙依据） — packages/baoyu-md/src/extensions/plantuml.ts 默认 serverUrl=https://www.plantuml.com/plantuml；注册于 renderer.ts 的 markedPlantUML()；本 skill 的 document.ts 路径调用 initRenderer，SKILL.md 亦将 PlantUML 列为支持特性。
[ok] 远程图片会被真实下载 — packages/baoyu-md/src/images.ts 的 downloadFile 使用 node:http/https + Mozilla/5.0 UA 下载并跟随 301/302；本 skill 在 hasRemoteImages 时建临时目录承接，HTML 内保留原 URL 并附 data-local-path。
[ok] 本 skill 的 Chrome 启动参数无安全降级/反检测项 — packages/baoyu-chrome-cdp/src/index.ts 的 launchChromeBase args 仅为 --remote-debugging-port/--user-data-dir/--no-first-run/--no-default-browser-check（+headless）；全包 grep bypass/detect/webdriver/stealth 零命中，无 --no-sandbox。
[ok] 无凭证读取 — 本目录 token 扫描 process.env/API_KEY/TOKEN/SECRET/.env 零命中；仅 EXTEND.md 偏好文件（路径在 SKILL.md 明列）。
[ok] mermaid securityLevel: loose 的渲染面 — packages/baoyu-chrome-cdp/src/mermaid.ts 以 `mermaid.initialize({ startOnLoad: false, theme: …, securityLevel: "loose" })` 渲染文档中的图表代码，属本地无头浏览器内执行用户文档内容；已在 injection_surface 与 verdict.risks 标注。
[ok] 『微信友好』定位与实际产物 — CSS 由 juice 内联（baoyu-md 依赖含 juice ^11.0.1），图片输出 localPath 供下游上传；--cite 默认关闭，与 SKILL.md 'Default: Off. Do not ask by default.' 一致。

6结论

面向公众号的实用主义：CSS 内联 + 图片本地路径回报 + 外链转底部引用，直接解决微信编辑器粘贴掉样式、外链不可点的问题。

Mermaid 走本地 headless Chrome 并做内容哈希缓存，无云渲染依赖，重复转换不重复出图。

降级路径完备：没有 Chrome 或渲染失败时回退 `<pre class="mermaid">`，转换整体不失败。

覆盖的 Markdown 方言广（GFM/高亮/alert/脚注/ruby/数学/PlantUML），且有 4 主题 + 13 预设色 + 字体字号选项。

输出可被程序消费：JSON（htmlPath/backupPath/contentImages/mermaidImages）让后续 skill（如 post-to-wechat）能直接接手。

适合：适合把写好的 Markdown 文章转成可直接粘贴进微信公众号编辑器的样式化 HTML，或作为 post-to-wechat 的渲染前端；也适合需要本地渲染 Mermaid/公式并保留本地图片路径的离线写作流。

不适合：不适合处理含内部架构图（PlantUML）或来源不明图片链接的敏感文档（默认会外发/外取）；不适合要求像素级可控的网页排版（输出的是公众号友好的内联样式 HTML，而非站点主题）；也不适合无 Chrome 且依赖 Mermaid 出图的场景（会静默退化为代码块）。

安装 agent 直装可复制

① 本站镜像更新 2026-09-15

方式 A · 人下载镜像包下载 baoyu-markdown-to-html.tar.gz

sha256: 548cfdf151b66892…

方式 B · JSON 格式安装指南，复制给 agent

安装指南

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② 上游 GitHub · 原始来源

能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗

本页镜像锁定 commit 1567581c26；上游为实时仓库。

来源信息 GitHub 原始

作者 / 仓库JimLiu / JimLiu/baoyu-skills

原始 GitHubJimLiu/baoyu-skills ↗

Stars25926

最近推送2026-09-10

本 skill commit1567581c26

本站信息

收录日期2026-09-06

分类文档与知识

侦查报告AI 侦查 · 2 遍 · 2026-09-06

本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。

baoyu-markdown-to-html

1实现原理 · 为什么它能做到

2核心能力

3外部依赖

4风险提醒 风险提醒：橙色 · 评估后使用

5第二遍独立确认

6结论

4风险提醒风险提醒：橙色 · 评估后使用