Agent API 文档API
doctor 与 inspect 准备状态
使用 doctor 和 inspect 的准备状态输出，在预览、转换、上传或创建草稿前判断当前任务是否可以继续。
doctor 与 inspect 准备状态
md2wechat 2.4.0 给 Agent 提供了更清楚的判断方式：在转换、上传、创建公众号草稿之前，先判断当前任务到底能不能做。
最短规则是：
先用 doctor --json 检查本机配置，再用 inspect --json 检查单篇文章。
两个命令分别回答什么
| 命令 | 用来判断 | 不要把它当成 |
|---|---|---|
md2wechat doctor --json | 本机配置是否具备尝试条件 | 某篇文章一定可以发布 |
md2wechat inspect article.md --json | 单篇文章的目标状态 | 账号登录或真实上传测试 |
doctor 是本地检查。它判断当前机器是否具备尝试转换、生图、创建草稿的基本配置。
inspect 检查某一篇 Markdown，并告诉你预览、转换、上传、草稿这些目标分别是 ready、blocked、degraded 还是 not requested。
推荐顺序
新环境或升级后，先跑：
md2wechat version --json
md2wechat doctor --json
md2wechat capabilities --json处理单篇文章时，再跑：
md2wechat inspect article.md --json
md2wechat preview article.md
md2wechat convert article.md如果要创建公众号草稿，先检查草稿目标：
md2wechat inspect article.md --draft --cover cover.jpg --json
md2wechat convert article.md --draft --cover cover.jpg新的准备状态结构
新的 Agent 应该优先读取 inspect --json 里的这些字段：
{
"data": {
"readiness": {
"schema_version": "1",
"targets": {
"preview": "ready",
"convert": "ready",
"upload": "not_requested",
"draft": "blocked"
},
"blockers": [
{
"code": "MISSING_COVER",
"target": "draft"
}
]
}
}
}旧字段仍然保留：
convert_readyupload_readydraft_readypreview_fidelity
但对 Agent 来说，targets 和 blockers 更适合作为判断依据，因为它们会说清楚哪个目标被什么问题挡住了。
常见阻塞项
| 阻塞项 | 通常代表 | 下一步检查 |
|---|---|---|
MISSING_API_KEY | API 模式还不能运行 | 检查 md2wechat doctor --json 和配置 |
LOCAL_IMAGE_MISSING | Markdown 里引用了不存在的本地图片 | 修正图片路径或删除引用 |
MISSING_COVER | 创建草稿缺少封面 | 传入 --cover 或 --cover-media-id |
Agent 应该怎么做
做自动化流程时，建议固定成这个顺序：
- API 相关任务前先跑
doctor --json。 - 只跑当前任务需要的发现命令。
- 对单篇文章跑
inspect --json。 - 如果目标被阻塞，停止该目标并说明阻塞原因。
- 用户还没看过结果时，先预览，再转换或创建草稿。
这样可以减少猜测，也更容易把失败原因讲清楚。