md2wechat

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MD to WeChat

Markdown转微信公众号格式

Converts Markdown articles to WeChat Official Account formatted HTML with inline CSS and optionally uploads to draft box. Supports two modes:

API Mode: Fast conversion using md2wechat.cn API
AI Mode: Beautiful themed layouts powered by Claude AI

将Markdown文章转换为带有内联CSS的微信公众号格式HTML，还可选择上传至公众号草稿箱。支持两种模式：

API模式：使用md2wechat.cn API快速转换
AI模式：由Claude AI驱动的精美主题排版

Quick Start

快速开始

bash

undefined

bash

undefined

Preview HTML (API mode, fast)

预览HTML（API模式，快速）

bash skills/md2wechat/scripts/run.sh convert article.md --preview

Preview HTML (AI mode, themed)

预览HTML（AI模式，主题化）

bash skills/md2wechat/scripts/run.sh convert article.md --mode ai --theme autumn-warm --preview

Upload to WeChat draft box

上传至微信草稿箱

bash skills/md2wechat/scripts/run.sh convert article.md --draft --cover cover.jpg

undefined

bash skills/md2wechat/scripts/run.sh convert article.md --draft --cover cover.jpg

undefined

Natural Language Image Generation

自然语言图片生成

You can also ask me to generate images using natural language:

你也可以通过自然语言指令让我生成图片：

Generate Image for Article (Insert into Markdown)

为文章生成图片（插入至Markdown）

"Help me generate a product concept image at the beginning of article.md"
"Add an image showing the product features after the second paragraph"
"Create a diagram for the comparison section in article.md"

I will:

Read the article to understand the context
Insert the AI image generation syntax at the appropriate location
Call the conversion command to generate and upload the image

"帮我在article.md的开头生成一张产品概念图"
"在第二段之后添加一张展示产品特性的图片"
"为article.md中的对比章节创建一张示意图"

我会：

读取文章内容以理解上下文
在合适位置插入AI图片生成语法
调用转换命令完成图片生成与上传

Generate Standalone Image (Not for Article)

生成独立图片（不用于文章）

"Generate an image of a cute cat sitting on a windowsill"
"Create a product concept image: modern smart home device, white design"
"Make a diagram showing the user flow"

I will:

Call the image generation command directly
Return the generated image URL and WeChat material ID

"生成一张猫咪坐在窗台上的可爱图片"
"创建一张现代智能家居设备的产品概念图"
"制作一张展示用户流程的示意图"

我会：

直接调用图片生成命令
返回生成的图片URL和微信素材ID

Natural Language Writing Assistance

自然语言写作辅助

You can also ask me to help write articles using creator styles:

你也可以让我以创作者风格协助撰写文章：

Write Article from Idea

从想法生成文章

"Write an article about self-discipline using Dan Koe style"
"Help me write a post about productivity with a sharp, grounded tone"
"Create a story-style article about my travel experience"

I will:

Understand your idea or topic
Use the appropriate writing style (default: Dan Koe)
Generate article structure and content
Extract memorable quotes
Optionally generate matching cover image

"用Dan Koe的风格写一篇关于自律的文章"
"帮我写一篇关于生产力的帖子，语气犀利且接地气"
"创作一篇关于我的旅行经历的故事风格文章"

我会：

理解你的想法或主题
使用合适的写作风格（默认：Dan Koe）
生成文章结构与内容
提取精彩语录
可选生成匹配的封面图

Refine Existing Content

优化现有内容

"Rewrite this article with a more engaging style"
"Polish my article.md with Dan Koe's writing style"
"Make this content more profound and sharp"

I will:

Read your existing content
Apply the selected writing style
Maintain original meaning while improving expression

"用更吸引人的风格重写这篇文章"
"用Dan Koe的风格润色我的article.md"
"让这段内容更有深度和犀利感"

我会：

读取你的现有内容
应用选定的写作风格
在保留原意的同时优化表达

Generate Cover Only

仅生成封面图

"Generate a cover image for my article about self-discipline"
"Create a Victorian woodcut style cover for my philosophy piece"

"为我那篇关于自律的文章生成一张封面图"
"为我的哲学文章创建一张维多利亚木刻风格的封面"

AI Writing Trace Removal (Humanizer)

AI写作痕迹消除（人性化处理）

"Remove AI traces from this article: article.md"
"Humanize this text to make it sound more natural"
"Remove AI writing traces with gentle intensity"
"Rewrite this to sound less like AI generated"

I will:

Read the text to identify AI writing patterns (24 types)
Remove or rewrite problematic phrases
Inject natural human-like expressions
Preserve core meaning and tone
Return quality score (5 dimensions, /50)

Humanizer can be combined with writing styles:

"Write with Dan Koe style and remove AI traces"
"Use dan-koe style, then humanize the result"

"消除这篇文章的AI痕迹：article.md"
"将这段文本人性化处理，使其更自然"
"以温和强度消除AI写作痕迹"
"重写这段内容，使其听起来不像AI生成的"

我会：

读取文本以识别AI写作模式（共24种）
删除或重写有问题的语句
注入自然的人类表达方式
保留核心含义与语气
返回质量评分（5个维度，满分50分）

人性化处理可与写作风格结合使用：

"用Dan Koe的风格写作并消除AI痕迹"
"使用dan-koe风格，然后对结果进行人性化处理"

List Available Styles

