Geofeed Tuner – より優れた IP ジオロケーションフィードを作成

このスキルは、CSV 形式の IP ジオロケーションフィードの作成と改善を以下の方法で支援します：

• CSV の形成が良好で一貫していることを確認
• RFC 8805（業界標準）とのアライメントを確認
• 実運用デプロイから学んだ意見的なベストプラクティスを適用
• 精度、完全性、プライバシーの向上を提案

このスキルを使用する場合

• ユーザーが CSV 形式の IP ジオロケーションフィードの作成、改善、または公開を支援するよう求めた場合、このスキルを使用します。
• CSV ジオロケーションフィードのチューニングとトラブルシューティングに使用—エラーをキャッチし、改善を提案し、RFC 準拠以上の実運用での使用可能性を確保します。
• 対象ユーザー：
  • 公開ルーティング可能な IP アドレス空間を担当するネットワークオペレータ、管理者、エンジニア
  • ISP、モバイルキャリア、クラウドプロバイダ、ホスティングおよびコロケーション企業、インターネット交換オペレータ、衛星インターネットプロバイダなどの組織
• 使用しないでください：このスキルをプライベートまたは内部 IP アドレス管理に使用しないでください；公開ルーティング可能な IP アドレスのみに適用されます。

前提条件

• Python 3 が必要です。

ディレクトリ構造とファイル管理

このスキルは、配布ファイル（読み取り専用）と作業ファイル（実行時に生成）の明確な分離を使用します。

読み取り専用ディレクトリ（変更しないでください）

以下のディレクトリには静的配布アセットが含まれています。これらのディレクトリ内のファイルを作成、変更、削除しないでください：

ディレクトリ	目的
assets/	静的データファイル（ISO コード、例）
references/	RFC 仕様とリファレンス用コードスニペット
scripts/	実行可能コードとレポート用 HTML テンプレート

作業ディレクトリ（生成されたコンテンツ）

すべての生成、一時、出力ファイルはこれらのディレクトリに保存されます：

ディレクトリ	目的
run/	すべてのエージェント生成コンテンツの作業ディレクトリ
run/data/	リモート URL からダウンロードした CSV ファイル
run/report/	生成された HTML チューニングレポート

ファイル管理ルール

1. assets/、references/、scripts/ には絶対に書き込まないでください—これらはスキル配布の一部であり、変更されないままである必要があります。
2. すべてのダウンロード入力ファイル（リモート URL から）は ./run/data/ に保存する必要があります。
3. すべての生成 HTML レポートは ./run/report/ に保存する必要があります。
4. すべての生成 Python スクリプトは ./run/ に保存する必要があります。
5. run/ ディレクトリはセッション間にクリアされる場合があります；永続データを保存しないでください。
6. 実行用作業ディレクトリ： ./run/ の生成スクリプトはすべて、スキルのルートディレクトリ（SKILL.md を含むディレクトリ）を現在の作業ディレクトリとして実行する必要があります。これにより、assets/iso3166-1.json および ./run/data/report-data.json のような相対パスが正しく解決されます。スクリプト実行前に ./run/ に cd しないでください。

処理パイプライン：順序付きフェーズ実行

すべてのフェーズは、フェーズ 1 からフェーズ 6 まで順序通り実行する必要があります。各フェーズは前のフェーズの正常終了に依存しています。たとえば、構造チェックは品質分析が実行される前に完了する必要があります。

フェーズは以下に概略されています。エージェントは各フェーズセクションで概説されている詳細なステップに従う必要があります。

フェーズ	名前	説明
1	標準を理解する	自己公開 IP ジオロケーションフィード向け RFC 8805 の主要要件を確認
2	入力を収集する	ローカルファイルまたはリモート URL から IP サブネットデータを収集
3	チェックと提案	CSV 構造を検証、IP プレフィックスを分析、データ品質をチェック
4	チューニングデータ検索	Fastah の MCP ツールを使用してジオロケーション精度向上用データを取得
5	チューニングレポート生成	分析と提案をまとめた HTML レポートを作成
6	最終確認	レポートデータの一貫性と完全性を確認

フェーズをスキップしないでください。 各フェーズは後続のステージに必要な重要なチェックまたはデータ変換を提供します。

実行計画ルール

各フェーズを実行する前に、エージェントは可視化される TODO チェックリストを生成する必要があります。

計画は以下を満たす必要があります：

• フェーズの最初に表示される
• すべてのステップを順序通りにリストする
• チェックボックス形式を使用する
• ステップの完了時にライブで更新される

フェーズ 1：標準を理解する

このスキルが適用する RFC 8805 の主要要件は以下に概略されています。この概要を作業用リファレンスとして使用してください。 完全な RFC 8805 テキスト は、エッジケース、曖昧な状況、またはユーザーがここで説明されていない標準質問を提起した場合にのみ参照してください。

