SuperAPI AI Directory

soia-media-publish-wechat-draft

General & other

View repository

Updated 10-16 08:46

About this skill

soia-media-publish-wechat-draft

Of the media content workflow'sOfficial Account publishing stage (publish): format the compose produced finished draft, validate it, and after confirmation push it into the WeChat Official Account drafts box.

Blueprint: an archived article in the vault about an Obsidian + AI WeChat Official Account formatting workflow—this skill is its practical implementation; do not write the real path of a personal vault into a public skill.

Customer-readable description

What this skill can do

Format the written article draft into inline-style HTML that complies with WeChat Official Account restrictions, and after mechanical validation passes, call the WeChat draft/add API to push it into the drafts box. This skill only creates drafts and never auto mass-sends.

Customer wants Skill will do Customer can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's main workflow, and execute the minimum reliable steps The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt.
Missing dependencies, permissions, configuration, or key Stop actions requiring external state and clearly state what is missing Install command, application address, configuration path, or questions requiring customer confirmation
Execution complete Summarize successes, skips, failures, file changes, and validation results A completion receipt that can be copied into a ticket/log

How the customer uses it

  1. Describe the goal in natural language and provide the necessary inputs: files, URLs, repos, workspace, proposal, vault, or platform account status.
  2. For actions that can be dry-run or previewed, give a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, ask the customer for confirmation first.

Dependencies and installation

Installation (recommended: install the entire domain plugin, installing all skills in this repository at once):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-media-content@soia

When only this one skill is needed, the npx route can be used. Note that the skill will fall into the shared source of truth ~/.agents/skills; if the plugin is installed at the same time, the same skill will appear as two indexes and each will drift, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-media-content-skills -g -a '*' -s soia-media-publish-wechat-draft -y

Configuration conventions:

~/.config/soia-skills/soia-media-publish-wechat-draft/config.yml
SOIA_MEDIA_PUBLISH_WECHAT_DRAFT_CONFIG_FILE=<custom-config-path>
  • If this skill does not need private configuration, you may skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is needed, it can only be placed in private config.yml, the process environment, or the provider's own login state, and must not be written into the repository, vault body, or logs.
  • Third-party skills can only declare dependencies and installation methods, and do not directly modify third-party skill files.

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。

Logs and completion receipt

Every execution must let the customer see the process and results. Minimum receipt format:

完成:<一句话说明本次完成了什么>。

日志摘要:
- started: <检查到的输入/配置/依赖,不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化:
- <绝对路径或“未改动文件”>

验证:
- <运行过的检查、命令或人工核对点>

问题与下一步:
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令;没有则写“无”>

Before writing: read the WeChat Official Account context

If the customer provides a personal manual, first read the WeChat Official Account reader and tone positioning in it, then execute in combination with the formatting rules below. If that file is absent or the WeChat Official Account definition is missing, fall back to a general WeChat Official Account tone.

Official Account publishing (main flow)

WeChat platform red lines (must comply)

The Official Account's built-in editor (web paste,draft/add API) will actively filter/strip large amounts of HTML/CSS syntax— once well-formatted HTML hits the red lines below, the styles will most likely disappear entirely after pasting or pushing. Before rendering, self-check against this list;scripts/render_wechat.py has been implemented accordingly,scripts/validate_wechat_html.py is a mechanical validator for this list (any hard violation directly exits 1).

