mp-weixin-skills

微信公众号文章管理 Skill

概述

这是一个专门用于管理微信公众号文章发布的 Skill。当您需要将文章发布到微信公众号时，此 Skill 会：

1. 首先要求 AI 将文章转换为微信公众号格式的 HTML
2. 然后使用 Python 脚本上传素材和创建草稿

核心原则：

• AI 负责：文档转换（Markdown/Word/PDF → 微信公众号 HTML）
• Skill 负责：微信 API 操作（上传素材、草稿管理）

快速开始

使用前准备

1. 配置微信公众号 API 凭证

在 skills 目录下或项目根目录创建 .env 文件：

# 微信公众号配置（必需）
WECHAT_APP_ID=your_app_id_here
WECHAT_APP_SECRET=your_app_secret_here

# 输出配置（可选）
OUTPUT_DIR=./output
TEMP_DIR=./temp

# 样式配置（可选）
TEMPLATE_NAME=default
THEME_COLOR=#07c160

2. 安装依赖

pip install -e .

基本使用

场景 1: 发布新文章

请将这篇文章发布到微信公众号草稿箱

AI 会自动：

1. 将文档转换为微信公众号格式的 HTML
2. 生成封面图片
3. 上传到微信草稿箱

场景 2: 仅转换格式（不上传）

python3 scripts/cli.py publish article.md --no-api

生成的 HTML 文件保存在 output/ 目录

场景 3: 更新已有草稿

python3 scripts/cli.py update <media_id>

场景 4: 上传图片素材

# 上传单张图片
python3 scripts/cli.py upload-image image.jpg

# 批量上传
python3 scripts/cli.py upload-images ./images

工作流程

完整发布流程

┌─────────────────────────────────────────────────────────┐
│                    第一步：AI 文档转换                    │
├─────────────────────────────────────────────────────────┤
│  1. 读取文章内容（Markdown/Word/PDF）                       │
│  2. 按样式规范转换为 HTML                                  │
│  3. 应用内联样式（标题、段落、代码块等）                    │
│  4. 生成符合微信阅读体验的完整 HTML                       │
│                                                             │
│  输出：带有内联样式的 HTML 字符串                          │
└─────────────────────────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────┐
│                第二步：微信草稿管理（Python 脚本）           │
├─────────────────────────────────────────────────────────┤
│  1. 接收 AI 生成的 HTML                                   │
│  2. 扫描并提取文章中的图片引用                              │
│  3. 下载远程图片到临时目录（如适用）                        │
│  4. 批量上传所有图片到微信素材库                            │
│  5. 替换 HTML 中的图片链接为微信 CDN URL                  │
│  6. 生成封面图片（模板生成或使用 AI 生成的图片）         │
│  7. 上传封面到微信素材库                                     │
│  8. 调用微信公众号 API 创建草稿                           │
│  9. 返回草稿 media_id 用于后续更新                          │
└─────────────────────────────────────────────────────────┘

图片处理流程（自动）

当文章包含图片时，脚本会自动执行以下步骤：

┌─────────────────────────────────────────────────────────┐
│                    图片提取与上传                         │
├─────────────────────────────────────────────────────────┤
│  扫描文章 → 识别图片类型 → 处理图片 → 上传素材库 → 替换链接  │
│                                                             │
│  图片类型处理：                                              │
│  • 本地图片 → 直接上传                                      │
│  • 相对路径 → 解析为完整路径后上传                          │
│  • 远程图片 → 下载到 temp/ 后上传                          │
│  • 已存在微信 → 跳过（可扩展）                              │
└─────────────────────────────────────────────────────────┘

图片处理特性：

• ✅ 自动扫描 Markdown/HTML 中的图片引用
• ✅ 支持本地图片和远程 URL
• ✅ 自动下载远程图片到临时目录
• ✅ 批量上传到微信素材库
• ✅ 自动替换 HTML 中的链接为微信 CDN URL
• ✅ 显示上传进度和结果统计

为什么这样设计？

优势	说明
职责分离	AI 擅长内容理解和样式应用，脚本专注 API 操作
质量更高	AI 能理解语义，生成更符合公众号风格的内容
维护简单	不需要维护复杂的文档解析逻辑，脚本只做 API 调用
灵活扩展	可以轻松更换 AI 提供商或转换方式

CLI 命令

发布文章

# 使用 API 上传到草稿箱
python3 scripts/cli.py publish article.md

# 仅生成 HTML 文件
python3 scripts/cli.py publish article.md --no-api

# 使用指定模板
python3 scripts/cli.py publish article.md --template fancy

更新草稿

# 更新已有草稿
python3 scripts/cli.py update <media_id>

# 指定新的源文件
python3 scripts/cli.py update <media_id> --source new-article.md

# 重新生成封面
python3 scripts/cli.py update <media_id> --regenerate-cover

上传图片

# 上传单张图片
python3 scripts/cli.py upload-image cover.jpg

# 上传为缩略图
python3 scripts/cli.py upload-image cover.jpg --type thumb

# 批量上传文件夹中的图片
python3 scripts/cli.py upload-images ./images

# 指定文件模式
python3 scripts/cli.py upload-images ./photos --pattern "*.png"

# 上传为缩略图
python3 scripts/cli.py upload-images ./covers --type thumb

样式规范

