BIGboss248/nextjs-wordpress

SEO 操作與自動化 (seo-ops)

一個自動化工作手冊，用於引導 seo MCP 伺服器、整合推送前與 CI/CD 品質關卡，以及執行基於證據的技術與排名審核。

---

階段 0：強制性飛行前檢查與自動安裝

[!IMPORTANT] 零手動設定假設：在進行任何程式碼分析或審核之前，請先確認 seo 指令列與 MCP 伺服器已在當前工作階段中設定完畢並可供使用。

flowchart TD
    Start["叫用 /seo-ops"] --> Check{"是否已設定 SEO MCP / 指令列？"}
    Check -->|否 / 遺失| AutoInstall["1. 執行自動安裝<br/>('npm i -g seo' + 寫入 mcp_config.json)"]
    AutoInstall --> TestDaemon["2. 驗證: 'npx -y seo mcp serve --test'"]
    TestDaemon --> PromptRestart["3. 提示使用者重新啟動 Agent/IDE 並停止"]
    Check -->|是 / 已啟用| RouteIntent["繼續進行使用者意圖路由"]

自行安裝手冊（當 MCP / 指令列遺失時觸發）

1. 安裝套件：

   npm install -g seo
   

2. 設定 MCP 伺服器： 確認 .agents/mcp_config.json（以及 ~/.gemini/config/mcp_config.json）包含以下內容：

   {
     "mcpServers": {
       "seo": {
         "command": "npx",
         "args": ["-y", "seo", "mcp", "serve"]
       }
     }
   }
   

3. 驗證守護行程：

   npx -y seo mcp serve --test
   

4. 提示重新啟動並停止此回合： 如果在本次工作階段中新增了 MCP 工具，Antigravity 需要重新載入工作階段/視窗才能註冊這些工具。請明確說明：

   "seo 指令列與 MCP 伺服器已安裝並註冊。請重新載入 IDE 視窗或重新啟動 Agent 工作階段，以便載入新的 MCP 工具（seo_list_reports、seo_describe_report、seo_run_report），然後重新叫用 /seo-ops。" 在沒有啟用工具的情況下，請勿繼續進行手動程式碼編輯或胡亂猜測。

---

活躍意圖路由（當 MCP / 指令列準備就緒時）

當滿足先決條件時，提示使用者或檢查上下文以了解其目標：

flowchart LR
    Route["活躍工作階段"] --> A["1. CI/CD 與推送前設定 (setup-cicd)"]
    Route --> B["2. 技術與頁面審核 (audit-technical)"]
    Route --> C["3. Search Console 與成長審核 (audit-gsc)"]
    Route --> D["4. 環境健康檢查 (check-health)"]

---

路徑 A：儲存庫 CI/CD 與推送前品質關卡 (setup-cicd)

在開發與部署流程中強制執行零回歸的 SEO 關卡：

• 1. 驗證 Node 22+：執行 node -v 以確保為 Node 22+ 執行環境。
• 2. 設定本機推送前掛鉤：
  • 部署推送前執行腳本（scripts/seo-pre-push.ps1 或 scripts/seo-pre-push.sh），並帶有開發伺服器自動探測功能（重複使用現有實例或啟動 cmd.exe /c pnpm run dev 並進行處理序樹清理）。
  • 在 .husky/pre-push 中，執行獨立的步驟：

    pnpm run test:all
    pnpm run seo:pre-push
    

  • 請參閱 cicd-pipeline-guide.md。
• 3. 安裝 GitHub Actions 工作流程：
  • 使用 seo-ci.yml.template 建立 .github/workflows/seo-check.yml。
• 4. 驗證管線：
  • Windows：powershell -ExecutionPolicy Bypass -File .agents/skills/seo-ops/scripts/verify-seo-setup.ps1 -Mode cicd
  • Linux/macOS：bash .agents/skills/seo-ops/scripts/verify-seo-setup.sh -m cicd

---

路徑 B：技術與頁面審核 (audit-technical)

對本機建置或線上 URL 執行基於證據的爬取：

• 1. 啟動本機建置 / 目標：
  • 在 http://127.0.0.1:3000 上執行 pnpm build && pnpm start。
• 2. 執行技術審核：
  • 透過 MCP：使用 reportId: "audit-page" 或 "site-crawl" 以及 params: {"url": "http://127.0.0.1:3000"} 呼叫 seo_run_report。
  • 透過指令列：

    npx -y seo report --url http://127.0.0.1:3000 --actions-only --json
    

• 3. 修復 Next.js 程式碼：
  • 更新 generateMetadata()（標題、描述、OpenGraph、標準網址）。
  • 修正 JSON-LD 結構化資料元件（BreadcrumbList、Article、WebSite）。
  • 修正內部損壞的 <Link> 標籤與 app/sitemap.ts。
  • 請參閱 ranking-optimization-guide.md。
• 4. 驗證修復：
  • 重新執行 seo audit-page --url <target-url> 以確認零錯誤的乾淨狀態。

---

路徑 C：Search Console 與成長機會 (audit-gsc)

在線上網域中透過 Search Console 發掘排名機會：

• 1. 透過 MCP 發現報告：
  • 呼叫 seo_list_reports（類別："gsc" 或 "pseo"）。
  • 針對 reportId: "quick-wins"、"second-page" 或 "pseo-patterns" 呼叫 seo_describe_report。
• 2. 執行機會審核：
  • 使用目標資源（site: "sc-domain:example.com"）呼叫 seo_run_report。
• 3. 套用增強功能：
  • 快速勝利（第 4–10 名）：優化 <title> 與 <meta description> 以提高點擊率。
  • 第二頁（第 10–20 名）：從高權重的父頁面加入情境式內部連結，並深化內容。
  • pSEO 模式：使用 generateStaticParams() 構建動態路由。
• 4. 重新驗證：確認更新的中繼資料與結構化資料已在生產環境的 SSR 建置中正確渲染。

---

邊緣案例與已知陷阱

• 處理序重新啟動需求：當 .agents/mcp_config.json 被修改時，Agent 必須等到工作階段/視窗重新載入後才能存取新工具。切勿跳過重新啟動提示。
• Windows 路徑解析：一律使用 "command": "npx" 搭配 ["-y", "seo", "mcp", "serve"]，以避免 Windows 上因 %PATH% 二進位檔查詢而發生的錯誤。
• 禁止靜態猜測：在未先執行 MCP 工具或指令列報告之前，切勿靜態檢查 SEO 相關程式碼。
• 證據分離：將觀察到的爬取證據與外部提供者的關鍵字估計值分開處理。

---

參考指南與資源

• MCP 設定與工具參考
• CI/CD 與推送前管線指南
• SEO 排名與程式碼修復指南
• GitHub Actions CI 工作流程範本
• MCP 設定 JSON 範本