快速开始

需要 Node.js 20.19.0 或更高版本。

把 Skill 安装到共享 Agent 目录：

npx wechat-mp-publisher@latest install --target agents

校验并预览文章：

npx wechat-mp-publisher@latest validate article.html
npx wechat-mp-publisher@latest preview article.html

随后让 Agent 为微信公众号准备文章。你确认本地预览后，Skill 才能上传素材并创建草稿；最终审核和发布仍在微信公众号后台完成。

为什么先走本地流程

wechat-mp-publisher 把可安装的本地工具与远程发布流程明确分开：

| 层级 | 职责 | 凭证边界 | | --- | --- | --- | | 本地 CLI | 安装 Skill、校验文章 HTML，并渲染手机宽度的沙箱预览。 | 不读取微信凭证，也不调用微信 API。 | | Agent Skill | 改写来源内容，在你明确确认后上传图片并创建草稿。 | 只在运行时从你指定的来源读取凭证。 | | 微信后台 | 手机预览、最终编辑审核与发布。 | 始终由你控制。 |

本地预览只监听 127.0.0.1，使用随机会话路径，并在沙箱 iframe 中渲染文章。脚本、表单、fetch 连接与嵌入对象均被禁用；图片仅允许读取文章目录内的本地文件和 mmbiz.qpic.cn 上的 HTTPS 文件。

安装与更新

选择一个安装目标：

npx wechat-mp-publisher@latest install --target agents
npx wechat-mp-publisher@latest install --target opencode
npx wechat-mp-publisher@latest install --target claude
npx wechat-mp-publisher@latest install --target codex
npx wechat-mp-publisher@latest install --target all

安装或更新前，可以检查所有已知目标：

npx wechat-mp-publisher@latest status --target all

对 npm 包管理的副本，重新运行对应的安装命令即可更新。安装器拒绝覆盖未受管目录或符号链接。如果受管副本含有本地修改，请先检查差异，再决定是否使用 --force；额外的本地文件会被保留，CLI 也会打印它创建的恢复路径。

也可以全局安装可执行程序：

npm install --global wechat-mp-publisher
wechat-mp-publisher install --target agents

从 v1 的 git clone 迁移

v1 文档把本仓库直接克隆进 OpenCode Skill 目录。v2 安装器会正确地把它识别成未受管目录，因此不会覆盖。

1. 检查旧克隆并保留所有本地修改。
2. 把旧克隆移到目标 Skill 路径之外作为备份。
3. 运行 v2 的 npm 安装命令。
4. 对比备份，确认不再需要后再删除。

不要对旧克隆使用 --force；它只适用于已经由本 npm 包管理的目录。

校验与预览

validate 提供简洁输出，doctor 会解释每一条规则：

npx wechat-mp-publisher@latest validate article.html
npx wechat-mp-publisher@latest doctor article.html
npx wechat-mp-publisher@latest validate article.html --final
npx wechat-mp-publisher@latest validate article.html --final --json

默认模式允许相对本地图片，并把它们标记为仅供预览的警告。上传图片后，--final 会把本地图片路径升级为错误，并报告文章能否进入 draft/add。

打开实时本地预览：

npx wechat-mp-publisher@latest preview article.html

发布工作流

安装后，Skill 会引导 Agent 完成一条带控制点的流程：

1. 确认来源、元数据、文章图片与封面。
2. 把内容改写成保守的移动端 HTML。
3. 运行本地校验并打开沙箱预览。
4. 在任何远程写入前停止，向你请求明确确认。
5. 在运行时获取稳定 access token。
6. 上传文章图片与永久封面素材。
7. 再次运行 validate article.html --final，且只在 draftReady:true 时调用 draft/add。
8. 返回草稿，由你在微信公众号后台审核并发布。

Skill 永远不会指示 Agent 调用自动发布接口。

微信侧前置条件

目标微信公众号当前必须具备 token、图片／素材与草稿接口权限。

• 在微信开发者平台配置账号。
• 把 AppID 与 AppSecret 放进运行时环境变量或现有密钥管理器。
• 永远不要提交、粘贴、打印凭证，也不要把凭证放进命令参数。
• 把微信实际看到的稳定公网出口 IPv4 加入账号 API 白名单。
• 遇到 48001 时停止，把它视为账号没有对应接口权限。

官方参考：

• 开发者平台迁移
• 稳定版 access token
• 新增草稿

保守 HTML 检查

校验器会捕获常见的静默失败与不安全标记：

• 根节点不是 section，或页面级背景／文字颜色；
• <style>、脚本、iframe、表单、嵌入对象与 meta refresh；
• class、id、事件处理器与 javascript: URL；
• 原生列表、<pre>、水平滚动与 white-space: pre*；
• 不安全的外部图片、本地预览图片，以及非安全协议的微信图片；
• 过长引用、编辑占位符与文档规定的内容体积边界。

通过本地检查，并不能替代微信公众号后台里的最终手机预览。

CLI 参考

wechat-mp-publisher install [--target agents|opencode|claude|codex|all]
wechat-mp-publisher uninstall [--target ...]
wechat-mp-publisher status [--target ...] [--json]
wechat-mp-publisher validate <article.html> [--final] [--json]
wechat-mp-publisher doctor <article.html> [--final] [--json]
wechat-mp-publisher preview <article.html> [--port 4173] [--no-open]

使用 --dir <path> 指定自定义 Skill 目录。--force 只能替换由本包管理的安装；卸载也只处理受管安装。

开发与发布

npm install
npm test
npm run check
npm run pack:audit

打包审计会检查 npm 最终文件清单、执行包内白名单，并阻止本项目已知的私有工作区路径与凭证标记。它是代码审查的补充，不是通用的密钥扫描器。

发布使用 GitHub Actions 与 npm Trusted Publishing。Release 标签必须以 v<version> 与 package.json 对齐；工作流运行完整的 prepublishOnly 检查，并通过 OIDC 向 npm 认证，不保存长期 npm token。

npm version patch
git push origin main --follow-tags

需要时使用 minor 或 major。正常发布流程不要在本地运行 npm publish。

链接

• 交互式项目页
• npm 包
• GitHub Releases
• 已归档的 MCP 前身

许可证

ISC