The PKM loop'sOfficial Account publishing stage (publish): typeset the finished draft produced by compose , validate it, and after confirmation push it into the WeChat Official Account draft box.
Blueprint: an archived article in the vault about an Obsidian + AI Official Account typesetting workflow—this skill is its practical implementation; do not write the real paths of a personal vault into a public skill.
Client-readable description
What this skill can do
Typeset a finished 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 draft box. This skill only creates drafts and never auto mass-sends.
| What the client wants | What the skill will do | What the client can see |
|---|---|---|
| Complete the work covered by this skill | Read the user request, necessary context, and this skill's main workflow, and execute the minimal reliable steps | The client will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt. |
| Missing dependencies, permissions, configuration, or keys | Stop actions that require external state and clearly state what is missing | Install commands, application addresses, configuration paths, or questions requiring client 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 client uses it
- State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
- The Agent first determines whether this skill is triggered, then checks dependencies, configuration, permissions, and risky actions.
- For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, seek client confirmation first.
- After execution, verify the real output; do not substitute "looks successful" for evidence.
- The final reply must give the client a visible summary: what was done, log summary, file changes, issues, and next steps.
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-publish-wechat-draft -y
Configuration conventions:
~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-publish-wechat-draft/config.yml
SOIA_PKM_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 may only be placed in a private
config.yml, the process environment, or the provider's own login state; it must not be written into the repository, vault body, or logs. - Hard dependencies, optional dependencies, and third-party skill relationships must be based on the "dependencies / prerequisites / resources / boundaries" description following this
SKILL.md; if it is not clearly written, first supplement the description or ask the client, and do not guess. - Third-party skills may only declare dependencies and installation methods; do not directly modify third-party skill files.
Logs and completion receipt
Every execution must let the client see the process and results. Minimum receipt format:
完成:<一句话说明本次完成了什么>。
日志摘要:
- started: <检查到的输入/配置/依赖,不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>
文件变化:
- <绝对路径或“未改动文件”>
验证:
- <运行过的检查、命令或人工核对点>
问题与下一步:
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令;没有则写“无”>
Before writing: read the Official Account context
If the client provides a personal spec document, first read the official account reader and tone positioning in it, then execute in combination with the formatting rules below. If that file is absent or the official account definition is missing, fall back to the generic official account tone.
Official account publishing (main workflow)
WeChat platform red lines (must comply)
The official account's built-in editor (web paste,draft/add interface) will actively filter/strip a large amount of HTML/CSS syntax — once formatted HTML hits the red lines below, the styles will most likely vanish entirely after pasting or pushing. Before rendering, self-check against this list;scripts/render_wechat.py is already implemented according to this,scripts/validate_wechat_html.py
and is the mechanical validator for this list (a hard violation exits 1 directly).
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 by copy-paste or API push, it will be stripped; styles can only survive via inlinestyle="".position/float— layout-type CSS is not supported by the editor; usemargin/padding/text-alignand 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 written as literal values (this skill's alternative: theme colors are defined centrally as Python constants at the top of the rendering script, rather than CSS variables). <style>...</style>as a whole block — embedded/external stylesheet rules never take effect; styles must be inlined one by one on the tag'sstyle="".
Must do this (mandatory, otherwise styles will most likely be lost after pasting)
- All styles are written inline in the
style=""attribute, without relying on any selectors. - Every visible text node is wrapped in a layer of
<span style="...">— the editor/copy-paste often takes styles by "tag boundaries"; bare text (directly attached under<p>/<section>/<li>, without another layer of<span>) is the most likely to lose styles when pasted.<code>/<pre>The monospaced text inside is itself "displayed as-is" and is not forced to be wrapped again. - Punctuation style is unified (Chinese body text is recommended to use full-width, code/English uses half-width), to avoid mixed full-width and half-width looking messy.
- Images: in the body first use
<img src="...">as a placeholder; before actually publishing, the image must be uploaded to the WeChat asset library and replaced with a CDN URL (scripts/publish.pyhandles this step); local path/external link images will most likely not display in the official account backend. - Code blocks: WeChat does not support true syntax highlighting components; use an inline-styled
<section>to wrap a layer<code style="...font-family:monospace...">to simulate the "code block" look of monospaced font + background color.
Self-check order: first manually go through the "must not do" list above, then run validate_wechat_html.py for mechanical review —
manual + script double insurance; if there is a hard violation, first fix the rendering result, and only after passing (exit 0) proceed to the step of pushing to the drafts box.
Formatting 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 length |
|---|---|---|---|
| Anchor layer | Headings, the most important judgment sentences (golden lines) of the whole text | #/## Heading; standalone conclusion sentence |
Whole piece ≤5 places (headings + golden sentences combined) |
| Markup layer | Highlight keywords/phrases within paragraphs 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 | Blockquote → golden sentence card, code block, image | Triggered as needed, no hard upper limit but don't overuse |
- The anchor layer "whole piece ≤5 places" is a hard constraint; headings and golden sentences count together, not 5 each.
- The markup layer follows the 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 piece looking like ad copy from being all bold. - The container layer is triggered by content form, not to "pad out visual richness"—only use a golden sentence card when there's a quote, only use a code block when there's code.
- Total emphasis ratio (markup layer text volume / total word count) is still recommended to be <15%. Background colors / boxes are forbidden (container layer excepted).
- Article type: frontmatter
workflow_type: tech(has code/tables) oreditorial(plain text);render_wechat.pyis currently a unified concise theme,render.py(early simplified version) retains the tech/editorial two styles. - Images: Alt empty → no caption shown below the image; Alt has content → write clearly what's in the image (don't use uninformative words like "image" or "screenshot").
6-step process
- Check the frontmatter's
workflow_type。 - Emphasis polishing: AI marks the whole text with
**/==/ blockquotes according to the density model, verifying anchor layer ≤5 and markup layer 1–3 per paragraph. - Render:
scripts/render_wechat.pyconverts Markdown → inline-style HTML that complies with the "WeChat platform red lines". - Validate:
scripts/validate_wechat_html.pymechanically rechecks the red lines—if there are hard violations, first go back to the render result/ script to fix; only after passing (exit 0) can you proceed to the next step; warnings don't block, but it's recommended to clear them along the way. - Confirm before pushing to drafts: by default, confirm the style, cover, and publishing account before execution—explicitly invoking this skill,
hitting
workflow_typedefault configuration, are all just recommended inputs and do not constitute a reason to skip confirmation; the only skip condition is when the client's current sentence explicitly says "push directly/no need to confirm"; after skipping, state the assumptions used this time in the receipt. After confirmation passes,scripts/publish.py→ call WeChatdraft/addto create a draft (upload images to CDN, upload cover). - After manual confirmation of publishing →
scripts/archive.pymark as published, record the link, update the log.
Script specs (scripts/)
render_wechat.py [--file <in.md>] [--output <out.html>](if--fileis not passed, read stdin; if--outputis 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,>quote → golden sentence card, code block → 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--filethen read stdin): mechanically validate the "WeChat platform red lines" above, report each violation's line number + type; hard violations (div/class/id/ position/float/media/keyframes/css variables/<style>blocks) exit 1, clean exit 0; bare text nodes are downgraded to warnings and do not block. Purehtml.parserimplementation, no third-party dependencies.render.py <in.md> <out.html> [--style tech|editorial]: early simplified renderer (tech/ editorial dual style), no red-line validation/<span>wrapper, kept for scenarios that still need tech-style tables/code highlighting —after rendering with it, before official publishing you must also first runvalidate_wechat_html.py。publish.py --article <md> --cover <png> [--dry-run]: render → upload images / cover to WeChat CDN →draft/addcreate draft. Credentials are read from the privateconfig.yml'senv.WECHAT_APP_ID/env.WECHAT_APP_SECRET.archive.py --article <md> --url <link>: set frontmatter tostatus: 已发布+ record date / link + append log.
Initial setup < 1 hour (rules 15 min + AI-generated script 20 min + Skill docs 10 min), afterward 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 a skill-specific private
config.yml(WECHAT_APP_ID/WECHAT_APP_SECRET),Do not commit to Git。 - You must first enable the development API at developers.weixin.qq.com / the mp backend, and configure the IP whitelist.
How to obtain and configure the WeChat official account AppID / AppSecret
-
Entry: WeChat official platform https://mp.weixin.qq.com,用该公众号绑定的**管理员微信扫码登录**。
-
Prerequisites:
draft/addand other interfaces are only available toverified subscription accounts/service accountsopen; unverified personal subscription accounts do not have permission for these interfaces, and calls will directly return something like48001 api unauthorized。 -
Path to get AppID / AppSecret: log in to the backend → bottom of the left menu "Settings and Development" → "Development" → "Basic Configuration" (in the old menu it's "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 following
WECHAT_APP_ID。 - Developer Password (AppSecret): click "Reset", and it is only shown after the administrator scans the QR code to confirm,only shown this one time, 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 cut off as well.
- Developer ID (AppID): directly visible and copyable, corresponding to the following
-
IP whitelist (critical, failure is guaranteed if missed): on the same "Basic Configuration" page there is "IP Whitelist"; you must add the actual machine calling the API'spublic IP to it, otherwise when exchanging for an 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.pyis already integrated withscripts/publish_env.py, and when run it willautomatically detect and load$SOIA_PKM_PUBLISH_WECHAT_DRAFT_CONFIG_FILE(or the compatible alias$SOIA_PKM_PUBLISH_ENV_FILE) as well as the default path~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-publish-wechat-draft/config.yml,no need to manually source:# ~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-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_PKM_PUBLISH_WECHAT_DRAFT_CONFIG_FILE=/你的/路径/config.yml python3 scripts/publish.py ...。) -
Self-check: After configuring it, you can first have the AI "use this credential 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.
Post-execution receipt
After pushing the draft, tell the user: ① the draft is in the official account backend (which article, what style) ② remind them "after confirming it is correct, you manually send it to all" ③ after sending to all, come back and say so, then run archive.py archive. If it is only formatting or validation, also report the artifact location and validation result.
Closed-loop position
clip(收) → organize(整理) → distill(点) → compose(写) → ★publish-wechat-draft(公众号发)
Upstream compose provides the finished draft; this skill is responsible for official account formatting + draft box delivery. The credential and the manual gate of "manual send to all" are controlled by the user.