如果用户询问如何切换 API 域名，请更改：

• 配置文件中的 api.md2wechat_base_url，或
• 环境变量中的 MD2WECHAT_BASE_URL

默认 API 域名：

https://www.md2wechat.cn

备用域名：

https://md2wechat.app

默认转换模式：

• 如果用户未明确传递 --mode，convert 应视为 api 模式
• 仅当用户明确要求 --mode ai 或明确请求 AI 主题化转换时，才使用 AI 模式

内置资源：

• 默认主题和默认写作风格已打包在二进制文件中
• 优先使用 MD2WECHAT_THEMES_DIR / MD2WECHAT_WRITERS_DIR 进行显式覆盖
• 然后检查项目本地的 themes/ / writers/ 目录
• 然后检查 ~/.config/md2wechat/themes/ / ~/.config/md2wechat/writers/
• 不要假设代理主机上存在仓库目录

提示词目录：

• 在猜测支持的提供商、主题或提示词模板之前，先检查 CLI
• 使用 capabilities --json 作为第一步发现
• 在选择资源之前，使用 providers list --json、themes list --json 和 prompts list --json
• 提示词覆盖顺序：MD2WECHAT_PROMPTS_DIR → 项目本地 prompts/ → ~/.config/md2wechat/prompts/ → 打包的提示词
• 不要假设磁盘上这些位置之外存在提示词 YAML 文件
• 将 CLI 发现输出视为事实来源；仅将仓库引用用作工作流帮助或样式示例

推荐的发现流程：

md2wechat capabilities --json
md2wechat providers list --json
md2wechat themes list --json
md2wechat prompts list --json
md2wechat prompts list --kind image --archetype cover --json

对于图片预设，不要假设 archetype 是唯一标准。一些信息图预设也可用作封面。在选择预设之前，请从 prompts show --json 中检查 primary_use_case、compatible_use_cases、recommended_aspect_ratios 和 default_aspect_ratio。

当任务依赖于特定模板时，先检查它：

md2wechat prompts show cover-default --kind image --json
md2wechat prompts show cover-hero --kind image --archetype cover --tag hero --json
md2wechat prompts show infographic-dark-ticket-cn --kind image --archetype infographic --tag ticket --json
md2wechat prompts show infographic-handdrawn-sketchnote --kind image --archetype infographic --tag sketchnote --json
md2wechat prompts show infographic-apple-keynote-premium --kind image --archetype infographic --tag apple --json
md2wechat prompts show infographic-victorian-engraving-banner --kind image --archetype infographic --tag victorian --json
md2wechat prompts render cover-default --kind image --var article_title='Example' --json
md2wechat generate_cover --article article.md
md2wechat generate_infographic --article article.md --preset infographic-comparison
md2wechat generate_infographic --article article.md --preset infographic-dark-ticket-cn --aspect 21:9
md2wechat generate_infographic --article article.md --preset infographic-handdrawn-sketchnote
md2wechat generate_infographic --article article.md --preset infographic-apple-keynote-premium
md2wechat generate_infographic --article article.md --preset infographic-victorian-engraving-banner --aspect 21:9
md2wechat generate_image --preset cover-hero --article article.md --model gemini-3-pro-image-preview

自然语言图片生成

你也可以要求我使用自然语言生成图片：

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

"帮我在 article.md 的开头生成一张产品概念图"
"在第二段后面添加一张展示产品功能的图片"
"为 article.md 中的对比部分创建一张图表"

我将：

1. 阅读文章以理解上下文
2. 在适当位置插入 AI 图片生成语法
3. 调用转换命令来生成并上传图片

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

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

我将：

1. 直接调用图片生成命令
2. 返回生成的图片 URL 和微信公众号素材 ID

自然语言写作辅助

你也可以要求我使用创作者风格帮助撰写文章：

根据想法撰写文章

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

我将：

1. 理解你的想法或主题
2. 使用适当的写作风格（默认：Dan Koe）
3. 生成文章结构和内容
4. 提取令人难忘的引语
5. 可选地生成匹配的封面图片

润色现有内容

"用更吸引人的风格重写这篇文章"
"用 Dan Koe 的写作风格润色我的 article.md"
"让这个内容更深刻、更犀利"

我将：

1. 阅读你现有的内容
2. 应用选定的写作风格
3. 保持原意同时改进表达

仅生成封面

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

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

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

我将：

1. 阅读文本以识别 AI 写作模式（24 种类型）
2. 移除或重写有问题的短语
3. 注入自然的人类表达方式
4. 保留核心含义和语气
5. 返回质量评分（5 个维度，满分 50）

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

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

列出可用风格

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

可用的写作风格：

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

用户可以在 writers/ 目录中添加自定义风格。详情请参阅 writers/README.md。

