给 Agent 的操作手册。

---
name: md2wechat
description: Convert Markdown to WeChat Official Account HTML. Use this whenever the user wants WeChat article formatting, article preview, WeChat draft upload, image generation for articles, cover or infographic generation, image-post creation, writer-style drafting, title suggestions, AI trace removal, or current discovery of supported providers, themes, prompts, and layout modules. Also use for unpublished Zhihu, CSDN, Toutiao, or Tencent Cloud Developer Community drafts through a browser. Use for product introductions, encyclopedia articles or entry drafts, and writing tailored to platforms or search targets.
---

# md2wechat

Use this skill to operate the `md2wechat` CLI. Keep the skill focused on execution decisions. For full command tutorials, installation details, and FAQ-level explanations, refer users to the project docs instead of expanding this runtime protocol.

## 办公 Agent 如何安装和使用 md2wechat

千问办公、DuMate、WorkBuddy、豆包工作（也常被称为豆包办公）采用同一条使用路径：让 Agent 在当前执行环境安装 md2wechat CLI，再读取操作手册。把下面这段提示词直接发给你的办公 Agent：

```text
帮我安装 md2wechat，执行安装：
npm install -g @geekjourneyx/md2wechat

如果没有初始化配置，请执行初始化配置：
md2wechat config init

已有配置请保留。如果缺少 Node.js 或 npm，请先检查并完成安装。
安装后读取操作手册：https://www.md2wechat.cn/docs/md2wechat/skill
CLI 使用手册：https://www.md2wechat.cn/docs/md2wechat
请检查 md2wechat version --json，告诉我安装结果和下一步需要补充的配置。
```

Agent 需要能执行终端命令并读写文章文件。如果它运行在远程环境或沙箱，安装也应在那个环境完成。初始化配置不会自动开通 API Key；调用排版服务时按手册填写自己的有效密钥。

安装后，把文章交给 Agent：

```text
请使用 md2wechat 为这篇文章排版。
先阅读 https://www.md2wechat.cn/features，了解高级排版模块。
保留原文事实和数据，选择适合内容的模块，不要为了使用模块增加虚构内容。
按 https://www.md2wechat.cn/docs/md2wechat/skill 操作。
将排版后的 Markdown 另存为新文件，生成预览供我检查。
如果缺少配置，请明确告诉我需要补充什么。本次只预览。
```

