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 判级。