wechat-automator

name	wechat-automator
description	一站式内容资产化引擎：默认对内容进行深度优化（契合公众号阅读场景），精排版渲染，一键上传草稿箱。当用户提到"推文"、"公众号"、"排版"、"发布"、"草稿"、或任何将内容转化为公众号图文的意图时，必须调用此技能。
version	2.0.0
author	嗯哌AI (NpieAI)

微信公众号内容资产化引擎 (WeChat Automator)

一句话定义

把短期流量（视频/笔记/碎片资料），转化为长期内容复利（可搜索、可收藏、可反复阅读的图文资产）。

---

触发条件 (Trigger Rules)

以下任一条件满足时，必须激活此技能：

1. 关键词触发：用户消息包含以下任一关键词组合：
   • 「推文」「公众号」「排版」「发布」「草稿」「群发」「图文」
   • 「wechat」「weixin」「mp.weixin」
   • 「视频脚本」+「转/整理/发/变成」→公众号意涵
   • 「笔记」+「排版/发布/推文」
2. 文件引用触发：用户引用了 .md / .writings.md / .txt 文件，并提到「发」「传」「推送」「转成图文」等动作词。
3. 路径指令触发：
   • wechat-automator:full(file_path) — 完整链路：输入→草稿箱
   • wechat-automator:format(file_path) — 仅排版预览，不上传
   • wechat-automator:upload_cover(path) — 仅上传封面图
4. 上下文推断触发：刚完成 oral-stylizer 处理，用户自然过渡到排版发布。

🔴 强制规则：一旦触发，必须用 Skill 工具加载本 skill，并严格按照 skill 内定义的五阶段流水线执行。严禁绕过 skill 自行编写脚本、手写 HTML、或直接用 requests 调 API。

反触发：纯技术咨询（「公众号 API 怎么调」）不激活，用通用知识回答。

---

默认行为与内容优化豁免

核心原则：默认深度优化，显式声明豁免

默认行为：对用户提供的任何内容，自动执行阶段 ①②（内容脱水 + 结构重组），使内容契合微信公众号读者的阅读习惯——包括但不限于：重构开头钩子、调整段落节奏、优化小标题、强化结尾 CTA。

豁免规则：仅当用户消息中明确包含以下任一关键词组合时，才跳过阶段 ①② 的内容修改，严格保留原文：

豁免关键词	示例
「不要修改内容」「不做任何修改」「不要改动」	「排版发公众号，不要改动原文任何一个字」
「严格按原文」「原封不动」「一字不改」	「严格按原文排版，发布到草稿箱」
「不增不减」「保留原文」「直接排版」	「不增不减，直接排版」
「仅排版」「只排版」「纯排版」	「仅排版，不需优化内容」

注意：豁免的是阶段 ①② 的内容改写，阶段 ③④ 的视觉增强和排版渲染始终执行。即使用户要求「不修改内容」，仍然要执行：卡片化、金句模块提取、数据可视化、配色排版。

判断流程

用户请求 → 引用的文件是 .html？
  ├─ 是 → 兼容性扫描：有 <style>？有 <div>？有 class？
  │        ├─ 全部干净 → 直达 ⑤ 上传（跳过 ①②③④）
  │        └─ 有问题   → 告知用户问题数量，询问是否自动修复后再上传
  └─ 否 → 检查是否包含豁免关键词？
           ├─ 是 → 跳过 ①②，进入 ③ 视觉增强 → ④ 排版渲染 → ⑤ 上传
           └─ 否 → 执行阶段 ①② → 🔴 暂停，输出预览给用户确认
                     ├─ 用户确认 → 继续 ③ 视觉增强 → ④ 排版渲染 → ⑤ 上传
                     └─ 用户要求修改 → 修改后再次预览，直到确认

🔴 阶段 ①② 确认门禁（强制）：执行完内容脱水 + 结构重组后，必须暂停，将优化后的 Markdown 内容输出给用户预览，等待用户明确确认（「确认」「可以」「继续」等）后，才能继续执行阶段 ③④⑤。禁止跳过此门禁直接完成全流程。

HTML 兼容性扫描标准（干净 HTML 的定义）：

• 无 <style> 标签
• 无 class 属性
• 无 <div> 元素
• 无可检测的 linear-gradient

四条全部满足 → 直达 ⑤。任一不满足 → 告知用户「这个 HTML 有 X 个 div / Y 个 style 标签，微信会丢格式，要我先修复吗？」

---

工作流总览（v2.0）

三阶段管线：
┌──────────┐    ┌──────────────────────────────────────┐    ┌──────────┐
│ ⓪ 内容优化 │ → │ ① 排版渲染                                 │ → │ ② 一键发布 │
│ 脱水+去AI │    │ 预处理→类型判定→推荐+预览→结构+渲染          │    │ 草稿箱    │
│ 🔴暂停确认 │    │ 🔴暂停确认类型  🔴暂停选择排版             │    │ 自动完成  │
└──────────┘    └──────────────────────────────────────┘    └──────────┘

详细流程：
  输入内容
    ↓
  ⓪.1 内容脱水（去冗余/提论点/压密度）
  ⓪.2 结构重组（钩子开头+正文骨架+CTA结尾）
  ⓪.3 去AI味（humanizer-zh 审阅）
    ↓
  🔴 暂停 → 输出优化后内容 → 等待用户确认
    ↓
  ①.0 智能预处理（章节编号+英文标签+关键词识别+目录提取+引言高亮+署名+签名占位）
    ↓
  ①.1 🔴 文章类型判定 → 列出 7 种类型 → 暂停，等用户确认（可覆盖）
    ↓
  ①.2 🔴 排版推荐 + 12 套预览 → 暂停，等用户选择排版方案
    ↓
  ①.3 生成 class-based HTML（融入预处理 + 选定布局专属结构 + v2.0 组件配方）
  ①.4 build_inline.py --theme <选定> → inline HTML + <span leaf=""> 包裹 + validate 校验
    ↓
  ② upload.py → 上传头图+封面 → 创建草稿
    ↓
  ✅ 草稿 media_id → 用户去后台预览群发

确认门禁（三处强制暂停）

#	位置	等什么	用户可回复
🔴 1	阶段⓪ 结束	确认优化后的内容	「确认」/ 修改意见
🔴 2	阶段①.1 结束	确认文章类型（AI 判定 + 列出全部 7 种供选）	「确认」/ 类型名 / 序号
🔴 3	阶段①.2 结束	选择排版方案（12 套预览对比）	预设名 / 自由组合 / 自定义色 / 「用推荐的」

⚠️ ①.1 和 ①.2 不可合并。 必须先确认类型，再基于类型推荐排版。跳过类型确认直接推荐 = 跳步。

豁免规则

• 用户说「不要修改内容」「一字不改」「仅排版」→ 跳过 ⓪，直接进入 ①
• 用户引用的文件是干净 HTML → 跳过 ⓪①，直达 ②

---

排版设计哲学（v1.8.0）

本节是阶段① 所有排版决策的理论基础。

三层视觉层级体系

公众号文章是扫描式阅读——读者不会逐字读，而是用眼睛扫。好的排版为读者建立一条视觉动线：先看什么、再看什么、略过什么。

