素材正文
自动化发文这件事，看起来简单，实际上是一场和系统协议死磕的持久战。本文记录了在 Halo 2.22+ 环境下，从 API 方案反复碰壁到最终用 RPA 彻底打通的完整过程，供有同样需求的人参考。
第一阶段：API 方案的连续碰壁
最直觉的思路是调用 Halo 的 REST API 直接写入文章。官方文档描述的流程看起来清晰：创建 Post、创建 Snapshot、关联快照、触发发布。然而实际执行时问题接连出现。
遭遇的核心问题：
第一，字段校验严苛。Post 创建接口对 spec 字段要求精确，缺字段或多字段都会返回 400，错误信息又不够明确，只能逐字段排查。
第二，快照内容不显示。即便文章发布成功，前台打开却是空白。排查后发现根本原因：contentPatch 字段需要的是 HTML，而不是 Markdown 原文。rawPatch 存 Markdown，contentPatch 必须存转换后的 HTML，两者缺一不可。
第三，编辑器注解遗漏。不加 "content.halo.run/preferred-editor": "bytemd" 注解，后台编辑文章时会弹出警告，且编辑器无法正确加载。
第四，409 冲突错误。PUT 更新文章时，若不携带服务器返回的最新 resourceVersion，会触发乐观锁冲突。正确做法是先 GET 拿到最新对象，再在此基础上 PUT。
API 方案的标准四步法（修正后）：
步骤1：POST /posts 创建文章壳子，metadata 中注入 bytemd 注解
步骤2：POST /snapshots 创建快照，rawPatch 存 Markdown，contentPatch 存 HTML
步骤3：GET /posts/{name} 获取最新状态，修改 headSnapshot/releaseSnapshot/publish，PUT 回写
步骤4：POST /posts/{name}/publish 触发发布接口
即便如此，API 方案在部分环境下仍不稳定，尤其是 H2 数据库下的异步写入问题偶发性较强。
第二阶段：转向 RPA，用 Playwright 模拟真人操作
既然后端道路不畅，不如绕到前端。Playwright 是一个浏览器自动化库，可以启动本地 Chrome，携带已有的登录状态，完整复刻人工操作的每一步。
核心逻辑转变： 不再强行向数据库塞数据，而是让脚本像真人一样打开编辑器、粘贴内容、点击发布。只要人工能成功的操作，脚本就能成功。
关键技术细节：
一、登录态复用。用 Playwright 登录一次后，将 storage_state 保存为 JSON 文件（含 Cookie）。之后每次发文直接加载这个文件，无需重复登录。
context = browser.new_context(storage_state="halo_auth.json")
二、正文注入方式。ByteMD 编辑器对键盘事件有特殊处理，用 type() 逐字符输入会触发代码块自动补全，导致排版混乱。改用 insert_text() 模拟整段粘贴，编辑器会将内容视为纯文本处理，格式完全正常。
page.keyboard.insert_text(content) # 正确
# page.keyboard.type(content) # 错误，会触发代码块
三、弹窗按钮精准定位。发布设置弹窗内的"发布"按钮 class 为 btn-secondary，区别于顶部工具栏的 btn-sm，需用 class 加文本双重定位，避免误点到"关闭"按钮。
完整 RPA 发文流程：
1. 打开 /console/posts/editor
2. 等待 .bytemd 编辑器加载
3. 点击编辑区，全选清空，insert_text 注入正文
4. 点击顶部工具栏"发布"按钮（btn-sm），等待弹窗出现
5. 定位标题输入框，fill() 填入标题
6. 点击弹窗内 btn-secondary 的"发布"按钮
7. 等待"发布成功"文字出现，验证完成
第三阶段：接入 WorkBuddy，实现手机端一键发布
RPA 脚本跑通后，进一步将其封装，通过 WorkBuddy 建立「聊天即发布」的触发链路。
触发格式：
#发文#
标题：文章标题
正文：文章内容
WorkBuddy 识别到 #发文# 关键字后，调用后台脚本，脚本自动完成内容格式化（加二级标题结构、去除 Emoji 和分割线、末尾署名）再启动 RPA 发布。手机端发出消息，博客前台随即上线，整个链路无需人工干预。
经验总结
| 方案 | 适用场景 | 主要风险 |
|---|---|---|
| API 直写 | 批量导入、定时任务 | 字段校验严格，contentPatch 需 HTML |
| RPA 模拟 | 日常发文、内容复杂 | 依赖界面结构，大版本升级需维护 |
两套方案并不互斥。API 方案胜在轻量、无界面依赖；RPA 方案胜在稳定、兼容性强。对于以内容质量为核心的个人博客，RPA 是更务实的选择。
凡是能手动完成的动作，皆可自动化。
归档记录
鸣沙石的数字采集