wpsnote/wechat-publisher

WeChat Publisher - 公众号发布助手

将已完成的 WPS 笔记内容，一键排版并导出为微信公众号 HTML 格式。这是创作流程的最后一步：内容已完成，只需排版发布。

使用场景

典型工作流：

1. 用 content-creator 创作文章内容
2. 保存到 WPS 笔记
3. 用本 skill 导出排版好的 HTML ← 你在这里
4. 粘贴到公众号后台直接发布

---

Contract（契约）

Input Contract

触发条件：

• "发公众号"
• "排版公众号"
• "导出到公众号"
• "我要发布了"
• "文章排版"
• "生成公众号 HTML"
• "这篇可以发了"
• "帮我排版一下"

输入类型：

1. WPS 笔记 ID（必填）：内容已完成的笔记
2. 模板名称（可选）：default/minimal/elegant，默认 blue-theme
3. 输出路径（可选）：默认生成 {标题}_formatted.html

前置条件：

• 笔记内容已完成（不是空笔记）
• 笔记已保存并同步到云端
• 内容建议 < 20000 字符

Output Contract

| 文件 | 说明 | |------|------| | {标题}_formatted.html | 带内联样式的公众号排版文件，可直接粘贴到公众号编辑器 |

排版特性：

• WPS 笔记 XML 直接转 HTML（无 Markdown 中间层，样式精度更高）
• WPS 预设颜色（fontColor / fontHighlightColor）完整映射到内联样式
• 代码块语法高亮
• 图片自适应处理
• 移动端阅读优化

Error Contract

| 错误场景 | 错误码 | 处理方式 | |---------|--------|----------| | 笔记不存在 | NOTE_NOT_FOUND | 检查 note_id 是否正确 | | 笔记为空 | EMPTY_CONTENT | 提示先完成内容创作 | | 内容过长 | CONTENT_TOO_LONG | 建议拆分为多篇发布 | | 图片处理失败 | IMAGE_ERROR | 检查图片链接有效性 |

---

工具优先级策略

优先使用 CLI，降级到 MCP：

检查 wpsnote-cli 是否可用
    ↓ 可用（推荐路径）
wpsnote-cli current / find  → 获取笔记 ID
wpsnote-cli read --note_id <id> --json → 获取笔记内容（XML）
    ↓ CLI 不可用（命令不存在 / 认证失败）
[降级] MCP: get_current_note / search_notes
[降级] MCP: read_note

AI 操作决策树：

用户触发「排版发布」
    │
    ├─ 检测 wpsnote-cli
    │       ↓ 可用
    │   ① 无 note_id → wpsnote-cli current --json
    │     有 note_id → 直接跳到 ③
    │       ↓ 不可用
    │   ① 无 note_id → MCP: get_current_note()
    │
    ├─ ② 搜索确认（用户给了关键词）
    │     CLI:  wpsnote-cli find --keyword "xxx" --json
    │     MCP:  search_notes({ keyword: "xxx" })
    │
    ├─ ③ 读取笔记内容
    │     CLI:  wpsnote-cli read --note_id <id> --json
    │     MCP:  read_note({ note_id: <id> })
    │
    └─ ④ 执行导出脚本
          python scripts/export-to-html.py --note-id <id>
          → 生成 "{标题}_formatted.html"

---

快速开始

方式一：CLI 读取 + 脚本转换（推荐）

# 获取当前笔记并导出
python scripts/export-to-html.py --current

# 通过 note_id 直接导出
python scripts/export-to-html.py --note-id "abc123"

# 指定模板风格
python scripts/export-to-html.py --note-id "abc123" --template "elegant"

# 搜索笔记并导出
python scripts/export-to-html.py --search "文章标题"

Python API

from scripts.export_to_html import WPSNoteExporter

exporter = WPSNoteExporter()
exporter.export(
    note_id="abc123",
    template_name="default",
    output_path="./article.html"
)

方式二：MCP 工具方式（CLI 不可用时降级）

