headless-cms-mcp-pipeline

Headless CMS MCP 内容管道

使用时机

• 通过模型上下文协议 (MCP) 管理、创作或发布Headless WordPress上的博客文章和页面。
• 针对Next.js无头前端，编排自主AI文章生成管道。
• 将外部AI代理连接到Sayoti Suite MCP RPC (/wp-json/sayoti-mcp/v1/rpc)。
• 在CMS和AI代理之间同步编辑标准、边界矩阵 (The Borderline Matrix)、临床E-E-A-T规则以及品牌视觉指南。
• 配置动态无头导航菜单、页面焦点关键词审计以及专门的页面角色（如引导磁石、隐私政策、服务条款）。

---

先决条件与零机密策略

⚠️ 严格的凭据保护（零泄密）

• 切忌在SKILL.md或git跟踪文件中硬编码API密钥、密码或Bearer Token。
• 所有凭据必须严格从$HERMES_HOME/.env或特定配置文件中的.env文件中解析环境变量。
• 此管道所需的凭据：
  1. MCP_SAYOTI_CMS_KEY：用于WordPress MCP RPC认证的主密钥（headers: {'X-Sayoti-Key': '${MCP_SAYOTI_CMS_KEY}'}）。
  2. HERMES_CUSTOM_9ROUTER_SAYOTI_MY_ID_API_KEY 或 NINEROUTER_API_KEY：用于9Router多模型网关的API密钥（用于image_generate和嵌入）。
• WordPress MCP服务器配置（在config.yaml的mcp_servers部分）：

  mcp_servers:
    sayoti-cms:
      url: "http://wordpress-sentra/wp-json/sayoti-mcp/v1/rpc"
      headers:
        X-Sayoti-Key: "${MCP_SAYOTI_CMS_KEY}"
      enabled: true
      timeout: 180
  

• 向量数据库先决条件：
  • 在WordPress管理后台 (sayoti_mcp_settings) 中，embedding_status 必须设置为 enabled，并使用模型 local/nomic-embed-text，以支持 rag_search 和自动文章索引。

---

架构原则

1. WordPress作为纯数据存储（零超时）：

   • WordPress在REST/MCP请求期间，绝不能执行长时间运行的同步AI调用（例如LLM生成、扩散模型）。
   • AI代理（Hermes）充当执行引擎：它进行研究、撰写草稿、通过9Router生成视觉内容、嵌入媒体，然后将数据发送到CMS。
   • CMS操作 (save_post, save_page) 必须作为纯快速数据库事务执行（< 1秒），并触发Next.js按需ISR重新验证。

2. 通过Upsert实现严格的实体分离：

   • 始终使用专用的upsert工具处理不同的内容实体：save_post用于博客文章，save_page用于静态/着陆页。
   • 不要将文章和页面合并到一个带有条件参数的通用工具中；不同的模式可以消除参数泄漏和LLM幻觉。
   • Upsert逻辑：如果存在匹配的id或slug，则执行更新；否则，创建新内容。

3. 专门的页面角色与引导磁石分类：

   • 页面在漏斗中承担特定的商业或法律角色：standard、lead_magnet、privacy_policy、terms_of_service 或 disclaimer。
   • 永远不要将引导磁石页面定义为模糊不清。始终将其分类为 page_role: 'lead_magnet'，并通过 lead_magnet_type 明确指定资产类型（例如 "Checklist Milestone Perkembangan 2–7 Tahun (PDF)"）。
   • CMS通过 /wp-json/sayoti/v1/site-settings 暴露这些信息，并在WordPress管理后台注册文章状态徽章（[🎁 引导磁石：...]、[🔒 隐私政策]、[📜 服务条款]），以便人工编辑立即识别页面功能。

4. 动态无头导航菜单：

   • 菜单绝不应在前端硬编码。WordPress是通过 /wp-json/sayoti/v1/menus?location=primary 和 footer 提供单一事实来源。
   • 在WP管理后台（外观 -> 菜单）更新菜单会触发一个ISR重新验证的webhook，标签为 menu，路径为 /，从而立即更新Next.js的页眉和页脚，无需重新部署。
   • 首次运行时，始终自动播种默认导航菜单，以便WP管理面板立即拥有一个干净、可随时编辑的菜单。

5. 编辑与视觉规则的单一事实来源：

   • 编辑规则 (content.md)、E-E-A-T标准 (sayoti-editorial.md)、品牌视觉规则 (sayoti-visual-branding.md) 以及页面内SEO关键词规则存储在WordPress数据库选项中。
   • 代理通过 get_editorial_guidelines 动态获取这些规则，确保输出与面板中的生成完全对齐。