RFC 8805 主要事実

目的： 自己公開 IP ジオロケーションフィードにより、ネットワークオペレータは簡単な CSV 形式で IP アドレス空間の権威的なロケーションデータを公開でき、ジオロケーションプロバイダがオペレータ提供の修正を組み込むことができます。

CSV カラム順序（セクション 2.1.1.1–2.1.1.5）：

カラム	フィールド	必須	注記
1	ip_prefix	はい	CIDR 記法；IPv4 または IPv6；ネットワークアドレスである必要があります
2	alpha2code	いいえ	ISO 3166-1 alpha-2 国別コード；空白または "ZZ" = ジオロケーション不可
3	region	いいえ	ISO 3166-2 細分化コード（例：US-CA）
4	city	いいえ	自由形式の都市名；権威的な検証セットはありません
5	postal_code	いいえ	廃止—空のままにするか、省略する必要があります

構造ルール：

• ファイルには # で始まるコメント行（ヘッダーを含む）を含む場合があります。
• ヘッダー行はオプション；存在する場合、# で始まっていればコメントとして扱われます。
• ファイルは UTF-8 エンコードである必要があります。
• サブネット ホストビットが設定されていてはいけません（例：192.168.1.1/24 は無効；192.168.1.0/24 を使用）。
• グローバルルーティング可能なユニキャストアドレスにのみ適用—プライベート、ループバック、リンクローカル、マルチキャストスペースではありません。

ジオロケーション不可： alpha2code が空または大文字小文字を区別しない ZZ（region/city の値に関係なく）を持つエントリは、オペレータがそのプレフィックスにジオロケーションを適用したくないという明示的なシグナルです。

郵便番号廃止（セクション 2.1.1.5）： 5 番目のカラムは郵便番号またはZIP コードを含まないようにする必要があります。IP 範囲マッピングに対して細粒度すぎ、プライバシーの懸念が生じます。

フェーズ 2：入力を収集する

• ユーザーが IP サブネットまたは範囲のリストを既に提供していない場合（inetnum または inet6num と呼ばれることもあります）、それを提供するよう促します。受け入れられる入力形式：

  • チャットに貼り付けられたテキスト
  • ローカル CSV ファイル
  • CSV ファイルを指すリモート URL

• 入力がリモート URLの場合：

  • 処理前に CSV ファイルを ./run/data/ にダウンロードしてみます。
  • HTTP エラー（4xx、5xx、タイムアウト、またはリダイレクトループ）の場合、すぐに停止してユーザーに報告します： Feed URL is not reachable: HTTP {status_code}. Please verify the URL is publicly accessible.
  • 不完全またはスペシャリストなダウンロードでフェーズ 3 に進まないでください。

• 入力がローカルファイルの場合、ダウンロードせずに直接処理します。

• エンコード検出と正規化：

  1. 最初に UTF-8 としてファイルを読み込んでみます。
  2. UnicodeDecodeError が発生した場合、utf-8-sig（BOM 付き UTF-8）、次に latin-1 を試します。
  3. 正常にデコードされたら、作業コピーとして UTF-8 に再エンコードして書き込みます。
  4. エンコードが成功しない場合は停止して報告します：Unable to decode input file. Please save it as UTF-8 and try again.

フェーズ 3：チェックと提案

実行ルール

• このフェーズ用のスクリプトを生成します。
• このフェーズを他のフェーズと組み合わせないでください。
• 将来のフェーズデータを事前計算しないでください。
• 出力を JSON ファイルとして保存します：./run/data/report-data.json

スキーマ定義

以下の JSON 構造はフェーズ 3 中に不変です。フェーズ 4 は後で、各 Entries 内のオブジェクトに TunedEntry オブジェクトを追加します—これが唯一の許可されたスキーマ拡張で、別々のフェーズで行われます。

JSON キーは {{.CountryCode}}、{{.HasError}} などのテンプレートプレースホルダに直接マップされます。

{
  "InputFile": "",
  "Timestamp": 0,

  "TotalEntries": 0,
  "IpV4Entries": 0,
  "IpV6Entries": 0,
  "InvalidEntries": 0,

  "Errors": 0,
  "Warnings": 0,
  "OK": 0,
  "Suggestions": 0,

  "CityLevelAccuracy": 0,
  "RegionLevelAccuracy": 0,
  "CountryLevelAccuracy": 0,
  "DoNotGeolocate": 0,

  "Entries": [
    {
      "Line": 0,
      "IPPrefix": "",
      "CountryCode": "",
      "RegionCode": "",
      "City": "",

      "Status": "",
      "IPVersion": "",

      "Messages": [
        {
          "ID": "",
          "Type": "",
          "Text": "",
          "Checked": false
        }
      ],

      "HasError": false,
      "HasWarning": false,
      "HasSuggestion": false,
      "DoNotGeolocate": false,
      "GeocodingHint": "",
      "Tunable": false
    }
  ]
}