完整步骤见[办公 Agent 安装与排版教程](/blog/office-agent-md2wechat-install-guide)。高级排版可先看[功能介绍](https://www.md2wechat.cn/features)，再查[网页版文档](https://www.md2wechat.cn/docs)和[高级排版教程](https://mp.weixin.qq.com/s/im5k-SXcoHMA6Kewtnm4Fw)。

## Intent Routing

Choose the command family before taking any publish or generation action:

- Standard article HTML, article preview, metadata inspection, or WeChat article draft: use `inspect`, `preview`, and `convert`.
- Unpublished Zhihu, CSDN, Toutiao, or Tencent Cloud Developer Community draft: run `md2wechat skills read md2wechat references/sync/workflow.md --json` for the current CLI's embedded workflow; the CLI prepares content and the Agent operates the browser.
- Image-first post, image note, image-text note, `newspic`, or multi-image post: use `create_image_post`, not `convert --draft`.
- Article cover or article infographic: prefer `generate_cover` or `generate_infographic` over raw `generate_image` when a bundled preset fits.
- Host-agent image generation request with no provider configured: use image plan mode (`--plan --json`) to get prompt intent, then hand it to the host image-generation tool if one is available outside md2wechat.
- WeChat title candidates for an existing article: use `title suggest <article.md> --json`; it emits a host-Agent AI request and does not choose or write the final title.
- Product introductions, encyclopedia articles or entry drafts, and platform/search-directed writing: read `md2wechat skills read md2wechat references/writing/workflow.md --json` and follow it as the host Agent. Prefer this route over `advise` or `write` for these requests; skip it for formatting-only tasks.
- Existing article or draft, user asks what to improve next: run `md2wechat advise <article.md> --json`; treat it as recommendation-only and keep `inspect --json data.readiness.targets/blockers` as the publish gate.
- Writing in a creator style or removing AI traces: use `write` or `humanize`.
- Provider, theme, prompt, or layout uncertainty: run discovery first. Do not guess from memory or repository files.

Treat `convert --draft` and `create_image_post` as different publish targets, not interchangeable variants.

## Discovery First

Use CLI discovery as the source of truth, but keep it scoped to the next decision. Do not run the full catalog for tasks that do not need provider, theme, prompt, or layout selection.

Use `capabilities` for aggregate routing facts, resource `list` for lightweight selection fields, `show` for one full resource definition, and `render` for materialized prompt/layout output. JSON stdout is compact; use `jq` only when a human needs formatted output.

Run the smallest useful discovery set:

- Article formatting with no theme or modules chosen:
  ```bash
  md2wechat themes list --json
  md2wechat layout list --json
  ```

- A named theme, provider, prompt, or layout module:
  ```bash
  md2wechat themes show <name> --json
  md2wechat providers show <name> --json
  md2wechat prompts show <name> --kind <kind> --json
  md2wechat layout show <name> --json
  ```

- Image generation or image-preset selection:
  ```bash
  md2wechat providers list --json
  md2wechat prompts list --kind image --json
  ```

- Subject-reference (image-to-image) capability before using `--subject-reference`:
  ```bash
  md2wechat providers show minimax --json
  ```
  Read `supports_subject_reference` on the provider and on each entry of `supported_models`. Only the `minimax` provider and its `image-01` model accept `--subject-reference`, and the reference must be a publicly reachable `http(s)` portrait image URL; inline data URLs and local paths are rejected. Unsupported provider/model combinations fail immediately with `CONFIG_INVALID`, so do not retry them as generation failures.

For Atlas Cloud image generation (introduced in v3.5.0), discover `atlascloud` with `providers show atlascloud --json` before configuring it. The aliases `atlas-cloud` and `atlas` select the same provider. Configure `api.image_provider` and the user's Atlas Cloud `api.image_key`; the v3.5.0 defaults are model `openai/gpt-image-2/text-to-image` and size `1024x1024`. Sizes use `WIDTHxHEIGHT`, not aspect-ratio notation. The CLI submits the image task and waits for its result. Image credentials and billing are separate from the Markdown conversion API. Do not claim live authentication or sufficient balance from local configuration checks. Use `--plan --json` when the user wants prompt intent for a host image tool instead of a remote generation request.

- Title suggestion prompt selection:
  ```bash
  md2wechat prompts list --kind title --json
  md2wechat prompts show wechat-title-expert --kind title --json
  ```

- Draft, upload, API local-readiness, or configuration troubleshooting:
  ```bash
  md2wechat doctor --json
  md2wechat config show --format json
  md2wechat config wechat-accounts --json
  ```
  `doctor` readiness is local configuration attemptability. `config wechat-accounts` is local-only and never prints WeChat secrets. Use `inspect --json` for article-specific target readiness.

- Unknown CLI version, changed behavior, or capability uncertainty:
  ```bash
  md2wechat version --json
  md2wechat capabilities --json
  md2wechat skills list --json
  md2wechat skills read md2wechat --json
  ```

`md2wechat skills read md2wechat --json` reads the SOP embedded in the current CLI binary. Prefer it when the installed external skill, README, or repository checkout may be stale relative to the executable on `PATH`.

For simple local actions such as `preview`, `humanize`, or a user-specified command with explicit flags, do not run unrelated provider, theme, prompt, or layout discovery.

Inspect specific resources only when the task needs them:

```bash
md2wechat providers show <name> --json
md2wechat themes show <name> --json
md2wechat prompts show <name> --kind <kind> --json
md2wechat layout show <name> --json
```

Use CLI output as the source of truth for currently available modes, providers, themes, prompts, and layout modules.

## Configuration Boundaries

- Assume `md2wechat` is already available on `PATH`.
- `convert` defaults to API mode unless the user explicitly asks for `--mode ai`.
- API-mode preview and conversion require a valid `MD2WECHAT_API_KEY`.
- WeChat upload, article draft creation, and `create_image_post` require WeChat credentials whenever the user explicitly requests those side effects.
- Read-only discovery, `inspect`, `preview`, and plain conversion are free of any global WeChat publishing credential requirement; API-mode preview and conversion still require a valid `MD2WECHAT_API_KEY`.
- Named WeChat account execution requires a valid `MD2WECHAT_API_KEY`; the CLI validates it before upload, draft, or `create_image_post` effects.
- Direct image generation calls the provider and uploads the result to WeChat material storage; it requires image-provider credentials plus WeChat credentials and the applicable IP allowlist. It returns `data.media_id` and `data.wechat_url`, does not write images into Markdown, and does not create a draft. After user confirmation, use `--cover-media-id` for a generated cover or insert the actual `wechat_url` into the article. Image plan mode (`--plan --json`) only emits prompt intent for a host Agent or external tool and does not require image-provider credentials.
- `title suggest --json` only emits a title-generation prompt request for the host Agent or external model. It does not call a model, upload, create drafts, or write back to Markdown.
- For stronger factual title hooks, pass --hook-level 2 or 3; do not treat generated titles as confirmed publishing intent.
- `doctor --json` is local-only: it checks local readiness and does not perform live authentication, upload images, or create drafts.
- Use `config show --format json` when the user asks what configuration is currently effective.
- Use `config wechat-accounts --json` when the user asks which local WeChat accounts are configured.

## Article Workflow

Prefer a confirm-first workflow for article work:

1. `md2wechat inspect <article.md> --json`
2. `md2wechat preview <article.md>`
3. `md2wechat convert <article.md> ...`
4. Add `--upload`, `--draft`, `--cover`, or `--cover-media-id` only when the user explicitly asks for upload or draft creation.

`inspect` is the source-of-truth command for structured metadata, checks, readiness targets, and blockers. In `--json` output, read `data.readiness.targets` and `data.readiness.blockers` before deciding whether `convert`, `upload`, or `draft` is blocked. If the requested target is blocked, stop and report the matching blockers; do not continue by guessing from legacy booleans or `checks` alone. Do not invent `data.agent_readiness`, `data.target_readiness`, `ArticleState`, state files, or a second readiness/state object. `preview` writes only byte-identical final API HTML from a successful converter result; with `--json`, inspect diagnostics are returned in `data.inspect` and are never wrapped into that file. It does not upload images, create drafts, or write back to Markdown. `convert` performs conversion and only the explicitly requested upload/draft effects. `convert --preview` is the convert-path preview flag and is not the same as the standalone `preview` command. On `PREVIEW_ACTION_REQUIRED` or `PREVIEW_FAILED`, this invocation does not create or overwrite preview HTML. With `--json`, `PREVIEW_ACTION_REQUIRED` returns an empty `data.output_file`. Any pre-existing explicit output path is stale and must not be treated as this invocation's result; use the returned prompt for host-Agent work or report the failure.
When the intended execution path is `convert --mode ai --custom-prompt ...`, run `inspect` with the same `--mode ai --custom-prompt ...` before trusting readiness.

## Formatting Protocol

When the user asks to format an article and has not chosen a theme or modules:

1. Read the article and optional Brand Profile.
2. Use discovery output as facts.
3. Choose a compatible theme and a small set of modules from the article's content goal.
4. Keep the source Markdown read-only.
5. Create a temporary formatted Markdown artifact, for example `/tmp/md2wechat-format/<run-id>/article.formatted.md`.
6. Insert only layout modules whose required fields can be filled correctly.
7. Run `md2wechat layout validate --file <formatted.md> --json`.
8. Pass the formatted Markdown artifact to `convert`.

Saving generated Markdown next to the source file requires explicit user confirmation and must not overwrite the source.

## Theme Selection

- Read `type` and `selectable` from `themes list --json`.
- API mode can use only `type: api` and `selectable: true` themes.
- AI mode can use only `type: ai` and `selectable: true` themes.
- Do not use collection descriptors such as non-selectable theme groups as concrete themes.
- If Brand Profile names a theme, verify it through CLI discovery before using it.
- If a requested theme is invalid or mode-incompatible, stop that path and choose a valid theme or ask the user.

## Layout Modules

Advanced layout modules render only in API mode. AI mode (`--mode ai`) does not parse `:::module` syntax, so advanced layout cards will not render there.

Use this decision frame:

- `attention`: help readers decide whether the article is worth reading.
- `readability`: make mobile reading easier.
- `memorability`: make one judgment, quote, metric, or brand anchor stick.
- `conversion`: help readers save, follow, inquire, share, or buy.

Use CLI discovery as the source of truth for layout syntax instead of memorizing or guessing `body_format` values:

- Inspect the opener, body schema, canonical executable example, and structurally distinct variants with `layout show <name> --json`. Reuse the canonical witness.
- Use `layout render` for structured fields and `--body-file` (or `--body-file -` for stdin) for complex bodies, then validate the generated Markdown.
- Default discovery returns recommended modules. Use `layout list --lifecycle compatibility --json` only for old-content migration. Local validation proves syntax acceptance only; production support is a release-conformance fact.

Default module discipline:

- Do not pile on modules.
- Use at most one hero, one verdict, and one cta unless the user explicitly asks for more.
- Skip modules when the article does not provide enough content to fill them honestly.

### Title and closing contract

Use these modules by reading task, not by visual resemblance:

- `hero: masthead`: masthead opening for a feature, release, or branded column.
- `section-title`: strong section entry. Its variants are exactly `marker`, `divider`, `numbered`, `frame`, `focus`, and `vertical`. Keep ordinary subsections as Markdown headings.
- `part`: ordinary major-section transition.
- `epilogue`: entry into the tail or final judgment. Do not use it for the same transition as `part`.
- `cta`: next action. Choose exactly one intent: `save-follow`, `consult`, or `trial`. Only `trial` accepts and renders up to three `points`; do not add `points` to the other variants.
- `closing`: lightweight thanks, wish, or quiet signature. It has no action role and must not replace `cta`.

Existing basic `symbol` keys include the following. Read `layout show` for the selected module before using a key:

- `spark-solid`
- `spark-outline`
- `diamond-solid`
- `diamond-outline`
- `reference-mark`
- `asterism`
- `double-circle`
- `circle`
- `square-solid`
- `square-outline`
- `star`
- `infinity`

不要直接填写符号、Emoji、HTML、SVG、多字符组合或自行创造的英文别名。系统负责把以上英文键映射为安全的纯文字符号。不要自行发明字段或枚举值；未知值的回退是渲染器的安全行为，不是 Agent 可以依赖的写法。

Before emitting a new module block:

1. Run `md2wechat layout list --json` and confirm the module exists.
2. Run `md2wechat layout show <name> --json` and read `fields`, `body_format`, enums, defaults, ignored fields, and invalid cases.
3. Emit only documented fields and values.
4. Run `md2wechat layout validate --file <formatted.md> --json`.

## API And AI Mode

- API mode is the default and is required for advanced layout modules.
- AI mode is a lighter path and does not render advanced layout modules.
- Do not silently switch from API mode to AI mode after an API failure. That changes the output capability.
- Use AI mode only when the user asks for it or accepts losing advanced layout rendering.
- If an AI-mode conversion completes, it is acceptable to briefly mention that API mode supports advanced layout modules and stronger visual structure.

## Brand Profile

Brand Profile lives at `~/.config/md2wechat/brand.md`.

- It is free-form Markdown, not YAML and not a fixed schema.
- The CLI does not parse it.
- Read it as context for voice, theme preferences, module preferences, CTA preferences, and forbidden expressions.
- Treat quantity preferences as soft constraints.
- Verify any named theme or module through CLI discovery.
- If Brand Profile does not exist, do not block the task. You may mention once that system defaults will be used.
- Create or edit Brand Profile only when the user explicitly asks.

## Publishing Side Effects

Do not create drafts, upload images, publish, or call remote image generation unless the user asks for that action.

Before every explicit WeChat side effect—image upload, article draft creation, or `create_image_post`—require configured WeChat credentials and use the target-matched readiness/preflight path. Discovery and inspection remain non-publishing paths; preview and plain conversion are free of any global WeChat publishing credential requirement, while API mode still requires a valid `MD2WECHAT_API_KEY`.

Before WeChat article draft creation through `convert`:

- Use `inspect --json` and check `data.readiness.targets.draft`; when blocked, read matching `data.readiness.blockers`.
- Draft creation requires a cover via `--cover` or `--cover-media-id`.
- Do not assume a WeChat URL or `mmbiz.qpic.cn` URL can be reused as `thumb_media_id`.
- If draft creation returns `45004`, check digest, summary, and description before assuming the body is too long.

In the WeChat `convert` flow, Markdown images are uploaded or replaced only during `--upload` or `--draft`, not during plain conversion or preview.

## Failure Handling

- Missing or invalid config: run `doctor --json` and `config show --format json`; report `data.overall` plus the blocking `data.readiness.*` item.
- Invalid layout syntax: run `layout validate`, inspect the failing module with `layout show`, fix the generated artifact, then validate again.
- Unknown layout modules warn for forward compatibility; verify typos against `layout list --json`.
- Theme rejection: check `type` and `selectable`, then choose a compatible theme or ask the user.
- AI request or style-writing flows may return a prompt/request rather than final prose or HTML unless the external model step is completed.


## 多平台未发布草稿

借助具备浏览器能力的 Agent，将符合要求的 Markdown 保存为知乎、CSDN、头条、腾讯云开发者社区未发布草稿，保存后重新打开核对。

需要具备浏览器能力的 Agent，以及用户已登录的目标平台账号。 支持普通 Markdown 与有效本地图片；远程图片、Obsidian 专用语法、原始 HTML 和高级排版块需先处理。 本地准备不需要微信凭证或排版 API Key；准备成功不等于草稿完成。

头条会归一化标题级别；混合多个标题级别时须在写入前停止，经作者同意调整原稿后再继续。特殊字符须逐字符核对。 腾讯云指引从 v3.7.0 起提供。先粘贴正文，再通过编辑器插入本地图片；保存后重新打开同一草稿核对。多图、长文及草稿列表恢复尚未验证。

先运行 `md2wechat capabilities --json`，再运行 `md2wechat sync prepare article.md --output ./article-prepared --json`。输出目录须为新目录且父目录已存在。成功的 SYNC_PREPARED / action_required 只代表本地准备完成。

Agent 应读取 `md2wechat skills read md2wechat references/sync/workflow.md --json`，以及目标平台的 references/sync/zhihu.md、references/sync/csdn.md、references/sync/toutiao.md、references/sync/tencent-cloud.md。通过正常编辑器保存，取得草稿地址后重新打开，核对标题、全文、图片位置及主要结构。中断时恢复同一草稿，不能盲目重复创建。当前不自动公开发布或更新旧文章。

项目记录包含 macOS、Chrome 已登录会话的知乎、CSDN、头条短图文、结构与长文验证。腾讯云已验证短结构正文与单图保存重开；多图、长文及从草稿列表恢复尚未验证。其他系统与 Agent 宿主尚未逐一验收。 企业自用、代运营及客户交付请先确认授权范围。商业授权单独沟通，购买服务不自动包含商业授权。

[完整首篇草稿教程](https://www.md2wechat.cn/docs/multi-platform) · [能力与费用](https://www.md2wechat.cn/multi-platform) · [实测记录](https://github.com/geekjourneyx/md2wechat-skill/blob/v3.7.0/docs/SMOKE.md)