层级	作用	频率	手段（按所选主题色自适应）
锚点层 🔴	最强锚点：产品名/步骤/CTA/核心金句，读者扫到的第一眼	全文 ≤ 5 处	.anchor-bold 主色加粗、.anchor-block 深色底白字、.golden-quote 金句模块
标记层 🟡	正文关键词下划线，让读者快速抓取每段重点	每段 1-3 处，高频	.kw-underline 主题色底划线（默认标记手段）、.highlight-marker 荧光笔（偶尔长句）
容器层 ⚪	引用块、概念标签、提示框、卡片——结构化信息块	按需，点缀 ≤3 种/篇	blockquote 引用、.highlight-box 强调块、.tip-box/.warn-box 提示框、.card-item 卡片

克制原则

1. 锚点不滥用：到处加粗等于没有重点。红/蓝/绿加粗只在全文 ≤5 处最关键的位置
2. 标记不遗漏：每段正文必须主动标记 1-3 个关键词（4-15 字短语），即使原文没有任何加粗也要主动加下划线——这是本 skill 的核心特色，也是最高频的标记手段
3. 容器不混搭：一篇只用所选布局的组件，不跨布局借组件；点缀组件种类 ≤3
4. 下划线是主角：.kw-underline 是全文出现最多的样式，比加粗更轻、比无色更突出，是扫描阅读的最佳标记
5. 颜色克制：主色用于锚点层和标记层的关键位置，正文大面积保持中性灰；对比色/警告色只在需要读者停顿的地方出现

智能主动标记（AI 做的事，不等用户写标记）

不等用户在 Markdown 里写好 **加粗** 和 ==高亮==，AI 主动分析内容，替读者标记重点。 阶段① 执行时，AI 必须完成以下 7 项智能处理：

1. 章节自动编号：按 ## 出现顺序分配 01/02/03…，末章若为结语/总结类用 ∞
2. 英文标签生成：据中文章节标题生成英文标签（教程→TUTORIAL、总结→SUMMARY、思考→THOUGHTS…）
3. 正文关键词下划线：对每个正文段落主动找出 1-3 个最重要的短语标记 .kw-underline
4. 引言金句高亮：识别开头引言中的核心词，用 .intro-highlight 或 .anchor-block 标记
5. 目录/看点提取：从所有 ## 取前 3 个作为导读要点
6. 引言卡署名：按文章作者/主题确定，未知则省略不写
7. 尾部签名区占位：默认 {{作者名}} / {{简介}}，用户提供则填入

文章类型 → 组件配方

先判定文章类型，再按类型选择排版系统。同类文章用同一套组件组合，保证排版气质稳定。

文章类型	判据	推荐排版系统	核心组件	点缀组件
教程/操作指南	步骤、命令、配置词多	forest 手册流 / amber 极客流	.step-block + 代码块 + .ordered-list	.tip-box / .warn-box
盘点/工具清单	并列条目、推荐、工具词多	plum 卡片流 / teal 经典左线	.card-item + .tool-badge + 胶囊列表	表格 / 数据卡
观点/深度分析	分析、逻辑、判断词多	navy 杂志流 / teal 经典左线	正文段 + .golden-quote + .highlight-box	.kw-underline 高频 / 居中金句
访谈/人物特稿	采访、引语、人物叙事多	navy 杂志流 / slate 书信流	正文段 + blockquote 引语 + timeline	.golden-quote / 居中金句
数据复盘/报告	数字、统计、对比词多	navy 杂志流 / teal 经典左线	数据卡 + 表格 + .ordered-list	.anchor-bold 关键数字
生活/情感随笔	我、感觉、日常词多	slate 书信流 / plum 卡片流	正文段 + 居中金句 + 轻量引用	.kw-underline 少量
案例实战	案例、项目、踩坑词多	amber 极客流 / forest 手册流	case-label + .step-block	.warn-box / .prompt-card

---

阶段 ⓪：内容优化（Content Optimization）

目标：输入内容 → 深度优化 → 去 AI 味 → 用户确认。

⓪.1 内容脱水

1. 去冗余：删除重复论述、口语填充句
2. 提论点：每段提炼 1 句可独立传播的核心观点
3. 压密度：信息密度提升 30-50%
4. 保人味：保留作者标志性表达（Banny 的「Vibe Coding」「Agentic Workflow」等）

⓪.2 结构重组

• 钩子开头：提取最反直觉的 1 句话前置，或用 2-3 句制造信息落差
• 正文架构：根据内容类型选择骨架（教程→问题原理步骤/观点→现象分析本质/案例→背景决策方法论/清单→总览逐条展开）
• H2 控制：3-5 个板块，标题要具体（「问题是什么」而非「关于 XX 的讨论」）
• CTA 结尾：给读者一个具体的下一步

⓪.3 去 AI 味

调用 humanizer-zh 审阅优化后的全文，去除 AI 写作特征（夸大的象征意义、宣传性语言、三段式法则、AI 词汇等）。

⓪.4 确认输出

🔴 必须暂停。将优化后的 Markdown 内容输出给用户预览，等待明确确认后才能继续。

---

阶段 ①：排版渲染（Layout & Rendering）v2.0

目标：智能预处理 → 🔴 文章类型判定确认 → 🔴 排版推荐+预览+选择 → 生成 HTML → 渲染。

①.0 智能预处理（AI 强制执行）
  ↓
①.1 文章类型判定 → 🔴 暂停：用户确认类型（可覆盖）
  ↓
①.2 排版系统推荐 + 生成预览网页 → 🔴 暂停：用户选择排版方案
  ↓
①.3 生成 class-based HTML（融入预处理 + 选定布局的专属结构 + 组件配方）
  ↓
①.4 build_inline.py 渲染 → validate 校验

⚠️ 关键顺序铁律：必须先确认文章类型，再推荐排版系统。类型决定推荐方向，跳过类型确认直接推荐 = 跳步，禁止。

①.0 智能预处理（v1.8.0 🔴 AI 强制执行）

在生成任何 HTML 之前，AI 必须对优化后的 Markdown 执行以下 7 项智能处理。核心理念：不等用户写标记，AI 主动替读者做信息导航。

①.0.1 章节自动编号

按 ## 出现顺序分配：01 02 03 …。末章若标题含「总结/结语/写在最后/尾声」等词，编号用 ∞，PART 改为 LAST。

• 编号不与原文标题冲突，作为章节视觉锚点
• 中间章节不跳号、不用 ∞

①.0.2 英文标签生成

为每个 ## 章节生成英文副标签（.chapter-en 类），用于章节标题区的装饰：

中文关键词	英文标签	中文关键词	英文标签
教程/步骤/操作/实战/指南	TUTORIAL	盘点/清单/工具/推荐	TOOLS
分析/观点/评论/深度/解读	ANALYSIS	案例/复盘/项目/经验	CASE STUDY
总结/结语/写在最后/尾声	EPILOGUE	思考/反思/感悟	THOUGHTS
问题/挑战/困境/难点	PROBLEM	方法/方案/策略/框架	METHOD
背景/现状/趋势/格局	CONTEXT	数据/指标/统计	DATA
原理/机制/本质/底层	PRINCIPLE	展望/未来/预测	OUTLOOK

无明确对应时，取章节核心名词的英文翻译（≤12 字符）。

①.0.3 正文关键词下划线 🔴 核心特色

对每个正文段落（<p> 元素），AI 主动识别 1-3 个最重要的短语（4-15 字），用 .kw-underline 类标记。

