vpm-discovery

name	vpm-discovery
description	VRChatのVPMリポジトリURLを新たに発見・報告するスキル。GitHub API・Yahoo Japan リアルタイム・GoogleをWeb検索やplaywright-cliで補完し、直近1か月の検索範囲から未収録のVPMリポジトリを検出する。リポジトリ自体の作成日で除外せず、最近の更新や告知で発見できたものは報告対象に含める。特にYahooリアルタイム検索での補完調査と、報告URLのJSON実在確認が必要なときに使う。明示的に呼び出された場合のみ使用すること。

VPM Repository Discovery

VRChatのVPM（VPM Package Manager）リポジトリを新たに発見するスキルです。 GitHub APIを主要手段として使い、補完的にYahoo Japan・Googleも活用します。

概要フロー

1. 既知URLの読み込み — フィルタリング用に既存リストを収集
2. GitHub API検索 — 複数クエリで直近1か月の更新・露出がある候補を収集
3. 補完検索 — Yahoo Japan リアルタイム・Google・Booth連携 をplaywright-cliで検索
4. URL正規化と検証 — 短縮URL展開後、index.json / vpm.json に正規化して web_fetch で確認
5. 結果報告 — 未収録URLを集約的リポジトリ優先で報告

---

Step 1: 既知URLの読み込み

VPM Catalog自身の repositories.txt と repositories-ignore.txt を読み込んで既知URLのセットを作成する。 これらのファイルを 情報源として使用してはならない（URLの発見には使わない）が、 フィルタリングには使用する（既に収録済みのURLを除外するため）。

既知URLセット = repositories.txt の全URL + repositories-ignore.txt の全URL

repositories-ignore.txt は次の形式を許容する:

<URL> # <reason>

この場合、比較や除外判定に使うのは # より前のURL部分だけとする。# 以降は人間向けの除外理由メモであり、URLの一部として扱わない。

注意: vrc-getのrepositories.txt（https://vrc-get.anatawa12.com/ 等）や、他のVPMキュレーションサイト（例: https://remuria.natsuneko.com/）は情報源にしてはならない。これらは他者が収集・整理したリストであり、ここから転用することはオリジナルの発見にならない。

---

Step 2: GitHub APIによる検索（主要手段）

GitHub Search UIではなく GitHub Search API を使う。ブラウザ不要で安定しており、日付フィルタも正確に機能する。 YYYY-MM-DD は実行日から1か月前の日付に置き換える。

重要: ここでの「直近1か月」は検索範囲を絞るための条件であり、報告対象の repository created_at を直近1か月に限定する意味ではない。過去に作成されたリポジトリでも、直近1か月の更新・公開・告知によって今回初めて発見できた未収録URLであれば報告する。

以下の複数クエリを 並列で web_fetch して候補を収集する：

https://api.github.com/search/repositories?q=vpm+vrchat+pushed%3A>YYYY-MM-DD&sort=updated&order=desc&per_page=30
https://api.github.com/search/repositories?q=vpm+package+listing+vrchat+pushed%3A>YYYY-MM-DD&sort=updated&order=desc&per_page=30
https://api.github.com/search/repositories?q=vpm-listing+vrchat+pushed%3A>YYYY-MM-DD&sort=updated&order=desc&per_page=30
https://api.github.com/search/repositories?q=VCC+listing+vrchat+pushed%3A>YYYY-MM-DD&sort=updated&order=desc&per_page=30

レスポンスJSONの items 配列から以下の条件でGitHub Pages URLを絞り込む：

• has_pages: true — GitHub PagesでVPM JSONを配信している可能性が高い
• fork: false — フォークは除外
• 対象外: vpm-catalogリポジトリ自身（kurotu/vpm-catalog）、vrc-get等のツール系リポジトリ

GitHubPagesのURLは https://<owner>.github.io/<repo>/index.json が標準。 homepage フィールドにカスタムドメインが入っている場合はそちらも候補にする。

ページネーション: total_count > 30 の場合は &page=2 で続きを取得すること。

---

Step 3: 補完検索（playwright-cli）

GitHub APIで見つからない可能性のある情報源として、Yahoo Japan リアルタイムとGoogleも確認する。

playwright-cli が利用可能かどうかの確認

