baoyu-post-to-wechat实战：把 Markdown 稳妥送入公众号草稿箱

返回总教程

baoyu-post-to-wechat 的实用价值，是把本地文章、图片和账号配置组织成公众号可接收的内容。最重要的边界是：草稿保存成功不等于已发布，更不等于已群发。 本文基于固定 commit 的 SKILL.md、参考文档和 API 脚本核对，案例是操作示例，非付费或账号实测；本次写作不安装、不登录、不上传、不生成草稿，也不发布。

场景与能力边界

该技能有两类内容入口。长文章接受 Markdown、已有 HTML 或纯文本，支持主题、摘要、作者、正文图片和原文链接；贴图适合多张图片加短说明，参考文档约束为最多九张，标题二十字、正文一千字，并按文件名排序上传目录中的 PNG/JPG。不要把贴图与长文章当成相同编辑器，也不要用同一套长度上限约束长文章。

长文章可以选择 api、browser 或 remote-api。API 走微信接口创建草稿；浏览器模式通过 Chrome 编辑器完成内容装配；远端 API 模式仍在本地转换和组装内容，只让微信 HTTPS 请求经 SSH SOCKS5 隧道使用远端出口。它不是把文章和脚本拷到服务器运行，更不是规避公众号权限。账号功能、接口权限和平台审核仍然有效。

前置依赖与按需安装

准备具有本地文件访问能力的 Agent、Node.js/npx 或 Bun。浏览器路线还要 Chrome、手动登录和可用剪贴板；API 路线需要对应公众号的 AppID、AppSecret、接口权限及 IP 白名单。远端 API 额外需要已获授权的 SSH 服务器，其出口 IP 必须在白名单中，认证仅支持 SSH 密钥。

以下命令结合仓库 README 的安装入口与 skills 安装器说明的筛选参数，只安装 baoyu-post-to-wechat，不必为了公众号转换安装整套技能：

1	npx skills add jimliu/baoyu-skills --skill baoyu-post-to-wechat --agent codex

Claude Code 用户将 --agent codex 替换成 --agent claude-code。--skill、--agent 属于 skills 安装器，参数已对照其官方说明核实，不是公众号脚本参数。该命令不是固定版本安装保证。严格复现本文时应使用文末固定 commit 的完整技能目录，并保留其依赖的共享文件。源码说明公众号技能自带 Markdown 转换流程，不必单独安装 baoyu-markdown-to-html。只有缺少 Bun 且确实需要全局运行时时，才考虑源码列出的 npm install -g bun；也可以使用 npx -y bun。

输入与输出约定

输入 Markdown 推荐提前写好 title、description 或 summary、author，正文使用普通 Markdown 图片链接。API 的 news 文章需要封面：技能按明确参数、frontmatter 的 coverImage/featureImage/cover/image、文章目录 imgs/cover.png、首张正文图依次寻找，仍无图片则应停下索取，不能无提示生成付费图片。这里是介绍封面需求，不要求为本教程页面配封面。

纯文本会先保存到 post-to-wechat/YYYY-MM-DD/<slug>.md。输出可能包括转换后的 HTML、图片处理产物以及草稿结果。API 的核心端点是 draft/add，返回的 media_id 标识草稿素材，不能充当公开文章链接。正确完成报告应写“草稿已保存，待后台审核”，列明账号、标题、摘要、图片数量、方法和 media_id。

可复制的自然语言 Agent 请求

请使用 baoyu-post-to-wechat，把 ./posts/release/article.md 保存到我指定公众号的草稿箱，不公开发布、不群发。先读取现有 EXTEND.md；没有则完成首次偏好设置。确认目标账号、API 权限与封面后，使用 default 主题，把普通外部链接转换为文末引用。不要预先用其他技能转 HTML。完成后报告标题、摘要、作者、图片数和 media_id，不回显任何密钥。

没有 API 凭据时可以改用：

请采用浏览器方式准备公众号长文章，保留我手动登录的步骤。先检查 Chrome、剪贴板和账号身份，只把指定 Markdown 装入编辑器并按我确认的范围保存草稿；任何公开发表或群发操作都停止等待确认。不要替我重置 AppSecret。

