md2wechat 提供了一组面向 Agent 和自动化脚本的发现命令,用来在执行前先确认当前 CLI 支持什么能力、有哪些可用资源、当前配置是否就绪。
v3.2 迁移:
capabilities --json的data.providers、data.themes、data.prompts已从资源数组改为聚合 summary object;各资源的list --json只返回轻量选择字段,完整定义或渲染结果请使用show --json/render --json。外层schema_version: "v1"仅标识统一响应 envelope,不表示每个命令的datapayload 永不演进。
这组命令的定位不是替代 --help,而是提供可机读、可枚举、可提前探测的能力接口。
Discovery 的责任分层是:capabilities 返回聚合路由事实;资源 list 返回轻量选择字段;show 返回单个资源的完整定义;render 返回物化后的 prompt 或 layout。所有 --json stdout 都是单行紧凑对象并以最终换行结束;人工阅读可使用 md2wechat ... --json | jq。
对于 Agent、脚本或 CI,discovery 应服务于下一步决策,而不是每次任务都全量枚举。使用最小必要集合:
- 版本、能力或行为不确定:
md2wechat version --json、md2wechat capabilities --json - API、草稿、上传或配置 readiness:
md2wechat doctor --json,必要时再md2wechat config show --format json - 多公众号本地配置检查:
md2wechat config wechat-accounts --json - 多平台草稿执行方式不确定:只运行
md2wechat capabilities --json并读取data.sync - 文章排版且用户未指定主题或模块:
md2wechat themes list --json、md2wechat layout list --json - 已有文章或初稿,不确定下一步是否需要标题、封面或排版:
md2wechat advise <article.md> --json - 已指定某个资源:使用对应的
providers show、themes show、prompts show或layout show - 图片生成或图片 prompt 选择:
md2wechat providers list --json、md2wechat prompts list --kind image --json - 公众号标题建议:
md2wechat title suggest <article.md> --json,必要时再md2wechat prompts show wechat-title-expert --kind title --json - Agent SOP 不确定或需要读取当前版本 skill:
md2wechat skills list --json、md2wechat skills read md2wechat --json - 简单本地操作,例如
preview、humanize或用户已给完整命令和 flags:不要运行无关的 catalog discovery
md2wechat capabilities --json返回内容包含:
- 已开放的高层命令能力
convert支持的模式和默认模式inspect/preview这类确认层命令- 当前可枚举的图片 provider
title_generation的 host-Agent handoff 边界- 当前可枚举的 theme
- 当前可枚举的 prompt catalog
data.article_advice是否可用、命令名、建议工具、响应 code、是否要求 JSON、是否有副作用layoutcatalog 是否可用、模块数量、schema version、是否仅 API 模式渲染skills是否作为当前二进制的内置 Agent SOP 入口开放
示例片段:
{
"article_advice": {
"available": true,
"command": "advise",
"tools": ["title", "cover", "layout", "micro_edit"],
"response_code": "ADVISE_COMPLETED",
"requires_json": true,
"side_effects": false
},
"layout": {
"available": true,
"module_count": 59,
"recommended_syntax_count": 59,
"recommended_scenario_count": 83,
"compatibility_module_count": 2,
"base_enhancement_count": 4,
"render_syntax_count": 65,
"supports_validate": true,
"api_mode_only": true,
"schema_version": "1"
},
"sync": {
"available": true,
"commands": ["sync prepare"],
"execution_owner": "host_agent",
"status": "action_required",
"local_only": true,
"create_draft": false,
"direct_publish": false,
"response_codes": ["SYNC_PREPARED", "SYNC_PREPARE_FAILED"],
"sop": "md2wechat skills read md2wechat references/sync/workflow.md --json"
},
"commands": ["convert", "inspect", "advise", "preview", "layout", "themes", "skills", "sync"]
}未出现在 commands 中的命令不应被 Agent 当成可执行能力。未来工作流不通过 capabilities 预告。
data.sync 只声明本地准备与宿主接手的边界。sync prepare 不创建远端草稿;action_required 表示仍需宿主执行。通过 data.sync.sop 读取公共步骤,再读取其中链接的知乎、CSDN、头条或腾讯云开发者社区说明。平台限制、账号核对和保存后核验均是执行要求,不能把准备完成当作同步成功。
完整流程见 SYNC.md。
md2wechat skills list --json
md2wechat skills read md2wechat
md2wechat skills read md2wechat --jsonskills 命令把 skills/md2wechat/SKILL.md 随二进制一起嵌入,供 Agent 在离线或只拿到二进制的环境中读取当前版本 SOP。这样 Agent 不需要猜 README、联网拉仓库,或读取一个可能和当前 CLI 版本不一致的本地 skill 副本。
skills list 始终返回标准 JSON envelope,包含可用 skill、数量和 frontmatter 摘要。skills read 默认输出原始 Markdown,适合直接喂给 Agent;加 --json 时会返回标准 JSON envelope,并把 Markdown 放在 data.content。
定向产品写作属于宿主工作流。使用 md2wechat skills list md2wechat/references/writing --json 列出资料,再读取 md2wechat skills read md2wechat references/writing/workflow.md --json。没有新增 growth 命令,也没有新增 capabilities 业务字段。缺少该路径表示安装版本未包含资料,不能声称新流程已执行。用法见 WRITING.md。
md2wechat doctor --jsondoctor 是本地只读诊断命令。它检查配置能否加载、默认转换模式、API key 是否存在、默认主题是否兼容当前模式、layout catalog 是否可用、WeChat 草稿凭证是否存在。
它不会调用远程 API,不会验证 live auth,不会上传图片,也不会创建草稿。JSON 输出中的 data.live 固定为 false,data.readiness.format_api / data.readiness.advanced_layout / data.readiness.draft 用来帮助 Agent 判断下一步能不能执行 API 转换、高级排版渲染或草稿创建。
注意:doctor 的 data.readiness.* 是本地配置可尝试性;inspect 的 data.readiness.targets/blockers 是单篇文章的执行目标状态。
md2wechat config wechat-accounts --jsonconfig wechat-accounts 是本地只读命令,用来列出配置文件中的命名公众号账号、当前解析到的账号和 default_account。它不调用 /api/auth/validate,不要求 MD2WECHAT_API_KEY,也不会输出 secret。
命名账号只在上传、生成并上传图片、创建草稿、创建图片消息,以及 convert --upload / convert --draft 等有微信副作用的路径上触发 API-key 校验。
在真正执行 convert、upload、draft 之前,推荐先调用:
md2wechat inspect article.md --json
md2wechat inspect article.md --upload --json
md2wechat inspect article.md --draft --cover ./cover.jpg --json
md2wechat preview article.md --json其中:
inspect只负责结构化 metadata、checks、readiness targets 和 blockers,用来确认最终标题、作者、摘要来源及convert/upload/draft目标状态。- Agent 在决定是否继续
convert、upload、draft前,必须用即将执行的 same publish target 运行inspect,并读取inspect --json的data.readiness.targets和data.readiness.blockers。 inspect的checks会直接暴露语义边界,例如TITLE_BODY_MISMATCH、DIGEST_METADATA_ONLY、IMAGE_REPLACEMENT_REQUIRES_UPLOAD_OR_DRAFT。preview只在 API 转换成功后生成本地 HTML 文件,文件字节与 converter 返回的最终 HTML 完全一致;inspect 诊断只在--json响应的data.inspect中返回,不会混入 HTML。convert负责转换,并且只按显式--upload/--draft请求执行远程副作用。preview --mode ai返回PREVIEW_ACTION_REQUIRED、status: action_required和 prompt,output_file为空;API 失败或空结果返回PREVIEW_FAILED。这些调用不会新建或覆盖预览 HTML;如果显式输出路径已有文件,它仍可能保留陈旧内容,不得视为本次调用的结果。--json走稳定 machine-readable contract;stdout 只保留 JSON,便于 Agent 和脚本直接解析。
md2wechat advise article.md --jsonadvise --json 是只读决策路由器。它根据文章内可观察信号推荐是否调用 title suggest、generate_cover --plan --json,或检查/应用合适的 layout modules;也可能建议人工确认的 micro_edit。
它不生成内容、不写回文件、不上传、不创建草稿。发布前是否可执行仍以 inspect --json 的 data.readiness.targets/blockers 为准。
md2wechat providers list --json
md2wechat providers show openai --json
md2wechat providers show atlascloud --json
md2wechat providers show openrouter --json
md2wechat providers show volcengine --json
md2wechat providers show minimax --jsonproviders list --json 只返回选择下一条命令所需的轻量元数据:
namealiasesdescriptionsupports_sizesupports_subject_referencecurrentconfigured
需要检查某个 provider 的模型或配置要求时,再调用 providers show <name> --json。show 保留上面的身份与状态字段,并返回完整定义:
required_configoptional_configdefault_base_urldefault_modelsupported_models
supported_models 中的每个模型也会带上 supports_subject_reference,用于判断哪些模型可以配合 --subject-reference 使用。
因此,Agent 应先用 list 选择 provider,只在准备配置或调用具体 provider 时读取 show,避免在枚举阶段加载完整模型表。
当前内置支持的图片 provider:
openaiminimaxatlascloud/atlas-cloud/atlastuzimodelscope/msopenrouter/orgemini/googlevolcengine/volc
其中只有 minimax 的 supports_subject_reference 为 true,对应模型为 image-01。
md2wechat themes list --json
md2wechat themes show default --json
md2wechat themes show autumn-warm --json主题信息来自运行时 ThemeManager。同名主题的实际覆盖优先级从高到低为:
~/.config/md2wechat/themes./themesMD2WECHAT_THEMES_DIR- 内置 theme 资产
这意味着纯二进制安装也能列出官方默认主题,用户和平台仍可通过目录覆盖内置主题。
themes list --json 返回的是轻量稳定 view,而不是内部 Go struct。它只包含选主题所需的字段:
nametype:api或aidescriptionversionselectable: 是否可被convert --theme直接选择api_theme: API 服务实际使用的主题名metadata_incomplete: 主题缺少稳定风格字段时为true
themes show <name> --json 返回完整稳定 view,并在这些字段之外提供 style 风格元数据。Agent 应先用 list 按模式和可选状态筛选,只有需要检查具体主题风格时才调用 show。
Collection descriptor 也会出现在发现结果里。例如 api-collection 用于描述 API 主题集合,但它不是可执行主题,所以 selectable: false。api.yaml 中的分组条目会展开为可执行 API 主题。Agent 必须选择 selectable: true 且 type 匹配当前模式的主题。
convert 和 inspect readiness 现在会 fail closed:
--mode api不能选择 AI 主题;--mode ai不能选择 API 主题;selectable: false的主题不能用于转换;--mode ai --custom-prompt是例外路径,custom prompt 本身就是排版提示词来源,不要求主题匹配;检查这个路径时,inspect也要带同样的--custom-prompt。
Prompt catalog 是一组内置并可覆盖的 YAML 资产,当前主要用于:
humanizerwrite的润色流程title suggest的公众号标题候选生成请求generate_image、generate_cover、generate_infographic的图片 preset 渲染
md2wechat prompts list --json
md2wechat prompts list --kind humanizer --json
md2wechat prompts list --kind refine --json
md2wechat prompts list --kind title --json
md2wechat prompts list --kind image --json
md2wechat prompts list --kind image --archetype cover --json
md2wechat prompts list --kind image --archetype infographic --json
md2wechat prompts list --kind image --tag editorial --jsonprompts list --json 只返回选择 prompt 所需的轻量身份与适用性字段:name、kind、description、version,以及存在时的 archetype、primary_use_case、compatible_use_cases、recommended_aspect_ratios、default_aspect_ratio、tags、variables。列表不会返回完整模板正文、示例或来源元数据。
md2wechat prompts show medium --kind humanizer --json
md2wechat prompts show authentic --kind humanizer --json
md2wechat prompts show default --kind refine --json
md2wechat prompts show wechat-title-expert --kind title --json
md2wechat prompts show cover-default --kind image --json
md2wechat prompts show cover-hero --kind image --archetype cover --tag hero --json
md2wechat prompts show infographic-victorian-engraving-banner --kind image --archetype infographic --tag victorian --jsonprompts show <name> --kind <kind> --json 返回完整定义,包括 examples、template、metadata 和 source。只有在需要检查或复用具体模板定义时才调用 show。
对于图片 prompt,archetype 表示主要分组,不代表只能用于这一种场景。优先查看 prompts show --json 返回的:
primary_use_casecompatible_use_casesrecommended_aspect_ratiosdefault_aspect_ratio
这样 Agent 能判断某些信息图 preset 是否也适合作为封面使用。
md2wechat prompts render cover-default \
--kind image \
--var article_title='从 0 到 1 做好公众号封面' \
--var article_summary='一份关于封面图策略的实战清单' \
--jsonprompts render 的 data 包含轻量 prompt 身份、实际使用的 vars 和物化后的 rendered 文本。它不会在 rendered 旁再次复制 template、examples、metadata 或 source;如需原始完整定义,使用 prompts show。
md2wechat generate_image --preset cover-hero --article article.md
md2wechat generate_cover --article article.md
md2wechat generate_cover --article article.md --preset cover-claude-warm
md2wechat generate_cover --article article.md --preset cover-semantic-concept
md2wechat generate_cover --article article.md --preset cover-editorial-collage
md2wechat generate_cover --article article.md --preset cover-suspense-black-gold
md2wechat generate_infographic --article article.md --preset infographic-comparison
md2wechat generate_infographic --article article.md --preset infographic-claude-warm
md2wechat generate_infographic --article article.md --preset infographic-ticket-process
md2wechat generate_infographic --article article.md --preset infographic-dark-ticket-cn --aspect 21:9
md2wechat generate_infographic --article article.md --preset infographic-handdrawn-sketchnote
md2wechat generate_infographic --article article.md --preset infographic-apple-keynote-premium
md2wechat generate_infographic --article article.md --preset infographic-victorian-engraving-banner --aspect 21:9
md2wechat generate_image --preset cover-hero --article article.md --model gemini-3-pro-image-preview高频图片命令和 prompt catalog 的关系是:
generate_image: 通用入口,可直接传 raw prompt,也可用--presetgenerate_cover:coverarchetype 的薄包装命令generate_infographic:infographicarchetype 的薄包装命令- 三个图片命令都支持
--model,用于单次覆盖本次调用的图片模型
如果某个图片 preset 的 compatible_use_cases 包含 cover,那么它也可以被 generate_cover 使用;默认画幅优先跟随 prompt 自身声明的 default_aspect_ratio。
当当前 Agent 运行时暴露 Image Gen 工具时,可以让图片命令只返回计划,交给宿主 Agent 执行:
md2wechat generate_cover --article article.md --plan --json
md2wechat generate_infographic --article article.md --preset infographic-comparison --plan --json
md2wechat generate_image "一张适合公众号文章的产品发布插画" --plan --jsonJSON envelope 会返回 IMAGE_PLAN_READY 和 status: action_required。关键执行边界在 data 中:
side_effects:falserequires_provider:falserequires_image_api_key:falseexecution_owner:"host_agent"
这条路径不要求或使用 IMAGE_API_KEY 进行图片 provider 调用,不请求 provider,也不上传微信。完整教程见 Agent 图片计划模式。
title suggest 会读取文章内容,渲染内置标题 prompt,然后返回一个需要宿主 Agent / 外部模型继续执行的 JSON 请求:
md2wechat title suggest article.md --json
md2wechat title suggest article.md --target-reader "独立开发者" --count 10 --max-title-chars 25 --hook-level 2 --jsonJSON envelope 会返回 TITLE_SUGGEST_REQUEST_READY 和 status: action_required。关键执行边界在 data 中:
action:"ai_title_suggestion_request"execution_owner:"host_agent"prompt_kind:"title"prompt_name:"wechat-title-expert"hook_level:1|2|3hook_level_label:"restrained"|"punchy"|"high_tension"side_effects:falserequires_external_model:truerecommendation_only:true
这条路径不会调用模型、不会写回 Markdown、不会创建草稿,也不会自动替用户确认最终标题。Agent 应读取 data.prompt,让外部模型生成候选标题,再把候选交给用户确认或在自己的上层流程中选择最高分。
md2wechat capabilities --json 的 data.title_generation 会暴露标题能力边界:
hook_levels:三个对象{level,label,description}default_hook_level:1max_recommended_hook_level:2level_3_requires_evidence_basis:true
这些字段只描述 host-Agent handoff 的请求能力,不表示 CLI 会本地生成标题、调用模型、选择最终标题或写回文章。
完整的人类/Agent 工作流、--hook-level 选择建议和候选 JSON 字段说明见 公众号标题建议。
当前内置 prompt kind:
humanizerrefinetitleimage
当前内置图片 archetype 分组:
coverinfographic
完整的内置与覆盖后图片 preset 清单不在文档中重复维护,请直接运行:
md2wechat prompts list --kind image --json
md2wechat prompts list --kind image --archetype cover --json
md2wechat prompts list --kind image --archetype infographic --json需要按视觉方向筛选时使用 tag,例如:
md2wechat prompts list --kind image --tag warm-editorial --json
md2wechat prompts list --kind image --tag semantic --json
md2wechat prompts list --kind image --tag collage --json
md2wechat prompts list --kind image --tag suspense --json
md2wechat prompts list --kind image --tag ticket-process --jsonprompts show <name> --kind image --json 返回该 preset 的用途、推荐画幅、默认画幅、变量、来源和完整模板。
Prompt catalog 的加载优先级为:
MD2WECHAT_PROMPTS_DIR./prompts~/.config/md2wechat/prompts- 内置 prompt 资产
也就是说,官方默认 prompt 会随二进制一起提供;用户和平台如需自定义,可按上面的顺序覆盖。
目前已经优先使用 prompt catalog 的能力有:
humanizewrite的润色流程title suggestgenerate_image --presetgenerate_covergenerate_infographic
当前仍然主要依赖代码或其他资产的部分:
convert的 API/AI 调用逻辑- 图片数量、插入位置、多候选选择等更高层视觉资产编排
扩展封面或信息图时,应优先新增 internal/assets/builtin/prompts/image/*.yaml,不要把长提示词写进 Go 代码。运行时完整清单始终以 md2wechat prompts list --kind image --json 为准。
The layout subcommand exposes 59 个主推 advanced WeChat layout syntax names (:::module) by default. Capability discovery separately reports 83 个主推高级排版场景条目, 2 个兼容模块, 4 个基础增强能力, and 65 项渲染层语法能力; these counts are not interchangeable. The 83 scenarios are source-use-case mappings, while the 59 names are the default CLI discovery objects. The CLI does not publish the test-only scenario mapping.
# List all built-in modules
md2wechat layout list --json
# Filter by purpose (serves one of: attention | readability | memorability | conversion)
md2wechat layout list --serves attention --json
md2wechat layout list --category opening --json
md2wechat layout list --tag brand --json
# Show full spec (fields, serves, when_to_use, example, metadata)
md2wechat layout show hero --json
# Render a :::module block from structured vars
md2wechat layout render hero \
--var eyebrow=深度观察 \
--var title="公众号排版的真问题" \
--json
# Validate :::module usage in a Markdown file
md2wechat layout validate --file article.md --json
md2wechat layout validate --stdin --json < article.mdlayout 内置 catalog 是唯一事实源,不读取用户目录、项目目录或环境变量中的模块 YAML。layout list --json 会在模块摘要中显示 body_format;layout show --json 会显示完整 schema、canonical Example 和结构不同的 Variants[].Example。Schema 定义合法输入;Example 是经过验证的可执行 witness,应复用而不是手猜语法。正文格式共有 fields / rows / json_object / json_array / markdown_images / markdown_fields / fields_markdown / split / lines / dialogue 十种;fields_markdown 用于 expand 的头部字段、独立 --- 和非空 Markdown 正文,围栏代码中的分隔符保持原样;compatible_body_formats 只表示模块仍接受的旧正文格式。
新内容的固定读取顺序是:input_positions → primary body_format 与对应 Opener、Fields / Rows / Body → canonical Variants[].Name → canonical Example。compatible_body_formats 和 Variants[].Aliases 都是只读 compatibility facts,只用于理解旧稿,不能作为新内容的选择项。
默认 layout list --json 只返回 recommended lifecycle,其中包括 gallery。旧稿迁移时才运行 layout list --lifecycle compatibility --json;dialogue、longimage 不推荐给新稿。复杂正文使用 layout render <name> --body-file <path>(或 --body-file - 从 stdin 读取),opener 参数用可重复的 --param KEY=VALUE,方括号 caption 用 --caption。cover-reveal 和 expand 默认完整静态展示;first-layer 是显式点击候选,微信内行为待验证。
品牌符号和动效以分别运行 layout show <name> --json(<name> 依次取 hero、section-title、closing、author-card)得到的 symbol / motion 字段为准。新品牌符号有 12 种;四个位置的 motion enum 与适用范围不同,value_applies_to 和 symbol_keys_by_value 指明哪些组合实际生效。不要把 API 的静态回退当成动效成功。
When the user says "帮我排版这篇文章" without naming a theme or module, run discovery first, then use layout list, layout show, and layout render as primitives. The CLI does not parse ~/.config/md2wechat/brand.md; Agents should read Brand Profile themselves and choose the final theme/modules. Keep the source Markdown read-only: create a temporary formatted Markdown artifact, validate it with layout validate, then pass that temporary file to convert. Saving generated Markdown near the source requires explicit user confirmation.
| Value | Purpose |
|---|---|
attention |
让读者知道值不值得读(hero, cards, verdict, audience-fit) |
readability |
让手机阅读不累(part, toc, steps, label-title) |
memorability |
让读者记住一个判断/品牌(verdict, manifesto, author-card) |
conversion |
让读者收藏/关注/咨询/转发/购买(cta, subscribe, faq, cases) |
layout validate reports warnings (not errors) for unknown module names. This allows forward-compatible documents where new modules are used before a CLI upgrade. Only known modules with missing required fields produce errors (exit 1).
| Code | Meaning |
|---|---|
LAYOUT_MODULE_NOT_FOUND |
Named module does not exist in catalog |
LAYOUT_INVALID_FILTER |
Missing required input (e.g., neither --file nor --stdin) |
LAYOUT_MISSING_REQUIRED_FIELD |
Required field absent in render call |
LAYOUT_INVALID_FIELD_VALUE |
Field value not in allowed enum |
LAYOUT_VALIDATE_HAS_ERRORS |
Validation found errors (exit 1) |
LAYOUT_VALIDATED |
Validation passed clean (exit 0) |
发现命令不会替代配置文件,但会帮助 Agent 确认:
- 当前默认 provider 是什么
- 当前 provider 是否已配置
- 当前是否存在某个 theme / prompt
- 当前 theme 是否可直接选择,是否匹配
api/ai模式 - 高级排版模块 catalog 是否可用
- 每个高级排版模块的
body_format和compatible_body_formats,即正文应采用十种受支持格式中的哪一种 - 尚未发布的工作流是否只是声明为
available: false
配置主路径仍然是:
~/.config/md2wechat/config.yaml
如需切换 API 域名、图片 provider 或其它默认值,请先看 CONFIG.md。