aiseo-audit

aiseo-audit

AI 検索への対応状況を監査する、決定論的な Lighthouse 形式のツールです。 生成エンジンがウェブページをどれだけ容易に取得、抽出、理解し、再利用できるかをテストします。

AI SEO が測定するのは、従来の検索順位ではなくコンテンツの対応状況です。スコアは調査に基づくヒューリスティックな監査結果であり、引用される確率を示すものでも、エンジンがそのページを引用する保証でもありません。

ウェブサイトとガイド · クイックスタート · CI/CD · AI アシスタントでの利用 · ライブラリ API · スコアリング手法

クイックスタート

Node.js 20.19 以降が必要です。

npx aiseo-audit https://yoursite.com

インストールも API キーも不要です。分析は AI API の呼び出しやテレメトリーを使わず、ローカルで実行されます。ネットワークアクセスの対象は、ページ、サイトマップ、robots.txt や llms.txt などのドメインシグナルファイルに限定されます。

通常、出力の冒頭には全体スコア、パイプラインの段階、影響の大きい修正項目が表示されます。

Overall Score: 68/100  Grade: D+

Pipeline Stages:
  Technical Eligibility    PASS 96%
  Retrieval Alignment           58%
  Citation Fitness              63%
  Provenance                    42%

Top fixes:
  1. Topic Consistency  (Entity Clarity)
  2. Citation Patterns  (Grounding Signals)
  3. Lead Summary       (Answerability)

プロジェクト内に CLI をインストールする場合：

npm install --save-dev aiseo-audit

プログラマティック API を使用する場合は通常の依存関係としてインストールするか、npm install -g aiseo-audit を使ってグローバルにインストールしてください。

aiseo-audit を選ぶ理由

• タグの検出ではなく、コンテンツを分析します。 エンジンと同じようにページを読み取ります。ページの主題を一貫して示しているか、質問に直接回答しているか、主張を出典で裏付けているか、定型文が内容の妨げになっていないかを確認します。50 を超える要素を分析します。
• 根拠のレベルに応じてスコアを付けます。 各要素には supported、conditional、heuristic、diagnostic、experimental のいずれかのラベルが付き、docs/EVIDENCE.md にあるレビュー済みの文献に対応付けられます。
• パイプラインの段階ごとに結果を報告します。 主な制約が技術的な適格性、検索との整合性、引用への適性、来歴のどれにあるかを確認できます。
• 決定論的で、内容を確認できます。 同じスコアリングバージョン、設定、取得済み入力、評価日を使えば、同じスコアが得られます。重みやしきい値は外部サービスに隠さず、文書化されています。
• さまざまな方法で実行できます。 CLI、GitHub Action、MCP サーバー、型付き TypeScript API を使用できます。ターミナル、JSON、Markdown、スタンドアロン HTML のレポートを出力できます。

よくあるワークフロー

対象クエリに基づく監査

クエリ対応監査では、次の 3 点を測定します。タイトルや見出しなどの構造フィールドにクエリ語が含まれているか、本文にクエリ語が含まれているか、クエリの各側面に対応するセクションがページにあるかです。安定した測定には約 5 件のクエリを指定してください。指定できるのは最大 10 件です。

npx aiseo-audit https://example.com/guide \
  --query "how to set up sso" \
  --query "saml vs oidc" \
  --query "sso troubleshooting checklist"

製品固有の価格、仕様、比較に関するチェックには --domain product を使ってください。--engine gemini|gpt|perplexity は既存のカテゴリの重みを各エンジンに合わせて調整する実験的なプリセットを適用します。新たなチェックが追加されることはありません。

共有可能なレポートを作成する

出力形式はファイルの拡張子から推測されます。

npx aiseo-audit https://example.com --out report.html
npx aiseo-audit https://example.com --out report.md
npx aiseo-audit https://example.com --out report.json

スコアと上位 3 件の修正項目のみを表示するには、--tldr を使ってください。

経時的に変化を追跡する

# First run establishes a baseline; later runs show the delta.
npx aiseo-audit https://example.com --diff

# Compare with a specific result without updating tracked history.
npx aiseo-audit https://example.com --baseline ./previous-audit.json

