WeChat Publisher With WeMD Render

intent

automate the full weChat public account publishing pipeline from markdown or plain text to live article. use this when you need to help write or publish 公众号 articles, create/update drafts, confirm and submit publishes, query publish results, list materials/drafts/published content, or manage rendering themes. the skill enforces a hard human confirmation gate before any publish action, handles local image upload and CDN substitution, renders markdown with 12 built-in or custom themes, and provides read-only asset queries. skip this if the task is menus, mass messaging, customer service, or analytics.

inputs

wechat credentials & setup:

• WECHAT_APPID (env var): public account app ID. required.
• WECHAT_APPSECRET (env var): public account app secret. required.
• access_token (auto-refreshed): bearer token for weChat API calls. expires every 7200 seconds. the skill auto-refreshes; no manual refresh needed.
• Node.js v18+ (runtime): required for WeMD markdown rendering. auto-installed on first run via setup.py.

article data (one required per publish attempt):

• title (string, required): article headline.
• author (string, required): byline.
• digest (string, required): short summary (weChat calls this "digest").
• content_markdown or content_markdown_path or content_text or content (string/path, required): article body. accept markdown, plain text, or file path.
• content_base_dir (string, optional): base directory for resolving relative image paths in body. defaults to cwd if omitted.
• thumb_image_path (string, local path, conditional): local cover image file. required if thumb_media_id not provided.
• thumb_media_id (string, conditional): weChat material ID of already-uploaded cover. required if thumb_image_path not provided.
• theme (string, conditional): rendering theme name (chinese or english id). required; user must specify or choose from list (see decision points).
• draft_media_id or media_id (string, optional): media ID of existing draft to update. omit for new draft.
• content_source_url (string, optional): original article source URL.
• need_open_comment (boolean, optional): enable comments. defaults to false.
• only_fans_can_comment (boolean, optional): restrict comments to subscribers only. defaults to false.

theme list (12 built-in + custom):

chinese name	english id	use case
默认	Default	generic, modern weChat green
学术论文	Academic-Paper	technical papers, research reports
极光玻璃	Aurora-Glass	product launches, creative content
包豪斯	Bauhaus	design, art, creative work
赛博朋克	Cyberpunk-Neon	tech, digital, AI topics
知识库	Knowledge-Base	tutorials, how-to docs
黑金奢华	Luxury-Gold	brand voice, deep-dive essays
莫兰迪森林	Morandi-Forest	lifestyle, slow reading
新粗野主义	Neo-Brutalism	trend pieces, edgy opinion
购物小票	Receipt	fun content, lists, retro vibes
落日胶片	Sunset-Film	stories, essays, film reviews
主题模板	Template	baseline layout reference

