Documentación de la herramienta

Facetas de texto enriquecido en Bluesky: bytes, menciones, enlaces y tags

Cómo funcionan las facetas de Bluesky: bytes UTF-8, caracteres y grafemas, el léxico de las facetas, ejemplos y los errores habituales en JavaScript y Python.

Bytes, caracteres y grafemas

El texto de un post es una sola cadena. Las menciones, los enlaces y los hashtags no van marcados dentro: son facetas, una lista junto al texto, y cada una dice «estos bytes del texto son una mención de este DID, un enlace a esta dirección o este tag». Las posiciones cuentan bytes de la codificación UTF-8, no caracteres.

Tres formas de contar el mismo texto no coinciden en cuanto sale del ASCII:

TextoBytes UTF-8Unidades UTF-16 (.length de JavaScript)Puntos de código (len() de Python)Grafemas
a1111
é2111
☕3111
👋4211
👨‍👩‍👧‍👦251171

Las facetas usan la primera columna. El límite de longitud de un post usa la última (300 grafemas) y la primera (3000 bytes): consulta Cómo cuenta Bluesky la longitud de un post.

El léxico de las facetas

Una faceta es un objeto app.bsky.richtext.facet: un index con byteStart (incluido) y byteEnd (excluido), y features, normalmente una:

  • app.bsky.richtext.facet#mention con did: el DID de la cuenta, nunca su handle;
  • app.bsky.richtext.facet#link con uri: una dirección completa, con esquema;
  • app.bsky.richtext.facet#tag con tag: el tag sin #, como máximo 64 grafemas y 640 bytes.

Los rangos deben quedar dentro del texto, empezar y terminar en límites de caracteres y no deberían solaparse. Ordenarlos por byteStart no es obligatorio, pero los lectores lo esperan.

Un ejemplo paso a paso

El texto Café ☕ with @bsky.app: https://atproto.com #atproto tiene 51 unidades UTF-16, pero 54 bytes: é ocupa 2 bytes y ☕ 3. Así que @bsky.app empieza en el byte 15, no en el índice 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" }]
  }
]

Cómo detecta Bluesky las facetas

El generador sigue las reglas de @atproto/api (packages/api/src/rich-text/detection.ts en bluesky-social/atproto), y una prueba compara ambos con textos difíciles:

  • Los enlaces empiezan por http:// o https://, o parecen un dominio con un dominio de nivel superior conocido (bsky.app/profile/x pasa a https://bsky.app/profile/x; index.js se queda en texto). Un ., ,, ;, :, ! o ? final queda fuera, igual que un ) final sin paréntesis de apertura.
  • Las menciones son una @ seguida de un handle con un dominio de nivel superior conocido, tras un espacio, un ( o el inicio del texto. Necesitan su DID.
  • Los hashtags empiezan por # o por el # de ancho completo, no son solo cifras, pierden su puntuación final y se cortan a los 64 grafemas. Un cashtag como $BTC pasa a ser el tag $BTC.

Errores habituales

  • Contar en UTF-16. indexOf y .length de JavaScript dan posiciones UTF-16. Codifica primero:
ts
const encoder = new TextEncoder();
const byteStart = encoder.encode(text.slice(0, start)).length;
const byteEnd = byteStart + encoder.encode(text.slice(start, end)).length;
  • Contar puntos de código. len() y los índices de cadenas de Python cuentan puntos de código. Cuenta los bytes codificados:
python
byte_start = len(text[:start].encode("utf-8"))
byte_end = byte_start + len(text[start:end].encode("utf-8"))
  • Un handle en una mención. La característica espera un DID: resuelve antes el handle con com.atproto.identity.resolveHandle.
  • Ninguna faceta. Un post creado por la API no tiene detección automática: sin facetas, los enlaces y los hashtags son texto plano. Con @atproto/api, RichText.detectFacets(agent) las construye por ti; consulta Crea un bot en TypeScript y Crea un bot en Python.

Úsalo desde el código

El generador es también una ruta de API gratuita y una herramienta MCP, build_post_facets:

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

Una llamada cuenta 1 en los límites, más 1 por cada 3 menciones no resueltas en el último minuto. Una dirección GET admite unos 8 KB una vez codificada, y un carácter no ASCII ocupa ahí hasta 12 bytes: envía los textos largos o no latinos por MCP, cuya petición es un cuerpo POST. Consulta API de herramientas y servidor MCP.

Generador de facetas de texto enriquecido

Menciones, enlaces y hashtags con sus posiciones en bytes.