Imported from xiaohuailabs/xiaohu-wechat-format (SKILL.md). Install upstream with npx skills add xiaohuailabs/xiaohu-wechat-format. Copyright stays with the author.

xiaohu-wechat-format

公众号一键排版技能。把任意文本内容（Markdown、纯文本、格式粗糙的笔记）转成微信公众号兼容的排版 HTML，AI 自动理解内容结构并增强排版，可视化选择主题后一键复制粘贴到微信后台。

Skill Description For Claude

把文章转为微信公众号兼容的内联样式 HTML。支持 Markdown 和纯文本输入，AI 自动补充结构和排版增强。当用户说"排版""微信排版""格式化文章""format"时使用。

Instructions

触发条件

用户说以下任何一种：

• /format 文件路径
• 排版这篇文章
• 微信排版
• 格式化为公众号格式
• 把这篇转成微信格式

完整工作流

第 1 步：确认文章

1. 如果用户给了文件路径，直接读取
2. 如果没给路径，问用户要文章路径
3. 读取文章内容，确认标题和字数

第 1.2 步：标点质检（必跑，阻断式）

读取文章后、进入排版前,必须跑一次中文正文半角标点修复:

python3 ~/.claude/skills/xiaohu-wechat-format/scripts/zh_punctuation_fix.py "文章路径.md" --write

脚本自动把中文字符旁的半角 , : ; ? ! . ( ) 换成全角 ,:;?!。(),保护代码块/行内 code/URL/Markdown 链接段不误伤。

输出会打印「违规: N → 0」。N > 0 = 原文有违规,已写回修复后内容。N = 0 = 已干净,零改动。

此步不能跳过——半角英文标点挤在中文字之间是典型 AI 味,读者第一眼就看出代码注释感。2026-04-19 根治:Claude Design 解读稿里 233 个半角逗号/84 冒号/70 括号混在中文正文,用户当场识破。

第 1.5 步：结构化预处理（仅在需要时）

读取文章后，先检测输入内容的 Markdown 结构完整度，决定是否需要 AI 结构化预处理。

检测方法：扫描全文，统计 ## 标题、**加粗**、- 列表、> 引用、` 代码 ` 等格式标记的数量。

判断规则：

• 有 ## 标题且格式标记分布合理 → 跳过，直接进入第 2 步
• 缺少 ## 标题，或几乎没有格式标记（纯文本/粗糙笔记）→ 执行结构化

结构化规则（底线：只加标记，不改内容）：

1. 加标题：识别文章的逻辑段落和主题转换点，在转换处插入 ## 标题。标题从内容中提炼，不编造。三段内容不硬拆五个标题——尊重原文信息密度
2. 分段落：确保段落之间有空行分隔，长段落在语义转换处拆分
3. 加列表：识别并列/枚举性质的内容，加 - 或 1. 标记
4. 加强调：识别关键词、产品名、核心概念，加 **加粗**
5. 清理格式：去除多余空行、修正缩进、统一标点
6. 不改措辞：不调语序、不增删内容、不润色文字。用户写什么就是什么，只加结构标记

保存与告知：

• 结构化后保存为 /tmp/wechat-format/xxx-structured.md
• 告知用户："检测到输入缺少 Markdown 格式标记，已自动补充标题和结构，保存在 xxx-structured.md，可检查调整"
• 后续第 2 步基于 structured.md 继续处理

第 2 步：AI 内容分析 + 自动套格式

读取文章（或上一步输出的 structured.md），Claude 分析内容结构，在 Markdown 层面自动套用合适的排版容器。这是我们比纯手动排版工具强的核心——AI 理解内容，自动匹配最佳呈现方式。

分析维度：文章类型（访谈/教程/产品介绍/深度分析）、内容元素（对话/图片/代码/数据）、节奏感（密集段 vs 留白段）。

自动套用规则（按优先级）：

1. 对话/访谈 → :::dialogue[标题]

   • 检测到 **名字：** 或 名字： 交替出现 → 用 :::dialogue 包裹
   • 格式：名字: 对话内容（中英文冒号都支持）
   • 不是所有对话都要套——独白段落、叙述性段落保持原样
   • 同一场景的连续对话放一个 dialogue 块，换场景换一个新块

2. 连续多图 → :::gallery[标题]

   • 3张以上连续图片 → 自动套 :::gallery，横向滚动浏览
   • 适合产品截图、对比图、系列图

3. 超长图片 → :::longimage[标题]

   • 流程图、架构图、长截图 → 固定高度容器，纵向滚动
   • 一般需要用户标注或 AI 判断图片内容

