Bluesky のリッチテキストファセット:バイト、メンション、リンク、タグ
Bluesky のファセットの仕組み:UTF-8 のバイト位置と文字・書記素の違い、ファセットのレキシコン、実例、JavaScript と Python でよくあるバグを解説します。
バイト、文字、書記素
投稿のテキストは 1 つの文字列です。メンション、リンク、ハッシュタグはその中に マークアップされているのではなく、ファセットとしてテキストの横に一覧で置かれます。 それぞれが「テキストのこのバイトは、この DID へのメンション、このアドレスへの リンク、またはこのタグ」と示します。位置は文字ではなく、UTF-8 エンコードの バイトで数えます。
同じテキストでも、ASCII 以外が入ると 3 つの数え方は一致しなくなります。
| テキスト | UTF-8 バイト | UTF-16 単位(JavaScript の .length) | コードポイント(Python の len()) | 書記素 |
|---|---|---|---|---|
a | 1 | 1 | 1 | 1 |
é | 2 | 1 | 1 | 1 |
☕ | 3 | 1 | 1 | 1 |
👋 | 4 | 2 | 1 | 1 |
👨👩👧👦 | 25 | 11 | 7 | 1 |
ファセットは最初の列を使います。投稿の長さの制限は最後の列(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 から始まります。
[
{
"$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 の位置を 返します。先にエンコードしましょう。
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()と文字列のインデックスは コードポイントを数えます。エンコードしたバイトを数えましょう。
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 でもあります。
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 サーバーをご覧ください。