md2wechat

用 Markdown 写公众号文章，像发朋友圈一样简单

快速开始 • Coding Agent • Obsidian / Claudian • OpenClaw • 功能介绍 • 使用说明 • 常见问题

---

立即开始

如果你第一次接触 md2wechat，先按这个顺序走：

• 如果你是 mac 用户，优先用 Homebrew 安装 CLI：brew install geekjourneyx/tap/md2wechat
• 如果你已经有稳定可用的 Node/npm 环境，也可以直接全局安装 CLI：npm install -g @geekjourneyx/md2wechat
• 如果你已经有稳定可用的 Go 环境，也可以选 go install github.com/geekjourneyx/md2wechat-skill/cmd/md2wechat@v2.0.7
• 想直接安装 CLI：看 安装指南
• 想申请 API 服务或咨询：扫描文末公众号二维码联系，备注「API咨询」
• 想先看支持的主题 / 图片 prompt / provider：执行 discovery 命令
• 想在 Claude Code / Codex / OpenCode 等 Coding Agent 里使用：先安装 CLI，再执行 npx skills add
• 想在 Obsidian 的 Claudian 插件里使用：先安装 CLI，再执行 npx skills add，然后看 Obsidian / Claudian 指南

# 查看当前实例支持什么
md2wechat capabilities --json
md2wechat themes list --json
md2wechat prompts list --kind image --json
md2wechat providers list --json
任选一种方式先安装 CLI，再在 Coding Agent 中安装 skill
npm install -g @geekjourneyx/md2wechat
curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash
安装 skill
npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

直接发给 Agent

如果你不想自己组织命令，可以直接把下面的话发给 Claude Code / Codex / OpenCode 等 Agent：

请帮我安装 md2wechat 并验证可用。按这个顺序执行：
1. 运行：curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash
2. 运行：npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat
3. 运行：export PATH="$HOME/.local/bin:$PATH"
4. 运行：md2wechat version --json
5. 运行：md2wechat config init
6. 运行：md2wechat capabilities --json
如果某一步失败，请直接告诉我失败原因和下一步修复命令，不要省略命令。

如果你在 OpenClaw 里使用，可以直接发：

请帮我安装 OpenClaw 版 md2wechat，并验证 CLI 和 skill 都可用。按这个顺序执行：
1. 运行：curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install-openclaw.sh | bash
2. 运行：export PATH="$HOME/.local/bin:$PATH"
3. 运行：md2wechat version --json
4. 运行：md2wechat config init
5. 运行：md2wechat capabilities --json
6. 如果我已经装过 skill，再检查：~/.openclaw/skills/md2wechat/ 是否存在，并确认 `command -v md2wechat` 有输出
如果某一步失败，请直接告诉我失败原因和下一步修复命令，不要省略命令。

先看这里

• convert 默认走 API 模式，需要你自己的 md2wechat.cn API Key；如需咨询或申请测试，扫描文末公众号二维码联系，备注「API咨询」
• AI 模式不需要 md2wechat.cn API Key，但当前 CLI 返回的是 AI request / prompt，需要由 Claude Code / Codex / OpenAI 等外部模型继续完成 HTML
• 主题、图片 prompt、provider 不要靠猜，先执行 md2wechat themes list --json、md2wechat prompts list --kind image --json、md2wechat providers list --json
• 安装、配置和校验入口分别看：安装指南 / 配置指南 / 能力发现

5分钟快速上手

第一步：安装工具

推荐先看 安装指南。如果你只想快速开始：

• mac 用户：优先使用 Homebrew
• 已有 Node/npm 环境：可以直接用 NPM 全局安装
• 已有 Go 环境：也可以使用 go install
• 其他环境：优先使用固定版本 install.sh

brew install geekjourneyx/tap/md2wechat

如果你更常用 Node/npm，也可以直接安装：

npm install -g @geekjourneyx/md2wechat

NPM 包不会在本地重新编译 Go 项目。它会下载与包版本同号的 GitHub Release 二进制，并校验同一个 checksums.txt，因此和 Homebrew / install.sh 复用同一套发布产物。

当前 npm 安装目标矩阵：

• macOS: amd64 / arm64
• Linux: amd64 / arm64
• Windows: amd64

如果你的 npm 默认走 https://registry.npmmirror.com，而刚发布的新版本还没同步过去，可能会出现 tarball 404。这种情况下先改用官方源安装：

npm install -g @geekjourneyx/md2wechat --registry=https://registry.npmjs.org/

如果你不用 Homebrew，或者想走固定版本 release + checksum 路径，再用安装脚本：

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash

默认会安装到用户级目录：

• macOS / Linux: ~/.local/bin/md2wechat
• Windows: 当前用户目录或 C:\Program Files\md2wechat\md2wechat.exe

如果脚本执行完后当前终端仍然提示 command not found: md2wechat，先执行：

export PATH="$HOME/.local/bin:$PATH"
md2wechat version --json

Windows PowerShell：

$env:MD2WECHAT_RELEASE_BASE_URL = "https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7"
iex ((New-Object System.Net.WebClient).DownloadString("$env:MD2WECHAT_RELEASE_BASE_URL/install.ps1"))

如果你主要在 Claude Code / Codex / OpenCode 等 Coding Agent 中使用，推荐先安装 CLI，再安装 skill。mac 用户优先用 Homebrew：

brew install geekjourneyx/tap/md2wechat

如果你已经有 Go 环境，也可以改成：

