WeChat Publisher（微信公众号发布）

通过微信公众号官方 API 管理图文内容：上传素材、创建草稿、发布文章。

Quick Start

CLI 位于此 skill 目录下（{baseDir} 即本 SKILL.md 所在目录），零 npm 依赖，运行方式：

node {baseDir}/wechat-publisher.mjs <command>

首次使用需初始化数据库：

node {baseDir}/wechat-publisher.mjs init

凭证配置（首次使用必读）

CLI 按以下优先级读取公众号凭证：

1. 环境变量：WECHAT_APP_ID / WECHAT_APP_SECRET（可选 WECHAT_API_PROXY）
2. 配置文件：<数据目录>/config.json：

   {"appId": "wx...", "appSecret": "...", "proxy": "http://<中转服务器IP>:<端口>"}

数据目录解析顺序：$WECHAT_PUBLISHER_DATA_DIR → ~/.openclaw/workspace/wechat-publisher（OpenClaw 环境）→ ~/.wechat-publisher。本地数据库、token 缓存、上传去重缓存都存放在此目录。

⚠️ 微信 API 有 IP 白名单限制：调用方出口 IP 必须加入公众号后台白名单。若运行环境没有固定公网 IP（家庭宽带、笔记本等），需要在云服务器上部署 HTTP 代理做中转并配置 proxy 字段，部署方法见仓库 README。若凭证未配置或报 40164（IP 不在白名单），引导用户完成配置而不要反复重试。

一键发布文件（publish-file）

当用户提供了现成的 Markdown 或 HTML 文件时，使用 publish-file 一键完成全流程：

node wechat-publisher.mjs publish-file /path/to/article.md [options]

与手动流程的选择：

• 有现成文件（用户给了 .md/.html）→ 优先用 publish-file，一条命令搞定
• 需要创作内容（从零写起）→ 用 Step 1-7 的手动流程，更灵活

选项

示例

# Markdown 一键发布
node wechat-publisher.mjs publish-file ~/article.md --author "运营" --style business --cta

# 预览转换效果
node wechat-publisher.mjs publish-file ~/article.md --dry-run

# HTML 一键发布
node wechat-publisher.mjs publish-file ~/newsletter.html --author "编辑部"

# 纯 Markdown → HTML 转换（不上传、不创建草稿）
node wechat-publisher.mjs convert ~/draft.md --style lively

支持的文件格式

• .md / .markdown — 自动转换为带内联样式的公众号 HTML
• .html / .htm — 保留原有 HTML 格式和样式

三种风格预设

如需品牌定制色，可在 wechat-publisher.mjs 的 STYLE_PRESETS 中自行添加预设（只需一行：primary/accent/heading/quoteBg 四个颜色值）。

图片处理规则

• 首张本地图片自动作为封面（或用 --thumb 指定）
• 正文配图默认上传 5 张；图密集的长文可用 --max-content-images N 上调（如 --max-content-images 20）
• 已上传图片有缓存去重，重复使用不浪费配额
• 单张上传失败最多重试 1 次，仍失败则跳过
• 外链图片保留原 URL（仅 mmbiz.qpic.cn 可在正文中显示）

自动检测规则

Publish-file 流程

[1/5] 解析文件（提取标题、正文、图片、摘要）
[2/5] 上传图片（封面 + 最多5张正文配图，自动去重）
[3/5] 生成 HTML（Markdown 转内联样式 HTML，或保留原 HTML）
[4/5] 创建草稿（调用微信 API）
[5/5] 输出结果（media_id、本地记录、下一步操作）

关键原则（必读！）

1. 严禁重复上传：每个文件只上传一次。CLI 内置去重，同文件再次上传会直接返回缓存结果。
2. 一轮完成所有步骤：从上传到创建草稿到发布，应在同一轮对话中顺序完成，不要等用户催促才推进下一步。
3. 上传完立即推进：封面上传成功拿到 media_id 后，立即进入 Step 4 创建草稿，不要停下来等确认。
4. 正文配图上限：一篇文章最多上传 5 张正文配图。如果原文有更多图片，选最重要的 5 张。
5. 失败不重试超过 2 次：单张图片上传失败后最多重试 1 次，仍然失败则跳过该图，继续后续步骤。
6. 处理大型网页/URL 时必须分段：当用户给出一个 URL 要求转发到公众号时，不要一次性把整个网页内容放进 prompt。先用 web 工具获取内容，如果内容很长（超过 8000 字），只提取正文部分（标题、正文段落、关键图片），丢弃导航栏、侧边栏、页脚、脚本、广告等无关内容。必要时分段处理：先提取并精简正文，再进行排版和发布。
7. 用户只说要推微信时，只做微信：若用户明确说「排版后推到微信草稿」「发到公众号」等，不要同时创建飞书文档、Notion 等。仅执行 wechat-publisher 流程：排版 → 上传图片 → 创建草稿（及可选发布）。
8. 正文中禁止占位图：content HTML 里的 <img src="..."> 必须使用 upload-image 返回的微信 CDN URL。不得使用占位符、data URI、外链或「图片说明」代替。若某张图无法上传或用户未提供，从正文中删除该图或改为文字说明（如「[此处配图：xxx]」），不要保留空框或无效 src。