列出可用风格

"Show me all available writing styles"
"What writing styles can I use?"

Available Writing Styles:

Dan Koe (default): Profound, sharp, grounded - great for personal growth and opinion pieces

Users can add custom styles in

writers/

directory. See

writers/README.md

for details.

"展示所有可用的写作风格"
"我可以使用哪些写作风格？"

可用写作风格：

Dan Koe（默认）：深刻、犀利、接地气 - 非常适合个人成长和观点类文章

用户可在

writers/

目录添加自定义风格。详情请见

writers/README.md

。

Workflow Checklist

工作流程检查清单

Copy this checklist to track progress:

Progress:
- [ ] Step 1: Analyze Markdown structure and images
- [ ] Step 2: Confirm conversion mode (API/AI) and theme
- [ ] Step 3: Generate HTML with inline CSS
- [ ] Step 4: Process images (upload to WeChat)
- [ ] Step 5: Replace image URLs in HTML
- [ ] Step 6: Preview or upload to draft

复制此清单以跟踪进度：

进度：
- [ ] 步骤1：分析Markdown结构与图片
- [ ] 步骤2：确认转换模式（API/AI）与主题
- [ ] 步骤3：生成带有内联CSS的HTML
- [ ] 步骤4：处理图片（上传至微信）
- [ ] 步骤5：替换HTML中的图片URL
- [ ] 步骤6：预览或上传至草稿箱

Step 1: Analyze Markdown

步骤1：分析Markdown

Read the markdown file and extract:

Element	How to Extract
Title	First `# heading` or filename
Author	Look for `Author:` or `作者:` in frontmatter
Digest	First paragraph or generate from content (max 120 chars)
Images	Collect all `![alt](src)` references
Structure	Headings, lists, code blocks, quotes, tables

Image Reference Types:

Type	Syntax	Processing
Local	`![alt](./path/image.png)`	Upload to WeChat
Online	`![alt](https://example.com/image.png)`	Download then upload
AI Generate	`![alt](__generate:prompt__)`	Generate via AI then upload

读取Markdown文件并提取以下内容：

元素	提取方式
标题	第一个 `# 标题` 或文件名
作者	查找前置元数据中的 `Author:` 或 `作者:`
摘要	第一段内容或从正文生成（最多120字符）
图片	收集所有 `![alt](src)` 引用
结构	标题、列表、代码块、引用、表格

图片引用类型:

类型	语法	处理方式
本地图片	`![alt](./path/image.png)`	上传至微信
在线图片	`![alt](https://example.com/image.png)`	下载后上传
AI生成图片	`![alt](__generate:prompt__)`	AI生成后上传

Step 2: Confirm Mode and Theme

步骤2：确认模式与主题

Conversion Mode

转换模式

Mode	Speed	Style	Best For
API	Fast (seconds)	Clean, standard	Quick publishing, technical content
AI	Slower (10-30s)	Beautiful themed	Important articles, brand content

模式	速度	风格	适用场景
API	快速（数秒）	简洁标准	快速发布、技术内容
AI	较慢（10-30秒）	精美主题化	重要文章、品牌内容

AI Themes

AI主题

Theme	Description	Best For
autumn-warm	Warm orange tones, emotional, literary	Stories, lifestyle, essays
spring-fresh	Fresh green tones, natural, vibrant	Travel, nature, outdoor
ocean-calm	Calm blue tones, professional, rational	Tech articles, business analysis
custom	Use custom prompt	Brand customization

主题	描述	适用场景
autumn-warm	温暖橙色调、感性文艺	故事、生活方式、散文
spring-fresh	清新绿色调、自然活力	旅行、自然、户外内容
ocean-calm	沉稳蓝色调、专业理性	科技文章、商业分析
custom	使用自定义提示词	品牌定制内容

API Themes (Fast)

API主题（快速）

Theme	Description	Best For
default	Default theme, clean and professional	General content
bytedance	ByteDance style	Tech news
apple	Apple minimalist style	Product reviews
sports	Active sports style	Sports content
chinese	Traditional Chinese culture style	Cultural articles
cyber	Cyberpunk style	Frontier tech

Ask the user: "Which mode and theme would you like?" - Only ask if the user doesn't specify in their request.

API mode (fast): default, bytedance, apple, sports, chinese, cyber
AI mode (themed): autumn-warm, spring-fresh, ocean-calm

Default: Use

API mode

if user doesn't specify.

Read detailed style prompts from references/themes.md

主题	描述	适用场景
default	默认主题、简洁专业	通用内容
bytedance	字节跳动风格	科技资讯
apple	苹果极简风格	产品评测
sports	动感运动风格	体育内容
chinese	传统文化风格	文化类文章
cyber	赛博朋克风格	前沿科技内容

询问用户：“你想要使用哪种模式和主题？” - 仅当用户未在请求中指定时询问。

API模式（快速）：default、bytedance、apple、sports、chinese、cyber
AI模式（主题化）：autumn-warm、spring-fresh、ocean-calm

默认设置：若用户未指定，使用

API模式

。

从[references/themes.md]查看详细风格提示词

Step 3: Generate HTML

步骤3：生成HTML

API Mode

API模式

Call md2wechat CLI:

bash

bash skills/md2wechat/scripts/run.sh convert article.md --mode api

调用md2wechat CLI：

bash

bash skills/md2wechat/scripts/run.sh convert article.md --mode api

