xiaohuailabs xiaohu-wechat-format
公众号一键排版技能。把任意文本内容（Markdown、纯文本、格式粗糙的笔记）转成微信公众号兼容的排版 HTML，AI 自动理解内容结构并增强排版，可视化选择主题后一键复制粘贴到微信后台。
Skill Description For Claude
把文章转为微信公众号兼容的内联样式 HTML。支持 Markdown 和纯文本输入，AI 自动补充结构和排版增强。当用户说"排版""微信排版""格式化文章""format"时使用。
Instructions
触发条件
用户说以下任何一种：
/format 文件路径排版这篇文章微信排版格式化为公众号格式把这篇转成微信格式
完整工作流
第 1 步：确认文章
- 如果用户给了文件路径，直接读取
- 如果没给路径，问用户要文章路径
- 读取文章内容，确认标题和字数
第 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.标记 - 加强调：识别关键词、产品名、核心概念，加
**加粗** - 清理格式：去除多余空行、修正缩进、统一标点
- 不改措辞：不调语序、不增删内容、不润色文字。用户写什么就是什么，只加结构标记
保存与告知：
- 结构化后保存为
/tmp/wechat-format/xxx-structured.md - 告知用户："检测到输入缺少 Markdown 格式标记，已自动补充标题和结构，保存在 xxx-structured.md，可检查调整"
- 后续第 2 步基于 structured.md 继续处理
第 2 步：AI 内容分析 + 自动套格式
读取文章（或上一步输出的 structured.md），Claude 分析内容结构，在 Markdown 层面自动套用合适的排版容器。这是我们比纯手动排版工具强的核心——AI 理解内容，自动匹配最佳呈现方式。
分析维度：文章类型（访谈/教程/产品介绍/深度分析）、内容元素（对话/图片/代码/数据）、节奏感（密集段 vs 留白段）。
自动套用规则（按优先级）：
对话/访谈 →
:::dialogue[标题]- 检测到
**名字：**或名字：交替出现 → 用:::dialogue包裹 - 格式：
名字: 对话内容（中英文冒号都支持） - 不是所有对话都要套——独白段落、叙述性段落保持原样
- 同一场景的连续对话放一个 dialogue 块，换场景换一个新块
- 检测到
连续多图 →
:::gallery[标题]- 3张以上连续图片 → 自动套
:::gallery，横向滚动浏览 - 适合产品截图、对比图、系列图
- 3张以上连续图片 → 自动套
超长图片 →
:::longimage[标题]- 流程图、架构图、长截图 → 固定高度容器，纵向滚动
- 一般需要用户标注或 AI 判断图片内容
核心观点/金句 → callout 格式
- 核心观点 →
> [!important] 标题 - 小技巧/提示 →
> [!tip] 标题 - 注意事项 →
> [!warning] 标题 - 普通引用 →
> [!callout] 标题（使用主题色） - 不要过度使用，一篇文章 1-3 处即可
- 核心观点 →
分隔符 → 在章节转换处确保有
---分隔图说标记 → 图片后紧跟的说明用斜体：
*这是图片说明*外部链接 → 无需处理（脚本自动转脚注）
处理完成后，把增强后的 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）- 老主题不写新字段走原单层逻辑，零破坏
- 参考实现：data-report（编号标题）、interview（吊牌标题+居中短下划线+大引号）、glass-light（渐变圆点+玻璃药丸）
- 展示型主题（大标题是风格本体）在 JSON 根加
"lint": {"display_type": true}豁免 theme_lint 的 H1/H2 上限检查
注意事项
- 依赖 Python
markdown库（系统已安装） - 图片在预览中可见，但粘贴到微信后需要手动上传
- 如果用户对排版不满意，可以切换主题重新生成
Obsidian 排版工具箱（写作时主动使用，写作 SKILL 共享参考）
三条硬规则（高于一切）
- 形态决定形式：写之前不预设排版结构。一段一段写，写到哪段问"这段内容本质是什么形态（清单/对比/流程/故事/数据/引用/关系）"，再选最契合的元素。禁止先决定"这篇要有 N 个 bullet list、N 个 callout"再去找内容塞
- 反炫技自检：每加一个 callout/高亮/表格/特殊容器，问"去掉它读者损失什么"。答不上来 → 删
- 密度交替：连续 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 个主题，用的是用户的真实文章