• 优先标：核心观点、结论判断、关键数据、专有名词、产品名
• 不标：过渡句、废话、整段内容
• 整段无要点时可跳过
• 即使原文没有任何 **加粗** 标记，也要主动加下划线——这是本 skill 出现频率最高的标记

①.0.4 引言金句高亮

识别文章开头引言（> 引用 块或首段金句）中的核心关键词，用 .intro-highlight（主色底白字）或 .anchor-bold（主色加粗）标记。引言卡中最多 2 处高亮。

①.0.5 目录/看点提取

从所有 ## 章节标题中精选 前 3 个作为导读看点（非完整章节目录），生成 .toc-card 容器。章节多于 3 个时挑最重要的 3 个，不要硬塞。

①.0.6 引言卡署名

按文章实际作者或主题确定引言卡署名：

• 文章有明确作者 → 写「—— 作者名」
• 无明确作者但主题明确 → 可用与主题相关的简短落款
• 完全未知 → 省略署名行，不留空

不要固定写任何默认人名。

①.0.7 尾部签名区占位

在文末 CTA 之前生成签名段落，默认用占位符，让用户替换成自己的署名：

• 用户在请求/偏好里给了署名或简介 → 直接填入
• 没给 → 保留 {{作者名}} / {{一句话简介}} 占位，交付时提示用户替换
• 原文末尾已有作者签名段 → 直接沿用原文，不替换成占位
• 签名区有且仅有末尾一处

---

①.1 🔴 第一步：文章类型判定（先确认类型，不推荐排版）

⚠️ 这一步只做类型判定，不推荐排版系统。排版推荐在 ①.2 用户确认类型之后。

1. 阅读优化后的文章，理解内容类型、情感基调、目标读者
2. 调用 detect_content_type() 判定文章类型
3. 列出全部 7 种类型供用户选择，标注 AI 判定的推荐项：

📝 AI 判定文章类型：**{类型名}**（置信度：{高/中/低}）

你也可以选择其他类型（不同类型的推荐结果不同）：

| 序号 | 文章类型 | 适合场景 |
|------|---------|---------|
| 1 | 生活/情感随笔 ⭐ 推荐 | 读书感悟、个人叙事、情感表达 |
| 2 | 观点/深度分析 | 论证推演、逻辑分析、评论 |
| 3 | 访谈/人物特稿 | 引语多、人物叙事多 |
| 4 | 案例实战 | 项目复盘、踩坑经验 |
| 5 | 盘点/工具清单 | 并列条目、推荐合集 |
| 6 | 教程/操作指南 | 步骤、命令、操作流程 |
| 7 | 数据复盘/报告 | 数字统计、对比分析 |

🔴 必须暂停等待用户确认。用户可回复：

• 「确认」/「用推荐的」→ 使用 AI 判定类型
• 序号或类型名 → 更换为用户指定的类型
• 自定义描述 → 按用户描述调整

用户确认类型后，才进入 ①.2。

---

①.2 🔴 第二步：排版系统推荐 + 预览对比

⚠️ 用户确认文章类型后执行。 AI 先生成一个临时 class-based HTML（用于文本提取，任意布局即可），然后运行 preview_themes.py。

1. 调用 recommend() 做关键词匹配 + 文章类型加权，得出 12 套预设的分数排名
2. 向用户说明推荐结果：

📊 排版系统推荐（基于类型：{类型名}）：

| 排名 | 预设 | 布局 × 配色 | 得分 | 来源 |
|------|------|------------|------|------|
| ⭐ 1 | slate 岩灰书信 | 书信流 × 岩灰玫瑰 | 20 分 | 原有 |
| 2 | ruby 红白编辑 | 红白编辑 × 红白配色 | 7 分 | v2.0 新增 |
| ...

3. 生成临时 class HTML → 运行 preview_themes.py 生成预览页：

python3 scripts/preview_themes.py output/article-class-html.html --open

v2.0 预览页特性：

• 12 套布局 × 各自专属 HTML 结构样本（不是同一段 HTML 换皮肤）
• 四栏 grid 布局，响应式（>1200px 四栏 → >900px 三栏 → >560px 两栏 → 手机一栏）
• 每张卡片标注：📐 布局名 + 🎨 配色名 + 🏷️ 适用文章类型
• 推荐项 ⭐ 金色边框高亮
• 每张卡片展示该布局的专属组件（封面卡/流程卡/时间线/END 分割线/引言卡等）

🔴 必须暂停等待用户选择。用户可回复：

• 预设名：slate ruby zen moyu olive ticket graph teal navy forest plum amber
• 自由组合：zen:slate-rose moyu:emerald（布局:配色）
• 自定义颜色：#e63946（默认 classic 布局，自动推导配色）
• 「用推荐的」→ 分数最高项

---

①.3 生成 class-based HTML（融入智能预处理 + 选定布局专属结构）

在运行 build_inline.py 之前，AI 用选定布局的专属结构生成 class-based HTML。必须满足：

1. 结构骨架：使用选定布局的专属 HTML 模板（参见 4.3 章节「各布局推荐组件配方」表）
2. 章节：.chapter-num / .chapter-num-final 编号 + .chapter-en 英文标签
3. 正文：每段 .kw-underline 标记 1-3 个关键词
4. 锚点：.anchor-bold 或 .anchor-block 全文 ≤5 处
5. 引言：.intro-highlight 高亮核心词（如有引言卡）
6. 目录：.toc-card + .toc-num + .toc-item（≥3 章节时）
7. 签名：末尾 .sig-placeholder 占位（或用户提供的署名）
8. 容器组件：按「各布局推荐组件配方」表使用，点缀 ≤3 种
9. 通用组件（v2.0）：.tag-step/.tag-case/.tag-skill 内容标签、.flow-row 流程卡、.tl-row 时间线、.end-divider END 分割线、.cover-card 封面卡、.info-note 信息旁注等——按需选用
10. 头图：class-based HTML 中不写头图 <img>（由 upload.py 自动注入）

①.4 渲染

python3 scripts/build_inline.py output/article-class-html.html output/article-inline.html --theme <选定>

build_inline.py 自动完成：

• class → inline style 转换
• <span leaf=""> 包裹所有文本节点（v1.9.0）
• validate_output() 强制校验

①.5 排版质量检查（v2.0 更新）

• 全文无 <style>、class=、<div>、linear-gradient、letter-spacing
• 🔴 全文文本已由 build_inline.py 自动包裹 <span leaf="">（v1.9.0 自动执行，validate_output 强制校验，不可跳过）
• 正文行高 ≥ 1.8，字号 ≥ 15px
• 🔴 每段正文含 1-3 个 .kw-underline 关键词下划线
• 🔴 章节编号连续（01/02/03…∞），不跳号
• 🔴 .anchor-bold / .anchor-block 全文 ≤ 5 处
• H2 视觉层级正确，英文标签已生成
• 关键观点用金句/强调模块包裹
• CTA 后有底部留白（≥32px）
• 颜色来自配色色板，全文主色一致
• 🔴 签名区仅末尾一处，默认占位或用户提供
• 头图位和配图位已标记（由 upload.py 阶段②自动注入）
• v2.0 通用组件按布局配方使用，点缀种类 ≤3

---

微信排版技术规范（Typography & Rendering Reference）

目标：无论选择哪套排版系统，最终输出都遵循以下技术规范。