AI Mode

AI模式

Read the selected style prompt from

references/themes.md

and generate HTML with inline CSS.

Important Rules:

All CSS must be inline (in
```
style
```
attributes)
No external stylesheets or scripts
Use WeChat-safe HTML tags only
Image placeholder format:
```

```
,
```

```
, etc.

Safe HTML Tags:

```
<p>
```
,
```
<br>
```
,
```
<strong>
```
,
```
<em>
```
,
```
<u>
```
,
```
<a>
```
```
<h1>
```
to
```
<h6>
```
```
<ul>
```
,
```
<ol>
```
,
```
<li>
```
```
<blockquote>
```
,
```
<pre>
```
,
```
<code>
```
```
<table>
```
,
```
<thead>
```
,
```
<tbody>
```
,
```
<tr>
```
,
```
<th>
```
,
```
<td>
```
```
<section>
```
,
```
<span>
```
(with inline styles)

Avoid:

```
<script>
```
,
```
<iframe>
```
,
```
<form>
```
External CSS/JS references
Complex positioning (fixed, absolute)

Critical for WeChat:

Create a main
```
<div>
```
container immediately after
```
<body>
```
to hold all global styles
Specify
```
color
```
explicitly for each
```
<p>
```
tag (WeChat resets to black otherwise)
Use two
```
<span>
```
tags for heading symbols: one with color+text-shadow, one with solid color

从

references/themes.md

读取选定的风格提示词，生成带有内联CSS的HTML。

重要规则:

所有CSS必须为内联样式（写在
```
style
```
属性中）
禁止使用外部样式表或脚本
仅使用微信支持的HTML标签
图片占位符格式：
```

```
、
```

```
等

安全HTML标签:

```
<p>
```
、
```
<br>
```
、
```
<strong>
```
、
```
<em>
```
、
```
<u>
```
、
```
<a>
```
```
<h1>
```
至
```
<h6>
```
```
<ul>
```
、
```
<ol>
```
、
```
<li>
```
```
<blockquote>
```
、
```
<pre>
```
、
```
<code>
```
```
<table>
```
、
```
<thead>
```
、
```
<tbody>
```
、
```
<tr>
```
、
```
<th>
```
、
```
<td>
```
```
<section>
```
、
```
<span>
```
（带内联样式）

避免使用:

```
<script>
```
、
```
<iframe>
```
、
```
<form>
```
外部CSS/JS引用
复杂定位（fixed、absolute）

微信适配关键:

在
```
<body>
```
后立即创建主
```
<div>
```
容器，用于承载全局样式
为每个
```
<p>
```
标签显式指定
```
color
```
（否则微信会重置为黑色）
为标题符号使用两个
```
<span>
```
标签：一个带颜色+文字阴影，一个为纯色

Step 4: Process Images

步骤4：处理图片

Image Generation Methods

图片生成方式

There are three ways to generate AI images:

共有三种AI图片生成方式：

Method 1: Natural Language - For Article (Recommended)

方式1：自然语言指令 - 用于文章（推荐）

Simply describe what you want in plain language:

User: "Generate a product concept image at the beginning of article.md"

User: "Add a comparison chart after the third paragraph"

User: "Create an image showing the workflow diagram in article.md"

How I process natural language requests:

Understand the intent - Identify where to insert the image
Read the article - Analyze context to create an appropriate prompt
Insert the syntax - Add
```
![alt](__generate:prompt__)
```
at the correct location
Show the prompt - Display the generated prompt for transparency
Generate and upload - Call the conversion command to complete

Note: Proceed directly with generation. Only ask for confirmation if the prompt is complex or ambiguous.

Example conversation:

User: "Add a product image at the start of my article"
Claude: "I'll add a product concept image at the beginning of article.md.
Based on your article about 'Smart Home Hub', I'll use this prompt:
'A modern smart home hub device, sleek white design with LED indicator
lights, minimalist product photography on a clean white background'
I'll proceed with generating the image."

只需用自然语言描述需求：

用户："在article.md的开头生成一张产品概念图"

用户："在第三段后添加一张对比图表"

用户："为article.md中的工作流程章节创建一张示意图"

我处理自然语言请求的流程：

理解意图 - 确定图片插入位置
读取文章 - 分析上下文以创建合适的提示词
插入语法 - 在正确位置添加
```
![alt](__generate:prompt__)
```
展示提示词 - 透明化展示生成的提示词
生成并上传 - 调用转换命令完成操作

注意：直接进行生成操作。仅当提示词复杂或模糊时才请求确认。

对话示例：

用户："在我的文章开头添加一张产品图片"
Claude："我会在article.md的开头添加一张产品概念图。
根据你关于'智能家居中枢'的文章，我将使用以下提示词：
'现代智能家居中枢设备，简洁白色设计搭配LED指示灯，简约产品摄影，纯净白色背景'
我将开始生成图片。"

Method 2: Natural Language - Standalone Image

方式2：自然语言指令 - 独立图片

Generate an image without any article:

User: "Generate an image of a cute cat sitting on a windowsill"
User: "Create a product concept: modern smart home device"
User: "Make a diagram showing user signup flow"

I will:

Create an appropriate prompt based on your description

Call:

bash skills/md2wechat/scripts/run.sh generate_image "prompt"

Return the WeChat URL and media ID

Use when: You just need an image, not for any article.

