エクストラクター

エクストラクターは、特定の種類のデータを取得するための、安定した名前を持つ再利用可能なコンポーネントです。Guida 0.9 では、記述子をワークスペースに置きます。Guida はそれらを検索可能なカタログとして読み込み、実装上の注意事項を非公式なチェックリストにすることなく、検証、認定、結果比較を行えるようにします。

エクストラクターを実行するのは Guida Complete と Guida Node です。 Guida Control は同じ契約を Remote Ops 経由で表示しますが、別のカタログを保持するわけではありません。

記述子と実装

記述子は公開契約です。実装、データ源、ワークフロー、キュー、既定入力、対象ドメイン、出力契約、必要な根拠を宣言します。実装そのものは、ワークスペース内の通常のコードです。

{
  "$schema": "../../../extractors.schema.json",
  "id": "careers.example.jobs",
  "profile": "web.discovery.browser",
  "label": "Example engineering jobs",
  "domain": "careers",
  "workflowName": "careers-example",
  "queueName": "careers_example",
  "implementation": {
    "module": "lib/careers-example-worker.js",
    "export": "discoverExampleJobs",
    "language": "javascript"
  },
  "source": { "kind": "web", "url": "https://example.com/careers" },
  "targetDomains": ["example.com"],
  "input": {
    "defaultUrl": "https://example.com/careers",
    "defaultCompanyName": "Example",
    "defaultSlug": "example"
  },
  "evidence": {
    "requiresPageLoaded": true,
    "requiresResultEvidence": true,
    "allowQualifiedEmpty": true
  }
}

小さなルートファイル extractors.json から記述子を取り込み、共通プロファイルを選択し、大規模なカタログを決定的なシャードに分割できます。各項目は固有の ID と読み込み元パスを保持します。

実行前の契約検証

カタログ検証では、不正な記述子、重複 ID、実装の欠落、解決できないプロファイル、無効なドメイン規則、互換性のない入出力契約を検出します。互換性チェックにより、エクストラクターと利用側の境界が明確になります。

スクリプティング API では、同期かつ読み取り専用の g.extractors.list()、g.extractors.get()、 g.extractors.validate() を利用できます。リモートクライアントは workspace.extractors.* と workspace.extractors.contracts.* を使います。

根拠を伴う認定

認定は範囲を限定した運用検証であり、永久に有効な保証ではありません。

Quick は対象を意図的に絞り、短時間で結果を返します。
Coverage は宣言された上限の範囲で、選択したカタログ全体へ検証を広げます。
空の結果を合格とするには、ページが読み込まれた根拠と、記述子で空結果を許可していることの両方が必要です。
セレクターの根拠は、宣言だけでなく実際に観測されていなければなりません。
巡回の完了状況と打ち切りを記録し、部分的な検証を完全な網羅として扱いません。

まず workspace.extractors.certification.plan で計画を作成します。計画には、実行可能な項目、ブロックされた項目、適用される上限が示されます。認定の開始、取り消し、根拠の書き出しには、引き続き Guida 側のポリシーと確認が適用されます。

Guida は最新の検証結果と、その根拠となる履歴を分けて保持します。実行、エクストラクターごとの結果、統計、異常検出、契約変更、書き出した根拠を確認できます。保持方針はワークスペースで定義し、運用データは operations.db に保存されます。

カタログと運用画面は、単一ホスト上の決定的なテストで 5,000 件のエクストラクターまで検証済みです。これは 5,000 件のブラウザーセッションを同時実行できるという意味でも、Enterprise フリートの上限を示す数字でもありません。

セマンティックパイプラインは、契約に沿った出力を検証ゲート、マッパー、出力先へ接続します。生成パイプラインでは $extractor.id などの明示的なバインディングを使い、Guida がファイル名やフォルダー名から意味を推測することはありません。