フィールド定義：

トップレベルメタデータ：

• InputFile：元の入力ソース、ローカルファイル名またはリモート URL のいずれか。
• Timestamp：チューニングが実行されたときの Unix エポック以降のミリ秒。
• TotalEntries：処理されたデータ行の総数（コメント行と空行を除く）。
• IpV4Entries：IPv4 サブネットであるエントリの数。
• IpV6Entries：IPv6 サブネットであるエントリの数。
• InvalidEntries：IP プレフィックス解析と CSV 解析に失敗したエントリの数。
• Errors：Status が ERROR であるエントリの総数。
• Warnings：Status が WARNING であるエントリの総数。
• OK：Status が OK であるエントリの総数。
• Suggestions：Status が SUGGESTION であるエントリの総数。
• CityLevelAccuracy：City が空でない有効なエントリの数。
• RegionLevelAccuracy：RegionCode が空でなく City が空である有効なエントリの数。
• CountryLevelAccuracy：CountryCode が空でなく、RegionCode と City が空である有効なエントリの数。
• DoNotGeolocate（メタデータ）：CountryCode、RegionCode、City がすべて空である有効なエントリの数。

エントリフィールド：

• Entries：オブジェクトの配列、データ行ごとに 1 つ、以下のエントリごとのフィールド付き：
  • Line：元の CSV 内の 1 から始まる行番号（コメント行と空行を含むすべての行をカウント）。
  • IPPrefix：CIDR スラッシュ表記での正規化 IP プレフィックス。
  • CountryCode：ISO 3166-1 alpha-2 国別コード、または空文字列。
  • RegionCode：ISO 3166-2 地域コード（例：US-CA）、または空文字列。
  • City：都市名、または空文字列。
  • Status：割り当てられた最高の重大度：ERROR > WARNING > SUGGESTION > OK。
  • IPVersion：解析された IP プレフィックスに基づいて "IPv4" または "IPv6"。
  • Messages：メッセージオブジェクトの配列、各オブジェクトは以下を含む：
    • ID：検証ルールリファレンス表からの文字列識別子（例："1101"、"3301"）。
    • Type：重大度タイプ："ERROR"、"WARNING"、または "SUGGESTION"。
    • Text：人間が読める検証メッセージ文字列。
    • Checked：検証ルールが自動チューニング可能な場合は true（リファレンス表の Tunable: true）、そうでない場合は false。レポート内のチェックボックスが checked か disabled かを制御します。
  • HasError：いずれかのメッセージが Type "ERROR" を持つ場合は true。
  • HasWarning：いずれかのメッセージが Type "WARNING" を持つ場合は true。
  • HasSuggestion：いずれかのメッセージが Type "SUGGESTION" を持つ場合は true。
  • DoNotGeolocate（エントリ）：CountryCode が空または "ZZ" の場合は true—エントリはジオロケーション不可の明示的なシグナル。
  • GeocodingHint：フェーズ 3 では常に空文字列 ""。将来の使用のため予約。
  • Tunable：エントリ内のいずれかのメッセージが Checked: true を持つ場合は true。すべてのメッセージの Checked 値にわたって論理 OR として計算されます。このフラグはレポート内の「Tune」ボタン可視性を駆動します。

検証ルールリファレンス

エントリにメッセージを追加する場合、このテーブルから ID、Type、Text、Checked の値を使用します。

ID	Type	Text	Checked	条件リファレンス
1101	ERROR	IP プレフィックスが空です	false	IP プレフィックス分析：空
1102	ERROR	無効な IP プレフィックス：IPv4 または IPv6 ネットワークとして解析できません	false	IP プレフィックス分析：無効な構文
1103	ERROR	非公開 IP 範囲は RFC 8805 フィードでは許可されません	false	IP プレフィックス分析：非公開
3101	SUGGESTION	IPv4 プレフィックスが異常に大きく、タイプミスを示唆している可能性があります	false	IP プレフィックス分析：IPv4 < /22
3102	SUGGESTION	IPv6 プレフィックスが異常に大きく、タイプミスを示唆している可能性があります	false	IP プレフィックス分析：IPv6 < /64
1201	ERROR	無効な国別コード：有効な ISO 3166-1 alpha-2 値ではありません	true	国別コード分析：無効
1301	ERROR	無効な地域形式；COUNTRY-SUBDIVISION（例：US-CA）を想定	true	地域コード分析：不正な形式
1302	ERROR	無効な地域コード：有効な ISO 3166-2 細分化ではありません	true	地域コード分析：未知のコード
1303	ERROR	地域コードが指定された国別コードと一致しません	true	地域コード分析：不一致
1401	ERROR	無効な都市名：プレースホルダ値は許可されません	false	都市名分析：プレースホルダ
1402	ERROR	無効な都市名：省略形またはコードベースの値が検出されました	true	都市名分析：省略形
2401	WARNING	都市名の形式が一貫していません；値の正規化を検討してください	true	都市名分析：形式
1501	ERROR	郵便番号は RFC 8805 で廃止されているため、プライバシー上の理由から削除する必要があります	true	郵便番号チェック
3301	SUGGESTION	地域は通常、小規模領土では不要です；地域値を削除することを検討してください	true	チューニング：小規模領土の地域
3402	SUGGESTION	都市レベルの粒度は通常、小規模領土では不要です；都市値を削除することを検討してください	true	チューニング：小規模領土の都市
3303	SUGGESTION	都市が指定されている場合は地域コードを推奨します；ドロップダウンから地域を選択してください	true	チューニング：都市の地域がない
3104	SUGGESTION	このサブネットが意図的にジオロケーション不可としてマークされているか、ロケーションデータが不足しているかを確認してください	true	チューニング：不特定ジオロケーション

