AI FAQ Generator + AI News Portal

Dwie niezależne wtyczki WordPress w jednym repozytorium. Pierwsza odpowiada gościom na pytania wyłącznie treścią ich własnej strony. Druga prowadzi portal wiedzy, który zasila się sam z kanałów RSS. Obie korzystają z modeli Gemini na kluczu właściciela witryny (BYOK) i obie da się z witryny usunąć bez śladu.

Ten plik jest jednocześnie README całego repozytorium i dokumentacją wtyczki 1.

[!IMPORTANT] Korzeń repozytorium jest katalogiem wtyczki 1, a wtyczka 2 leży w podfolderze. To nie jest bałagan, tylko wymuszenie WordPressa: skaner wtyczek schodzi tylko dwa poziomy w głąb wp-content/plugins/, więc plik główny musi leżeć najwyżej jeden katalog niżej. Na żywą instalację celują junctiony dokładnie w te ścieżki, dlatego przenoszenie katalogów wtyczek albo zmiana ich nazw psuje żywą stronę i testy.

Spis treści

• Stan
• Co robi każda wtyczka
• Gdzie co leży
• Rozdzielność wtyczek
• Instalacja
• Praca w repozytorium
• Testy i strażnicy
• CI
• Bezpieczeństwo
• Dokumentacja poza kodem
• Współpraca
• Dokumentacja wtyczki 1 — reszta tego pliku

Stan

Obie wtyczki są testowane do WordPressa 7.0.2. Obie są na licencji GPLv2 — wyłącznie wersja druga, bez klauzuli „or later"; pełny tekst w LICENSE.

Wersja 1.1.0 to wydanie po audycie całości obu wtyczek. Co audyt znalazł i co z tego naprawiono, opisuje katalog audyt/.

Co robi każda wtyczka

AI FAQ Generator (wtyczka 1)

Indeksuje treść witryny, dzieli ją na fragmenty i liczy dla nich embeddingi. Gość pyta, wtyczka szuka pasujących fragmentów i odpowiada tylko wtedy, gdy pokrycie w treści jest wystarczające — poza tematem odmawia zamiast zmyślać. Do tego narzędzie dla właściciela, które układa gotowe zestawy pytań i odpowiedzi.

AI News Portal (wtyczka 2)

Pobiera wpisy z kanałów RSS, odsiewa je słowami wykluczającymi, sprawdza duplikaty, przepisuje materiał modelem i publikuje w Centrum Wiedzy. Przebieg chodzi sam, pod atomowym zamkiem, żeby dwa równoległe uruchomienia nie opublikowały tego samego dwa razy.

Gdzie co leży

.                              wtyczka 1 — korzeń repo
  ai-faq-generator.php         plik główny, stałe AIFAQ_*
  uninstall.php                sprzątanie bez śladu (cała sieć witryn)
  readme.txt                   readme w formacie WordPressa
  src/                         83 pliki — kod wtyczki 1
    Admin/     18              kokpit, ustawienia, metabox
    Index/     11              indeksowanie: chunker, batcher, crawl
    Rest/       9              trasy aifaq/v1
    Data/       8              schemat i repozytoria
    PublicUi/   7              front gościa, nagłówki bezpieczeństwa
    Core/       6              cykl życia, ustawienia, router
    Rag/        6              potok pytania gościa
    App/        5              powłoka aplikacji
    Providers/  4              warstwa modelu (BYOK)
    Faq/        3              publikacja par FAQ
    Http/       3              transport HTTP
    Seo/        2              JSON-LD
  tests/                       63 zestawy + tests/load/ (14 skryptów obciążeniowych)
  assets/                      15 plików — JS, CSS i puste index.php blokujące listowanie
  instrukcje/                  47 plików — 5 PDF-ów, źródła HTML, schematy, zrzuty
  audyt/                       14 plików — opis audytu, raport, dokumentacja zderzana z kodem
  .github/                     workflow „Testy" + CI-owe kopie obu runnerów

