Słownik

Dlaczego byteStart i byteEnd w facetach Bluesky liczą bajty, a nie znaki

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •9 min czytania
Dlaczego byteStart i byteEnd w facetach Bluesky liczą bajty, a nie znakiDlaczego byteStart i byteEnd w facetach Bluesky liczą bajty, a nie znaki

TL;DR, szybka odpowiedź

9 min czytania

Facet 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."

PoleTypOgraniczenie w leksykonieZnaczenie
index.byteStartintegerminimum: 0Pierwszy bajt opisywanego zakresu, włącznie
index.byteEndintegerminimum: 0Bajt po ostatnim opisywanym bajcie, wyłącznie
featuresarrayunia #mention, #link, #tagJedna 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.

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.

Programista pisze kod na laptopie: to taka szybka poprawka w JavaScripcie, która po cichu psuje przesunięcia bajtów w tekście spoza ASCII.

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

Trzy systemy liczenia dają dla niego różne wyniki:

Jednostka liczeniaWartość dla tego ciąguGdzie używa jej Bluesky
Grafemy32maxGraphemes: 300 dla text w app.bsky.feed.post
Jednostki kodowe UTF-1633Nigdzie. To wartość, którą zwraca text.length w JavaScripcie
Bajty UTF-836byteStart 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:

PrefiksJednostki kodowe UTF-16Bajty UTF-8
Café 56
Café 🥐 811
Café 🥐 hours 1417

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
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Jak błędne przesunięcie prześlizguje się dalej
Tekst zawiera akcenty lub emoji
indexOf liczy UTF-16, a nie bajty
byteStart trafia w zły bajt
Rekord nadal przechodzi walidację schematu
Link wskazuje niewłaściwy tekst
Nic w tym łańcuchu nie zgłasza błędu, więc zły link wychodzi po cichu.

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$typeWymagane poleOgraniczenieSformułowanie w leksykonie
Wzmiankaapp.bsky.richtext.facet#mentiondidformat: did"The text is usually a handle, including a '@' prefix, but the facet reference is a DID."
Linkapp.bsky.richtext.facet#linkuriformat: uri"The text URL may have been simplified or truncated, but the facet reference should be a complete URL."
Tagapp.bsky.richtext.facet#tagtagmaxLength: 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.

Osoba ustawia harmonogram postów na laptopie: to proces, który narzędzie do planowania musi przełożyć na poprawne zakresy bajtów w facetach.

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

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.

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

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

Powiązane artykuły