Documentação da ferramenta

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:

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

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#mention com did: o DID da conta, nunca o handle;
  • app.bsky.richtext.facet#link com uri: um endereço completo, com esquema;
  • app.bsky.richtext.facet#tag com tag: 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:

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

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:// ou https://, ou parecem um domínio com um domínio de topo conhecido (bsky.app/profile/x passa a https://bsky.app/profile/x; index.js fica 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 $BTC passa a ser o tag $BTC.

Erros comuns

  • Contar em UTF-16. indexOf e .length do JavaScript dão posições UTF-16. Codifique primeiro:
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 pontos de código. len() e os índices de cadeias do Python contam pontos de código. Conte os bytes codificados:
python
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:

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

Gerador de facetas de texto rico

Menções, ligações e hashtags com as posições em bytes.