go install github.com/geekjourneyx/md2wechat-skill/cmd/md2wechat@v2.0.7

然后安装 skill：

npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

如果你要直接发给 Agent，建议把这句也带上：

如果 install.sh 执行完后当前终端仍然提示 command not found: md2wechat，请继续执行：
export PATH="$HOME/.local/bin:$PATH"
md2wechat version --json

手动下载 release 资产时，请同时校验 checksums.txt。主路径应始终指向固定版本的 release，不要使用 latest 或 main 作为安装入口。

第二步：配置微信（只需一次）

md2wechat config init

用记事本打开生成的配置文件（会显示路径），填入两个信息：

第一次接微信开发，建议直接看：

• 微信凭证与 IP 白名单指南

里面单独讲清楚了：

• AppID / AppSecret 去哪里拿
• IP 白名单怎么配
• 为什么白名单没配时会报错
• 配好后怎么一步步验证

第三步：开始使用

# 1. 用 Markdown 写好文章（假设文件叫 article.md）
2. 先确认系统最终会怎么理解这篇文章
md2wechat inspect article.md
3. 生成本地 HTML 预览文件
md2wechat preview article.md
4. 需要时再预览 convert 输出或创建草稿
md2wechat convert article.md --preview
md2wechat convert article.md --draft --cover cover.jpg

小贴士：inspect 负责解释最终 metadata / readiness，preview 负责本地确认视觉结果；它们都不会触发上传或草稿副作用。

这是什么？

md2wechat 是一个让你的微信公众号写作更高效的神器。

一句话理解：用 Markdown 写文章 → 一键转换 → 自动发到微信草稿箱

适合谁用？

站点入口

• 国际站: md2wechat.com
• 国内站 / API 主站: md2wechat.cn
• GitHub 项目: geekjourneyx/md2wechat-skill

关于作者

这个项目由 geekjourneyx 维护。

• 独立开发者 / AI Builder / AI 科技领域博主
• 持续打磨面向 AI Agent 的 CLI、API 与自动化工作流
• 相关项目和长期方向可见 GitHub 主页: github.com/geekjourneyx/geekjourneyx

核心功能

flowchart LR
    A[用 Markdown 写文章] --> B{选择模式}
B -->|API 模式| C[调用 md2wechat.cn API]
C --> D[获取 HTML]

B -->|AI 模式| E[生成 AI request]
E --> F[由 Claude 等继续生成 HTML]

D --> G[预览效果]
F --> G

G --> H{满意吗}
H -->|不满意| B
H -->|满意| I[上传图片]
I --> J[发送到微信草稿箱]
J --> K[完成]

classDef nodeA fill:#e3f2fd,stroke:#2196f3,color:#0d47a1
classDef nodeE fill:#fff3e0,stroke:#ff9800,color:#e65100
classDef nodeJ fill:#e8f5e9,stroke:#4caf50,color:#1b5e20
classDef nodeK fill:#c8e6c9,stroke:#4caf50,color:#1b5e20

class A nodeA
class E nodeE
class J nodeJ
class K nodeK

五大核心功能

write 与 convert 的区别：

简单理解：

• write = 帮你写文章（从想法到完整文章）
• convert = 帮你排版（从 Markdown 到微信格式）

两种转换模式

完整工作流程

flowchart LR
    A1[Markdown 写作] --> A2[插入图片]
    A2 --> B1{选择模式}
B1 -->|API| B2[md2wechat.cn]
B1 -->|AI| B3[生成 AI request]

B2 --> B4[HTML 生成]
B3 --> B4[由 Claude 等继续生成 HTML]

B4 --> C1[预览效果]
C1 --> C2{满意吗}

C2 -->|调整| B1
C2 -->|OK| C3[上传图片]
C3 --> C4[发送草稿]
C4 --> C5[完成]

classDef write fill:#e3f2fd,stroke:#2196f3,color:#0d47a1
classDef ai fill:#fff3e0,stroke:#ff9800,color:#e65100
classDef done fill:#e8f5e9,stroke:#4caf50,color:#1b5e20
classDef success fill:#c8e6c9,stroke:#4caf50,color:#1b5e20

class A1,A2 write
class B3 ai
class C4,C5 done

使用方法

基础命令

# 先检查最终标题/摘要/发布风险
md2wechat inspect article.md
生成本地预览 HTML（输出文件路径）
md2wechat preview article.md
预览转换效果（不发送）
md2wechat convert article.md --preview
转换并保存为 HTML 文件
md2wechat convert article.md -o output.html
使用 AI 模式生成精美排版
md2wechat convert article.md --mode ai --theme autumn-warm --preview
显式覆盖标题、作者、摘要
md2wechat convert article.md --title "新标题" --author "作者名" --digest "摘要"

文章元数据

convert 的文章元数据优先级如下：

• 标题：--title -> frontmatter.title -> 正文首个 Markdown 标题 -> 未命名文章
• 作者：--author -> frontmatter.author
• 摘要：--digest -> frontmatter.digest -> frontmatter.summary -> frontmatter.description

长度限制：

• 标题最多 32 个字符
• 作者最多 16 个字符
• 摘要最多 128 个字符

如果创建草稿时摘要仍为空，草稿层会从正文 HTML 生成一个 120 字符兜底摘要。convert 不会自动移除正文里的一级标题，所以同一个 H1 可能既作为草稿标题来源，也继续出现在文章正文里。

确认层命令

在真正执行 convert / --draft 之前，推荐先走确认层：