ai-news-portal/                wtyczka 2 — 135 plików
  ai-news-portal.php           plik główny, stałe AINP_*
  uninstall.php                własne sprzątanie
  src/         19              15 klas + 4 szablony frontu
  tests/       30              29 zestawów
  instrukcje/  60              5 PDF-ów i ich źródła
  assets/      21

Rozdzielność wtyczek

Wtyczki są w pełni rozdzielne: osobne przestrzenie stałych (AIFAQ_* i AINP_*), osobne uninstall.php, LICENSE, readme.txt i tests/, zero wspólnego kodu. AI News Portal „nie ma żadnej zależności od drugiej wtyczki z tej samej paczki, nie dzieli z nią kodu, opcji ani tabel" (jego README).

[!NOTE] Ta rozdzielność nie jest deklaracją, tylko warunkiem przebiegu testów. Zestaw tests/uninstall-guard-test.php zderza każdy literał z uninstall.php wtyczki 1 z prawdziwymi kluczami wtyczki 2 własnym matcherem LIKE. Napis ainp nie musiałby się w kodzie pojawić, żeby dane drugiej wtyczki zniknęły — strażnik szuka skutku, nie słowa.

Instalacja — każda wtyczka osobno

Wtyczka 1 — AI FAQ Generator. Do wp-content/plugins/ai-faq-generator/ trafia zawartość korzenia repo. Czystą paczkę bez wtyczki 2 daje git archive z tagu wydania wtyczki 1 — drzewo tagu v1.0.0 nie zawiera folderu ai-news-portal/:

git archive v1.0.0 --prefix=ai-faq-generator/ -o ai-faq-generator.zip

Wtyczka 2 — AI News Portal. Do wp-content/plugins/ai-news-portal/ trafia sam folder ai-news-portal/ z repo. Archiwum zachowuje prefiks ścieżki, więc ZIP rozpakowuje się od razu we właściwy katalog:

git archive ai-news-portal-v1.0.0 ai-news-portal -o ai-news-portal.zip

[!TIP] Sklonowanie całego repo prosto do plugins/ uaktywni tylko wtyczkę 1 — ai-news-portal/ai-news-portal.php leży wtedy trzeci poziom pod plugins/, poza zasięgiem skanera WordPressa. Wtyczka 2 wymaga własnego katalogu albo junctiona wskazującego na ai-news-portal/.

Gotowe paczki ZIP wiszą przy wydaniach: https://github.com/mtsle/ai-faq-generator/releases. Katalogi instrukcje/ nie wchodzą do paczek instalacyjnych — klient dostaje PDF-y osobno, obok pliku .zip.

Praca w repozytorium

Potrzebny jest tylko PHP CLI z rozszerzeniem mbstring. Testy nie wymagają bazy danych, sieci ani zainstalowanego WordPressa — zamiast nich chodzą atrapy.

bash .github/ci/testy-wtyczka1.sh
bash .github/ci/testy-wtyczka2.sh

Oba runnery biorą interpreter ze zmiennej PHP i domyślnie wołają php z PATH:

PHP=/sciezka/do/php bash .github/ci/testy-wtyczka1.sh

Zasady pracy, konwencje commitów, wersjonowanie i wymagania wobec nowych testów opisuje osobny dokument: CONTRIBUTING.md.

Testy i strażnicy

Różnica w kryteriach jest historyczna i celowa. Runner wtyczki 2 nie zalicza segmentu, jeśli liczba wykonanych asercji nie zgadza się z zadeklarowaną — test, który po cichu przestał cokolwiek sprawdzać, dalej świeciłby na zielono, a tak przewraca przebieg.

Segmenty wtyczki 2 są ułożone według architektury, więc czyta się je jak mapę kodu:

Segmenty wtyczki 1 są ułożone według kroków budowy (K3–K23), bo powstawały razem z produktem. Pełna lista jest w .github/ci/testy-wtyczka1.sh.

Strażnicy strukturalni

Osobna kategoria zestawów nie sprawdza zachowania, tylko pilnuje własności całego kodu — tego, co łatwo cofnąć jedną porządkującą zmianą i czego zwykły test nie zauważy.