FlagTLDR – flagi krajów, filtrowanie i TL;DR wątków na X

FlagTLDR to rozszerzenie przeglądarki (Manifest V3: Chrome, Edge, Brave; ładuje się też w Firefoksie) dla x.com. Pokazuje kraj konta autora, pozwala filtrować wpisy wg kraju/regionu, podsumowuje dyskusję pod wpisem Twoim własnym Grokiem i (opcjonalnie) oznacza wpisy lokalnym klasyfikatorem. Każdą funkcję można wyłączyć. Aktualna wersja: 0.5.0 – zmiany: CHANGELOG.md.

Rozszerzenie sprawdzone end-to-end na makiecie x.com (także z modelem basal-omni-pico), nie na prawdziwym, zalogowanym x.com. Testujesz u siebie? → docs/TESTOWANIE.md (instalacja z zipa, aktualizacja, scenariusze, raport diagnostyczny).

Funkcje

• ⚖ Podsumuj (TL;DR wątku): jedno kliknięcie przy wpisie → Twój Grok (ukryta ramka x.com/i/grok lub karta w tle) streszcza tylko poddrzewo klikniętego wpisu. Ścieżka Teza: teza, argumenty ZA / PRZECIW wg ważności (top 3 + „Pokaż wszystkie”), zwinięte OCENA / BRAKUJE / SZUM; ścieżka Informacja dla wpisów bez tezy. Pasek postępu z upływającym i oczekiwanym czasem. Domyślnie hybrydowo: rozszerzenie dostarcza zweryfikowane odpowiedzi, a Grok doczytuje wątek wg tych samych zasad.
• Kraj konta autora: flaga kraju wg X, zarys regionu, gdy X podaje tylko region; przycisk „🌐 Sprawdź kraj” przy wpisie (domyślnie na żądanie), opcjonalne automatyczne sprawdzanie z kolejką i limitem tempa, pamięć 14 dni.
• Filtr wg kraju / regionu: zwiń / ukryj / przyciemnij, czarna lub biała lista (domyślnie wyłączony).
• Oznaczanie wpisów klasyfikatorem (opcjonalnie, lokalnie): zob. „Model / klasyfikator”.
• Tryb diagnostyczny: raport bez treści do zgłaszania problemów.

Co da się zrobić (w skrócie)

Pytanie	Odpowiedź
Czy można „zainstalować coś w X”?	Nie. X nie ma platformy wtyczek/mini-aplikacji dla zewnętrznych twórców. Oficjalne są tylko X API i xAI API.
Jak w takim razie?	Rozszerzenie przeglądarki (Manifest V3) działające na x.com – Chrome, Edge, Brave, Firefox (też Firefox na Androidzie). Alternatywa: userscript (Tampermonkey).
Podsumowanie wątku przez Groka z Twojego konta X	Tak, automatycznie jednym kliknięciem (tryb grok-auto, domyślny). Po kliknięciu „⚖ Podsumuj” rozszerzenie otwiera Twojego Groka w ukrytej ramce x.com/i/grok albo w karcie w tle. Wpisuje tam prompt, klika „Wyślij”, czeka na koniec odpowiedzi i pokazuje ją w panelu pod wpisem. Steruje wyłącznie interfejsem; nie wywołuje wewnętrznych API X. Przy błędzie zostaje ręczne przekazanie (schowek + Grok). Alternatywy: xAI API (klucz lub OAuth subskrypcji SuperGrok/Premium+), dowolne API zgodne z OpenAI.
Skąd jest konto autora? Ukrywanie wg kraju	Tak (domyślnie włączone na żądanie, automatyczne sprawdzanie domyślnie wyłączone). Przy autorze: flaga kraju „wg X” (to samo, co „Informacje o koncie” → „Konto z”), zarys regionu, gdy X podaje tylko region (np. „Azja Południowa”), 🌐 dla nieznanego regionu, ⚠ gdy X sam ostrzega o VPN/proxy, osobno 📍 lokalizacja wpisana w profilu. Pasywnie z danych, które X już pobrał; aktywne sprawdzanie to opcja z ostrzeżeniem o ryzyku (nieudokumentowany endpoint w Twojej sesji), z adaptacyjnym tempem wg nagłówków limitu X (domyślnie do 12/min, rezerwa dla Ciebie), cache 14 dni i pauzą po 429; do tego przycisk „🌐 Sprawdź kraj” przy wpisie (jedno zapytanie, od razu po kliknięciu). Filtr: kraje/regiony/„nieznana”, ukryj / zwiń / przyciemnij, oś czasu / odpowiedzi, czarna / biała lista, opcjonalnie poza promptem podsumowania.
Oznaczanie wpisów łatwo trenowanym modelem	Tak. Główny kandydat: basal-omni (Remigiusz Kinas, Apache-2.0, PL+EN) – model „System 1” w stylu Jev, który zwraca prawdopodobieństwa etykiet. Klasyfikację definiujesz opisem + etykietami z rubrykami + przykładami. basal-omni-pico (0,8B) działa na CPU (~0,3–0,5 s/wpis). Zapasowo: embeddingi + szybko trenowana głowica (sekundy) lub LLM few-shot.

