MD to WeChat

Use md2wechat when the user wants to:

• convert Markdown into WeChat Official Account HTML
• inspect resolved article metadata, readiness, and publish risks before conversion
• generate a local preview artifact or upload article drafts
• inspect live capabilities, providers, themes, and prompts
• generate covers, infographics, or other article images
• create image posts
• write in creator styles or remove AI writing traces

Intent Routing

Choose the command family before doing any publish action:

• Use convert / inspect / preview when the user wants a standard WeChat article draft (news), HTML conversion, article metadata, article preview, or a draft that needs --cover.
• Use create_image_post when the user says 小绿书, 图文笔记, 图片消息, newspic, 多图帖子, or asks to publish an image-first post rather than an article HTML draft.
• Do not route 小绿书 / 图文笔记 requests to convert --draft just because the user also has a Markdown article. A Markdown file can still be the image source for create_image_post -m article.md.
• Treat convert --draft and create_image_post as different publish targets, not interchangeable command variants.

Defaults And Config

• Assume md2wechat is already available on PATH.
• Draft upload and publish-related actions require WECHAT_APPID and WECHAT_SECRET.
• Image generation may require extra provider config in ~/.config/md2wechat/config.yaml.
• convert defaults to api mode unless the user explicitly asks for --mode ai.
• Check config in this order:
  1. ~/.config/md2wechat/config.yaml
  2. environment variables such as MD2WECHAT_BASE_URL
  3. project-local md2wechat.yaml, md2wechat.yml, or md2wechat.json
• If the user asks to switch API domain, change api.md2wechat_base_url or MD2WECHAT_BASE_URL.
• Treat live CLI discovery output as the source of truth. Do not guess provider names, theme names, or prompt names from repository files alone.

Discovery First

Run these before selecting a provider, theme, or prompt:

md2wechat version --json
md2wechat capabilities --json
md2wechat providers list --json
md2wechat themes list --json
md2wechat prompts list --json
md2wechat prompts list --kind image --json
md2wechat prompts list --kind image --archetype cover --json

Inspect a specific resource before using it:

md2wechat providers show openrouter --json
md2wechat themes show autumn-warm --json
md2wechat prompts show cover-default --kind image --json
md2wechat prompts show cover-hero --kind image --archetype cover --tag hero --json
md2wechat prompts show infographic-victorian-engraving-banner --kind image --archetype infographic --tag victorian --json
md2wechat prompts render cover-default --kind image --var article_title='Example' --json

When choosing image presets, prefer the prompt metadata returned by prompts show --json, especially primary_use_case, compatible_use_cases, recommended_aspect_ratios, and default_aspect_ratio.

Core Commands

Configuration:

• md2wechat config init
• md2wechat config show --format json
• md2wechat config validate

Conversion:

• md2wechat inspect article.md
• md2wechat preview article.md
• md2wechat convert article.md --preview
• md2wechat convert article.md -o output.html
• md2wechat convert article.md --draft --cover cover.jpg
• md2wechat convert article.md --mode ai --theme autumn-warm --preview
• md2wechat convert article.md --title "新标题" --author "作者名" --digest "摘要"

Image handling:

• md2wechat upload_image photo.jpg
• md2wechat download_and_upload https://example.com/image.jpg
• md2wechat generate_image "A cute cat sitting on a windowsill"
• md2wechat generate_image --preset cover-hero --article article.md --size 2560x1440
• md2wechat generate_cover --article article.md
• md2wechat generate_infographic --article article.md --preset infographic-comparison
• md2wechat generate_infographic --article article.md --preset infographic-dark-ticket-cn --aspect 21:9
• md2wechat generate_infographic --article article.md --preset infographic-handdrawn-sketchnote

Drafts and image posts:

• md2wechat create_draft draft.json
• md2wechat test-draft article.html cover.jpg
• md2wechat create_image_post --help
• md2wechat create_image_post -t "Weekend Trip" --images photo1.jpg,photo2.jpg
• md2wechat create_image_post -t "Travel Diary" -m article.md
• echo "Daily check-in" | md2wechat create_image_post -t "Daily" --images pic.jpg
• md2wechat create_image_post -t "Test" --images a.jpg,b.jpg --dry-run

Writing and humanizing:

• md2wechat write --list
• md2wechat write --style dan-koe
• md2wechat write --style dan-koe --input-type fragment article.md
• md2wechat write --style dan-koe --cover-only
• md2wechat write --style dan-koe --cover
• md2wechat write --style dan-koe --humanize --humanize-intensity aggressive
• md2wechat humanize article.md
• md2wechat humanize article.md --intensity aggressive
• md2wechat humanize article.md --show-changes
• md2wechat humanize article.md -o output.md

Article Metadata Rules

For convert, metadata resolution is:

• Title: --title -> frontmatter.title -> first Markdown heading -> 未命名文章
• Author: --author -> frontmatter.author
• Digest: --digest -> frontmatter.digest -> frontmatter.summary -> frontmatter.description

Limits enforced by the CLI:

• --title: max 32 characters
• --author: max 16 characters
• --digest: max 128 characters

Draft behavior:

• If digest is still empty when creating a draft, the draft layer generates one from article HTML content with a 120-character fallback.
• Creating a draft requires either --cover or --cover-media-id.
• --cover is a local image path contract for article drafts. --cover-media-id is for an existing WeChat permanent cover asset. Do not assume a WeChat URL or mmbiz.qpic.cn URL can be reused as thumb_media_id.
• inspect is the source-of-truth command for resolved metadata, readiness, and checks.
• preview v1 writes a standalone local HTML preview file. It does not start a workbench, write back to Markdown, upload images, or create drafts.
• convert --preview is still the convert-path preview flag; it is not the same thing as the standalone preview command.
• preview --mode ai is degraded confirmation only; it must not be treated as final AI-generated layout.
• --title / --author / --digest affect draft metadata, not necessarily visible body HTML.
• Markdown images are only uploaded/replaced during --upload or --draft, not during plain convert --preview.

Agent Rules

• Start with discovery commands before committing to a provider, theme, or prompt.
• Route by publish target first: article draft => convert; image post / 小绿书 / newspic => create_image_post.
• Prefer the confirm-first flow for article work: inspect -> preview -> convert / --draft.
• If the user says 小绿书, 图文笔记, 图片消息, newspic, or asks for a multi-image post, prefer create_image_post even when the source content lives in Markdown.
• Prefer generate_cover or generate_infographic over a raw generate_image "prompt" call when a bundled preset fits the task.
• Validate config before any draft, publish, or image-post action.
• If draft creation returns 45004, check digest/summary/description before assuming the body content is too long.
• If the user asks for AI conversion or style writing, be explicit that the CLI may return an AI request or prompt rather than final HTML or prose unless the workflow completes the external model step.
• Do not perform draft creation, publishing, or remote image generation unless the user asked for it.

References

• Theme examples and visual guidance: references/themes.md
• WeChat draft and image-post API details: references/wechat-api.md
• Markdown image syntax and AI placeholders: references/image-syntax.md
• HTML conversion notes: references/html-guide.md
• Writer-style workflow: references/writing-guide.md
• Humanizer workflow: references/humanizer.md

Safety And Transparency

• Reads local Markdown files and local images.
• May download remote images when asked.
• May call external image-generation services when configured.
• May upload HTML, images, drafts, and image posts to WeChat when the user explicitly requests those actions.