seo-orchestrator

seo-orchestrator（第 2 层）

分三个阶段协调整个审计：检测 → 分派 → 综合。脚本负责采集；模型只负责判断。阅读简洁的 stdout 摘要及其中提到的 JSON 文件——切勿将 HTML 粘贴到对话中。不会向用户的项目写入任何内容；所有产物都存放在 ${CLAUDE_PLUGIN_DATA}/runs/<host>/<run-id>/ 下。

1. 检测 — 一次调用

1. 解析目标和命令传入的标志（--pages、--max、--render、--ua、--vertical、--environment、--feed、--out；默认 --out "${CLAUDE_PLUGIN_DATA}/runs"）。
2. 在一条命令中运行整个确定性流程。audit.mjs 采集目标（对于 URL，它会调用 crawl.mjs；对于 --pages 1 或本地路径，它会调用 snapshot.mjs；如果传入的是运行目录，则完全跳过采集），写入 profile.json（平台 / 框架 / CMS 插件 / 托管 / 环境 / 功能 / 写入目标 / vertical_hints，以及一个垂直领域猜测），运行检查注册表，并调用 report.mjs 生成第一份仅包含确定性结果的报告：

node "${CLAUDE_PLUGIN_ROOT}/scripts/audit.mjs" <url|path> \
  --out "${CLAUDE_PLUGIN_DATA}/runs" --checks deterministic --format json \
  [--pages N] [--max N] [--render static|auto|js] [--ua <preset>] \
  [--vertical <ids>] [--environment production|preview|staging|local] [--feed <path>]

只读取它打印的 JSON 摘要：run_dir、mode、platform、vertical、coverage、tier、scores、findings、checks、report_json、report_md、findings_json、warnings。此处 --render 默认值为 static——如果目标看起来是客户端渲染的，请传入 --render auto。退出码 2 表示无法采集目标；退出码 3 仅表示触发了 --fail-under / --fail-on-* 门槛，这是 CI 方面的问题，并不代表审计失败。 3. 读取 <run_dir>/crawl.json（包含 slug/url/role 的页面、模板、抽样信息、警告）和 <run_dir>/profile.json。 4. 垂直领域：对首页 parsed（<run_dir>/pages/<homepage-slug>.json）以及 profile.vertical_hints 运行 seo-vertical-detect。该脚本只会猜测——除非传入了 --vertical，否则 profile.vertical.source 为 "inferred"。如果你的判断新增或更改了垂直领域，请针对同一次运行重新执行确定性流程（无需重新爬取），以便实际触发条件检查：

node "${CLAUDE_PLUGIN_ROOT}/scripts/audit.mjs" <run_dir> --checks deterministic --format json --vertical <ids>

references/routing.md 将垂直领域映射到条件模块（M18 电商、M19 本地、multilingual 上的 M20 hreflang）。 5. 现在运行目录中包含 <run_dir>/findings.deterministic.json（Agent 不得重复输出的确定性结果）和 <run_dir>/checks.json（已运行的检查、错误、needs_api、manual_review、已剔除项）。

2. 分派（并行 — 一条消息，四次 Agent 调用）

在一条消息中启动四个只读专家，以隔离其冗长的中间输出。每个提示词 = 封装块 + 该 Agent 的模块列表。Agent 不依赖 ${…} 替换：请传入绝对路径。

ENVELOPE
plugin_root: <absolute ${CLAUDE_PLUGIN_ROOT}>
run_dir: <absolute run dir>
pages: [{slug, url, role}, …]              # <run_dir>/pages/<slug>.json (+ <slug>.html, + <slug>.rendered.html when rendered)
site: robots=<run_dir>/site/robots.json  sitemaps=<run_dir>/site/sitemaps.json  discovery=<run_dir>/site/discovery.json
vertical: {primary: <v>, also: [<v>…], multilingual: <bool>}
platform: <run_dir>/profile.json           # one line: <platform>/<framework>, env=<kind>, head_owner=<…>
platform_cards: [<plugin_root>/references/platforms/<id>.md, …]   # omit when the platform is unknown
modules: [<M-ids for this agent>]
deterministic_findings: <run_dir>/findings.deterministic.json — do not re-emit these ids; add model-judged findings only
return: JSON array only — findings per schema/finding.schema.json, no prose

Agent	模块
technical-auditor	M1、M2（+M3）、M4、M7、M7b（移动端）、M7c（标题）、M8、M9、M10、M15、M17 — 以及 vertical.multilingual 为真时的 M20（hreflang）
ai-search-geo-specialist	M6、M11、M12、M14、M21（AI 发现与 Agent 端点，权重为 0）、M22（Agent 就绪度）
content-eeat-analyst	M13、M16
schema-generator	M5 — 以及 vertical 包含 ecommerce 时的 M18，vertical 包含 local-business 时的 M19

子 Agent 没有 Write/Edit 权限——审计绝不会修改文件。如果 Agent 在数组周围返回了文字，只保留数组。

3. 综合整理

1. 使用 Bash heredoc，将每个返回的数组原样保存到 <run_dir>/agents/<agent>.json（mkdir -p "<run_dir>/agents" && cat > "<run_dir>/agents/<agent>.json" <<'EOF' … EOF）——保存到插件数据目录，绝不能保存到项目中。这是唯一一次不遵循 node 模式的 Bash 调用；allowed-tools 中的 mkdir -p / cat > 条目已预先批准对 ${CLAUDE_PLUGIN_DATA}/runs/ 下路径的操作（需要在 smoke 中验证：heredoc 正文中若包含 ;、| 或 &&，仍可能触发确认提示）。
2. node "${CLAUDE_PLUGIN_ROOT}/scripts/report.mjs" <run_dir> --merge "agents/*.json" --lang <en|es> [--vertical <ids>] [--environment <kind>] [--out-md <path>] — 重新读取 findings.deterministic.json，合并各 Agent 数组（按 id + 规范化位置去重，保留严重程度最高的条目；needs_api / manual_review 绝不会覆盖已评分的状态），将架构无效的发现项移至 report.dropped_findings，按页面及整个网站汇总评分，并重写 findings.json、report.json、report.md。传入与第 1 步相同的 --vertical / --environment。--merge 可重复使用，可接受文件、目录，或仅针对文件名的 * / ? glob。
3. 根据 report.json 展示结果（各评分等级/解读见 references/scoring-model.md）：
   • Search SEO 和 AI Visibility — 分别展示评分等级、分数和一句话解读，绝不混合；每项分别提供分类表（数值、权重、是否启用）。
   • 覆盖情况：coverage.mode（完整或确定性）、达到的层级、needs_api / manual_review 数量。
   • 采样表，数据来自 crawl.json：发现与采样的模板数量、按角色划分的页面，以及每项跳过记录及原因。
   • 平台概况行（平台/框架/插件、环境；非生产环境时注明「预期在预览环境中」）。
   • 按影响 ÷ 工作量排序的首要操作项：状态、证据、建议、可修复性（自动/拟议/建议）、expected_impact。
   • report.md 的绝对路径，然后提供以下选项：/claude-seo-ai:fix <target>（安全的 AUTO 修复，每项变更均需确认）和变更后的 /claude-seo-ai:compare --baseline latest --against <target>。

降级模式

如果缺少 node，或仅安装了 skills 而未附带 scripts/ 目录：首先说明这一点。仅使用 WebFetch 摘要作为后备；将每项依赖 header/status/render/robots 的发现标记为 needs_api；跳过持久化；将报告标记为 "prompt-only mode — not comparable to a scripted run"。绝不将 WebFetch 摘要呈现为原始 HTML 或经过测量的状态/header。