メッセージの設定

検証チェックが一致した場合、リファレンステーブルの値を使用して、エントリの Messages 配列にメッセージを追加します：

entry["Messages"].append({
    "ID": "1201",      # テーブルから
    "Type": "ERROR",   # テーブルから
    "Text": "Invalid country code: not a valid ISO 3166-1 alpha-2 value",  # テーブルから
    "Checked": True    # テーブルから（True = チューニング可能）
})

エントリのすべてのメッセージを設定した後、エントリレベルのフラグを導出します：

entry["HasError"] = any(m["Type"] == "ERROR" for m in entry["Messages"])
entry["HasWarning"] = any(m["Type"] == "WARNING" for m in entry["Messages"])
entry["HasSuggestion"] = any(m["Type"] == "SUGGESTION" for m in entry["Messages"])
entry["Tunable"] = any(m["Checked"] for m in entry["Messages"])

精度レベルカウントルール

精度レベルは相互排他的です。最も細粒度の空でないジオフィールドに基づいて、各有効な（非エラー、非無効）エントリを正確に 1 つのバケットに割り当てます：

条件	バケット
City が空でない	CityLevelAccuracy
RegionCode が空でなく、City が空である	RegionLevelAccuracy
CountryCode が空でなく、RegionCode と City が空である	CountryLevelAccuracy
DoNotGeolocate（エントリ）が true	DoNotGeolocate（メタデータ）

HasError: true を持つエントリや InvalidEntries 内のエントリをカウントしないでください。

エージェントは以下を実行してはいけません：

• フィールドの名前を変更
• フィールドを追加または削除
• データ型を変更
• キーの順序を変更
• ネストを変更
• オブジェクトをラップ
• 複数のファイルに分割

値が不明な場合、空のままにしてください—データを作成しないでください。

構造とフォーマットチェック

このフェーズは、フィードが正常に形成され、解析可能であることを検証します。重大な構造エラーをチューナーが地理的位置情報の品質を分析する前に解決する必要があります。

CSV 構造

このサブセクションは、IP ジオロケーションフィードに使用されるCSV 形式の入力ファイルのルールを定義しています。 目標は、ファイルが確実に解析され、一貫した内部表現に正規化されることです。

• CSV 構造チェック

  • pandas が利用可能な場合、CSV 解析に使用します。

  • そうでない場合、Python の組み込み csv モジュールにフォールバックします。

  • CSV が正確に 4 または 5 の論理カラムを含むことを確認します。

  • コメント行が許可されています。

  • ヘッダー行はあっても、なくてもかまいません。

  • ヘッダー行が存在しない場合、暗黙のカラム順序を想定します：

    ip_prefix, alpha2code, region, city, postal code (deprecated)
    

  • リファレンス入力ファイルを参照： assets/example/01-user-input-rfc8805-feed.csv

• CSV のクレンジングと正規化

  • 以下の操作と同等の Python ロジックを使用して CSV をクレンジングして正規化します：

    • 最初の 5 カラムのみを選択し、5 番目を超えるカラムをドロップします。
    • UTF-8 BOM を使用して出力ファイルを書き込みます。

  • コメント

    • 最初のカラムが # で始まるコメント行を削除します。
    • これは # で始まるヘッダー行も削除します。
    • 1 から始まる行番号をキーとして、完全な元の行を値として使用してコメントのマップを作成します。空行も保存します。
    • このマップを JSON ファイルに保存します：./run/data/comments.json
    • 例：{ "4": "# It's OK for small city states to leave state ISO2 code unspecified" }

