Wechat Oa

微信公众号草稿箱管理工具集。触发词（满足任一即触发）：看看草稿箱/查看草稿/草稿列表/公众号草稿/搜草稿/搜索草稿/按关键词找草稿/按标题搜/创建草稿/新建草稿/发文章到公众号/推送文章/更新草稿/删除草稿/批量删除草稿/生成封面图/上传图片到公众号/上传图片到素材库/已发布文章列表/公众号素材列表/素材管理/删...

Woody@andy8663

Install

openclaw skills install @andy8663/wechat-oa

wechat-oa

微信公众号草稿箱管理工具集。基于官方微信 API。

WeChat Official Account draft management toolkit. Built on official WeChat APIs.

⚠️ 使用前必读 / MUST READ BEFORE USE

创建或更新公众号文章前，AI 必须先阅读 design.md 排版规范。

Before creating or updating any WeChat article, AI MUST read design.md layout specification first.

涵盖内容 / Covers:

容器宽度（文章 677px / 图文卡片 375px）
字体规范（clamp() 响应式字号）
配色规范（≤5 主体色，对比度 ≥4.5:1）
布局规范（Flex/Grid only，禁止 absolute/float）
标题规范（禁止重复主标题、header 标签、左边框装饰）
内容结构（扁平结构，有/无背景色的 padding 规则不同）
CSS/HTML/JS 限制（公众号渲染器兼容性白名单）

📖 完整规范见 design.md

🚀 快速开始 / Quick Start

1. 安装 / Install

bash

pip install wechat-oa

2. 配置凭证 / Configure Credentials

bash

cp config.example.json config.json
# 编辑 config.json，填入 APP_ID 和 APP_SECRET
# Edit config.json, fill in APP_ID and APP_SECRET

3. 试试看 / Try It Out

bash

# 查看草稿列表
wechat-oa list

# 创建新草稿
wechat-oa create article.md --digest "这是文章摘要"

📦 安装与配置 / Installation & Configuration

获取 AppID 和 AppSecret / Get AppID & AppSecret

登录微信公众平台
进入 设置与开发 → 基本设置
复制 公众号 AppID 和 公众号 AppSecret（如未设置需先启用）

IP 白名单配置 / IP Whitelist Configuration

调用微信 API 前，必须将服务器 IP 加入白名单：

推送模式	需要加入白名单的 IP	说明
`direct`	本机出口 IP	直连微信 API，配本机 IP
`hybrid`	本机出口 IP	优先直连，失败自动切中转
`relay`	服务器 IP `120.79.2.44`	通过中转服务器调用微信 API

配置步骤：

登录微信公众平台
进入 设置与开发 → 安全中心 → IP 白名单 → 点击「配置」
填入对应模式的 IP（多个 IP 用回车分隔）
保存

⚠️ 不添加 IP 白名单会导致 API 调用失败！

💡 不方便配本机 IP 白名单？ 使用 hybrid 或 relay 模式，只需将服务器 IP 120.79.2.44 加入白名单即可。

配置文件 / Config File

将 config.example.json 复制为 config.json，填入你的凭证：

⚠️ 注意：config.json 必须使用标准 JSON 格式，不要保留 // 注释，否则会导致解析错误。

json

{
  "default_account": "main",
  "current_account": "main",
  "PUSH_MODE": "hybrid",
  "WECHAT_OA_SERVER": "https://synergyinfo.tech",
  "WECHAT_OA_SERVER_KEY": "",
  "ENV": "prod",
  "accounts": {
    "main": {
      "name": "主公众号",
      "author": "你的名字",
      "voice_name": ["主号", "主公众号"],
      "APP_ID": "wx0000000000000000",
      "APP_SECRET": "00000000000000000000000000000000"
    }
  }
}

PUSH_MODE 说明：

模式	说明	适用场景
`direct`	直连微信官方 API	IP 固定且可配白名单
`relay`	通过中转服务器推送	IP 不固定，无法配白名单
`hybrid`	优先直连，失败自动切换中转	推荐 — 兼顾速度与稳定性

🔑 如何获取 WECHAT_OA_SERVER_KEY？
访问同协云平台订购月卡获取卡密：https://saas.synergyinfo.tech/products/wechat-oa

⚠️ config.json 包含凭证，不要提交到 GitHub！已在 .gitignore 中忽略。

📝 核心功能 / Core Features

草稿管理 / Draft Management

命令	说明	示例
`list`	查看草稿列表	`wechat-oa list`
`create <文件>`	创建新草稿（支持 .html 和 .md）	`wechat-oa create article.md`
`update <media_id> <文件>`	更新已有草稿	`wechat-oa update <media_id> article.md`
`delete <media_id>`	删除草稿	`wechat-oa delete <media_id>`

素材管理 / Material Management

命令	说明	示例
`upload <图片>`	上传图片到永久素材库	`wechat-oa upload cover.png`
`count`	获取素材总数	`wechat-oa count`
`materials [type]`	批量获取素材列表	`wechat-oa materials image`
`del-material <media_id>`	删除素材	`wechat-oa del-material <media_id>`

自动功能 / Auto Features

自动封面生成：根据文章标题生成科技风封面图（2.35:1 比例）
智能摘要：AI 推送文章时生成 1-2 句精准摘要传入 --digest 参数