6. 解耦的双插件架构（通用内容 vs 无头桥接）：

   • 切勿将AI、主题集群、MCP服务器与无头重定向逻辑耦合。如果客户已经拥有一个活跃的WordPress主题（Astra、Elementor、Divi），并且只需要AI/SEO引擎，那么一个单体插件就会失效。
   • 拆分为两个干净、独立的插件：
     • sayoti-content-engine：通用且与主题无关。包含MariaDB 11.8向量RAG、主题集群（Hub & Spoke）、链接浏览器、死链自动修复、面板内AI写作工具、引导磁石自定义文章类型和CRM，以及MCP服务器 (/wp-json/sayoti-mcp/v1/rpc)。无重定向，无Next.js依赖。可在任何现有的WordPress安装上运行。
     • sayoti-headless-bridge：仅在使用无头Next.js前端时安装。包含301模板重定向（带有可配置的切换开关）、REST端点 /site-settings 和 /menus、ISR重新验证webhook、页面控制器（首页和法律角色）以及动态营销跟踪标签（GTM、Meta Pixel、TikTok、Ads）和本地SEO schema（谷歌地图和商家地址）。

---

全面的10步文章生成工作流程

[用户主题提示]
        ↓ 1. 摄入任务
[WordPress MCP: get_topic_cluster & get_editorial_guidelines]
        ↓ 2. 拉取支柱分类法与编辑指南
[Agent (Hermes): 焦点关键词与角度]
        ↓ 3. 制定焦点关键词与具体角度
[WordPress MCP: rag_search]
        ↓ 4. 检查语义内容重复 (>80%) 并获取内部链接候选
[Web Research: 通用4级引用层级]
        ↓ 5. 验证事实与支撑主张
[Agency Agents: content-creator]
        ↓ 6. 加载专业写作人格
[Content Authoring: Gutenberg Native]
        ↓ 7. 撰写900-1500词语义HTML（钩子、H2、Hub链接、FAQ、CTA、免责声明）
[9Router image_generate + MCP upload_media]
        ↓ 8. 以自适应水印旁加载视觉素材（零超时）
[WordPress MCP: save_post]
        ↓ 9. 即时数据库事务 + 自动向量索引 + Next.js ISR
[WordPress MCP: audit_post_seo]
        ↓ 10. 审计SEO得分（目标80-100%）并交付实时报告
[Live on Vercel Next.js]

第1步：摄入主题与上下文

接收来自用户或编辑日历的初始内容请求。识别目标受众的痛点和商业意图。

第2步：检索指南与分类法

调用 sayoti-cms 工具以建立结构边界：

1. get_topic_cluster：检查可用的分类支柱，并为目标类别检索官方的主要Hub（文章ID、标题、Slug）。
2. get_editorial_guidelines：获取有效的编辑长度限制（900–1,500词）、强制性开头结构、FAQ手风琴规则、行动框架以及官方十六进制颜色调色板。

第3步：深度焦点关键词研究与角度制定

• 搜索意图与关键词研究： 不要仅仅随意选择一个短语。要积极研究目标受众（如个人资料中定义的那样）所使用的真实搜索行为和查询（通过网络搜索/关键词模式来了解信息性问题、问题或调查性比较）。
• 选择主要焦点关键词： 基于研究结果，精确建立1个主要焦点关键词，并具有明确的长尾搜索意图（例如 "cara melatih anak speech delay 2 tahun mandiri" 而非宽泛的通用头部术语）。
• 定义清晰独特的视角： 将所选关键词锚定在一个独特的视角上（例如特定的年龄过渡、现实的家庭日常实践或在≤24小时内可实现的切实步骤）。
• 单URL映射： 确保此焦点关键词严格专用于唯一的URL，以防止未来的关键词竞争。

第4步：语义RAG验证与内容重复检查

执行 rag_search(query: "<focus_keyword> <angle>", limit: 5)：

1. 内容重复过滤： 如果任何已发布的文章在相同角度上语义相似度超过80%，则立即调整视角（例如从一般症状转向家庭日常实践或特定的里程碑过渡）。
2. 横向链接发现： 记录向量搜索返回的相关现有文章，以作为上下文相关的内部链接。

第5步：多层级引用研究（通用4级引用层级）

使用通用证据层级来支撑所有事实主张：

• 第1级（主要法定与科学权威 - 黄金标准）： 官方临床协会（IDAI、Himpsi、PPHI、WHO、CDC、AAP）、政府健康指南和同行评审期刊。对于里程碑年龄数字、临床定义和医学声明是强制性的。
• 第2级（可靠二级与行业研究）： 可信的新闻机构（Kompas、Antara、BBC）和关于宏观趋势的机构白皮书。
• 第3级（观察与现场情绪）： 真实的受众/用户挣扎、从业者现场笔记和社区讨论。用于撰写富有同理心的开头钩子。始终标记为情绪或实际现场观察，而不是规范性法定或临床事实。
• 第4级（禁止）： 内容农场、未经授权的SEO博客和没有主要链接的AI改写内容。切勿引用。