长文重排并推送到微信：拆解流程（防超时）

当用户给出一篇已有长文（如在线文档链接、粘贴的全文）并要求「重新排版并推到微信草稿」时，若一次性处理容易因信息量过大、响应超时或处理了无关内容而失败。采用以下拆解方式：

何时启用拆解

• 用户提供的正文纯文本或 HTML 超过约 6000 字，或
• 用户提供的消息/附件中明显包含多篇/多段混合内容（如多期连载、多篇文章），或
• 之前同一请求曾出现超时或「处理了不知道是啥的东西」的情况。

拆解策略（两阶段）

阶段一（本轮只做精简与排版，不调用微信 API）

1. 只取一篇、只取正文：若附件或消息里有多篇，只处理用户明确指定的那一篇（如「第一期」「这篇」）；其余忽略，不要混在一起排版。
2. 严格限制输入长度：从原文中只取前 6000 字（或按小节取「标题 + 前 3～4 个小节」），作为「本期要排版的正文」。更长部分用一句话概括并放在文末，例如：「（后续章节可在下期推送中继续。）」
3. 输出排版结果：按本 SKILL 的排版规范，生成完整可用的 content HTML（段落、小标题、引用、列表、分隔线等均带内联样式）。正文中不要插入 <img>，除非本轮已能拿到微信 CDN URL（通常阶段一不传图，或只保留 1 张封面占位说明）。
4. 明确回复用户：给出标题（及备选）、摘要、以及「已按公众号规范排好版，正文约 xxx 字。请确认：若认可，请回复『推送到微信草稿』，我会再上传封面与配图并创建草稿。」

阶段二（用户确认后再执行）

5. 用户回复确认后，再执行：上传封面图 → 上传正文配图（最多 5 张，若原文有图则选最重要的 5 张）→ 将 content 中的占位或说明替换为微信 CDN URL → draft add 创建草稿。
6. 若用户在本轮同时提供了封面图与最多 5 张配图，且正文已在前一步排好版，则可在同一轮内完成阶段二，无需等用户再回复。

单轮可处理的正文上限

• 用于生成/排版的原文输入建议不超过 6000 字（约 1.2 万 token）。超过则先做「阶段一」精简与排版，下一轮再推送。
• 最终写入微信草稿的 content HTML 总长度仍须符合公众号限制（不超过 20000 字）。

避免「处理了不知道是啥的东西」

• 不猜测、不扩展：只处理用户明确指向的那一篇文章/那一期内容；不要自动把「下一篇预告」、其他连载、无关链接或附件一并排版或推送。
• 图片：没有真实上传并拿到微信 CDN URL 的图片，一律不写入 content；用文字说明替代或省略，不保留占位符或空白图框。
• 来源单一：若用户给的是在线文档链接（飞书 / Notion 等），只抓该文档正文，不要混入侧栏、评论、其他文档。

若按上述拆解后仍出现请求超时，可在 OpenClaw 运行环境中适当调大 agents.defaults.timeoutSeconds（具体配置位置见 OpenClaw 文档或部署配置）。

发布一篇公众号文章的完整流程

⚠️ 常规流程：整个流程应在一轮对话中连续执行。每完成一步立即进入下一步，不要中途停下来报告中间状态或等待用户确认。

例外：当用户提供的是已有长文（见上文「长文重排并推送到微信：拆解流程」）时，先做阶段一（精简+排版并回复），等用户确认后再做阶段二（上传图+创建草稿），避免单轮信息量过大导致超时或错乱。

Step 0: 处理来源 URL（如果用户提供了网页链接）

当用户给出一个 URL 说"把这篇文章发到公众号"时：