生成不用于任何文章的独立图片：

用户："生成一张猫咪坐在窗台上的可爱图片"
用户："创建一个产品概念：现代智能家居设备"
用户："制作一张展示用户注册流程的示意图"

我会：

根据你的描述创建合适的提示词

调用：

bash skills/md2wechat/scripts/run.sh generate_image "prompt"

返回微信URL和素材ID

适用场景：你仅需要图片，无需用于文章。

Method 3: Manual Syntax

方式3：手动语法

Write the image generation syntax directly in Markdown:

markdown

![Product Concept](__generate:A futuristic smart home hub device, sleek design__)

Syntax format:

![alt text](__generate:prompt__)

在Markdown中直接编写图片生成语法：

markdown

![产品概念](__generate:A futuristic smart home hub device, sleek design__)

语法格式：

![alt text](__generate:prompt__)

Processing Images by Type

按类型处理图片

For each image reference in order:

按顺序处理每个图片引用：

Local Image

本地图片

bash

bash skills/md2wechat/scripts/run.sh upload_image "/path/to/image.png"

Response:

json

{"success": true, "wechat_url": "https://mmbiz.qpic.cn/...", "media_id": "xxx"}

bash

bash skills/md2wechat/scripts/run.sh upload_image "/path/to/image.png"

响应：

json

{"success": true, "wechat_url": "https://mmbiz.qpic.cn/...", "media_id": "xxx"}

Online Image

在线图片

bash

bash skills/md2wechat/scripts/run.sh download_and_upload "https://example.com/image.png"

bash

bash skills/md2wechat/scripts/run.sh download_and_upload "https://example.com/image.png"

AI Generated Image (via CLI)

AI生成图片（通过CLI）

bash

undefined

bash

undefined

Generate with default size (2048x2048 square)

使用默认尺寸生成（2048x2048正方形）

bash skills/md2wechat/scripts/run.sh generate_image "A cute cat sitting on a windowsill"

Generate with 16:9 ratio for WeChat cover (recommended)

使用16:9比例生成微信封面图（推荐）

bash skills/md2wechat/scripts/run.sh generate_image --size 2560x1440 "prompt"


**WeChat Cover Images**: For article covers, use 16:9 horizontal ratio (2560x1440 recommended) as it displays better in WeChat's feed and article list. Square images (2048x2048) are cropped in preview.

**Note**: AI image generation requires `IMAGE_API_KEY` environment variable.

**Image Processing Pipeline**:
1. If AI generation: Call image API → get URL
2. If online: Download image to temp
3. If local: Read file
4. Compress if width > 1920px (configurable)
5. Upload to WeChat material API
6. Return `wechat_url` and `media_id`
7. Store result for HTML replacement

---

bash skills/md2wechat/scripts/run.sh generate_image --size 2560x1440 "prompt"


**微信封面图**：文章封面图推荐使用16:9横向比例（2560x1440像素），这样在微信信息流和文章列表中展示效果更好。正方形图片（2048x2048）在预览时会被裁剪。

**注意**：AI图片生成需要设置`IMAGE_API_KEY`环境变量。

**图片处理流程**:
1. 若为AI生成：调用图片API → 获取URL
2. 若为在线图片：下载至临时目录
3. 若为本地图片：读取文件
4. 若宽度超过1920px则压缩（可配置）
5. 上传至微信素材API
6. 返回`wechat_url`和`media_id`
7. 存储结果用于HTML替换

---

Step 5: Replace Image URLs

步骤5：替换图片URL

Replace placeholders in HTML:

html

<!-- Before -->
<!-- IMG:0 -->
<!-- IMG:1 -->

<!-- After -->
<img src="https://mmbiz.qpic.cn/..." />
<img src="https://mmbiz.qpic.cn/..." />

Use the WeChat URLs returned from image processing.

替换HTML中的占位符：

html

<!-- 替换前 -->
<!-- IMG:0 -->
<!-- IMG:1 -->

<!-- 替换后 -->
<img src="https://mmbiz.qpic.cn/..." />
<img src="https://mmbiz.qpic.cn/..." />

使用图片处理返回的微信URL进行替换。

Step 6: Preview or Upload

步骤6：预览或上传

Ask user:

Preview only - Show HTML for review
Upload to draft - Create WeChat draft article

询问用户：

仅预览 - 展示HTML供审核
上传至草稿箱 - 创建微信公众号草稿文章

Preview Mode

预览模式

Display HTML in markdown code block for user to copy.

在Markdown代码块中展示HTML，供用户复制。

Upload Mode

上传模式

Create draft and run:

bash

bash skills/md2wechat/scripts/run.sh convert article.md --draft --cover cover.jpg

Required for draft:

```
WECHAT_APPID
```
environment variable
```
WECHAT_SECRET
```
environment variable
Cover image (use
```
--cover
```
or first image in content)

Response:

json

{"success": true, "media_id": "draft_media_id", "draft_url": "https://mp.weixin.qq.com/..."}

创建草稿并运行：

bash

bash skills/md2wechat/scripts/run.sh convert article.md --draft --cover cover.jpg

草稿上传要求:

```
WECHAT_APPID
```
环境变量
```
WECHAT_SECRET
```
环境变量
封面图（使用
```
--cover
```
参数或正文中的第一张图片）

响应：

json

