peterpanstechland WeChat Publisher（微信公众号发布）
通过微信公众号官方 API 管理图文内容：上传素材、创建草稿、发布文章。
Quick Start
CLI 位于此 skill 目录下（{baseDir} 即本 SKILL.md 所在目录），零 npm 依赖，运行方式：
node {baseDir}/wechat-publisher.mjs <command>
首次使用需初始化数据库：
node {baseDir}/wechat-publisher.mjs init
凭证配置（首次使用必读）
CLI 按以下优先级读取公众号凭证：
- 环境变量：
WECHAT_APP_ID/WECHAT_APP_SECRET（可选WECHAT_API_PROXY） - 配置文件：
<数据目录>/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 的手动流程，更灵活
选项
| 选项 | 说明 |
|---|---|
--style minimal|business|lively |
排版风格预设（默认 minimal） |
--author <name> |
作者名 |
--title <override> |
覆盖自动检测的标题 |
--digest <text> |
覆盖自动检测的摘要 |
--thumb <cover.jpg> |
指定封面图（默认用正文首图） |
--cta |
文末追加「点赞/在看/转发」引导 |
--max-content-images <N> |
正文配图上限（默认 5；图多的长文可上调，注意上传日配额） |
--dry-run |
仅预览 HTML 输出，不创建草稿 |
示例
# 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 格式和样式
三种风格预设
| 风格 | --style 值 | 强调色 | 适用场景 |
|---|---|---|---|
| 简约 | minimal |
微信绿 #07c160 |
通用、技术 |
| 商务 | business |
蓝 #1890ff |
正式、商业 |
| 活泼 | lively |
红 #ff6b6b |
轻松、活动 |
如需品牌定制色，可在 wechat-publisher.mjs 的 STYLE_PRESETS 中自行添加预设（只需一行：primary/accent/heading/quoteBg 四个颜色值）。
图片处理规则
- 首张本地图片自动作为封面（或用
--thumb指定） - 正文配图默认上传 5 张；图密集的长文可用
--max-content-images N上调（如--max-content-images 20） - 已上传图片有缓存去重，重复使用不浪费配额
- 单张上传失败最多重试 1 次，仍失败则跳过
- 外链图片保留原 URL（仅 mmbiz.qpic.cn 可在正文中显示）
自动检测规则
| 字段 | Markdown | HTML |
|---|---|---|
| 标题 | 首个 # H1 |
<title> 或 <h1> |
| 摘要 | 首个正文段落前 120 字 | 首个 <p> 前 120 字 |
| 封面 | 首张本地图片 | 首张本地 <img> |
Publish-file 流程
[1/5] 解析文件（提取标题、正文、图片、摘要）
[2/5] 上传图片（封面 + 最多5张正文配图，自动去重）
[3/5] 生成 HTML（Markdown 转内联样式 HTML，或保留原 HTML）
[4/5] 创建草稿（调用微信 API）
[5/5] 输出结果（media_id、本地记录、下一步操作）
关键原则（必读！）
- 严禁重复上传：每个文件只上传一次。CLI 内置去重，同文件再次上传会直接返回缓存结果。
- 一轮完成所有步骤：从上传到创建草稿到发布，应在同一轮对话中顺序完成，不要等用户催促才推进下一步。
- 上传完立即推进：封面上传成功拿到
media_id后，立即进入 Step 4 创建草稿，不要停下来等确认。 - 正文配图上限：一篇文章最多上传 5 张正文配图。如果原文有更多图片，选最重要的 5 张。
- 失败不重试超过 2 次：单张图片上传失败后最多重试 1 次，仍然失败则跳过该图，继续后续步骤。
- 处理大型网页/URL 时必须分段：当用户给出一个 URL 要求转发到公众号时，不要一次性把整个网页内容放进 prompt。先用 web 工具获取内容，如果内容很长（超过 8000 字），只提取正文部分（标题、正文段落、关键图片），丢弃导航栏、侧边栏、页脚、脚本、广告等无关内容。必要时分段处理：先提取并精简正文，再进行排版和发布。
- 用户只说要推微信时，只做微信：若用户明确说「排版后推到微信草稿」「发到公众号」等，不要同时创建飞书文档、Notion 等。仅执行 wechat-publisher 流程：排版 → 上传图片 → 创建草稿（及可选发布）。
- 正文中禁止占位图：content HTML 里的
<img src="...">必须使用upload-image返回的微信 CDN URL。不得使用占位符、data URI、外链或「图片说明」代替。若某张图无法上传或用户未提供，从正文中删除该图或改为文字说明（如「[此处配图：xxx]」），不要保留空框或无效 src。
长文重排并推送到微信：拆解流程（防超时）
当用户给出一篇已有长文（如在线文档链接、粘贴的全文）并要求「重新排版并推到微信草稿」时，若一次性处理容易因信息量过大、响应超时或处理了无关内容而失败。采用以下拆解方式：
何时启用拆解
- 用户提供的正文纯文本或 HTML 超过约 6000 字，或
- 用户提供的消息/附件中明显包含多篇/多段混合内容（如多期连载、多篇文章），或
- 之前同一请求曾出现超时或「处理了不知道是啥的东西」的情况。
拆解策略（两阶段）
阶段一（本轮只做精简与排版，不调用微信 API）
- 只取一篇、只取正文：若附件或消息里有多篇，只处理用户明确指定的那一篇（如「第一期」「这篇」）；其余忽略，不要混在一起排版。
- 严格限制输入长度：从原文中只取前 6000 字（或按小节取「标题 + 前 3～4 个小节」），作为「本期要排版的正文」。更长部分用一句话概括并放在文末，例如：「（后续章节可在下期推送中继续。）」
- 输出排版结果：按本 SKILL 的排版规范，生成完整可用的 content HTML（段落、小标题、引用、列表、分隔线等均带内联样式）。正文中不要插入
<img>，除非本轮已能拿到微信 CDN URL（通常阶段一不传图，或只保留 1 张封面占位说明）。 - 明确回复用户：给出标题（及备选）、摘要、以及「已按公众号规范排好版，正文约 xxx 字。请确认：若认可，请回复『推送到微信草稿』，我会再上传封面与配图并创建草稿。」
阶段二（用户确认后再执行）
- 用户回复确认后，再执行：上传封面图 → 上传正文配图（最多 5 张，若原文有图则选最重要的 5 张）→ 将 content 中的占位或说明替换为微信 CDN URL →
draft add创建草稿。 - 若用户在本轮同时提供了封面图与最多 5 张配图，且正文已在前一步排好版，则可在同一轮内完成阶段二，无需等用户再回复。
单轮可处理的正文上限
- 用于生成/排版的原文输入建议不超过 6000 字（约 1.2 万 token）。超过则先做「阶段一」精简与排版，下一轮再推送。
- 最终写入微信草稿的 content HTML 总长度仍须符合公众号限制（不超过 20000 字）。
避免「处理了不知道是啥的东西」
- 不猜测、不扩展：只处理用户明确指向的那一篇文章/那一期内容；不要自动把「下一篇预告」、其他连载、无关链接或附件一并排版或推送。
- 图片：没有真实上传并拿到微信 CDN URL 的图片，一律不写入 content；用文字说明替代或省略，不保留占位符或空白图框。
- 来源单一：若用户给的是在线文档链接（飞书 / Notion 等），只抓该文档正文，不要混入侧栏、评论、其他文档。
若按上述拆解后仍出现请求超时，可在 OpenClaw 运行环境中适当调大 agents.defaults.timeoutSeconds（具体配置位置见 OpenClaw 文档或部署配置）。
发布一篇公众号文章的完整流程
⚠️ 常规流程：整个流程应在一轮对话中连续执行。每完成一步立即进入下一步，不要中途停下来报告中间状态或等待用户确认。
例外：当用户提供的是已有长文（见上文「长文重排并推送到微信：拆解流程」）时，先做阶段一（精简+排版并回复），等用户确认后再做阶段二（上传图+创建草稿），避免单轮信息量过大导致超时或错乱。
Step 0: 处理来源 URL（如果用户提供了网页链接）
当用户给出一个 URL 说"把这篇文章发到公众号"时：
- 获取网页内容：用 web/browse 工具抓取页面。
- 精简提取：只保留文章标题、正文段落、关键配图（最多 5 张）。丢弃导航栏、侧边栏、页脚、相关推荐、广告、脚本标签等无关内容。
- 控制长度：提取后的纯文本正文控制在 8000 字以内。如果原文特别长，保留核心内容并在文末注明"阅读原文"链接。
- 下载配图：将正文中需要的图片下载到本地临时目录，后续通过
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 个字，简短有力
写作模板
根据用户描述判断文章类型，选用对应模板组织内容结构。用户未明确指定时，自动选择最匹配的模板：
| 模板 | 适用场景 | 结构 |
|---|---|---|
| 产品测评 | 产品推荐、工具评测 | 开篇引入 → 产品介绍 → 优缺点 → 使用体验 → 总结推荐 |
| 教程/干货 | 操作指南、知识分享 | 背景/痛点 → 步骤 1/2/3（每步配图）→ 注意事项 → 总结 |
| 观点文 | 热点评论、深度分析 | 热点引入 → 观点陈述 → 论据 1/2/3 → 结论与建议 |
| 资讯快报 | 行业动态、新闻摘要 | 一句话概括 → 要点 1/2/3 → 延伸阅读/原文链接 |
撰写要点：
- 正文用 HTML 标签排版（具体样式见下方「排版规范」）
- 建议每 3-4 段插入一张配图（最多 5 张），提高阅读体验
- 适当使用 emoji 增加亲和力，但不过度（标题 0-1 个，正文每段 0-2 个）
- 文末加引导语（关注、点赞、在看）
排版规范（必须遵守）
生成 content HTML 时，必须使用以下内联样式模板，保证统一 UI 风格。微信公众号仅支持内联 style 属性，不支持 <style> 标签和外部 CSS。
用户可指定「简约」「商务」「活泼」三种风格预设（未指定时默认「简约」）：
| 风格 | 主色 | 强调色 | 标题装饰 | 引用块 |
|---|---|---|---|---|
| 简约（默认） | #333 |
#07c160（微信绿） |
绿色左边框 | 灰底绿边 |
| 商务 | #1a1a1a |
#1890ff（蓝） |
蓝色左边框 | 灰底蓝边 |
| 活泼 | #333 |
#ff6b6b（红） |
红色左边框 | 浅红底红边 |
下方模板以「简约」风格为例，其他风格替换对应颜色即可。
段落：
<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 时的正确做法：
- 告诉用户：「草稿已成功创建。由于公众号未完成企业认证，无法通过 API 自动发布。」
- 引导用户：「请登录微信公众号后台 mp.weixin.qq.com → 内容管理 → 草稿箱 → 找到刚才创建的草稿 → 点击发布。」
- 不要重试 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
| Command | Description |
|---|---|
init |
初始化本地数据库（首次使用，幂等） |
auth |
显示 access_token 状态 |
upload-image <file> |
上传正文图片，返回微信 CDN URL（自动去重） |
upload-cover <file> |
上传永久封面素材，返回 media_id（自动去重） |
draft add --json '{...}' |
创建图文草稿 |
draft list [--offset N] [--count N] |
列出微信草稿箱 |
draft get <media_id> |
获取草稿详情 |
draft delete <media_id> |
删除草稿 |
publish <media_id> |
提交草稿发布 |
publish-status <publish_id> |
查询发布状态 |
history [--month YYYY-MM] [--status S] |
列出本地记录 |
search <keyword> |
搜索本地记录 |
publish-file <file> [opts] |
一键发布 Markdown/HTML 到草稿（解析→上传→创建草稿） |
convert <file.md> [--style S] |
Markdown → 微信 HTML 转换（预览，不创建草稿） |
history 筛选参数
--month YYYY-MM— 按月份--status draft|published|failed— 按状态--limit N— 最大条数（默认 50）
Important Rules
- 首次使用必须
init（幂等，可重复运行） - 正文图片 URL 必须来自
upload-image返回值，外部 URL 会被微信过滤 - 封面
thumb_media_id必须来自upload-cover返回值 - 发布是异步操作，提交后用
publish-status轮询结果 - 每日草稿创建限额 1000 次，发布限额 100 次
- 发布后草稿自动从草稿箱移除
- 如果 access_token 过期导致报错，工具会自动刷新，重试即可
- 每个文件只上传一次，CLI 内置去重缓存
- 正文配图最多 5 张，超过的选重要的保留
- 单张图片上传最多重试 1 次，仍失败则跳过继续后续步骤
- publish 返回 48001（api_unauthorized）时不要重试，这是账号认证级别的限制，引导用户去公众号后台手动发布即可