发现优先规则

作为 Agent 工作时：

1. 在假设某个功能存在之前，先检查 capabilities --json
2. 在选择图片提供商之前，先检查 providers list --json
3. 在选择主题之前，先检查 themes list --json
4. 在选择或渲染提示词模板之前，先检查 prompts list --json
5. 仅当 CLI 发现输出不足时，才回退到仓库引用

工作流程清单

复制此清单以跟踪进度：

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

步骤 1：分析 Markdown

读取 Markdown 文件并提取：

图片引用类型：

步骤 2：确认模式和主题

转换模式

在选择主题之前，检查实时 CLI 结果：

md2wechat themes list --json

AI 主题

这些是常见的内置示例，并非事实来源：

API 主题（快速）

这些是代表性示例。权威列表是 themes list --json。

询问用户："您希望使用哪种模式和主题？" - 仅当用户在其请求中未指定时才询问。

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

默认：如果用户未指定，则使用 API 模式。

请阅读 references/themes.md 仅用于视觉意图和提示词示例。不要将其视为权威的主题清单。

步骤 3：生成 HTML

API 模式

调用 md2wechat CLI：

md2wechat convert article.md --mode api

AI 模式

从 references/themes.md 中读取选定的样式提示词，并生成一个 AI 请求/提示词，供外部模型继续处理，最终生成符合微信公众号安全要求的 HTML，并带有内联 CSS。

重要规则：

1. 所有 CSS 必须是内联的（在 style 属性中）
2. 没有外部样式表或脚本
3. 仅使用微信公众号安全的 HTML 标签
4. 图片占位符格式：<!-- IMG:0 -->、<!-- IMG:1 --> 等

安全的 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> 标签：一个带有颜色+文字阴影，一个带有纯色

步骤 4：处理图片

图片生成方法

生成 AI 图片有三种方式：

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

只需用简单的语言描述你想要什么：

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

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

用户："在 article.md 中创建一张展示工作流程图的图片"

我如何处理自然语言请求：

1. 理解意图 - 确定在哪里插入图片
2. 阅读文章 - 分析上下文以创建合适的提示词
3. 插入语法 - 在正确位置添加 ![alt](__generate:prompt__)
4. 显示提示词 - 显示生成的提示词以确保透明度
5. 生成并上传 - 调用转换命令来完成

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

示例对话：

用户："在我的文章开头添加一张产品图片"
Claude："我将在 article.md 的开头添加一张产品概念图。
根据您关于'智能家居中心'的文章，我将使用这个提示词：
'一个现代智能家居中心设备，流线型白色设计，带有 LED 指示灯，
简约产品摄影，背景为干净的白色'
我将继续生成图片。"

方法 2：自然语言 - 独立图片

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

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

我将：

1. 根据你的描述创建合适的提示词
2. 当图片是封面或信息图时，优先使用打包的预设
3. 否则调用：md2wechat generate_image "prompt"
4. 返回微信公众号 URL 和素材 ID

使用时机：你只需要一张图片，不用于任何文章。

方法 3：手动语法

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

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

语法格式：![alt text](__generate:prompt__)

按类型处理图片

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

本地图片

md2wechat upload_image "/path/to/image.png"

响应：

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

在线图片

md2wechat download_and_upload "https://example.com/image.png"

AI 生成图片（通过 CLI）

# 使用默认尺寸生成（2048x2048 正方形）
md2wechat generate_image "A cute cat sitting on a windowsill"

# 从打包的提示词预设生成封面图片
md2wechat generate_cover --article article.md

# 从打包的提示词预设生成信息图
md2wechat generate_infographic --article article.md --preset infographic-process

# 为微信公众号封面生成 16:9 比例的图片（推荐）
md2wechat generate_image --preset cover-hero --article article.md --size 2560x1440

微信公众号封面图片：对于文章封面，使用 16:9 横屏比例（推荐 2560x1440），因为它在微信公众号的 feed 流和文章列表中显示效果更好。正方形图片（2048x2048）在预览中会被裁剪。

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

图片处理流程：

1. 如果是 AI 生成：调用图片 API → 获取 URL
2. 如果是在线图片：下载图片到临时目录
3. 如果是本地图片：读取文件
4. 如果宽度 > 1920px 则压缩（可配置）
5. 上传到微信公众号素材 API
6. 返回 wechat_url 和 media_id
7. 存储结果以供 HTML 替换

步骤 5：替换图片 URL

替换 HTML 中的占位符：

<!-- 之前 -->
<!-- IMG:0 -->
<!-- IMG:1 -->

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

使用图片处理返回的微信公众号 URL。

步骤 6：预览或上传

询问用户：

1. 仅预览 - 显示 HTML 供审查
2. 上传到草稿箱 - 创建微信公众号草稿文章