# Show the timeline for every tracked URL.
npx aiseo-audit --diff --all

--diff はデフォルトで ./audits に JSON の結果を記録し、検出した設定ファイルを更新します。リポジトリで有効にする前に、CLI ガイドを確認してください。

サイトマップを監査する

npx aiseo-audit --sitemap https://example.com/sitemap.xml --out site-report.html

レポートには、平均スコア、サイト全体のカテゴリ別平均、ホストレベルの来歴プロファイル、URLごとの結果が含まれます。サイトマップインデックスにも対応しています。デフォルトではURLを順番に処理します。作業量を制限するには、--max-urls と --concurrency を使用してください。

その他のレシピとすべてのフラグについては、CLI ガイドをご覧ください。チュートリアルと実践的な実装ガイダンスについては、aiseo-audit.comをご覧ください。

監査レポートの内容

すべてのレポートでは、結果を次の4つのパイプラインステージにまとめています。

ステージ	意味
技術的適格性	ページを取得して利用可能なテキストを抽出し、少なくとも1つの既知の AI クローラーがアクセスできる状態を維持できますか？
検索との整合性	構造フィールド、エンティティ、トピックの網羅性、構造化データは、検索を支えていますか？
引用適性	文脈内のコンテンツは、再利用可能な、直接的で根拠に基づき、適切に最新の情報を提供していますか？
来歴	ページは、著者、組織の識別情報、帰属を明確に伝えていますか？

技術的適格性はゲートとして機能します。取得の失敗、利用できないテキスト、または既知のクローラーすべてをブロックしている場合、全体スコアは25点が上限となり、後続ステージのパーセンテージは表示されません。引用適性にも、明らかに古くなった時事的コンテンツ、対象クエリとの不一致、商品の価格情報の欠落に対する、エビデンスに基づく減点ゲートがあります。

評価要素は10のカテゴリに整理されています。クエリ整合性は対象クエリが指定された場合にのみ表示され、商品適合性は商品ページの場合にのみ表示されます。評価要素、重み、しきい値、ステージの対応関係については、監査の内訳をご覧ください。

スコア対象外の診断情報がスコアに影響することはありません。調査でまだ評価を正当化できない場合も、観察結果を確認できます。

スコアの解釈

レターグレードには、一般的な学業成績のスコア帯を使用しています。母集団のパーセンタイルや、引用される可能性の較正済み推定値ではなく、サイトが「平均以上」であることを示す根拠でもありません。ツールのバージョンと設定を一定に保ち、同じページまたはページセットを比較するためにスコアを使用し、最も重みの大きい指摘から対応して再測定してください。

--fail-under を使用する場合は、どのようなスコアでも必ず合格するという普遍的な基準として扱うのではなく、自分の v2 のベースラインからしきい値を設定してください。

CI/CD

公式の GitHub Action を使用すると、ワークフローのゲートを設定し、固定された PR コメントを維持できます。

name: AI SEO Audit
on:
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: agencyenterprise/aiseo-audit@v2
        with:
          url: https://yoursite.com
          fail-under: 70
          comment-on-pr: true

チェックをブロック条件にする前に、自分のページを基準に fail-under を調整してください。1行の CI コマンドでも実行できます。

npx aiseo-audit https://yoursite.com --fail-under 70

AI アシスタントとの連携（MCP）

付属の MCP サーバーは、Cursor、Claude Desktop、Windsurf、その他の MCP クライアントに audit_url ツールを提供します。

{
  "mcpServers": {
    "aiseo-audit": {
      "command": "npx",
      "args": ["-y", "aiseo-audit-mcp"]
    }
  }
}

このツールでは、queries と domain をオプションの引数として指定できます。別途サーバーをインストールする必要はありません。

設定

CLI は、現在のディレクトリから上位のディレクトリを検索し、aiseo.config.json、.aiseo.config.json、または aiseo-audit.config.json を探します。

{
  "queries": ["how to audit ai seo", "ai seo checklist"],
  "domain": "auto",
  "format": "html",
  "weights": {
    "answerability": 2,
    "groundingSignals": 2,
    "queryAlignment": 2
  }
}

