Facettes de texte enrichi Bluesky : octets, mentions, liens et tags
Les facettes Bluesky : positions en octets UTF-8, caractères et graphèmes, le lexique des facettes, des exemples et les bugs fréquents en JavaScript et Python.
Octets, caractères et graphèmes
Le texte d’un post est une seule chaîne. Les mentions, liens et hashtags n’y sont pas balisés : ce sont des facettes, une liste à côté du texte, dont chacune dit « ces octets du texte sont une mention de ce DID, un lien vers cette adresse ou ce tag ». Les positions comptent les octets de l’encodage UTF-8, pas les caractères.
Trois façons de compter le même texte divergent dès qu’il sort de l’ASCII :
| Texte | Octets UTF-8 | Unités UTF-16 (.length en JavaScript) | Points de code (len() en Python) | Graphèmes |
|---|---|---|---|---|
a | 1 | 1 | 1 | 1 |
é | 2 | 1 | 1 | 1 |
☕ | 3 | 1 | 1 | 1 |
👋 | 4 | 2 | 1 | 1 |
👨👩👧👦 | 25 | 11 | 7 | 1 |
Les facettes utilisent la première colonne. La limite de longueur d’un post utilise la dernière (300 graphèmes) et la première (3 000 octets) : voir Comment Bluesky compte la longueur d’un post.
Le lexique des facettes
Une facette est un objet app.bsky.richtext.facet : un index avec
byteStart (inclus) et byteEnd (exclu), et des features, en général une
seule :
app.bsky.richtext.facet#mentionavecdid: le DID du compte, jamais son handle ;app.bsky.richtext.facet#linkavecuri: une adresse complète, schéma compris ;app.bsky.richtext.facet#tagavectag: le tag sans#, au plus 64 graphèmes et 640 octets.
Les plages doivent rester dans le texte, commencer et finir sur des limites de
caractères, et ne devraient pas se chevaucher. Les trier par byteStart
n’est pas obligatoire, mais les lecteurs s’y attendent.
Un exemple détaillé
Le texte Café ☕ with @bsky.app: https://atproto.com #atproto fait 51
unités UTF-16, mais 54 octets : é prend 2 octets et ☕ 3. Donc
@bsky.app commence à l’octet 15, et non à l’index 12 :
[
{
"$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" }]
}
]Comment Bluesky détecte les facettes
Le générateur suit les règles de @atproto/api
(packages/api/src/rich-text/detection.ts dans bluesky-social/atproto), et
un test compare les deux sur des textes piégeux :
- Les liens commencent par
http://ouhttps://, ou ressemblent à un domaine sur un domaine de premier niveau connu (bsky.app/profile/xdevienthttps://bsky.app/profile/x;index.jsreste du texte). Un.,,,;,:,!ou?final est exclu, de même qu’une)finale sans parenthèse ouvrante. - Les mentions sont un
@suivi d’un handle sur un domaine de premier niveau connu, après une espace, une(ou le début du texte. Il leur faut leur DID. - Les hashtags commencent par
#ou par le#pleine chasse, ne sont pas faits que de chiffres, perdent leur ponctuation finale et s’arrêtent à 64 graphèmes. Un cashtag comme$BTCdevient le tag$BTC.
Bugs fréquents
- Compter en UTF-16.
indexOfet.lengthen JavaScript donnent des positions UTF-16. Encodez d’abord :
const encoder = new TextEncoder();
const byteStart = encoder.encode(text.slice(0, start)).length;
const byteEnd = byteStart + encoder.encode(text.slice(start, end)).length;- Compter des points de code.
len()et les index de chaînes en Python comptent des points de code. Comptez les octets encodés :
byte_start = len(text[:start].encode("utf-8"))
byte_end = byte_start + len(text[start:end].encode("utf-8"))- Un handle dans une mention. La fonctionnalité attend un DID : résolvez
d’abord le handle avec
com.atproto.identity.resolveHandle. - Aucune facette. Un post créé par l’API n’a aucune détection
automatique : sans facettes, liens et hashtags restent du texte brut. Avec
@atproto/api,RichText.detectFacets(agent)les construit pour vous ; voir Créer un bot en TypeScript et Créer un bot en Python.
L’utiliser depuis du code
Le générateur est aussi une route d’API gratuite et un outil MCP,
build_post_facets :
curl -G "https://bluesky.bot/api/v1/tools/facet-builder" \
--data-urlencode "text=Hello @bsky.app! #atproto"Un appel compte pour 1 dans les limites, plus 1 par tranche de 3 mentions non résolues dans la dernière minute. Une adresse GET contient environ 8 Ko une fois encodée, et un caractère non ASCII y prend jusqu’à 12 octets : envoyez un texte long ou non latin par MCP, dont la requête est un corps POST. Voir API des outils et serveur MCP.