Wechat Native Publisher

wechat-native-publisher

微信公众号图文「排版 + 推送」一体化工具链。解决公众号领域最头疼的问题：

1. 排版：公众号不认原生 HTML 粘贴，/ 边框背景会被清洗。必须用「微信原生富文本」结构才能做出白底 + 图标 + 卡片化精品排版，且 浏览器预览 = 微信端真实渲染。
2. 流程：很多工具只能让你「复制粘贴」一段 HTML 再去手动贴。本工链直接把正文推到草稿箱，你只需检查排版后点「发布」——正文 0 编辑。

适用人群

• 泛内容运营者：公众号作者、编辑、代运营、写手，把自己定稿的 md/txt/word 一键变成精品图文。
• 不需要写代码：用 md 流水线即可；要高度定制再走 Python 组件 流水线。

第一次使用：确认你的排版风格（第 0 步，2 分钟）

先跑一遍「排版偏好确认」向导，把主题色、署名、渲染规范固定成你的 wnp_profile.json， 之后每次推送/预览自动套用，不用重复回答：

$PY "$SKILL/scripts/init_profile.py"          # 交互式：账号署名 → 主题三选一或自定义配色 → 渲染规范 → 打印确认单 → 保存

不想交互可参数直给（脚本化）：

$PY "$SKILL/scripts/init_profile.py" --name 我的账号 --slogan "清醒，但不冷漠" \
    --theme custom --primary "#2456a6" --accent "#ff6b4a" \
    --concept highlight --numbering on --end-sign on --cover auto

生成的 wnp_profile.json（放你的工作目录即可，push_draft/make_preview 自动发现）：

• theme：signature / mono / paper / custom（自定义主色+强调色，16 色槽自动衍生）
• sign：文末品牌签名位（名字 + 签名语）；frontmatter 写了 sign_name 时以文章为准
• rules：==高亮== 用荧光笔还是黑粗 / ## 是否自动编号 01、02… / 文末签名开关
• cover：无封面时是否自动生成同主题几何封面

排版规范（wnp_profile.json）与公众号凭据（config.json）完全分离：前者管「长什么样」， 后者管「推到哪」。凭据依旧只走 --config，profile 里永不存 appid/appsecret。

一键流程（两种使用方式）

方式一：自动排版模式（推荐，0 代码）—— 技能帮你排版

你给纯文本/md，技能用组件库自动排版成微信原生富文本，再推草稿箱。排版本身是这个技能的硬实力，不需要你自己写HTML。

PY=python   # 建议 Python 3.10+（需 requests、Pillow）
SKILL=wechat-native-publisher

# 1) 首次先自检环境（凭据/AppID/IP白名单/连接，有问题会给你指引）
$PY "$SKILL/scripts/push_draft.py" --check-env --config 

# 2) 把定稿 md 推到草稿箱（自动套用当前目录 wnp_profile.json 的排版规范）
$PY "$SKILL/scripts/push_draft.py" --config  \
    --md "$SKILL/examples/sample.md"

# 只预览不推送（先自检 + 打印正文）：
#   $PY .../push_draft.py --config  --md article.md --no-push
# 换主题（覆盖 profile）：--theme mono / --theme paper
# 换排版规范：--profile <其他路径>；跳过自检：--no-validate；BLOCK 仍强推：--force

方式二：HTML 直输模式 —— 你/AI 已排好版，技能直接推送

你或AI已经用HTML排好版了（符合微信白名单规则：section/rgb/span leaf），技能直接验证+上传图片+推草稿箱。不需要重新排版。

# 把已排好版的 HTML 推到草稿箱
$PY "$SKILL/scripts/push_draft.py" --config  \
    --html "$SKILL/examples/sample_html.html"

# 只预览不推送：
#   $PY .../push_draft.py --config  --html article.html --no-push

HTML 文件格式要求：

• 元数据用 HTML 注释 frontmatter：<!-- title: 标题 author: 作者 digest: 摘要 cover: 封面路径 -->
• 正文为 `` 内内容（或全文，技能自动提取）
• 必须符合微信白名单规则（用 不用/，颜色用 `rgb()` 不用 hex，文本节点包 ）
• 发布前自检会自动拦截不符合规则的内容，告诉你哪里要改
• 图片用 ``，技能自动上传到微信CDN并替换URL

md 语法约定（确定性映射，一字不改）

