md2wechat

md2wechat

使用此技能操作 md2wechat CLI。请让此技能聚焦于执行决策。有关完整命令教程、安装详情和常见问题解答，请引导用户查阅项目文档，而不是扩展此运行时协议。

意图路由

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

• 标准文章 HTML、文章预览、元数据检查或微信公众号文章草稿：使用 inspect、preview 和 convert。
• 未发布的知乎、CSDN、今日头条或腾讯云开发者社区草稿：运行 md2wechat skills read md2wechat references/sync/workflow.md --json，获取当前 CLI 内嵌的工作流；CLI 负责准备内容，Agent 负责操作浏览器。
• 图片优先的帖子、图片笔记、图文笔记、newspic 或多图帖子：使用 create_image_post，而不是 convert --draft。
• 文章封面或文章信息图：如果有适用的内置预设，优先使用 generate_cover 或 generate_infographic，而不是原始的 generate_image。
• 未配置图像提供方时，主机 Agent 收到图像生成请求：使用图像计划模式（--plan --json）获取提示词意图，然后交给 md2wechat 之外可用的主机图像生成工具。
• 为现有文章生成微信公众号标题候选：使用 title suggest <article.md> --json；此命令会发出主机 Agent AI 请求，不会选择或写入最终标题。
• 产品介绍、百科文章或词条草稿，以及面向平台或搜索的写作：读取 md2wechat skills read md2wechat references/writing/workflow.md --json 并以主机 Agent 身份遵循其中的指引。此类请求优先采用此方式，而非 advise 或 write；仅涉及格式调整的任务除外。
• 用户询问现有文章或草稿下一步应如何改进：运行 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 标准输出内容紧凑；仅在人类需要格式化输出时使用 jq。

运行最小且有用的发现命令集：

• 未选择主题或模块的文章格式化：

  md2wechat themes list --json
  md2wechat layout list --json
  

• 指定主题、提供方、提示词或布局模块：

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

• 图像生成或图像预设选择：

  md2wechat providers list --json
  md2wechat prompts list --kind image --json
  

• 使用 --subject-reference 前，检查主体参考（图生图）功能：

  md2wechat providers show minimax --json
  

  查看提供方及 supported_models 中每个条目的 supports_subject_reference。只有 minimax 提供方及其 image-01 模型接受 --subject-reference，且参考图必须是可公开访问的 http(s) 人像图片 URL；不接受内联数据 URL 和本地路径。不支持的提供方／模型组合会立即报错 CONFIG_INVALID，因此不要将其作为生成失败重试。

• 标题建议提示词选择：

  md2wechat prompts list --kind title --json
  md2wechat prompts show wechat-title-expert --kind title --json
  

• 草稿、上传、API 本地就绪状态或配置故障排查：

  md2wechat doctor --json
  md2wechat config show --format json
  md2wechat config wechat-accounts --json
  

  doctor 的就绪状态表示本地配置是否具备执行条件。config wechat-accounts 仅在本地运行，且不会打印微信密钥。使用 inspect --json 检查文章特定目标的就绪状态。

• CLI 版本未知、行为发生变化或功能不确定：

  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 等简单本地操作，或带有明确标志且由用户指定的命令，不要执行无关的提供方、主题、提示词或布局发现。

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

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 上可用。
• 除非用户明确要求使用 --mode ai，否则 convert 默认使用 API 模式。
• API 模式的预览和转换需要有效的 MD2WECHAT_API_KEY。
• 用户明确要求产生副作用时，微信上传、创建文章草稿和 create_image_post 均需要微信凭据。
• 只读发现、inspect、preview 和普通转换均不要求全局微信发布凭据；但 API 模式的预览和转换仍需要有效的 MD2WECHAT_API_KEY。
• 使用指定微信账号执行操作需要有效的 MD2WECHAT_API_KEY；CLI 会在上传、创建草稿或执行 create_image_post 操作前验证该密钥。
• 直接生成图像需要图像提供方凭据；图像计划模式（--plan --json）仅向宿主 Agent 或外部工具输出提示词意图，不需要图像提供方凭据。
• title suggest --json 仅向宿主 Agent 或外部模型输出标题生成提示请求。它不会调用模型、上传内容、创建草稿，也不会写回 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 是 convert 路径的预览标志，与独立的 preview 命令不同。出现 PREVIEW_ACTION_REQUIRED 或 PREVIEW_FAILED 时，此次调用不会创建或覆盖预览 HTML。使用 --json 时，PREVIEW_ACTION_REQUIRED 会返回空的 data.output_file。任何预先存在的显式输出路径都已过期，不得视为此次调用的结果；请使用返回的提示词执行宿主 Agent 工作，或报告失败。 当预期执行路径为 convert --mode ai --custom-prompt ... 时，信任就绪状态前，先使用相同的 --mode ai --custom-prompt ... 运行 inspect。