通过 wps-note SKILL 的 MCP 工具读取笔记内容，再转换为 HTML：

# 1. 搜索并获取笔记
search_notes({ keyword: "文章标题" }) → note_id

# 2. 读取笔记内容
read_note({ note_id }) → xml_content

# 3. 转换为 HTML（本地脚本处理）
python scripts/export-to-html.py --note-id <id>

完整 MCP 工作流示例

# 步骤 1：获取当前笔记（或搜索）
get_current_note()
→ { note_id: "abc123", title: "AI 工具介绍", word_count: 3500 }

# 步骤 2：读取笔记内容（根据大小选择方式）
get_note_outline({ note_id: "abc123" })
→ blocks: [...]

read_note({ note_id: "abc123" })
→ xml_content: "<h1>AI 工具介绍</h1><p>...</p>"

# 步骤 3：导出为 HTML（本地脚本转换）
python scripts/export-to-html.py --note-id "abc123" --template blue-theme
→ 生成 "AI 工具介绍_formatted.html"

---

占位符标签（快速排版）

在 WPS 笔记中使用这些标签，导出时自动转换为对应样式：

| 标签 | 用法 | 效果 | |------|------|------| | <b/> | <b/>文字</b> | 橙色加粗（整段或行内） | | <h2/> | <h2/>大标题</h2> | 蓝色大标题（一级章节） | | <h3/> | <h3/>小标题</h3> | 蓝色小标题（二级分节） | | <bq/> | <bq/>引用文字</bq> | 灰底蓝边引用块 | | <note/> | <note/>注释文字</note> | 灰色小字注释 |

使用示例：

<h2/>01｜核心观点

<b/>整段橙色加粗，适合核心金句。</b>

<b/>行内加粗</b> 用于强调重点词汇。

<h3/>深入分析

正文段落正常书写...

<bq/>引用块适合摘录观点或补充说明。</bq>

<note/>注：本文仅代表个人观点。</note>

---

WPS 笔记颜色 → HTML 颜色映射

WPS 笔记的 XML 中颜色受预设色板约束，导出时按下表映射为公众号内联样式 RGB 值：

fontColor（字体颜色）

| WPS XML 值 | 含义 | HTML 输出 | |-----------|------|----------| | #080F17 | 黑色 | color: rgb(8,15,23) | | #C21C13 | 红色 | color: rgb(194,28,19) | | #DB7800 | 橙色 | color: rgb(219,120,0) | | #078654 | 绿色 | color: rgb(7,134,84) | | #0E52D4 | 蓝色 | color: rgb(14,82,212) | | #0080A0 | 浅蓝 | color: rgb(0,128,160) | | #757575 | 灰色 | color: rgb(117,117,117) | | #DA326B | 粉色 | color: rgb(218,50,107) | | #D1A300 | 金色 | color: rgb(209,163,0) | | #58A401 | 浅绿 | color: rgb(88,164,1) | | #116AF0 | 亮蓝 | color: rgb(17,106,240) | | #A639D7 | 紫色 | color: rgb(166,57,215) |

fontHighlightColor（文字背景高亮）

| WPS XML 值 | 含义 | HTML 输出 | |-----------|------|----------| | #FBF5B3 | 黄色 | background-color: rgb(251,245,179); padding:0 2px; border-radius:2px | | #F8D7B7 | 橙色 | background-color: rgb(248,215,183); ... | | #F7C7D3 | 粉色 | background-color: rgb(247,199,211); ... | | #DFF0C4 | 绿色 | background-color: rgb(223,240,196); ... | | #C6EADD | 深绿 | background-color: rgb(198,234,221); ... | | #D9EEFB | 蓝色 | background-color: rgb(217,238,251); ... | | #D5DCF7 | 浅蓝 | background-color: rgb(213,220,247); ... | | #E6D6F0 | 紫色 | background-color: rgb(230,214,240); ... | | #E6E6E6 | 灰色 | background-color: rgb(230,230,230); ... |