重みのキーが指定されていない場合、デフォルト値は 1 です。カテゴリを除外するには、値を 0 に設定してください。すべてのフィールド、デフォルト値、例については、CLI の設定をご覧ください。

オフライン監査、再生、回帰ゲート

2.0.2 の次のリリースでは、指定した HTML、再現可能なスナップショット、安定した指摘、ページ固有のクローラーチェック、明示的な CI 失敗ポリシーが追加されます。移行の詳細については、信頼性と統合ガイドをご覧ください。

npx aiseo-audit --file ./dist/index.html --url https://example.com --out report.html
npx aiseo-audit https://example.com --snapshot-out inputs.json --out baseline.json
npx aiseo-audit --replay inputs.json --json
npx aiseo-audit https://example.com --baseline baseline.json --fail-on-regression

プログラム API

import { analyzeUrl, loadConfig, renderReport } from "aiseo-audit";

const config = await loadConfig();
const result = await analyzeUrl({ url: "https://example.com" }, config);
const html = renderReport(result, { format: "html" });

console.log(result.overallScore, result.grade);

このパッケージは ESM と CommonJS に対応し、アナライザー、サイトマップ、レポート、差分、設定、スコアリングの各型をエクスポートします。API ガイドをご覧ください。

制限事項

• ブラウザーでレンダリングされた DOM ではなく、取得した HTML を対象とします。 この監査ではクライアント側の JavaScript は実行されません。サーバー側でレンダリングされたコンテンツや事前にレンダリングされたコンテンツは確認できますが、ページの読み込み後にのみ追加されるコンテンツは見落とす場合があります。
• 視覚的な評価やマルチモーダル評価は行いません。 レイアウトの品質、煩わしい広告、視覚的な階層、画像だけで伝えられる情報は監査の対象外です。画像の alt テキストは確認できますが、ピクセルは確認できません。
• HTTP での公開アクセスを前提とします。 認証、同意フロー、パーソナライズ、ボット対策、地域によって、監査で取得される内容が変わる場合があります。
• ネットワークの応答は変動する場合があります。 同一の取得入力に対するスコアリングには決定性がありますが、リダイレクト、動的な HTML、実験、サーバー障害によって入力が変わる場合があります。
• サイトマップの処理には明示的な上限があります。 デフォルトでは実行は逐次的に行われます。大規模なサイトでは --max-urls と --concurrency を使用してください。部分的な網羅を明示的に許可しない限り、ページの取得に失敗すると CLI は失敗します。
• エンジンの挙動には引き続き非決定性があります。 準備状況スコアから、デプロイ済みのエンジンが特定の回答に対してページを取得または引用するかどうかを予測することはできません。

研究と方法論

このスコアリングモデルは、固定コンテキスト実験、検索研究、稼働中のエンジンに関する観察など、生成エンジン最適化（GEO）と生成情報検索に関する査読済み研究に基づいています。エビデンスの強さと実験の範囲が重要です。重みとしきい値は、確率を当てはめて算出したものではなく、専門家が設定したヒューリスティックです。

• 監査の内訳：すべてのカテゴリ、要因、範囲、段階、ゲート
• エビデンス：要因とエビデンスの対応関係、およびエビデンスの段階
• 新たな研究：複数の論文の統合とメンテナンスポリシー
• 論文レビュー：現在のモデルの基盤となる一次資料のレビュー

1.x からの移行

バージョン 2.0 では要因セットを再スコアリングしたため、同じページでも通常は異なるスコアになります。GitHub Action を @v1 から @v2 に変更する前に、主要なページのベースラインを再設定し、CI のしきい値を再調整してください。既存の 1.x の設定とベースラインデータは引き続き読み取れますが、--tldr が出力する JSON の形式は変更されました。

完全な2.0 移行ガイドをご覧ください。

ドキュメント

• ウェブサイトとガイド
• CLI と設定
• プログラムから利用する API
• スコアリングの方法論
• エビデンスマップ
• 研究の統合
• 今後の作業
• 変更履歴

コントリビューション

開発環境のセットアップ、プロジェクト構成、プルリクエストのガイドラインについては、CONTRIBUTING.mdをご覧ください。セキュリティ上の問題については、SECURITY.mdに従って報告してください。

ライセンス

MIT