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:
| Texto | Bytes UTF-8 | Unidades UTF-16 (.length de JavaScript) | Puntos de código (len() de Python) | Grafemas |
|---|---|---|---|---|
a | 1 | 1 | 1 | 1 |
é | 2 | 1 | 1 | 1 |
☕ | 3 | 1 | 1 | 1 |
👋 | 4 | 2 | 1 | 1 |
👨👩👧👦 | 25 | 11 | 7 | 1 |
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#mentioncondid: el DID de la cuenta, nunca su handle;app.bsky.richtext.facet#linkconuri: una dirección completa, con esquema;app.bsky.richtext.facet#tagcontag: 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:
[
{
"$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://ohttps://, o parecen un dominio con un dominio de nivel superior conocido (bsky.app/profile/xpasa ahttps://bsky.app/profile/x;index.jsse 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$BTCpasa a ser el tag$BTC.
Errores habituales
- Contar en UTF-16.
indexOfy.lengthde JavaScript dan posiciones UTF-16. Codifica primero:
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:
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:
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.