• 注記

  • 実装パス（pandas と組み込み csv）の両方が、UTF-8 BOM が存在することを確認するために、utf-8-sig エンコーディングを使用して出力を書き込む必要があります。

IP プレフィックス分析

• 各エントリの IPPrefix フィールドが存在し、空でないことを確認します。

• エントリ間で重複する IPPrefix 値をチェックします。

• 重複が見つかった場合、スキルを停止してユーザーにメッセージで報告します：Duplicate IP prefix detected: {ip_prefix_value} appears on lines {line_numbers}

• 重複が見つからない場合は、分析を続行します。

• チェック

  • 各サブネットは、references/ フォルダー内のコードスニペットを使用して、IPv4 または IPv6 ネットワークとして正常に解析する必要があります。
  • サブネットを正規化して CIDR スラッシュ表記で表示する必要があります。
    • 単一ホスト IPv4 サブネットは /32 として表される必要があります。
    • 単一ホスト IPv6 サブネットは /128 として表される必要があります。

• エラー

  • 以下の条件をエラーとして報告します：

  • 無効なサブネット構文

    • メッセージ ID：1102

  • 非公開アドレス空間

    • プライベート、ループバック、リンクローカル、マルチキャスト、またはそれ以外の非公開であるサブネットに適用されます
      • Python では、./references に示されるように、is_private および関連アドレスプロパティを使用して非公開範囲を検出します。
    • メッセージ ID：1103

• 提案

  • 以下の条件を提案として報告します：

  • 異常に大きい IPv6 サブネット

    • /64 より短いプレフィックス
    • メッセージ ID：3102

  • 異常に大きい IPv4 サブネット

    • /22 より短いプレフィックス
    • メッセージ ID：3101

地理的位置情報品質チェック

地理的位置情報データの精度と一貫性を分析します：

• 国別コード
• 地域コード
• 都市名
• 廃止されたフィールド

このフェーズは構造チェックが成功した後に実行されます。

国別コード分析

• ローカルで利用可能なデータテーブル ISO3166-1 を使用してチェックします。

  • 国と地域を持つ JSON 配列、ISO コード付き
  • 各オブジェクトには以下が含まれます：
    • alpha_2：2 文字の国別コード
    • name：短い国名
    • flag：フラグの絵文字
  • このファイルは RFC 8805 CSV の有効な CountryCode 値のスーパーセットを表します。

• エントリの CountryCode（RFC 8805 セクション 2.1.1.2、カラム alpha2code）を alpha_2 属性に対してチェックします。

• サンプルコードは references/ ディレクトリで利用可能です。

• 国が assets/small-territories.json で見つかった場合、エントリを内部的に小規模領土としてマークします。このフラグは後のチェックと提案で使用されますが、出力 JSON に保存されません（一時的な検証状態です）。

• 注： small-territories.json には、iso3166-1.json に存在しない一部の歴史的/紛争中のコード（AN、CS、XK）が含まれています。これらのいずれかを CountryCode として使用するエントリは、小規模領土として一致する場合でも、国別コード検証（エラー）に失敗します。国別コード エラーが優先されます—小規模領土フラグに基づいて抑制しないでください。

• エラー

  • 以下の条件をエラーとして報告します：
  • 無効な国別コード
    • 条件：CountryCode が存在しますが、alpha_2 セットで見つかりません
    • メッセージ ID：1201

• 提案

  • 以下の条件を提案として報告します：

  • サブネットの不特定ジオロケーション

    • 条件：すべての地理フィールド（CountryCode、RegionCode、City）がサブネット用に空です。
    • アクション：
      • エントリの DoNotGeolocate = true を設定します。
      • エントリの CountryCode を ZZ に設定します。
    • メッセージ ID：3104

地域コード分析

• ローカルで利用可能なデータテーブル ISO3166-2 を使用してチェックします。

  • ISO コード付きの国の細分化物を持つ JSON 配列
  • 各オブジェクトには以下が含まれます：
    • code：国別コード（例：US-CA）で前置された細分化コード
    • name：短い細分化名
  • このファイルは RFC 8805 CSV の有効な RegionCode 値のスーパーセットを表します。

• RegionCode 値が提供された場合（RFC 8805 セクション 2.1.1.3）：

  • 形式が {COUNTRY}-{SUBDIVISION}（例：US-CA、AU-NSW）と一致することを確認します。
  • 値を code 属性に対してチェックします（既に国別コードで前置されています）。

• 小規模領土例外： エントリが小規模領土且つ RegionCode 値がエントリの CountryCode に等しい場合（例：シンガポール向けの国と地域の両方の SG）、地域を受け入れ可能として扱います—このエントリのすべての地域検証チェックをスキップします。小規模領土は実質的に、意味のある ISO 3166-2 行政区分がない都市国家です。