# 看系统最终会如何解释这篇文章
md2wechat inspect article.md
生成本地预览 HTML 文件
md2wechat preview article.md

说明：

• inspect 会输出最终标题、作者、摘要来源，以及 upload/draft readiness 和风险检查。
• inspect 还会显式暴露一些常见误解，例如 TITLE_BODY_MISMATCH、DIGEST_METADATA_ONLY、IMAGE_REPLACEMENT_REQUIRES_UPLOAD_OR_DRAFT。
• preview 第一版会生成一个本地 HTML 文件，不会启动重工作台，也不会触发上传或草稿副作用。
• preview --mode ai 不会伪造最终视觉稿；它会明确标注当前只是 AI request / prompt，页面只作为确认层预览。
• --title / --author / --digest 控制的是微信草稿 metadata；它们不保证直接改变正文里可见的 H1、作者行或摘要段落。
• Markdown 图片只有在 --upload 或 --draft 流程中才会被上传并替换为已发布 URL；纯 convert --preview 只预览正文输出。
• --json 命令约定 stdout 只输出 JSON，适合 Agent 和脚本直接消费。

Agent 可发现命令

如果你是 Agent、自动化脚本，或者想先确认当前实例支持哪些能力，先执行这些命令：

# 总览当前 CLI 能力、默认模式、可用资源
md2wechat capabilities --json
看文章最终 metadata 与 readiness
md2wechat inspect article.md --json
查看图片 provider
md2wechat providers list --json
查看可用主题
md2wechat themes list --json
查看内置 Prompt Catalog
md2wechat prompts list --json
md2wechat prompts list --kind image --json
md2wechat prompts list --kind image --archetype cover --json

需要查看具体资源时，可继续用：

md2wechat providers show openrouter --json
md2wechat providers show volcengine --json
md2wechat themes show autumn-warm --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 --json

Prompt 模板也可以直接渲染：

md2wechat prompts render cover-default \
  --kind image \
  --var article_title='从 0 到 1 做好公众号封面' \
  --var article_summary='一份关于封面图策略的实战清单' \
  --json

详细说明见 docs/DISCOVERY.md。

图片 prompt 的底层统一归类为 kind=image。cover 和 infographic 是主要用途分组，不是两套独立系统。判断某个 preset 能否兼作封面或信息图时，优先看 prompts show --json 返回的 primary_use_case、compatible_use_cases、recommended_aspect_ratios 和 default_aspect_ratio。

风格写作

# 查看所有可用写作风格
md2wechat write --list
用 Dan Koe 风格写文章（交互模式）
md2wechat write
用指定风格写文章，从观点生成
md2wechat write --style dan-koe
润色现有文章
md2wechat write --style dan-koe --input-type fragment article.md
生成匹配的封面提示词
md2wechat write --style dan-koe --cover-only
同时生成文章和封面
md2wechat write --style dan-koe --cover

写作风格说明：

如何添加自定义风格：

在 writers/ 目录下创建 YAML 文件即可，格式参考 writers/dan-koe.yaml。

Prompt Catalog

除了 themes/ 和 writers/，项目现在还提供内置 Prompt Catalog，用于承载：

• humanize 的强度模板
• write 的润色模板
• 后续扩展的图片 archetype，例如封面图、信息图、配图

当前内置 prompt kind：

• humanizer
• refine
• image

Prompt 覆盖顺序：

• MD2WECHAT_PROMPTS_DIR
• ./prompts
• ~/.config/md2wechat/prompts
• 内置 prompt 资产

这意味着纯二进制安装也能用默认 prompt，而用户和平台仍然可以覆盖。

风格写作工作原理

┌─────────────────────────────────────────────────────────────────────┐
│                      风格写作 (write 命令)                           │
│                                                                       │
│  你只需要提供一个想法 → AI 自动生成符合特定创作者风格的文章            │
│                                                                       │
└─────────────────────────────────────────────────────────────────────┘

核心概念：

完整工作流程：

flowchart LR
    A[你提供想法] --> B{选择写作风格}
    B --> C[构建结构化提示词]
C --> D{AI 处理}
D --> E[生成完整文章]

E --> F{需要封面?}
F -->|是| G[生成封面提示词]
F -->|否| H[输出文章]

G --> I[用 AI 生成封面图]
I --> J[上传到微信素材库]
H --> K[转换为微信格式]
J --> K
K --> L[发送到草稿箱]

classDef idea fill:#e3f2fd,stroke:#2196f3,color:#0d47a1
classDef creator fill:#fff3e0,stroke:#ff9800,color:#e65100
classDef ai fill:#f3e5f5,stroke:#9c27b0,color:#4a148c
classDef output fill:#e8f5e9,stroke:#4caf50,color:#1b5e20

class A idea
class B,C creator
class D,E,G,I ai
class H,J,K,L output

输入类型说明：

输出说明：

{
  "success": true,
  "code": "WRITE_AI_REQUEST_READY",
  "schema_version": "v1",
  "status": "action_required",
  "retryable": false,
  "data": {
    "mode": "ai",
    "action": "ai_write_request",
    "style": "Dan Koe",
    "prompt": "结构化的写作提示词...",
    "cover_prompt": "封面提示词..."
  }
}

重要说明：write 命令默认使用 AI 模式，返回的是结构化提示词，需要由 Claude 等 AI 大模型处理才能生成最终文章。在 Claude Code 中使用时，这个流程是自动的。

从想法到发布的完整流程：