注意：任意 hex 色值在 WPS 编辑器中会被静默丢弃，导出脚本只处理上述预设色板中的颜色，其他值忽略不渲染。

---

模板风格

| 模板 | 特点 | 适用场景 | |------|------|----------| | blue-theme ⭐默认 | 蓝色强调色，现代简洁 | 科技、企业、正式文档 | | default | 橙色风格，专业美观 | 通用场景 | | minimal | 极简风格，干净利落 | 技术文档、教程 | | elegant | 优雅精致，细节丰富 | 深度长文、品牌内容 |

blue-theme 蓝色主题

基于样本 HTML 的蓝色主题，特点：

• 主色: rgb(36, 91, 219) 深蓝色
• 正文字号: 15px（比默认更小更紧凑）
• 行距: 2.0（更舒适的可读性）
• 引用块: 左边框 3px + 浅灰背景
• 分栏: Flex 布局，居中对齐

使用方法：

python scripts/export-to-html.py --note-id "abc123" --template blue-theme

---

与 content-creator 的组合

创作流程：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  content-       │     │   WPS 笔记      │     │  wechat-        │
│  creator        │ --> │   （内容完成）   │ --> │  publisher      │
│  （创作内容）    │     │                 │     │  （排版发布）    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              你在这里 ↑

完整示例：

# 1. 创作内容
python scripts/create-content.py --topic "AI 工具介绍"

# 2. 写入 WPS
python scripts/wps-write.py --input draft.md --title "AI 工具介绍"

# 3. 排版发布（本 skill）
python scripts/export-to-html.py --search "AI 工具介绍"

---

转换流程

WPS 笔记 XML
    │
    ├─ 占位符处理（<b/> <h2/> <bq/> <note/>）
    │
    ├─ xml_to_html()：逐块渲染
    │   ├─ <h1>/<h2>       → <h2 style="...蓝色...">
    │   ├─ <h3>-<h6>       → <p><span style="...蓝色...">
    │   ├─ <p>             → <p><span style="...灰色正文...">
    │   ├─ <p listType>    → 橙色圆点 / 橙色数字列表
    │   ├─ <blockquote>    → 灰底蓝边引用块
    │   ├─ <codeblock>     → 语法高亮代码框
    │   ├─ <table>         → 蓝色表头表格
    │   ├─ <highlightBlock>→ 高亮提示块（保留 WPS 配色）
    │   ├─ <columns>       → Flex 分栏
    │   ├─ <span fontColor>→ WPS 预设颜色 → RGB 内联样式
    │   └─ <strong>/<em>  → 加粗 / 斜体
    │
    └─ 套入 template.html 壳 → {标题}_formatted.html
                                      │
                                      └─ 浏览器打开 → 点「复制内容」→ 粘贴到公众号

文件结构

wechat-publisher/
├── SKILL.md               # 本文件
├── scripts/
│   ├── export-to-html.py  # 核心导出脚本（WPS XML → HTML 直接转换）
│   └── md_to_html.py      # 独立 MD 转 HTML 脚本（本地 .md 文件用）
├── templates/
│   ├── template.html      # HTML 输出壳（含复制按钮）
│   ├── preview.html       # 排版样例（各元素效果预览）
│   ├── default.yaml       # 默认模板（橙色风格）
│   ├── blue-theme.yaml    # 蓝色主题模板
│   ├── minimal.yaml       # 极简模板
│   └── elegant.yaml       # 优雅模板
└── references/
    └── format-guide.md    # 格式规范

---

常用编排模式

模式 1：直接导出当前笔记

用户已有内容，直接排版导出：

# CLI 方式（推荐）
python scripts/export-to-html.py --current --template blue-theme

# MCP 方式（降级）
get_current_note() → note_id
python scripts/export-to-html.py --note-id <id> --template blue-theme

模式 2：搜索后导出

用户不记得笔记 ID，先搜索再导出：