• エラー

  • 以下の条件をエラーとして報告します：
  • 無効な地域形式
    • 条件：RegionCode が {COUNTRY}-{SUBDIVISION} と一致しない且つ小規模領土例外が適用されない
    • メッセージ ID：1301
  • 不明な地域コード
    • 条件：RegionCode 値が code セットで見つからない且つ小規模領土例外が適用されない
    • メッセージ ID：1302
  • 国と地域の不一致
    • 条件：RegionCode の国の部分が CountryCode と一致しない
    • メッセージ ID：1303

都市名分析

• 都市名はヒューリスティックチェックのみを使用して検証されます。

• 現在、都市名を検証するための権威的なデータセットはありません。

• エラー

  • 以下の条件をエラーとして報告します：

  • プレースホルダまたは無意味な値

    • 条件：以下を含むプレースホルダまたは無意味な値：
      • undefined
      • Please select
      • null
      • N/A
      • TBD
      • unknown
    • メッセージ ID：1401

  • 切り詰められた名前、省略形、または空港コード

    • 条件：有効な都市名を表さない切り詰められた名前、省略形、または空港コード：
      • LA
      • Frft
      • sin01
      • LHR
      • SIN
      • MAA
    • メッセージ ID：1402

• 警告

  • 以下の条件を警告として報告します：
  • 一貫性のない大文字小文字または形式
    • 条件：データ品質を低下させる可能性のある一貫性のない大文字小文字、スペース、または形式の都市名、例えば：
      • HongKong 対 Hong Kong
      • 混合大文字小文字または予期しないスクリプト使用
    • メッセージ ID：2401

郵便番号チェック

• RFC 8805 セクション 2.1.1.5 は郵便番号またはZIP コードを明示的に廃止しています。

• 郵便番号は非常に小さな人口を表すことができ、統計的性質を持つ IP アドレス範囲のマッピングにプライバシー上の懸念のため考慮されません。

• エラー

  • 以下の条件をエラーとして報告します：
  • 郵便番号が存在
    • 条件：郵便/ZIP コードフィールドに空でない値が存在します。
    • メッセージ ID：1501

チューニングと推奨事項

このフェーズは、実運用ジオフィードデプロイから学んだ RFC 8805 を超える意見的な推奨事項を適用し、精度と使用可能性を向上させます。

• 提案

  • 以下の条件を提案として報告します：

  • 小規模領土に指定された地域または都市

    • 条件：
      • エントリが小規模領土
      • RegionCode が空でないまたは
      • City が空でない。
    • メッセージ ID：3301（地域の場合）、3402（都市の場合）

  • 都市が指定されている場合は地域コードが欠落

    • 条件：
      • City が空でない
      • RegionCode が空である
      • エントリが小規模領土ではない
    • メッセージ ID：3303

フェーズ 4：チューニングデータ検索

目的

Fastah の rfc8805-row-place-search ツールを使用して、すべての Entries をルックアップします。

実行ルール

• ペイロード生成のみ用の新しいスクリプトを生成します（データセットを読み取り、1 つ以上のペイロード JSON ファイルを書き込みます；このスクリプトから MCP を呼び出さないでください）。
• サーバーは 1 リクエストあたり最大 1000 エントリのみを受け入れるため、1000 を超えるエントリがある場合、複数のリクエストに分割します。
• エージェントは生成されたペイロードファイルを読み込み、それらからリクエストを構築し、最大 1000 エントリのバッチで MCP サーバーにそれらのリクエストを送信する必要があります。
• MCP 失敗時： MCP サーバーに到達できない、エラーを返す、または任意のバッチに対して結果を返さない場合、警告をログして、フェーズ 5 に続行します。影響を受けるすべてのエントリに対して TunedEntry: {} を設定します。レポート生成をブロックしないでください。ユーザーに明確に通知します：Tuning data lookup unavailable; the report will show validation results only.
• 提案はアドバイスのみ—それらを自動入力しないでください。

ステップ 1：重複排除によるルックアップペイロードの構築

データセットを以下から読み込みます：./run/data/report-data.json

• Entries 配列を読み込みます。各エントリは MCP ルックアップペイロードを構築するために使用されます。

サーバーリクエストを重複排除により削減します：

• Entries の各エントリについて、コンテンツハッシュ（CountryCode + RegionCode + City のハッシュ）を計算します。
• 重複排除マップを作成します：{ contentHash -> { rowKey, payload, entryIndices: [] } }。rowKey は、MCP サーバーに送信されてレスポンスをマッチングするために使用される UUID です。
• エントリのハッシュが既に存在する場合、その0 から始まる配列インデックス in Entries を、その重複排除エントリの entryIndices 配列に追加します。
• ハッシュが新規の場合、UUID (rowKey) を生成し、新しい重複排除エントリを作成します。

リクエストバッチを構築します：