4. 核心观点/金句 → callout 格式

   • 核心观点 → > [!important] 标题
   • 小技巧/提示 → > [!tip] 标题
   • 注意事项 → > [!warning] 标题
   • 普通引用 → > [!callout] 标题（使用主题色）
   • 不要过度使用，一篇文章 1-3 处即可

5. 分隔符 → 在章节转换处确保有 --- 分隔

6. 图说标记 → 图片后紧跟的说明用斜体：*这是图片说明*

7. 外部链接 → 无需处理（脚本自动转脚注）

处理完成后，把增强后的 Markdown 保存为临时文件（/tmp/wechat-format/xxx-enhanced.md）。

第 2.5 步：推荐主题

根据内容分析结果，推荐 3 个最适合的主题：

推荐的主题 ID 通过 --recommend 参数传给脚本，在 gallery 中高亮显示。

第 3 步：打开主题画廊（默认流程）

python3 ~/.claude/skills/xiaohu-wechat-format/scripts/format.py \
  --input "文章路径.md" \
  --gallery \
  --recommend newspaper magazine ink

这会用用户的真实文章渲染 34 个主题，在浏览器打开画廊页面。用户点按钮切换主题预览，选中后点「用这个风格排版」一键复制到剪贴板。

第 3 步（备选）：直接指定主题排版

如果用户已经知道想用哪个主题，可以跳过画廊直接排版：

python3 ~/.claude/skills/xiaohu-wechat-format/scripts/format.py \
  --input "文章路径.md" \
  --theme terracotta

第 4 步：确认结果

告诉用户：

• Gallery 模式：在浏览器中切换主题预览，选中后点按钮复制，粘贴到公众号后台
• 直接模式：在浏览器中检查预览，点「复制到微信」按钮

参数说明

• --input / -i：Markdown 文件路径（必须）
• --gallery：打开主题画廊（推荐，默认使用）
• --theme / -t：直接指定主题名（跳过画廊）
• --output / -o：输出目录（默认 /tmp/wechat-format）
• --recommend：推荐的主题 ID 列表，gallery 中高亮显示（如 --recommend newspaper magazine ink）
• --no-open：不自动打开浏览器

可用主题（30 个）

独立风格（9 个，差异最大）

精选风格（7 个）

模板系列（14 个，布局×配色）

四种布局（简约/聚焦/精致/醒目）× 多种配色（金/蓝/红/绿/藏青/灰）

微信兼容说明

脚本自动处理以下微信限制：

• 纯内联样式：所有 CSS 直接写在每个标签的 style="..." 属性上
• 列表模拟：<ul>/<ol> 改为 <section> + flexbox 模拟
• 引用块转 section：输出端 <blockquote> 统一换成 <section>（2024-11 起微信新版编辑器会重写 blockquote 剥掉样式，doocs/md #447）
• margin 简写：margin-top/bottom 分拆写法自动合并（分拆写法有被编辑器丢弃的报告）
• 外链转脚注：[text](url) 自动变成正文 text[1] + 文末脚注列表
• 图片处理：![[image.jpg]] 自动搜索 Vault 并复制到输出目录
• SVG 自动转 PNG：公众号素材库不收 SVG，本地 .svg 图自动经 qlmanage 转 PNG；外链 SVG 打警告
• 视频自动识别：独占一行的 YouTube/B站/视频号/.mp4 链接自动转"视频卡片"（▶ 徽章+标题+脚注链接）。公众号不支持外链视频，需播放器请在后台手动插视频号/腾讯视频
• 多类型提示框：[!tip]/[!note]/[!important]/[!warning]/[!caution] 各有独立配色
• 图说识别：图片后紧跟的斜体段落自动变为居中灰色图说
• 对话气泡：:::dialogue[标题] → 左右交替聊天气泡，右侧用主题色
• 图片画廊：:::gallery[标题] → 横向滚动多图容器
• 长图展示：:::longimage[标题] → 固定高度纵向滚动容器（内部可上下滑动看全长图）

金句卡片与头尾槽位（2026-06-12 新增）

• 金句卡片：>> 文字 → 白底阴影卡；>>> 文字 → 居中金句卡（主题色顶线）。主题可用 styles.quote_card / quote_card_center / quote_card_p 覆盖
• :::intro 导读块：文首彩底导读（科技号报道头式），:::intro[自定义标签] 改标签文字
• :::end[可选CTA文案]：— END — 结束符 + 可选"点赞在看"引导文案
• :::history[往期回顾]：文末往期文章卡，内容写 - [标题](链接) 列表，链接自动转脚注
• :::video[标题]：手动视频卡片，内容第一行 URL、第二行可选说明

主题三层标题结构（2026-06-12 新增，治"换色游戏"的根）

主题 JSON 里声明 h2_inner / h2_prefix / h2_suffix（h1-h6 同理）即触发三层渲染：

