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）
• 老主题不写新字段走原单层逻辑，零破坏
• 参考实现：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 个主题，用的是用户的真实文章