1. 获取网页内容：用 web/browse 工具抓取页面。
2. 精简提取：只保留文章标题、正文段落、关键配图（最多 5 张）。丢弃导航栏、侧边栏、页脚、相关推荐、广告、脚本标签等无关内容。
3. 控制长度：提取后的纯文本正文控制在 8000 字以内。如果原文特别长，保留核心内容并在文末注明"阅读原文"链接。
4. 下载配图：将正文中需要的图片下载到本地临时目录，后续通过 upload-image 上传到微信 CDN。

⚠️ 绝对不要把原始网页 HTML（包含 CSS/JS/导航等）直接传给 LLM 或塞进 content 字段。AWS、Medium 等网站的完整 HTML 可能超过 25 万 token，会导致 InvalidParameter: Range of input length 错误。

Step 1: 撰写内容

帮用户撰写以下字段：

• title（必填）— 文章标题，不超过 32 个字
• author（可选）— 作者名，不超过 16 个字
• digest（可选）— 摘要，不超过 128 个字；留空则自动截取正文前 54 个字
• content（必填）— 正文，HTML 格式，不超过 20000 个字

标题优化

撰写 title 时，同时生成 2-3 个备选标题供用户选择：

主标题：xxx
备选1：xxx
备选2：xxx

标题原则：

• 善用数字（"5 个方法"、"3 分钟学会"）和悬念（"你一定不知道…"）
• 触达痛点（"还在为 xxx 发愁？"）
• 长度不超过 32 个字，简短有力

写作模板

根据用户描述判断文章类型，选用对应模板组织内容结构。用户未明确指定时，自动选择最匹配的模板：

撰写要点：

• 正文用 HTML 标签排版（具体样式见下方「排版规范」）
• 建议每 3-4 段插入一张配图（最多 5 张），提高阅读体验
• 适当使用 emoji 增加亲和力，但不过度（标题 0-1 个，正文每段 0-2 个）
• 文末加引导语（关注、点赞、在看）

排版规范（必须遵守）

生成 content HTML 时，必须使用以下内联样式模板，保证统一 UI 风格。微信公众号仅支持内联 style 属性，不支持 <style> 标签和外部 CSS。

用户可指定「简约」「商务」「活泼」三种风格预设（未指定时默认「简约」）：

下方模板以「简约」风格为例，其他风格替换对应颜色即可。

段落：

<p style="margin: 0 0 1em 0; line-height: 1.8; font-size: 16px; color: #333; letter-spacing: 0.5px;">正文内容</p>

段落间距（呼吸感）：

<p style="margin: 0; line-height: 1;"><br/></p>

小标题（h2）：

<h2 style="margin: 1.5em 0 0.8em 0; font-size: 18px; font-weight: bold; color: #1a1a1a; border-left: 4px solid #07c160; padding-left: 12px; line-height: 1.4;">小标题文字</h2>

强调文字：

<strong style="color: #07c160;">重点文字</strong>

引用块：

<blockquote style="margin: 1em 0; padding: 12px 16px; background: #f7f7f7; border-left: 4px solid #07c160; color: #555; font-size: 15px; line-height: 1.75;">引用内容</blockquote>

图片（居中 + 圆角）：

<p style="text-align: center; margin: 1.2em 0;"><img src="微信CDN_URL" style="max-width: 100%; border-radius: 8px;" /></p>

图注（图片下方可选说明）：

<p style="text-align: center; font-size: 13px; color: #999; margin: 0.3em 0 1em 0;">▲ 图片说明文字</p>

无序列表：

<ul style="margin: 0.8em 0; padding-left: 2em; color: #333;">
  <li style="margin-bottom: 0.5em; line-height: 1.8; font-size: 16px;">列表项</li>
</ul>

有序列表：

<ol style="margin: 0.8em 0; padding-left: 2em; color: #333;">
  <li style="margin-bottom: 0.5em; line-height: 1.8; font-size: 16px;">列表项</li>
</ol>

样式片段库

根据内容类型，在正文中选用以下样式片段（直接复制 HTML 使用）：

分隔线（章节之间）：

<p style="text-align: center; margin: 1.5em 0; color: #ddd; font-size: 14px; letter-spacing: 4px;">────── ✦ ──────</p>

提示框（重要提示、注意事项）：

<div style="margin: 1em 0; padding: 12px 16px; background: #fff7e6; border-left: 4px solid #fa8c16; border-radius: 0 8px 8px 0; font-size: 15px; color: #664d03; line-height: 1.75;">💡 <strong>提示：</strong>这里写提示内容</div>

总结框（要点归纳、文末总结）：

