内容创作 · freestylefly/canghe-skills

canghe-markdown-to-html

Name: canghe-markdown-to-html
Author: freestylefly/canghe-skills

Converts Markdown to styled HTML with WeChat-compatible themes. Supports code highlighting, math, PlantUML, footnotes, alerts, and infographics. Use when user asks for "markdown to html", "convert md to html", "md转html", or needs styled HTML output from markdown.

L4 高权限 · 分级授权与审计V1 已固定执行命令联网读写文件Dual-pass Audit

Author freestyleflyGitHub freestylefly/canghe-skills ↗License MIT（仓库根 LICENSE）Commit dd0bf35595

管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者，使用风险由使用者自行承担。

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

提示词编排 + 单脚本执行：SKILL.md 让 agent 把自身目录当作 SKILL_DIR，实际转换交给一个 Bun/TypeScript 脚本 scripts/main.ts。

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

**Agent Execution**: Determine this SKILL.md directory as `SKILL_DIR`, then use `${SKILL_DIR}/scripts/<name>.ts`.

这里在做什么：SKILL.md 只负责路由与工作流，真正的解析/渲染逻辑在脚本里；agent 定位路径后以 npx bun 调用。

转换命令以 npx -y bun 即时执行本地脚本，并支持 --theme / --title / --keep-title 等选项。

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

npx -y bun ${SKILL_DIR}/scripts/main.ts <markdown_file> --theme <theme>

这里在做什么：Step 2 给出的执行命令；npx -y 会即时拉取 bun 运行时而非固定版本（供应链面）。

实现栈由依赖清单暴露：marked 解析、highlight.js 高亮、juice 内联 CSS、front-matter 读元数据。

skills/canghe-markdown-to-html/scripts/md/package.json

"juice": "^11.0.1", "marked": "^15.0.6", "reading-time": "^1.5.0",

这里在做什么：juice 把 CSS 内联化是微信排版的关键；marked 负责 Markdown→HTML；highlight.js 出代码高亮。

主题靠 CSS 变量 + 主题文件实现，default 主题定义各级标题、引用、代码块、表格等排版（如二级标题白字彩底居中）。

skills/canghe-markdown-to-html/scripts/md/themes/default.css

