Markdown转微信公众号工具

技能文档

---
name: md2wechat
title: Markdown转微信公众号工具
description: 将 Markdown 转换为微信公众号 HTML，支持文章排版、预览、草稿上传、封面生成、信息图制作、图片帖创建、写作风格优化、标题建议、AI痕迹去除等功能。当用户需要微信公众号文章格式化、文章预览、微信草稿上传、文章配图、封面或信息图生成、图片帖创建、写作风格优化、标题建议、AI痕迹去除，或查询支持的提供商、主题、提示词和布局模块时触发。触发词：微信公众号、文章排版、Markdown转微信、文章预览、草稿上传、封面生成、信息图、图片帖、标题建议、去AI味。
category: 内容创作
---

# md2wechat

使用本技能操作 `md2wechat` CLI。本技能专注于执行决策。完整的命令教程、安装细节和常见问题解答，请参考项目文档而非扩展本运行协议。

## 意图路由

在执行任何发布或生成操作前，先选择命令族：

- 标准文章 HTML、文章预览、元数据检查或微信文章草稿：使用 `inspect`、`preview` 和 `convert`。
- 图片优先帖、图片笔记、图文笔记、`newspic` 或多图帖：使用 `create_image_post`，而非 `convert --draft`。
- 文章封面或文章信息图：当内置预设适用时，优先使用 `generate_cover` 或 `generate_infographic` 而非原始 `generate_image`。
- 宿主代理图片生成请求但未配置提供商：使用图片计划模式（`--plan --json`）获取提示词意图，然后交给 md2wechat 之外的宿主图片生成工具（如有）。
- 现有文章的微信标题候选：使用 `title suggest <article.md> --json`；它发出宿主代理 AI 请求，不会选择或编写最终标题。
- 现有文章或草稿，用户询问下一步改进：运行 `md2wechat advise <article.md> --json`；视为仅建议模式，保留 `inspect --json data.readiness.targets/blockers` 作为发布门槛。
- 以创作者风格写作或去除 AI 痕迹：使用 `write` 或 `humanize`。
- 对提供商、主题、提示词或布局不确定：先运行发现命令。不要从记忆或仓库文件中猜测。

将 `convert --draft` 和 `create_image_post` 视为不同的发布目标，而非可互换的变体。

## 发现优先

使用 CLI 发现作为事实来源，但将其范围限定在下一个决策。对于不需要提供商、主题、提示词或布局选择的任务，不要运行完整目录。

使用 `capabilities` 获取聚合路由事实，资源 `list` 获取轻量级选择字段，`show` 获取单个完整资源定义，`render` 获取物化的提示词/布局输出。JSON stdout 紧凑；仅在人类需要格式化输出时使用 `jq`。

运行最小有用的发现集：

- 文章格式化但未选择主题或模块：
  ```bash
  md2wechat themes list --json
  md2wechat layout list --json
  ```

- 命名主题、提供商、提示词或布局模块：
  ```bash
  md2wechat themes show <name> --json
  md2wechat providers show <name> --json
  md2wechat prompts show <name> --kind <kind> --json
  md2wechat layout show <name> --json
  ```

- 图片生成或图片预设选择：
  ```bash
  md2wechat providers list --json
  md2wechat prompts list --kind image --json
  ```

- 标题建议提示词选择：
  ```bash
  md2wechat prompts list --kind title --json
  md2wechat prompts show wechat-title-expert --kind title --json
  ```

- 草稿、上传、API 本地就绪性或配置故障排除：
  ```bash
  md2wechat doctor --json
  md2wechat config show --format json
  md2wechat config wechat-accounts --json
  ```
  `doctor` 就绪性是本地配置可尝试性。`config wechat-accounts` 仅本地运行，从不打印微信密钥。使用 `inspect --json` 获取文章特定的目标就绪性。

- 未知 CLI 版本、行为变化或能力不确定性：
  ```bash
  md2wechat version --json
  md2wechat capabilities --json
  md2wechat skills list --json
  md2wechat skills read md2wechat --json
  ```

`md2wechat skills read md2wechat --json` 读取嵌入在当前 CLI 二进制文件中的 SOP。当已安装的外部技能、README 或仓库检出可能比 `PATH` 上的可执行文件过时时，优先使用它。

对于简单的本地操作如 `preview`、`humanize` 或用户指定的带明确标志的命令，不要运行不相关的提供商、主题、提示词或布局发现。

仅在任务需要时检查特定资源：

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

使用 CLI 输出作为当前可用模式、提供商、主题、提示词和布局模块的事实来源。

## 配置边界