{"success": true, "media_id": "draft_media_id", "draft_url": "https://mp.weixin.qq.com/..."}

Configuration

配置

Required for WeChat API

微信API必填项

Variable	Description	Required
`WECHAT_APPID`	WeChat Official Account AppID	Yes, for draft upload
`WECHAT_SECRET`	WeChat API Secret	Yes, for draft upload

变量	描述	是否必填
`WECHAT_APPID`	微信公众号AppID	是，用于草稿上传
`WECHAT_SECRET`	微信API密钥	是，用于草稿上传

Optional for AI Features

AI功能可选项

Variable	Description	Required
`IMAGE_API_KEY`	Image generation API key	For AI images
`IMAGE_API_BASE`	Image API base URL	For AI images
`COMPRESS_IMAGES`	Compress images > 1920px (true/false)	No, default true
`MAX_IMAGE_WIDTH`	Max width in pixels	No, default 1920

变量	描述	是否必填
`IMAGE_API_KEY`	图片生成API密钥	用于AI图片生成
`IMAGE_API_BASE`	图片API基础URL	用于AI图片生成
`COMPRESS_IMAGES`	压缩宽度超过1920px的图片（true/false）	否，默认true
`MAX_IMAGE_WIDTH`	最大宽度（像素）	否，默认1920

How to Get AppID and Secret

如何获取AppID和密钥

Visit WeChat Developer Platform
Login and select your Official Account
Go to Settings & Development → Basic Configuration
Find in Developer ID section:
- Developer ID (AppID): Copy directly
- Developer Password (AppSecret): Click "Reset" to get
Add these values to environment variables or config file

Warning: AppSecret is very important, keep it secure!

访问微信公众平台开发者中心
登录并选择你的公众号
进入 设置与开发 → 基本配置
在 开发者ID 区域查找：
- 开发者ID（AppID）：直接复制
- 开发者密码（AppSecret）：点击“重置”获取
将这些值添加到环境变量或配置文件中

警告：AppSecret非常重要，请妥善保管！

Config File Location

配置文件位置

~/.config/md2wechat/config.yaml    # Global config
./md2wechat.yaml                    # Project config (higher priority)

~/.config/md2wechat/config.yaml    # 全局配置
./md2wechat.yaml                    # 项目配置（优先级更高）

Error Handling

错误处理

Error	Action
Missing config	Ask user to set environment variable or run `md2wechat config init`
Image upload fails	Log error, continue with placeholder
WeChat API fails	Show error message, return HTML for manual upload
Markdown parse error	Ask user to check file format
IP not in whitelist	Guide user to add IP to WeChat whitelist (see Troubleshooting)

错误	处理方式
配置缺失	提示用户设置环境变量或运行 `md2wechat config init`
图片上传失败	记录错误，使用占位符继续
微信API调用失败	显示错误信息，返回HTML供手动上传
Markdown解析错误	提示用户检查文件格式
IP不在白名单	引导用户将IP添加至微信白名单（见故障排查）

Complete Examples

完整示例

Example 1: Simple Article (No Images)

示例1：无图片的简单文章

Input:

simple.md

markdown

undefined

输入：

simple.md

markdown

undefined

My First Article

我的第一篇文章

This is a simple article with no images.


**Process**:
1. Generate HTML with API mode
2. Skip image processing
3. Ask: preview or upload?
4. If upload → create draft

这是一篇没有图片的简单文章。


**处理流程**:
1. 使用API模式生成HTML
2. 跳过图片处理步骤
3. 询问：预览还是上传？
4. 若选择上传 → 创建草稿

Example 2: Article with Local Images

示例2：包含本地图片的文章

Input:

with-images.md

markdown

undefined

输入：

with-images.md

markdown

undefined

Travel Diary

旅行日记

Day 1 in Paris:


**Process**:
1. Analyze: 1 local image
2. Generate HTML with `<!-- IMG:0 -->` placeholder
3. Run: `upload_image "./photos/eiffel.jpg"`
4. Replace placeholder with WeChat URL
5. Preview or upload

巴黎第一天：


**处理流程**:
1. 分析：1张本地图片
2. 生成带有`<!-- IMG:0 -->`占位符的HTML
3. 运行：`upload_image "./photos/eiffel.jpg"`
4. 用微信URL替换占位符
5. 预览或上传

Example 3: AI Mode with Theme

示例3：带主题的AI模式

Input:

story.md

markdown

undefined

输入：

story.md

markdown

undefined

The Old Library

旧图书馆

A story about memories...


**Process**:
1. User selects AI mode + autumn-warm theme
2. Read theme prompt from references/themes.md
3. Generate themed HTML with inline CSS
4. Preview or upload

一个关于回忆的故事...


**处理流程**:
1. 用户选择AI模式 + autumn-warm主题
2. 从references/themes.md读取主题提示词
3. 生成带有内联CSS的主题化HTML
4. 预览或上传

Example 4: AI Image Generation via Natural Language

示例4：通过自然语言生成AI图片

User Request:

"Help me add a product concept image at the beginning of article.md"

Process:

Read article.md to understand the product
Create an appropriate image prompt based on context
Confirm with user: "I'll use this prompt: '...'"
Insert
```
![Product Concept](__generate:...)
```
at line 2
Run conversion command to generate and upload

Result: Image generated and uploaded to WeChat

用户请求:

"帮我在article.md的开头添加一张产品概念图"

处理流程:

