zm-wechat-draft-publish-verify

intent

use this skill to publish a prepared wechat official account article (markdown or html) into the draft box. the skill converts input to wechat-compatible html, uploads cover images, calls zm-md2wechat-conversion-tool create_draft, then forces backend verification via wechat's draft/get api. do this when you need reliable draft creation with proof that the article actually exists in wechat's backend, not just local preview artifacts. do not use this for editorial review, topic selection, or ai trace decisions.

inputs

article source (one of)

• article.html (wechat-compatible html, preferred)
• article.md (markdown, will be converted)

cover image

• cover.png, cover.jpg, or equivalent (required, for upload_image)

metadata (required, passed to publish.sh or draft.json)

• title (string, ≤32 chars recommended, required)
• author (string, ≤16 chars recommended, required)
• digest (string, ≤120-128 chars recommended, required)

optional package structure

wechat_package/
  article.html
  cover.png
  images/
  publish-checklist.md

external: wechat official account credentials

• env var: WECHAT_APPID (app id of wechat official account)
• env var: WECHAT_SECRET (app secret, do not log or expose)
• config file: ~/.config/zm-md2wechat-conversion-tool/config.yaml (yaml with wechat.appid and wechat.secret keys)
• network: current public ip must be in wechat official account ip allowlist (check wechat backend)

external: zm-md2wechat-conversion-tool

• bin: zm-md2wechat-conversion-tool (cli tool, must be in $PATH)
• bin: python3 (required by tool)
• setup: run scripts/setup.sh from this skill or install directly via your package manager

external: wechat api access

• api endpoint: wechat's draft/get (called by zm-md2wechat-conversion-tool internally or by verification step)
• rate limit: wechat api has standard rate limits per appid, typically 45 req/min for draft/get
• token expiry: access token expires hourly, tool handles refresh automatically

procedure

step 1: validate config before any publish attempt

input: wechat credentials (env vars or config file) action: run zm-md2wechat-conversion-tool config validate --json output: json result with success: true or error details on failure: stop. do not proceed to draft creation. report config issue (invalid appid, missing secret, malformed yaml, unreachable wechat api).

step 2: inspect article if markdown input

input: article.md action: run zm-md2wechat-conversion-tool inspect article.md --json output: article.zm-md2wechat-conversion-tool-inspect.json (metadata, frontmatter, any ai markers) note: only for markdown. skip if input is already html.

step 3: preview article if markdown input

input: article.md action: run zm-md2wechat-conversion-tool preview article.md --json output: article.zm-md2wechat-conversion-tool-preview.json (local preview, not backend proof) note: local artifact only. do not report success based on this. skip if input is html.

step 4: convert markdown to html if needed

input: article.md action: run zm-md2wechat-conversion-tool convert article.md --output article.html --json output: article.html (wechat-compatible html), article.zm-md2wechat-conversion-tool-convert.json (conversion metadata) note: skip if input is already html. check that convert did not return CONVERT_AI_REQUEST_READY (that is an action-required state, not success).

step 5: upload cover image

input: cover.png (or jpg), wechat credentials action: run zm-md2wechat-conversion-tool upload_image cover.png --json output: article.zm-md2wechat-conversion-tool-cover-upload.json (contains thumb_media_id) on failure: stop. report upload failure (invalid ip, expired token, image rejected). critical: media_id alone is a submission receipt. it does not mean the draft is in the backend yet.

step 6: generate draft json payload

input: title, author, digest, article.html, thumb_media_id (from step 5) action: create article.zm-md2wechat-conversion-tool-create-draft.json with structure:

{
  "articles": [
    {
      "title": "<title>",
      "author": "<author>",
      "digest": "<digest>",
      "content": "<section style=\"...\">...</section>",
      "thumb_media_id": "<media_id>",
      "show_cover_pic": 0
    }
  ]
}

validation: articles array not empty, title present, content present, thumb_media_id present, no local paths leaked (no <home>/, no content-factory/ in content). output: article.zm-md2wechat-conversion-tool-create-draft.json

step 7: call create_draft

