pw-post-to-wechat

WeChat Official Account Publishing Tool

Automate publishing content to WeChat Official Accounts, supporting both image-text and article modes.

Usage

Image-text publishing (multi-image with text)

# 从 markdown 文件和图片目录生成
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./images/

# 使用明确的参数
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --title "标题" --content "内容" --image img1.png --image img2.png --submit

# 仅预览不保存
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./images/

Article publishing (complete Markdown)

# 发布 markdown 文章 (默认主题)
npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md

# 指定主题
npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md --theme grace
npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md --theme simple

# 覆盖标题和作者
npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md --title "自定义标题" --author "作者名"

Description: ${SKILL_DIR} represents this skill's installation directory; the Agent will replace it with the actual path at runtime.

Parameter description

Image-text publishing parameters

--markdown

Specify the Markdown file path; automatically extracts the title and content.

Parameter type: file path (optional)

Feature description:

Parse frontmatter to get the title and author
If there is no frontmatter, use the first H1 title
Extract the first paragraph as the content (up to 1000 characters)
Automatically compress when the title exceeds 20 characters

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown ./article.md --images ./pics/

Markdown format:

---
title: 文章标题
author: 作者名
---

# 这是标题 (如果没有 frontmatter)

这是首段内容, 会被提取为图文内容...

Best practices:

Use frontmatter to explicitly specify the title and author
The first paragraph should be concise and compelling to attract readers
Keep the title within 20 characters to avoid compression

--images

Specify the image directory; uploads all images in the directory.

Parameter type: directory path (optional)

Feature description:

Upload all PNG/JPG files in the directory
Sort in alphabetical order by filename
Supports up to 9 images (WeChat limit)

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./images/

Best practices:

Name with numeric prefixes: 01-cover.png, 02-content.png
Ensure image clarity is suitable for mobile viewing
Keep the number of images within 9

--title

Directly specify the article title.

Parameter type: string (optional)

Limit: up to 20 characters, automatically compressed if exceeded

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --title "如何提升效率" --content "内容..." --image cover.png

Compression rules:

Original: "How to completely reshape your life in one day"
Compressed: "Reshape your life in one day"

Best practices:

The title should be concise and powerful, highlighting the core value
Avoid redundant words (how, in what way, etc.)
Use numbers and verbs to enhance appeal

--content

Directly specify the article content.

Parameter type: string (optional)

Limit: up to 1000 characters, automatically compressed if exceeded

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --title "标题" --content "这是内容..." --image img.png

Best practices:

The content should be concise and clear, guiding users to click and view
Highlight the article's core value and highlights
Keep it within 1000 characters to avoid compression

--image

Specify a single image file; can be used repeatedly to add multiple images.

Parameter type: file path (optional, repeatable)

Limit: up to 9 images

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --title "标题" --content "内容" --image img1.png --image img2.png --image img3.png

Best practices:

The first image serves as the cover and should be the most appealing
Image order affects the display effect
Ensure the image format is PNG or JPG

--submit

Save as draft; by default, only preview without saving.

Parameter type: Boolean flag (optional)

Default behavior: Do not save, preview only

Use cases:

After confirming the content is correct, add this parameter to save
Use when publishing in batches

Usage example:

# 仅预览
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./pics/

# 保存为草稿
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./pics/ --submit

Notes:

After saving, you need to manually publish in the WeChat Official Account backend
It is recommended to preview first to confirm everything is correct before saving

--profile

Specify the Chrome profile directory to keep the login state.

Parameter type: Directory path (optional)

Default behavior: Use a temporary profile

Use cases:

Avoid needing to scan the QR code to log in every time
Multi-account management

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./pics/ --profile ~/.chrome-wechat

Best practices:

Create different profile directories for different WeChat Official Account accounts
Regularly clean up profiles to avoid taking up too much space

Article publishing parameters

--markdown

Specify the Markdown file to convert and publish.

Parameter type: File path (required)

Feature description:

Fully parse Markdown format
Preserve styles such as headings, lists, quotes, and code blocks
Automatically handle image placeholders and replacement

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md

Supported Markdown syntax:

Heading: #, ##, ###
Bold: **text**
Italic: *text*
List: -, 1.
Quote: >
Code block: ```
Link: [text](url)
Image: ![alt](path)

Best practices:

Use standard Markdown syntax
Use relative paths for images
Avoid overly complex nested structures

--theme

Specify the article theme style.

Parameter type: String (optional)

Optional values:

default - Default theme, simple and elegant
grace - Graceful theme, suitable for formal content
simple - Minimal theme, highlighting the content itself

Default value: default

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md --theme grace

Theme features:

Theme	Applicable scenarios	Features
default	General content	Balances aesthetics and readability
grace	Formal articles, professional content	Elegant layout, emphasizing hierarchy
simple	Technical documentation, tutorials	Minimalist style, highlighting content

Best practices:

simple is recommended for technical articles
grace is recommended for brand content
Use default for everyday content

--title

Override the title extracted from Markdown.

Parameter type: String (optional)

Default behavior: Extract from Markdown frontmatter or H1

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md --title "自定义标题"

Use cases:

The Markdown file has no title
Need to use a title different from the one in the file
Use different titles for different platforms

--author

Specify the article author name.

Parameter type: String (optional)

Default value: Baoyu

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md --author "张三"

Best practices:

Use the real author name to enhance credibility
Team accounts can use the team name

--summary

Specify the article summary.

Parameter type: String (optional)

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md --summary "这是一篇关于..."

Best practices:

The summary should be concise and clear, summarizing the core of the article
Keep it within 100 characters
Highlight the article's value and key points

--html

Use a pre-rendered HTML file instead of Markdown.

Parameter type: File path (optional)

Use cases:

Already have rendered HTML content
Need to use custom styles
Complex layout requirements

Usage example:

npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --html article.html

Notes:

The HTML needs to comply with the requirements of the WeChat Official Account editor
Images still need to be handled using placeholders

--profile

Specify the Chrome profile directory.

Parameter type: Directory path (optional)

Function: Same as the --profile parameter for image-text publishing

Feature comparison

Function	Image-text publishing	Article publishing
Multiple image support	Supported (up to 9 images)	Supported (inline images)
Markdown support	Title/content extraction	Full formatting
Automatic title compression	Supported (compressed to 20 characters)	Not supported
Content compression	Supported (compressed to 1000 characters)	Not supported
Theme support	Not supported	Supported (default, grace, simple)
Applicable scenarios	Quickly publish multi-image content	Long articles, technical documentation

Workflow

Image-text publishing workflow

Parse content:
- Extract the title and content from the Markdown file
- Or use --title and --content to specify them directly
Process images:
- Read all images from the --images directory
- Or use multiple --image parameters to specify images
- Sort by file name
Automated publishing:
- Open the Chrome browser
- Navigate to the WeChat Official Account image-text editor
- Upload all images
- Fill in the title and content
- Decide whether to save based on the --submit parameter
Output results:
- Report publishing status
- Display the number of images
- Prompt follow-up actions

Article publishing workflow

Parse Markdown:
- Read the Markdown file
- Extract metadata such as title and author
- Identify all image references
Generate HTML:
- Convert Markdown to HTML
- Apply the selected theme style
- Replace images with placeholders [[IMAGE_PLACEHOLDER_N]]
Automated publishing:
- Open the Chrome browser
- Navigate to the WeChat Official Account article editor
- Paste the HTML content into the editor
Replace images:
- For each placeholder:
  - Find and select the placeholder text
  - Scroll into the visible area
  - Press Backspace to delete the placeholder
  - Paste the image from the clipboard
Output the result:
- Report the publishing status
- Display the number of images
- Suggest follow-up actions

Prerequisites

Google Chrome is installed
bun runtime (installed automatically via npx -y bun auto-installed)
On the first run, you need to log in to WeChat Official Account in the opened browser window

Common Issues

Login-related

Issue: QR code login is required on every run

Solution: Use the --profile parameter to specify the profile directory

npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./pics/ --profile ~/.chrome-wechat

Issue: Logs out immediately after login

Solution:

Check the network connection
Ensure the WeChat Official Account account status is normal
Try clearing the profile and logging in again

Image-related

Issue: Image upload failed

Solution:

Check the image format (only PNG/JPG supported)
Check the image size (less than 5MB recommended)
Ensure the image path is correct

Issue: Image order is incorrect

Solution:

Name with numeric prefixes: 01-, 02-, 03-
Or use multiple --image parameters to specify them in order

Content-related

Issue: Title is compressed

Solution:

Keep the title within 20 characters
Or manually edit the compressed title

Issue: Content is compressed

Solution:

Keep the content within 1000 characters
Or use article publishing mode to publish the full content

Browser-related

Issue: Chrome not found

Solution: Set environment variables

export WECHAT_BROWSER_CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Issue: Paste failed

Solution:

Check system clipboard permissions
Ensure Chrome has permission to access the clipboard
macOS requires granting permissions in System Settings

Script Reference

All scripts are located in this skill's scripts/ subdirectory.

Agent Execution Instructions:

Determine that the directory path of this SKILL.md file is SKILL_DIR
Script path = ${SKILL_DIR}/scripts/<script-name>.ts
Replace all ${SKILL_DIR} in the document with the actual path

Available Scripts:

Script	Purpose	Description
`wechat-browser.ts`	Image and text publishing	Multi-image with text mode
`wechat-article.ts`	Article publishing	Full Markdown format
`md-to-wechat.ts`	Markdown conversion	Convert to WeChat HTML
`copy-to-clipboard.ts`	Clipboard operations	Copy content to clipboard
`paste-from-clipboard.ts`	Paste operation	Send real paste keystroke

Usage examples

Example 1: Quick image-text publishing

# 场景: 有一篇 markdown 文章和一个图片目录
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown ./article.md --images ./xhs-images/

# 执行流程:
# 1. 解析 markdown 元数据:
#    - 标题: "如何在一天内彻底重塑你的人生" → "一天内重塑你的人生"
#    - 作者: 从 frontmatter 或使用默认值
# 2. 从首段提取内容
# 3. 在 xhs-images/ 中找到 7 张图片
# 4. 打开 Chrome, 导航到微信"图文"编辑器
# 5. 上传所有图片
# 6. 填充标题和内容
# 7. 报告: "图文已发布, 包含 7 张图片。"

Example 2: Publish a full article

# 场景: 发布一篇技术文章, 使用 simple 主题
npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown ./tech-article.md --theme simple

# 执行流程:
# 1. 解析 markdown, 找到 5 张图片
# 2. 生成带占位符的 HTML
# 3. 打开 Chrome, 导航到微信编辑器
# 4. 粘贴 HTML 内容
# 5. 对每张图片:
#    - 选中 [[IMAGE_PLACEHOLDER_1]]
#    - 滚动到可见区域
#    - 按 Backspace 删除
#    - 粘贴图片
# 6. 报告: "文章已编排, 包含 5 张图片。"

Example 3: Batch publishing

# 场景: 批量发布多篇文章
for file in articles/*.md; do
  npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts \
    --markdown "$file" \
    --images "images/$(basename $file .md)/" \
    --submit \
    --profile ~/.chrome-wechat
done

Example 4: Publish with custom parameters

# 场景: 完全自定义标题、内容和图片
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts \
  --title "2024 年度总结" \
  --content "回顾这一年的成长与收获..." \
  --image cover.png \
  --image chart1.png \
  --image chart2.png \
  --submit

Extension support

Customize configuration via EXTEND.md.

Check paths (priority order):

.pw-skills/pw-post-to-wechat/EXTEND.md (project level)
~/.pw-skills/pw-post-to-wechat/EXTEND.md (user level)

If found, load before the workflow. Extended content overrides default values.

Reference documentation

Image-text publishing: View references/image-text-posting.md for the detailed image-text publishing guide
Article publishing: View references/article-posting.md for the detailed article publishing guide

Notes

Image-text publishing titles are limited to 20 characters, content to 1000 characters
Up to 9 images (WeChat limit)
First run requires scanning a QR code to log in
Use the --profile parameter to keep the login state
It is recommended to preview and confirm before using --submit to save
Article publishing supports full Markdown format
Image processing requires system clipboard permissions
macOS requires granting Chrome clipboard permissions in System Settings

About this skill

Usage

Image-text publishing (multi-image with text)

Article publishing (complete Markdown)

Parameter description

Image-text publishing parameters

--markdown

--images

--title

--content

--image

--submit

--profile

Article publishing parameters

--markdown

--theme

--title

--author

--summary

--html

--profile

Feature comparison

Workflow

Image-text publishing workflow

Article publishing workflow

Prerequisites

Common Issues

Login-related

Image-related

Content-related

Browser-related

Script Reference

Usage examples

Example 1: Quick image-text publishing

Example 2: Publish a full article

Example 3: Batch publishing

Example 4: Publish with custom parameters

Extension support

Reference documentation

Notes