playwright-cliを起動する前に、Chromiumがインストールされているか確認する。 失敗した場合は先にインストールする：

playwright-cli install-browser chromium

3-1: Yahoo Japan リアルタイム検索

まずは次のクエリを優先して試す:

1. VPM リポジトリ
2. VPMリポジトリ
3. VPM リポジトリ VRChat
4. VCC 追加
5. booth VCC 追加
6. booth VRChat VPM
7. VCC 入れる
8. VCC booth
9. ALCOM 追加
10. ALCOM リポジトリ
11. ALCOM booth

VPM リポジトリ は実際の告知ポストに当たりやすく、VPMリポジトリ VRChat や index.json VRChat VPM のように語を増やしすぎると「一致する情報は見つかりませんでした」になりやすい。 また、VPMインストール方法の表現は「追加」だけでなく「入れる」「入れられる」も多用されるため、VCC 入れる と VCC booth で補完する。 さらに、ALCOMはVCCの後継ツールとして普及が進んでいるため、VCCに言及しない告知ポストを捕捉するために ALCOM 系クエリも追加する。

playwright-cli open "https://search.yahoo.co.jp/realtime/search?p=VPM%20%E3%83%AA%E3%83%9D%E3%82%B8%E3%83%88%E3%83%AA&ei=UTF-8"
playwright-cli snapshot

リアルタイム検索はXポスト等が対象。VPMリポジトリURLや index.json / vpm.json を含む投稿を探す。

• ページ本文に 一致する情報は見つかりませんでした が含まれる場合、そのクエリは不発と判断する
• 表示上は ... で省略されることがあるため、必要に応じてリンク一覧を取得する
• t.co など短縮URLは、必ずリダイレクト先を展開してから候補URLとして扱う
• Yahooで見つかったURLが HTML ページやディレクトリURL（例: https://example.github.io/repo/ や https://example.github.io/vpm/）だった場合、そのまま報告せず Step 4 の正規化を行う

Bot検出やJavaScriptエラーが発生した場合はスキップして次に進む。

3-2: Google 検索

Googleはヘッドレスブラウザを頻繁にブロックするため、web_fetch を先に試みる：

https://www.google.com/search?q=VRChat+vpm+index.json+site%3Agithub.io&tbs=qdr%3Am

取得できなかった場合（JavaScript必須で空の結果）はスキップする。 playwright-cliでも同様にBotブロックされることが多いため、無理に試みない。

---

3-3: Booth経由のVPMリポジトリ探索

BoothでVPM対応ツールを配布する作者の中には、VPMリポジトリURLをPDFマニュアルのみに記載するケースがある。 こうしたリポジトリを捕捉するために、Step 3-1 で見つかったBoothページURLを精査し、GitHubリポジトリへの経路を辿る。

Boothページが見つかったときの精査手順