h2 { display: table; padding: 0 0.2em; margin: 4em auto 2em; color: #fff; background: var(--md-primary-color);

这里在做什么：颜色走 var(--md-primary-color) 便于 EXTEND.md 覆盖；主题只改样式不改结构。

偏好外置三级机制：项目级 .canghe-skills/... 优先，其次 $HOME/.canghe-skills/...，支持默认主题、自定义 CSS 变量、代码块样式。

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

**EXTEND.md Supports**: Default theme | Custom CSS variables | Code block style

这里在做什么：把用户偏好写成文件由 skill 读取，agent 用 Bash 探测存在性后再决定是否应用。

输出与冲突处理：HTML 与输入同目录，若已存在先备份为 .bak-YYYYMMDDHHMMSS，并向 stdout 打印含图片占位符的 JSON 供下游替换。

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

**Conflict handling**: If HTML file already exists, it will be backed up first:

这里在做什么：脚本会本地写盘且覆盖前备份；contentImages 的 MDTOHTMLIMGPH_n 占位符机制供 post-to-wechat 等下游贴图。

中文前置处理：仅当输入含 CJK 时，若检测到 canghe-format-markdown 可用则询问是否先格式化（修复 ** 被标点破坏等）。

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

**Condition**: Only execute if input file contains Chinese text.

这里在做什么：Step 0 的跨 skill 委派，点名调用 canghe-format-markdown；属他人 skill 行为，不参与本 skill 判级。

可选 PlantUML 渲染把图表源码发往公共服务器（默认 www.plantuml.com），是唯一的执行期外发路径。

skills/canghe-markdown-to-html/scripts/md/extensions/plantuml.ts

* @default 'https://www.plantuml.com/plantuml'

这里在做什么：plantuml 扩展默认 serverUrl 指向公共渲染服务；风险扫描另在 plantuml.ts:193 定位到 fetch(svgUrl) 实际取图。

2核心能力

01Markdown → 带内联样式的 HTML 转换（面向微信公众号优化）

02代码块语法高亮（highlight.js）

03三套微信兼容主题 default / grace / simple

04数学公式（KaTeX）、PlantUML 与 Mermaid 图表支持

05GFM 警报块（alerts）与脚注、注音（ruby）等扩展语法

06输出图片占位符 JSON（MDTOHTMLIMGPH_n），供下游贴图流程替换

07同目录输出 + 覆盖前自动备份 + stdout JSON 报告

08偏好外置（EXTEND.md 主题 / CSS 变量 / 代码块样式）与中文前置格式化委派

3外部依赖

Kind	Dependency / Endpoint
cli	bun（经 npx -y 即时拉取）
api	PlantUML 公共渲染服务（图表源码外发）
package	marked（Markdown 解析）
package	juice（CSS 内联化）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: npx -y bun ${SKILL_DIR}/scripts/main.ts <markdown_file> --theme <theme>（age
网络端点: 声明外部网络访问: PlantUML 渲染：对 https://www.plantuml.com/plantuml 发 GET 取 SVG（图表源码外发），仅当文档含 p
本地工作目录: 文件读写与工件输出: 与输入同目录写 <name>.html（覆盖前备份为 .bak-YYYYMMDDHHMMSS）

审计说明： 。① 判级对象＝本 skill 目录（SKILL.md + scripts/main.ts + scripts/md/*）。② 目录内自身行为＝本地 bun 脚本 + 本地读写（写 .html、备份），无凭证读取、无逆向/冒充、无 TLS/沙箱降级。③ 判橙关键＝按 SKILL.md 执行时用户内容会出网到外部服务后端：SKILL.md 明列 PlantUML 支持，其扩展默认 serverUrl 指向公共渲染服务 https://www.plantuml.com/plantuml（图表源码外发），风险扫描并在 plantuml.ts:193 定位 fetch(svgUrl)。若文档既无 plantuml 块也无远程图片，行为退化为纯本地（蓝级）。跨 skill 调用 canghe-format-markdown 只写入 reason，不作档位依据。

5第二遍独立确认

[ok] 实现原理（SKILL.md 编排 + main.ts 执行） — SKILL.md 的 Script Directory/Workflow 段落自证 agent 只做路由，转换由 scripts/main.ts 承担；执行命令逐字可核。
[ok] PlantUML 执行期外发 — plantuml.ts 的 @default 端点与风险扫描 plantuml.ts:193 的 fetch(svgUrl) 相互印证，判橙据成立。
[ok] 三套主题存在性 — §1 清单与 §2 内文均含 themes/default.css、grace.css、simple.css，主题描述与 SKILL.md 一致。
[ok] 依赖栈 — package.json 列出 marked/highlight.js/juice/front-matter/remark-cjk-friendly 等，与实现原理相符。
[ok] 是否存在凭证读取 — 「凭证/环境变量」65 条命中均为 ${SKILL_DIR}/$HOME 路径或示例占位，未发现密钥/cookie 读取，判定为无。
[unlocatable] main.ts / render.ts 写盘细节 — bundle 只列清单未展开这两份正文，写盘/备份行为以 SKILL.md 描述与扫描行（main.ts:244、render.ts:868）为据，未代码级复核。
[ok] URL 命中性质 — 193 条 URL 命中绝大多数为注释/文档链接与 highlight.js 语言名；真实执行期网络仅 plantuml fetch，未发现被夸大的外发。
[ok] 跨 skill 调用 canghe-format-markdown — SKILL.md Step 0 明写条件式调用，属他人 skill 行为，按范式不参与本 skill 判级。