ツールのドキュメント

Bluesky のリッチテキストファセット:バイト、メンション、リンク、タグ

Bluesky のファセットの仕組み:UTF-8 のバイト位置と文字・書記素の違い、ファセットのレキシコン、実例、JavaScript と Python でよくあるバグを解説します。

バイト、文字、書記素

投稿のテキストは 1 つの文字列です。メンション、リンク、ハッシュタグはその中に マークアップされているのではなく、ファセットとしてテキストの横に一覧で置かれます。 それぞれが「テキストのこのバイトは、この DID へのメンション、このアドレスへの リンク、またはこのタグ」と示します。位置は文字ではなく、UTF-8 エンコードの バイトで数えます。

同じテキストでも、ASCII 以外が入ると 3 つの数え方は一致しなくなります。

テキストUTF-8 バイトUTF-16 単位(JavaScript の .length)コードポイント(Python の len())書記素
a1111
é2111
☕3111
👋4211
👨‍👩‍👧‍👦251171

ファセットは最初の列を使います。投稿の長さの制限は最後の列(300 書記素)と 最初の列(3,000 バイト)を使います。 Bluesky は投稿の長さをどう数えるかをご覧ください。

ファセットのレキシコン

ファセットは app.bsky.richtext.facet オブジェクトです。byteStart(含む)と byteEnd(含まない)を持つ index と、通常 1 つの features からなります。

  • app.bsky.richtext.facet#mention と did:アカウントの DID(ハンドルではない)
  • app.bsky.richtext.facet#link と uri:スキームを含む完全なアドレス
  • app.bsky.richtext.facet#tag と tag:# を除いたタグ。最大 64 書記素、 640 バイト

範囲はテキストの内側に収まり、文字の境界で始まって終わる必要があり、重ならない ようにします。byteStart 順に並べるのは必須ではありませんが、読み手はそれを 想定しています。

実例

テキスト Café ☕ with @bsky.app: https://atproto.com #atproto は UTF-16 では 51 単位ですが、54 バイトです。é は 2 バイト、☕ は 3 バイトだからです。 そのため @bsky.app はインデックス 12 ではなく、バイト 15 から始まります。

json
[
  {
    "$type": "app.bsky.richtext.facet",
    "index": { "byteStart": 15, "byteEnd": 24 },
    "features": [
      {
        "$type": "app.bsky.richtext.facet#mention",
        "did": "did:plc:z72i7hdynmk6r22z27h6tvur"
      }
    ]
  },
  {
    "$type": "app.bsky.richtext.facet",
    "index": { "byteStart": 26, "byteEnd": 45 },
    "features": [
      { "$type": "app.bsky.richtext.facet#link", "uri": "https://atproto.com" }
    ]
  },
  {
    "$type": "app.bsky.richtext.facet",
    "index": { "byteStart": 46, "byteEnd": 54 },
    "features": [{ "$type": "app.bsky.richtext.facet#tag", "tag": "atproto" }]
  }
]

Bluesky がファセットを検出する方法

ビルダーは @atproto/api のルール(bluesky-social/atproto の packages/api/src/rich-text/detection.ts)に従い、テストで難しいテキストを 使って両者を比べています。

  • リンクは http:// か https:// で始まるもの、または既知のトップレベル ドメインを持つドメインに見えるものです(bsky.app/profile/x は https://bsky.app/profile/x になり、index.js はテキストのままです)。末尾の .、,、;、:、!、? と、開き括弧のない末尾の ) は除かれます。
  • メンションは、空白、(、またはテキストの先頭の後に続く @ と、既知の トップレベルドメインを持つハンドルです。DID が必要です。
  • ハッシュタグは # または全角の # で始まり、数字だけではなく、末尾の 句読点を除き、64 書記素で止まります。$BTC のようなキャッシュタグは タグ $BTC になります。

よくあるバグ

  • UTF-16 で数える。 JavaScript の indexOf と .length は UTF-16 の位置を 返します。先にエンコードしましょう。
ts
const encoder = new TextEncoder();
const byteStart = encoder.encode(text.slice(0, start)).length;
const byteEnd = byteStart + encoder.encode(text.slice(start, end)).length;
  • コードポイントで数える。 Python の len() と文字列のインデックスは コードポイントを数えます。エンコードしたバイトを数えましょう。
python
byte_start = len(text[:start].encode("utf-8"))
byte_end = byte_start + len(text[start:end].encode("utf-8"))
  • メンションにハンドルを入れる。 この機能には DID が必要です。先に com.atproto.identity.resolveHandle でハンドルを解決してください。
  • ファセットがない。 API で作成した投稿には自動検出がありません。 ファセットがなければ、リンクもハッシュタグもプレーンテキストです。 @atproto/api なら RichText.detectFacets(agent) が作ってくれます。 TypeScript でボットを作ると Python でボットを作るをご覧ください。

コードから使う

ビルダーは無料の API ルートであり、MCP ツール build_post_facets でもあります。

bash
curl -G "https://bluesky.bot/api/v1/tools/facet-builder" \
  --data-urlencode "text=Hello @bsky.app! #atproto"

1 回の呼び出しは制限に対して 1 回分、さらに直近 1 分間に解決されていない メンション 3 件ごとに 1 回分として数えられます。GET のアドレスはエンコード後で 約 8 KB までで、ASCII 以外の文字はそこで最大 12 バイトになります。長いテキストや ラテン文字以外のテキストは、リクエストが POST の本文になる MCP で送ってください。 ツール API と MCP サーバーをご覧ください。

リッチテキストのファセットビルダー

メンション、リンク、ハッシュタグをバイト位置つきで。