操作案例：技术周报进入草稿箱

假设本地已有文章 posts/weekly/article.md、正文图和指定封面。第一步加载偏好；若没有 EXTEND.md，按首次配置流程确定主题、颜色、方法、作者、评论开关及保存位置。第二步选择账号，不能因为浏览器已经登录就省略身份核对。第三步确定 API 或浏览器路线，再校验标题、摘要及图片路径。

API 路线的已核实命令形态如下。${BUN_X} 替换成 bun 或 npx -y bun，{baseDir} 替换成技能真实路径；命令会上传素材并创建草稿，不是无副作用预览：

1	${BUN_X} {baseDir}/scripts/wechat-api.ts ./posts/weekly/article.md --theme default

浏览器长文章入口则是：

1	${BUN_X} {baseDir}/scripts/wechat-article.ts --markdown ./posts/weekly/article.md --theme default

不要先把 Markdown 转成 HTML 再传入。 API 转换需要真实图片标签以便上传，浏览器转换需要占位符以便粘贴替换，两条路线处理图片不同。已有 HTML 可以作为输入，但不会按 Markdown 路线自动改造普通外链。Markdown 默认把普通外部链接转成底部引用，只有用户明确需要保留内联链接时才选择源码提供的 --no-cite。

草稿创建后，在公众号后台“内容管理 → 草稿箱”核验。若结果不确定，先检查草稿箱再重试，避免重复创建。整个案例到草稿验收结束，公开发布属于另一项需要明确授权的操作。

配置：偏好、密钥和多账号分离

EXTEND.md 查找顺序为项目 .baoyu-skills/baoyu-post-to-wechat/EXTEND.md、XDG 配置目录同名位置、用户 ~/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md，第一个存在的文件优先。可参考源码中的非敏感配置：

default_theme: default
default_color: blue
default_publish_method: browser
default_author: 技术编辑部
need_open_comment: 1
only_fans_can_comment: 0

主题包括 default、grace、simple、modern。评论字段明确映射到 API 草稿请求，不能承诺浏览器路线具有相同自动控制能力。

单账号凭据可放到环境变量或项目、用户级 .baoyu-skills/.env，键为 WECHAT_APP_ID 和 WECHAT_APP_SECRET。不要把密钥写入公开笔记、Hexo frontmatter 或 Git。多账号用 accounts:、唯一 alias 和可选 default: true 管理；每个账号可以有独立 Chrome profile。多账号凭据有账号内联配置、带别名前缀环境变量及 env 文件、无前缀回退等解析路径，因此必须报告实际选择的账号，而非只说“凭据存在”。

远端模式通过 remote_publish_host、remote_publish_user、remote_publish_identity_file 等类型明确的字段配置，不接受任意 SSH/SCP 选项。TLS 验证仍由本地进程完成，远端不落地文件，也不需要把 AppSecret 写到服务器；凭据仍会按微信认证协议发送给微信 API。

验收清单

明确选择了长文章还是贴图，以及 API/浏览器/远端 API 路线。
目标账号、作者、标题和摘要已确认，密钥没有进入日志或笔记。
API 长文章的封面存在，正文图路径可读，草稿中没有图片占位符。
外链引用、代码、列表和移动端排版符合预期。
多账号 profile 与 API 凭据没有串号。
返回草稿 media_id 或后台可确认的草稿状态，而非假造公开链接。
明确写出“尚未公开发布/群发”。

排错与常见误区

凭据缺失：按 references/api-setup.md 的路径检查，不要自动替用户更换密钥。IP 错误或 40164：核对实际出口 IP；远端服务器也可能经 NAT 从不同地址出网。找不到 Chrome：源码支持 WECHAT_BROWSER_CHROME_PATH。浏览器没有登录：停下让用户手动扫码，而不是尝试从别的软件搬运 Cookie。粘贴失败：检查系统剪贴板、macOS 辅助功能或 Linux 的按键工具。没封面：明确提供现有文件，不要把正文图误作已批准封面。贴图 --submit：在该贴图脚本里表示保存草稿，默认仅预览；不能把它类比为 X 的公开提交。远端隧道失败：检查密钥、主机校验、连通性与超时，不应以关闭主机校验作为常规修复。