headless-cms-mcp-pipeline

Headless CMS MCP 內容管道

使用時機

• 透過模型上下文協定 (MCP) 管理、編寫或發佈 Headless WordPress 上的部落格文章和頁面。
• 針對 Next.js headless 前端，編排自主 AI 文章生成流程。
• 將外部 AI 代理連接到 Sayoti Suite MCP RPC (/wp-json/sayoti-mcp/v1/rpc)。
• 同步編輯標準、The Borderline Matrix、臨床 E-E-A-T 規則、以及品牌視覺指南，以確保 CMS 與 AI 代理之間的一致性。
• 配置動態的 Headless 導覽選單、頁面焦點關鍵字稽核、以及特殊頁面角色（例如：Lead Magnet、隱私權政策、服務條款）。

---

先決條件與零秘密政策

⚠️ 嚴格的憑證保護（零秘密洩漏）

• 絕不在 SKILL.md 或 git 追蹤的檔案中硬編碼 API 金鑰、密碼或 Bearer Token。
• 所有憑證必須嚴格從 $HERMES_HOME/.env 或特定 profile 的 .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 多模型閘道（image_generate 和嵌入）的 API 金鑰。
• 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 On-Demand ISR 重新驗證。

2. 透過 Upsert 進行嚴格的實體分離：

   • 始終對不同的內容實體使用專用的 upsert 工具：使用 save_post 處理部落格文章，使用 save_page 處理靜態/登陸頁面。
   • 不要將文章和頁面合併到一個帶有條件參數的通用工具中；獨立的架構可以消除參數洩漏和 LLM 幻覺。
   • Upsert 邏輯：如果存在匹配的 id 或 slug，則執行更新；否則，建立新內容。

3. 特殊頁面角色與 Lead Magnet 分類：

   • 頁面在銷售漏斗中扮演特定的商業或法律角色：standard、lead_magnet、privacy_policy、terms_of_service 或 disclaimer。
   • 切勿讓 Lead Magnet 頁面含糊不清。始終將其分類為 page_role: 'lead_magnet'，並透過 lead_magnet_type 說明確切的資產類型（例如："Checklist Milestone Perkembangan 2–7 Tahun (PDF)"）。
   • CMS 透過 /wp-json/sayoti/v1/site-settings 公開這些內容，並在 WordPress 管理後台註冊文章狀態徽章（[🎁 LEAD MAGNET: ...]、[🔒 PRIVACY POLICY]、[📜 TERMS OF SERVICE]），使人類編輯能立即識別頁面功能。

4. 動態 Headless 導覽選單：

   • 選單絕不能在前端硬編碼。WordPress 是透過 /wp-json/sayoti/v1/menus?location=primary 和 footer 的單一事實來源。
   • 在 WP 管理後台（外觀 -> 選單）更新選單會觸發一個帶有 menu 標籤和路徑 / 的 ISR 重新驗證 Webhook，從而立即更新 Next.js 的頁首和頁尾，無需重新部署。
   • 始終在首次執行時自動預設導覽選單，使 WP 管理儀表板立即可用一個乾淨、可立即編輯的選單。

5. 編輯與視覺規則的單一事實來源：

   • 編輯規則 (content.md)、E-E-A-T 標準 (sayoti-editorial.md)、品牌視覺規則 (sayoti-visual-branding.md) 以及 On-Page SEO 關鍵字規則存放在 WordPress 資料庫選項中。
   • 代理透過 get_editorial_guidelines 動態獲取這些規則，使輸出能與儀表板內的生成結果 100% 保持一致。

6. 解耦的 2 外掛架構（通用內容 vs Headless 橋接器）：

   • 絕不會將 AI、主題集群和 MCP 伺服器與 Headless 重定向邏輯耦合。如果客戶端已有活躍的 WordPress 主題（如 Astra、Elementor、Divi）且只想使用 AI/SEO 引擎，則單體外掛會失效。
   • 將其分離為兩個乾淨、獨立的外掛：
     • sayoti-content-engine：通用且不受主題影響。包含 MariaDB 11.8 向量 RAG、主題集群（Hub & Spoke）、連結探索器、死連結自動修復、儀表板內 AI 寫手、Lead Magnet 自訂文章類型和 CRM、以及 MCP 伺服器(/wp-json/sayoti-mcp/v1/rpc)。沒有重定向，沒有 Next.js 依賴。適用於任何現有的 WordPress 安裝。
     • sayoti-headless-bridge：僅在使用 Headless Next.js 前端時安裝。包含 301 範本重定向（可配置開關）、REST /site-settings 和 /menus、ISR 重新驗證 Webhook、頁面控制器（首頁和法律角色）、以及動態行銷追蹤標籤（GTM、Meta Pixel、TikTok、Ads）和本地 SEO Schema（Google 地圖與商家地址）。

---

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

[使用者主題提示]
        ↓ 1. 攝入任務
[WordPress MCP: get_topic_cluster & get_editorial_guidelines]
        ↓ 2. 提取支柱分類法與編輯指南
[代理 (Hermes): 焦點關鍵字與角度]
        ↓ 3. 制定焦點關鍵字與具體角度
[WordPress MCP: rag_search]
        ↓ 4. 檢查語意重複 (>80%) 並獲取內部連結候選
[網路研究: 通用 4 層引用層次結構]
        ↓ 5. 驗證事實並佐證主張
[機構代理: content-creator]
        ↓ 6. 載入專業寫作角色
[內容創作: Gutenberg 原生]
        ↓ 7. 撰寫 900-1500 字語意 HTML (鉤子, H2s, 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%) 並提供即時報告
[部署於 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 原生）

使用原生的 WordPress Gutenberg 區塊註解（<!-- wp:paragraph -->、<!-- wp:heading -->、<!-- wp:separator -->、<!-- wp:list -->）撰寫 900–1,500 字的語意 HTML：

1. 單一 H1： 由頁面範本處理；直接從開場段落開始內文。
2. 3 段落開場結構：
   • 段落 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 中發現的相關 Spoke 文章。
5. Callout Card 對比規則： 特殊備註必須使用 <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 項 On-Page 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 自適應地自動蓋上品牌 Logo）；對於 H2 主體插圖，則傳入 apply_watermark: false。
   • 該工具會傳回 CMS 網域（https://cms...）上的官方 id（附件 ID）和 url，100% 符合 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 On-Demand ISR 重新驗證。
  3. 將文章區塊索引到 MariaDB 向量嵌入表（wp_sayoti_vectors）中。

步驟 10：SEO 稽核與最終報告

1. 呼叫 audit_post_seo(post_id: <id>) 進行稽核，並根據分數建議必要的調整。
2. 提供一份 HTML 或 Markdown 格式的即時報告，總結已發佈文章的 SEO 分數、已解決的重複問題、以及已觸發的 ISR 重新驗證。

---

變數參考

• MCP_SAYOTI_CMS_KEY：WordPress MCP RPC 認證的主密鑰。
• HERMES_CUSTOM_9ROUTER_SAYOTI_MY_ID_API_KEY：用於 9Router 多模型閘道的 API 金鑰。
• NINEROUTER_API_KEY：9Router 金鑰的備用變數名稱。