wechat-article-publisher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WeChat Article Publisher

微信文章发布工具

Publish Markdown or HTML content to WeChat Official Account drafts via API, with automatic format conversion.

通过API将Markdown或HTML内容发布到微信公众号草稿箱，支持自动格式转换。

Prerequisites

前提条件

WECHAT_API_KEY environment variable set (from .env file)
Python 3.9+
Authorized WeChat Official Account on wx.limyai.com

设置WECHAT_API_KEY环境变量（来自.env文件）
Python 3.9+
在wx.limyai.com上已授权的微信公众号

Scripts

脚本

Located in

~/.claude/skills/wechat-article-publisher/scripts/

位于

~/.claude/skills/wechat-article-publisher/scripts/

目录下：

wechat_api.py

WeChat API client for listing accounts and publishing articles:

bash

undefined

用于列出账号和发布文章的微信API客户端：

bash

undefined

List authorized accounts

python wechat_api.py list-accounts

Publish from markdown file

python wechat_api.py publish --appid <wechat_appid> --markdown /path/to/article.md

Publish from HTML file (preserves formatting)

python wechat_api.py publish --appid <wechat_appid> --html /path/to/article.html

Publish with custom options

python wechat_api.py publish --appid <appid> --markdown /path/to/article.md --type newspic

undefined

python wechat_api.py publish --appid <appid> --markdown /path/to/article.md --type newspic

undefined

parse_markdown.py

Parse Markdown and extract structured data (optional, for advanced use):

bash

python parse_markdown.py <markdown_file> [--output json|html]

解析Markdown并提取结构化数据（可选，用于高级场景）：

bash

python parse_markdown.py <markdown_file> [--output json|html]

Workflow

工作流程

Strategy: "API-First Publishing"

Unlike browser-based publishing, this skill uses direct API calls for reliable, fast publishing.

