Documentation de l’outil

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 :

TexteOctets UTF-8Unités UTF-16 (.length en JavaScript)Points de code (len() en Python)Graphèmes
a1111
é2111
☕3111
👋4211
👨‍👩‍👧‍👦251171

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#mention avec did : le DID du compte, jamais son handle ;
  • app.bsky.richtext.facet#link avec uri : une adresse complète, schéma compris ;
  • app.bsky.richtext.facet#tag avec tag : 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 :

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" }]
  }
]

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:// ou https://, ou ressemblent à un domaine sur un domaine de premier niveau connu (bsky.app/profile/x devient https://bsky.app/profile/x ; index.js reste 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 $BTC devient le tag $BTC.

Bugs fréquents

  • Compter en UTF-16. indexOf et .length en JavaScript donnent des positions UTF-16. Encodez d’abord :
ts
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 :
python
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 :

bash
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.

Générateur de facettes de texte enrichi

Mentions, liens et hashtags avec leurs positions en octets.