预览模式

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

上传模式

创建草稿并运行：

md2wechat convert article.md --draft --cover cover.jpg

草稿上传所需条件：

• WECHAT_APPID 环境变量
• WECHAT_SECRET 环境变量
• 封面图片（使用 --cover 或内容中的第一张图片）

响应：

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

配置

微信公众号 API 所需配置

AI 功能可选配置

如何获取 AppID 和 Secret

1. 访问 微信开发者平台
2. 登录并选择你的微信公众号
3. 进入设置与开发 → 基本配置
4. 在开发者 ID 部分找到：
   • 开发者 ID (AppID) ：直接复制
   • 开发者密码 (AppSecret) ：点击"重置"获取
5. 将这些值添加到环境变量或配置文件中

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

配置文件位置

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

错误处理

完整示例

示例 1：简单文章（无图片）

输入：simple.md

# My First Article

This is a simple article with no images.

处理流程：

1. 使用 API 模式生成 HTML
2. 跳过图片处理
3. 询问：预览还是上传？
4. 如果上传 → 创建草稿

示例 2：带本地图片的文章

输入：with-images.md

# Travel Diary

Day 1 in Paris:

![Eiffel Tower](./photos/eiffel.jpg)

处理流程：

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

示例 3：带主题的 AI 模式

输入：story.md

# The Old Library

A story about memories...

处理流程：

1. 用户选择 AI 模式 + autumn-warm 主题
2. 从 references/themes.md 中读取主题提示词
3. 生成主题化的 AI 请求/提示词
4. 在 Claude Code 或其他兼容的 AI 环境中继续处理以生成 HTML

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

用户请求：

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

处理流程：

1. 阅读 article.md 以了解产品
2. 根据上下文创建合适的图片提示词
3. 向用户确认："我将使用这个提示词：'...'"
4. 在第 2 行插入 ![Product Concept](__generate:...)
5. 运行转换命令以生成并上传

结果：图片已生成并上传到微信公众号

示例 5：带有预写图片语法的文章

输入：mixed.md

# Tech Review

![Product Photo](./product.jpg)