Load WECHAT_API_KEY from environment
List available WeChat accounts (if user hasn't specified)
Detect file format (Markdown or HTML) and parse accordingly
Call publish API to create draft in WeChat
Report success with draft details

Supported File Formats:

```
.md
```
files → Parsed as Markdown, converted by WeChat API
```
.html
```
files → Sent as HTML, formatting preserved

策略："API优先发布"

与基于浏览器的发布方式不同，本工具使用直接API调用，确保发布可靠、快速。

从环境变量加载WECHAT_API_KEY
列出可用的微信账号（如果用户未指定）
检测文件格式（Markdown或HTML）并进行相应解析
调用发布API在微信中创建草稿
返回包含草稿详情的成功报告

支持的文件格式：

```
.md
```
文件 → 解析为Markdown，通过微信API进行转换
```
.html
```
文件 → 以HTML格式发送，保留原格式

Step-by-Step Guide

分步指南

Step 1: Check API Key

步骤1：检查API密钥

Before any operation, verify the API key is available:

bash

undefined

在进行任何操作前，请验证API密钥是否已配置：

bash

undefined

Check if .env file exists and contains WECHAT_API_KEY

cat .env | grep WECHAT_API_KEY


If not set, remind user to:
1. Copy `.env.example` to `.env`
2. Set their `WECHAT_API_KEY` value

cat .env | grep WECHAT_API_KEY


如果未配置，请提醒用户执行以下操作：
1. 将`.env.example`复制为`.env`
2. 设置`WECHAT_API_KEY`的值

Step 2: List Available Accounts

步骤2：列出可用账号

Get the list of authorized WeChat accounts:

bash

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py list-accounts

Output example:

json

{
  "success": true,
  "data": {
    "accounts": [
      {
        "name": "我的公众号",
        "wechatAppid": "wx1234567890",
        "username": "gh_abc123",
        "type": "subscription",
        "verified": true,
        "status": "active"
      }
    ],
    "total": 1
  }
}

Important:

If only one account, use it automatically
If multiple accounts, ask user to choose
Note the
```
wechatAppid
```
for publishing

获取已授权的微信账号列表：

bash

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py list-accounts

输出示例：

json

{
  "success": true,
  "data": {
    "accounts": [
      {
        "name": "我的公众号",
        "wechatAppid": "wx1234567890",
        "username": "gh_abc123",
        "type": "subscription",
        "verified": true,
        "status": "active"
      }
    ],
    "total": 1
  }
}

重要提示：

如果只有一个账号，将自动使用该账号
如果有多个账号，请让用户选择目标账号
记录
```
wechatAppid
```
用于发布操作

Step 3: Publish Article

步骤3：发布文章

For Markdown files:

bash

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py publish \
  --appid <wechatAppid> \
  --markdown /path/to/article.md

For HTML files (preserves formatting):

bash

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py publish \
  --appid <wechatAppid> \
  --html /path/to/article.html

For 小绿书 (image-text mode):

bash

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py publish \
  --appid <wechatAppid> \
  --markdown /path/to/article.md \
  --type newspic

Success response:

json

{
  "success": true,
  "data": {
    "publicationId": "uuid-here",
    "materialId": "uuid-here",
    "mediaId": "wechat-media-id",
    "status": "published",
    "message": "文章已成功发布到公众号草稿箱"
  }
}

针对Markdown文件：

bash

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py publish \
  --appid <wechatAppid> \
  --markdown /path/to/article.md

针对HTML文件（保留格式）：

bash

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py publish \
  --appid <wechatAppid> \
  --html /path/to/article.html

针对小绿书（图文模式）：

bash

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py publish \
  --appid <wechatAppid> \
  --markdown /path/to/article.md \
  --type newspic

成功响应：

json

{
  "success": true,
  "data": {
    "publicationId": "uuid-here",
    "materialId": "uuid-here",
    "mediaId": "wechat-media-id",
    "status": "published",
    "message": "文章已成功发布到公众号草稿箱"
  }
}

Step 4: Report Result

步骤4：报告结果

After successful publishing:

Confirm the draft was created
Remind user to review and publish manually in WeChat admin panel
Provide any relevant IDs for reference

发布成功后：

确认草稿已创建
提醒用户登录微信公众平台手动审核并发布
提供相关ID供参考

API Reference

API参考

Authentication

认证

All API requests require the

X-API-Key

header:

X-API-Key: WECHAT_API_KEY

所有API请求都需要

X-API-Key

请求头：

X-API-Key: WECHAT_API_KEY

Get Accounts List

获取账号列表

POST https://wx.limyai.com/api/openapi/wechat-accounts

POST https://wx.limyai.com/api/openapi/wechat-accounts

Publish Article

发布文章

POST https://wx.limyai.com/api/openapi/wechat-publish

Parameters:

Parameter	Type	Required	Description
wechatAppid	string	Yes	WeChat AppID
title	string	Yes	Article title (max 64 chars)
content	string	Yes	Article content (Markdown/HTML)
summary	string	No	Article summary (max 120 chars)
coverImage	string	No	Cover image URL
author	string	No	Author name
contentFormat	string	No	'markdown' (default) or 'html'
articleType	string	No	'news' (default) or 'newspic'

POST https://wx.limyai.com/api/openapi/wechat-publish

参数：

参数	类型	是否必填	描述
wechatAppid	string	是	微信AppID
title	string	是	文章标题（最多64字符）
content	string	是	文章内容（Markdown/HTML格式）
summary	string	否	文章摘要（最多120字符）
coverImage	string	否	封面图片URL
author	string	否	作者名称
contentFormat	string	否	'markdown'（默认）或 'html'
articleType	string	否	'news'（默认）或 'newspic'

Error Codes

错误码

Code	Description
API_KEY_MISSING	API key not provided
API_KEY_INVALID	API key invalid
ACCOUNT_NOT_FOUND	Account not found or unauthorized
ACCOUNT_TOKEN_EXPIRED	Account authorization expired
INVALID_PARAMETER	Invalid parameter
WECHAT_API_ERROR	WeChat API call failed
INTERNAL_ERROR	Server error

代码	描述
API_KEY_MISSING	未提供API密钥
API_KEY_INVALID	API密钥无效
ACCOUNT_NOT_FOUND	账号不存在或未授权
ACCOUNT_TOKEN_EXPIRED	账号授权已过期
INVALID_PARAMETER	参数无效
WECHAT_API_ERROR	微信API调用失败
INTERNAL_ERROR	服务器错误

Critical Rules

核心规则

NEVER auto-publish - Only save to drafts, user publishes manually
Check API key first - Fail fast if not configured
List accounts first - User may have multiple accounts
Handle errors gracefully - Show clear error messages
Preserve original content - Don't modify user's markdown unnecessarily

禁止自动发布 - 仅保存到草稿箱，由用户手动发布
优先检查API密钥 - 如果未配置则直接终止操作
先列出账号 - 用户可能拥有多个账号
优雅处理错误 - 显示清晰的错误提示信息
保留原始内容 - 尽量不修改用户的Markdown内容

Supported Formats

支持的格式

Markdown Files (.md)

Markdown文件 (.md)

H1 header (# ) → Article title
H2/H3 headers (##, ###) → Section headers
Bold (text)
Italic (text)
Links text
Blockquotes (> )
Code blocks (
```
...
```
)
Lists (- or 1.)
Images → Auto-uploaded to WeChat

H1标题（# ）→ 文章标题
H2/H3标题（##、###）→ 章节标题
粗体（text）
斜体（text）
链接 text
引用块（> ）
代码块（
```
...
```
）
列表（- 或 1.）
图片 → 自动上传到微信

HTML Files (.html)

HTML文件 (.html)

```
<title>
```
or
```
<h1>
```
→ Article title
All HTML formatting preserved (styles, tables, etc.)
```
<img>
```
tags → Images auto-uploaded to WeChat
First
```
<p>
```
→ Auto-extracted as summary
Supports inline styles and rich formatting

HTML Title Extraction Priority:

```
<title>
```
tag content
First
```
<h1>
```
tag content
"Untitled" as fallback

HTML Content Extraction:

If
```
<body>
```
exists, uses body content
Otherwise, strips
```
<html>
```
,
```
<head>
```
,
```
<!DOCTYPE>
```
and uses remaining content

```
<title>
```
或
```
<h1>
```
→ 文章标题
保留所有HTML格式（样式、表格等）
```
<img>
```
标签 → 图片自动上传到微信
第一个
```
<p>
```
→ 自动提取为摘要
支持内联样式和富文本格式

HTML标题提取优先级：

```
<title>
```
标签内容
第一个
```
<h1>
```
标签内容
回退为"无标题"

HTML内容提取：

如果存在
```
<body>
```
标签，则使用body内容
否则，移除
```
<html>
```
、
```
<head>
```
、
```
<!DOCTYPE>
```
标签后使用剩余内容

Article Types

文章类型

news (普通文章)

news（普通文章）

Standard WeChat article format
Full Markdown/HTML support
Rich text with images

标准微信文章格式
完全支持Markdown/HTML
带图片的富文本内容

newspic (小绿书/图文消息)

newspic（小绿书/图文消息）

Image-focused format (like Instagram posts)
Maximum 20 images extracted from content
Text content limited to 1000 characters
Images auto-uploaded to WeChat

以图片为核心的格式（类似Instagram帖子）
最多从内容中提取20张图片
文本内容限制为1000字符
图片自动上传到微信

Example Flow

示例流程

Markdown File

Markdown文件

User: "把 ~/articles/ai-tools.md 发布到微信公众号"

bash

undefined

用户："把 ~/articles/ai-tools.md 发布到微信公众号"

bash

undefined

Step 1: Verify API key

cat .env | grep WECHAT_API_KEY

Step 2: List accounts

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py list-accounts

Step 3: Publish (assuming single account with appid wx1234567890)

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py publish
--appid wx1234567890
--markdown ~/articles/ai-tools.md

Step 4: Report

"文章已成功发布到公众号草稿箱！请登录微信公众平台预览并发布。"

undefined

undefined

HTML File

HTML文件

User: "把这个HTML文章发布到公众号：~/articles/newsletter.html"

bash

undefined

用户："把这个HTML文章发布到公众号：~/articles/newsletter.html"

bash

undefined

Step 1: Verify API key

cat .env | grep WECHAT_API_KEY

Step 2: List accounts

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py list-accounts

Step 3: Publish HTML (auto-detects format)

python ~/.claude/skills/wechat-article-publisher/scripts/wechat_api.py publish
--appid wx1234567890
--html ~/articles/newsletter.html

Step 4: Report

"文章已成功发布到公众号草稿箱！HTML格式已保留。请登录微信公众平台预览并发布。"

undefined

undefined

Error Handling

错误处理

API Key Not Found

API密钥未找到

Error: WECHAT_API_KEY environment variable not set.

Solution: Ask user to set up

.env

file with their API key.

Error: WECHAT_API_KEY environment variable not set.

解决方案：请用户在.env文件中配置API密钥。

Account Not Found

账号未找到

Error: ACCOUNT_NOT_FOUND - 公众号不存在或未授权

Solution: Ask user to authorize their account on wx.limyai.com.

Error: ACCOUNT_NOT_FOUND - 公众号不存在或未授权

解决方案：请用户在wx.limyai.com上授权其公众号。

Token Expired

令牌过期

Error: ACCOUNT_TOKEN_EXPIRED - 公众号授权已过期

Solution: Ask user to re-authorize on wx.limyai.com.

Error: ACCOUNT_TOKEN_EXPIRED - 公众号授权已过期

解决方案：请用户在wx.limyai.com上重新授权。

WeChat API Error

微信API错误

Error: WECHAT_API_ERROR - 微信接口调用失败

Solution: May be temporary issue, retry or check WeChat service status.

Error: WECHAT_API_ERROR - 微信接口调用失败

解决方案：可能是临时问题，请重试或检查微信服务状态。

Best Practices

最佳实践

Why use API instead of browser automation?

为什么使用API而非浏览器自动化？

Reliability: Direct API calls are more stable than browser automation
Speed: No browser startup, page loading, or UI interactions
Simplicity: Single command to publish
Portability: Works on any system with Python (no macOS-only dependencies)

可靠性：直接API调用比浏览器自动化更稳定
速度：无需启动浏览器、加载页面或进行UI交互
简洁性：一条命令即可完成发布
可移植性：在任何安装了Python的系统上均可运行（无macOS专属依赖）

Content Guidelines

内容指南

Images: Use public URLs when possible; local images will be uploaded
Title: Keep under 64 characters
Summary: Auto-extracted from first paragraph if not provided
Cover: First image in markdown becomes cover if not specified

图片：尽可能使用公共URL；本地图片将被自动上传
标题：保持在64字符以内
摘要：如果未提供，将自动从第一段提取
封面：如果未指定，Markdown中的第一张图片将作为封面

Workflow Efficiency

工作流程效率

Minimal workflow (1 command):
- list-accounts → get appid → publish → done

Full workflow (with verification):
1. Check .env → list accounts → confirm with user
2. Publish with options → report result

极简工作流程（1条命令）：
- list-accounts → 获取appid → publish → 完成

完整工作流程（含验证）：
1. 检查.env → 列出账号 → 与用户确认
2. 带选项发布 → 报告结果

Troubleshooting

故障排除

Q: How do I get a WECHAT_API_KEY?

问：如何获取WECHAT_API_KEY？

A: Register and authorize your WeChat account at wx.limyai.com to get your API key.

答：在wx.limyai.com注册并授权您的微信账号即可获取API密钥。

Q: Can I publish to multiple accounts?

问：能否发布到多个账号？

A: Yes, use

list-accounts

to see all authorized accounts, then specify the target

--appid

答：可以，使用

list-accounts

查看所有已授权账号，然后指定目标

--appid

。

Q: Images not showing in WeChat?

问：图片在微信中不显示？

A: Ensure images are accessible URLs. Local images are auto-uploaded but may fail if path is incorrect.

答：确保图片是可访问的URL。本地图片会自动上传，但如果路径错误可能会失败。

Q: Title is too long?

问：标题太长？

A: WeChat limits titles to 64 characters. The script will use the first 64 chars of H1.

答：微信限制标题为64字符。脚本将使用H1的前64个字符。

Q: What's the difference between news and newspic?

问：news和newspic有什么区别？

news

is standard article format;

newspic

(小绿书) is image-focused with limited text.

答：

news

是标准文章格式；

newspic

（小绿书）是以图片为核心的格式，文本内容有限制。