<div style="margin: 1em 0; padding: 12px 16px; background: #f0f9ff; border-left: 4px solid #1890ff; border-radius: 0 8px 8px 0; font-size: 15px; color: #333; line-height: 1.75;">📌 <strong>小结：</strong>这里写总结内容</div>

文末引导（关注、点赞、在看）：

<p style="margin: 0; line-height: 1;"><br/></p>
<p style="text-align: center; margin: 1.5em 0; color: #ddd; font-size: 14px; letter-spacing: 4px;">────── ✦ ──────</p>
<p style="margin-top: 1em; padding: 16px; background: #f0f9ff; border-radius: 8px; text-align: center; color: #666; font-size: 14px; line-height: 1.8;">如果觉得有帮助，欢迎 <strong style="color: #07c160;">点赞</strong> | <strong style="color: #07c160;">在看</strong> | <strong style="color: #07c160;">转发</strong><br/>你的支持是我持续创作的动力 👆</p>

完整排版示例

以下是一篇排版后的 content 结构示意（简约风格）：

<h2 style="margin: 1.5em 0 0.8em 0; font-size: 18px; font-weight: bold; color: #1a1a1a; border-left: 4px solid #07c160; padding-left: 12px; line-height: 1.4;">一、开篇引入</h2>

<p style="margin: 0 0 1em 0; line-height: 1.8; font-size: 16px; color: #333; letter-spacing: 0.5px;">这里是第一段正文，介绍背景和痛点。使用 <strong style="color: #07c160;">强调色</strong> 突出关键词。</p>

<p style="margin: 0; line-height: 1;"><br/></p>

<p style="margin: 0 0 1em 0; line-height: 1.8; font-size: 16px; color: #333; letter-spacing: 0.5px;">这里是第二段正文，展开论述。</p>

<p style="text-align: center; margin: 1.2em 0;"><img src="微信CDN_URL" style="max-width: 100%; border-radius: 8px;" /></p>
<p style="text-align: center; font-size: 13px; color: #999; margin: 0.3em 0 1em 0;">▲ 图片说明</p>

<p style="text-align: center; margin: 1.5em 0; color: #ddd; font-size: 14px; letter-spacing: 4px;">────── ✦ ──────</p>

<h2 style="margin: 1.5em 0 0.8em 0; font-size: 18px; font-weight: bold; color: #1a1a1a; border-left: 4px solid #07c160; padding-left: 12px; line-height: 1.4;">二、核心内容</h2>

<p style="margin: 0 0 1em 0; line-height: 1.8; font-size: 16px; color: #333; letter-spacing: 0.5px;">详细内容段落…</p>

<blockquote style="margin: 1em 0; padding: 12px 16px; background: #f7f7f7; border-left: 4px solid #07c160; color: #555; font-size: 15px; line-height: 1.75;">这里引用一段数据或名言。</blockquote>

<div style="margin: 1em 0; padding: 12px 16px; background: #fff7e6; border-left: 4px solid #fa8c16; border-radius: 0 8px 8px 0; font-size: 15px; color: #664d03; line-height: 1.75;">💡 <strong>提示：</strong>这里写注意事项</div>

<p style="text-align: center; margin: 1.5em 0; color: #ddd; font-size: 14px; letter-spacing: 4px;">────── ✦ ──────</p>

<h2 style="margin: 1.5em 0 0.8em 0; font-size: 18px; font-weight: bold; color: #1a1a1a; border-left: 4px solid #07c160; padding-left: 12px; line-height: 1.4;">三、总结</h2>

<div style="margin: 1em 0; padding: 12px 16px; background: #f0f9ff; border-left: 4px solid #1890ff; border-radius: 0 8px 8px 0; font-size: 15px; color: #333; line-height: 1.75;">📌 <strong>小结：</strong>全文要点归纳。</div>

<p style="margin: 0; line-height: 1;"><br/></p>
<p style="text-align: center; margin: 1.5em 0; color: #ddd; font-size: 14px; letter-spacing: 4px;">────── ✦ ──────</p>
<p style="margin-top: 1em; padding: 16px; background: #f0f9ff; border-radius: 8px; text-align: center; color: #666; font-size: 14px; line-height: 1.8;">如果觉得有帮助，欢迎 <strong style="color: #07c160;">点赞</strong> | <strong style="color: #07c160;">在看</strong> | <strong style="color: #07c160;">转发</strong><br/>你的支持是我持续创作的动力 👆</p>

Step 2: 上传正文配图（最多 5 张）

正文中所有图片必须使用微信 CDN URL，外部链接会被过滤。

对每张需要在文章正文中展示的图片（最多 5 张）：