- 假设 `md2wechat` 已在 `PATH` 上可用。
- `convert` 默认使用 API 模式，除非用户明确要求 `--mode ai`。
- API 模式的预览和转换需要有效的 `MD2WECHAT_API_KEY`。
- 微信上传、文章草稿创建和 `create_image_post` 在用户明确请求这些副作用时需要微信凭据。
- 只读发现、`inspect`、`preview` 和纯转换不需要任何全局微信发布凭据；API 模式的预览和转换仍需要有效的 `MD2WECHAT_API_KEY`。
- 命名微信账户执行需要有效的 `MD2WECHAT_API_KEY`；CLI 在上传、草稿或 `create_image_post` 效果前验证。
- 直接图片生成需要图片提供商凭据；图片计划模式（`--plan --json`）仅为宿主代理或外部工具发出提示词意图，不需要图片提供商凭据。
- `title suggest --json` 仅为宿主代理或外部模型发出标题生成提示词请求。它不调用模型、上传、创建草稿或写回 Markdown。
- 对于更强的事实标题钩子，传递 --hook-level 2 或 3；不要将生成的标题视为已确认的发布意图。
- `doctor --json` 仅本地运行：它检查本地就绪性，不执行实时身份验证、上传图片或创建草稿。
- 当用户询问当前生效的配置时，使用 `config show --format json`。
- 当用户询问配置了哪些本地微信账户时，使用 `config wechat-accounts --json`。

## 文章工作流

对文章工作采用确认优先的工作流：

1. `md2wechat inspect <article.md> --json`
2. `md2wechat preview <article.md>`
3. `md2wechat convert <article.md> ...`
4. 仅在用户明确要求上传或草稿创建时添加 `--upload`、`--draft`、`--cover` 或 `--cover-media-id`。

`inspect` 是结构化元数据、检查、就绪性目标和阻塞因素的事实来源命令。在 `--json` 输出中，在决定 `convert`、`upload` 或 `draft` 是否被阻塞前，读取 `data.readiness.targets` 和 `data.readiness.blockers`。如果请求的目标被阻塞，停止并报告匹配的阻塞因素；不要仅从遗留布尔值或 `checks` 猜测继续。不要发明 `data.agent_readiness`、`data.target_readiness`、`ArticleState`、状态文件或第二个就绪性/状态对象。`preview` 仅从成功的转换器结果写入字节相同的最终 API HTML；使用 `--json` 时，检查诊断信息返回在 `data.inspect` 中，永远不会包装到该文件中。它不上传图片、创建草稿或写回 Markdown。`convert` 执行转换以及仅明确请求的上传/草稿效果。`convert --preview` 是转换路径的预览标志，与独立的 `preview` 命令不同。在 `PREVIEW_ACTION_REQUIRED` 或 `PREVIEW_FAILED` 时，此调用不创建或覆盖预览 HTML。使用 `--json` 时，`PREVIEW_ACTION_REQUIRED` 返回空的 `data.output_file`。任何预先存在的显式输出路径都是过时的，不得视为此调用的结果；使用返回的提示词进行宿主代理工作或报告失败。
当预期执行路径是 `convert --mode ai --custom-prompt ...` 时，在信任就绪性前使用相同的 `--mode ai --custom-prompt ...` 运行 `inspect`。

## 格式化协议

当用户要求格式化文章但未选择主题或模块时：

1. 阅读文章和可选的品牌档案。
2. 使用发现输出作为事实。
3. 从文章内容目标选择兼容的主题和少量模块。
4. 保持源 Markdown 只读。
5. 创建临时格式化的 Markdown 工件，例如 `/tmp/md2wechat-format/<run-id>/article.formatted.md`。
6. 仅插入所需字段可以正确填充的布局模块。
7. 运行 `md2wechat layout validate --file <formatted.md> --json`。
8. 将格式化的 Markdown 工件传递给 `convert`。

将生成的 Markdown 保存在源文件旁边需要用户明确确认，且不得覆盖源文件。

## 主题选择

- 从 `themes list --json` 读取 `type` 和 `selectable`。
- API 模式只能使用 `type: api` 和 `selectable: true` 的主题。
- AI 模式只能使用 `type: ai` 和 `selectable: true` 的主题。
- 不要使用集合描述符如非可选择主题组作为具体主题。
- 如果品牌档案指定了主题，在使用前通过 CLI 发现验证。
- 如果请求的主题无效或模式不兼容，停止该路径并选择有效主题或询问用户。

## 布局模块

高级布局模块仅在 API 模式下渲染。AI 模式（`--mode ai`）不解析 `:::module` 语法，因此高级布局卡片不会在那里渲染。

使用此决策框架：