内容原则：只做结构映射，不增删、不改写文案。你写的正文长什么样，推出去就长什么样。

主题

--theme 一键换肤；渲染与封面取色都跟随主题。 custom 由 init_profile.py --theme custom --primary #RRGGBB --accent #RRGGBB 定义； 主色管结构（徽章/章节方块/列表/竖线），强调色管焦点（荧光笔/概念/结尾卡）， 浅底/浅边/深字/投影等其余槽位按同一色族自动算出，不用你配全。

目录结构

wechat-native-publisher/
├── SKILL.md
├── scripts/
│   ├── themes.json        # 三套主题的颜色槽（16 个语义槽）
│   ├── theme.py           # 主题加载/换肤/hex 取色 + 自定义配色衍生(apply_custom)
│   ├── renderer.py        # 核心渲染组件库（微信可存活结构：section/rgb/span leaf）
│   ├── md2render.py       # md/txt → 微信组件的确定性解析器（rules：概念高亮/编号）
│   ├── init_profile.py    # ★第 0 步：排版偏好确认向导 → 生成 wnp_profile.json
│   ├── profile.py         # wnp_profile.json 读取/换肤/规则应用（push/preview 共用）
│   ├── validate.py        # 发布前自检（hex/table/text-decoration/script 等 B 级拦截）
│   ├── wx_api.py          # 微信 API（token/封面/正文插图/草稿）—— 不内置凭据
│   ├── make_cover.py      # 封面：插画合成(+裁白边叠字品牌条) / 几何占位(--no-art)
│   └── make_preview.py    # 本地离线预览（微信同结构 + base64 插图；支持 --profile）
├── examples/
│   ├── sample.md          # 通用示例（去品牌，可直接套用）
│   └── sample_html.html   # HTML直输示例（已排好版的微信兼容HTML）
└── references/
    └── wechat-whitelist.md# 微信富文本存活细节

进阶「Python 组件流水线」请按 SKILL.md 下方组件速查，用 scripts/renderer.py 的组件 自建一个文章模块（导出 TITLE/AUTHOR/DIGEST/COVER/ILLUSTRATIONS/build_content(images)）。

进阶：Python 组件流水线

需要高度定制（首屏摘要框、part_header 章节头、结尾赞看转卡片等富组件）时，写一个文章模块（导出 TITLE/AUTHOR/DIGEST/COVER/ILLUSTRATIONS/build_content(images)），用 renderer 组件拼正文：

$PY .../push_draft.py --config  --build examples.article
$PY .../make_preview.py --build examples.article --out preview.html

组件速查（scripts/renderer.py）：p/key/concept/num_badge/dot/quote_card/summary_box/part_header/chapter_header/section_title/summary_title/img/caption/hr_dashed/signature/end_card。全部输出 section+rgb()+span leaf 的微信存活结构。

配色与安全要点

• 颜色必须用 rgb()，不能用 hex（微信富文本会清洗 hex）；下划线用 border-bottom（不用 text-decoration）；容器统一 （不用 /``）。
• 凭据绝不写进 skill：config.json 由 --config 指定，或环境变量 WECHAT_PUSH_CONFIG。skill 目录不留 config.json。
• 安全：本 skill 无任何第三方远程渲染，所有处理本地完成；只写入「草稿箱」不群发（群发需管理员扫码）。

v1.2.1 安全防护（SSRF + 路径遍历）

远程图片URL防护（SSRF）：

• 下载远程图片前解析主机名，拒绝所有私有/回环/链路本地/多播/保留IP（IPv4+IPv6）
• 禁用HTTP重定向（防止公开URL重定向到内部地址）
• 仅允许80/443端口
• 流式下载，单张图片最大20MB
• 验证Content-Type为图片类型
• 用Pillow解码验证下载内容确实是有效图片

本地图片路径防护（路径遍历）：

• 所有本地图片路径用 os.path.realpath() 解析后，验证仍在授权目录（文章所在目录）之下

• 拒绝 ../ 路径遍历和绝对路径逃逸

• 验证是常规文件（非目录/设备/FIFO）

• 仅允许 .jpg/.jpeg/.png/.gif/.webp/.bmp 格式

• 单张图片最大20MB

• 需 requests + Pillow（封面/插图本地处理）。桌面/服务器均可。

参考

• 微信富文本「可存活」结构细节 → references/wechat-whitelist.md
• 新手环境指引/errcode 对照 → push_draft.py --check-env