Facetas de texto rico do Bluesky: bytes, menções, ligações e tags
Como funcionam as facetas do Bluesky: posições em bytes UTF-8, caracteres e grafemas, o léxico das facetas, exemplos práticos e os erros comuns em JavaScript e Python.
Bytes, caracteres e grafemas
O texto de uma publicação é uma única cadeia. As menções, ligações e hashtags não estão marcadas lá dentro: são facetas, uma lista junto ao texto, e cada uma diz «estes bytes do texto são uma menção deste DID, uma ligação para este endereço ou este tag». As posições contam bytes da codificação UTF-8, não caracteres.
Três formas de contar o mesmo texto deixam de coincidir assim que sai do ASCII:
| Texto | Bytes UTF-8 | Unidades UTF-16 (.length do JavaScript) | Pontos de código (len() do Python) | Grafemas |
|---|---|---|---|---|
a | 1 | 1 | 1 | 1 |
é | 2 | 1 | 1 | 1 |
☕ | 3 | 1 | 1 | 1 |
👋 | 4 | 2 | 1 | 1 |
👨👩👧👦 | 25 | 11 | 7 | 1 |
As facetas usam a primeira coluna. O limite de comprimento de uma publicação usa a última (300 grafemas) e a primeira (3000 bytes): consulte Como o Bluesky conta o comprimento de uma publicação.
O léxico das facetas
Uma faceta é um objeto app.bsky.richtext.facet: um index com
byteStart (incluído) e byteEnd (excluído), e features, normalmente uma:
app.bsky.richtext.facet#mentioncomdid: o DID da conta, nunca o handle;app.bsky.richtext.facet#linkcomuri: um endereço completo, com esquema;app.bsky.richtext.facet#tagcomtag: o tag sem#, no máximo 64 grafemas e 640 bytes.
Os intervalos têm de ficar dentro do texto, começar e acabar em limites de
caracteres, e não se devem sobrepor. Ordená-los por byteStart não é
obrigatório, mas os leitores esperam-no.
Um exemplo prático
O texto Café ☕ with @bsky.app: https://atproto.com #atproto tem 51
unidades UTF-16, mas 54 bytes: é ocupa 2 bytes e ☕ 3. Por isso
@bsky.app começa no byte 15, e não no í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" }]
}
]Como o Bluesky deteta as facetas
O gerador segue as regras do @atproto/api
(packages/api/src/rich-text/detection.ts em bluesky-social/atproto), e um
teste compara os dois com textos difíceis:
- As ligações começam por
http://ouhttps://, ou parecem um domínio com um domínio de topo conhecido (bsky.app/profile/xpassa ahttps://bsky.app/profile/x;index.jsfica como texto). Um.,,,;,:,!ou?final fica de fora, tal como um)final sem parêntese de abertura. - As menções são um
@seguido de um handle com um domínio de topo conhecido, depois de um espaço, de um(ou no início do texto. Precisam do DID. - Os hashtags começam por
#ou pelo#de largura total, não são só algarismos, perdem a pontuação final e param aos 64 grafemas. Um cashtag como$BTCpassa a ser o tag$BTC.
Erros comuns
- Contar em UTF-16.
indexOfe.lengthdo JavaScript dão posições UTF-16. Codifique primeiro:
const encoder = new TextEncoder();
const byteStart = encoder.encode(text.slice(0, start)).length;
const byteEnd = byteStart + encoder.encode(text.slice(start, end)).length;- Contar pontos de código.
len()e os índices de cadeias do Python contam pontos de código. Conte os bytes codificados:
byte_start = len(text[:start].encode("utf-8"))
byte_end = byte_start + len(text[start:end].encode("utf-8"))- Um handle numa menção. A funcionalidade espera um DID: resolva primeiro
o handle com
com.atproto.identity.resolveHandle. - Nenhuma faceta. Uma publicação criada pela API não tem deteção
automática: sem facetas, as ligações e os hashtags são texto simples. Com o
@atproto/api,RichText.detectFacets(agent)constrói-as por si; consulte Criar um bot em TypeScript e Criar um bot em Python.
Usar a partir de código
O gerador é também uma rota de API gratuita e uma ferramenta MCP,
build_post_facets:
curl -G "https://bluesky.bot/api/v1/tools/facet-builder" \
--data-urlencode "text=Hello @bsky.app! #atproto"Uma chamada conta 1 nos limites, mais 1 por cada 3 menções não resolvidas no último minuto. Um endereço GET leva cerca de 8 KB depois de codificado, e um carácter não ASCII ocupa lá até 12 bytes: envie textos longos ou não latinos pelo MCP, cujo pedido é um corpo POST. Consulte API das ferramentas e servidor MCP.