ツールのドキュメント

Bluesky のカスタムフィードの仕組みとデバッグ方法

Bluesky のカスタムフィードの構成要素(ジェネレーターのレコード、サービス DID、#bsky_fg サービス、スケルトンと完成したフィード)と、各ヘルスチェックの直し方を説明します。

カスタムフィードの構成要素

カスタムフィードは、別々の場所にある 2 つの部分でできています。

  • レコード(app.bsky.feed.generator):作成者のアカウントにあり、名前、説明、アバター、そしてフィードを配信するフィードジェネレーターを指す did フィールドを持ちます。アドレスはフィードの AT URI at://<作成者>/app.bsky.feed.generator/<rkey>、bsky.app のリンクは https://bsky.app/profile/<作成者>/feed/<rkey> です。
  • フィードジェネレーター:その DID(did:web または did:plc)で識別されるサーバーです。DID ドキュメントには id が #bsky_fg、type が BskyFeedGenerator のサービスがあり、その serviceEndpoint がサーバーの https アドレスです。

1 つのジェネレーターが、それぞれのレコードを持つ複数のフィードを配信できます。

スケルトンと完成したフィード

フィードを開くと、アプリは Bluesky の AppView に app.bsky.feed.getFeed を問い合わせます。AppView はレコードを読み、ジェネレーターの DID を解決し、#bsky_fg のエンドポイントを見つけて、そこで app.bsky.feed.getFeedSkeleton を呼び出します。ジェネレーターはスケルトン、つまり投稿の URI の一覧だけを返します。

json
{
  "feed": [
    { "post": "at://did:plc:abc/app.bsky.feed.post/3l2k7yqzx2c2a" }
  ],
  "cursor": "1731567000000"
}

AppView はそれを完成させます。各投稿、作者、数値を取得し、ブロック、ミュート、ラベルを適用して、完全な投稿を返します。閲覧者がログインしていない限り、ジェネレーターには誰がフィードを読んでいるか分かりません。ログインしている場合は、その人を示すトークンがリクエストに付きます。

AppView は各ジェネレーターの状態も追跡します。isOnline は最近接続できたこと、isValid は応答の形式が正しかったことを示します。フィードインスペクターは両方を表示します。

DID ドキュメント

did:web の場合、ドキュメントは https://<ホスト>/.well-known/did.json で配信されます。did:plc の場合は PLC ディレクトリが保持します。最小限の例:

json
{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:web:feed.example.com",
  "service": [
    {
      "id": "#bsky_fg",
      "type": "BskyFeedGenerator",
      "serviceEndpoint": "https://feed.example.com"
    }
  ]
}

ジェネレーターは app.bsky.feed.describeFeedGenerator にも、同じ DID と配信するすべてのフィードの AT URI で応答する必要があります。

ヘルスチェックの手順

インスペクターのヘルスチェックは求められたときだけ実行し、AppView と同じ経路をたどります。

  1. サービス DID:レコードの did は、ホスト名のみ(ポートやパスなし)の did:web か did:plc でなければなりません。そうでなければ、正しい DID でレコードを公開し直してください。
  2. #bsky_fg サービス:DID ドキュメントが存在し、id が DID と一致する正しい JSON で、https のエンドポイントを持つ type BskyFeedGenerator の #bsky_fg サービスがある必要があります。
  3. describeFeedGenerator:GET <エンドポイント>/xrpc/app.bsky.feed.describeFeedGenerator が、サービス DID と同じ did と feeds の一覧を含めて 200 で応答する必要があります。
  4. フィードが載っている:フィードの AT URI がその feeds 一覧にあるべきです。ない場合は注意になります。一覧に載せていないフィードを配信するジェネレーターもあります。
  5. getFeedSkeleton:GET <エンドポイント>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1 が feed 配列を含めて 200 で応答する必要があります。401 は、フィードがログインした閲覧者を必要とすることを意味します。アプリでは動作しますが、ログインしていない読者やインスペクターのプレビューでは表示されません。

各リクエストの上限は 4 秒・64 KB で、かかった時間を表示します。リクエストは安全チェックを通ります。ポート 443 の https のみで、プライベートやローカルのアドレスには決して送りません。そのため、家庭内ネットワーク上や localhost へのトンネルの背後にあるジェネレーターは、アプリが公開アドレス経由で接続できても、チェックに失敗します。

よくある直し方

  • オフラインだがサーバーは動いている:DID ドキュメントのエンドポイント(入力ミス、https:// ではなく http://、余分なパス)と、そのホストに対して証明書が有効かを確認してください。
  • 有効が false:スケルトンは { "post": "<at uri>" } の要素からなる feed 配列を持つオブジェクトでなければなりません。余分なフィールドは問題ありませんが、別の形式は不可です。
  • スケルトンは空でないのにプレビューが空:返された投稿が削除されている、ブロックや削除されたアカウントのものである、またはログインしている人にだけ公開している作者のものである可能性があります。
  • 動いていたのに止まった:ホストを移した did:web のジェネレーターは DID ドキュメントの更新が、did:plc のジェネレーターは PLC 操作が必要です。

AT Protocol のカスタムフィードのチュートリアルと Bluesky のスターターキットで作り方を学べます。Bluesky.bot はボットのフィードのために独自のジェネレーターを運用しており、その DID ドキュメントは /.well-known/did.json にあります。

フィードインスペクター

カスタムフィードをプレビューし、何も表示されない理由を調べます。