input: article.zm-md2wechat-conversion-tool-create-draft.json, wechat credentials action: run zm-md2wechat-conversion-tool create_draft article.zm-md2wechat-conversion-tool-create-draft.json --json output: article.zm-md2wechat-conversion-tool-create-draft-result.json (contains media_id if successful) on failure: stop. report create_draft error (invalid payload, content rejected, wechat backend error). critical: command success does not equal task success. proceed to step 8 unconditionally.

step 8: verify draft exists in wechat backend (mandatory)

input: media_id (from step 7 result) action: call wechat draft/get api with the media_id to retrieve the full draft output: article.zm-md2wechat-conversion-tool-create-draft-verify.json (contains full draft from wechat backend) validation checklist:

• draft really exists (api returned 200, no 40007 "invalid media_id")
• title matches expected input
• author matches expected input
• thumb_media_id present and matches uploaded cover
• content present and contains expected wechat html (inline styles, no local paths)
• show_cover_pic correct (0 or 1)
• if markdown was input, verify final html is real generated html (not CONVERT_AI_REQUEST_READY payload)
• if article has body images, spot-check that at least one image is present (not stripped) on any check failure: report verification failure with exact blocker. do not report success.

decision points

if input is markdown:

• run steps 2, 3, 4 (inspect, preview, convert)
• verify step 4 convert result is not CONVERT_AI_REQUEST_READY (if so, stop and report "ai conversion request ready, not draft created")

else if input is html:

• skip steps 2, 3, 4
• proceed directly to step 5 (upload cover)

if step 5 (upload_image) fails:

• check error code
• if errcode=40164 invalid ip: report "current ip not in wechat allowlist, add to backend settings"
• if errcode=40125 invalid appsecret: report "invalid appsecret in config.yaml"
• if errcode=40001 invalid access_token: report "token expired or refresh failed, retry"
• otherwise: report upload failure with full error response

if step 7 (create_draft) succeeds but step 8 (draft/get) fails:

• if draft/get returns errcode=40007 invalid media_id: treat as unverified (backend did not actually persist)
• if draft/get times out or returns server error: treat as unverified, do not retry more than 3 times
• if verification checks (title mismatch, content missing, etc.) fail: report exact mismatch, do not claim success

if rate limit is hit during step 8 (draft/get):

• wechat api typically allows 45 req/min for draft/get per appid
• wait 60 seconds, retry up to 2 times
• if still rate-limited, report and stop

if ai mode was upstream:

• verify that the html in the final draft is real generated html (check for wechat-compatible tags, inline styles)
• do not accept CONVERT_AI_REQUEST_READY as proof of draft creation
• the publish-ready payload is only a staging artifact, not the final content

output contract

success case: all of the following files exist next to the article, and step 8 verification passed

article.zm-md2wechat-conversion-tool-cover-upload.json
article.zm-md2wechat-conversion-tool-create-draft.json
article.zm-md2wechat-conversion-tool-create-draft-result.json
article.zm-md2wechat-conversion-tool-create-draft-verify.json

failure case: same files written up to the failure point, plus error details in the final output file (verify.json or result.json depending on where failure occurred)

final source of truth: article.zm-md2wechat-conversion-tool-create-draft-verify.json (contains full draft from wechat backend, or verification failure details)

data format: all artifacts are json (--json flag used in all cli calls)

file location: all artifacts written to same directory as input article

markdown intermediate artifacts (if input was markdown):

article.zm-md2wechat-conversion-tool-inspect.json
article.zm-md2wechat-conversion-tool-preview.json
article.zm-md2wechat-conversion-tool-convert.json
article.html (converted output)

outcome signal

user knows it worked when:

• the script exits with status 0 (success)
• article.zm-md2wechat-conversion-tool-create-draft-verify.json exists and contains a success: true or verified: true field
• the verify.json shows the draft title, author, digest, and cover all match the input
• the verify.json shows content field contains inline-styled wechat html (not plain text, not local paths)
• the user can open the wechat official account backend and see the draft in the draft list with the correct title, cover, and author

user knows it failed when:

• the script exits with non-zero status
• the final artifact (verify.json or result.json) contains an error field with a specific blocker (e.g., "invalid ip", "invalid appsecret", "draft media_id not found in backend", "title mismatch")
• no draft appears in the wechat official account draft list
• the verify.json is missing or does not contain the expected title/author/cover