4.1 🔴 微信 CSS 核心规则：禁止 <style> + 禁止 <div>

两项关键发现（基于生产环境实测验证）：

规则	后果	解决方案
<style> 标签	❌ 微信完全删除	所有样式写入 style="" 内联属性
class 属性	❌ 微信完全剥离	不依赖 class 选择器
<div> 元素	❌ 微信全部转为裸 <p>，丢失所有样式	零 div：用 <section>/<p>/<blockquote>/<table> 替代
linear-gradient	❌ 微信删除	用纯色 background-color 替代

唯一可靠的样式方式：style="" 内联属性 + 零 div + 语义化 HTML 元素。

4.2 微信排版硬约束

• ❌ 禁止 <style> 标签（微信直接删除）
• ❌ 禁止 <div> 元素（微信转为裸 <p>，样式全部丢失）
• ❌ 禁止 class 属性（微信直接删除）
• ❌ 禁止外部 CSS 文件、外部字体、JavaScript
• ❌ 禁止 position: fixed/absolute/sticky
• ❌ 禁止 flex 和 grid 布局（微信会剥离）
• ❌ 禁止 linear-gradient（微信会删除，改用纯色 background-color）
• ❌ 禁止 <iframe>、<form>、<input>
• ⚠️ <blockquote> 有隐性 300 字限制：微信编辑器对单次引用内容超过 300 字会自动插入「引用字数:XX/300」警告。超过 300 字的引用内容（如 Prompt 全文、长文摘录等）必须改用 <section> + border-left 样式替代
• ✅ 所有样式写在每个元素的 style="" 属性中
• ✅ 用语义元素替代 div：<section> 做容器、<blockquote> 做强调块（≤300字）、<section> + 左边框做超长引用（>300字）、<table> 做数据对比、<p> 做卡片
• ✅ 布局基于 block/inline-block/table + margin/padding
• ✅ 背景色使用纯色（background-color），禁用渐变
• ✅ 图片 src 必须是微信 CDN URL（mmbiz.qpic.cn 域名）
• ✅ 容器最大宽度 677px

Div → 语义元素映射表（关键！所有 <div> 必须转换）：

原始 div 用途	替换元素	示例
页面容器	<section style="...">	<section style="margin:0;padding:0 16px 0;...">
元信息标签	<span style="display:inline-block;..."> 包在 <p> 中	<p style="text-align:center;"><span style="...">深度解析</span></p>
开篇大数字	<p> + <strong>	<p style="text-align:center;"><strong style="font-size:56px;">9,500 ★</strong></p>
金句模块	<blockquote style="...">（不设左边框）	<blockquote style="background-color:#d4edf5;border-radius:12px;text-align:center;">
强调模块	<blockquote style="...">（带完整边框）	<blockquote style="background-color:#f7fafc;border:1px solid #e0e7ef;">
卡片列表 wrapper	直接删除，子项用 <p>
卡片项	<p style="...">（带背景+边框+圆角）	<p style="background-color:#fafbfc;border:1px solid #e8ecf1;border-radius:8px;">
数据双栏	<table> + <td style="width:50%">
CTA 底部	<blockquote style="...">（不设左边框）	<blockquote style="margin-top:44px;background-color:#d4edf5;border-radius:14px;">
编辑注记	<p style="...">（左侧灰色细线）	<p style="border-left:2px solid #dce3ea;color:#8a9aaa;font-style:italic;">
超长引用（>300字）	<section style="...">（左边框 + 略小字号，视觉等效 blockquote 但不触发微信 300 字限制）	<section style="border-left:3px solid #0d7377;margin:16px 0;padding:4px 0 4px 18px;"><p style="font-size:14px;color:#4a5a6a;">...</p></section>

4.3 6 套异构排版系统（v1.8.0）

每套排版系统拥有独立的组件库、HTML 结构和视觉语言，不是同一骨架换 CSS。

排版系统一览

系统	设计理念	H2 特征	独有组件	适用文章类型
classic 经典左线	左粗线分区，结构清晰	左蓝条+浅底	.golden-quote .card-item .highlight-box	观点分析、工具盘点
cardflow 卡片流	每段独立成卡，模块化	深色顶栏（卡片标题）	.section-card .info-card .data-badge	产品介绍、工具清单
editorial 杂志流	大标题+引题+戏剧化引用	居中+上下装饰线	.lead .ornament-divider .image-frame	商业评论、人物访谈
guide 手册流	步骤编号+提示框+对比	最大号无装饰	.step-num .tip-box .warn-box	教程指南、案例实战
letter 书信流	日期+问候+署名，极简	只比正文略大	.dateline .greeting .sign-off .postscript	个人随笔、生活感悟
workshop 极客流	深色实验台+Prompt卡+工具徽章	深底白字，等宽感	.prompt-card .tool-badge .workflow-step	技术编程、AI 实战
moyu 摸鱼杂志	翠绿卡片+黄色高亮+虚线引用	大号绿字+深色标题	.cover-card .pill-capsule .flow-row	教程测评、工具盘点
red-editorial 红白编辑	正红点睛+克制白底+戏剧引言卡	红底编号+底部红色实线	.intro-card .intro-quote-mark .end-divider	观点分析、读书感悟
graphite 素砚	全灰阶+1px细线，极致克制	无底色大留白	.golden-quote（上下细线） .highlight-box	设计评论、科技观点
zen 虚白	虚室生白+大呼吸感，极简	衬线体+64px 章间距	.golden-quote（无线框） .card-item（底部分割线）	深度随笔、读书笔记
ticket 票根	票据隐喻+硬阴影+撕票虚线	虚线上下边框	.golden-quote（硬阴影） .card-item（硬阴影）	工具对比、创意测评
olive 墨帖	墨色深底+暖橙点睛，编辑质感	深色底栏+6px 小圆角	.golden-quote（橙左边条） .tl-row .highlight-box	案例复盘、深度评测

12 套预设主题组合（v2.0）

预设名	布局	配色	适用内容	适用文章类型
teal	classic 经典左线	teal-gold 青蓝金	通用深度分析	opinion list tutorial
navy	editorial 杂志流	navy-coral 深蓝珊瑚	商业/行业评论	opinion interview data
forest	guide 手册流	forest-amber 森语琥珀	教程/操作指南	tutorial case
plum	cardflow 卡片流	plum-sage 梅紫灰绿	产品/工具介绍	list personal case
slate	letter 书信流	slate-rose 岩灰玫瑰	个人随笔/故事	personal interview
amber	workshop 极客流	forest-amber 森语琥珀	技术/AI/编程	tutorial case list
moyu	moyu 摸鱼杂志	emerald 摸鱼绿	教程测评/工具盘点	tutorial list case opinion
ruby	red-editorial 红白编辑	crimson 红白编辑	观点分析/读书感悟	opinion personal interview
graph	graphite 素砚	graphite 素砚	设计/科技/高端品牌	opinion data case
zen	zen 虚白	zen 虚白	深度随笔/读书笔记	personal opinion interview
ticket	ticket 票根	ticket 票根	工具对比/创意测评	list case tutorial
olive	olive 墨帖	olive 墨帖	案例复盘/深度评测	case opinion tutorial

🆕 v1.8.0 智能标记 CSS 类（全布局通用）

以下新增类在所有 6 套布局中可用，由 AI 在阶段①.0 智能预处理时主动标记，build_inline.py 自动转换为 inline style：