自动应用的样式

元素	样式特点
一级标题	主题色渐变背景、白色文字、圆角阴影
二级标题	左侧主题色装饰条（4px）、12px 左内边距
段落	行高 1.75、字号 15px、两端对齐
代码块	深色背景（#2d2d2d）、支持横向滚动、字号 13px
内联代码	浅灰背景（#f0f0f0）、粉色文字（#d63384）
引用块	左侧主题色边框、浅灰背景
表格	表头主题色背景、白色文字、边框合并

主题色推荐

色值	适用场景
#07c160	科技、效率（默认）
#ff6b6b	生活、情感
#4a90e2	商业、职场
#f5a623	教育、培训
#9013fe	创意、设计

详细文档

此 SKILL 遵循 Progressive Disclosure 原则，详细文档按需加载：

文档	内容	何时阅读
平台特征参考	用户画像、内容调性、阅读行为	需要了解公众号平台特征时
转换规则参考	标题优化、开头格式、正文结构、视觉元素	AI 转换文档时
样式规范参考	完整样式配置、移动端优化	需要自定义样式时
封面生成参考	封面规格、生成方式、设计原则	需要生成封面时
图片上传参考	图片格式、批量上传、优化建议	需要上传图片时
工作流参考	完整工作流、场景示例、自动化脚本	需要了解完整流程时

图片素材上传

当文章包含本地图片时：

1. AI 会自动：扫描图片引用，批量上传到素材库
2. 手动上传：使用 upload-images 命令
3. 图片规范：
   • 格式：JPG, PNG
   • 大小：thumb ≤ 2MB，image ≤ 5MB
   • 推荐尺寸：宽度 ≤ 900px

详细说明请查看 图片上传参考

封面图生成

自动封面规格：

• 尺寸：1080×460 (2.35:1)
• 格式：JPEG
• 质量：95%
• 字体：华文黑体（支持中文）

封面生成方式：

方式	说明	适用场景
搜索加工（默认）	从 Unsplash/Pexels 搜索高质量图片，添加渐变遮罩和标题文字	适用于所有文章
AI 生成	使用 Claude/Midjourney/DALL·E 生成	重要文章、品牌建设
模板生成	自动使用文章标题生成，渐变背景	网络不可用时的备选

详细说明请查看 封面生成参考

移动端友好设计

代码块（移动端优化）

关键特性：

• 深色背景（#2d2d2d）保护眼睛
• 字号 13px 适合手机阅读
• 横向滚动（overflow-x: auto）
• 不强制换行（white-space: pre）
• iOS 平滑滚动（-webkit-overflow-scrolling: touch）

设计原则：

1. 不破坏代码结构
2. 支持横向滚动查看长代码
3. 触控滑动体验流畅

图片优化

移动端建议：

• 单张图片 ≤ 500KB
• 宽度 ≤ 900px
• 使用渐进式 JPEG
• 考虑图片懒加载

常见问题

Q: 转换后的 HTML 在哪？

A: 使用 --no-api 参数时，HTML 保存在 output/ 目录

Q: 如何获取 media_id？

A: 发布成功后会返回 media_id，也可以在微信公众号后台查看

Q: 图片上传失败怎么办？

A: 检查图片大小（image ≤ 5MB，thumb ≤ 2MB），使用 TinyPNG 压缩后重试

Q: 代码块在手机上显示不全？

A: 这是正常的，代码块支持横向滚动，不会强制换行破坏代码结构

项目结构

mp-weixin-skills/
├── SKILL.md              # 主文件（304 行，<500 行 ✅）
├── skills.json           # Skill 元数据
├── .env.example          # 环境配置示例
│
├── scripts/              # 可执行脚本（核心功能）
│   ├── cli.py           # 命令行接口（主入口）
│   ├── config.py        # 配置管理
│   ├── exceptions.py    # 自定义异常
│   │
│   ├── wechat/          # 微信 API 操作（核心）⭐
│   │   ├── __init__.py
│   │   └── api_client.py
│   │
│   ├── covers/          # 封面生成（核心）⭐
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── template_maker.py
│   │
│   ├── converters/      # HTML 处理（可选）
│   │   ├── __init__.py
│   │   ├── html_builder.py
│   │   └── style_manager.py
│   │
│   ├── parsers/         # 文档解析（可选，AI 主要处理）
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── markdown.py
│   │   ├── pdf.py
│   │   └── word.py
│   │
│   └── utils/           # 工具函数
│       ├── __init__.py
│       └── logger.py
│
├── references/           # 详细文档（按需加载）📚
│   ├── platform-guide.md      # 平台特征
│   ├── conversion-rules.md    # 转换规则（AI 转换时）
│   ├── style-specs.md         # 样式规范
│   ├── cover-guide.md         # 封面指南
│   ├── image-upload.md        # 图片上传
│   └── workflows.md           # 工作流程
│
├── examples/             # 示例文章
├── tests/               # 测试文件（可选）
├── output/              # 输出目录（生成）
└── temp/                # 临时文件（生成）

核心功能说明：

• ⭐ wechat/ - 微信公众号 API 操作（上传素材、创建/更新草稿）
• ⭐ covers/ - 自动封面生成（1080×460）
• 📚 references/ - Progressive Disclosure 文档，按需加载

许可证

MIT License