第6步：加载专业人格

调用 agency_agents_load(agent="content-creator")（或相应的Agency专家），并应用活动配置文件的SOUL.md所指定的沟通语气。

第7步：起草完整的语义HTML（Gutenberg Native）

使用原生WordPress Gutenberg块注释（<!-- wp:paragraph -->、<!-- wp:heading -->、<!-- wp:separator -->、<!-- wp:list -->）撰写900–1,500词的语义HTML：

1. 单个H1： 由页面模板处理；直接从开头的段落开始正文。
2. 三段式开头结构：
   • 第1段（钩子）：验证受众挣扎的真实场景（来自第3级的见解）。
   • 第2段（快速解答）：自然、平静的直接回答（无需刻板的“快速解答：”标签）。
   • 第3段（过渡）：热情邀请读者一起探索解决方案。
3. 每个H2的详细阐述： 每个标题下3到5个全面的段落，整合实用的家庭刺激步骤（≤24小时）。
4. 内部链接整合：
   • 垂直（强制）： 在正文前300–500词内自然地将上下文链接回主要Hub：<a href="/posts/<hub-slug>" class="text-primary font-semibold underline hover:text-accent">...</a>。
   • 横向： 上下文链接到第4步发现的相关的辐条文章。
5. 标注卡片对比规则： 特别说明必须使用 <div class="my-8 rounded-2xl border-2 border-primary/25 bg-card p-6 sm:p-8 shadow-sm">，标题使用 text-primary font-bold 或 text-foreground font-bold。在浅色卡片上切勿使用 text-secondary。
6. 收尾顺序：
   • <h2>Kesimpulan &amp; Langkah Pendampingan Terbaik</h2>：总结并提供3个行动链接（/metode-belajar、/checklist-milestone、/kontak 或直接WhatsApp）。
   • <h2>Pertanyaan yang Sering Diajukan Orang Tua (FAQ)</h2>：最少5个问题，格式为 <details class="faq-accordion mb-4 rounded-xl border border-border p-4 bg-card transition-all"><summary class="cursor-pointer font-semibold text-foreground flex items-center justify-between"><span>...</span><span class="text-primary font-bold ml-2">+</span></summary><div class="mt-3 text-sm text-foreground/80 leading-relaxed border-t border-border pt-3">...</div></details>。放置在免责声明之前。
   • 强制临床免责声明： <div class="my-6 rounded-xl border border-border bg-muted/30 p-4 text-xs italic text-muted-foreground leading-relaxed">Catatan: Informasi dalam panduan ini bersifat edukatif untuk mendukung stimulasi mandiri di rumah dan tidak menggantikan asesmen langsung serta anjuran medis dari dokter spesialis anak atau terapis profesional.</div>
   • <h2>Referensi</h2>：<ol> 列表，包含经过验证的来源，带有可点击的完整 https:// URL，与文内引用匹配。
7. 7项页面内SEO标准： 焦点关键词存在于标题、永久链接Slug、前100词、至少一个H2/H3、摘要中，并且密度保持在0.5%–2.0%之间。

第8步：视觉生成与媒体旁加载（零超时）

1. 通过 image_generate (9Router) 生成图像，强制使用官方品牌十六进制颜色，并严格遵循 anti_text_rule（画布上无文本/数字/水印）。
2. 通过MCP工具 upload_media 上传图像：
   • 传递 image_url 或 image_base64。
   • 对于特色图像，传递 apply_watermark: true（通过PHP GD自适应地自动添加品牌标志水印）；对于H2正文插图，传递 apply_watermark: false。
   • 该工具会返回官方的 id（附件ID）和 CMS 域上的 url（https://cms...），完全符合Next.js Vercel remotePatterns 的要求。
3. 将文内图像直接嵌入到 <figure class="wp-block-image size-large"><img src="..." alt="..." /><figcaption>...</figcaption></figure> 块中。

第9步：即时发布 (save_post)

调用 save_post：

• title、slug、content、category_id、focus_keyword、excerpt。
• featured_media_id：设置为第8步中 upload_media 返回的附件 id。
• generate_featured_image: false 和 generate_in_article_images: false（绕过服务器端同步图像生成；作为即时数据库写入执行，<1秒，完全消除超时风险）。
• WordPress自动：
  1. 保存文章并更新SEO元字段。
  2. 触发Next.js按需ISR重新验证。
  3. 将文章块索引到MariaDB向量嵌入表中 (wp_sayoti_vectors)。

第10步：SEO审计与最终报告

1. 调用 audit_post_seo(post_id: <id>)…

[翻译截断]