/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 步：标点质检（必跑，阻断式）

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

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 步：打开主题画廊（默认流程）

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

| 主题 | 命令值 | 风格 | |------|--------|------| | 赤陶 | 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 同理）即触发三层渲染：

<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`