CSS 类	层级	用途	频率
.kw-underline	🟡 标记层	主题色下划线——关键词标记的默认手段	每段 1-3 处
.kw-underline-warn	🟡 标记层	对比色下划线——对比/否定专用	偶尔
.highlight-marker	🟡 标记层	荧光笔效果——偶尔长句强调	偶尔
.anchor-bold	🔴 锚点层	主色加粗——最强强调	全文 ≤5 处
.anchor-block	🔴 锚点层	主色底白字标签——视觉锚点	全文 ≤3 处
.intro-highlight	🔴 锚点层	引言核心词高亮——开场焦点	引言内 ≤2 处
.chapter-num	⚪ 结构层	章节大号编号（01/02…）	每章 1 处
.chapter-num-final	⚪ 结构层	结语编号变体（∞）	末章 1 处
.chapter-en	⚪ 结构层	英文章节副标签	每章 1 处
.toc-card / .toc-num / .toc-item	⚪ 容器层	目录/看点卡片	≥3 章时 1 组
.sig-placeholder	⚪ 结构层	签名区占位	文末 1 处

🆕 v2.0 通用组件库（跨布局可用）

CSS 类	类别	用途	适用布局
.tag-step .tag-case .tag-skill	内容标签	STEP/CASE/SKILL 编号标签	guide, moyu, olive, workshop
.flow-row .flow-active .flow-inactive .flow-arrow	流程卡片	3 步横排流程展示	moyu, guide, workshop
.tl-row .tl-dot-circle .tl-dot-line .tl-body	时间线	递进/经历脉络	olive, editorial, red-editorial
.end-divider .end-line-l .end-line-r .end-label	END 分割	章节结束标记	red-editorial, editorial, letter
.pill-capsule	胶囊列表	行内圆角标签	moyu, classic, cardflow
.cover-card .cover-tag .cover-title .cover-subtitle	封面卡	文章开篇封面	moyu, red-editorial, olive
.info-note	信息旁注	左竖条提示/名词解释	red-editorial, classic, editorial
.cta-triple .cta-action .cta-icon-box	CTA 三连	点赞/在看/转发三连区	所有布局（文末）

各布局推荐组件配方

布局	常用组件	点缀组件
classic 经典左线	.golden-quote .highlight-box .card-item	.info-note .pill-capsule
cardflow 卡片流	.section-card .info-card .data-badge	.golden-quote
editorial 杂志流	.lead .golden-quote .ornament-divider	.end-divider .tl-row
guide 手册流	.step-block .tip-box .warn-box	.tag-step .flow-row
letter 书信流	.dateline .greeting .sign-off	.end-divider
workshop 极客流	.prompt-card .tool-badge .workflow-step	.tag-skill .flow-row
moyu 摸鱼杂志	.cover-card .golden-quote .card-item	.flow-row .pill-capsule .tag-step
red-editorial 红白编辑	.intro-card .golden-quote .end-divider	.info-note .tl-row
graphite 素砚	.golden-quote .highlight-box	.cover-card
zen 虚白	.golden-quote（无线框居中） .card-item（底部分割线）	几乎不加装饰
ticket 票根	.golden-quote（硬阴影） .card-item（硬阴影）	.cover-card .meta-tag
olive 墨帖	.golden-quote（橙左边条） .highlight-box	.tl-row .tag-skill .info-note

使用方式

# 预设组合
python3 scripts/build_inline.py in.html out.html --theme navy

# 显式指定布局和配色
python3 scripts/build_inline.py in.html out.html --layout workshop --palette teal-gold

# 自定义主色（默认 classic 布局，自动推导配色）
python3 scripts/build_inline.py in.html out.html --theme "#e63946"

---

4.3.5 主题推荐与可视化预览（v1.8.0）🔴 强制交互节点

在运行 build_inline.py 之前，必须执行以下交互流程：

步骤 A：文章类型判定 + 自动推荐

调用 detect_content_type(text) → recommend(text) 分析文章文本。recommend() 返回：

{
    "presets": [("forest", {...}, 16), ("amber", {...}, 13), ...],  # 降序排列
    "content_type": "tutorial",          # 文章类型 ID
    "content_type_name": "教程/操作指南",  # 中文名
    "content_type_confidence": "high",    # high/medium/low
    "secondary_type": "case",             # 次类型（可能为 None）
}

推荐逻辑：关键词匹配分 + 文章类型加权（高置信度 +3 分，中 +1 分），确保同类型文章推荐稳定。

步骤 B：生成可视化预览网页

python3 scripts/preview_themes.py output/article-class-html.html --open

步骤 C：用户选择

预览页打开后，必须暂停等待用户选择。用户可回复：

• 预设名：navy、amber、forest、teal、plum、slate
• 自由组合：classic:teal-gold workshop:navy-coral
• 自定义颜色：#e63946
• 「用推荐的」→ 使用得分最高的预设

步骤 D：进入 build_inline.py

用户确认后，将选定主题传入：

python3 scripts/build_inline.py output/article-class-html.html output/article-inline.html --theme <选定主题>

---

4.4 嵌套上下文特殊处理

某些元素在特定父容器内需要覆盖默认样式：

父容器	子元素	特殊处理
<blockquote>	<p>	color:#4a5a6a;font-size:14px;（覆盖默认 p 的 color:#3f3f3f）
<pre>	<code>	去掉 background-color 和 color（继承 pre 的深色主题）
.golden-quote	<p>	color:#0d7377;font-weight:700;text-align:center;
.highlight-box	<strong>	color:#0d7377;（覆盖默认 strong 的 color:#212121）
.cta-footer	<p>	color:#0d7377;font-weight:500;text-align:center;font-size:14px;

4.5 HTML 生成流程

Step 0：主题推荐与预览（v1.3.0 🔴 强制交互）

• 用 recommend_theme() 分析文章内容 → 自动推荐最匹配的主题
• 运行 preview_themes.py --open → 在浏览器中并排展示 5 套主题的实际渲染效果
• 暂停等待用户选择（主题名 / 自定义颜色 / 「用推荐的」）
• 将选定 --theme <name|#RRGGBB> 传给 build_inline.py

Step 1：生成 class-based HTML（便于结构可读性）

<blockquote class="golden-quote"><p>万物皆可蒸馏</p></blockquote>

⚠️ 必须使用语义元素（<p>, <blockquote>, <h2>, <h3>, <section>, <code>, <hr>, <strong>），严禁 <div>。🔴 禁止 <pre> 标签（微信不支持，换行全部丢失，参见铁律 7）。格式化文本用 <section> + white-space:pre-wrap + <br> 替代。

⚠️ <code> 内如需展示 HTML 标签（如 <style>），必须写 <style>，不要写裸 <style>。

⚠️ 头图（v1.3.0）：class-based HTML 中不要写头图 <img>。头图由 upload.py 自动上传 img/header_image.png 并在阶段⑤注入正文顶部。

Step 2：用 build_inline.py 将 class 映射转换为 inline style（v1.9.0：自动包裹 <span leaf="">）

python3 scripts/build_inline.py output/article-class-html.html output/article-inline.html --theme teal