Zrzuty ekranu

Wykonane automatycznie (scripts/demo.sh) w Chrome for Testing 156 z rozpakowanym rozszerzeniem, na makiecie x.com (extension/fixtures/mock-x, treści zmyślone), z klasyfikatorem basal-omni-pico na CPU. Zrzuty z prawdziwego x.com – po decyzjach z DECISIONS.md.

Oznaczanie wpisów (💡 merytoryczny, 🔇 szum – zwinięty)	„⚖ Podsumuj” → postęp (Grok działa w tle)
Wynik pod wpisem (Kopiuj · Otwórz w Groku · Ponów)	Błąd → ręczny fallback (schowek + Grok)

Na zrzutach „Grok” to makieta (fixtures/mock-x/grok.html), która strumieniuje odpowiedź złożoną lokalnie, bez AI. Tryb ręczny (grok-handoff): summary-handoff.png.

Kraj konta autora – flaga = kraj wg X, zarys = region wg X, 🌐 = nieznany region, ⚠ = X ostrzega o VPN/proxy, 📍 w przerywanej ramce = lokalizacja wpisana w profilu (niezweryfikowana). Dane z makiety (extension/fixtures/about/*.json).

Styl „flaga / zarys + nazwa”	Styl „tylko flaga / zarys”
Filtr: zwinięte odpowiedzi z wybranego regionu i „nieznana” (przycisk „Pokaż”)	Ustawienia kraju konta (czerwona ramka = ryzyko)

Tryb Groka niedostępny (limit planu) → ostrzeżenie w panelu, podsumowanie w bieżącym trybie

Sprawdzanie kraju, kolejka i kotwiczenie przycisków:

„🌐 Sprawdź kraj” przy wpisie (jednorazowa uwaga o ryzyku)	Po kliknięciu: flaga przy wszystkich wpisach autora
Pigułka kolejki + mini‑panel (pauza X 429)	Ankieta obrazkowa: „⚖ Podsumuj” w pasku akcji
Podsumowanie tylko poddrzewa klikniętego wpisu	Cytat: przycisk i plakietka przy wpisie, nie w cytacie

Ustawienia (system prompt, dostawca, definicja klasyfikacji z przykładami):

Instalacja

Wszystko jest w /workspace/x-addons; narzędzia i cache są lokalne (.tools/, .cache/) – nic globalnego.

cd /workspace/x-addons
scripts/setup.sh            # Node 22 (.tools/node, przez uvx nodeenv), npm deps, uv sync dla classifier/
source scripts/env.sh       # PATH/UV_CACHE_DIR/HF_HOME tylko dla tego projektu

Rozszerzenie

• Chrome / Edge / Brave: chrome://extensions → „Tryb dewelopera” → „Załaduj rozpakowane” → katalog extension/.
• Firefox (desktop): about:debugging#/runtime/this-firefox → „Załaduj tymczasowy dodatek” → extension/manifest.json.
• Gotowa paczka dla Chrome (bez narzędzi deweloperskich): python3 scripts/package-chrome.py → dist/flagtldr-<wersja>-chrome.zip (oraz rozpakowana kopia dist/flagtldr-<wersja>-chrome/). Rozpakuj → „Załaduj rozpakowane”. Szczegóły i scenariusze testów: docs/TESTOWANIE.md. dist/ nie jest w gicie.
• Paczka web-ext: cd extension && npm run build → extension/web-ext-artifacts/*.zip. Kontrola: npm run check (testy + web-ext lint).

Klasyfikator (opcjonalny, lokalny)

scripts/basal-serve.sh                                   # basal-omni-pico na CPU, :8000 (osobne env .tools/basal-env)
cd classifier && uv run xaddons-classifier serve --backend basal   # serwis dla rozszerzenia, :8765
# bez modelu (test UI):  uv run xaddons-classifier serve            # backend "rules"

Użycie

1. Ustawienia (klik w ikonę rozszerzenia): system prompt podsumowania, dostawca (domyślnie Grok na koncie X), ewentualnie klucz xAI/OpenRouter albo adres lokalnego mostu.

2. Podsumowanie: otwórz wpis na x.com, przewiń odpowiedzi (X dociąga je partiami), kliknij ⚖ Podsumuj przy wpisie z tezą – może być w środku rozmowy: do promptu trafia tylko jego poddrzewo (odpowiedzi i odpowiedzi na nie), a wpisy wyżej najwyżej jako „kontekst nadrzędny” (ustawienie „Kontekst nadrzędny”, domyślnie bezpośredni rodzic). W trybie domyślnym (grok-auto) na dole pojawia się arkusz z postępem (Zbieram odpowiedzi → Otwieram Groka w tle → Wysyłam do Groka → Grok pisze… → Gotowe). Wynik ląduje w panelu pod wpisem: Kopiuj, Otwórz w Groku (link do rozmowy) i Ponów. Jeśli coś pójdzie nie tak (niezalogowany, zmiana interfejsu X, limit zapytań, przekroczony czas), panel pokazuje powód i przycisk „Kopiuj prompt i otwórz Groka”. W trybie API wynik trafia do tego samego panelu. Musisz być zalogowany do X w tej przeglądarce. Każde podsumowanie to nowa rozmowa w Twojej historii Groka.

3. Oznaczanie: w ustawieniach zaznacz „Klasyfikuj widoczne wpisy”, wybierz backend, wpisz opis klasyfikacji, etykiety (key, rubric, color, icon, action: mark/collapse/hide) i przykłady etykieta | tekst. Przycisk „Wczytaj przykładową klasyfikację” ładuje shared/labelset.example.json (merytoryczny / kontra / szum).

4. Kraj konta autora (ustawienia → „3. Kraj konta autora”; domyślnie włączone na żądanie – przycisk „🌐 Sprawdź kraj”, automatyczne sprawdzanie i filtr domyślnie wyłączone):

   • „Pokazuj kraj / region konta przy wpisach” – styl (flaga/zarys + nazwa lub sama ikona), czcionka flag (Twemoji na Windows), 📍 lokalizacja z profilu, „?” dla nieznanych.
   • Pasywnie (bez ryzyka): rozszerzenie bierze tylko to, co X sam pobrał – lokalizację z profilu z każdej odpowiedzi GraphQL oraz „Konto z”, gdy sam otworzysz czyjeś „Informacje o koncie”.
   • ⚠ „Sprawdzaj kraje automatycznie” (ryzyko, domyślnie wyłączone): zapytanie AboutAccountQuery (to samo, które wysyła strona „Informacje o koncie”) z Twojej sesji, tylko dla autorów widocznych na ekranie, 1 naraz, domyślnie do 12/min (1–30) z tempem adaptacyjnym, pamięć podręczna 14 dni (1–30), pauza do resetu limitu po 429, zatrzymanie po błędach (401/403, zmiana queryId, 3 błędy z rzędu). Stan i „Wznów” w ustawieniach.
   • Filtr: wybierz kraje, regiony (region obejmuje swoje kraje i pod-regiony) i/lub „Nieznana lokalizacja”; tryb zwiń z „Pokaż” / ukryj / przyciemnij; zakres oś czasu / odpowiedzi w wątkach / oba; czarna albo biała lista. Konto jeszcze niesprawdzone nigdy nie jest ukrywane; otwarty wpis też nie. Odpowiedzi ukryte/zwinięte filtrem domyślnie nie trafiają do promptu podsumowania.

5. Tryb diagnostyczny (ustawienia → „4. Diagnostyka”): zapisuje tylko strukturę i czasy – trafienia selektorów Groka, szkielet strony z długościami zamiast tekstu, kroki i czasy strumieniowania, statystyki parsera x.com, stan klasyfikatora – bez treści wpisów, promptu, odpowiedzi, nazw kont, ID, ciasteczek i tokenów. „Pobierz raport diagnostyczny” (w ustawieniach z podglądem albo w panelu błędu) zapisuje plik JSON. Przykład: docs/diagnostics/sample-report.json.

   Sekcja `geo` raportu: tylko liczniki (zapytania, trafienia cache, 429, stopy) – bez @handle i krajów.

6. Bez lokalnego klasyfikatora: podsumowania działają normalnie. Backend „Wbudowany” oznacza wpisy offline, a niedostępny serwis daje jednorazowy komunikat i brak znaczków (ponowienie najwyżej raz na minutę).

7. Demo bez konta X: scripts/demo.sh (lub XA_CLASSIFIER=basal scripts/demo.sh) – generuje zrzuty powyżej.

Model / klasyfikator

Część ML to opcjonalny, lokalny klasyfikator wpisów (classifier/, pakiet xaddons-classifier). W repozytorium nie ma wag modelu ani trenowania – serwis korzysta z cudzego, otwartego modelu albo z reguł.

• Co klasyfikuje: widoczne wpisy na x.com według Twojej definicji: opis zadania + etykiety z rubrykami (key, rubric, color, icon, action: mark / collapse / hide) + opcjonalne przykłady etykieta | tekst. Przykładowy zestaw shared/labelset.example.json: merytoryczny / kontra / szum. Rozszerzenie oznacza wpis kolorem/ikoną albo go zwija/ukrywa.
• Modele / backendy:
  • basal – rodzina basal-omni (Remigiusz Kinas, Apache-2.0, PL+EN; domyślnie Remek/basal-omni-pico, 0,8B) uruchamiana lokalnie przez basal-serve (scripts/basal-serve.sh, CPU, osobne środowisko); większe warianty (1.0-mini / max) wymagają GPU;
  • embed – embeddingi + szybko trenowana głowica (opcjonalne zależności uv sync --extra embed);
  • rules – reguły bez modelu (do testów UI) oraz backend „Wbudowany” w samym rozszerzeniu (offline).
• Uruchomienie lokalnie: scripts/basal-serve.sh (model na :8000) i cd classifier && uv run xaddons-classifier serve --backend basal (serwis dla rozszerzenia na 127.0.0.1:8765) – zob. „Instalacja”.
• Wejście / wyjście: POST /v1/classify {labelset, posts} → dla każdego wpisu {label, probabilities, confidence}.
• Ograniczenia: orientacyjny test na 15 ręcznie napisanych polskich wpisach (classifier/data/eval.sample.jsonl, 3 etykiety – mały zbiór): basal-omni-pico 11/15 z 4 przykładami, 10/15 zero-shot, ~0,3–0,5 s/wpis na CPU. Model bywa zbyt pewny siebie na danych spoza domeny (krótkie, ironiczne wpisy z X) – warto ustawić próg pewności i skalibrować go na własnych przykładach. Szczegóły: RESEARCH §5.
• Podsumowania wątków nie używają tego modelu: „⚖ Podsumuj” korzysta z Twojego własnego Groka na Twoim koncie X (lub opcjonalnie z Twojego klucza API zgodnego z OpenAI), a podsumowania działają także bez lokalnego klasyfikatora.

Prywatność

Rozszerzenie nie ma własnego serwera i nie zbiera danych. Ustawienia, pamięć krajów, statystyki czasu i (opcjonalna) diagnostyka są w chrome.storage.local w Twojej przeglądarce. Prompt podsumowania trafia tylko do wybranego przez Ciebie dostawcy (domyślnie Twój Grok na x.com), sprawdzanie kraju to zapytania do x.com w Twojej sesji, a wpisy do klasyfikacji – tylko do lokalnego serwisu na 127.0.0.1. Bez analityki i telemetrii. Raport diagnostyczny zawiera wyłącznie strukturę i czasy, bez treści, nazw kont, ID, ciasteczek i tokenów. Polityka prywatności: docs/store/PRIVACY.md.

Rozwój i testy

• Testy jednostkowe i lint: cd extension && npm run check; klasyfikator: cd classifier && uv run pytest -q.
• Testy end-to-end na makiecie x.com (scripts/e2e/, Chrome for Testing) i scenariusze ręczne: docs/TESTOWANIE.md.
• Wymagania: docs/REQUIREMENTS.md · decyzje: docs/DECISIONS.md · research: docs/RESEARCH.md · materiały do sklepów: docs/store/.
• Historia zmian: CHANGELOG.md.

Architektura (skrót)

x.com ──(MAIN world) page-hook.js: kopiuje odpowiedzi GraphQL, które X i tak pobiera (TweetDetail, timeline, AboutAccountQuery…);
   │      opcjonalnie (aktywne sprawdzanie) wysyła AboutAccountQuery z kontekstu strony – token zostaje w stronie
   ├─ lib/geo.js + geo-data.js: nazwa kraju/regionu → ISO → flaga / zarys SVG (Natural Earth), reguły filtra
   ├─ lib/geo-limit.js (w tle): cache 14 dni, 1 naraz, limit/min, pauza po 429, stop po błędach
   └─(ISOLATED) content.js: parser wpisów, przycisk „Podsumuj”, oznaczenia (CSS), panel wyniku
         └─ background service worker: router
              ├─ podsumowanie: grok-auto (domyślne) | grok-handoff | openai-compatible (xAI API / progrok / OpenRouter / Ollama) | [grok-x-session – wyłączone]
              │    grok-auto: job → ukryta ramka x.com/i/grok (same-origin) lub karta w tle (tabs.create active:false)
              │      └─ grok-automation.js (w ramce/karcie): wpisuje prompt (input events) → klik „Wyślij” → czeka,
              │         aż strumień się ustabilizuje → markdown + URL rozmowy → background → panel pod wpisem
              │      selektory Groka w jednym miejscu: extension/src/lib/grok-auto.js (SEL)
              └─ klasyfikacja: rules (wbudowany) | classifier/ :8765 (basal / embed) | basal-serve :8000 bezpośrednio
classifier/ (uv, FastAPI): POST /v1/classify {labelset, posts} → {label, probabilities, confidence}
shared/labelset.example.json: wspólny format klasyfikacji

Struktura

CHANGELOG.md historia wersji
docs/        RESEARCH.md, REQUIREMENTS.md, DECISIONS.md, TESTOWANIE.md, diagnostics/sample-report.json, screenshots/,
             store/ (PRIVACY, PERMISSIONS, LISTING, PUBLISHING, assets/), icon/ (flagtldr.svg, variants/, comparison.png)
extension/   manifest.json, src/{content,background,lib (diag.js, geo.js, geo-data.js, geo-limit.js, account-info.js…),options}, icons/,
             vendor/twemoji-flags/ (czcionka flag, MIT/CC-BY 4.0), test/, fixtures/ (about/*.json – makiety AboutAccountQuery)
classifier/  pyproject.toml (uv), src/xaddons_classifier/{server,spec,backends/{rules,basal,embed}}, tests/, scripts/eval.py, data/
shared/      labelset.example.json
scripts/     env.sh, setup.sh, basal-serve.sh, demo.sh, package-chrome.py, e2e/ (screens.mjs, diag.mjs, geo.mjs, unreleased.mjs, store-assets.mjs, icon-render.mjs, release-check.mjs…), geo/build_geo.py

Ograniczenia i ryzyka

• Regulamin X zabrania dostępu innymi niż opublikowane interfejsy i scrapingu bez zgody. Rozszerzenie tylko czyta to, co już jest wyświetlone/pobrane w Twojej przeglądarce i domyślnie nie wysyła własnych zapytań do X – to obszar niższego ryzyka (jak popularne rozszerzenia typu Control Panel for Twitter), ale nie zerowego. Patrz RESEARCH §2.
• Tryb grok-auto (one-click), ryzyko umiarkowane/niskie. Rozszerzenie klika w interfejs Groka za Ciebie, tylko po Twoim kliknięciu, raz na podsumowanie i bez wewnętrznych API. Regulamin X ogólnie zakazuje jednak automatyzacji dostępu, więc to szara strefa, tyle że o znacznie mniejszej skali niż ścieżka grok-x-session. Nie zdejmujemy żadnych nagłówków bezpieczeństwa: X sam pozwala osadzać x.com w ramce na x.com (frame-ancestors 'self'). Selektory Groka nie są zweryfikowane na prawdziwym x.com, tylko na makiecie i według źródeł zewnętrznych; po zmianie interfejsu poprawia się je w src/lib/grok-auto.js. Opcje: kontekst (ramka / karta w tle / zminimalizowane okno), limit znaków promptu (24 000; przy przekroczeniu najpierw odpadają najmniej polubione odpowiedzi), limit czasu (180 s), debug „nie zamykaj karty”.
• Kraj konta – aktywne sprawdzanie (opcja, domyślnie wyłączona), ryzyko średnie: zapytania do nieudokumentowanego endpointu AboutAccountQuery w Twojej zalogowanej sesji – szara strefa regulaminu, możliwe 429 (które psują też natywne „Informacje o koncie”), w skrajności ograniczenie konta. Zabezpieczenia: tylko widoczni, 1 naraz, adaptacyjnie do 12/min z rezerwą, cache 14 dni, pauza po 429, stop po błędach; tempo dopasowane do nagłówków x-rate-limit-* z rezerwą. Kliknięcie „🌐 Sprawdź kraj” to jedno zapytanie od razu (max 2 naraz), wstrzymywane tylko pauzą nałożoną przez X. Samo „Konto z” bywa błędne (VPN, Starlink, narzędzia do planowania postów, podróże) – traktuj je jako sygnał, nie dowód. Szczegóły: RESEARCH §8, DECISIONS D10, D11.
• X często zmienia DOM i nazwy zapytań GraphQL – selektory/parsery trzeba będzie utrzymywać.
• basal-omni-pico jest szybki, ale na nowych danych bywa zbyt pewny siebie – trzeba skalibrować na własnych przykładach.
• Na telefonie: tylko Firefox (Android), Edge/Vivaldi/Lemur (Android) lub Safari/Orion (iOS – nieprzetestowane).