flowchart TB
    subgraph Phase1["阶段1：创作"]
        A1[你的想法] --> A2[选择写作风格]
        A2 --> A3[AI 生成文章]
        A3 --> A4[生成封面提示词]
    end
subgraph Phase2["🎨 阶段2：制作"]
    B1[AI 生成封面图] --> B2[上传到微信素材库]
    A4 --> B1
    A3 --> B3[保存为 Markdown]
end

subgraph Phase3["📤 阶段3：发布"]
    C1[转换为微信格式] --> C2[发送到草稿箱]
    B2 --> C1
    B3 --> C1
    C2 --> C3[在微信编辑器中微调]
    C3 --> C4[发布！]
end

classDef phase1 fill:#e3f2fd,stroke:#2196f3,color:#0d47a1
classDef phase2 fill:#fff3e0,stroke:#ff9800,color:#e65100
classDef phase3 fill:#e8f5e9,stroke:#4caf50,color:#1b5e20

class A1,A2,A3,A4 phase1
class B1,B2,B3 phase2
class C1,C2,C3,C4 phase3

一条命令完成全流程（在 Claude Code 中）：

"用 Dan Koe 风格写一篇关于 AI 时代程序员怎么搞钱的文章，生成封面，并发送到微信草稿箱"

Claude 会自动：

1. 调用 write 命令生成文章和封面提示词
2. 用 AI 生成封面图并上传
3. 转换为微信格式
4. 发送到草稿箱

AI 写作去痕

致谢：AI 写作去痕功能基于 Humanizer-zh 项目，感谢作者 臧师傅 的分享。

什么是 AI 去痕？

AI 生成的文章往往有明显的"AI 味"——公式化的表达、重复的结构、浮夸的词汇。AI 去痕功能可以识别并去除这些痕迹，让文章听起来更像真人写的。

能检测哪些 AI 痕迹？

三种处理强度：

使用方法：

# 独立使用：去除文章的 AI 痕迹
md2wechat humanize article.md
指定强度
md2wechat humanize article.md --intensity aggressive
显示修改对比和质量评分
md2wechat humanize article.md --show-changes
输出到文件
md2wechat humanize article.md -o output.md

与写作风格组合使用：

# 写作 + 去痕：生成文章后自动去除 AI 痕迹
md2wechat write --style dan-koe --humanize
指定去痕强度
md2wechat write --style dan-koe --humanize --humanize-intensity aggressive

风格优先原则：当与写作风格组合时，会保留风格的核心特征（如 Dan Koe 的破折号），只去除无意的 AI 痕迹。

AI 去痕工作流程：

flowchart LR
    A[AI 生成的文章] --> B[识别 AI 痕迹模式]
    B --> C{检测到问题}
C --> D[过度强调意义]
C --> E[AI 词汇]
C --> F[三段式结构]
C --> G[填充短语]
C --> H[协作痕迹]

D --> I[重写为自然表达]
E --> I
F --> J[打破公式结构]
G --> I
H --> K[删除客套话]

I --> L[注入真实观点]
J --> L
K --> L

L --> M[变化句子节奏]
M --> N[人性化后的文章]

N --> O{需要评分?}
O -->|是| P[5维度质量评分]
O -->|否| N

P --> Q[输出结果]

classDef ai fill:#ffebee,stroke:#f44336,color:#c62828
classDef problem fill:#fff3e0,stroke:#ff9800,color:#e65100
classDef fix fill:#e3f2fd,stroke:#2196f3,color:#0d47a1
classDef result fill:#e8f5e9,stroke:#4caf50,color:#1b5e20

class A ai
class B,C,D,E,F,G,H problem
class I,J,K,L,M fix
class N,P,Q result

质量评分系统：

去除 AI 痕迹后，会给出 5 维度评分（总分 50）：

评级标准：

• 45-50 分：优秀，已去除 AI 痕迹
• 35-44 分：良好，仍有改进空间
• 低于 35 分：需要重新修订

去痕效果对比：

自然语言使用（在 Claude Code 中）：

"去除这篇文章的 AI 痕迹"
"让这篇文章听起来更像人写的"
"用温和强度处理这篇文章"
"用 Dan Koe 风格写一篇文章，然后去除 AI 痕迹"

完整发布流程

# 一步到位：转换 + 上传图片 + 发送草稿
md2wechat convert article.md --draft --cover cover.jpg
md2wechat convert article.md --draft --cover-media-id PERMANENT_MEDIA_ID
流程说明：
1. 将 Markdown 转换为微信格式 HTML
2. 如果传了 --cover，则上传封面图片到微信素材库
3. 如果传了 --cover-media-id，则直接复用已有封面素材
4. 创建草稿并推送到微信后台

AI 模式主题选择

API 模式主题选择

精确主题清单以运行时 discovery 输出为准：

md2wechat themes list --json

下面内容主要用于帮助理解主题分组和风格差异。

主题预览

完整主题预览: https://md2wechat.app/theme-gallery

主题分类

基础主题（6 个） - v1.0 内置

Minimal 系列（8 个） - 干净克制，纯色文字无装饰

Focus 系列（8 个） - 居中对称，标题上下双横线

Elegant 系列（8 个） - 层次丰富，左边框递减 + 渐变背景

Bold 系列（8 个） - 视觉冲击，标题满底色 + 圆角投影

主题命名规则

<系列>-<颜色>
系列:
minimal  - 干净克制
focus    - 居中对称
elegant  - 层次丰富
bold     - 视觉冲击
颜色: gold, green, blue, orange, red, navy, gray, sky