# 🔴 关键：必须设置 convert_charrefs=False
# 否则 HTMLParser 会把 &lt; &gt; 转成 < >，导致 <code> 内的标签被当作真标签吃掉内容
parser = HTMLParser(convert_charrefs=False)
# 移除所有 class 属性，注入对应的 style 属性（颜色来自主题色板）
# 🆕 v1.9.0：同时自动为所有文本节点包裹 <span leaf="">，防微信剥离样式

⚠️ AI 在生成 class-based HTML 时不需要手写 <span leaf="">——build_inline.py 的 InlineStyleConverter.handle_data() 自动完成包裹，validate_output() 强制校验。

Step 3：后处理嵌套上下文冲突（blockquote p、pre code、golden-quote p、cta-footer p 等） ⚠️ 嵌套覆盖必须追踪父级 class 名，不能只追踪 tag 名。例如 golden-quote 下的 <p> 和普通 blockquote 下的 <p> 需要不同的覆盖样式。

Step 4：输出纯 body 片段 HTML（仅 inner content，不含 <html>, <head>, <body> 标签），所有样式通过 style="" 内联，全文无 <style> 标签、无 class 属性、无 <div> 元素。

Step 5（v1.3.0）：运行 upload.py 完成头图注入 + 底部留白 + 封面上传 + 草稿创建

python3 scripts/upload.py --token TOKEN --html output/article-inline.html --title "标题" --author "嗯哌" --digest "摘要"

upload.py 自动执行：上传 img/header_image.png → 注入 <img> 到正文顶部 → 底部注入留白 <p> → 上传 img/cover.png 做封面 → 创建草稿

4.6 排版质量检查清单

• 全文无 <style> 标签
• 全文无 class 属性
• 所有元素样式通过 style="" 内联
• 全文无 linear-gradient（已替换为纯色 background-color）
• 全文无 letter-spacing
• 正文行高 ≥ 1.8，字号 ≥ 15px
• 在 375px 宽视口下无横向滚动
• H2 ≤ 19px，视觉层级正确（H2 > H3 > 正文 > 辅助文字）
• 关键观点使用金句模块或强调模块包裹
• 文章底部有 CTA 模块
• CTA 之后有底部留白（≥32px 空行，便于追加底部信息）
• blockquote / golden-quote / cta-footer 内子元素样式已做嵌套覆盖
• class-based HTML 中不含头图 <img>（由 upload.py 阶段⑤自动注入）
• 颜色来自主题色板，全文主色一致（v1.3.0）

---

阶段 ②：一键发布（Publish）

目标：排版完成 → 推送到公众号草稿箱，用户打开后台即可预览和群发。

5.1 凭据获取

按以下顺序查找微信 API 凭据：

1. 环境变量：WEIXIN_APPID / WEIXIN_APPSECRET 或 WECHAT_APPID / WECHAT_APPSECRET
2. 会话上下文：如果用户在本轮对话中已提供过，直接复用（不在日志中明文输出）
3. 主动询问：以上均未找到时，向用户询问 AppID 和 AppSecret。提示路径：公众号后台 → 开发 → 基本配置

凭据仅在当前会话内存缓存，不写入任何文件。

5.2 获取 Access Token

GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

• 有效期 7200 秒，会话内存缓存复用
• 失败重试 1 次，仍失败则中止并报告错误

5.3 封面处理

thumb_media_id 为必填字段。封面图获取 / 生成优先级：

1. img/cover.png（v1.3.0 默认）：skill 根目录下预置封面图，直接上传到微信素材库
2. 用户显式指定的图片路径/URL → 上传到微信素材库
3. 文章内第一张 <img> 的 src（需已是 mmbiz.qpic.cn URL）
4. 自动生成封面图（fallback）：用 Python 内置库生成品牌色纯色 PNG，1080×1080px → 上传
5. 以上均失败 → 报告错误，不上传空封面

本地上传封面：

POST https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN&type=image

成功返回 media_id 和微信 CDN URL（mmbiz.qpic.cn）。将 URL 回填到正文 <img> 标签中。

头图自动注入（v1.3.0）：upload.py 会自动上传 img/header_image.png 到微信素材库，获取 CDN URL，并注入到正文 HTML 最顶部。class-based HTML 中不需要手写头图 <img>。

封面自动生成代码模板：

import struct, zlib

def create_cover_png(w=1080, h=1080):
    """生成品牌色纯色 PNG"""
    def chunk(ctype, data):
        c = ctype + data
        crc = struct.pack('>I', zlib.crc32(c) & 0xffffffff)
        return struct.pack('>I', len(data)) + c + crc
    
    ihdr_data = struct.pack('>IIBBBBB', w, h, 8, 2, 0, 0, 0)
    ihdr = chunk(b'IHDR', ihdr_data)
    
    raw = b''
    for y in range(h):
        raw += b'\x00'
        for x in range(w):
            raw += struct.pack('BBB', 13, 115, 119)  # #0d7377
    
    idat = chunk(b'IDAT', zlib.compress(raw))
    iend = chunk(b'IEND', b'')
    
    return b'\x89PNG\r\n\x1a\n' + ihdr + idat + iend

封面裁剪提示：微信在星标/常读用户侧展示 2.35:1 宽图，普通用户展示 1:1 方图。核心信息必须放在图片中央 1:1 区域内。

5.4 创建草稿

使用 upload.py 一键完成：头图上传注入 → 底部留白 → 封面上传 → 创建草稿。

python3 scripts/upload.py \
  --token ACCESS_TOKEN \
  --html output/article-inline.html \
  --title "文章标题（≤64字）" \
  --author "嗯哌" \
  --digest "摘要（≤120字）"

upload.py 内部流程：

步骤 0：去除 <section> 外层容器 → 让内容直接填满微信文章区宽度（v1.7.0）

步骤 1：上传 img/header_image.png → 获取微信 CDN URL → 注入 <img> 到正文最前面

步骤 2：追加底部留白 <p style="margin:0;padding:0;height:0;"><br></p> 到正文最后

步骤 3：上传 img/cover.png → 获取 thumb_media_id（若不存在则自动生成品牌色封面 fallback）

步骤 4：构建 payload → 🔴 铁律1 序列化 → 创建草稿

# 🔴 关键：必须 ensure_ascii=False，否则中文变 \uXXXX → 微信编辑器显示乱码
# 🔴 必须用 data= 传 UTF-8 字节，不能用 json= 参数
payload_json = json.dumps(payload, ensure_ascii=False)
resp = requests.post(
    f"https://api.weixin.qq.com/cgi-bin/draft/add?access_token={token}",
    data=payload_json.encode("utf-8"),
    headers={"Content-Type": "application/json; charset=utf-8"},
    timeout=60,
)

关键约束：

• title ≤ 64 字，超长自动截断末尾加 …
• content 中的 HTML 已由 upload.py 自动注入头图和底部留白
• thumb_media_id 为必填项——upload.py 自动从 img/cover.png 获取

5.5 错误处理

错误码	含义	处理
40001	access_token 过期/无效	重新获取 token，重试 1 次
40007	不合法的媒体 ID	① 检查 thumb_media_id 是否已正确上传；② 重新上传封面获取新 media_id；③ 确认上传时使用了 type=image 参数
40125	无效的 appsecret	提示用户检查凭据，重新提供
45009	调用频率超限	等待 1 分钟后重试
50000+	微信服务器错误	等待 5 秒后重试，最多 3 次

5.6 成功响应

{ "media_id": "xxx" }

