seo-platform-detect

seo-platform-detect

プロファイルは、どのモジュールも単独では判断できない3つのことを決定します。プラットフォーム条件付きのチェック ID のうちどれを実行するか、プラットフォーム側が所有するためどの検出結果を not_applicable にするか、そして fix がどの修正アダプターを使うかです。監査ごとに1回、スナップショットの直後、ディスパッチの前に実行してください。

検出はサイトの種類とは独立しています。seo-vertical-detect は サイトの種類 を判定し、このスキルは 何を使って構築されているか を判定します。どちらも1つの profile.json に反映されます。

実行するタイミング

通常の /audit および /geo のフローでは、これを自分で実行する必要はありません。audit.mjs が実行時のホームページスナップショットに対して同じ detect() をすでに呼び出し、結果を <run_dir>/profile.json として保存します。まずそのファイルを読み込んでください。ヘッドレス処理では利用できなかったシグナル（リポジトリ／パッケージのシグナルには --path <project>、WordPress プラグインの判定には --probe）が必要な場合、またはランナーの外で作業している場合にのみ、スクリプトを直接実行してください。いずれの場合も、監査ごとに1回、ディスパッチ用エンベロープの作成前に実行します。すべてのサブエージェントが同じプロファイルを読み込みます。

実行方法

node "${CLAUDE_PLUGIN_ROOT}/scripts/detect-platform.mjs" --snapshot "<run_dir>/pages/<home-slug>.json"

該当する場合にのみ、フラグを追加してください。

• ユーザーからローカルプロジェクト（--project）が提供された場合は --path <project> を指定します。リポジトリとパッケージのシグナルを参照する唯一の方法です。これを指定しない場合、Payload は検出できず、Next.js ルーターの検出は DOM マーカーにフォールバックします。また、これにより capabilities.local_files が有効になり、ローカルファイルの修正が可能になります。
• 対象にアクセスでき、WordPress プラグインの判定が重要な場合は --probe を指定します。/wp-json/、/.well-known/ucp、/products.json、/wp-sitemap.xml にリクエストします。GET は合計4回で、それ以上は行いません。REST 名前空間の一覧が Yoast、Rank Math、AIOSEO を見分ける唯一の信頼できる方法です。HTML コメントが示すのはコメントを出力したプラグインであり、有効なプラグインではありません。
• 標準出力の JSON をパイプせずに保存するには、--out "<run_dir>/profile.platform.json" を指定します。

オフライン／フィクスチャーモード（テストで使用するほか、ネットワークに接続できない場合にも使用します）： --html <file> [--headers <json>] [--cookies <json>] [--probes <json>] [--url <u>]。

終了コード：0 成功 · 1 不正な呼び出し、または入力を読み取れない場合 · 2 フェッチ失敗。

返される内容

{ version: "detect-platform/1", target, platform, framework, cms_plugins[], hosting, environment, capabilities, write_targets[], candidates, vertical_hints[], cards[], sources, notes[] }。

platform／framework／cms_plugins[]／hosting はそれぞれ、独自の confidence（シグナルの種類が2つ以上あり、8以上で high、5以上で medium、2以上で low）と、それを導き出した signals を持ちます。証拠がこれに満たないレイヤーは null になります。プラットフォームを特定できないことも結果であり、欠落ではありません。特定できないものとして報告し、instructions に基づいて処理を続けてください。説明文で low を上位の確度に丸めないでください。

4つのレイヤーは個別にスコアリングされるため、ヘッドレス構成も正しく判定できます。たとえば、WordPress バックエンドと Next.js フロントエンドの構成では、platform: wordpress と framework: nextjs が得られ、capabilities.head_owner は framework になります。カードの内容が一致しない場合は、head_owner に従ってください。

profile.json への統合

<run_dir>/profile.json は、この出力と seo-vertical-detect の出力を統合したものです。audit.mjs がこれを書き込みます。detect() が所有するすべてのキーを更新し、追加したキーは保持するため、ファイル内の vertical ブロックは再実行後も残ります（--vertical フラグを指定した場合は上書きされます）。形式：

{ "version": "detect-platform/1", "platform": {…}, "framework": {…}, "cms_plugins": [],
  "hosting": {…}, "environment": {…}, "capabilities": {…}, "write_targets": [],
  "candidates": {…}, "vertical_hints": [], "cards": [], "sources": {…}, "notes": [],
  "vertical": { "primary": "ecommerce", "also": [], "multilingual": false, "locales": [] } }

vertical_hints[] は判定結果ではなく シグナル として seo-vertical-detect に渡してください。判定には、引き続き独自の証拠を引用する必要があります。environment.kind はスコアラーに渡してください（score.mjs --environment preview|staging|local）。これにより、本番環境以外のホストでは noindex タイプの重大度5の上限を適用せず、代わりに想定どおりのものとして報告します。

どのカードをどのサブエージェントに渡すか

profile.cards[] にはパス（references/platforms/<id>.md）がすでに記載されています。すべての ディスパッチ用エンベロープに、platform フィールド（profile.json の絶対パス）と1行の概要 （"shopify (high) · theme head · staging theme available · environment production"）とともに、platform_cards として記載し、次の2つの指示を一字一句そのまま添えてください。

• ルールに該当する場合は、カードの §10 のチェック ID を出力すること。
• カードの §4 の項目 ⇒ not_applicable とし、evidence.observed で担当者を明記すること。黙って合格にせず、プラットフォーム上で誰も変更できない項目を fail にしないでください。

プラットフォームカード、フレームワークカード、プラグインカードがあれば、それらを一緒に渡してください。ヘッドレスサイトでは、3つすべてが明らかに必要です。capabilities.instructions_only が true の場合は、提案する修正がすべてクリック手順として提示されることもエージェントに伝えてください。そのため、fix_preview は差分ではなく、人が読める文章にする必要があります。

誠実さ

• write_targets の needs に記載するのは認証情報のキー名です。有無は CLAUDE_PLUGIN_OPTION_<KEY> / <KEY> を確認します。値を読み取ったり、表示したり、ログに記録したりすることはありません。ready: false は「未設定」を意味し、「キーが間違っている」という意味ではありません。
• Cookie の名前は根拠として使用しますが、Cookie の値は記録しません。
• --path がない場合はリポジトリのシグナルがなく、--probe がない場合はプローブのシグナルがありません。プロフィールの notes[] にもその旨が記載されています。不完全なプロフィールを完全なものとして提示せず、レポートにもその旨を繰り返し記載してください。
• カードの §12 で UNVERIFIED と示されたシグナルは、検出の判定を裏付けるためには使用できますが、書き込みの根拠としては使用できません。未検証の API の詳細に修正が依存する場合、回答は needs_api です。