custom themes can be added via manage_themes.py with user-provided CSS (must use #wemd as root selector).

external connection: weChat public account API

• endpoint: https://api.weixin.qq.com/
• auth: OAuth2 via appid + appsecret, bearer token in Authorization header.
• scope: permanent material upload, draft management, publish, stats query.
• rate limit: 45 calls/min per appid. the skill does not batch or queue; hitting the limit will cause timeouts. see edge case handling.
• token expiry: 7200 seconds (2 hours). auto-refresh happens transparently.

procedure

step 1: validate inputs and ask for theme if missing.

• input: user-provided article data dict.
• check: is title, author, digest, body content, and cover (image or media_id) all present.
• check: is theme specified.
• if theme is missing, output the 12-theme table and ask user to choose by chinese or english name. wait for user response.
• if cover is missing (both thumb_image_path and thumb_media_id are null/empty), ask user to provide one.
• output: validated article dict with theme field populated.
• edge case: user says "default" or "no preference" → set theme to "Default".
• edge case: user provides invalid theme name → re-ask with theme list.

step 2: normalize article content (md rendering + image upload).

• input: article dict with validated content_markdown / content_markdown_path / content_text.
• call: python scripts/normalize_article.py --input article.json --theme <theme_id> --base-dir <content_base_dir>.
• internal flow:
  • read markdown or plain text from file or string.
  • pass to WeMD renderer with selected theme. output is inline-style html compatible with weChat.
  • scan html for local image references (relative or absolute paths). for each local image:
    • read file from disk.
    • call weChat permanent material upload api (POST /cgi-bin/material/add_material?type=image).
    • receive weChat media_id and cdn_url.
    • replace local path in html with cdn_url.
  • output: normalized article dict with content field as rendered html, all images replaced by cdn urls.
• edge case: image upload fails (file missing, weChat api error, network timeout) → log error, ask user to retry or skip image. do not silent-fail.
• edge case: markdown rendering produces invalid html → log warning, proceed with best-effort html.
• edge case: local image file is >5mb or >5000px dimension → log warning, attempt upload anyway (weChat will reject if over limit); report error to user.

step 3: upload cover image (if local path provided).

• input: normalized article dict with thumb_image_path set.
• check: is thumb_media_id already set (user provided pre-uploaded cover). if yes, skip this step.
• call: python scripts/upload_material.py --file <thumb_image_path>.
• internal flow:
  • POST to weChat permanent material upload api with image file.
  • receive media_id and cdn_url.
  • output: updated article dict with thumb_media_id field set.
• edge case: cover upload fails → log error, abort and ask user to retry or provide pre-uploaded media_id.
• edge case: cover file is missing, unreadable, or >5mb → log error, abort.

step 4: create or update draft.

• input: normalized article dict with all required fields, theme, content (html), thumb_media_id.
• check: is draft_media_id / media_id set. if yes, update mode. else create mode.
• call: python scripts/upsert_draft.py --input article.json [--update] (add --update flag if updating).
• internal flow:
  • call weChat draft api: POST /cgi-bin/draft/add (create) or POST /cgi-bin/draft/update (update).
  • request body includes title, author, digest, content (html), thumb_media_id, comment flags.
  • receive draft media_id from response.
  • generate preview url: construct weChat preview link (internal format; script handles this).
  • output dict: { media_id, preview_url, title, author, digest, theme }.
• output: show user the draft summary (title, digest, theme, media_id, preview link).
• edge case: weChat api rejects draft (malformed html, missing required field) → log api error, ask user to fix and retry. do not auto-fix.
• edge case: draft already exists but media_id not provided → warn user, ask for media_id to update or create new.

step 5: wait for human confirmation.

• input: draft media_id and preview url.
• output: display preview link to user. instruct user to click, review content, and reply with "确认发布" (confirm publish) or similar affirmative phrase.
• acceptance criteria: user must explicitly say yes (chinese: 确认发布, 可以发布, 批准发布, etc.; english: confirm, approve, publish, etc.). silent approval or ambiguous replies are rejected.
• timeout: no hard timeout. hold until user responds.
• edge case: user says "edit" or "cancel" → abort publish flow, ask user to modify and restart.
• edge case: preview link expires (weChat preview tokens are session-scoped) → regenerate link and re-ask for confirmation.

step 6: submit publish.

• input: draft media_id, confirmed flag set by step 5.
• call: python scripts/submit_publish.py --draft-id <media_id> --confirmed.
• internal flow:
  • POST to weChat publish api: POST /cgi-bin/freepublish/submit?access_token=...
  • request body: { media_id, index (default 0 for single-article publish) }.
  • receive publish_id from response.
  • output: { publish_id, draft_media_id, publish_time (utc timestamp) }.
• output: show user publish_id and next step (query status in ~30s).
• edge case: weChat api rejects draft as unpublishable (e.g., draft expired, duplicate title) → log error, suggest user check draft and retry from step 4.
• edge case: network timeout → retry once; if still fails, report error and ask user to check weChat backend manually.

step 7: query publish status.

• input: publish_id from step 6.
• call: python scripts/query_publish_status.py --publish-id <publish_id>.
• internal flow:
  • poll weChat status api: GET /cgi-bin/freepublish/getpublishstatus?access_token=...
  • weChat returns: { type (0=draft, 1=published, 2=deleted), state (0=unfinished, 1=success, 2=failed), article (array of article metadata if published) }.
  • if state=1 (success), extract article url, title, publish time, view count (if available).
  • if state=2 (failed), extract error reason.
  • output: { publish_id, status (success/failed/pending), article_url (if published), error_reason (if failed), view_count (if published and available) }.
• output: display to user. if success, show article url and congratulate. if failed, show error and suggest retry.
• edge case: publish_id not found on weChat backend → likely expired (weChat holds publish records ~30 days). inform user and suggest checking weChat editor.
• edge case: status is pending (state=0) → re-query after 10-30s. do not hammer api.
• edge case: view_count is 0 or unavailable → this is normal (stats lag behind publish by hours); do not report as error.

step 8: query assets (read-only).

• input: query type (materials-count, drafts-list, published-list).
• call: python scripts/query_assets.py <type> [--no-content].
• internal flow:
  • materials-count: GET /cgi-bin/material/get_materialcount → returns total counts of images, voice, video, news items.
  • drafts-list: GET /cgi-bin/draft/getall → returns list of all draft metadata. include --no-content to omit body html (faster, smaller payload).
  • published-list: GET /cgi-bin/material/batchget_material?type=news → returns list of all published article metadata. include --no-content to omit body html.
  • output: list of items with metadata (title, author, digest, create_time, thumb_url, etc.). if --no-content set, body field is empty.
• output: display count or list to user in table format.
• edge case: no items found → return empty list, not error.
• edge case: weChat api rate limit hit → log error, ask user to retry in 1-2 minutes.

step 9: manage custom themes (add/list/delete).

• input: action (add, list, delete), theme metadata.
• call: python scripts/manage_themes.py <action> [--cn <name> --en <id> --css-file <path> | --name <name>].
• internal flow:
  • add: user provides css file (plain text, #wemd root selector). agent asks user to confirm theme name (chinese + english id). script stores theme in local config (~/.wemd_themes.json or similar). output: theme saved.
  • list: script reads local config, displays all 12 built-in + custom themes in table format.
  • delete: user specifies theme name. script checks if theme is custom (built-in themes cannot be deleted). removes from config. output: theme deleted or error if built-in.
• output: confirmation message.
• edge case: css file is missing or malformed → log error, abort add.
• edge case: theme name conflicts with built-in → warn user, ask for different name.
• edge case: user tries to delete built-in theme → reject with message "cannot delete built-in theme".

decision points

if user has not specified a theme:

• output the 12-theme list (table or bullet points).
• ask user to pick by chinese name or english id.
• wait for response.
• else (user specified theme): validate theme name exists in built-in + custom list. if not, ask user to re-pick or create custom.

if user provides "default" or says "no preference":

• set theme to "Default" (english id).
• proceed without re-asking.

if cover image path is local:

• upload via upload_material.py to weChat permanent material api.
• replace thumb_image_path with thumb_media_id in article dict.
• else (user provided thumb_media_id): skip upload, use provided media_id as-is.

if draft_media_id / media_id is set:

• use weChat draft update api (upsert mode).
• else (no media_id): use weChat draft create api.

if user says anything other than explicit "确认发布" / "confirm" / "approve" / "publish":

• reject confirmation.
• re-prompt user to click preview link and confirm, or edit and restart.

if image upload fails (step 2 or 3):

• log error and filename.
• ask user: retry, skip image, or abort.
• if abort: stop publish flow.
• if skip: continue with missing image (weChat preview may show broken image; user will see in step 5).
• if retry: repeat upload step.

if publish api rejects draft:

• log weChat error code + message.
• suggest user check draft validity (no prohibited content, no duplicate title, etc.).
• ask user to review in weChat editor or restart from step 4.

if publish status query returns pending:

• re-query after 10-30s (do not block user; offer async callback).
• if still pending after 3 retries, tell user to check weChat backend or re-query later.

if theme name provided but not found in list:

• ask user to confirm spelling or pick from the display list.
• if user insists on custom theme, redirect to step 9 (manage_themes add).

output contract

success case: publish complete

• format: plaintext summary + structured data.
• example:

  ✓ article published
  title: 2026 AI 工具盘点
  author: Bingo
  theme: Luxury-Gold
  article_url: https://mp.weixin.qq.com/s/...
  publish_time: 2026-01-15 14:32 UTC
  draft_id: TnhkZ9HGMxOYETms_33Ct...
  publish_id: 123456789
  

success case: draft created (waiting for confirmation)

• format: plaintext summary + preview link.
• example:

  ✓ draft created
  title: 2026 AI 工具盘点
  digest: 深度盘点。
  theme: Luxury-Gold
  draft_id: TnhkZ9HGMxOYETms_33Ct...
  preview: http://mp.weixin.qq.com/s?...
  next: review content at preview link, then reply "确认发布"
  

success case: asset query

• format: table or list.
• example:

  ✓ drafts (3 total)
  1. "Q4 营收报告" | author: Finance | created: 2026-01-10
  2. "产品路线图" | author: Product | created: 2026-01-12
  3. "团队招聘启事" | author: HR | created: 2026-01-14
  

error case

• format: plaintext error summary + actionable next step.
• example:

  ✗ draft creation failed
  reason: weChat api error 40001 (invalid access_token)
  next: check WECHAT_APPID and WECHAT_APPSECRET env vars are set correctly, then retry
  

file location (if applicable):

• local article json: ~/.wemd_articles/<timestamp>_<title_slug>.json (for caching).
• local themes config: ~/.wemd_themes.json.
• logs: ~/.wemd_logs/ (one log file per publish attempt, named by publish_id or timestamp).

outcome signal

user knows the skill worked when:

1. theme was missing and asked for: user sees numbered or bullet list of 12 themes. user picks one, skill confirms and proceeds.

2. draft created: user sees draft_id, preview link, and instructions to review. user can click preview, see formatted article with applied theme (colors, fonts, spacing, images). no errors logged.

3. confirmation gate triggered: user sees explicit message asking for "确认发布" or similar. any ambiguous reply (e.g., "ok", "好的") is rejected and user is re-prompted. only explicit yes is accepted.

4. draft updated: if updating existing draft, user sees "draft updated" message with new preview link.

5. publish submitted: user sees publish_id and article_url (or "check status in 30s" if not immediately available). no weChat api errors.

6. publish status queried: user sees final status (published, failed, pending) with article url or error reason. view count (if available) is shown.

7. assets listed: user sees non-empty table of drafts/published articles or count of materials. no api timeout.

8. custom theme added: user provides css file, agent asks user to confirm name, user says yes, script outputs "theme saved". theme appears in list on next list query.

9. images uploaded and substituted: article preview shows images rendered inline with cdn urls (weixin-friendly image proxy). no broken image placeholders (unless user skipped upload).

10. credentials never exposed: no appid, appsecret, access_token, or media_ids appear in user-visible output. internal logs are redacted.

credits: original author not declared. enriched for Implexa quality standards.