保存 media_id，提示用户：打开公众号后台 → 草稿箱 → 预览确认排版效果 → 群发。

上传完成后，upload.py 自动清理临时文件，只保留 HTML 排版文件和原始 Markdown。

---

完整链路示例

示例 1：默认完整流程——优化 + 排版 + 发布

用户：帮我把这篇文章优化后发公众号
（附带 draft.md）

→ 阶段⓪：内容脱水 + 结构重组 + 去AI味
→ 🔴 输出优化稿 → 用户确认「可以」
→ 阶段①：analyze_content() → 推荐最佳排版系统
         preview_themes.py --open → 浏览器 6 套对比
         🔴 用户选择
         build_inline.py --theme <选定> → inline HTML
→ 阶段②：upload.py → 上传头图+封面 → 创建草稿
→ ✅ media_id 返回

示例 2：豁免优化 + 指定排版

用户：这篇按原文，用卡片流排版发公众号，一字不改

→ 豁免「一字不改」→ 跳过阶段⓪
→ 阶段①：用户指定「卡片流」→ build_inline.py --theme plum
→ 阶段②：upload.py → ✅

示例 3：自定义颜色

用户：主色用 #e63946，发公众号

→ 阶段⓪① 正常执行
→ 阶段①：build_inline.py --theme "#e63946" → 默认 classic 布局 + 自动推导配色
→ 阶段②：upload.py → ✅

---

与其它 Skill 的协作

• oral-stylizer：阶段⓪ 的前置处理器。口述碎碎念先调 oral-stylizer 结构化，再进入本 skill。
• humanizer-zh：阶段⓪.3 去 AI 味的执行引擎，直接调用审阅全文。

协作管线：oral-stylizer → wechat-automator（⓪优化 → ①排版 → ②发布）

配图扩展（预留口子）

本 skill 不内置配图生成。但 HTML 结构支持配图占位：

<p class="illustration"><img src="PLACEHOLDER" alt="配图说明"></p>

配图准备完成后，替换 PLACEHOLDER 为微信 CDN URL 即可。.illustration 样式（居中、圆角、全宽）已在所有排版系统中内置。

未来可通过安装 npie-illustrations skill 实现自动配图流程（出 shot list → 生成 → 插入），两 skill 接口已预留对齐。

---

---

🔴 历史事故与铁律（2026-06-09 血泪教训）

以下每条都曾经导致过批量乱码草稿的生产事故。违反任何一条 = 用户草稿箱被污染 = 不可接受。

铁律 0：排版发布 = 必须调用本 skill

用户说「排版」「发布」「排版发布」「发公众号」「推送草稿」或任何含公众号发布意图的话 → 必须先用 Skill 工具加载 wechat-automator，然后严格按其五阶段流水线执行。 严禁以下行为：

• ❌ 加载了 skill 但自己另写 Python 脚本绕过
• ❌ 手动拼接 HTML 直接用 requests 上传
• ❌ 用 curl 代替 skill 的 build_and_upload.py
• ❌ 跳过 class-based → html.parser → inline 转换管线

skill 加载后的 scripts/build_and_upload.py 是唯一合法的执行入口。

铁律 1：JSON 序列化必须 ensure_ascii=False

# ❌ 错误：requests 的 json= 参数默认 ensure_ascii=True
# 中文 → \uXXXX → 微信编辑器不解码 → 草稿箱全乱码
resp = requests.post(url, json=payload)

# ✅ 正确：手动序列化，ensure_ascii=False
payload_json = json.dumps(payload, ensure_ascii=False)
resp = requests.post(url, data=payload_json.encode("utf-8"),
                     headers={"Content-Type": "application/json; charset=utf-8"})

根因：requests.post(json=payload) 内部调用 json.dumps(payload)，默认 ensure_ascii=True，所有非 ASCII 字符（中文）被转义为 \uXXXX。微信 API 虽接受请求并返回成功，但草稿编辑器不解码这些转义序列，直接显示为 我把...。

铁律 2：HTMLParser 必须 convert_charrefs=False

# ❌ 错误：默认 convert_charrefs=True
# &lt;style&gt; → <style>（真标签）→ 微信/浏览器吃掉后续内容
parser = HTMLParser()  # 默认 convert_charrefs=True

# ✅ 正确
parser = HTMLParser(convert_charrefs=False)
# &lt;style&gt; 保持为实体引用 → handle_entityref('lt') → 正确输出 &lt;

根因：Python HTMLParser 默认 convert_charrefs=True，将 < > 等命名实体转为对应字符 < >。如果 <code>&lt;style&gt;</code> 被转为 <code><style></code>，<style> 被当作真标签，导致后面内容全部丢失。

铁律 3：只传 body 片段，不传完整 HTML 文档

# ❌ 错误：传完整 HTML 文档给 content 字段
content = "<!DOCTYPE html><html><head>...</head><body>...</body></html>"

# ✅ 正确：只传 body 内部纯内容片段
# content = "<p>...</p><h2>...</h2><blockquote>...</blockquote>"
# 不含 <html>, <head>, <body>, <section> 外层包裹

根因：微信草稿 API 的 content 字段期望的是文章内文 HTML 片段，不是完整网页文档。传入 <!DOCTYPE> / <html> / <head> 标签会导致编辑器解析异常。

铁律 4：嵌套覆盖必须追踪父级 class

# ❌ 错误：只追踪 tag 名，无法区分子元素的父容器类型
tag_stack = ["blockquote"]  # 丢失 class 信息
# golden-quote 下的 <p> 和 cta-footer 下的 <p> 都用了 blockquote p 样式

# ✅ 正确：追踪 (tag, class) 元组
tag_stack = [("blockquote", "golden-quote")]
# 先查 (class, tag) → (golden-quote, p) → 正确样式
# 再查 (tag, tag)   → (blockquote, p)    → 兜底样式

铁律 6：超长引用（>300 字）禁用 <blockquote>，改用 <section> + 左边框

<!-- ❌ 错误：Prompt 全文等超长内容（>300字）包在 <blockquote> 中
     微信编辑器自动插入警告：「引用字数:1119/300(单次引用不得超过300字)」 -->
<blockquote>
  <p>你现在是我的Obsidian知识库资深架构师和重构专家...</p>
  <p>审查重点（必须覆盖）...</p>
  <!-- ...1100+ 字内容 -->
</blockquote>

<!-- ✅ 正确：用 <section> + border-left 替代，视觉等效但无字数警告 -->
<section style="border-left:3px solid #0d7377;margin:16px 0;padding:4px 0 4px 18px;">
  <p style="font-size:14px;color:#4a5a6a;">你现在是我的Obsidian知识库资深架构师和重构专家...</p>
  <p style="font-size:14px;color:#4a5a6a;">审查重点（必须覆盖）...</p>
</section>

根因：微信编辑器对 <blockquote> 元素有隐性 300 字上限检测。超过 300 字的单次引用会被自动插入警告文字，破坏排版。<section> 不受此限制，配合 border-left 样式可实现相同的视觉效果。

适用范围：Prompt 全文、长文摘录、多段落引用等任何可能超过 300 字的引用内容。短引用（≤300 字）仍可正常使用 <blockquote>。

铁律 5：上传前必须验证，验证必须排除 <code> 和 <pre>