读取article.md以理解产品内容
根据上下文创建合适的图片提示词
与用户确认："我将使用以下提示词：'...'"
在第2行插入
```
![Product Concept](__generate:...)
```
调用转换命令完成生成与上传

结果: 图片生成并上传至微信

Example 5: Article with Pre-written Image Syntax

示例5：包含预编写图片语法的文章

Input:

mixed.md

markdown

undefined

输入：

mixed.md

markdown

undefined

Tech Review

科技评测

![Concept Art](generate:Futuristic gadget design)


**Process:**
1. Process 3 images in order
2. Each returns WeChat URL
3. Replace all placeholders
4. Final HTML with all WeChat-hosted images

---

![概念图](generate:Futuristic gadget design)


**处理流程:**
1. 按顺序处理3张图片
2. 每张图片返回微信URL
3. 替换所有占位符
4. 生成包含所有微信托管图片的最终HTML

---

References

参考文档

Style Themes - Detailed style prompts for AI themes
HTML Guide - WeChat HTML constraints and best practices
Image Syntax - Image reference syntax and generation
Writing Guide - Writer style assistant documentation
Humanizer - AI writing trace removal documentation 🆕
WeChat API - API reference

Style Themes - AI主题的详细风格提示词
HTML Guide - 微信HTML约束与最佳实践
Image Syntax - 图片引用语法与生成说明
Writing Guide - 写作风格助手文档
Humanizer - AI写作痕迹消除文档 🆕
WeChat API - API参考

Troubleshooting

故障排查

Configuration Issues

配置问题

Q: "AppID not configured" error A: Set

WECHAT_APPID

and

WECHAT_SECRET

environment variables, or run:

bash

bash skills/md2wechat/scripts/run.sh config init

Q: Config file not working A: Check config file location. Supported locations:

```
./md2wechat.yaml
```
(current directory, highest priority)
```
~/.md2wechat.yaml
```
```
~/.config/md2wechat/config.yaml
```

Q：出现"AppID未配置"错误 A：设置

WECHAT_APPID

和

WECHAT_SECRET

环境变量，或运行：

bash

bash skills/md2wechat/scripts/run.sh config init

Q：配置文件不生效 A：检查配置文件位置。支持的位置：

```
./md2wechat.yaml
```
（当前目录，优先级最高）
```
~/.md2wechat.yaml
```
```
~/.config/md2wechat/config.yaml
```

Image Issues

图片问题

Q: Image upload fails with "invalid filetype" A: WeChat supports JPG, PNG, GIF. Ensure image is in correct format:

bash

undefined

Q：图片上传失败，提示"invalid filetype" A：微信支持JPG、PNG、GIF格式。确保图片格式正确：

bash

undefined

Convert using ImageMagick

使用ImageMagick转换格式

convert input.tiff output.jpg


**Q: Images not showing in draft**
A: Images must use WeChat-hosted URLs (`mmbiz.qpic.cn`), not external URLs.

**Q: AI image generation fails**
A: Check `IMAGE_API_KEY` is set and API base URL is correct.

convert input.tiff output.jpg


**Q：草稿中图片不显示**
A：图片必须使用微信托管URL（`mmbiz.qpic.cn`），而非外部URL。

**Q：AI图片生成失败**
A：检查`IMAGE_API_KEY`是否已设置，且API基础URL正确。

WeChat API Issues

微信API问题

Q: "IP not in whitelist" error A: Add your server IP to WeChat whitelist:

Get your public IP:

bash

curl ifconfig.me

Q：出现"IP不在白名单"错误 A：将你的服务器IP添加至微信白名单：

获取你的公网IP：

bash

curl ifconfig.me

or

或

curl ip.sb


