npm package: @geekjourneyx/md2wechat
Description: Install the md2wechat CLI from the matching GitHub Release bundle.
Latest version: 2.0.7

<div align="center">

<h1>
  <img src="assets/favicon.ico" alt="md2wechat logo" width="28" />
  md2wechat
</h1>

<img src="assets/readme-cover.webp" alt="md2wechat" width="520" />

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

[![Go Version](https://img.shields.io/badge/Go-1.26.1+-00ADD8?logo=go)](https://golang.org)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![GitHub Release](https://img.shields.io/badge/download-latest-green)](https://github.com/geekjourneyx/md2wechat-skill/releases)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Skill-purple)](#coding-agent)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-Compatible-00b0aa)](#openclaw)
[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/geekjourneyx/md2wechat-skill)

[快速开始](#quickstart) • [Coding Agent](#coding-agent) • [Obsidian / Claudian](#obsidian-claudian) • [OpenClaw](#openclaw) • [功能介绍](#features) • [使用说明](#usage) • [常见问题](#faq)

---

## 立即开始

如果你第一次接触 `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：看 [安装指南](docs/INSTALL.md)
- 想申请 API 服务或咨询：扫描文末公众号二维码联系，备注「API咨询」
- 想先看支持的主题 / 图片 prompt / provider：执行 discovery 命令
- 想在 Claude Code / Codex / OpenCode 等 Coding Agent 里使用：先安装 CLI，再执行 `npx skills add`
- 想在 Obsidian 的 Claudian 插件里使用：先安装 CLI，再执行 `npx skills add`，然后看 [Obsidian / Claudian 指南](docs/OBSIDIAN.md)

```bash
# 查看当前实例支持什么
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：

```text
请帮我安装 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 里使用，可以直接发：

```text
请帮我安装 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` 有输出
如果某一步失败，请直接告诉我失败原因和下一步修复命令，不要省略命令。
```

</div>

---

> ### 先看这里
> - `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`
> - 安装、配置和校验入口分别看：[安装指南](docs/INSTALL.md) / [配置指南](docs/CONFIG.md) / [能力发现](docs/DISCOVERY.md)

---

<a id="quickstart"></a>

## 5分钟快速上手

### 第一步：安装工具

推荐先看 [安装指南](docs/INSTALL.md)。如果你只想快速开始：

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

```bash
brew install geekjourneyx/tap/md2wechat
```

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

```bash
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`。这种情况下先改用官方源安装：

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

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

```bash
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`，先执行：

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

Windows PowerShell：

```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：

```bash
brew install geekjourneyx/tap/md2wechat
```

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

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

然后安装 skill：

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

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

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

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

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

```bash
md2wechat config init
```

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

| 配置项 | 是什么 | 在哪获取 |
|--------|--------|----------|
| AppID | 公众号唯一标识 | [微信开发者平台](https://developers.weixin.qq.com/platform) → 开发接口管理 |
| Secret | API 密钥 | 同上，需要管理员权限 |

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

- [微信凭证与 IP 白名单指南](docs/WECHAT-CREDENTIALS.md)

里面单独讲清楚了：

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

### 第三步：开始使用

```bash
# 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 帮你 |
|------|------|---------------|
| 内容创作者 | 微信编辑器太难用，排版花时间 | Markdown 写作，自动排版 |
| 产品经理 | 要发公告，但不会 HTML | 不用学代码，一行命令搞定 |
| 程序员 | 习惯 Markdown，讨厌微信编辑器 | 保持你的写作习惯 |
| AI 用户 | 用 AI 生成内容，但要手动复制粘贴 | AI 生成 → 微信草稿，无缝衔接 |

### 站点入口

- 国际站: [md2wechat.com](https://www.md2wechat.com/)
- 国内站 / API 主站: [md2wechat.cn](https://md2wechat.cn)
- GitHub 项目: [geekjourneyx/md2wechat-skill](https://github.com/geekjourneyx/md2wechat-skill)

### 关于作者

这个项目由 [geekjourneyx](https://github.com/geekjourneyx/geekjourneyx) 维护。

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

---

<a id="features"></a>

## 核心功能

```mermaid
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
```

### 五大核心功能

| 功能 | 命令 | 说明 | 适合谁 |
|------|------|------|--------|
| **Markdown 转换** | `convert` | 将 Markdown 转换为微信格式 HTML | 所有用户 |
| **风格写作** | `write` | 用创作者风格辅助写作，自动生成文章和封面提示词 | 写作小白、内容创作者 |
| **AI 去痕** | `humanize` | 去除 AI 生成痕迹，让文章听起来更自然、像人写的 | AI 写作用户 |
| **小绿书** | `create_image_post` | 创建图片消息（小绿书），最多 20 张图片 | 图片内容创作者 |
| **草稿推送** | `convert --draft` | 一键发送到微信草稿箱 | 需要频繁发布的用户 |

**`write` 与 `convert` 的区别：**

| 对比项 | `write` 命令 | `convert` 命令 |
|--------|-------------|---------------|
| **输入** | 一个想法/观点/片段 | 完整的 Markdown 文件 |
| **输出** | 结构化提示词（AI 处理后生成文章） | 微信格式 HTML |
| **用途** | 从零开始创作 | 格式转换已有内容 |
| **封面** | 自动生成封面提示词 | 需要手动指定封面图 |

**简单理解：**
- `write` = 帮你写文章（从想法到完整文章）
- `convert` = 帮你排版（从 Markdown 到微信格式）

### 两种转换模式

| 模式 | 适合谁 | 特点 | 样式 |
|------|--------|------|------|
| **API 模式** | 追求稳定、快速 | 调用 md2wechat.cn API，秒级响应 | 简洁专业 |
| **AI 模式** | 追求精美排版 | 生成 AI request / prompt，样式更丰富 | 秋日暖光 / 春日清新 / 深海静谧 |

### 完整工作流程

```mermaid
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
```

<a id="usage"></a>

## 使用方法

### 基础命令

```bash
# 先检查最终标题/摘要/发布风险
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` 之前，推荐先走确认层：

```bash
# 看系统最终会如何解释这篇文章
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、自动化脚本，或者想先确认当前实例支持哪些能力，先执行这些命令：

```bash
# 总览当前 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
```

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

```bash
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 模板也可以直接渲染：

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

详细说明见 [docs/DISCOVERY.md](docs/DISCOVERY.md)。

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

### 风格写作

```bash
# 查看所有可用写作风格
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
```

**写作风格说明：**

| 风格 | 特点 | 适合内容 |
|------|------|----------|
| **Dan Koe** | 深刻但不晦涩，犀利但不刻薄，有哲学深度但接地气 | 个人成长、观点文章、评论 |

**如何添加自定义风格：**

在 `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 自动生成符合特定创作者风格的文章            │
│                                                                       │
└─────────────────────────────────────────────────────────────────────┘
```

**核心概念：**

| 概念 | 说明 | 示例 |
|------|------|------|
| **写作风格** | 特定创作者的写作 DNA，包括语气、结构、用词习惯 | Dan Koe：深刻犀利、接地气 |
| **输入类型** | 你提供的内容类型 | 观点、片段、大纲、标题 |
| **AI 模式** | 返回结构化提示词，由 Claude 等大模型生成内容 | 默认模式 |
| **封面提示词** | 根据文章内容自动生成的配图提示 | 匹配写作风格 |

**完整工作流程：**

```mermaid
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
```

**输入类型说明：**

| 输入类型 | 说明 | 示例 |
|----------|------|------|
| `idea` | 一个观点或想法 | "我觉得自律是个伪命题" |
| `fragment` | 内容片段，需要润色扩展 | 现有的草稿或未完成的文章 |
| `outline` | 文章大纲 | 有结构，需要填充内容 |
| `title` | 仅标题，围绕标题写作 | "自律是个谎言" |

**输出说明：**

```json
{
  "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 中使用时，这个流程是自动的。

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

```mermaid
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](https://github.com/op7418/Humanizer-zh) 项目，感谢作者 **臧师傅** 的分享。

**什么是 AI 去痕？**

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

**能检测哪些 AI 痕迹？**

| 类别 | 检测模式 | 示例 |
|------|----------|------|
| **内容模式** | 过度强调意义、宣传语言、模糊归因 | "标志着"、"凸显了"、"行业报告显示" |
| **语言模式** | AI 词汇、否定排比、三段式 | "此外"、"深入探讨"、"不仅…而且…" |
| **风格模式** | 破折号过度、粗体滥用、表情符号 | 过度使用 `——`、大量 `**粗体**` |
| **填充词** | 填充短语、过度限定、通用结论 | "为了实现这一目标"、"未来一片光明" |
| **协作痕迹** | 对话式填充、知识截止免责声明 | "希望这对您有帮助"、"截至 2024 年" |

**三种处理强度：**

| 强度 | 命令 | 适合场景 |
|------|------|----------|
| `gentle` | `--intensity gentle` | 文章已经比较自然，只处理明显问题 |
| `medium` | 默认 | 大多数场景，平衡处理 |
| `aggressive` | `--intensity aggressive` | AI 味很重的文章，深度改写 |

**使用方法：**

```bash
# 独立使用：去除文章的 AI 痕迹
md2wechat humanize article.md

# 指定强度
md2wechat humanize article.md --intensity aggressive

# 显示修改对比和质量评分
md2wechat humanize article.md --show-changes

# 输出到文件
md2wechat humanize article.md -o output.md
```

**与写作风格组合使用：**

```bash
# 写作 + 去痕：生成文章后自动去除 AI 痕迹
md2wechat write --style dan-koe --humanize

# 指定去痕强度
md2wechat write --style dan-koe --humanize --humanize-intensity aggressive
```

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

**AI 去痕工作流程：**

```mermaid
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）：

| 维度 | 说明 | 评分标准 |
|------|------|----------|
| **直接性** | 是否直截了当 | 10 分：直击要点；1 分：充满铺垫 |
| **节奏** | 句子长度是否变化 | 10 分：长短交错；1 分：机械重复 |
| **信任度** | 是否尊重读者 | 10 分：简洁明了；1 分：过度解释 |
| **真实性** | 听起来像真人吗 | 10 分：自然流畅；1 分：机械生硬 |
| **精炼度** | 有无冗余内容 | 10 分：无废话；1 分：大量填充 |

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

**去痕效果对比：**

| 原文（AI 味） | 去痕后 |
|--------------|--------|
| 在当今快速发展的科技时代，人工智能技术正以前所未有的速度改变着我们的生活方式 | 这几年，AI 变化太快了 |
| 人工智能的重要性不言而喻。它不仅标志着技术进步的新里程碑 | AI 挺重要的，但不是那种玄乎的重要 |
| 此外，AI 技术还在改善我们的日常生活质量 | 顺手提一句，AI 确实让生活方便了不少 |
| 尽管存在挑战，但人工智能的未来依然光明 | 未来会怎样不好说，有好有坏吧 |
| 希望这对您有帮助 | —— |

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

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

### 完整发布流程

```bash
# 一步到位：转换 + 上传图片 + 发送草稿
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 模式主题选择

| 主题名 | 命令 | 风格 | 适合内容 |
|--------|------|------|----------|
| **秋日暖光** | `--theme autumn-warm` | 温暖橙色调 | 情感故事、生活随笔 |
| **春日清新** | `--theme spring-fresh` | 清新绿色调 | 旅行日记、自然主题 |
| **深海静谧** | `--theme ocean-calm` | 专业蓝色调 | 技术文章、商业分析 |

### API 模式主题选择

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

```bash
md2wechat themes list --json
```

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

#### 主题预览
**完整主题预览**: [https://md2wechat.app/theme-gallery](https://md2wechat.app/theme-gallery)

#### 主题分类

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

| 主题 | 风格 | 适合 |
|------|------|------|
| `default` | 微信经典，温暖舒适 | 通用内容 |
| `bytedance` | 科技现代，简洁利落 | 科技资讯 |
| `apple` | 视觉渐变，精致优雅 | 产品评测 |
| `sports` | 活力动感，充满能量 | 体育健康 |
| `chinese` | 古典雅致，书卷气息 | 文化文章 |
| `cyber` | 未来科技，霓虹光影 | 前沿科技 |

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

| 颜色 | 主题 | 命令 |
|------|------|------|
| 金色 | minimal-gold | `--theme minimal-gold` |
| 绿色 | minimal-green | `--theme minimal-green` |
| 蓝色 | minimal-blue | `--theme minimal-blue` |
| 橙色 | minimal-orange | `--theme minimal-orange` |
| 红色 | minimal-red | `--theme minimal-red` |
| 藏青 | minimal-navy | `--theme minimal-navy` |
| 灰色 | minimal-gray | `--theme minimal-gray` |
| 天蓝 | minimal-sky | `--theme minimal-sky` |

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

| 颜色 | 主题 | 命令 |
|------|------|------|
| 金色 | focus-gold | `--theme focus-gold` |
| 绿色 | focus-green | `--theme focus-green` |
| 蓝色 | focus-blue | `--theme focus-blue` |
| 橙色 | focus-orange | `--theme focus-orange` |
| 红色 | focus-red | `--theme focus-red` |
| 藏青 | focus-navy | `--theme focus-navy` |
| 灰色 | focus-gray | `--theme focus-gray` |
| 天蓝 | focus-sky | `--theme focus-sky` |

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

| 颜色 | 主题 | 命令 |
|------|------|------|
| 金色 | elegant-gold | `--theme elegant-gold` |
| 绿色 | elegant-green | `--theme elegant-green` |
| 蓝色 | elegant-blue | `--theme elegant-blue` |
| 橙色 | elegant-orange | `--theme elegant-orange` |
| 红色 | elegant-red | `--theme elegant-red` |
| 藏青 | elegant-navy | `--theme elegant-navy` |
| 灰色 | elegant-gray | `--theme elegant-gray` |
| 天蓝 | elegant-sky | `--theme elegant-sky` |

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

| 颜色 | 主题 | 命令 |
|------|------|------|
| 金色 | bold-gold | `--theme bold-gold` |
| 绿色 | bold-green | `--theme bold-green` |
| 蓝色 | bold-blue | `--theme bold-blue` |
| 橙色 | bold-orange | `--theme bold-orange` |
| 红色 | bold-red | `--theme bold-red` |
| 藏青 | bold-navy | `--theme bold-navy` |
| 灰色 | bold-gray | `--theme bold-gray` |
| 天蓝 | bold-sky | `--theme bold-sky` |

#### 主题命名规则

```
<系列>-<颜色>

系列:
  minimal  - 干净克制
  focus    - 居中对称
  elegant  - 层次丰富
  bold     - 视觉冲击

颜色: gold, green, blue, orange, red, navy, gray, sky
```

#### 使用示例

```bash
# 使用 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` 的实际输出。

#### 背景类型选择

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

| 背景类型 | 命令 | 效果 | 适合场景 |
|----------|------|------|----------|
| `default` | `--background-type default` | 默认背景（纯色或渐变） | 通用内容 |
| `grid` | `--background-type grid` | 网格纹理背景 | 技术文档、笔记类 |
| `none` | `--background-type none` | 无背景（透明） | 嵌入式内容 |

**使用示例：**

```bash
# 使用网格背景
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`。

**配置文件设置：**

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

### 图片处理

```bash
# 上传单张图片到微信素材库
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** | `modelscope` 或 `ms` | 阿里 ModelScope，免费额度 | [modelscope.cn](https://modelscope.cn/my/myaccesstoken) |
| **TuZi** | `tuzi` | 国产 API，稳定快速 | [tu-zi.com](https://api.tu-zi.com) |
| **OpenAI** | `openai` | 官方 OpenAI | [platform.openai.com](https://platform.openai.com) |
| **OpenRouter** | `openrouter` 或 `or` | 多模型聚合接口，支持 Gemini / Flux 等 | [openrouter.ai](https://openrouter.ai) |
| **Google Gemini** | `gemini` 或 `google` | 官方 Gemini 图片生成 API | [ai.google.dev](https://ai.google.dev/gemini-api/docs/image-generation) |
| **Volcengine Ark** | `volcengine` 或 `volc` | 火山引擎 Ark，支持豆包 Seedream 5.0 系列 | [豆包大模型](https://www.volcengine.com/product/doubao) |

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

```bash
# 使用 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
```

```yaml
# 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`，去 [豆包大模型](https://www.volcengine.com/product/doubao) 点击“控制台” -> “开通管理”，勾选 `Seedream` 模型完成开通。

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

#### Markdown 中生成图片

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

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

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

- 支持中文和英文提示词
- 生成的图片会自动上传到微信素材库
- 需要配置图片生成服务（详见 [图片服务配置文档](docs/IMAGE_PROVISIONERS.md)）

**在 Claude Code 中使用自然语言：**
```
"帮我在文章开头生成一张产品概念图"
"在第三段后添加一张对比图"
"生成一张可爱的猫"（独立生成，不关联文章）
```

---

## AI 模式详解

### 什么是 AI 模式？

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

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

### AI 模式的优势

| 对比项 | API 模式 | AI 模式 |
|--------|----------|----------|
| 响应速度 | 秒级 | 需要额外 AI 步骤 |
| 排版质量 | 👍 标准规范 | 🌟 精美多样 |
| 样式选择 | 2-3 种 | 更灵活 |
| 成本 | 低 | 取决于外部 AI |
| 适合场景 | 日常文章 | 重要文章、品牌内容 |

### 在 Claude Code 中使用 AI 模式

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

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

---

## 配置说明

### 配置文件位置

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

生成示例配置：

```bash
md2wechat config init
```

查看当前实际生效配置：

```bash
md2wechat config show --format json
```

### 配置项说明

```yaml
# 微信公众号配置（必需）
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/`
- 二进制内置默认资产

更完整的保姆级说明见：

- [配置指南](docs/CONFIG.md)
- [示例配置](docs/examples/config.yaml.example)
- [真实烟雾测试记录](docs/SMOKE.md)

需要明确一点：

- `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，优先执行：

```bash
brew install geekjourneyx/tap/md2wechat
```

升级：

```bash
brew upgrade geekjourneyx/tap/md2wechat
```

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

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

**Windows PowerShell：**
```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 资产

如果你需要固定版本或离线安装，请按 [安装指南](docs/INSTALL.md) 的 release + checksum 步骤操作。

### 方式三：从源码编译

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

---

<a id="coding-agent"></a>

## Coding Agent 集成

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

### 安装方式

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

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

```bash
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 的对话脚本：

```text
请先安装 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](https://github.com/YishenTu/claudian)，也可以直接复用同一套 skill。

Claudian 官方说明里已经明确：
- 它兼容 Claude Code skill 格式
- 会从 `~/.claude/skills/` 或 `{vault}/.claude/skills/` 发现 skill
- 支持 slash commands 和 skills

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

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

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

```bash
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 指南](docs/OBSIDIAN.md)

#### 方式四：项目内使用

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

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

#### 方式五：全局安装

将 Skill 复制到全局目录：

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

#### 方式六：创建符号链接

```bash
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
```

---

<a id="obsidian-claudian"></a>

## Obsidian / Claudian 支持

如果你在 Obsidian 里使用 [Claudian](https://github.com/YishenTu/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 用户的脚本：

```text
请帮我在当前电脑上安装 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 指南](docs/OBSIDIAN.md)

---

<a id="openclaw"></a>

## OpenClaw 支持

md2wechat 现已支持 [OpenClaw](https://openclaw.ai/) 平台！

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

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

- [ClawHub 页面：clawhub.ai/geekjourneyx/md2wechat](https://clawhub.ai/geekjourneyx/md2wechat)

### 什么是 OpenClaw？

[OpenClaw](https://openclaw.ai/) 是一个开源的 AI Agent 平台，**在你的设备上运行**，通过你已经在用的聊天应用（WhatsApp、Telegram、Discord、Slack）来操控 AI 助手。

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

### 安装方式

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

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

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

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

- [ClawHub 页面：clawhub.ai/geekjourneyx/md2wechat](https://clawhub.ai/geekjourneyx/md2wechat)

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

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

```bash
brew install geekjourneyx/tap/md2wechat
```

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

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

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

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

#### 方式三：一键脚本安装

```bash
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 / 通用大模型的对话脚本：

```text
请帮我安装 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`，不要只返回错误原文。
```

#### 方式四：手动安装

```bash
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` 配置：

```bash
md2wechat config init
md2wechat config validate
```

默认配置文件：

```text
~/.config/md2wechat/config.yaml
```

### Claude Code vs OpenClaw

| 方面 | Claude Code | OpenClaw |
|------|-------------|----------|
| **定位** | 终端 AI 编程助手 | 聊天应用 AI 助手 |
| **仓库内 skill 路径** | `skills/md2wechat/` | `platforms/openclaw/md2wechat/` |
| **技能目录** | `~/.claude/skills/` | `~/.openclaw/skills/` |
| **安装方式** | `/plugin` 命令 | `clawhub` CLI + `brew/go install`，或 OpenClaw installer |
| **配置方式** | 环境变量 / `config.yaml` | `~/.config/md2wechat/config.yaml` |
| **LLM 支持** | Claude | Claude、GPT、DeepSeek 等 |

> **详细文档**：[OpenClaw 安装指南](docs/OPENCLAW.md)

---

## 使用示例

### 示例 1：技术博主

```bash
# 写好技术文章
vim my-tech-post.md

# 使用简洁的 API 模式转换
md2wechat convert my-tech-post.md --preview

# 满意后发送草稿
md2wechat convert my-tech-post.md --draft --cover cover.jpg
```

### 示例 2：产品经理发公告

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

### 示例 3：生活方式博主

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

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

```bash
# 交互模式：输入观点，AI 生成文章
md2wechat write

# 指定风格生成
md2wechat write --style dan-koe

# 生成封面提示词
md2wechat write --style dan-koe --cover-only
```

---

<a id="faq"></a>

## ❓ 常见问题

<details>
<summary><b>Q: 必须要会编程才能用吗？</b></summary>

**A: 不需要！** 只要会用命令行（终端）就可以。如果是 Windows 用户，下载 .exe 文件后，在 CMD 或 PowerShell 中运行命令即可。
</details>

<details>
<summary><b>Q: AI 模式需要付费吗？</b></summary>

**A:** AI 模式使用 Claude 能力：
- 如果你在 **Claude Code** 中使用，直接调用内置 AI
- 如果你想自己接入，需要配置 OpenAI 兼容的 API
</details>

<details>
<summary><b>Q: 支持哪些 Markdown 语法？</b></summary>

**A:** 支持常用语法：
- 标题（# ## ###）
- 列表（无序、有序）
- 粗体、斜体、行内代码
- 代码块（带语法高亮）
- 引用块
- 分割线
- 图片、链接
- 表格
</details>

<details>
<summary><b>Q: 生成的文章可以直接在微信编辑器中编辑吗？</b></summary>

**A:** 可以！草稿发送后，你可以登录微信公众平台，在草稿箱中继续编辑。
</details>

<details>
<summary><b>Q: 如何知道应该下载哪个版本？下载错了怎么办？</b></summary>

**A:**

**Mac 用户：**
- 点击屏幕左上角苹果图标 → 「关于本机」
- 看到 `Apple M1/M2/M3/M4` → 下载 **Apple Silicon (arm64)** 版本
- 看到 `Intel` → 下载 **Intel (amd64)** 版本

**Linux 用户：**
- 运行 `uname -m` 命令
- 输出 `x86_64` → 下载 **amd64** 版本
- 输出 `aarch64` → 下载 **arm64** 版本

**如果下载错了：**
- 删除错误的文件，重新下载正确版本即可
- 也可以使用一键安装脚本，会自动检测系统架构

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

<details>
<summary><b>Q: 写作功能是什么？怎么用？</b></summary>

**A:** 写作功能可以帮你用特定创作者风格生成文章：

```bash
# 查看所有可用风格
md2wechat write --list

# 交互式写作
md2wechat write

# 指定风格写作
md2wechat write --style dan-koe
```

只需输入你的观点或想法，AI 会自动生成符合该风格的文章。
</details>

<details>
<summary><b>Q: 我是写作小白，不会写文章能用吗？</b></summary>

**A:** 完全可以！写作功能专为小白设计：

1. **只需要输入观点**：比如"我觉得自律是个伪命题"
2. **AI 自动扩展**：会自动生成结构完整的文章
3. **多种风格可选**：内置 Dan Koe 等风格，也可以自定义

不需要你会写作技巧，只需要有想法就行。
</details>

<details>
<summary><b>Q: 如何添加我喜欢的作家风格？</b></summary>

**A:** 在 `writers/` 目录下创建 YAML 文件：

```bash
# 参考内置风格
cat writers/dan-koe.yaml

# 创建自己的风格
vim writers/my-style.yaml
```

详细格式参考 `writers/README.md`。
</details>

<details>
<summary><b>Q: AI 去痕是什么？怎么用？</b></summary>

**A:** AI 去痕功能可以去除 AI 生成文章的"AI 味"，让文章听起来更像真人写的：

```bash
# 基本用法
md2wechat humanize article.md

# 指定强度（gentle/medium/aggressive）
md2wechat humanize article.md --intensity aggressive

# 显示修改对比和质量评分
md2wechat humanize article.md --show-changes
```

**与写作风格组合使用：**

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

> **致谢**：AI 去痕功能基于 [Humanizer-zh](https://github.com/op7418/Humanizer-zh) 项目。
</details>

<details>
<summary><b>Q: AI 去痕会改变文章意思吗？</b></summary>

**A:** 不会。AI 去痕只修改表达方式，不改变核心信息。

它会：
- 删除填充短语和过度强调
- 打破公式化结构
- 变化句子节奏
- 注入真实观点

但会保留原文的核心观点和信息。
</details>

<details>
<summary><b>Q: AI 去痕和写作风格会冲突吗？</b></summary>

**A:** 不会。当两者组合使用时，遵循**风格优先原则**：

- 保留写作风格的核心特征（如 Dan Koe 的破折号停顿）
- 只去除无意的 AI 痕迹
- 保持风格的一致性

```bash
# 风格优先：保留 Dan Koe 风格，去除 AI 痕迹
md2wechat write --style dan-koe --humanize
```
</details>

<details>
<summary><b>Q: 发送草稿时报错 "content size out of limit (errcode=45002)"？</b></summary>

**A:** 这是微信 API 的内容大小限制错误。

**微信草稿 API 限制：**
- **字符数**：< 20,000 字符（中文算 1 个字符）
- **大小**：< 1 MB

**解决方案：**
1. 缩短文章内容
2. 减少不必要的格式（API 模式的 inline CSS 会增加内容体积）
3. 拆分为多篇文章发布
4. 使用更简洁的排版主题

**注意：** API 模式生成的 HTML 包含大量 inline CSS，会使内容体积膨胀约 5-10 倍。长文章建议：
- 使用更简洁的 Markdown 写作
- 删除部分图片或使用外部图片链接
- 手动在微信编辑器中复制粘贴（绕过 API 限制）

**来源：** [微信公众号 API 文档](https://developers.weixin.qq.com/doc/subscription/api/draftbox/draftmanage/api_draft_add.html)
</details>

<details>
<summary><b>Q: ModelScope 图片生成需要多久？</b></summary>

**A:** ModelScope 使用异步 API 模式，通常需要 10-30 秒。

**流程：**
1. 发起请求 → 获取 task_id
2. 轮询任务状态（每 5 秒一次）
3. 任务完成 → 返回图片 URL

**超时设置：**
- 默认最大轮询时间：120 秒
- 超时后会返回错误，建议：
  - 简化提示词
  - 重试一次
  - 检查 ModelScope 服务状态
</details>

<details>
<summary><b>Q: 如何配置 ModelScope 图片生成？</b></summary>

**A:** ModelScope 是推荐的图片生成服务，有免费额度。

**配置步骤：**

1. **获取 API Key**
   - 访问 [modelscope.cn](https://modelscope.cn/my/myaccesstoken)
   - 登录后创建 Access Token
   - 格式类似：`ms-your-token-here`

2. **配置环境变量**
   ```bash
   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
   ```

3. **或在配置文件中设置**
   ```yaml
   # ~/.config/md2wechat/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
   ```

4. **测试**
   ```bash
   md2wechat generate_image "A golden cat"
   md2wechat generate_cover --title "AI 文章封面测试" --summary "测试封面 preset"
   ```
</details>

<details>
<summary><b>Q: write 命令支持管道输入吗？</b></summary>

**A:** 支持！可以通过管道或 heredoc 传递内容。

**使用方式：**

```bash
# 管道输入
echo "你的想法或内容" | md2wechat write --style dan-koe

# heredoc 输入（适合多行内容）
md2wechat write --style dan-koe --title "文章标题" <<EOF
第一段内容
第二段内容
更多观点...
EOF
```

**适用场景：**
- 脚本自动化
- 从其他命令输出传递内容
- 在 CI/CD 流程中使用
</details>

---

## 更多文档

| 文档 | 说明 |
|------|------|
| [文档索引](docs/README.md) | `docs/` 目录导航 |
| [新手入门指南](docs/QUICKSTART.md) | **强烈推荐！** 详细的图文教程 |
| [完整使用说明](docs/USAGE.md) | 所有命令和选项 |
| [架构说明](docs/ARCHITECTURE.md) | 当前代码边界与主线 |
| [OpenClaw 安装指南](docs/OPENCLAW.md) | OpenClaw 平台安装配置指南 |
| [图片服务配置](docs/IMAGE_PROVISIONERS.md) | AI 图片生成服务完整配置指南 |
| [写作功能指南](writers/README.md) | 如何使用和自定义写作风格 |
| [写作功能问答](docs/WRITING_FAQ.md) | 写作小白完整指南 |
| [AI 去痕指南](docs/WRITING_FAQ.md) | AI 写作去痕完整指南 |
| [常见问题](docs/FAQ.md) | 20+ 常见问题解答 |
| [故障排查](docs/TROUBLESHOOTING.md) | 遇到问题看这里 |

---

## 贡献

欢迎提交 Issue 和 Pull Request！

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

---

## 许可证

[MIT License](LICENSE)

---

## 打赏 Buy Me A Coffee

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

### WeChat

<img src="https://raw.githubusercontent.com/geekjourneyx/awesome-developer-go-sail/main/docs/assets/wechat-reward-code.jpg" alt="微信打赏码" width="200" />

---

## 作者

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

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

<p align="center">
<img src="https://raw.githubusercontent.com/geekjourneyx/awesome-developer-go-sail/main/docs/assets/qrcode.jpg" alt="公众号：极客杰尼" width="180" />
</p>

## Star History

<a href="https://www.star-history.com/?repos=geekjourneyx%2Fmd2wechat-skill&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=geekjourneyx/md2wechat-skill&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=geekjourneyx/md2wechat-skill&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=geekjourneyx/md2wechat-skill&type=date&legend=top-left" />
 </picture>
</a>

---

<div align="center">

**让公众号写作更简单**

[主页](https://github.com/geekjourneyx/md2wechat-skill) • [文档](docs) • [反馈](https://github.com/geekjourneyx/md2wechat-skill/issues)

Made by [geekjourneyx](https://geekjourney.dev)

</div>