sztuczny-miodek

Skill Claude Code do audytu polszczyzny i eradykacji manieryzmu AI (AI-tellów) w tekstach polskich i angielskich. Metodologia: pragmatyczny puryzm Jana Miodka.

Ten projekt to fork. Rdzeń pochodzi od Tomasza Jakubowskiego, z oryginalnego repozytorium researchanddeploy/sztuczny-miodek: deterministyczny linter Stage 1, kanon manieryzmu, metodologia Miodka, instalacja jako skill Claude Code oraz słownik domenowy.

Fork rozwija narzędzie o kolejne warstwy:

• CLI przez uvx z ujednoliconym poleceniem miodek,
• trzy bramki jakości: przy zapisie pliku, na merge request, przed publikacją,
• korektor zamykający pętlę audytu do werdyktu PASS,
• osąd modelu Stage 2 z routingiem silników i lejkiem kosztowym,
• ekonomię i obserwowalność: metryki z manifestu oraz eksporter Prometheus,
• integrację LanguageTool na żądanie.

Spis treści

• Co robi
• Kluczowe funkcje
• Instalacja
  • Tryb A — bezpośredni clone (skill)
  • Tryb B — plugin przez marketplace
  • Tryb C — CLI przez uvx
• Użycie
  • W Claude Code
  • Linter z linii poleceń
  • Interpretacja manifestu i werdyktu
• Dokumentacja
• Atrybucja i licencja

Co robi

Skill realizuje dwie misje:

1. Wzorcowa polszczyzna (PL) — pełny audyt tekstu polskiego wg dziesięciu priorytetów: cyrylica, kalki angielskie, fałszywi przyjaciele, anglicyzmy, sztuczne kolokacje, interpunkcja, styl i gramatyka, ortografia terminów łacińskich/greckich, manieryzm AI, typografia.
2. Usuwanie AI-tellów (PL + EN) — wykrywa i usuwa manieryzmy generatywne: puste signposty, triady (rule-of-three), antytezę „nie X — to Y”, paralelizm, nadużycie myślnika, puste superlatywy, klisze redefinicyjne, emoji w nagłówkach. Dla raportów, syntez, listów motywacyjnych, CV i dokumentacji.

Skill działa jako twarda bramka jakości przed deklaracją „done”. Obowiązuje semantyka „PASS z uwagami = NIE PASS”: każdy nierozwiązany flag blokuje werdykt PASS. Werdykt FAIL zapada przy cyrylicy w tekście PL (FAIL-HARD), markerze klasy block po przekroczeniu progu albo gęstości ważonej trafień powyżej 8 na 500 słów.

Zasada Miodka: poprawiaj to, co ma polski odpowiednik; zachowuj to, co przyjęło się w danej dziedzinie. Dla manieryzmu AI: zmieniaj teksturę prozy, zachowuj fakty i metryki.

Kluczowe funkcje

• Deterministyczny linter (Stage 1). Wykrywa manieryzm bez kosztu tokenów LLM, na samej bibliotece standardowej Pythona. Łapie szeroko, a niepewne trafienia oznacza do przeglądu.
• Opcjonalny osąd modelu (Stage 2). Rozstrzyga niepewne trafienia w kontekście całego zdania i nanosi poprawkę tylko tam, gdzie trzeba.
• Kanon manieryzmu PL i EN. Czternaście kategorii ze wspólnym źródłem w manieryzm-ai.md, każda z odpowiednikiem w linterze.
• Pełny audyt polszczyzny. Priorytety od cyrylicy po typografię, wedle pragmatycznego puryzmu Jana Miodka (szczegóły w SKILL.md).

Format manifestu i czytanie werdyktu opisuje sekcja Interpretacja manifestu i werdyktu.

Instalacja

Tryb A — bezpośredni clone (skill)

Najprostszy. Skill ląduje wprost w katalogu skilli Claude Code:

mkdir -p ~/.claude/skills
git clone https://github.com/researchanddeploy/sztuczny-miodek.git ~/.claude/skills/sztuczny-miodek

Claude Code wykryje skill automatycznie na podstawie SKILL.md. Wywołanie: /sztuczny-miodek.

Aktualizacja: cd ~/.claude/skills/sztuczny-miodek && git pull.

Tryb B — plugin przez marketplace

Wersjonowane aktualizacje i instalacja jedną komendą:

/plugin marketplace add researchanddeploy/sztuczny-miodek
/plugin install sztuczny-miodek@sztuczny-miodek

Wywołanie: /sztuczny-miodek:sztuczny-miodek. Aktualizacja: /plugin update sztuczny-miodek@sztuczny-miodek.

Oba tryby korzystają z tego samego SKILL.md w korzeniu repo. Katalog .claude-plugin/ jest używany tylko w trybie B.

Tryb C — CLI przez uvx

Narzędzie linii poleceń miodek można uruchomić bez ręcznej instalacji. Wymaga uv. Najprościej, wprost z PyPI:

uvx miodek lint --lang both ŚCIEŻKA_DO_PLIKU.md

uvx pobiera paczkę do cache i uruchamia ulotnie, bez instalowania niczego na stałe. Polecenie miodek to dispatcher z podkomendami lint, correct, gate, lt oraz build-dict. Eksporter metryk Prometheus jest osobnym poleceniem miodek-exporter.