<h2 style="外层只管布局"><span style="prefix">01</span><span style="inner">标题文字</span></h2>

• 视觉挂在 inner 上（inline-block 自动收缩 → 色块宽度=文字宽度）
• prefix/suffix 是伪元素的实体替身：编号、楔子、装饰符号；文本配在根级 decor.h2.prefix_text，{n} 自动替换为 01、02 递增序号
• blockquote_prefix 同理（引用块大引号 ❝，文本在 decor.blockquote.prefix_text）
• 老主题不写新字段走原单层逻辑，零破坏
• 参考实现：data-report（编号标题）、interview（吊牌标题+居中短下划线+大引号）、glass-light（渐变圆点+玻璃药丸）
• 展示型主题（大标题是风格本体）在 JSON 根加 "lint": {"display_type": true} 豁免 theme_lint 的 H1/H2 上限检查

注意事项

• 依赖 Python markdown 库（系统已安装）
• 图片在预览中可见，但粘贴到微信后需要手动上传
• 如果用户对排版不满意，可以切换主题重新生成

Obsidian 排版工具箱（写作时主动使用，写作 SKILL 共享参考）

三条硬规则（高于一切）

1. 形态决定形式：写之前不预设排版结构。一段一段写，写到哪段问"这段内容本质是什么形态（清单/对比/流程/故事/数据/引用/关系）"，再选最契合的元素。禁止先决定"这篇要有 N 个 bullet list、N 个 callout"再去找内容塞
2. 反炫技自检：每加一个 callout/高亮/表格/特殊容器，问"去掉它读者损失什么"。答不上来 → 删
3. 密度交替：连续 3 段不许同结构。长段后接短段，列表后接散文，密集元素后留呼吸位

⚠️ :::xxx 容器特殊规则：:::byline / :::stat / :::gallery / :::longimage / :::dialogue 仅 xiaohu-wechat-format 排版转换时识别。Obsidian 原生预览 / 本地 preview.py / 其他 Markdown 阅读器不渲染，会裸字显示 :::byline[小互说] / :::。只在公众号最终稿用，且必须经 format.py 转换后再发布。能用 H2 / callout / blockquote 替代的尽量替代。

内容形态 → 元素选择决策表

带 ⚡ 的元素经 xiaohu-wechat-format 转换后在公众号显示美观；不带的是公众号原生支持。

小标题前缀变体池

选择规则：① 一篇文章只用 1-2 种前缀样式，绝对禁止全篇 6 个章节都用 ①②③④⑤⑥；② 严肃技术 → 圆圈/中文序号；吐槽/避坑 → 动词式或 emoji；对比陈述 → 裸标题；③ 同一篇上下章节交替

反炫技自检（写完通读）

• callout 总数 > 4 → 砍
• 高亮 > 5 处 → 砍
• 表格能改成 2-3 句话讲完？能 → 改
• emoji 标题 > 3 → 砍
• 6 个连续章节都用 ①②③④⑤⑥ → 必须改
• 跟上一篇文章对比：开头方式/章节切法/收尾方式雷同？有 → 换

元素使用边界

• callout 是重武器：tip / important / warning / note 全文 ≤ 4 个
• 高亮 ≤ 5 处：满屏黄色就是没重点
• 加粗 ≤ 每段 2 处：是"扫读视觉锚点"，不是"我觉得这很重要"
• 任务列表只用于操作清单
• 引用块不要嵌套引用块
• 表格不超过 4 列（移动端撑爆）
• 代码块必须带语言标签

反模式

• ❌ 整段加粗代替结构 → 拆成无序列表
• ❌ callout 套娃 → 5 个 important 等于没有
• ❌ 罗列式短句 → 3 个 4 字 bullet 直接写段落更好
• ❌ 表格只有 2 行 → 信息密度低，写两段更省地方
• ❌ 截图代码 → 所有命令和代码用代码块

不能用的：Mermaid 图表（微信不支持 JS）

Obsidian 进阶语法（知识库档案/长文收纳）

完整 callout 13 种：note / info / abstract / tip / success / question / warning / failure / danger / bug / example / quote / todo

折叠 callout：> [!faq]- 默认收起，> [!example]+ 默认展开。

wikilink 完整：[[Note]] / [[Note|显示文字]] / [[Note#标题]] / [[Note#^block-id]] / [[#标题]]

图片尺寸：![[image.png|640]] 或 ![[image.png|640x480]]

完整 Obsidian 语法字典：知识库/写作参考/obsidian-语法字典.md

克制原则：上面这些规则是"什么时候该用"，不是"什么时候必须用"。每篇文章用 3-5 类元素就够丰富了。

• 画廊模式渲染 34 个主题，用的是用户的真实文章