# CLI 方式（推荐）
python scripts/export-to-html.py --search "文章标题"

# MCP 方式（降级）
search_notes({ keyword: "文章标题" }) → note_id
python scripts/export-to-html.py --note-id <id>

---

Troubleshooting

CLI 不可用

现象：wpsnote-cli 命令未找到或认证失败 解决：自动降级使用 MCP 工具，流程不变

笔记读取失败 (NOTE_NOT_FOUND)

现象：search_notes 或 get_current_note 返回笔记不存在 原因：笔记 ID 错误、笔记被删除、编辑器未就绪 解决：

1. 重新搜索确认正确的 note_id
2. 检查 WPS 笔记应用是否正常打开
3. 如使用 get_current_note，确保笔记窗口是激活状态

内容为空或格式错乱

现象：导出的 HTML 内容为空或格式异常 原因：笔记 XML 解析失败、包含不支持的 block 类型 解决：

1. 检查笔记是否确实包含内容（不是空笔记）
2. 查看笔记是否包含 embed、note_audio_card 等只读内容
3. 手动检查 XML 结构是否有异常标签

图片无法显示

现象：公众号后台图片显示为空白或红叉 原因：图片 URL 失效、本地图片未正确转 base64、图片格式不支持 解决：

1. 网络图片：检查 URL 是否直接指向图片资源（不是 HTML 页面）
2. 本地图片：确认已转为 base64 data URI
3. 图片格式：优先使用 PNG、JPG，避免 WebP

占位符标签不生效

现象：<b/>、<h2/> 等标签在 HTML 中显示为纯文本 原因：标签格式错误、嵌套不当 解决：

1. 确保标签正确闭合：<b/>文字</b> ✓ <b/>文字 ✗
2. 检查标签是否嵌套在其他标签内导致解析失败
3. 参考占位符标签章节的正确用法

模板加载失败

现象：指定模板后样式未生效，使用默认样式 原因：模板名称拼写错误、模板文件缺失、YAML 解析错误 解决：

1. 检查模板名称拼写（blue-theme、default、minimal、elegant）
2. 确认 templates/ 目录存在对应 .yaml 文件
3. 检查模板 YAML 格式是否正确

HTML 粘贴到公众号后样式丢失

现象：本地预览正常，但粘贴到公众号后台样式错乱 原因：公众号编辑器过滤部分 CSS、微信内置浏览器兼容性问题 解决：

1. 使用内联样式（style="..."），避免 class 选择器
2. 避免使用复杂 CSS 特性（grid、flex 谨慎使用）
3. 在公众号后台预览后，用手机扫码查看实际效果

MCP 工具调用失败

现象：mcp__wpsnote__read_note 等工具报错 原因：EDITOR_NOT_READY、BLOCK_NOT_FOUND、网络问题 解决：

1. 检查 WPS 笔记应用是否正常运行
2. 重新获取 note_id 或 block_id
3. 参考 wps-note SKILL 的 Troubleshooting

---

注意事项

1. 这是最后一步：只用于内容已完成的笔记，不要在这里创作
2. CLI 优先：wpsnote-cli 可用时总是首选，速度快且更稳定
3. 行内代码：WPS XML 不支持行内代码，会被转为纯文本
4. 内容长度：超过 20000 字符建议拆分多篇
5. 图片处理：WPS 笔记里的图片 src 是 WPS CDN 地址，导出时直接引用，微信公众号可正常加载；不做 base64 转换（本地路径上传公众号容易失败）
6. 图片说明：带 caption 属性的图片，导出后会在图片下方生成灰色居中小字说明
7. 颜色约束：WPS 笔记只支持预设色板，任意 hex 会被编辑器静默丢弃；导出脚本按预设色板映射到 RGB，非预设色值直接忽略

---

Resources

• 格式规范：references/format-guide.md
• 模板配置：templates/
• 核心脚本：scripts/export-to-html.py
• MD 转换脚本：scripts/md_to_html.py