Overview
This is a Skill specifically for managing the publishing of WeChat Official Account articles. When you need to publish an article to a WeChat Official Account, this Skill will:
- First require the AI to convert the article into HTML in WeChat Official Account format
- Then use Python scripts to upload materials and create drafts
Core principles:
- AI is responsible for: document conversion (Markdown/Word/PDF → WeChat Official Account HTML)
- Skill is responsible for: WeChat API operations (uploading materials, draft management)
Quick Start
Preparation Before Use
- Configure WeChat Official Account API credentials
In the skills directory or the project root directory, create a .env file:
# 微信公众号配置（必需）
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
- Install dependencies
pip install -e .
Basic Usage
Scenario 1: Publish a new article
请将这篇文章发布到微信公众号草稿箱
The AI will automatically:
- Convert the document into HTML in WeChat Official Account format
- Generate a cover image
- Upload to the WeChat draft box
Scenario 2: Convert format only (no upload)
python3 scripts/cli.py publish article.md --no-api
The generated HTML file is saved in the output/ directory
Scenario 3: Update an existing draft
python3 scripts/cli.py update <media_id>
Scenario 4: Upload image materials
# 上传单张图片
python3 scripts/cli.py upload-image image.jpg
# 批量上传
python3 scripts/cli.py upload-images ./images
Workflow
Complete publishing workflow
┌─────────────────────────────────────────────────────────┐
│ 第一步：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 用于后续更新 │
└─────────────────────────────────────────────────────────┘
Image processing workflow (automatic)
When an article contains images, the script will automatically perform the following steps:
┌─────────────────────────────────────────────────────────┐
│ 图片提取与上传 │
├─────────────────────────────────────────────────────────┤
│ 扫描文章 → 识别图片类型 → 处理图片 → 上传素材库 → 替换链接 │
│ │
│ 图片类型处理： │
│ • 本地图片 → 直接上传 │
│ • 相对路径 → 解析为完整路径后上传 │
│ • 远程图片 → 下载到 temp/ 后上传 │
│ • 已存在微信 → 跳过（可扩展） │
└─────────────────────────────────────────────────────────┘
Image processing features:
- ✅ Automatically scan image references in Markdown/HTML
- ✅ Support local images and remote URLs
- ✅ Automatically download remote images to a temporary directory
- ✅ Batch upload to the WeChat material library
- ✅ Automatically replace links in HTML with WeChat CDN URLs
- ✅ Display upload progress and result statistics
Why is it designed this way?
| Advantage | Description |
|---|---|
| Separation of responsibilities | AI excels at content understanding and style application, while scripts focus on API operations |
| Higher quality | AI can understand semantics and generate content that better matches the Official Account style |
| Simple maintenance | No need to maintain complex document parsing logic; scripts only make API calls |
| Flexible expansion | Easily switch AI providers or conversion methods |
CLI Commands
Publish article
# 使用 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
Update draft
# 更新已有草稿
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
Upload image
# 上传单张图片
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
Style Specifications
Automatically applied styles
| Element | Style features |
|---|---|
| Level 1 heading | Theme color gradient background, white text, rounded corners with shadow |
| Level 2 heading | Left-side theme color decorative bar (4px), 12px left padding |
| Paragraph | Line height 1.75, font size 15px, justified |
| Code block | Dark background (#2d2d2d), supports horizontal scrolling, font size 13px |
| Inline code | Light gray background (#f0f0f0), pink text (#d63384) |
| Blockquote | Left theme-color border, light gray background |
| Table | Header theme-color background, white text, collapsed borders |
Theme color recommendations
| Color value | Applicable scenarios |
|---|---|
#07c160 |
Technology, productivity (default) |
#ff6b6b |
Lifestyle, emotions |
#4a90e2 |
Business, workplace |
#f5a623 |
Education, training |
#9013fe |
Creativity, design |
Detailed documentation
This SKILL follows the Progressive Disclosure principle, with detailed documentation loaded on demand:
| Document | Content | When to read |
|---|---|---|
| Platform characteristics reference | User personas, content tone, reading behavior | When you need to understand the characteristics of the WeChat Official Account platform |
| Conversion rules reference | Title optimization, opening format, body structure, visual elements | When AI converts documents |
| Style specification reference | Complete style configuration, mobile optimization | When you need to customize styles |
| Cover generation reference | Cover specifications, generation methods, design principles | When you need to generate a cover |
| Image upload reference | Image formats, batch upload, optimization suggestions | When you need to upload images |
| Workflow reference | Complete workflow, scenario examples, automation scripts | When you need to understand the complete process |
Image asset upload
When the article contains local images:
- AI will automatically: scan image references and batch upload them to the asset library
- Manual upload: use the
upload-imagescommand - Image specifications：
- Format: JPG, PNG
- Size: thumb ≤ 2MB, image ≤ 5MB
- Recommended size: width ≤ 900px
For detailed instructions, see Image upload reference
Cover image generation
Automatic cover specifications:
- Size: 1080×460 (2.35:1)
- Format: JPEG
- Quality: 95%
- Font: STHeiti (supports Chinese)
Cover generation methods:
| Method | Description | Applicable scenarios |
|---|---|---|
| Search and process(default) | Search for high-quality images from Unsplash/Pexels, add gradient overlay and title text | Applicable to all articles |
| AI generation | Generate using Claude/Midjourney/DALL·E | Important articles, brand building |
| Template generation | Automatically generate using the article title, gradient background | Fallback when the network is unavailable |
For detailed instructions, see Cover Generation Reference
Mobile-Friendly Design
Code Blocks (Mobile-Optimized)
Key Features:
- Dark background (#2d2d2d) protects the eyes
- 13px font size is suitable for mobile reading
- Horizontal scrolling（overflow-x: auto）
- No forced line breaks（white-space: pre）
- iOS smooth scrolling（-webkit-overflow-scrolling: touch）
Design Principles:
- Does not break code structure
- Supports horizontal scrolling to view long code
- Smooth touch swipe experience
Image Optimization
Mobile Recommendations:
- Single image ≤ 500KB
- Width ≤ 900px
- Use progressive JPEG
- Consider lazy loading images
FAQ
Q: Where is the converted HTML?
A: When using the --no-api parameter, the HTML is saved in the output/ directory
Q: How do I get the media_id?
A: After a successful publish, the media_id is returned; you can also view it in the WeChat Official Account backend
Q: What should I do if the image upload fails?
A: Check the image size (image ≤ 5MB, thumb ≤ 2MB), compress it with TinyPNG, and try again
Q: The code block is not fully displayed on mobile?
A: This is normal. Code blocks support horizontal scrolling and will not force line breaks that break the code structure
Project Structure
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/ # 临时文件（生成）
Core Feature Description:
- ⭐ wechat/ - WeChat Official Account API operations (upload materials, create/update drafts)
- ⭐ covers/ - Automatic cover generation (1080×460)
- 📚 references/ - Progressive Disclosure documentation, loaded on demand
License
MIT License