# Xiaohu Wechat Format

> xiaohu-wechat-format

- Skill: `xiaohuailabs/xiaohu-wechat-format` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add xiaohuailabs/xiaohu-wechat-format`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaohuailabs/xiaohu-wechat-format/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xiaohuailabs (https://skillmd.com/u/xiaohuailabs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiaohuailabs/xiaohu-wechat-format

---

# xiaohu-wechat-format

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

## Skill Description For Claude

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

## Instructions

### 触发条件

用户说以下任何一种：
- `/format 文件路径`
- `排版这篇文章`
- `微信排版`
- `格式化为公众号格式`
- `把这篇转成微信格式`

### 完整工作流

#### 第 1 步：确认文章

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

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

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

```bash
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 个最适合的主题：

| 内容类型 | 推荐主题 |
|----------|----------|
| 深度长文/分析 | newspaper, magazine, ink |
| 科技产品/AI工具 | bytedance, github, sspai |
| 访谈/对话体 | terracotta, coffee-house, mint-fresh |
| 教程/操作指南 | github, sspai, bytedance |
| 文艺/随笔/观点 | terracotta, sunset-amber, lavender-dream |
| 活力/动态/速报 | sports, bauhaus, chinese |

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

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

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

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

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

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

```bash
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 个，差异最大）

| 主题 | 命令值 | 风格 |
|------|--------|------|
| 赤陶 | terracotta | 暖橙色，满底圆角标题，左边框渐变 |
| 字节蓝 | bytedance | 蓝青渐变，科技现代 |
| 中国风 | chinese | 朱砂红，古典雅致 |
| 报纸 | newspaper | 纽约时报风，严肃深度 |
| GitHub | github | 开发者风，浅色代码块 |
| 少数派 | sspai | 中文科技媒体红 |
| 包豪斯 | bauhaus | 红蓝黄三原色，先锋几何 |
| 墨韵 | ink | 纯黑水墨，极简留白 |
| 暗夜 | midnight | 深色底+霓虹色，赛博朋克 |

#### 精选风格（7 个）

| 主题 | 命令值 | 风格 |
|------|--------|------|
| 运动 | sports | 渐变色带，活力动感 |
| 薄荷 | mint-fresh | 薄荷绿，清爽健康 |
| 日落 | sunset-amber | 琥珀暖调，温暖感性 |
| 薰衣草 | lavender-dream | 紫色梦幻，浪漫诗意 |
| 咖啡 | coffee-house | 棕色暖调，稳重温馨 |
| 微信原生 | wechat-native | 微信绿，传统阅读 |
| 杂志 | magazine | 超大留白，品质长文 |

#### 模板系列（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 同理）即触发三层渲染：

```html
<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 转换后在公众号显示美观；不带的是公众号原生支持。

| 内容形态 | 推荐元素 | 公众号 | 不要用 |
|---------|---------|----------|-------|
| ≥3 项**并列要点**（无先后） | 无序列表 `-` | 原生 | 各项有强对比→改表格；只有 2 项→写成句子 |
| **有先后/因果/步骤** | 有序列表 `1. 2. 3.` 或动词式标题 | 原生 | 步骤 ≤2→写句子 |
| **教程操作清单** | 任务列表 `- [ ]` | ⚠️ 公众号勾选框不渲染 | 非操作类别用 |
| **场景化举例**（"假设你..."） | 引用块 `>` | 原生 | 不要每段都套 |
| **引用原话/CEO 表态** | 引用块 `>` + `> — 来源` | 原生 | 没真出处别用 |
| **多人对话/访谈** | `:::dialogue` ⚡ | 转 HTML | 独白别套 |
| **关键判断/反直觉结论** | `> [!important]` ⚡ | 转色块 | 全文 ≤2 处 |
| **小技巧/巧妙用法** | `> [!tip]` ⚡ | 转色块 | 一篇 ≤1 个 |
| **风险/已知坑/局限** | bullet list 默认；`> [!warning]` ⚡ 只留给单条高危 | 列表原生 / callout 转色块 | warning 一篇 ≤1 处 |
| **背景补充/扩展** | `> [!note]` ⚡ | 转色块 | 跟主线无关考虑直接删 |
| **2+ 选项参数对照** | 表格 | 原生（最多 4 列） | 只 2 项弱对比写句子 |
| **可复制命令/代码** | ``` 代码块 + 语言 | ⚠️ 公众号无语法高亮 | 截图代码（绝对不行） |
| **核心数据/百分比** | `==高亮==` ⚡ | 转 `<mark>` | 全文 ≤5 处 |
| **文章级大数字** | `:::stat` ⚡ | 转大字块 | 全文 ≤1 个 |
| **段落关键词** | `**加粗**` | 原生 | 不能整句加粗、每段 ≤2 处 |
| **反差句式** | `~~X~~ Y` 删除线 | 原生 | 一篇 ≤2 次 |
| **连续 ≥3 图** | `:::gallery` ⚡ | 转横滑 | ≤2 图直接 `![]()` |
| **超长流程图/架构图** | `:::longimage` ⚡ | 转固定高度纵滑 | 普通图别用 |
| **作者点睛收尾**（小互说） | `:::byline[小互说]` ⚡ | 转署名块 | 一篇 ≤1 处 |
| **章节切换** | `## 标题` 或 `---` 分隔线 | 原生 | 短文（<800 字）连续叙述别切 |

### 小标题前缀变体池

| 前缀样式 | 适合场景 | 例 |
|---------|---------|----|
| **裸标题（无前缀）** | 章节本身有完整名词，散文式叙述 | `## 这事为什么重要` |
| `①②③④⑤⑥` 圆圈数字 | 严肃技术分点；**一篇至多用一处** | `### ① 流式 LoD` |
| `1. 2. 3.` 阿拉伯 | 步骤、操作 | `1. 抓取 2. 写初稿 3. 扫描` |
| `一、二、三、` 中文序号 | 偏正式、报告感、深度解读 | `## 一、问题的根源` |
| **动词+名词式**（坑一/招一/症状一） | 病症清单、避坑指南 | `## 坑一：偷改测试` |
| **emoji 前缀**（🚨⚠️🔥💡🎯） | 警示、亮点；**不滥用** | `## 🚨 最严重的那条` |
| **疑问句标题** | 痛点引入 | `## 数字里到底藏着什么` |
| **数字式断言**（"3 个核心""6 宗罪"） | 强观点、列举式 | `## Claude Code 的六宗罪` |

**选择规则**：① 一篇文章只用 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 个主题，用的是用户的真实文章