2. Add IP to WeChat:
   - Visit [WeChat Developer Platform](https://developers.weixin.qq.com/platform)
   - Go to **Settings & Development** → **Basic Configuration**
   - Find **IP Whitelist** section
   - Click "Set" and add your IP
   - Wait a few minutes for changes to take effect

**Q: "access_token expired" error**
A: Program auto-refreshes tokens. If persists:
```bash

curl ip.sb


2. 添加IP至微信：
   - 访问[微信公众平台开发者中心](https://developers.weixin.qq.com/platform)
   - 进入 **设置与开发** → **基本配置**
   - 找到 **IP白名单** 区域
   - 点击“设置”并添加你的IP
   - 等待几分钟让设置生效

**Q：出现"access_token expired"错误**
A：程序会自动刷新令牌。若问题持续：
```bash

Check config

检查配置

bash skills/md2wechat/scripts/run.sh config show

Re-init if needed

必要时重新初始化

bash skills/md2wechat/scripts/run.sh config init


**Q: "create draft failed" error**
A: Possible causes:
1. Insufficient permissions - ensure account is verified
2. Sensitive content - check article content
3. Draft limit reached - check existing drafts
4. **Content size out of limit (errcode=45002)** - article content exceeds WeChat API limit

**Q: "content size out of limit" error (errcode=45002)**
A: WeChat draft API has content limits:
- **Characters**: < 20,000 characters (中文算1个字符)
- **Size**: < 1 MB

If you encounter this error:
1. Shorten your article content
2. Reduce unnecessary formatting (inline CSS adds size)
3. Consider splitting into multiple articles
4. Use simpler themes with less inline styling

API mode generates more inline CSS which increases content size. For very long articles, consider manual editing or splitting.

**Q: API rate limit exceeded**
A: WeChat has API limits. Wait and retry:
```bash

bash skills/md2wechat/scripts/run.sh config init


**Q：出现"create draft failed"错误**
A：可能原因：
1. 权限不足 - 确保账号已认证
2. 敏感内容 - 检查文章内容
3. 草稿数量超限 - 检查现有草稿
4. **内容大小超限（errcode=45002）** - 文章内容超过微信API限制

**Q：出现"content size out of limit"错误（errcode=45002）**
A：微信草稿API有内容限制：
- **字符数**：< 20,000字符（中文算1个字符）
- **大小**：< 1 MB

若遇到此错误：
1. 缩短文章内容
2. 减少不必要的格式（内联CSS会增加大小）
3. 考虑将文章拆分为多篇
4. 使用更简洁的主题，减少内联样式

API模式会生成更多内联CSS，增加内容大小。对于超长文章，建议手动编辑或拆分。

**Q：API调用频率超限**
A：微信有API调用限制。请等待后重试：
```bash

Wait 60 seconds

等待60秒

sleep 60

Retry

重试

bash skills/md2wechat/scripts/run.sh convert article.md --draft

undefined

bash skills/md2wechat/scripts/run.sh convert article.md --draft

undefined

HTML/Style Issues

HTML/样式问题

Q: Styles not working in WeChat editor A: Check:

CSS uses inline
```
style
```
attributes (not
```
<style>
```
tags)
CSS properties are in allowed list (see HTML Guide)
No syntax errors (unclosed tags, etc.)

Q: Background color lost in WeChat A: WeChat strips

<body>

styles. Use main container:

html

<div style="background-color: #faf9f5; padding: 40px 10px;">
  <!-- All content here -->
</div>

Q: Text color not as expected A: WeChat resets

<p>

color to black. Always specify:

html

<p style="color: #4a413d;">Your text here</p>

Q：样式在微信编辑器中不生效 A：检查：

CSS使用内联
```
style
```
属性（而非
```
<style>
```
标签）
CSS属性在允许列表中（见HTML Guide）
无语法错误（如未闭合的标签）

Q：微信中背景色丢失 A：微信会剥离

<body>

样式。请使用主容器：

html

<div style="background-color: #faf9f5; padding: 40px 10px;">
  <!-- 所有内容放在这里 -->
</div>

Q：文本颜色不符合预期 A：微信会将

<p>

标签颜色重置为黑色。请始终显式指定：

html

<p style="color: #4a413d;">你的文本内容</p>

Command Issues

命令问题

Q: "command not found: md2wechat" A: The

run.sh

script will auto-download the binary on first run. If you want to install manually:

bash

undefined

Q：出现"command not found: md2wechat"错误 A：

run.sh

脚本会在首次运行时自动下载二进制文件。若需手动安装：

bash

undefined

Use the script - it will handle installation

使用脚本 - 它会处理安装

bash skills/md2wechat/scripts/run.sh --help

Or download from releases

或从发布页面下载

Visit: https://github.com/geekjourneyx/md2wechat-skill/releases

访问：https://github.com/geekjourneyx/md2wechat-skill/releases


**Q: AI mode very slow**
A: AI mode requires Claude API call and takes 10-30 seconds. For faster results, use API mode.

---


**Q：AI模式速度很慢**
A：AI模式需要调用Claude API，耗时10-30秒。若需更快结果，请使用API模式。

---

CLI Commands Reference

CLI命令参考

All commands go through the

run.sh

wrapper, which handles auto-installation:

bash

undefined

所有命令通过

run.sh

包装器执行，它会处理自动安装：

bash

undefined

Show help

显示帮助

bash skills/md2wechat/scripts/run.sh --help

Convert and preview

转换并预览

bash skills/md2wechat/scripts/run.sh convert article.md --preview

Convert with AI theme

使用AI主题转换

bash skills/md2wechat/scripts/run.sh convert article.md --mode ai --theme autumn-warm --preview

Convert and upload to draft

转换并上传至草稿箱

bash skills/md2wechat/scripts/run.sh convert article.md --draft --cover cover.jpg

Upload single image

上传单张图片

bash skills/md2wechat/scripts/run.sh upload_image photo.jpg

Download and upload online image

下载并上传在线图片

bash skills/md2wechat/scripts/run.sh download_and_upload https://example.com/image.jpg

Generate AI image (requires IMAGE_API_KEY)

生成AI图片（需要IMAGE_API_KEY）

bash skills/md2wechat/scripts/run.sh generate_image "A cute cat sitting on a windowsill"

Generate with 16:9 ratio for WeChat cover (recommended)

生成16:9比例的微信封面图（推荐）

bash skills/md2wechat/scripts/run.sh generate_image --size 2560x1440 "prompt"

Initialize config

初始化配置

bash skills/md2wechat/scripts/run.sh config init

Show config

显示配置

bash skills/md2wechat/scripts/run.sh config show

List available writing styles

列出可用写作风格

bash skills/md2wechat/scripts/run.sh write --list

Write with creator style (interactive)

使用创作者风格写作（交互式）

bash skills/md2wechat/scripts/run.sh write

Write with specific style (via stdin/piped)

使用特定风格写作（通过标准输入/管道）

echo "你的想法或内容" | bash skills/md2wechat/scripts/run.sh write --style dan-koe

Write with title and heredoc

使用标题和 heredoc 写作

bash skills/md2wechat/scripts/run.sh write --style dan-koe --title "文章标题" <<EOF 你的内容 EOF

Write with specific style

使用特定风格写作

bash skills/md2wechat/scripts/run.sh write --style dan-koe

Generate cover prompt only

仅生成封面提示词

bash skills/md2wechat/scripts/run.sh write --style dan-koe --cover-only

Remove AI writing traces (humanize)

消除AI写作痕迹（人性化处理）

bash skills/md2wechat/scripts/run.sh humanize article.md

Humanize with intensity

按指定强度进行人性化处理

bash skills/md2wechat/scripts/run.sh humanize article.md --intensity aggressive

Write with humanize

写作并进行人性化处理

bash skills/md2wechat/scripts/run.sh write --style dan-koe --humanize

Create image post (小绿书/newspic)

创建图片帖子（小绿书/newspic）

bash skills/md2wechat/scripts/run.sh create_image_post -t "Title" --images photo1.jpg,photo2.jpg

Extract images from Markdown

从Markdown中提取图片创建帖子

bash skills/md2wechat/scripts/run.sh create_image_post -t "Title" -m article.md

With description and comments

添加描述和开启评论

bash skills/md2wechat/scripts/run.sh create_image_post -t "Title" -c "Description" --images photo.jpg --open-comment

Preview mode (dry-run)

预览模式（试运行）

bash skills/md2wechat/scripts/run.sh create_image_post -t "Test" --images a.jpg,b.jpg --dry-run

---

bash skills/md2wechat/scripts/run.sh create_image_post -t "Test" --images a.jpg,b.jpg --dry-run

---

Image Posts (小绿书/Newspic)

图片帖子（小绿书/Newspic）

Create WeChat image-only posts (小绿书/图片消息) with up to 20 images.

创建最多包含20张图片的微信纯图片帖子（小绿书/图片消息）。

Natural Language

自然语言指令

"Create an image post titled 'Weekend Trip' with photos from ./photos/"
"Make a 小绿书 post with travel.md images"
"Upload these images as an image post: a.jpg, b.jpg, c.jpg"

"创建标题为'周末旅行'的图片帖子，使用./photos/中的照片"
"用travel.md中的图片制作一篇小绿书帖子"
"将这些图片上传为图片帖子：a.jpg, b.jpg, c.jpg"

Command Options

命令选项

Flag	Short	Description
`--title`	`-t`	Post title (required)
`--content`	`-c`	Description text
`--images`		Comma-separated image paths
`--from-markdown`	`-m`	Extract images from Markdown file
`--open-comment`		Enable comments
`--fans-only`		Only fans can comment
`--dry-run`		Preview without uploading
`--output`	`-o`	Save result to JSON file

参数	缩写	描述
`--title`	`-t`	帖子标题（必填）
`--content`	`-c`	描述文本
`--images`		逗号分隔的图片路径
`--from-markdown`	`-m`	从Markdown文件中提取图片
`--open-comment`		开启评论功能
`--fans-only`		仅粉丝可评论
`--dry-run`		预览模式，不实际上传
`--output`	`-o`	将结果保存至JSON文件

Examples

示例

bash

undefined

bash

undefined

Basic image post

基础图片帖子

bash skills/md2wechat/scripts/run.sh create_image_post
-t "Weekend Trip"
--images photo1.jpg,photo2.jpg,photo3.jpg

bash skills/md2wechat/scripts/run.sh create_image_post
-t "周末旅行"
--images photo1.jpg,photo2.jpg,photo3.jpg

Extract images from article

从文章中提取图片创建帖子

bash skills/md2wechat/scripts/run.sh create_image_post
-t "Travel Diary"
-m article.md

bash skills/md2wechat/scripts/run.sh create_image_post
-t "旅行日记"
-m article.md

With description and comments enabled

添加描述并开启评论

bash skills/md2wechat/scripts/run.sh create_image_post
-t "Food Blog"
-c "Today's lunch"
--images food.jpg
--open-comment

bash skills/md2wechat/scripts/run.sh create_image_post
-t "美食博客"
-c "今日午餐"
--images food.jpg
--open-comment

Read description from stdin

从标准输入读取描述

echo "Daily check-in" | bash skills/md2wechat/scripts/run.sh create_image_post
-t "Daily"
--images pic.jpg

echo "日常打卡" | bash skills/md2wechat/scripts/run.sh create_image_post
-t "日常"
--images pic.jpg

Preview mode

预览模式

bash skills/md2wechat/scripts/run.sh create_image_post
-t "Test"
--images a.jpg,b.jpg
--dry-run

undefined

bash skills/md2wechat/scripts/run.sh create_image_post
-t "测试"
--images a.jpg,b.jpg
--dry-run

undefined

Notes

注意事项

Image limit: Maximum 20 images per post
Image format: JPG, PNG, GIF (same as regular articles)
Content: Plain text only, not HTML
Requires:
```
WECHAT_APPID
```
and
```
WECHAT_SECRET
```
for upload

图片数量限制：每个帖子最多20张图片
图片格式：支持JPG、PNG、GIF（与普通文章相同）
内容：仅支持纯文本，不支持HTML
要求：上传需要
```
WECHAT_APPID
```
和
```
WECHAT_SECRET
```
环境变量