🎨 高级功能 / Advanced Features

中继模式 (Relay Mode) / AI 收支付

当 config.json 中 PUSH_MODE 设为 relay 时，文章通过公网服务器（wechat-oa-server）中转推送到微信公众号。中继模式支持 支付宝 AI 收 标准协议（HTTP 402 + Payment-Needed）。

推送流程（免费模式）：

bash

wechat-oa create article.md

推送流程（收费模式）：

调用 create → 服务端返回 HTTP 402 + Payment-Needed
客户端保存 Payment-Needed → 调用 alipay-bot 发起支付
用户扫码完成支付 → 告诉 Agent "已支付"
调用 finish_push(trade_no, payload) → 服务端验证 → 执行推送

摘要（digest）生成规范 / Digest Generation

推送或更新文章时，AI 必须生成摘要并传入 --digest 参数，不要留空让服务端自动提取。

摘要生成步骤：

读取文章全文（MD/HTML 文件内容）
识别文章类型（技术文章、产品介绍、资讯、教程等）
提取核心观点或亮点（不是简单截取开头）
用 1-2 句话概括，语言简洁有吸引力
确保不超过 120 字（微信限制 128 字，留余量）

摘要要求：

维度	规范
长度	1-2 句话，不超过 120 字（微信限制 128 字，留余量）
内容	概括文章核心观点或亮点，不是机械截取正文前几句
风格	简洁有吸引力，让读者在公众号消息列表中有点击欲望
语言	与文章正文语言一致

示例：

文章：介绍一款新的 AI 编程工具
摘要："这款 AI 编程助手能自动补全代码，支持 20+ 编程语言，让你的开发效率提升 3 倍！"

命令示例：

bash

wechat-oa create article.md --digest "这款 AI 编程助手能自动补全代码..."

📚 命令参考 / Command Reference

命令 Command	说明 Description	底层API Underlying API
`list`	查看草稿列表（含标题+时间）	`draft/batchget`
`get <media_id>`	获取单篇草稿详情	`draft/get`
`create <文件> --digest <摘要>`	创建新草稿（支持 .html 和 .md）	`draft/add`
`create <文件> --force-cover`	创建草稿并强制生成封面	`draft/add`
`update <media_id> <文件>`	更新已有草稿	`draft/update`
`delete <media_id>`	删除草稿	`draft/delete`
`upload <图片文件>`	上传图片到永久素材库	`material/add_material`
`count`	获取各类永久素材总数	`material/get_materialcount`
`materials [type]`	批量获取素材列表	`material/batchget_material`
`del-material <media_id>`	删除素材	`material/del_material`
`cover <标题>`	生成封面图预览（不推送）	PIL local generation

🖼️ 正文图片处理 / Inline Image Processing

自动上传流程 / Auto-upload Flow

创建或更新草稿时，系统会自动处理正文中的图片：

text

HTML/MD 文件
    ↓
提取 <img src="..."> 或 ![alt](path)
    ↓
本地图片？ ──是──→ 上传到微信素材库 ──→ 获取微信 URL
    ↓ 否
网络图片？ ──是──→ 保留原 URL（可选下载上传）
    ↓ 否
跳过（已是微信素材库图片）
    ↓
替换 HTML 中的 src 为微信 URL
    ↓
推送草稿

支持的图片格式 / Supported Formats

HTML: <img src="local/image.png"> 或 <img src="http://example.com/img.png">
Markdown: ![描述](./images/photo.jpg)
路径类型: 相对路径、绝对路径、file:/// 协议

❓ 常见问题 / FAQ

Q1：为什么我的文章段落之间没间距？

A：微信渲染器会删除所有 margin。解决方法：用 <br> 代替，详见 design.md。

Q2：为什么标题颜色没生效？

A：可能 CSS 里 color 属性出现了两次，后面的覆盖前面的。检查 design.md 的 CSS 限制章节。

Q3：推送时提示 IP 不在白名单？

A：按照"安装与配置 → IP 白名单配置"章节，将对应 IP 加入白名单。

💡 特性 / Features

公众号排版规范 / WeChat MP layout specification：内置 design.md 排版规范，AI 生成 HTML 时必须遵循
行内样式转换 / Inline-style conversion：自动将 HTML 中的 <style> 标签转换为行内 style="" 属性，兼容微信文章渲染
自动封面生成 / Auto cover generation：根据文章标题生成科技风封面图（2.35:1 比例）
正文图片自动上传 / Auto inline image upload：自动提取 HTML/MD 中的本地图片，上传到微信素材库并替换 URL
智能摘要 / Smart digest：AI 推送文章时生成 1-2 句精准摘要

📝 输出文件 / Output Files

封面图默认保存在 .cache/cover.png

🐛 问题反馈 / Feedback

🌐 GitHub Issues：https://github.com/andy8663/wechat-oa
📧 邮箱：andy8663@126.com
🔔 微信公众号：技术定义未来（ID: gh_b906288c4c2f）

💡 提交 Issue 前建议先搜索是否已有类似问题

📖 相关文档 / Related Documents

design.md - 排版风格规范（必读）
README.md - 项目介绍与安装指南