BIGboss248/nextjs-wordpress

SEO 运维与自动化 (seo-ops)

一个用于引导 seo MCP 服务器、集成预推送和 CI/CD 质量门，以及执行基于证据的技术和排名审计的自动化运行手册。

---

阶段 0：强制性飞行前检查与自动安装

[!IMPORTANT] 零手动设置假设：在进行任何代码分析或审计之前，验证 seo CLI 和 MCP 服务器已在当前会话中配置并可用。

flowchart TD
    Start["调用 /seo-ops"] --> Check{"SEO MCP / CLI 是否已配置？"}
    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 / CLI 缺失时触发）

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 CLI 和 MCP 服务器已安装并注册。请重新加载 IDE 窗口或重启 Agent 会话，以便加载新的 MCP 工具（seo_list_reports、seo_describe_report、seo_run_report），然后重新调用 /seo-ops。" 在活动工具可用之前，请勿进行手动代码编辑或推测性猜测。

---

活动意图路由（当 MCP / CLI 就绪时）

当先决条件满足后，提示用户或根据上下文检查其目标：

flowchart LR
    Route["活动会话"] --> A["1. CI/CD 与预推送设置 (setup-cicd)"]
    Route --> B["2. 技术与页面审计 (audit-technical)"]
    Route --> C["3. 搜索控制台与增长审计 (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. 启动本地构建 / 目标：
  • 运行 pnpm build && pnpm start，地址为 http://127.0.0.1:3000。
• 2. 执行技术审计：
  • 通过 MCP：调用 seo_run_report，其中 reportId: "audit-page" 或 "site-crawl"，以及 params: {"url": "http://127.0.0.1:3000"}。
  • 通过 CLI：

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

• 3. 修复 Next.js 代码：
  • 更新 generateMetadata()（标题、描述、OpenGraph、规范 URL）。
  • 修复 JSON-LD 结构化数据组件（BreadcrumbList、Article、WebSite）。
  • 修复内部损坏的 <Link> 标签和 app/sitemap.ts。
  • 参见 ranking-optimization-guide.md。
• 4. 验证修复：
  • 重新运行 seo audit-page --url <target-url> 以确认清洁的零发现状态。

---

路径 C：搜索控制台与增长机会 (audit-gsc)

在在线域名上使用搜索控制台发现排名机会：

• 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 工具或 CLI 报告的情况下，切勿静态检查 SEO 代码。
• 证据分离：将观察到的爬取证据与外部提供商的关键词估计分开。

---

参考指南与资源

• MCP 设置与工具参考
• CI/CD 与预推送管道指南
• SEO 排名与代码修复指南
• GitHub Actions CI 工作流模板
• MCP 配置 JSON 模板