mage-send-to-wechat

name	mage-send-to-wechat
description	Publishes content to WeChat Official Account (微信公众号) through API or browser automation. Supports article publishing with HTML, markdown, or plain text input, and image-text posting with multiple images. Use when the user asks to 发布公众号、发微信公众号文章、发贴图/图文、post to wechat, or send WeChat Official Account content.

Send To WeChat Official Account

Script Directory

Determine this SKILL.md directory as SKILL_DIR, then use ${SKILL_DIR}/scripts/<name>.ts.

Script	Purpose
scripts/wechat-browser.ts	Image-text posting through browser automation
scripts/wechat-article.ts	Article publishing through browser automation
scripts/wechat-api.ts	Article publishing through WeChat API
scripts/check-permissions.ts	Environment and permission check

Reference Loading Guide

Keep SKILL.md lean. Load only the file needed for the current step:

• Read references/config/first-time-setup.md only when EXTEND.md does not exist.
• Read references/article-posting.md only when the user is publishing a full article workflow.
• Read references/image-text-posting.md only when the user is publishing image-text / 贴图 content.

Preferences (EXTEND.md)

Check preferences in this order:

test -f .mage-skills/mage-send-to-wechat/EXTEND.md && echo "project"
test -f "$HOME/.mage-skills/mage-send-to-wechat/EXTEND.md" && echo "user"

If not found, run references/config/first-time-setup.md before any other workflow step.

Supported keys:

• default_theme
• default_publish_method
• default_author
• need_open_comment
• only_fans_can_comment
• chrome_profile_path

Value priority:

1. CLI arguments
2. Frontmatter
3. EXTEND.md
4. Skill defaults

Pre-flight Check

Suggest this before first real use, but let the user skip if they prefer:

npx -y bun ${SKILL_DIR}/scripts/check-permissions.ts

This verifies Chrome, Bun, isolated profile, accessibility, clipboard, paste keystrokes, and WeChat API credentials.

Two Workflows

Image-Text Posting

Use this for short posts with multiple images, up to the WeChat image limit.

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

Load details from references/image-text-posting.md when needed.

Article Publishing

Use this for full-length articles that need HTML rendering, inline images, metadata, and optional API publishing.

Publishing Progress:
- [ ] Step 0: Load preferences
- [ ] Step 1: Determine input type
- [ ] Step 2: Check `mage-md-to-html`
- [ ] Step 3: Convert markdown to HTML
- [ ] Step 4: Validate metadata
- [ ] Step 5: Select publish method
- [ ] Step 6: Publish to WeChat
- [ ] Step 7: Report completion

Article Workflow

Step 0: Load Preferences

If no EXTEND.md exists, run first-time setup first. Resolve and keep these defaults for later:

• default_author
• need_open_comment
• only_fans_can_comment

Step 1: Determine Input Type

Input	Action
.html file	Skip markdown conversion
.md file	Continue to markdown conversion
Plain text	Save as markdown first, then continue

For plain text:

1. Generate a 2-4 word kebab-case slug.
2. Save to post-to-wechat/yyyy-MM-dd/<slug>.md.
3. Continue as markdown input.

Step 2: Check mage-md-to-html

Skip this step if the input is already HTML.

Check whether mage-md-to-html is available. If it is available, read it and use it for markdown conversion. If not:

1. tell the user mage-md-to-html is not available
2. suggest installing mage-md-to-html
3. offer a fallback: continue only if the user provides HTML manually

Step 3: Convert Markdown To HTML

Skip if the input is HTML.

If theme is not already specified through CLI or preferences, ask for one:

• default
• grace
• simple

Then execute mage-md-to-html and capture:

• htmlPath
• title
• author
• summary
• contentImages

Step 4: Validate Metadata

Check:

• title
• summary
• author
• cover image

Fallback chain for author:

--author -> frontmatter author -> EXTEND.md default_author

Cover image fallback chain for API news articles:

1. CLI --cover
2. frontmatter coverImage / featureImage / cover / image
3. imgs/cover.png
4. first inline content image
5. if still missing, stop and ask the user for a cover

Step 5: Select Publish Method

Choose unless already fixed by CLI or preferences:

• api for faster draft creation
• browser for Chrome session based publishing

If API is selected, check for credentials in:

test -f .mage-skills/.env && rg "WECHAT_APP_ID" ".mage-skills/.env"
test -f "$HOME/.mage-skills/.env" && rg "WECHAT_APP_ID" "$HOME/.mage-skills/.env"

If missing, guide the user to obtain:

• WECHAT_APP_ID
• WECHAT_APP_SECRET

and save them to project-level or user-level .mage-skills/.env.

Step 6: Publish

API method:

npx -y bun ${SKILL_DIR}/scripts/wechat-api.ts <html_file> [--title <title>] [--summary <summary>] [--author <author>] [--cover <cover_path>]

If the same article has already been published to draft and publish-result.json contains a successful media_id, prefer updating that existing draft instead of creating a second draft entry.

Browser method:

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

For API drafts, ensure the final payload resolves:

• author
• need_open_comment
• only_fans_can_comment

Step 7: Report Completion

For API:

• input path
• method
• title
• summary
• inline image count
• comment settings
• resulting media_id
• whether the draft was created or updated
• draft management reminder

For browser:

• input path
• method
• title
• summary
• inline image count
• whether --submit was used
• whether manual review is still needed

Requirements Summary

• Browser mode requires Chrome and a reusable login session.
• API mode requires WECHAT_APP_ID and WECHAT_APP_SECRET.
• Article mode requires mage-md-to-html when the source is markdown or plain text.
• Image-text mode uses browser automation and image uploads.

Troubleshooting

Problem	Action
No API credentials	guide .mage-skills/.env setup
Browser not logged in	ask user to log in once with the isolated profile
Cover image missing	stop and request one before API publish
HTML paste fails	retry browser path or switch method
mage-md-to-html unavailable	ask user to install it or provide HTML manually