Boothページ（*.booth.pm/items/*）のURLが検索結果に含まれていたら、まず BoothショップのサブドメインからGitHubユーザーを直接確認する。これはBoothページを取得する前に行う。

0. BoothショップのサブドメインからGitHubリポジトリを直接確認（必須）

xxx.booth.pm/items/* の xxx 部分をGitHubユーザー名として、必ず次のAPIを確認する：

https://api.github.com/users/xxx/repos?type=public&per_page=100&sort=updated

• ユーザーが存在しない場合（404）はこの経路をスキップして次のチェックへ進む。
• レスポンスの Link ヘッダに rel="next" が含まれる場合は、page=2, page=3 … と順にフェッチして全リポジトリを取得する。
• fork: false な公開リポジトリは has_pages で絞り込まず VPM候補として Step 4 に送る。 has_pages: true は GitHub Pages URL 推定の優先材料にはなるが必須条件ではない。raw.githubusercontent.com/.../index.json や .../vpm.json のような Pagesを使わないJSON配布 もあるため、Step 4 のURL正規化・web_fetch 検証で判定する。

これはBoothページにVPM URLが記載されていない場合でも有効な経路であり、スキップしてはならない。

その後、web_fetch でBoothページを取得し、以下を追加チェックする。

A. GitHub Pages URL（直接発見）

*.github.io 形式のURLがページ内にあれば Step 4 の正規化候補として追加する。

B. GitHubユーザー／リポジトリリンク（github.com/<user>）

見つかった場合は次のAPIでそのユーザーのリポジトリ一覧を確認する：

https://api.github.com/users/<user>/repos?type=public&per_page=100&sort=updated

• ユーザーが存在しない場合（404）はこの経路をスキップする。
• ページングが必要な場合は page=2, page=3 … と順にフェッチする。
• fork: false な公開リポジトリは has_pages で絞り込まず VPM候補として Step 4 に送る。

C. Xハンドル（x.com/<handle> や twitter.com/<handle>）

Boothページに掲載されているXリンクをもとに、Yahoo Japanリアルタイムで再検索する：

• @<handle> VCC
• @<handle> VPM

作者がVPMリポジトリURLを含む告知ポストをしていれば発見できる。

D. GitHubリンクが見つからない場合のフォールバック

BoothショップのサブドメインとGitHubユーザー名が完全一致しないケースがある （例: tsukumodo-lab.booth.pm → GitHub: tsukumodo）。 サブドメインから -lab / -dev / -studio などのサフィックスを除いた名前でも api.github.com/users/<name>/repos を試みる。 404なら無視してよい。

注意: サブドメインがそのままGitHubユーザー名と一致するケース（例: yoridrill.booth.pm → yoridrill）は上記の手順0で既にカバーされる。手順0でリポジトリが見つからなかった場合のみ、このフォールバックを試みること。

---

Step 4: VPMリポジトリURLのパターン認識

VPMリポジトリのURLは以下のようなパターンを持つことが多い：

https://<user>.github.io/<repo>/index.json
https://<user>.github.io/<repo>/vpm.json
https://<user>.github.io/<repo>/
https://<user>.github.io/vpm/
https://vpm.<domain>/index.json
https://vpm.<domain>/vpm.json
https://<custom-domain>/
https://raw.githubusercontent.com/<user>/<repo>/main/index.json
https://<custom-domain>/index.json

ただし、報告対象は JSON を直接返すURLだけとする。 HTMLページやディレクトリURLを見つけた場合は、まず次のようにJSON候補へ正規化する:

1. 末尾が / の場合は index.json を付けた候補を試す
2. index.json が404なら vpm.json も試す
3. カスタムドメインのルートURLも同様に index.json / vpm.json を試す

例:

• https://rassi0429.github.io/KokoaVPMRepository/ → https://rassi0429.github.io/KokoaVPMRepository/index.json
• https://sizimityper.github.io/vpm/ → https://sizimityper.github.io/vpm/index.json

URLを収集したら、正規化後のURLに実際にアクセスしてVPMリポジトリであることを確認する（Step 5）。

---

Step 5: URL検証

候補URLそれぞれに対して web_fetch でアクセスし、以下の条件を確認する。 playwright-cliでの検証より web_fetch の方が高速で安定しているため、こちらを優先する。

1. HTTPステータスが200（404などはそのURLを除外）
2. JSONとして解析可能
3. 以下のいずれかのフィールドを含む：
   • packages オブジェクト（VPMリポジトリの必須フィールド）
   • name + id + url
4. JSON内の url フィールドと、実際にフェッチしたURLを比較する（比較時の正規化はスキーム・ホストの大文字小文字と末尾スラッシュに限定し、パスは変更しない）
   • VPMリポジトリのJSONは自分自身の正規URLを url フィールドに自己申告していることが多い。これがフェッチ元URLと食い違う場合、フェッチ元は別ドメインへのミラー/エイリアス（GitHub Pagesのデフォルトドメインとカスタムドメインの両方が生きているケースなど）である可能性が高い
   • .url が既知URLセット（Step 1）に既に含まれていれば、フェッチ元URLは同一リポジトリの重複として除外する
   • .url が既知セットに含まれていなければ、.url 自体にも web_fetch してみる。200でJSONが返り id が一致すれば、そちらを正規URLとして報告する（見つけた側のURLではなく）
   • .url へのアクセスが失敗する（404・タイムアウト等）、または200でも id が一致しない（テンプレート流用などで url フィールドが書き換えられていない）場合は、そちらの .url は信用せず、実際に機能しているフェッチ元URLをそのまま報告する
   • url フィールド自体が存在しない場合はこのチェックをスキップする（食い違いとして扱わない）

例: https://cympfh.github.io/vpm/index.json を発見したが、中身の url フィールドは https://cympfh.cc/vpm/index.json だった。cympfh.cc/vpm/index.json は既に収録済みだったため、このgithub.io URLは同一リポジトリのミラーと判断し報告しなかった。同様のパターンはカスタムドメインを持つ作者（vpm.<domain> 系、独自ドメイン系）で頻発する。

追加ルール:

• 元の候補URLがHTMLページや短縮URLだった場合、最終的に200でJSONを返したURLだけを報告URLとして採用する
• ルートURL自体が有効でも、レスポンスがHTMLなら報告対象にしない
• index.json と vpm.json の両方が有効な場合は、JSONの url フィールドと一致する方を優先する
• Yahoo経由で見つけたURLも、報告前に必ず web_fetch でJSONレスポンスを確認する

複数の候補URLは 並列で web_fetch して効率よく確認する。

---

Step 6: フィルタリング

Step 1で収集した既知URLセットと照合し、既に収録済みのURLは除外する。

• URLの末尾スラッシュの有無、大文字小文字の違いは正規化して比較すること
• 拾ったHTML URLは、JSON URLに正規化してから既知URLセットと比較すること
• repositories-ignore.txt に含まれるURLも除外すること（形式は Step 1 参照）
• さらに、別の集約的リポジトリで実質的にカバー済みの個別リポジトリは冗長候補として除外すること
• URL文字列が既知セットと一致しなくても、Step 5-4 の .url チェックで既知の収録済みリポジトリと同一だと判明した場合は同一リポジトリのミラーとして除外すること。既知リポジトリの id を事前に網羅的に収集する必要はなく、候補の .url を辿った先が既知URLと一致するかどうかで判定すればよい

---

Step 7: 代表パッケージの取得と集約度の評価

未収録URLが確定したら、各リポジトリJSONから情報を取得し、集約的かどうかを判定する。

集約的リポジトリ（優先報告）

packages オブジェクトに複数の異なるパッケージが含まれるリポジトリは「集約的VPMリポジトリ」として優先して報告する。 これは、ある作者が自分の複数ツールをまとめて配布しているケースであり、ユーザーにとって価値が高い。

例: packages に com.author.tool-a, com.author.tool-b, com.author.tool-c が含まれる場合 → 集約的

単一パッケージリポジトリ（後回し）

packages に1パッケージしかない場合は「単一パッケージリポジトリ」として後順で報告する。

集約リポジトリとの重複カバレッジ判定

単一パッケージリポジトリや小規模リポジトリを見つけた場合でも、そのパッケージが別の集約的リポジトリにすでに含まれているなら、原則としてその個別リポジトリは報告しない。

判定の目安:

1. パッケージIDが完全一致している
2. 別リポジトリ側が複数パッケージをまとめて配布している
3. 集約側のURLが既存収録済み、または同じ探索で同時に発見されている

例:

• https://sizimityper.github.io/reflector-shader/index.json の com.sizimityper.reflector-shader
• https://sizimityper.github.io/vpm/index.json に同じ com.sizimityper.reflector-shader が含まれる
• この場合は後者を優先し、前者は冗長として除外する
• 除外を再判定しなくて済むよう、https://sizimityper.github.io/reflector-shader/index.json # covered by https://sizimityper.github.io/vpm/index.json のように理由付きで報告に記録してよい（スキル実行中に repositories-ignore.txt は更新しない）

これは「有効なJSON URLかどうか」ではなく、カタログとして追加価値があるかで判断するためのルールである。

同一作者の既存収録リポジトリとの重複確認

候補リポジトリのGitHubオーナーが、repositories.txt に別のリポジトリ名で既に収録されている場合（例: club-maul.github.io/vpm-listing は収録済みだが、新たに見つけた Club-Maul.github.io/staff-scanner-v2 は未収録）、その既存リポジトリのJSONを取得し、候補の packages とパッケージIDが重複していないか確認する。

• パッケージIDが完全一致し、かつ既存リポジトリ側のバージョン数が同等以上なら、候補は「既存リポジトリでカバー済み」と判断して報告しない
• これは同じ作者が単発ツール用に個別リポジトリを切っただけで、既にメインのまとめリポジトリに同じパッケージを追加済み、というケースで起きやすい
• <候補URL> # covered by <既存URL> の形式で理由付きの除外情報を報告に記録してよい（スキル実行中に repositories-ignore.txt は更新しない。Step 8参照）

テンプレート・開発専用ダミーの除外

JSONが正常に取得でき、packages も存在するのに実際にはVRChat制作に使えないリポジトリがある。これらはVPMクライアントには読み込めても、カタログの利用者にとって価値がないため報告しない。

• VRChat公式サンプルテンプレートの未改変フォーク: vrchat-community/template-package や vrchat-community/template-package-listing を単にフォーク・公開しただけで中身を差し替えていないもの。id が com.vrchat.demo-template.listing / com.vrchat.example-listing である、または displayName が "VRChat Example Package" 、description が "Simple Package for testing Automation" など、テンプレート特有の文言であれば該当する
• 開発者専用・テスト用ダミー: リポジトリ名や name フィールドに "DEVELOPER ONLY" 等が明記されている、またはパッケージIDが *upm-test-* のようなテストフィクスチャで占められている場合、一般ユーザー向けの配布物ではないため除外する

判断に迷う場合は、代表パッケージの description / displayName / author を確認し、実際にVRChatアバター/ワールド制作に使える内容かどうかを基準にする。

代表パッケージの選択（単一の場合も含む）

報告用の代表パッケージを1つ選ぶ際の優先順位：

1. keywords や description が充実しているもの
2. バージョン数が多い（活発に開発されている）もの
3. パッケージ名がわかりやすいもの

---

Step 8: 結果報告

以下のフォーマットで報告する。集約的リポジトリを先に、単一パッケージリポジトリを後に並べること。

## 新規発見VPMリポジトリ

### 1. <リポジトリ名>（集約: N パッケージ）   ← 集約的な場合はパッケージ数を明記
**URL**: `<vpm-repository-url>`
**発見元**: GitHub API / Yahoo Japan リアルタイム / Google
**収録パッケージ**: `<pkg-a>`, `<pkg-b>`, ... （集約的の場合は全パッケージIDを列挙）
**代表パッケージ**: `<package-id>`
**概要**: <パッケージ群の機能・用途を2〜3文で説明。集約的な場合はまとめて説明する>

---

### 2. <リポジトリ名>
**URL**: `<vpm-repository-url>`
**発見元**: GitHub API
**代表パッケージ**: `<package-id>`
**概要**: <パッケージの機能・用途を2〜3文で説明>

---

未収録URLが見つからなかった場合は、その旨を報告する。

報告時の追加ルール:

• 必要なら説明文で「最近発見できたが repo 自体は以前から存在する」と補足してよい
• ただし、集約的リポジトリに収録済みの個別リポジトリは冗長なので報告しない
• 冗長・不要と判断したURLは repositories-ignore.txt 用に理由付きで報告してよい（形式は Step 1 参照。実ファイルの更新は行わない）

---

注意事項

• 検索のみが目的。収集したURLを repositories.txt に追加するなど、ファイルの変更は行わない
• 他のキュレーションサイトを情報源にしない: https://remuria.natsuneko.com/ などの第三者キュレーションサイトは情報源として使用しない。これらのサイトは独自のキュレーション活動の成果物であり、そこからURLを転用することはオリジナルの発見にならない
• GitHub APIはレート制限（未認証: 10req/min）があるため、リクエスト間隔に注意する
• playwright-cliセッションは作業終了後に playwright-cli close で必ず閉じる
• GoogleやYahooでBot検出（CAPTCHA等）が発生した場合はスキップして他の検索手段を使う
• 同じドメインの別パス（例: vpm.example.com/a.json と vpm.example.com/b.json）は別リポジトリとして扱う
• vrc-get（vrc-get/vrc-get）などVPMクライアントツール自体はリポジトリではないので除外する
• GitHub Pagesのデフォルトドメイン（<user>.github.io/...）とカスタムドメインの両方が生きている作者は多い。JSON内の id と url フィールドはリポジトリの同一性判定・優先URL判定の一番強い根拠になるので、URL文字列の見た目が違っても必ず確認する（Step 5-4, Step 6参照）