TL;DR, szybka odpowiedź
9 min czytaniaFacet to jeden wpis w tablicy facets rekordu app.bsky.feed.post. Ma indeks, czyli byteSlice złożony z byteStart i byteEnd, oraz tablicę features z adresem uri linku, identyfikatorem did wzmianki albo tekstem tagu. Przesunięcia liczą bajty tekstu zakodowanego w UTF-8, z początkiem włącznie i końcem wyłącznie. Sam leksykon ostrzega, że języki takie jak JavaScript indeksują tekst w UTF-16, więc indexOf zwraca złą liczbę, gdy tylko w tekście pojawi się akcent lub emoji, a powstały post nadal jest zgodny ze schematem.
Czym są facety Bluesky i co mierzą byteStart i byteEnd?
Bluesky przechowuje tekst posta jako zwykły ciąg znaków, bez znaczników i bez automatycznego wykrywania linków, więc przesunięcia byteStart i byteEnd w facetach to jedyna informacja, która mówi klientowi, który fragment tego ciągu jest linkiem, wzmianką lub hashtagiem. Leksykon app.bsky.richtext.facet nazywa facet "Annotation of a sub-string within rich text." Każdy facet wymaga dwóch pól: index, czyli #byteSlice, oraz features, tablicy adnotacji odnoszących się do tego wycinka.
Oto struktura, prosto z definicji w leksykonie:
{
"index": { "byteStart": 17, "byteEnd": 36 },
"features": [{ "$type": "app.bsky.richtext.facet#link", "uri": "https://example.com" }]
}Definicja byteSlice określa jednocześnie sposób liczenia i granice: "Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text."
| Pole | Typ | Ograniczenie w leksykonie | Znaczenie |
|---|---|---|---|
index.byteStart | integer | minimum: 0 | Pierwszy bajt opisywanego zakresu, włącznie |
index.byteEnd | integer | minimum: 0 | Bajt po ostatnim opisywanym bajcie, wyłącznie |
features | array | unia #mention, #link, #tag | Jedna lub więcej adnotacji dla tego zakresu bajtów |
Przeczytaj jeszcze raz kolumnę z ograniczeniami. minimum: 0 to jedyna reguła liczbowa dla obu przesunięć. Nie ma górnej granicy powiązanej z długością tekstu, nie ma reguły, że byteEnd musi być większe od byteStart, ani reguły, że zakres ma trafiać w granicę znaku. Dlatego błędne przesunięcia nie powodują żadnego błędu.
Dlaczego mój link na Bluesky publikuje się jako zwykły tekst?
Link wyświetla się jako zwykły tekst, bo rekord posta nie zawiera facetu, którego zakres bajtów obejmuje ten adres URL. Sam URL w polu text niczego nie robi. Klienci Bluesky nie szukają w tekście posta ciągu http://, tylko czytają tablicę facets i opisują dokładnie te zakresy bajtów, które są w niej wskazane.
Błąd jest cichy w obie strony. Pomiń facet, a dostaniesz zwykły tekst. Wyślij facet z przesunięciami źle policzonymi o trzy, a klient posłusznie podlinkuje bajty, które wskazujesz, być może końcówkę poprzedniego słowa i większość adresu. W obu przypadkach com.atproto.repo.createRecord zwraca zwykłą odpowiedź o sukcesie, bo rekord z błędnymi przesunięciami nadal jest zgodny ze schematem.
Leksykon nie definiuje kilku zachowań i tę lukę warto nazwać wprost, zamiast zgadywać. app.bsky.richtext.facet nie określa, co ma zrobić renderer, gdy zakres bajtów wychodzi poza koniec tekstu, gdy dwa facety się nakładają albo gdy zakres przecina na pół znak wielobajtowy. Nie ustala też maxLength dla tablicy facets w app.bsky.feed.post, podczas gdy sąsiednia tablica tags w tym samym rekordzie ma wyraźny limit maxLength: 8. Limit tagów jest udokumentowany, a limit facetów, jeśli w praktyce istnieje, już nie.