格式化协议

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

1. 阅读文章和可选的 Brand Profile。
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 的主题。
• 不要将不可选择的主题组等集合描述符用作具体主题。
• 如果 Brand Profile 指定了主题，使用前先通过 CLI 发现命令验证。
• 如果请求的主题无效或与模式不兼容，请停止该路径，改选有效主题或询问用户。

布局模块

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

使用以下决策框架：

• attention：帮助读者判断文章是否值得阅读。
• readability：让移动端阅读更轻松。
• memorability：让某个判断、引述、指标或品牌要点令人印象深刻。
• conversion：帮助读者收藏、关注、咨询、分享或购买。

将 CLI 探索作为布局语法的准确信息来源，不要死记或猜测 body_format 的取值：

• 使用 layout show <name> --json 检查开头标记、正文架构、规范的可执行示例，以及结构上不同的变体。复用规范示例。
• 对结构化字段使用 layout render，对复杂正文使用 --body-file（或通过标准输入使用 --body-file -），然后验证生成的 Markdown。
• 默认探索会返回推荐模块。仅在迁移旧内容时使用 layout list --lifecycle compatibility --json。本地验证只能证明语法被接受；生产环境支持情况属于发布一致性事实。
• 推荐使用 gallery。对于 expand，通过 --body-file 传入标题字段、独立的 --- 和 Markdown 正文。cover-reveal 和 expand 默认输出完整静态内容；只有用户明确要求交互候选方案时才使用 first-layer，并在依赖它之前验证目标 API。

默认模块规范：

• 不要堆叠模块。
• 除非用户明确要求更多，否则最多使用一个主视觉模块、一个结论模块和一个 CTA 模块。
• 如果文章提供的内容不足以如实填充模块，就跳过该模块。

API 模式与 AI 模式

• API 模式是默认模式，也是使用高级布局模块的必要条件。
• AI 模式是较轻量的路径，不会渲染高级布局模块。
• API 模式失败后，不要悄悄切换到 AI 模式。这会改变输出能力。
• 只有用户提出要求或接受失去高级布局渲染能力时，才使用 AI 模式。
• 如果 AI 模式转换成功，可以简要说明 API 模式支持高级布局模块和更强的视觉结构。

品牌资料

品牌资料位于 ~/.config/md2wechat/brand.md。

• 它是自由格式的 Markdown，不是 YAML，也没有固定架构。
• CLI 不会解析它。
• 将其作为语气、主题偏好、模块偏好、CTA 偏好和禁用表达方面的背景信息来阅读。
• 将数量偏好视为软性约束。
• 通过 CLI 探索验证任何指定的主题或模块。
• 如果品牌资料不存在，不要因此阻碍任务。可以提及一次将使用系统默认设置。
• 仅当用户明确要求时，才创建或编辑品牌资料。

发布副作用

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

每次执行明确的微信副作用——上传图片、创建文章草稿或调用 create_image_post——之前，都必须确认已配置微信凭据，并使用与目标匹配的就绪状态检查／预检路径。探索和检查不属于发布流程；预览和纯转换不要求全局微信发布凭据，但 API 模式仍需要有效的 MD2WECHAT_API_KEY。

通过 convert 创建微信文章草稿之前：

• 使用 inspect --json 并检查 data.readiness.targets.draft；如果被阻止，则查看匹配的 data.readiness.blockers。
• 创建草稿必须通过 --cover 或 --cover-media-id 提供封面。
• 不要假设微信 URL 或 mmbiz.qpic.cn URL 可以用作 thumb_media_id。
• 如果创建草稿返回 45004，请先检查摘要、简介和描述，再判断正文是否过长。

在微信 convert 流程中，只有使用 --upload 或 --draft 时才会上传或替换 Markdown 图片；纯转换或预览不会执行这些操作。

故障处理

• 缺少或无效的配置：运行 doctor --json 和 config show --format json；报告 data.overall 以及阻塞流程的 data.readiness.* 项。
• 布局语法无效：运行 layout validate，通过 layout show 检查出错的模块，修复生成的产物，然后再次验证。
• 未知的布局模块会发出警告，以保持向前兼容；使用 layout list --json 检查是否有拼写错误。
• 主题被拒绝：检查 type 和 selectable，然后选择兼容的主题或询问用户。
• AI 请求或样式编写流程可能会返回提示词/请求，而非最终文案或 HTML，除非已完成外部模型步骤。