使用示例

# 使用 Elegant 金色主题
md2wechat convert article.md --theme elegant-gold --preview
使用 Minimal 蓝色主题
md2wechat convert article.md --theme minimal-blue --draft --cover cover.jpg
使用 Bold 红色主题（视觉冲击强）
md2wechat convert article.md --theme bold-red

提示: 某些 API 主题能力依赖当前 API 域名与服务版本，先看 md2wechat themes list --json 的实际输出。

背景类型选择

除了主题，你还可以自定义背景样式：

使用示例：

# 使用网格背景
md2wechat convert article.md --theme elegant-gold --background-type grid
使用无背景（适合复制到其他编辑器）
md2wechat convert article.md --theme minimal-blue --background-type none
组合使用
md2wechat convert article.md --theme focus-green --background-type grid --draft --cover cover.jpg

默认值是 none。只有在需要显式背景时才传 --background-type default 或 --background-type grid。

配置文件设置：

# ~/.config/md2wechat/config.yaml
api:
  background_type: none  # default/grid/none

图片处理

# 上传单张图片到微信素材库
md2wechat upload_image photo.jpg
下载网络图片并上传
md2wechat download_and_upload https://example.com/image.jpg
AI 生成图片并上传（需要配置 IMAGE_API_KEY）
md2wechat generate_image "A cute cat sitting on a windowsill"
用内置封面 preset 生成封面图
md2wechat generate_cover --article article.md
用内置信息图 preset 生成信息图
md2wechat generate_infographic --article article.md --preset infographic-comparison
生成暗黑票券风中文信息图（推荐 21:9）
md2wechat generate_infographic --article article.md --preset infographic-dark-ticket-cn --aspect 21:9
生成手绘 sketchnote 信息图
md2wechat generate_infographic --article article.md --preset infographic-handdrawn-sketchnote
生成苹果发布会风格信息图（默认 3:4，也可兼作封面）
md2wechat generate_infographic --article article.md --preset infographic-apple-keynote-premium
生成维多利亚黑白版画横幅信息图（也可兼作封面，推荐 21:9）
md2wechat generate_infographic --article article.md --preset infographic-victorian-engraving-banner --aspect 21:9
生成 16:9 比例的封面图（推荐，适配公众号封面）
md2wechat generate_image --preset cover-hero --article article.md --size 2560x1440
单次覆盖本次调用使用的图片模型
md2wechat generate_infographic --article article.md --preset infographic-comparison --model gemini-3-pro-image-preview

公众号封面图建议：使用 16:9 横向比例（2560x1440）作为文章封面，在微信 feed 流和文章列表中显示效果更好。方形图片（2048x2048）在预览时会被裁剪。

AI 图片生成服务配置

支持多种 AI 图片生成服务：

配置方式（环境变量或配置文件）：

# 使用 ModelScope（推荐，有免费额度）
export IMAGE_PROVIDER=modelscope
export IMAGE_API_KEY=ms-your-token-here
export IMAGE_API_BASE=https://api-inference.modelscope.cn
export IMAGE_MODEL=Tongyi-MAI/Z-Image-Turbo

# config.yaml
api:
  image_provider: modelscope
  image_key: ms-your-token-here
  image_base_url: https://api-inference.modelscope.cn
  image_model: Tongyi-MAI/Z-Image-Turbo
  image_size: 1024x1024

--model 可覆盖当前命令的图片模型；未传时，优先使用 IMAGE_MODEL，再回退到 api.image_model，最后才是 provider 默认模型。 md2wechat providers show <name> --json 现在会同时暴露 supported_models，适合 Agent 或脚本先确认模型目录再选 --model。 如果 Volcengine 返回 ModelNotOpen，去 豆包大模型 点击“控制台” -> “开通管理”，勾选 Seedream 模型完成开通。

ModelScope 特点：

• 有免费额度，适合测试
• 国内服务，访问稳定
• 默认模型 Tongyi-MAI/Z-Image-Turbo 生成速度快
• 使用异步 API（task_id + 轮询），约 10-30 秒完成

Markdown 中生成图片

在 Markdown 中使用特殊语法生成图片：

![产品概念图](__generate:现代智能家居设备，白色简约设计，LED指示灯__)

语法格式： ![描述](__generate:提示词__)

• 支持中文和英文提示词
• 生成的图片会自动上传到微信素材库
• 需要配置图片生成服务（详见 图片服务配置文档）

在 Claude Code 中使用自然语言：

"帮我在文章开头生成一张产品概念图"
"在第三段后添加一张对比图"
"生成一张可爱的猫"（独立生成，不关联文章）

AI 模式详解

什么是 AI 模式？

AI 模式当前会生成用于外部大模型继续处理的排版请求，而不是像 API 模式那样直接在本地返回最终 HTML。

┌─────────────────────────────────────────────────────────────┐
│                     AI 模式工作流程                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   1. 你用 Markdown 写文章                                    │
│              ↓                                               │
│   2. md2wechat 提取文章结构                                  │
│              ↓                                               │
│   3. 构建专业的排版提示词 (Prompt)                           │
│              ↓                                               │
│   4. 输出 AI request / Prompt                              │
│              ↓                                               │
│   5. 在 Claude Code 等环境中继续生成 HTML                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

AI 模式的优势

在 Claude Code 中使用 AI 模式

如果你使用 Claude Code，AI 模式生成的 request / prompt 可以继续由 Claude 自动接力处理：

# 在 Claude Code 中直接运行
md2wechat convert article.md --mode ai --theme autumn-warm