Dlaczego JavaScript podaje zły byteStart?
JavaScript podaje zły byteStart, bo String.prototype.indexOf i String.prototype.length liczą jednostki kodowe UTF-16, a facety liczą bajty UTF-8. Leksykon mówi o tym w uwadze, której większość ludzi nigdy nie czyta, bo znajduje się w pliku JSON, a nie w poradniku:
NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.
W czystym tekście ASCII oba systemy dają ten sam wynik i właśnie dlatego ten błąd trafia na produkcję. Testujesz na Opening hours https://example.com, wszystkie przesunięcia się zgadzają i kod idzie dalej. Potem w poście pojawia się słowo z akcentem albo emoji i przesunięcia się rozjeżdżają.
Weźmy taki ciąg znaków:
Café 🥐 hours https://example.comTrzy systemy liczenia dają dla niego różne wyniki:
| Jednostka liczenia | Wartość dla tego ciągu | Gdzie używa jej Bluesky |
|---|---|---|
| Grafemy | 32 | maxGraphemes: 300 dla text w app.bsky.feed.post |
| Jednostki kodowe UTF-16 | 33 | Nigdzie. To wartość, którą zwraca text.length w JavaScripcie |
| Bajty UTF-8 | 36 | byteStart i byteEnd oraz maxLength: 3000 dla text |
Rozbieżność bierze się z dwóch znaków. é to jedna jednostka kodowa UTF-16 i dwa bajty UTF-8. 🥐 to para zastępcza, czyli dwie jednostki kodowe UTF-16, i cztery bajty UTF-8. Gdy dochodzisz do adresu URL, oba systemy indeksowania różnią się o trzy:
| Prefiks | Jednostki kodowe UTF-16 | Bajty UTF-8 |
|---|---|---|
Café | 5 | 6 |
Café 🥐 | 8 | 11 |
Café 🥐 hours | 14 | 17 |
Dlatego text.indexOf('https://example.com') zwraca 14, a poprawny byteStart to 17. Użyj liczby z JavaScriptu, a Bluesky opisze bajty od 14 do 32, które po zdekodowaniu dają rs https://example. Słowo "hours" oddaje linkowi dwie ostatnie litery, końcowe com zostaje poza nim, a nikt nie dostaje żadnego błędu.
AdaptlyPost
Rozpocznij 7-dniowy bezpłatny okres próbny
Analityka wszystkich platform
Skrzynka społecznościowa
Asystent oparty na AI
Jak poprawnie obliczyć byteStart i byteEnd?
Zakoduj tekst do bajtów UTF-8 za pomocą TextEncoder, a oba przesunięcia wyprowadź z długości zakodowanych danych, a nie z indeksów w ciągu znaków. Zakodowanie fragmentu przed dopasowaniem daje byteStart, a zakodowanie samego dopasowania daje długość, którą trzeba dodać, by otrzymać byteEnd.
Ten kod działa bez zmian w Node 18 lub nowszym oraz w każdej nowoczesnej przeglądarce:
const encoder = new TextEncoder();
const decoder = new TextDecoder();
function detectFacets(text) {
const bytes = encoder.encode(text);
const facets = [];
const add = (match, feature) => {
const byteStart = encoder.encode(text.slice(0, match.index)).length;
const byteEnd = byteStart + encoder.encode(match[0]).length;
if (decoder.decode(bytes.slice(byteStart, byteEnd)) !== match[0]) {
throw new Error(`byte range ${byteStart}..${byteEnd} does not cover "${match[0]}"`);
}
facets.push({ index: { byteStart, byteEnd }, features: [feature] });
};
for (const m of text.matchAll(/https?:\/\/[^\s]+/g)) {
add(m, { $type: 'app.bsky.richtext.facet#link', uri: m[0] });
}
for (const m of text.matchAll(/#([A-Za-z0-9_]+)/g)) {
add(m, { $type: 'app.bsky.richtext.facet#tag', tag: m[1] });
}
return facets.sort((a, b) => a.index.byteStart - b.index.byteStart);
}
console.log(JSON.stringify(detectFacets('Café 🥐 hours https://example.com #bakery'), null, 2));Wynik:
[
{
"index": { "byteStart": 17, "byteEnd": 36 },
"features": [{ "$type": "app.bsky.richtext.facet#link", "uri": "https://example.com" }]
},
{
"index": { "byteStart": 37, "byteEnd": 44 },
"features": [{ "$type": "app.bsky.richtext.facet#tag", "tag": "bakery" }]
}
]Warunek kontrolny w add to część, którą warto zachować. Wycina z powrotem fragment zakodowanej tablicy bajtów, dekoduje go i porównuje z dopasowanym tekstem. Protokół nigdy nie powie ci, że zakres jest błędny, więc ta asercja to jedyny sygnał awarii, jaki dostaniesz, a kosztuje jedno porównanie na facet.
Dwa szczegóły tego fragmentu wynikają z leksykonu, a nie z upodobań. Cecha tag zawiera bakery, a nie #bakery, bo leksykon mówi, że odniesienie "should not" zawierać prefiksu. A features jest tablicą, więc jeden zakres bajtów może nieść więcej niż jedną adnotację.
Co znajduje się w tablicy features?
Każdy wpis w features to jeden z trzech elementów unii zdefiniowanych w tym samym pliku leksykonu, rozróżnianych przez ciąg $type.
| Cecha | $type | Wymagane pole | Ograniczenie | Sformułowanie w leksykonie |
|---|---|---|---|---|
| Wzmianka | app.bsky.richtext.facet#mention | did | format: did | "The text is usually a handle, including a '@' prefix, but the facet reference is a DID." |
| Link | app.bsky.richtext.facet#link | uri | format: uri | "The text URL may have been simplified or truncated, but the facet reference should be a complete URL." |
| Tag | app.bsky.richtext.facet#tag | tag | maxLength: 640, maxGraphemes: 64 | "The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags')." |
Wzmianki wymagają dodatkowego kroku. Widoczny tekst to nazwa użytkownika (handle), na przykład @example.com, ale facet przechowuje DID, więc najpierw musisz rozwiązać nazwę zapytaniem com.atproto.identity.resolveHandle, które przyjmuje parametr handle i zwraca did. Jego jedyny udokumentowany błąd to HandleNotFound, opisany jako "The resolution process confirmed that the handle does not resolve to any DID." Przechowywanie DID zamiast nazwy sprawia, że stara wzmianka nadal wskazuje właściwe konto, nawet gdy zmieni ono nazwę.
Sformułowanie dotyczące linku ma znaczenie dla wyświetlanego tekstu. Facet przechowuje pełny URL, a tekst może być skrócony, więc w poście możesz pokazać example.com/very-long... i nadal kierować ludzi pod pełny adres, o ile zakres bajtów obejmuje skrócony tekst, który faktycznie wpisano.
Dlaczego starsze przykłady kodu używają start i end?
Starsze przykłady używają start i end, bo rekord posta miał kiedyś inne pole z innymi zasadami liczenia, a obie wersje do dziś znajdują się w plikach leksykonu. app.bsky.feed.post definiuje tablicę entities oznaczoną jako "DEPRECATED: replaced by app.bsky.richtext.facet." Jej typ indeksu to #textSlice, którego opis brzmi: "Deprecated. Use app.bsky.richtext instead -- A text segment. Start is inclusive, end is exclusive. Indices are for utf16-encoded strings."
Protokół wprowadził więc typ wycinka w UTF-16, zastąpił go typem w UTF-8 i zachował obie definicje w schemacie. Każdy znaleziony fragment budujący { start, end } celuje w przestarzałe pole, a skopiowanie jego arytmetyki indeksów do byteSlice odtwarza dokładnie ten błąd, przed którym ostrzega nowszy NOTE. Zanim zaufasz przesunięciom, sprawdź nazwy pól: byteStart i byteEnd oznaczają bajty, a start i end oznaczały jednostki kodowe.

Jakie miejsce ma w tym narzędzie do planowania?
Narzędzie do planowania publikujące na Bluesky musi zbudować tablicę facets za ciebie, bo zapisuje ten sam rekord app.bsky.feed.post, który napisać można ręcznie. AdaptlyPost planuje posty na Bluesky razem z innymi sieciami, w których publikuje, więc obliczenia na bajtach odbywają się raz, w warstwie publikacji, a nie w każdym twoim skrypcie. Ten sam post może trafić na wiele kont i do wielu sieci za jednym razem, a zaangażowanie z Bluesky pojawia się później w analityce Bluesky.
Nic z tego nie zmienia protokołu. Limit 300 grafemów, limit 3 000 bajtów i przesunięcia w UTF-8 należą do Bluesky i działają tak samo, niezależnie od tego, czy rekord zapisuje narzędzie, czy ty. Narzędzie usuwa za to ryzyko wysłania byteStart przesuniętego o trzy w tym jednym poście, w którym akurat znalazło się emoji.
Najczęściej zadawane pytania
Czy potrzebuję facetu, jeśli pełny URL jest już widoczny w tekście posta?
Tak. Bluesky w ogóle nie wyciąga linków z tekstu posta, więc wpisany w całości URL wyświetla się jako nieklikalny zwykły tekst, chyba że facet z cechą #link obejmuje jego zakres bajtów. To najczęstsze zaskoczenie dla każdego, kto przechodzi z API automatycznie tworzącego linki.
Czy byteEnd to indeks ostatniego bajtu, czy następnego po nim?
Następnego po nim. Leksykon podaje "Start index is inclusive, end index is exclusive", co oznacza, że byteEnd minus byteStart równa się dokładnej długości opisywanego tekstu w bajtach. Dla https://example.com, czyli dziewiętnastu znaków ASCII, różnica wynosi 19.
AdaptlyPost
Rozpocznij 7-dniowy bezpłatny okres próbny
Analityka wszystkich platform
Skrzynka społecznościowa
Asystent oparty na AI
Co się stanie, jeśli byteStart i byteEnd będą błędne?
Rekord zostanie przyjęty. Jedyne ograniczenie liczbowe, jakie leksykon nakłada na te pola, to minimum: 0, więc przesunięcia wskazujące złe bajty albo wychodzące poza koniec tekstu nadal przechodzą walidację. Dowiesz się o tym, patrząc na wyrenderowany post, i dlatego warto zachować sprawdzenie przez dekodowanie i porównanie z powyższego kodu.
Czy usuwać znak krzyżyka z facetu tagu?
Tak. Leksykon mówi, że widoczny tekst "usually includes a '#' prefix, but the facet reference should not", z jednym wyjątkiem nazwanym "double hash tags". Zakres bajtów nadal obejmuje # w tekście, a znak znika tylko z ciągu tag.
Czy jeden facet może zawierać jednocześnie link i tag?
Tak. features jest zdefiniowane jako tablica unii #mention, #link i #tag, więc jeden byteSlice może zawierać więcej niż jedną adnotację. Leksykon nie mówi, jak klient ma wyświetlić zakres z dwiema sprzecznymi cechami, więc trzymaj się jednej na zakres, chyba że przetestujesz wynik.
Ile facetów może mieć jeden post?
Leksykon tego nie określa. Tablica facets w app.bsky.feed.post nie ma maxLength, w przeciwieństwie do tablicy tags w tym samym rekordzie, ograniczonej przez maxLength: 8. Skoro żaden limit nie jest opublikowany, traktuj praktyczny pułap jako nieznany, zamiast zakładać, że go nie ma.
Czym różni się przestarzałe pole entities od facetów?
Tablica entities w app.bsky.feed.post jest oznaczona jako przestarzała na rzecz app.bsky.richtext.facet i używała innego typu indeksu, #textSlice. textSlice liczył start i end w jednostkach kodowych UTF-16, tych samych, których używają indexOf i length w JavaScripcie, a byteSlice liczy bajty UTF-8. Obie definicje nadal znajdują się w plikach leksykonu, więc przykład kodu budujący { start, end } celuje w wycofane pole, a nie w to, które czytają dziś klienci Bluesky.
Dlaczego facet wzmianki na Bluesky przechowuje DID, a nie tekst nazwy użytkownika?
Widoczny tekst wzmianki to zwykle nazwa użytkownika, na przykład @example.com, ale leksykon wymaga, by odniesieniem w facecie był DID, uzyskany zapytaniem com.atproto.identity.resolveHandle. Nazwa może się zmienić, gdy ktoś przemianuje konto, a DID nie, więc przechowywanie DID utrzymuje starą wzmiankę przy właściwej osobie także po zmianie nazwy. Jedyny udokumentowany błąd tego zapytania, HandleNotFound, pojawia się, gdy proces rozwiązywania potwierdzi, że nazwa nie prowadzi do żadnego DID.
Czy tekst linku widoczny w poście może różnić się od faktycznego adresu URL?
Cecha linku przechowuje w facecie pełny URL, nawet gdy wyświetlany tekst jest skrócony. Leksykon zaznacza, że adres w tekście "may have been simplified or truncated", ale odniesienie w facecie "should be a complete URL." Dzięki temu post może pokazywać coś w rodzaju example.com/very-long..., a zakres bajtów nadal kieruje czytelników pod pełny adres, o ile obejmuje skrócony tekst, który faktycznie wpisano.
Jakie są limity znaków i bajtów w poście na Bluesky?
Bluesky ogranicza tekst posta do 300 grafemów przez maxGraphemes w polu text rekordu app.bsky.feed.post, a dodatkowo do 3 000 bajtów UTF-8 przez maxLength. To dwie jednostki liczenia dla tego samego pola: grafemy dla limitu wyświetlania, bajty dla limitu zapisu, a byteStart i byteEnd korzystają z tej samej liczby bajtów. Emoji albo znak z akcentem zużywają więcej budżetu bajtów niż grafemów i to ta sama różnica, która psuje przesunięcia byteStart.
Wykorzystaj to w praktyce z AdaptlyPost
Czy ten artykuł był pomocny?
Chętnie poznamy opinię!
Więcej naszych treści w Google
Jedno kliknięcie oznacza AdaptlyPost jako preferowane źródło, dzięki czemu nasze artykuły pojawiają się wyżej w Najważniejszych wiadomościach, trybie AI i Podsumowaniach AI.
Jeszcze chwila...
AdaptlyPost
Planowanie treści na wszystkich platformach
Wszystkie konta społecznościowe w jednym miejscu dzięki AdaptlyPost.
Analityka wszystkich platform
Skrzynka społecznościowa
Asystent oparty na AI
Powiązane hasła ze słownika


Jak działa generator kanałów Bluesky: od leksykonu do działającego kanału
Generator kanałów Bluesky to jedna usługa HTTPS odpowiadająca na jedno zapytanie XRPC. Leksykony, wpis w dokumencie DID, JWT i luki w dokumentacji.


Jak opublikować GIF na Bluesky, żeby się nie zatrzymał
Jak GIF trafia do posta na Bluesky: wyszukiwarka KLIPY, przesłane pliki zamieniane w wideo, osadzone obrazy z jedną klatką i to, co wysyła AdaptlyPost.


Jak threadgate na Bluesky decyduje, kto może odpowiedzieć na post
Threadgate na Bluesky ogranicza odpowiedzi do wspomnianych osób, obserwujących, obserwowanych lub listy. Jak działa ten rekord i postgate blokujący cytaty.
Powiązane artykuły


Pięć liczników zaangażowania: czy Bluesky ma analitykę?
Czy Bluesky ma analitykę? Nie. Lexicon daje postView pięć liczników zaangażowania, bez liczby wyświetleń, impresji i endpointu analitycznego.


Limity rozmiaru wideo na Bluesky: 300 MB, MP4 i 1920 pikseli
Limit rozmiaru wideo na Bluesky to 300 MB na plik MP4. Aplikacja skaluje wideo do 1920 pikseli na dłuższym boku przy 3 Mbps, a proporcje nie są narzucone.


Dlaczego dzienny limit postów na Instagramie to w dokumentacji Mety 100 i 50
Instagram nie podaje dziennego limitu postów dla aplikacji. Dokumentacja API Mety mówi raz o 100 postach na 24 godziny, a dwa razy o 50. Sprawdź, co obowiązuje.