# ❌ 错误：全文搜索 <style，误判 <code>&lt;style&gt;</code> 中的内容
# ❌ 错误：全文搜索 <div，误判 <code>&lt;div&gt;</code> 中的内容

# ✅ 正确：先 strip <code> 和 <pre> 块，再验证其余部分
clean = re.sub(r'<code[^>]*>.*?</code>', '', html, flags=re.DOTALL)
clean = re.sub(r'<pre[^>]*>.*?</pre>', '', clean, flags=re.DOTALL)
# 然后在 clean 上做 <style>, <div>, class= 检查

铁律 7：微信不支持 <pre> 标签——所有换行全部丢失，内容变成一行（2026-06-26 实战血证）

<!-- ❌ 致命错误：<pre> 在微信编辑器中被吃掉所有换行符
     CLAUDE.md 的 151 行内容变成一行，目录树结构完全塌缩 -->
<pre style="...">
# My‑Viki 系统规则
## 1. 角色与总目标
- 你是 **My‑Viki 的知识架构师和维护者**。
...
</pre>
<!-- 结果：微信草稿箱里变成一行乱码 -->

根因：微信编辑器不支持 <pre> 标签。<pre> 内的换行符（\n）被全部忽略，所有内容挤压成一行。同时 <pre> 的背景色和等宽字体样式也可能被剥离。

✅ 唯一正确的替代方案：<section> + white-space:pre-wrap + 显式 <br> 换行

import html as html_mod

def text_to_wechat_block(content, style_extras=""):
    """
    将多行文本转为微信兼容的格式化区块。
    三步：① HTML 转义 → ② \n → <br> → ③ 包入 <section>
    """
    escaped = html_mod.escape(content)       # 转义 < > & "
    with_br = escaped.replace('\n', '<br>')  # 换行 → 显式 <br>
    return f'<section style="white-space:pre-wrap;font-family:monospace;{style_extras}">{with_br}</section>'

关键样式说明：

样式属性	作用	必要性
white-space:pre-wrap	保留空格缩进，配合 <br> 换行	🔴 必须
font-family:monospace	等宽字体，替代 <pre> 的默认等宽效果	🟡 强烈建议
max-height:520px;overflow-y:auto	长内容滚动（CLAUD.md/WIKI.md 等 150+ 行文件）	🟡 按需
-webkit-overflow-scrolling:touch	iOS 平滑滚动	🟡 按需

适用范围：目录树、代码块、配置文件全文、Markdown 原文展示——任何依赖换行和空格对齐的格式化文本，一律用此方案，禁止使用 <pre>。

禁止 <pre> 的唯一例外：build_inline.py 的验证逻辑中，<pre> 仅在 <code> 展示 HTML 标签转义示例（如 <style>）时可用于 class-based 中间文件，但最终输出到微信的 HTML 必须零 <pre>。

铁律 8：每段正文必须标记 1-3 个关键词下划线（v1.8.0）

<!-- ❌ 错误：整段没有任何标记，读者扫过去全是灰字，信息密度为零 -->
<p style="..."><span leaf="">前端通过自然语言描述需求，Agent 自动完成从代码生成到部署的全链路。</span></p>

<!-- ✅ 正确：AI 主动标记 1-3 个关键短语 -->
<p style="...">
  <span leaf="">前端通过</span>
  <span style="border-bottom:2px solid #0d737740;font-weight:600;"><span leaf="">自然语言描述需求</span></span>
  <span leaf="">，Agent 自动完成从</span>
  <span style="border-bottom:2px solid #0d737740;font-weight:600;"><span leaf="">代码生成到部署</span></span>
  <span leaf="">的全链路。</span>
</p>

根因：公众号是扫描式阅读。读者不会逐字读，而是用眼睛扫关键词。没有下划线标记的段落 = 读者什么都抓不住 = 跳出。.kw-underline 是全文出现频率最高的样式，必须逐段落实。

铁律 9：章节编号必须连续，末章结语用 ∞（v1.8.0）

<!-- ❌ 错误：编号跳号（01 → 03），或中间章节用了结语编号 ∞ -->
<!-- ❌ 错误：末章是"写在最后"但编号仍是普通数字 04 -->

<!-- ✅ 正确：01 → 02 → 03 → ∞，严格连续 -->
<span class="chapter-num" leaf="">01</span>  <!-- 第一章 -->
<span class="chapter-num" leaf="">02</span>  <!-- 第二章 -->
<span class="chapter-num" leaf="">03</span>  <!-- 第三章 -->
<span class="chapter-num-final" leaf="">∞</span>  <!-- 结语章 -->

根因：章节编号是读者的空间导航。跳号会让读者困惑"我漏看了什么？"；末章不用 ∞ 区分会让结语淹没在正文中。

铁律 10：锚点层全文 ≤ 5 处（v1.8.0）

.anchor-bold（主色加粗）和 .anchor-block（主色底白字标签）只在全文最关键的 ≤5 处使用——产品名、核心结论、CTA 动词。到处锚点 = 没有锚点。正文日常强调用 .kw-underline（标记层），不要滥用 .anchor-bold。

铁律 11：签名区仅末尾一处，默认占位（v1.8.0）

• 签名区（「我是 {{作者名}}…」+「点赞、在看、转发」）只在文末 CTA 之前出现一次
• 原文末尾已有作者签名段的，直接沿用原文，不另生成
• 默认用 {{作者名}} / {{一句话简介}} 占位符——不要写死任何人名
• 中间章节不出现签名式段落

铁律 12：点缀组件种类 ≤ 3，不跨布局混用（v1.8.0）

一篇只用所选布局的组件 + 通用视觉层级类。.tip-box / .warn-box / .prompt-card / .card-item 等容器级组件，全篇点缀种类 ≤3，避免花哨。不要从其他布局借组件——每个布局的组件是成套设计的，混用会破坏排版气质一致性。

铁律 13：所有文本节点必须包裹 <span leaf=""> ——微信防样式剥离的命门（v1.9.0）

<!-- ❌ 错误：裸文本直接放在 <p> 内，微信可能剥离样式 -->
<p style="...">这是一段正文内容</p>

<!-- ✅ 正确：文本包裹在 <span leaf=""> 中 -->
<p style="..."><span leaf="">这是一段正文内容</span></p>

根因：微信公众号编辑器在处理粘贴的 HTML 时，会对没有 <span> 包裹的裸文本进行"样式归一化"——轻则丢失加粗/颜色，重则整段样式崩塌。<span leaf=""> 是唯一可靠的全平台防剥离手段。

实施方式（v1.9.0 起自动执行）：

• build_inline.py 的 InlineStyleConverter.handle_data() 自动为所有文本节点包裹 <span leaf="">
• validate_output() 强制检查 leaf 包裹数量，为 0 时报错
• AI 在生成 class-based HTML 时不需要手写 <span leaf="">——转换管线自动补全
• 例外：<code> 和 <pre> 内的文本保持原样（代码内容不容干扰）
• 防双重包裹：转换器自动检测已存在的 <span leaf="">，不会嵌套

---

安全与隐私

• API 凭据（AppID / AppSecret）优先级：环境变量 → 会话上下文 → 主动询问。仅在当前会话内存缓存，不写入任何磁盘文件
• 生成的 HTML 和草稿内容保存在本地，不经过第三方服务中转
• 上传完成后自动清理临时文件（JSON payload、自动生成的封面 PNG）
• 凭据在日志和输出中不出现明文