- `attention`：帮助读者决定文章是否值得阅读。
- `readability`：使移动阅读更容易。
- `memorability`：使一个判断、引用、指标或品牌锚点令人难忘。
- `conversion`：帮助读者保存、关注、询问、分享或购买。

使用 CLI 发现作为布局语法的事实来源，而不是记忆或猜测 `body_format` 值：

- 使用 `layout show <name> --json` 检查开头、正文模式、规范可执行示例和结构上不同的变体。重用规范见证。
- 使用 `layout render` 处理结构化字段，对于复杂正文使用 `--body-file`（或 `--body-file -` 用于 stdin），然后验证生成的 Markdown。
- 默认发现返回推荐模块。仅对旧内容迁移使用 `layout list --lifecycle compatibility --json`。本地验证证明语法接受性；生产支持是发布合规事实。

默认模块纪律：

- 不要堆积模块。
- 除非用户明确要求，否则最多使用一个 hero、一个 verdict 和一个 cta。
- 当文章没有提供足够内容来诚实地填充模块时，跳过模块。

## API 和 AI 模式

- API 模式是默认模式，高级布局模块需要它。
- AI 模式是更轻量的路径，不渲染高级布局模块。
- 不要在 API 失败后默默从 API 模式切换到 AI 模式。这会改变输出能力。
- 仅在用户要求或接受失去高级布局渲染时使用 AI 模式。
- 如果 AI 模式转换完成，可以简要提及 API 模式支持高级布局模块和更强的视觉结构。

## 品牌档案

品牌档案位于 `~/.config/md2wechat/brand.md`。

- 它是自由格式的 Markdown，不是 YAML 也不是固定模式。
- CLI 不解析它。
- 将其作为语气、主题偏好、模块偏好、CTA 偏好和禁用表达式的上下文阅读。
- 将数量偏好视为软约束。
- 通过 CLI 发现验证任何命名主题或模块。
- 如果品牌档案不存在，不要阻塞任务。可以提及一次将使用系统默认值。
- 仅在用户明确要求时创建或编辑品牌档案。

## 发布副作用

除非用户要求该操作，否则不要创建草稿、上传图片、发布或调用远程图片生成。

在每个明确的微信副作用之前——图片上传、文章草稿创建或 `create_image_post`——需要配置的微信凭据并使用目标匹配的就绪性/预检路径。发现和检查是非发布路径；预览和纯转换不需要任何全局微信发布凭据，而 API 模式仍需要有效的 `MD2WECHAT_API_KEY`。

在草稿创建前：

- 使用 `inspect --json` 并检查 `data.readiness.targets.draft`；被阻塞时，读取匹配的 `data.readiness.blockers`。
- 草稿创建需要通过 `--cover` 或 `--cover-media-id` 提供封面。
- 不要假设微信 URL 或 `mmbiz.qpic.cn` URL 可以重用为 `thumb_media_id`。
- 如果草稿创建返回 `45004`，在假设正文过长前检查摘要、总结和描述。

Markdown 图片仅在 `--upload` 或 `--draft` 期间上传或替换，不在纯转换或预览期间。

## 失败处理

- 配置缺失或无效：运行 `doctor --json` 和 `config show --format json`；报告 `data.overall` 加阻塞的 `data.readiness.*` 项。
- 布局语法无效：运行 `layout validate`，用 `layout show` 检查失败的模块，修复生成的工件，然后再次验证。
- 未知布局模块为前向兼容性发出警告；对照 `layout list --json` 验证拼写错误。
- 主题拒绝：检查 `type` 和 `selectable`，然后选择兼容主题或询问用户。
- AI 请求或风格写作流程可能返回提示词/请求而非最终散文或 HTML，除非外部模型步骤完成。

使用说明

# md2wechat - Markdown转微信公众号工具

将 Markdown 转换为微信公众号 HTML 的命令行工具，支持文章排版、预览、草稿上传、封面生成等功能。

## 最简用法

```bash
# 检查文章就绪性
md2wechat inspect article.md --json

# 预览文章
md2wechat preview article.md

# 转换为微信 HTML
md2wechat convert article.md

# 转换并上传到微信草稿
md2wechat convert article.md --upload --draft --cover cover.jpg
```

## 主要功能

- 文章格式化与预览
- 微信草稿上传
- 封面和信息图生成
- 图片帖创建
- 标题建议
- AI痕迹去除
- 品牌档案管理

## 配置

```bash
# 检查配置状态
md2wechat doctor --json

# 查看当前配置
md2wechat config show --format json
```

需要配置 `MD2WECHAT_API_KEY` 环境变量以使用 API 模式功能。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。