AI Agent集成实战：基于CDP与Skill的微信公众号自动化发布方案

1. 项目概述：一个为AI Agent量身定制的微信公众号发布工具

如果你和我一样，经常需要把Markdown格式的技术文章、项目文档发布到微信公众号，那你一定体会过那种“水土不服”的痛。微信后台的富文本编辑器对HTML的支持非常“特立独行”，直接复制粘贴Markdown渲染后的网页内容，格式十有八九会乱掉，图片不显示、代码块错位、列表样式丢失都是家常便饭。过去，我不得不手动在微信编辑器里一点点调整，或者依赖一些第三方转换工具，但流程总是割裂的。

直到我遇到了white0dew/wechat-skill这个项目，它彻底改变了我的工作流。这不仅仅是一个Markdown转微信HTML的工具，更是一个为Codex和OpenClaw这类AI Agent框架深度优化的Skill（技能）。它的核心思路非常清晰：将“内容格式化”与“发布自动化”这两个最耗时的环节打包成一个原子化操作，让AI Agent能像调用一个函数一样，完成从Markdown草稿到微信草稿箱的全流程。对于开发者、内容创作者和自动化流程构建者来说，这意味着你可以把精力完全集中在内容创作上，而将繁琐的排版和上传工作交给程序。

这个项目包含两个核心部分：一个提供实时预览和转换的Web应用（md2wechat），以及一个能驱动浏览器自动操作微信公众号后台的CDP（Chrome 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内明确的约定包括：

1. 执行路径决策：Skill内部逻辑会判断，当用户只需要HTML时，就只做Markdown转换；当需要发布时，则自动走完整的CDP自动化流程。AI无需自己判断该走哪条路。
2. 操作默认值：默认使用“复制富文本”按钮（而非直接操作DOM），默认保存为草稿，默认标记为原创。这些都是经过验证的、最稳妥的公众号发布操作流程。
3. 资源访问策略：默认使用线上站点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。

操作流程如下：

1. 在左侧编辑区粘贴或编写你的Markdown内容。你可以使用标准的Markdown语法，包括代码块（```language）、表格、列表等。
2. 右侧预览区会实时显示转换后的效果，这个效果已经非常接近在微信后台发布后的最终样式。
3. 点击上方的“复制富文本”按钮。这一步是关键，它并非复制HTML代码，而是利用了浏览器的document.execCommand(‘copy’)或 Clipboard API，将带有样式的富文本内容复制到系统剪贴板。
4. 打开微信公众号后台素材管理页面，新建图文消息，在正文区域直接粘贴（Ctrl+V）。格式和图片（如果使用图床链接）通常会完好无损地呈现。

主题功能：网站提供了多种预设主题（如default,minimal），你可以通过URL参数快速切换，例如https://wechat.reshub.vip/?theme=minimal。主题实验室功能允许你自定义CSS并保存在浏览器本地，这对于有固定品牌样式的团队非常有用。

注意事项：即使预览完美，粘贴到微信后台后仍建议快速滚动检查一遍，特别是代码块和表格。微信编辑器有时会进行“二次处理”。如果发现样式偏差，可以回到md2wechat调整主题或内容。

3.2 高级用法：CDP自动化脚本驱动

这才是项目的精髓所在，它实现了真正的“一键发布”。cdp_export.ts脚本是一个Node.js程序，它使用puppeteer-core库通过CDP协议控制浏览器。

准备工作：启动一个支持CDP的浏览器实例自动化操作的前提是有一个正在运行、并开启了远程调试端口的浏览器。

# 对于Chrome或Chromium（如Edge） /path/to/chrome --remote-debugging-port=9222 --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/?theme=default" \ --cdp http://127.0.0.1:9222 \ --action copy-rich \ --wechat \ # 触发微信后台流程 --title "我的技术文章" \ --author "你的名字" \ --summary "本文介绍了如何自动化微信文章发布..." \ --cover "./cover-image.jpg" # 可选，封面图路径

执行这个命令后，脚本会：

1. 在已连接的浏览器中打开md2wechat网站。
2. 将Markdown文件内容填入编辑器。
3. 点击“复制富文本”按钮。
4. 打开微信公众号后台登录页（如果未登录）或直接进入素材管理页。
5. 新建图文，粘贴内容。
6. 自动填写标题、作者、摘要。
7. 上传本地封面图片（如果提供了--cover参数）。
8. 勾选“原创声明”（默认行为，可用--no-original禁用）。
9. 点击“保存为草稿”（默认行为，可用--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脚本或开发新主题，就需要搭建本地环境。

环境搭建步骤：

1. 克隆项目并安装依赖：

   git clone <repository-url> cd wechat-skill npm install

2. 启动本地开发服务器：

   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. 常见问题排查与稳定性优化实录

在实际自动化运行中，你可能会遇到一些问题。以下是我遇到的一些典型情况及其解决方案。

问题1：CDP连接失败，提示Failed to connect to browser

• 原因：浏览器未以远程调试模式启动，或者端口被占用。
• 排查：检查浏览器启动命令是否正确，确认--remote-debugging-port=9222已添加。用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参数提供的图片路径是绝对路径或相对于执行命令的正确相对路径。可以尝试在脚本中增加上传前更长的等待时间。

稳定性优化建议：

1. 使用独立的浏览器配置文件：始终为自动化任务使用--user-data-dir，隔离登录状态和缓存，避免与手动操作冲突。
2. 添加操作抖动（Jitter）：脚本的--jitter-ms参数可以在操作间插入随机延迟，模拟人类操作的不确定性，避免被反自动化机制检测。
3. 实施重试机制：对于关键步骤（如点击“保存草稿”），可以在你自己的调用脚本外层包裹一个重试逻辑，例如失败后等待几秒再重试整个流程。
4. 日志与监控：将CDP脚本的输出重定向到日志文件，便于事后排查。对于生产环境，可以监控“保存草稿”是否成功（例如检查最终页面是否跳转或出现成功提示）。

这个项目将一件繁琐、易错的事情变得优雅而自动化。它不仅仅是一个工具，更是一种工作流理念的体现：将重复性劳动标准化、脚本化，并友好地暴露给AI。无论是个人博主节省排版时间，还是团队将技术博客同步到公众号的自动化流程，white0dew/wechat-skill都提供了一个非常坚实的起点。我在使用中最大的体会是，信任它的默认约定，先从最简单的线上使用开始，当你真正需要定制化时，再去深入它的代码和CDP脚本，你会发现它设计得足够模块化，让你可以轻松地“拧下螺丝”，换上自己需要的部件。