node wechat-publisher.mjs upload-image /path/to/image.jpg

返回微信 CDN URL，将其嵌入 content HTML 的 <img src="..."> 中。

限制：单张不超过 1MB，支持 JPG/PNG。

去重：CLI 会自动检测同一文件是否已上传过，重复调用直接返回缓存 URL，不会浪费 API 配额。

失败处理：如果某张图上传失败，重试 1 次后仍失败则跳过，从正文中移除该 <img> 标签，继续下一步。

Step 3: 上传封面图（仅 1 张）

封面图需要一个永久素材 media_id：

node wechat-publisher.mjs upload-cover /path/to/cover.jpg

返回 media_id，用于 thumb_media_id 字段。

限制：单张不超过 10MB，支持 BMP/PNG/JPEG/GIF。

去重：同一文件再次上传会返回缓存的 media_id。

⚠️ 封面图上传成功后，立即进入 Step 4，不要停下来报告或等待用户确认。

Step 4: 创建草稿

将所有内容组合，调用 draft add：

node wechat-publisher.mjs draft add --json '{
  "title": "5个提升效率的AI工具推荐",
  "author": "运营团队",
  "digest": "这5个AI工具让你的工作效率翻倍...",
  "content": "<p>正文 HTML（图片使用 Step 2 返回的 URL）</p>",
  "thumb_media_id": "STEP3_RETURNED_MEDIA_ID",
  "content_source_url": "https://example.com/original",
  "need_open_comment": 1,
  "only_fans_can_comment": 0
}'

成功后返回 media_id（草稿ID），同时记录到本地数据库。

Step 5: 确认并发布

向用户展示草稿摘要，确认后尝试提交发布：

node wechat-publisher.mjs publish <media_id>

⚠️ 未认证公众号的发布限制：

如果公众号未完成企业认证，publish 命令会返回 error: api_unauthorized（错误码 48001）。 这不是 bug，而是微信平台的权限限制——freepublish/submit 接口仅对已认证的公众号开放。

遇到 48001 时的正确做法：

1. 告诉用户：「草稿已成功创建。由于公众号未完成企业认证，无法通过 API 自动发布。」
2. 引导用户：「请登录微信公众号后台 mp.weixin.qq.com → 内容管理 → 草稿箱 → 找到刚才创建的草稿 → 点击发布。」
3. 不要重试 publish 命令，不要尝试其他发布接口，48001 是账号级别的权限限制，无法通过代码绕过。

如果 publish 成功，会返回 publish_id。注意：发布是异步的，提交成功不等于发布完成。

Step 6: 查询发布状态

node wechat-publisher.mjs publish-status <publish_id>

发布需要几秒到几分钟不等。状态为 0 表示成功。

Step 7: 反馈用户

发布成功后，向用户汇报：

✅ 公众号文章已发布
标题: 5个提升效率的AI工具推荐
作者: 运营团队
状态: 已发布

管理草稿箱

# 列出草稿（从微信服务器获取）
node wechat-publisher.mjs draft list

# 查看草稿详情
node wechat-publisher.mjs draft get <media_id>

# 删除草稿
node wechat-publisher.mjs draft delete <media_id>

查看本地记录

所有通过此工具创建的草稿和发布记录都保存在本地数据库：

# 列出本地记录
node wechat-publisher.mjs history

# 按月筛选
node wechat-publisher.mjs history --month 2026-03

# 按状态筛选
node wechat-publisher.mjs history --status published

# 搜索
node wechat-publisher.mjs search 效率工具

CLI Commands Reference

history 筛选参数

• --month YYYY-MM — 按月份
• --status draft|published|failed — 按状态
• --limit N — 最大条数（默认 50）

Important Rules

1. 首次使用必须 init（幂等，可重复运行）
2. 正文图片 URL 必须来自 upload-image 返回值，外部 URL 会被微信过滤
3. 封面 thumb_media_id 必须来自 upload-cover 返回值
4. 发布是异步操作，提交后用 publish-status 轮询结果
5. 每日草稿创建限额 1000 次，发布限额 100 次
6. 发布后草稿自动从草稿箱移除
7. 如果 access_token 过期导致报错，工具会自动刷新，重试即可
8. 每个文件只上传一次，CLI 内置去重缓存
9. 正文配图最多 5 张，超过的选重要的保留
10. 单张图片上传最多重试 1 次，仍失败则跳过继续后续步骤
11. publish 返回 48001（api_unauthorized）时不要重试，这是账号认证级别的限制，引导用户去公众号后台手动发布即可