Alternatywnie, wprost ze źródła git (np. dla gałęzi roboczej przed wydaniem na PyPI):

uvx --from git+https://github.com/hretheum/sztuczny-miodek@epic-a-reguly-jako-dane \
  miodek lint --lang both ŚCIEŻKA_DO_PLIKU.md

Czysty skill (tryby A i B) żyje w Claude Code: wywołujesz go w rozmowie, a model prowadzi audyt i korektę. Tryb C wynosi te same reguły poza Claude Code, do terminala i do potoku CI, jako samodzielne polecenie. Co daje:

• działa poza Claude Code, w dowolnym terminalu i w potoku CI, bez asystenta;
• batch na całych katalogach i wzorcach glob z jednym zbiorczym kodem wyjścia (Użycie z CLI);
• trzy bramki jakości jako kroki automatyzacji;
• osąd modelu Stage 2 z routingiem silników oraz korektor do werdyktu PASS;
• budowa słownika domenowego podkomendą miodek build-dict;
• eksporter metryk Prometheus jako polecenie miodek-exporter.

Rdzeń nie ma żadnych zależności (sama biblioteka standardowa). Warstwy opcjonalne wydzielają extras [exporter] i [lt], dziś puste, bo wszystkie komponenty działają na bibliotece standardowej. Powiązanie z homelabem (quadlet, systemd) zostaje poza paczką.

Użycie

W Claude Code

Skill uruchamia się przez jeden z wyzwalaczy w rozmowie:

• sprawdź polszczyznę
• sztuczny miodek
• audyt językowy
• korekta tekstu, manieryzm AI, AI-tell, de-AI, usuń ślady AI, odAI-uj

Claude przeprowadzi pełny protokół: pre-scan linterem, osąd kontekstowy, korektę, przebieg weryfikacyjny i werdykt PASS/FAIL.

Linter z linii poleceń

Pre-scan można uruchomić samodzielnie podkomendą lint:

miodek lint --lang both ŚCIEŻKA_DO_PLIKU.md

Po instalacji przez uvx (Tryb C) zadziała też bez klonu repo. Z klonu repo, bez instalacji, ten sam linter uruchomisz przez python3 -m miodek.ai_linter --lang both ŚCIEŻKA_DO_PLIKU.md (z PYTHONPATH=src).

Flaga --lang przyjmuje pl, en lub both. Można podać kilka ścieżek naraz. Audyt całych katalogów i wzorców glob, raport zbiorczy --report oraz pozostałe flagi opisuje Użycie z CLI: batch i flagi.

Interpretacja manifestu i werdyktu

Manifest to jedna linia na trafienie:

raport.md:42:PL-SIGN:review:Warto podkreślić, że

Pola: ścieżka pliku, numer linii, ID kategorii, klasa (review lub block), dopasowany fragment. Klasa review wymaga osądu kontekstowego (możliwy false-positive). Klasa block to bloker werdyktu po przekroczeniu progu.

Blok == SUMMARY == podaje werdykt na końcu:

== SUMMARY ==
plik | słowa | trafienia | em-dash/akapit(max) | gęstość/500 | blokery | WERDYKT

PASS zapada tylko przy zerze blokerów i gęstości nie większej niż 8.

Dokumentacja

Pełny opis warstw zaawansowanych żyje w katalogu docs/. Pełną listę flag każdej komendy pokazuje miodek <komenda> --help.

• Użycie z CLI: batch i flagi — audyt katalogów, wzorce glob, raport zbiorczy, profile i format wyjścia.
• Bramki jakości — trzy bramki: przy zapisie pliku, na merge request, przed publikacją.
• Stage 2: osąd modelu, silniki, korekta — runner, wymienne silniki, RunPod, routing apelacyjny, korektor, LanguageTool.
• Ekonomia i obserwowalność — współczynnik redukcji, metryki z manifestu, eksporter Prometheus i dashboard.
• Słownik domenowy — warstwa terminologii, format JSON, budowa przez miodek build-dict.
• Audyt i korekta stron Confluence — miodek confluence pull (audyt) i correct (korekta z zapisem zwrotnym, dry-run + potwierdzenie); wiele instancji przez --instance (nazwane sloty CONFLUENCE_<NAZWA>_* w env).
• Interfejs adaptera — adaptery wejścia i wyjścia, segmentacja.
• Kalibracja progów — metodyka strojenia progów na korpusie.
• Współtworzenie — bramka jakości, testy, styl, pull requesty.
• Changelog — historia wersji.

Atrybucja i licencja

Autor oryginalnego skilla: Tomasz Jakubowski (upstream: github.com/researchanddeploy/sztuczny-miodek). To repozytorium rozwija jego narzędzie jako fork zgodny z licencją MIT.

Kod, taksonomia AI-tellów, reguły polszczyzny i układ skilla: licencja MIT (zob. plik LICENSE).

Metodologia opiera się na pracy Jana Miodka (pragmatyczny puryzm, „Ojczyzna polszczyzna”). To referencja i atrybucja, nie redystrybucja chronionej treści. Licencja MIT obejmuje wyłącznie materiały tego repozytorium; nie rozciąga się na cudzą własność intelektualną, do której repo się odwołuje.