• マップから一意の重複排除エントリを抽出し、重複排除順を保持します。
• 最大 1000 項目のリクエストバッチを構築します。
• 各バッチについて、[{ rowKey, payload, entryIndices }, ...] のようなメモリ内構造を保持して、rowKey によってレスポンスをマップバックします。
• MCP ペイロードファイルを書き込むときに、各ペイロードオブジェクトに rowKey フィールドを含めます：

[
    {"rowKey": "550e8400-e29b-41d4-a716-446655440000", "countryCode":"CA","regionCode":"CA-ON","cityName":"Toronto"},
    {"rowKey": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "countryCode":"IN","regionCode":"IN-KA","cityName":"Bangalore"},
    {"rowKey": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "countryCode":"IN","regionCode":"IN-KA"}
]

• レスポンスを読み込むときに、各レスポンス rowKey フィールドを、対応するすべての entryIndices を取得するための重複排除エントリと一致させます。

ルール：

• ペイロードを以下に書き込みます：./run/data/mcp-server-payload.json
• ペイロードを書き込んだ後、スクリプトを終了します。

ステップ 2：Fastah MCP ツールを起動

• Fastah MCP サーバーの mcp.json スタイル設定の例は以下の通りです：

    "fastah-ip-geofeed": {
      "type": "http",
      "url": "https://mcp.fastah.ai/mcp"
    }

• サーバー：https://mcp.fastah.ai/mcp

• ツールとそのスキーマ：最初の tools/call 前に、エージェントは tools/list リクエストを送信して、rfc8805-row-place-search の入力と出力スキーマを読み込む必要があります。 検出されたスキーマを、フィールド名、タイプ、制約の権威的なソースとして使用します。

• 以下は説明のみです；常に tools/list によって返されるスキーマに従います：

  [
      {"rowKey": "550e8400-...", "countryCode":"CA", ...},
      {"rowKey": "690e9301-...", "countryCode":"ZZ", ...}
  ]
  

• ./run/data/mcp-server-payload.json を開き、すべての重複排除エントリを rowKey と一緒に送信します。

• 重複排除後に 1000 を超える重複排除エントリがある場合、各 1000 エントリのリクエストに分割します。

• サーバーは、マップバックするために各レスポンスで同じ rowKey フィールドで応答します。

• ローカルデータを使用しないでください。

ステップ 3：チューニングデータをエントリにアタッチ

• チューニングデータをアタッチするための新しいスクリプトを生成します。
• ./run/data/report-data.json と重複排除マップ（ステップ 1 のメモリから保持、またはペイロードファイルから再導出）の両方を読み込みます。
• MCP サーバーからの各レスポンスについて：
  • レスポンスから rowKey を抽出します。
  • 重複排除マップからその rowKey に関連付けられた entryIndices 配列を検索します。
  • entryIndices の各インデックスについて、Entries[index] に最適なマッチをアタッチします。
• 利用可能な場合、レスポンスからの最初（最良）のマッチを使用します。

そのフィールドが存在しない場合、各影響を受けるエントリにフィールドを作成します。MCP API レスポンスキーを Go struct フィールド名に再マップします：

"TunedEntry": {
  "Name": "",
  "CountryCode": "",
  "RegionCode": "",
  "PlaceType": "",
  "H3Cells": [],
  "BoundingBox": []
}

TunedEntry フィールドは単一オブジェクト（配列ではない）です。MCP サーバーからの最適なマッチを保持します。

MCP API レスポンスキー → JSON キーマッピング：

MCP API レスポンスキー	JSON キー
placeName	Name
countryCode	CountryCode
stateCode	RegionCode
placeType	PlaceType
h3Cells	H3Cells
boundingBox	BoundingBox

UUID マッチを持たないエントリ（つまり MCP サーバーが UUID のレスポンスを返さなかった）は、空の TunedEntry: {} オブジェクトを受け取る必要があります—フィールドを欠落したままにしないでください。

• データセットを以下に書き込みます：./run/data/report-data.json
• ルール：
  • すべての既存検証フラグを維持します。
  • 追加の中間ファイルを作成しないでください。

フェーズ 5：チューニングレポート生成

./run/data/report-data.json と ./run/data/comments.json のデータを使用して、./scripts/templates/index.html のテンプレートをレンダリングすることで、自己完結した HTML レポートを生成します。

完成したレポートを ./run/report/geofeed-report.html に書き込みます。生成後、システムのデフォルトブラウザで開いてみてください（例：webbrowser.open()）。ヘッドレス環境、CI パイプライン、またはリモートコンテナで実行されていてブラウザが利用できない場合、ブラウザステップをスキップして、ファイルパスをユーザーに提示します。これでユーザーはファイルを開くか、ダウンロードできます。

