1. 项目概述一个为AI Agent量身定制的微信公众号发布工具如果你和我一样经常需要把Markdown格式的技术文章、项目文档发布到微信公众号那你一定体会过那种“水土不服”的痛。微信后台的富文本编辑器对HTML的支持非常“特立独行”直接复制粘贴Markdown渲染后的网页内容格式十有八九会乱掉图片不显示、代码块错位、列表样式丢失都是家常便饭。过去我不得不手动在微信编辑器里一点点调整或者依赖一些第三方转换工具但流程总是割裂的。直到我遇到了white0dew/wechat-skill这个项目它彻底改变了我的工作流。这不仅仅是一个Markdown转微信HTML的工具更是一个为Codex和OpenClaw这类AI Agent框架深度优化的Skill技能。它的核心思路非常清晰将“内容格式化”与“发布自动化”这两个最耗时的环节打包成一个原子化操作让AI Agent能像调用一个函数一样完成从Markdown草稿到微信草稿箱的全流程。对于开发者、内容创作者和自动化流程构建者来说这意味着你可以把精力完全集中在内容创作上而将繁琐的排版和上传工作交给程序。这个项目包含两个核心部分一个提供实时预览和转换的Web应用md2wechat以及一个能驱动浏览器自动操作微信公众号后台的CDPChrome DevTools Protocol脚本。最巧妙的是它为AI使用场景做了大量预设和约定比如默认使用线上服务而非本地启动这极大地降低了AI Agent的使用门槛和出错概率。接下来我将为你深入拆解这个项目的设计哲学、核心用法以及我在实际集成和自动化发布中积累的一手经验。2. 核心设计思路与Skill解析2.1 为什么是“Skill”而非普通工具库理解这个项目首先要理解Skill在AI Agent生态中的定位。在Codex/OpenClaw的语境下一个Skill是一个封装好的、可被AI直接理解和调用的能力单元。它通常包含清晰的输入输出定义、错误处理逻辑以及最重要的——使用约定。post-to-wechat这个Skill的设计充分体现了对AI协作的深度思考。普通工具可能会提供一堆API和配置项把选择权抛给调用者。但AI在处理复杂、多步骤的任务时过多的选择会增加其决策负担和出错率。因此这个Skill采用了“约定优于配置”和“提供默认最佳路径”的原则。Skill内明确的约定包括执行路径决策Skill内部逻辑会判断当用户只需要HTML时就只做Markdown转换当需要发布时则自动走完整的CDP自动化流程。AI无需自己判断该走哪条路。操作默认值默认使用“复制富文本”按钮而非直接操作DOM默认保存为草稿默认标记为原创。这些都是经过验证的、最稳妥的公众号发布操作流程。资源访问策略默认使用线上站点https://wechat.reshub.vip。这是一个关键设计。对于AI Agent来说启动一个本地开发服务器是高风险操作涉及端口占用、依赖安装、进程管理而直接访问一个稳定的线上服务则简单可靠得多。Skill明确约定只有在用户显式要求本地开发或调试时才启动本地服务。实操心得这种为AI“铺好路”的设计理念非常值得学习。我们在为AI构建工具时目标不应该是提供最全的功能而是提供最确定、最不易出错的执行路径。明确的默认行为和清晰的触发条件能极大提升AI Agent完成任务的成功率。2.2 项目结构深度解读项目的模块化结构清晰地区分了核心逻辑、用户界面和自动化脚本这使得它既易于使用也便于二次开发。. ├── apps/ │ └── web/ # Next.js 前端应用 ├── packages/ │ ├── core/ # 核心转换引擎 │ └── cli/ # 命令行接口 ├── skill/ │ └── post-to-wechat/ # AI Skill与CDP自动化脚本 └── docs/ └── wechat-compatibility.md # 兼容性圣经packages/core这是项目的心脏。它负责将标准的Markdown包含GFM扩展如表格、任务列表转换为微信编辑器兼容的HTML片段。它的转换逻辑不是简单的Markdown渲染而是严格遵循docs/wechat-compatibility.md中定义的“微信兼容性白名单”进行标签替换、样式内联和属性过滤。apps/web基于Next.js构建的交互式前端。它提供了实时预览、主题切换、一键复制等用户友好功能。更重要的是它作为CDP脚本操作的“界面”其DOM结构是稳定的为自动化操作提供了可靠的锚点。skill/post-to-wechat这是AI与项目交互的桥梁。除了定义Skill的元信息SKILL.md其scripts/cdp_export.ts脚本是实现魔法的地方。它通过CDP远程控制一个已启动的Chrome/Edge浏览器实例模拟用户操作。docs/wechat-compatibility.md这份文档的价值不亚于代码本身。它详细记录了微信公众号后台富文本编辑器的“怪癖”比如哪些CSS属性被支持、哪些HTML标签会被过滤、图片的最大宽度限制等。所有转换逻辑都以这份文档为最终验收标准。3. 核心使用方式与实操详解3.1 初级用法手动转换与复制对于偶尔发布文章的用户最直接的方式是访问线上站点https://wechat.reshub.vip。操作流程如下在左侧编辑区粘贴或编写你的Markdown内容。你可以使用标准的Markdown语法包括代码块language、表格、列表等。右侧预览区会实时显示转换后的效果这个效果已经非常接近在微信后台发布后的最终样式。点击上方的“复制富文本”按钮。这一步是关键它并非复制HTML代码而是利用了浏览器的document.execCommand(‘copy’)或 Clipboard API将带有样式的富文本内容复制到系统剪贴板。打开微信公众号后台素材管理页面新建图文消息在正文区域直接粘贴CtrlV。格式和图片如果使用图床链接通常会完好无损地呈现。主题功能网站提供了多种预设主题如default,minimal你可以通过URL参数快速切换例如https://wechat.reshub.vip/?thememinimal。主题实验室功能允许你自定义CSS并保存在浏览器本地这对于有固定品牌样式的团队非常有用。注意事项即使预览完美粘贴到微信后台后仍建议快速滚动检查一遍特别是代码块和表格。微信编辑器有时会进行“二次处理”。如果发现样式偏差可以回到md2wechat调整主题或内容。3.2 高级用法CDP自动化脚本驱动这才是项目的精髓所在它实现了真正的“一键发布”。cdp_export.ts脚本是一个Node.js程序它使用puppeteer-core库通过CDP协议控制浏览器。准备工作启动一个支持CDP的浏览器实例自动化操作的前提是有一个正在运行、并开启了远程调试端口的浏览器。# 对于Chrome或Chromium如Edge /path/to/chrome --remote-debugging-port9222 --user-data-dir/tmp/chrome-test--user-data-dir参数很重要它指定了一个新的用户数据目录避免干扰你日常使用的浏览器会话也便于登录微信公众号后台只需登录一次Cookie会保存在这个目录。脚本命令详解最基本的命令是只复制富文本到剪贴板供你手动粘贴node skill/post-to-wechat/scripts/cdp_export.ts \ --markdown-file ./my-article.md \ --app https://wechat.reshub.vip \ --cdp http://127.0.0.1:9222 \ --action copy-rich--markdown-file: 指定你的Markdown源文件路径。--app: md2wechat网站地址默认即线上地址。--cdp: 你启动的浏览器调试地址。--action: 操作类型copy-rich表示仅复制。全自动保存草稿 要实现从文件到微信草稿箱的全自动化需要添加--wechat参数并提供元数据。node skill/post-to-wechat/scripts/cdp_export.ts \ --markdown-file ./my-article.md \ --app https://wechat.reshub.vip/?themedefault \ --cdp http://127.0.0.1:9222 \ --action copy-rich \ --wechat \ # 触发微信后台流程 --title 我的技术文章 \ --author 你的名字 \ --summary 本文介绍了如何自动化微信文章发布... \ --cover ./cover-image.jpg # 可选封面图路径执行这个命令后脚本会在已连接的浏览器中打开md2wechat网站。将Markdown文件内容填入编辑器。点击“复制富文本”按钮。打开微信公众号后台登录页如果未登录或直接进入素材管理页。新建图文粘贴内容。自动填写标题、作者、摘要。上传本地封面图片如果提供了--cover参数。勾选“原创声明”默认行为可用--no-original禁用。点击“保存为草稿”默认行为可用--no-submit禁用。实操心得参数优先级脚本参数如--title的优先级高于Markdown文件中的Frontmatter。这意味着你可以在不修改源文件的情况下通过命令行快速覆盖元数据非常适合做A/B测试或批量处理。3.3 为AI Agent集成Skill对于Codex用户集成这个Skill非常简单本质上是创建一个符号链接让Codex能发现它。# 假设你已经克隆了仓库到 /path/to/wechat-skill mkdir -p ~/.codex/skills ln -s /path/to/wechat-skill/skill/post-to-wechat ~/.codex/skills/post-to-wechat重启Codex后AI Agent就具备了“发布文章到微信”的能力。当用户提出相关需求时AI会自行阅读SKILL.md中的约定调用正确的命令序列。AI使用的最佳路径正如项目文档强调的对AI来说最稳定可靠的路径是Markdown - 线上站点 - 复制富文本 - 微信公众号后台。AI应避免主动执行npm run dev除非用户明确指示。4. 微信兼容性避坑指南与实战经验“兼容微信”是一个持续的战斗因为微信后台的渲染引擎并非标准浏览器。core包的转换逻辑就是这场战斗的成果。以下是一些从文档和实战中总结的关键点1. 样式必须内联微信会剥离style标签和大部分class。因此转换器会把所有必要的CSS样式以style”...”的形式内联到每个HTML元素上。这也是为什么项目需要“主题”系统——主题本质上是一套生成内联样式的规则。2. 严格的标签与属性白名单只有部分HTML标签能被安全使用。例如div、span、p、h1-h6、ul、ol、li、table、img、code、pre等是安全的。而像script、iframe、video某些情况等则会被过滤。属性方面style、src、href、width、height、colspan、rowspan等常用属性被保留。3. 图片处理策略远程图片如果Markdown中的图片是HTTP/HTTPS链接转换后会直接使用。但需确保图床稳定且允许微信爬虫访问。本地图片在自动化流程中通过--cover参数指定的封面图脚本会通过文件选择器上传。正文中的本地图片链接则需要先上传到微信素材库或第三方图床将链接替换为网络URL后再进行转换。目前CDP脚本不处理正文内的本地图片自动上传这是一个需要注意的环节。4. 代码高亮的特殊处理标准的代码高亮库如Prism.js会生成大量带class的span这在微信中会失效。md2wechat的解决方案通常是使用一个简化的、以内联样式实现的高亮方案或者直接放弃语法高亮仅保留等宽字体和背景色以保证代码块的结构清晰。避坑技巧在编写Markdown时尽量避免使用过于复杂或依赖JavaScript的Markdown扩展。简单的表格、任务列表通常没问题。转换后务必在微信后台的“预览”功能中发送到手机查看因为手机端的渲染可能与网页后台略有不同。5. 本地开发、调试与自定义主题虽然AI和大多数用户应使用线上服务但如果你需要修改转换规则、调试CDP脚本或开发新主题就需要搭建本地环境。环境搭建步骤克隆项目并安装依赖git clone repository-url cd wechat-skill npm install启动本地开发服务器npm run dev这会在http://localhost:3000启动Next.js开发服务器。热重载功能让你修改前端代码后能立即看到效果。调试CDP脚本 CDP脚本 (cdp_export.ts) 是用TypeScript编写的你可以直接修改它来适应你的特殊需求。例如你可能需要调整操作之间的等待时间或者为你的公众号后台不同的UI版本修改元素选择器。脚本中使用了page.waitForSelector,page.click,page.type等Puppeteer方法。调试时可以增加--delay-scale参数来放慢操作速度便于观察。如果微信后台界面更新导致元素找不到你需要更新脚本中的选择器。这时可以打开浏览器的开发者工具手动定位新界面中对应按钮的CSS选择器或XPath。创建自定义主题 主题定义了文章的视觉风格。在apps/web中主题通常是一组CSS规则。你可以通过网站的“主题实验室”进行可视化调整然后导出为JSON配置文件。更深入的方式是直接修改主题源代码通常位于apps/web/styles/themes/或类似目录下然后重新构建。 自定义主题的核心是理解最终生成的是内联样式因此你的CSS规则需要能够被序列化并应用到对应的HTML元素上。例如为主题定义一个代码块的背景色和字体转换引擎会将这些样式计算后内联到每一个pre和code标签中。6. 常见问题排查与稳定性优化实录在实际自动化运行中你可能会遇到一些问题。以下是我遇到的一些典型情况及其解决方案。问题1CDP连接失败提示Failed to connect to browser原因浏览器未以远程调试模式启动或者端口被占用。排查检查浏览器启动命令是否正确确认--remote-debugging-port9222已添加。用curl http://127.0.0.1:9222/json/version测试端口是否可访问。解决确保只启动了一个调试实例。如果端口冲突更换一个端口如9333并同步修改脚本的--cdp参数。问题2脚本执行中断提示找不到页面元素如“复制富文本”按钮原因页面加载速度慢脚本在元素出现前就尝试操作或者网站UI更新导致选择器失效。排查脚本默认有等待逻辑。可以尝试增加--delay-scale 2参数将所有的等待时间翻倍。在脚本命令后添加--debug参数如果支持或直接修改脚本加入page.screenshot({path: ‘debug.png’})来查看中断时的页面状态。解决对于网络慢的情况增加延迟系数。如果是选择器失效需要更新脚本中的选择器字符串。线上站点wechat.reshub.vip的UI相对稳定此问题较少见。问题3内容成功粘贴到微信后台但格式仍有部分错乱原因可能是Markdown源文件中包含了微信不支持的复杂结构或者是某个主题的样式在微信中解析异常。排查首先在md2wechat的预览中确认样式正确。然后将转换后的HTML片段通过“导出HTML”功能复制出来在一个简单的HTML文件中用微信的X5内核可用QQ浏览器调试查看或直接粘贴到微信后台的“源代码”模式需开启开发者工具对比。解决简化Markdown源文件。尝试切换到更简单的主题如minimal。检查docs/wechat-compatibility.md确保没有使用黑名单中的样式属性。问题4封面图片上传失败原因微信后台的上传组件可能动态加载文件选择器的触发方式需要精确模拟。排查脚本中使用的是page.waitForSelector(‘input[type“file”]’)和input.uploadFile()方法。上传失败可能是选择器没等到或者文件路径无效。解决确保--cover参数提供的图片路径是绝对路径或相对于执行命令的正确相对路径。可以尝试在脚本中增加上传前更长的等待时间。稳定性优化建议使用独立的浏览器配置文件始终为自动化任务使用--user-data-dir隔离登录状态和缓存避免与手动操作冲突。添加操作抖动Jitter脚本的--jitter-ms参数可以在操作间插入随机延迟模拟人类操作的不确定性避免被反自动化机制检测。实施重试机制对于关键步骤如点击“保存草稿”可以在你自己的调用脚本外层包裹一个重试逻辑例如失败后等待几秒再重试整个流程。日志与监控将CDP脚本的输出重定向到日志文件便于事后排查。对于生产环境可以监控“保存草稿”是否成功例如检查最终页面是否跳转或出现成功提示。这个项目将一件繁琐、易错的事情变得优雅而自动化。它不仅仅是一个工具更是一种工作流理念的体现将重复性劳动标准化、脚本化并友好地暴露给AI。无论是个人博主节省排版时间还是团队将技术博客同步到公众号的自动化流程white0dew/wechat-skill都提供了一个非常坚实的起点。我在使用中最大的体会是信任它的默认约定先从最简单的线上使用开始当你真正需要定制化时再去深入它的代码和CDP脚本你会发现它设计得足够模块化让你可以轻松地“拧下螺丝”换上自己需要的部件。