md2wechat-skill 使用指南

如果说 md2wechat-skill 是新手第一入口，这一页就是进阶补充页。

这页不再重复“先装什么”的主线，而是重点解释：

• 安装完成后还要验证什么
• 为什么 discovery-first 是最佳实践
• Claude Code / Codex / OpenCode / Claudian / OpenClaw 的差异到底在哪
• 什么情况下该继续看 FAQ 或环境专页

推荐验证顺序

安装完成后，建议按这个顺序验证，而不是只看 version 一条命令。

md2wechat version --json
md2wechat config init
md2wechat capabilities --json
md2wechat providers list --json
md2wechat themes list --json
md2wechat prompts list --kind image --json

这 6 条命令分别验证的是：

1. CLI 是否真的可执行
2. 配置文件是否能正确初始化
3. 当前运行时暴露了哪些高层能力
4. 当前有哪些图片 provider
5. 当前有哪些主题
6. 当前有哪些封面图和信息图 prompt 资产

2.0.7 之后，国产生图怎么配

如果你想优先用国产模型做封面图、信息图或文章配图，2.0.7 之后先记住这几个点：

• config init 默认已经对齐到 volcengine
• 默认图片尺寸已经改成 provider-aware 的 2K
• 默认模型是 doubao-seedream-5-0-260128
• provider 别名也支持 volc

最短检查顺序：

md2wechat config init
md2wechat providers show volcengine --json
md2wechat config show --format json

你重点确认这些值：

api:
  image_provider: 'volcengine'
  image_model: 'doubao-seedream-5-0-260128'
  image_size: '2K'

如果你只想先把生图跑通，通常最少还要补：

api:
  image_key: '你的火山引擎 API Key'

为什么这次要强调 provider-aware 默认值

以前很多人会沿用一套固定像素心智，比如：

image_size: 1024x1024

这对某些 provider 勉强能用，但对 volcengine 这种按尺寸等级工作的路径并不自然。

所以 2.0.7 之后：

• 不再默认拿别的 provider 尺寸去套国产模型
• 2K 成为更合理的起步值
• 横版还是竖版，更多靠 prompt 里的 16:9 landscape 或 3:4 portrait 来约束

Volcengine 路径最该先跑哪条 discovery

如果你只跑一条命令，优先这个：

md2wechat providers show volcengine --json

它会直接告诉你：

• provider 名称
• 可用别名
• 默认模型
• 当前内置支持的模型目录

这样你就不用再手写猜：

• doubao-seedream-5-0-260128
• doubao-seedream-5-0-lite-260128

ModelNotOpen 应该先怎么排

这类报错最常见，也最容易被误判。

如果你看到：

{
  "error": {
    "code": "ModelNotOpen"
  }
}

优先排查的不是 prompt，而是账号是否已经开通 Seedream。

建议直接去：

• 火山引擎豆包

然后进控制台里的开通管理，把 Seedream 勾上。

为什么要坚持 discovery-first

在 Agent 工作流里，最容易出错的不是命令本身，而是运行时先入为主地假设“某个 theme 一定存在”或“某个 provider 一定配置好了”。

所以最佳实践是：

1. 先跑 discovery
2. 再决定用哪个 theme / provider / prompt
3. 最后才执行生成、转换、发草稿

这样做的好处是：

• 对新手更稳，不容易一上来就撞报错
• 对自动化更稳，减少运行时猜测
• 对 GEO 更友好，因为结构更容易被模型提取成可靠步骤

运行时差异到底在哪里

虽然这些环境都能接 md2wechat，但它们的差异很明确。

推荐的第一次任务组合

主技能页已经给了最短路径，这里补充一个更稳的三段式组合。

第 1 段：纯预览

md2wechat convert article.md --preview

这一步只证明转换链路是通的。

第 2 段：AI 模式

md2wechat convert article.md --mode ai --theme autumn-warm --json

这一步用来验证：

• 你是否真的在 AI 模式
• 你是否理解 AI 模式返回的是结构化结果，而不是最终 HTML

第 3 段：草稿创建

md2wechat convert article.md --draft --cover cover.jpg

这一步才会开始暴露：

• 微信凭证
• API Key
• 封面图
• 素材上传链路

什么时候继续看 FAQ

如果你遇到的是“症状型问题”，直接去 FAQ 更快，例如：

• command not found: md2wechat
• skill 装了但 Agent 还是不能用
• Claudian 找不到命令
• OpenClaw 安装后仍然失败
• AI 模式为什么不是最终 HTML

对应页面：

• md2wechat-skill FAQ

什么时候继续看环境专页

如果你已经确定问题只发生在某一个环境，就不要继续在总文档里绕。

直接看：

• Coding Agents 总览
• Claude Code
• Codex
• OpenCode
• Claudian
• OpenClaw

最后的建议

对新手用户最稳的做法永远是：

1. 主技能页照着装
2. 用这页的验证顺序做 discovery
3. 先做预览，再做 AI 模式，再做草稿
4. 有症状就进 FAQ，有环境问题就进专页