配置说明

配置文件位置

~/.config/md2wechat/config.yaml    # 全局配置（推荐）

生成示例配置：

md2wechat config init

查看当前实际生效配置：

md2wechat config show --format json

配置项说明

# 微信公众号配置（必需）
wechat:
  appid: "你的AppID"
  secret: "你的Secret"
API 配置
api:
md2wechat_key: "md2wechat.cn 的 API Key"  # API 模式需要
md2wechat_base_url: "https://www.md2wechat.cn"  # 可改成 https://md2wechat.app
convert_mode: "api"                       # 配置展示/兼容字段；不传 --mode 时 CLI 仍默认 api
default_theme: "default"                  # 默认主题
http_timeout: 30                          # 超时时间（秒）
图片处理配置
image:
compress: true           # 自动压缩大图
max_width: 1920         # 最大宽度
max_size_mb: 5          # 最大文件大小（MB）

如果你不知道 API 域名在哪里改，就改这里：

• 配置文件：api.md2wechat_base_url
• 环境变量：MD2WECHAT_BASE_URL

默认主题和默认写作风格已经内置在二进制里。 如果你要覆盖它们，优先级从高到低是：

• MD2WECHAT_THEMES_DIR / MD2WECHAT_WRITERS_DIR
• 当前项目目录下的 themes/ / writers/
• ~/.config/md2wechat/themes/ / ~/.config/md2wechat/writers/
• 二进制内置默认资产

更完整的保姆级说明见：

• 配置指南
• 示例配置
• 真实烟雾测试记录

需要明确一点：

• md2wechat convert article.md 在未显式传 --mode 时，始终默认走 api
• 只有显式传 --mode ai 才会走 AI 模式

📁 项目结构

md2wechat-skill/
├── cmd/                    # 命令行工具
│   └── md2wechat/         # 主程序
├── internal/              # 核心功能模块
│   ├── converter/        # 转换器（API/AI）
│   ├── draft/            # 草稿服务
│   ├── image/            # 图片处理
│   ├── wechat/           # 微信 API 封装
│   ├── writer/           # 写作助手
│   ├── humanizer/        # AI 去痕
│   └── config/           # 配置管理
├── writers/              # 写作风格配置
│   ├── dan-koe.yaml      # Dan Koe 风格
│   └── README.md         # 自定义风格指南
├── docs/                 # 详细文档
│   ├── USAGE.md          # 使用教程
│   ├── FAQ.md            # 常见问题
│   └── TROUBLESHOOTING.md # 故障排查
├── examples/             # 示例文章
├── scripts/              # 安装脚本
└── bin/                  # 编译好的二进制文件

高级安装

方式一：Homebrew（macOS 优先推荐）

如果你在 macOS 上，并且已经装了 Homebrew，优先执行：

brew install geekjourneyx/tap/md2wechat

升级：

brew upgrade geekjourneyx/tap/md2wechat

方式二：一键安装脚本（其他环境推荐）

Mac/Linux：

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash

Windows PowerShell：

$env:MD2WECHAT_RELEASE_BASE_URL = "https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7"
iex ((New-Object System.Net.WebClient).DownloadString("$env:MD2WECHAT_RELEASE_BASE_URL/install.ps1"))

脚本会下载 release 资产并验证 checksums.txt，这是当前推荐路径。

方式二：手动下载 release 资产

如果你需要固定版本或离线安装，请按 安装指南 的 release + checksum 步骤操作。

方式三：从源码编译

git clone https://github.com/geekjourneyx/md2wechat-skill.git
cd md2wechat-skill
make build

Coding Agent 集成

md2wechat 提供了面向 Claude Code / Codex / OpenCode 的 skill 和仓库安装方式，让你在 Coding Agent 中直接使用自然语言完成排版、图片生成和草稿推送。

安装方式

方式一：npx skills add（推荐，通用）

适合 Claude Code / Codex / OpenCode 等支持 skills 安装协议的环境：

npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

安装后，直接在 Agent 中调用 md2wechat skill 即可。npx skills add 只安装 skill，不会替你自动安装 CLI runtime。

当前 coding-agent skill 的 runtime 逻辑是：

• 直接依赖 PATH 里已安装好的 md2wechat
• skill 本身不再承担 runtime 查找、缓存 bootstrap 或执行时下载
• 如果 md2wechat 不在 PATH 里，先安装 CLI，再继续使用 skill

skill 不再在正常执行路径中自动下载并执行远程二进制。

推荐直接发给 Coding Agent 的对话脚本：

请先安装 md2wechat CLI，再安装 md2wechat skill，并验证版本和能力发现都正常。
执行：
1. 如果我是 mac 用户，先运行：brew install geekjourneyx/tap/md2wechat
2. 如果我已经有稳定可用的 Go 环境，也可以改成：go install github.com/geekjourneyx/md2wechat-skill/cmd/md2wechat@v2.0.7
3. 如果以上两种都不适合，再运行：curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash
4. 运行：npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat
5. 如果我是通过 install.sh 安装的，再运行：export PATH="$HOME/.local/bin:$PATH"
6. 运行：md2wechat version --json
7. 运行：md2wechat capabilities --json
8. 运行：md2wechat config init
如果失败，请继续排查，不要只停止在报错信息。

方式二：Claude Code / Codex 兼容路径

如果你所在的 Agent 环境仍然暴露 Plugin Marketplace 或旧插件入口，也建议继续沿用同一条主路径：