テンプレートは Go html/template 構文（{{.Field}}、{{range}}、{{if eq}} など）を使用します。テンプレートを読み込み、JSON データファイルから レンダリングコンテキストを構築し、テンプレートプレースホルダを処理して最終 HTML を生成する Python スクリプトを書き込みます。テンプレートファイル自体を変更しないでください—すべての処理はレンダリング時に Python スクリプトで発生します。

ステップ 1：メタデータプレースホルダを置換

テンプレート内の各 {{.Metadata.X}} プレースホルダを、report-data.json から対応する値に置換します。JSON キーはテンプレートプレースホルダと一致するため、マッピングは直接的です—{{.Metadata.InputFile}} は InputFile JSON キーにマップされます等。

テンプレートプレースホルダ	JSON キー（report-data.json）
{{.Metadata.InputFile}}	InputFile
{{.Metadata.Timestamp}}	Timestamp
{{.Metadata.TotalEntries}}	TotalEntries
{{.Metadata.IpV4Entries}}	IpV4Entries
{{.Metadata.IpV6Entries}}	IpV6Entries
{{.Metadata.InvalidEntries}}	InvalidEntries
{{.Metadata.Errors}}	Errors
{{.Metadata.Warnings}}	Warnings
{{.Metadata.Suggestions}}	Suggestions
{{.Metadata.OK}}	OK
{{.Metadata.CityLevelAccuracy}}	CityLevelAccuracy
{{.Metadata.RegionLevelAccuracy}}	RegionLevelAccuracy
{{.Metadata.CountryLevelAccuracy}}	CountryLevelAccuracy
{{.Metadata.DoNotGeolocate}}	DoNotGeolocate（メタデータ）

{{.Metadata.Timestamp}} に関する注： このプレースホルダは JavaScript new Date(...) 呼び出し内に表示されます。生の整数値に置換します（<script> 内の数値リテラルに対して HTML エスケープは不要）。その他すべてのメタデータ値は HTML 要素テキスト内に表示されるため、HTML エスケープする必要があります。

ステップ 2：コメントマッププレースホルダを置換

テンプレート内でこのパターンを特定します：

const commentMap = {{.Comments}};

{{.Comments}} を ./run/data/comments.json からのシリアル化 JSON オブジェクトで置換します。JSON は直接 JavaScript オブジェクトリテラル（文字列内ではなく）として埋め込まれるため、追加のエスケープは不要です：

comments_json = json.dumps(comments)
template = template.replace("{{.Comments}}", comments_json)

ステップ 3：エントリ範囲ブロックを展開

テンプレートは <tbody id="entriesTableBody"> 内に {{range .Entries}}...{{end}} ブロックを含みます。以下のように処理します：

1. 正規表現を使用して範囲ブロックボディを抽出します。 重要： ブロックにはネストされた {{end}} タグ（{{if eq .Status ...}}、{{if .Checked}}、{{range .Messages}} から）が含まれています。\{\{range \.Entries\}\}(.*?)\{\{end\}\} のような素朴な非貪欲マッチは最初の内部 {{end}} にマッチし、ブロックを切り詰めます。代わりに、外部 {{end}} を後続の </tbody> にアンカーします：

   m = re.search(
       r'\{\{range \.Entries\}\}(.*?)\{\{end\}\}\s*</tbody>',
       template,
       re.DOTALL,
   )
   entry_body = m.group(1)  # 1 つのエントリイテレーション用テンプレートテキスト
   

   これにより、ネストされたすべての 3 つの <tr> 行と {{range .Messages}}...{{end}} を含む完全なブロックボディをキャプチャするようになります。
2. 反復report-data.json の Entries 配列の各エントリについて。
3. ブロックボディを展開各エントリに対して、以下の処理順序を使用します。
4. 全体マッチを置換します（{{range .Entries}} から </tbody> を通して）、連結された展開 HTML の後に </tbody> を続けます。

各エントリ向け処理順序（{{end}} の混同を避けるため、最も内側の構成から最初に）：

1. {{if eq .Status ...}}...{{end}} 条件を評価します（ステータスバッジクラスとアイコン）。
2. {{if .Checked}}...{{end}} 条件を評価します（メッセージチェックボックス）。
3. {{range .Messages}}...{{end}} 内側範囲を展開します。
4. 単純な {{.Field}} プレースホルダを置換します。

エントリフィールドマッピング

範囲ブロックボディ内で、各エントリについてこれらのプレースホルダを置換します。JSON キーはテンプレートプレースホルダと一致するため、テンプレートプレースホルダ {{.X}} は JSON キー X に直接マップされます：

テンプレートプレースホルダ	JSON キー（Entries[]）	注記
{{.Line}}	Line	直接整数値
{{.IPPrefix}}	IPPrefix	HTML エスケープ
{{.CountryCode}}