What must not be done (prohibited; if present it will be eaten/stripped)

  • <div> — the WeChat editor does not recognize it; for block-level containers always use <section>(multi-line container) or <p>(single paragraph) instead.
  • class="..." / id="..." — whether copying and pasting or pushing via the API, it will be stripped; styles can only survive via inline style="" — layout-type CSS is not supported by the editor; use
  • position / float — layout-type CSS is not supported by the editor; use margin/padding/text-align and other flow layouts instead.
  • @media / @keyframes — responsive breakpoints and animation rules are discarded entirely; the Official Account body has neither breakpoints nor any use for animations.
  • CSS variable var(--x) usage and --x: ... declarations — custom properties are not supported; colors/sizes must be hard-coded literal values (this skill's alternative: theme colors are defined centrally as Python constants at the top of the rendering script, instead of CSS variables).
  • <style>...</style> blocks — embedded/external stylesheet rules never take effect; styles must be inlined one by one in each tag's style="" attribute.

What must be done this way (mandatory; otherwise styles will most likely be lost after pasting)

  • All styles are written inline in the style="" attribute, not relying on any selectors.
  • Every visible text node is wrapped with a <span style="..."> layer—the editor/copy-paste often picks up styles by "tag boundaries", and bare text (directly under <p>/<section>/<li> , not wrapped in another <span>layer) is most likely to lose styles when pasted. <code>/<pre> Monospace text inside is itself "displayed as-is", so wrapping it again is not mandatory.
  • Keep punctuation style consistent (Chinese body text is recommended to use full-width; code/English uses half-width) to avoid a messy mix of full-width and half-width.
  • Images: in the body, first use <img src="..."> placeholders; before actual publishing, the images must be uploaded to the WeChat material library and replaced with CDN URLs (scripts/publish.py handles this step); local-path/external-link images will most likely not display in the Official Account backend.
  • Code blocks: WeChat does not support real syntax-highlighting components; use an inline-styled <section> wrapper <code style="...font-family:monospace..."> to simulate the "code block" look of monospace font + background color.

Self-check order: first manually go through the "what must not be done" list above, then run validate_wechat_html.py for mechanical review— manual + script double insurance; if there are hard violations, fix the rendering result first, and only after passing (exit 0) proceed to the step of pushing to the draft box.

Layout rules: emphasis density model

Three levels; the further down, the "heavier" and the more the quantity must be controlled:

Level Purpose Markdown / Implementation Quantity within the piece
Anchor layer Headings, the most important judgment sentences in the whole text (golden lines) #/## Headings; conclusions that stand alone as sentences Whole piece ≤5 places (headings + golden lines combined)
Mark layer In-paragraph keyword/phrase highlighting to help readers skim **加粗**(theme color),==高亮==(red bold) 1–3 places per paragraph
Container layer Content blocks that need to break out of the body text visually Quote block → quote card, code block, image Triggered as needed; no hard upper limit, but do not overuse
  • The anchor layer "≤5 per article" is a hard constraint; headings and quote cards count together, not 5 each per type.
  • The markup layer follows L1/L2 from the original three-level emphasis:**...** is phrase-level emphasis (theme-color bold),==...== is conclusion/ warning/key-number-level emphasis (red bold); the two combined are 1–3 places per paragraph, to avoid the whole text looking like ad copy because everything is bold.
  • The container layer is triggered by content form, not to "make the visuals look richer"—only use a quote card when there is a quote, and only use a code block when there is code.
  • The total emphasis ratio (markup-layer text / full-text word count) is still recommended to be <15%. Background colors / boxes are prohibited (except for the container layer).
  • Article type: frontmatter workflow_type: tech(has code/tables) or editorial(plain text); render_wechat.py is currently a unified clean theme,render.py(early simplified version) retains the tech/editorial two styles.
  • Images: empty Alt → no caption is shown below the image; Alt with content → clearly state what is in the image (do not use meaningless words like "image" or "screenshot").

6-step process

  1. Check the frontmatter's workflow_type。
  2. Emphasis polishing: AI labels the full text according to the density model as ** / == / quote blocks, and verifies the anchor layer ≤5 and the markup layer 1–3 per paragraph.
  3. Render:scripts/render_wechat.py converts Markdown → inline-style HTML that complies with the "WeChat platform red lines".
  4. Validate:scripts/validate_wechat_html.py mechanically rechecks the red lines—if there are hard violations, first go back to the rendered result/ script to fix; only after passing (exit 0) can you proceed to the next step; warnings do not block, but it is recommended to clear them along the way.
  5. Before pushing to the draft box, first confirm: by default, confirm the style, cover, and publishing account before execution—explicitly invoking this skill, hitting workflow_type default configuration are only recommended inputs and do not constitute a reason to skip confirmation; the only skip condition is that the client's current statement explicitly says "push directly/no confirmation"—after skipping, the receipt must state the assumptions used this time. After confirmation passes, scripts/publish.py → call WeChat draft/add to create a draft (upload images to CDN, upload cover).
  6. After manual confirmation of publishing → scripts/archive.py mark as published, record the link, update the log.

Script specifications (scripts/)

  • render_wechat.py [--file <in.md>] [--output <out.html>](if --file is not passed, read stdin, if --output is not passed, print to stdout): the currently recommended renderer, using only tags/inline styles allowed by the WeChat platform red lines;**…** → theme-color bold,==…== → red bold,> quotes → quote cards, code blocks → inline style <section> simulation, wrapping each text node in <span>. The theme color is a Python constant at the top of the script, not a CSS variable.
  • validate_wechat_html.py [--file <html>] [--json](if --file is not passed, read stdin): mechanically validate the above "WeChat platform red lines", reporting each violation's line number + type; hard violations (div/class/id/ position/float/media/keyframes/css variables/<style> block) exit 1, clean exit 0; plain text nodes are downgraded to warning and do not block. Pure html.parser implementation, no third-party dependencies.
  • render.py <in.md> <out.html> [--style tech|editorial]: early simplified renderer (tech/ editorial dual style), does not perform redline validation/<span> wrapping, kept for scenarios that still need tech-style tables/code highlighting —after rendering with it, be sure to also run validate_wechat_html.py。
  • publish.py --article <md> --cover <png> [--dry-run]: render → upload images / cover to WeChat CDN → draft/add create draft. Credentials are read from the private config.yml 's env.WECHAT_APP_ID / env.WECHAT_APP_SECRET .
  • archive.py --article <md> --url <link>: set frontmatter to status: 已发布 + record date / link + append log.

Initial setup <1 hour (rules 15 min + AI-generated scripts 20 min + Skill docs 10 min), after that each article's formatting ≈ 0.

⚠️ Security rules (must follow)

  • Only create drafts, never auto mass-send—mass sending must be manually clicked by the user in the official account backend.
  • Credentials are stored in skill-specific private config.yml(WECHAT_APP_ID / WECHAT_APP_SECRET),not committed to Git。
  • You must first enable the development API in the developers.weixin.qq.com / mp backend and configure the IP whitelist.

How to obtain and configure the WeChat official account AppID / AppSecret

  • Entry point: WeChat Official Accounts Platform https://mp.weixin.qq.com,用该公众号绑定的**管理员微信扫码登录**。

  • Prerequisites:draft/add and other interfaces are only open toverified subscription/service accounts; unverified personal subscription accounts do not have permission for these interfaces, and calls will directly report something like 48001 api unauthorized。

  • Path to get AppID / AppSecret: log in to the backend → bottom of the left menu "Settings and Development" → "Development" → "Basic Configuration" (the old menu is "Development" → "Development Interface Management" → "Basic Configuration") → in the "Official Account Development Information" section on the page:

    • Developer ID (AppID): directly visible and copyable, corresponding to the WECHAT_APP_ID。
    • Developer Password (AppSecret): click "Reset", it is only displayed after the administrator confirms by scanning the QR code,only displayed this once, copy and save it on the spot, corresponding to WECHAT_APP_SECRET; resetting will immediately invalidate the old secret, and if it is still in use elsewhere it will be disconnected as well.
  • IP whitelist (critical, failure if missed): on the same "Basic Configuration" page there is an "IP whitelist"; you must add thepublic IP of the machine that actually calls the API, otherwise when exchanging for access_token it will report 40164 invalid ip. If running locally, first check the local machine's public IP (e.g. curl ifconfig.me), and remember to update it after changing networks.

  • Where to put it: secrets are only placed in the private config.yml, not in the vault, not in this open-source skill repository, and not in shell startup files.publish.py is already integrated with scripts/publish_env.py, and when run it willautomatically detect and load $SOIA_MEDIA_PUBLISH_WECHAT_DRAFT_CONFIG_FILE(or the compatible alias $SOIA_MEDIA_PUBLISH_ENV_FILE) as well as the default path ~/.config/soia-skills/soia-media-publish-wechat-draft/config.yml, and perform a read-only fallback for the old namespace,no manual source needed:

    # ~/.config/soia-skills/soia-media-publish-wechat-draft/config.yml
    env:
      WECHAT_APP_ID: "wx************"
      WECHAT_APP_SECRET: "********************************"
    
    # 直接跑,脚本自己会读私有 config.yml
    python3 scripts/publish.py --article xxx.md --cover xxx.png
    

    (when credentials are placed in a non-default path:SOIA_MEDIA_PUBLISH_WECHAT_DRAFT_CONFIG_FILE=/你的/路径/config.yml python3 scripts/publish.py ...。)

  • Self-check: after configuring, you can first have the AI "use these credentials to exchange for an access_token once to see if it works"; once it works, proceed to the main flow of render → validate → push to drafts.

Receipt after execution

After pushing the draft, tell the user: ① the draft is in the WeChat Official Account backend (which article, what style) ② remind them "after confirming it's correct, you manually send it to all" ③ after sending to all, come back and say so, then run archive.py archive. If it's just formatting or verification, also report the artifact location and verification results.

closure location

clip(收) → organize(整理) → distill(点) → compose(写) → ★publish-wechat-draft(公众号发)

upstream compose provides the finished draft; this skill is responsible for WeChat Official Account formatting + draft box delivery. Credentials and the manual gate of "manual sending to all" are controlled by the user.