1. 先把 md2wechat CLI 安装到 PATH
2. 再通过 npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat 安装 skill

不要把旧的 plugin 安装入口当成新的主契约；当前仓库文档、skill 和 release 检查都以 CLI + npx skills add 为准。

方式三：Claudian / Obsidian

如果你在 Obsidian 里使用 Claudian，也可以直接复用同一套 skill。

Claudian 官方说明里已经明确：

• 它兼容 Claude Code skill 格式
• 会从 ~/.claude/skills/ 或 {vault}/.claude/skills/ 发现 skill
• 支持 slash commands 和 skills

所以对 md2wechat 来说，最稳的路径是：

brew install geekjourneyx/tap/md2wechat
md2wechat version --json
npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

如果你不用 Homebrew，再改用固定版本安装脚本：

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
md2wechat version --json
npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

然后在 Claudian 里：

• 直接输入 /md2wechat
• 或直接让 Agent 调用 md2wechat skill

如果 Obsidian 图形界面里仍然找不到 md2wechat，优先去 Claudian：

• Settings -> Environment -> Custom variables
• 添加：
  • PATH=/Users/你的用户名/.local/bin:...

保姆级说明见：

• Obsidian / Claudian 指南

方式四：项目内使用

克隆项目后，Skill 自动可用：

git clone https://github.com/geekjourneyx/md2wechat-skill.git
cd md2wechat-skill
# 在 Claude Code 中直接使用

方式五：全局安装

将 Skill 复制到全局目录：

# 复制到全局技能目录
cp -r skills/md2wechat ~/.claude/skills/

方式六：创建符号链接

ln -s /path/to/md2wechat-skill/skills/md2wechat ~/.claude/skills/md2wechat

项目结构

md2wechat-skill/
├── .claude-plugin/        # 插件清单
│   └── marketplace.json   # Plugin Marketplace 配置
├── skills/                # coding-agent skill 目录（Claude Code / Codex / OpenCode）
│   └── md2wechat/
│       └── SKILL.md       # 技能定义
├── platforms/             # 平台适配层
│   └── openclaw/
│       └── md2wechat/     # OpenClaw 专用 skill 包
│           └── SKILL.md
├── scripts/               # 安装脚本
│   ├── install.sh         # CLI 安装脚本
│   └── install-openclaw.sh # OpenClaw 安装脚本
└── themes/                # AI 主题配置
    ├── autumn-warm.yaml
    ├── spring-fresh.yaml
    └── ocean-calm.yaml

Obsidian / Claudian 支持

如果你在 Obsidian 里使用 Claudian，md2wechat 现在也能直接接进去。

Claudian 官方 README 说明它：

• 是一个把 Claude Code 嵌入 Obsidian 的插件
• 兼容 Claude Code skill 格式
• 会从 ~/.claude/skills/ 或 {vault}/.claude/skills/ 发现 skills
• 支持 slash commands

这意味着：

• 先安装 md2wechat CLI
• 再执行 npx skills add ...
• 之后你可以在 Claudian 里直接用 /md2wechat 或自然语言调用 skill

推荐直接发给 Claudian / Obsidian 用户的脚本：

请帮我在当前电脑上安装 md2wechat，并让 Claudian 可以在 Obsidian 里通过 /md2wechat 使用它。按这个顺序执行：
1. 如果我是 mac 用户，先运行：brew install geekjourneyx/tap/md2wechat
2. 如果我已经有稳定可用的 Go 环境，也可以改成：go install github.com/geekjourneyx/md2wechat-skill/cmd/md2wechat@v2.0.7
3. 如果以上两种都不适合，再运行：curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash
4. 如果我是通过 install.sh 安装的，再运行：export PATH="$HOME/.local/bin:$PATH"
5. 运行：md2wechat version --json
6. 运行：npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat
7. 如果我在 Obsidian 里仍然找不到 md2wechat，请提醒我去 Claudian 的 Settings -> Environment -> Custom variables，把 PATH 补上 ~/.local/bin
8. 最后告诉我如何在 Claudian 里输入 /md2wechat 或直接调用 md2wechat skill
如果某一步失败，请继续排查，不要只返回报错原文。

适合谁：

• 已经在 Obsidian 里用 Claudian 写作
• 想在笔记库里直接把 Markdown 转公众号格式
• 想在 Obsidian 里直接生成封面图、信息图或推送草稿

单独文档：

• Obsidian / Claudian 指南

OpenClaw 支持

md2wechat 现已支持 OpenClaw 平台！

OpenClaw 使用独立的 platforms/openclaw/md2wechat/ skill 包，和面向 Claude Code / Codex / OpenCode 的 skills/md2wechat/ 分开维护。OpenClaw 现在也直接依赖已安装到环境路径里的 md2wechat CLI，不再保留 skill 内部 runtime wrapper。

OpenClaw 用户也可以直接从技能页面进入：

• ClawHub 页面：clawhub.ai/geekjourneyx/md2wechat

什么是 OpenClaw？

OpenClaw 是一个开源的 AI Agent 平台，在你的设备上运行，通过你已经在用的聊天应用（WhatsApp、Telegram、Discord、Slack）来操控 AI 助手。

The AI that actually does things. — 你的助手，你的设备，你的规则。

安装方式

方式一：ClawHub 安装（仅安装 skill 壳）

# 安装 OpenClaw 专用 md2wechat skill 包
npx clawhub@latest install md2wechat

