如何把 CMS 文章自动推送到自媒体矩阵（进阶版 32）
如果你团队的写作流是这样的：
> 编辑在 CMS（WordPress / Strapi / Sanity / Notion / 自研后台）里写完一篇文章，点"发布"——内部站点立即上线，但要发到头条号、微信公众号、百家号、知乎，还需要运营同学一个一个登录后台手工搬运。
这一道断点是大多数内容团队效率最低的地方。这篇文章给 AI Agent 团队和内容工程师 6 步把这道断点补上：CMS 一发布，自媒体矩阵自动跟上。底层用颜小二自媒体发布 API 平台。
这篇适合谁
- AI Agent 团队：内容生产链路里 CMS 是中间件，发布是出口
- 企业内容运营技术中台：要把 CMS 与自媒体打通
- 使用 WordPress / Strapi / Sanity / Ghost 等 CMS 的团队
- 想替运营把"复制粘贴"工作消灭掉的工程师
前置：CMS 字段与发布字段的映射要先理清楚
每个 CMS 字段命名都不同，但都能映射到颜小二的统一字段。先做一张映射表：
| CMS 字段 | 颜小二字段 | 备注 | |---|---|---| | post_id / slug | external_id | 业务侧主键 | | title | title | 直接传 | | content / body | content_html | 注意 Markdown 要先渲染成 HTML | | featured_image | cover_url | 用 CDN 绝对地址 | | excerpt / summary | summary | 没有就截前 100 字 | | categories | category | 取首选 | | tags | tags | 取数组 |
字段对齐之后，剩下的事情就只是"什么时候触发推送"。
6 步打通 CMS → 自媒体矩阵
第 1 步：在 CMS 里加一个"发布到自媒体"开关
不是每篇 CMS 文章都需要发到自媒体（站内公告、内部备忘录就不需要）。给文章模型加一个布尔字段 publish_to_external，编辑勾选后才触发推送。
第 2 步：在 CMS 里挂 Webhook
文章被保存且 status=published 且 publish_to_external=true 时，触发 Webhook 推到你侧的 worker 服务：
- WordPress：用
transition_post_status钩子 - Strapi：用 lifecycle
afterUpdate - Sanity：用 GROQ-powered webhook
- 自研后台：在保存逻辑里加一行 HTTP 请求
第 3 步：worker 做字段映射 + external_id 生成
worker 收到 Webhook 后做三件事：
1. 按上面字段映射表，把 CMS payload 翻译成颜小二请求体 2. 生成 external_id（推荐 cms_{post_id}_v{revision}） 3. 决定 target_platforms（从 CMS 文章的元数据读取，或全量）
第 4 步：调颜小二统一发布 API
``json { "external_id": "cms_98231_v1", "group_code": "brand_official", "title": "你的文章标题", "content_html": "<p>渲染好的正文 HTML</p>", "cover_url": "https://cdn.yourdomain.com/cover/98231.jpg", "summary": "100 字以内摘要", "tags": ["AI", "效率工具"], "category": "科技", "target_platforms": ["toutiao", "wechat_mp", "baijiahao", "zhihu"], "callback_url": "https://your-cms.com/yanxiaoer/callback" } ``
颜小二按 group_code 路由到目标账号集合，下发任务给本地 Agent 执行。登录态保存在你侧本地，cookie 不上云——这点对内容资产合规审计很关键。
第 5 步：callback handler 把发布结果写回 CMS
每个平台发布完，颜小二会把结果（platform_url、platform_id、status）回调给你的 callback_url。你的 handler 把这些信息写回 CMS 的"外部发布记录"表，编辑在 CMS 后台就能直接看到"这篇文章发到哪些平台、链接是什么、有没有失败"。
第 6 步：失败补偿 + 编辑通知
如果某个平台失败了：
- 临时性失败：自动重试（颜小二底层会先重试，超出阈值上报给你）
- 登录态失效：触发本地 Agent 重登流程，重登好后用同 external_id 重发
- 业务性失败（标题超长、违规）：发邮件 / 飞书通知给编辑改稿
颜小二在这条链路里负责什么
颜小二是一个多租户内容分发执行中台。在 CMS → 自媒体的链路里它做了这些：
- 统一文章接收 API：你的 CMS / worker 只面对一个端点
- group_code 账号分组路由：按品牌 / 行业切流量
- external_id 幂等去重：CMS 重复触发 Webhook 不会发两次
- 登录态本地保存：cookie 不离开你的环境
- 结构化 callback：成功 / 失败 / 登录态过期，三种状态明确
这套组合让你的 CMS 工程师只需要写"翻译 + 转发"的薄薄一层。
错误排查清单
| 现象 | 常见原因 | 处理方式 | |---|---|---| | Webhook 触发但 worker 没收到 | 公网不可达 / 鉴权失败 | curl 自测、查日志 | | 同一篇被发了两次 | external_id 用了随机值 | 改用 cms_{post_id}_v{rev} | | 部分平台成功部分失败 | 各平台审核策略不同 | 看回调 error_msg | | 图片在某平台显示不出来 | cover_url 不是公网 CDN | 改用绝对 HTTPS 地址 | | Markdown 在平台格式乱 | 没渲染成 HTML 直接传了 | worker 里加 markdown→html |
常见问题（FAQ）
Q：CMS 没有 Webhook 怎么办？ 轮询。worker 每 5 分钟拉一次"最近更新且 publish_to_external=true 但没推过的文章"，这种轮询模式也成立，只是延迟高一些。
Q：编辑改稿后会重发吗？ 取决于你的 external_id 策略。改错别字保留原 ID（不会重发）；大改升 v2 走重发。颜小二按 ID 幂等。
Q：能不能延迟发布（比如定时第二天 9 点）？ 颜小二支持 scheduled_at 字段。CMS 编辑选了定时，worker 把时间戳传过来即可。
Q：图片要先上传到颜小二吗？ 不需要。颜小二只接受 cover_url（公网可达的 HTTPS 地址）。图片应该在你的 CDN 里，颜小二只读取。
Q：能不能只发部分平台？ 能。target_platforms 字段按需指定，比如某些"内部"性质的文章只发知乎不发头条。详细看 [API 文档](/docs.html)。
下一步
CMS 与自媒体打通是大多数内容团队接入颜小二的第一个场景。先选一个低风险的 CMS（比如内部博客）跑通全链路，再扩到主站 CMS。
→ [免费申请接入](/contact.html#form) | [查看 API 文档](/docs.html) | [自媒体发布 API 落地页](/lp/zimedia-publish-api.html)