![Comparison Chart](https://example.com/chart.png)

![Concept Art](__generate:Futuristic gadget design__)

处理流程：

1. 按顺序处理 3 张图片
2. 每张都返回微信公众号 URL
3. 替换所有占位符
4. 最终 HTML 包含所有托管在微信公众号的图片

参考文档

• 样式主题 - AI 主题的详细样式提示词
• HTML 指南 - 微信公众号 HTML 限制和最佳实践
• 图片语法 - 图片引用语法和生成
• 写作指南 - 写作风格辅助文档
• 人性化处理 - AI 写作痕迹移除文档 🆕
• 微信公众号 API - API 参考

故障排除

配置问题

问：出现"AppID 未配置"错误 答：设置 WECHAT_APPID 和 WECHAT_SECRET 环境变量，或运行：

md2wechat config init

问：配置文件不生效 答：检查配置文件位置。支持的位置：

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

图片问题

问：图片上传失败，提示"invalid filetype" 答：微信公众号支持 JPG、PNG、GIF。确保图片格式正确：

# 使用 ImageMagick 转换
convert input.tiff output.jpg

问：草稿中图片不显示 答：图片必须使用微信公众号托管的 URL（mmbiz.qpic.cn），不能使用外部 URL。

问：AI 图片生成失败 答：检查 IMAGE_API_KEY 是否已设置且 API 基础 URL 正确。

微信公众号 API 问题

问：出现"IP not in whitelist"错误 答：将你的服务器 IP 添加到微信公众号白名单：

1. 获取你的公网 IP：

curl ifconfig.me

# 或
curl ip.sb

2. 将 IP 添加到微信公众号： * 访问 微信开发者平台 * 进入设置与开发 → 基本配置 * 找到IP 白名单部分 * 点击"设置"并添加你的 IP * 等待几分钟让更改生效

问：出现"access_token expired"错误 答：程序会自动刷新令牌。如果持续出现：

# 检查配置
md2wechat config show

# 如果需要，重新初始化
md2wechat config init

问：出现"create draft failed"错误 答：可能的原因：

1. 权限不足 - 确保账户已认证
2. 敏感内容 - 检查文章内容
3. 草稿数量达到上限 - 检查现有草稿
4. 内容大小超出限制 (errcode=45002) - 文章内容超出微信公众号 API 限制

问：出现"content size out of limit"错误 (errcode=45002) 答：微信公众号草稿 API 有内容限制：

• 字符数：< 20,000 字符（中文算 1 个字符）
• 大小：< 1 MB

如果遇到此错误：

1. 缩短文章内容
2. 减少不必要的格式（内联 CSS 会增加大小）
3. 考虑拆分成多篇文章
4. 使用样式较少的简单主题

API 模式生成的内联 CSS 更多，这会增加内容大小。对于非常长的文章，请考虑手动编辑或拆分。

问：API 调用频率超限 答：微信公众号有 API 限制。等待并重试：

# 等待 60 秒
sleep 60
# 重试
md2wechat convert article.md --draft

HTML/样式问题

问：在微信公众号编辑器中样式不生效 答：检查：

1. CSS 使用内联 style 属性（不是 <style> 标签）
2. CSS 属性在允许列表中（见 HTML 指南）
3. 没有语法错误（未闭合标签等）

问：在微信公众号中背景色丢失 答：微信公众号会剥离 <body> 样式。使用主容器：

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

问：文本颜色不符合预期 答：微信公众号会将 <p> 颜色重置为黑色。始终指定：

<p style="color: #4a413d;">你的文本在这里</p>

命令问题

问：出现"command not found: md2wechat" 答：Coding-agent skill 默认要求 md2wechat 已安装到 PATH 中，不再自带 runtime wrapper 或执行时下载逻辑。

先安装 CLI，然后重新运行 skill：

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.3/install.sh | bash
npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

如果安装程序已完成但当前 shell 仍然找不到 md2wechat，请运行：

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

问：AI 模式非常慢 答：AI 模式需要调用 Claude API，耗时 10-30 秒。如需更快结果，请使用 API 模式。

CLI 命令参考

此 skill 假设 md2wechat CLI 已安装并可在 PATH 中找到：

# 显示帮助
md2wechat --help

# 转换并预览
md2wechat convert article.md --preview

# 使用 AI 主题转换
md2wechat convert article.md --mode ai --theme autumn-warm --preview

# 转换并上传到草稿箱
md2wechat convert article.md --draft --cover cover.jpg

# 上传单张图片
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"

# 从打包的预设生成封面图片
md2wechat generate_cover --article article.md

# 从打包的预设生成信息图
md2wechat generate_infographic --article article.md --preset infographic-comparison

# 通过预设生成 16:9 比例的微信公众号封面（推荐）
md2wechat generate_image --preset cover-hero --article article.md --size 2560x1440

# 初始化配置
md2wechat config init

# 显示配置
md2wechat config show

# 列出可用的写作风格
md2wechat write --list

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

# 使用特定风格写作（通过 stdin/管道）
echo "你的想法或内容" | md2wechat write --style dan-koe

# 使用标题和 heredoc 写作
md2wechat write --style dan-koe --title "文章标题" <<EOF
你的内容
EOF

# 使用特定风格写作
md2wechat write --style dan-koe

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

# 移除 AI 写作痕迹（人性化处理）
md2wechat humanize article.md

# 人性化处理（指定强度）
md2wechat humanize article.md --intensity aggressive

# 写作并进行人性化处理
md2wechat write --style dan-koe --humanize

# 创建图片消息（小绿书/newspic）
md2wechat create_image_post -t "Title" --images photo1.jpg,photo2.jpg

# 从 Markdown 中提取图片
md2wechat create_image_post -t "Title" -m article.md

# 带有描述和评论
md2wechat create_image_post -t "Title" -c "Description" --images photo.jpg --open-comment

# 预览模式（试运行）
md2wechat create_image_post -t "Test" --images a.jpg,b.jpg --dry-run

图片消息（小绿书/Newspic）

创建微信公众号纯图片消息（小绿书/图片消息），最多可包含 20 张图片。

自然语言

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

命令选项

示例

# 基本图片消息
md2wechat create_image_post \
  -t "Weekend Trip" \
  --images photo1.jpg,photo2.jpg,photo3.jpg

# 从文章中提取图片
md2wechat create_image_post \
  -t "Travel Diary" \
  -m article.md

# 带有描述并开启评论
md2wechat create_image_post \
  -t "Food Blog" \
  -c "Today's lunch" \
  --images food.jpg \
  --open-comment

# 从 stdin 读取描述
echo "Daily check-in" | md2wechat create_image_post \
  -t "Daily" \
  --images pic.jpg

# 预览模式
md2wechat create_image_post \
  -t "Test" \
  --images a.jpg,b.jpg \
  --dry-run

注意事项

• 图片限制：每条消息最多 20 张图片
• 图片格式：JPG、PNG、GIF（与常规文章相同）
• 内容：仅纯文本，非 HTML
• 必需条件：上传需要 WECHAT_APPID 和 WECHAT_SECRET

周安装量

211

仓库

geekjourneyx/md…at-skill

GitHub Stars

714

首次出现

2026年2月5日

安全审计

Gen Agent Trust HubFail[SocketWarn](/geekjourneyx/md2wechat-skill/md2