当前 ClawHub 路径只会安装 skill 壳到 OpenClaw workspace，不保证自动安装 md2wechat CLI。完整、可验证的安装主线仍建议使用下一种固定版本 installer。

如果你更习惯先从网页进入，再决定是否安装，可以直接打开：

• ClawHub 页面：clawhub.ai/geekjourneyx/md2wechat

方式二：先安装 CLI（优先 Homebrew）

如果你已经装好了 OpenClaw skill 壳，或者只需要先把 CLI 装到环境里，可以先执行：

brew install geekjourneyx/tap/md2wechat

这个方式只安装 md2wechat CLI，不会自动写入 ~/.openclaw/skills/md2wechat/。如果你还没装 skill 壳，请继续执行 npx clawhub@latest install md2wechat，或者直接用下一种一键脚本。

如果你已经有 Go 环境，也可以执行：

go install github.com/geekjourneyx/md2wechat-skill/cmd/md2wechat@v2.0.7

它同样只安装 CLI，不会自动写入 ~/.openclaw/skills/md2wechat/。

方式三：一键脚本安装

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install-openclaw.sh | bash

脚本会按固定版本安装 OpenClaw skill 包与 md2wechat CLI，并校验 checksums.txt。这是当前最完整、最可验证的 OpenClaw 安装路径。

推荐直接发给 OpenClaw / 通用大模型的对话脚本：

请帮我安装 OpenClaw 版 md2wechat，并验证 skill 和 CLI 都可用。
执行：
1. curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install-openclaw.sh | bash
2. 先执行：export PATH="$HOME/.local/bin:$PATH"
3. md2wechat version --json
4. md2wechat config init
5. md2wechat config validate
6. md2wechat capabilities --json
如果失败，请继续排查 ~/.openclaw/skills/md2wechat/ 和 `command -v md2wechat`，不要只返回错误原文。

方式四：手动安装

VERSION=2.0.7
# 按你的平台选择对应二进制，这里以 Linux amd64 为例
curl -LO https://github.com/geekjourneyx/md2wechat-skill/releases/download/v${VERSION}/md2wechat-openclaw-skill.tar.gz
curl -LO https://github.com/geekjourneyx/md2wechat-skill/releases/download/v${VERSION}/md2wechat-linux-amd64
curl -LO https://github.com/geekjourneyx/md2wechat-skill/releases/download/v${VERSION}/checksums.txt
sha256sum -c checksums.txt --ignore-missing
mkdir -p ~/.openclaw/skills
mkdir -p ~/.local/bin
mkdir -p /tmp/md2wechat-openclaw
tar -xzf md2wechat-openclaw-skill.tar.gz -C /tmp/md2wechat-openclaw
cp -r /tmp/md2wechat-openclaw/skills/md2wechat ~/.openclaw/skills/
install -m 0755 md2wechat-linux-amd64 ~/.local/bin/md2wechat
export PATH="$HOME/.local/bin:$PATH"

手动安装时，请以同一版本 release 提供的 OpenClaw 资产为准，确保 skill 包与 md2wechat CLI 同版本安装。

配置

安装完成后直接初始化 md2wechat 配置：

md2wechat config init
md2wechat config validate

默认配置文件：

~/.config/md2wechat/config.yaml

Claude Code vs OpenClaw

详细文档：OpenClaw 安装指南

使用示例

示例 1：技术博主

# 写好技术文章
vim my-tech-post.md
使用简洁的 API 模式转换
md2wechat convert my-tech-post.md --preview
满意后发送草稿
md2wechat convert my-tech-post.md --draft --cover cover.jpg

示例 2：产品经理发公告

# 生成 AI 排版请求，再交给 Claude Code 等环境继续处理
md2wechat convert announcement.md --mode ai --theme ocean-calm

示例 3：生活方式博主

# 使用春日清新主题
md2wechat convert travel-diary.md --mode ai --theme spring-fresh --preview

示例 4：写作小白用观点生成文章

# 交互模式：输入观点，AI 生成文章
md2wechat write
指定风格生成
md2wechat write --style dan-koe
生成封面提示词
md2wechat write --style dan-koe --cover-only

❓ 常见问题

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash

# 查看所有可用风格
md2wechat write --list
交互式写作
md2wechat write
指定风格写作
md2wechat write --style dan-koe

# 参考内置风格
cat writers/dan-koe.yaml
创建自己的风格
vim writers/my-style.yaml

# 基本用法
md2wechat humanize article.md
指定强度（gentle/medium/aggressive）
md2wechat humanize article.md --intensity aggressive
显示修改对比和质量评分
md2wechat humanize article.md --show-changes

# 写作 + 去痕
md2wechat write --style dan-koe --humanize

# 风格优先：保留 Dan Koe 风格，去除 AI 痕迹
md2wechat write --style dan-koe --humanize

# 管道输入
echo "你的想法或内容" | md2wechat write --style dan-koe
heredoc 输入（适合多行内容）
md2wechat write --style dan-koe --title "文章标题" <<EOF
第一段内容
第二段内容
更多观点...
EOF

更多文档

贡献

欢迎提交 Issue 和 Pull Request！

如果你有好的想法或发现了 bug，请随时提 issue。

许可证

MIT License

打赏 Buy Me A Coffee

如果该项目帮助了您，请作者喝杯咖啡吧。

WeChat

作者

• 作者：geekjourneyx
• X（Twitter）：https://x.com/seekjourney
• 公众号：极客杰尼

如需咨询，扫描公众号二维码联系，备注「API咨询」：

Star History