# Google Ads ver 2 Terminalowe narzedzie do pracy na kontach Google Ads klientow. Instrukcja pracy dla Claude Code, Codex, Gemini CLI i innych agentow AI jest w `AGENTS.md`. Instrukcja rozbudowy o nowe grupy i zadania jest w `DEVELOPMENT.md`. Backlog rzeczy sprawdzanych w starej wersji jest w `OLD_COMMANDS_CHECKLIST.md`. ## Start 1. Uzupelnij `.env` na podstawie `.env.example`. 2. Uzupelnij `config/clients.toml` na podstawie `config/clients.example.toml`. 3. Zainstaluj zaleznosci: ```powershell python -m pip install -r requirements.txt ``` 4. Uruchom menu: ```powershell python gads.py ``` Albo uruchom konkretne zadanie bez menu: ```powershell python gads.py --client laitica.pl --task sync_pla_cl1 ``` Tryb dla Claude Code, Codex albo Gemini CLI: ```powershell python gads.py analiza-klienta python gads.py analiza-klienta --client-number 5 python gads.py analiza-klienta --client-number 5 --task-number 1 --plan-only ``` Po tej komendzie narzedzie zapisze plan w `clients//plans/`. Agent czyta plik `.md` albo `.json`, analizuje go i pyta Cie o zgode. Po Twojej akceptacji agent uruchamia wdrozenie konkretnego planu: ```powershell python gads.py --client laitica.pl --task sync_pla_cl1 --apply-plan clients/laitica.pl/plans/PLAN.json --confirm-apply TAK ``` ## Raport klienta Miesieczny raport HTML generuje komenda: ```powershell python gads.py raport-klienta python gads.py raport-klienta --client-number 1 --month 2026-04 python gads.py raport-klienta aruba.rzeszow.pl 04.2026 python gads.py analiza-klienta aruba.rzeszow.pl 02-2026 ``` Komenda pobiera dane Google Ads, opcjonalnie GA4, e-commerce, Semstorm i linki SEO, a potem zatrzymuje sie przed generowaniem HTML. Tworzy plik roboczy z kontekstem liczbowym i miejscem na wnioski przygotowane przez agenta AI: ```text scripts/reports/output/__recommendations.json ``` Skrypt nie generuje wnioskow samodzielnie. Agent AI uzupelnia `recommendations` w tym pliku z perspektywy osoby obslugujacej konto Google Ads klienta: decyzyjnie opisuje, co robimy, co kontrolujemy i jaki jest nastepny krok po naszej stronie. Nie pisze klientowi, ze `warto cos sprawdzic` albo `nalezy przeanalizowac`, bo to agent/operator konta podejmuje decyzje. Tytuly, wnioski i rekomendacje widoczne dla klienta musza miec poprawne polskie znaki. Po pokazaniu propozycji i akceptacji uzytkownika agent uruchamia: ```powershell python gads.py raport-klienta --client aruba.rzeszow.pl --month 2026-04 --confirm-recommendations TAK ``` Po zatwierdzeniu wnioskow raport HTML jest zapisywany w: ```text scripts/reports/output///index.html ``` Historia sprzedaży miesięcznej oraz trzy kafelki w sekcji `E-commerce — Sprzedaż` mogą być zasilane z Google Sheet przypisanego do klienta: ```toml [clients."example.pl"] sales_history_sheet = "https://docs.google.com/spreadsheets/d/" ``` Arkusz powinien mieć kolumny: `Miesiąc`, `Transakcje`, `Przychody`, `Średnia wartość koszyka`. Upload na serwer nie wykonuje sie automatycznie. Po sprawdzeniu lokalnego raportu uruchom: ```powershell python gads.py raport-klienta --client aruba.rzeszow.pl --month 2026-04 --confirm-upload TAK ``` Wymagane dane FTP w `.env`: `ADSPRO_HOST`, `ADSPRO_USERNAME`, `ADSPRO_PASSWORD`, `ADSPRO_REMOTE_PATH`. ## MVP Pierwsze zadanie: - pobiera kampanie `[PLA_CL1]` z Google Ads, - wyciaga segmenty CL1 z nazw kampanii, - pobiera produkty z adsPRO, - przygotowuje plan synchronizacji grup reklam, - czeka na akceptacje przed wdrozeniem zmian, - zapisuje historie w katalogu klienta. ## Dane i historia - `config/clients.toml` - lista klientow i identyfikatory kont. - `config/clients.toml` - takze reguly globalne i wyjatki per klient, np. ustawienia kampanii PLA. - `config/clients.toml` - takze pominiecia zadan przy wyborze `ALL`, np. `skip_in_all` w sekcji klienta. - `.env` - dane dostepowe do Google Ads i adsPRO. - `clients//data/` - pobrane dane robocze. - `clients//history/YYYY-MM-DD.jsonl` - historia do filtrowania po kliencie, dacie i kampanii. - `clients//changes/YYYY-MM-DD.md` - czytelny dziennik zmian. ## Lokalna baza wiedzy Baza wiedzy ma lokalny magazyn regul i opcjonalny importer przez API. API modeli jest uzywane tylko przy dodawaniu nowej wiedzy, nie podczas analizy klienta. ```powershell python gads.py wiedza init python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" --dry-run python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" python gads.py wiedza propozycje python gads.py wiedza zatwierdz --rule-id "" --task "" python gads.py wiedza szukaj "pmax shopping" python gads.py wiedza reguly --task check_pla_settings python gads.py wiedza lista --topic shopping python gads.py wiedza statystyki python gads.py wiedza indeksuj python gads.py wiedza szukaj-ai "czy PMax kanibalizuje Display?" python gads.py wiedza import-stare --from "D:\google ads\lancedb" python gads.py wiedza przypisz ``` Pliki bazy wiedzy: - `knowledge/sources/` - materialy zrodlowe do pozniejszego importu. - `knowledge/rules.jsonl` - atomowe reguly dla narzedzia. - `knowledge/imports.jsonl` - historia importow. - `knowledge/lancedb/` - metadane indeksu semantycznego. Fizyczny indeks LanceDB jest domyslnie w `%LOCALAPPDATA%\google-ads-ver2-knowledge-lancedb`, zeby uniknac problemow zapisu w katalogach synchronizowanych. Na innym komputerze przenosi sie `rules.jsonl`, a indeks LanceDB odbudowuje sie lokalnie: ```powershell python gads.py wiedza indeksuj ``` Stara baza LanceDB moze byc przeniesiona jednorazowo bez przypisywania do zadan: ```powershell python gads.py wiedza import-stare --from "D:\google ads\lancedb" ``` Pozniejsze przypisywanie nieprzypisanych regul do aktualnych zadan: ```powershell python gads.py wiedza przypisz python gads.py wiedza przypisz --restart ``` `wiedza przypisz` domyslnie pokazuje jedna regule, pelny kontekst decyzji i konczy porcje po odpowiedzi. Reguly ida w kolejnosci zapisanej w `knowledge/rules.jsonl`, zeby latwo bylo porownac ekran z otwartym plikiem. W przegladzie mozna wpisac numer zadania albo `task_id`, `P` zeby pominac, `Q` zeby przerwac, oraz `U` zeby usunac biezaca regule z `knowledge/rules.jsonl`. Usuniecie wymaga dodatkowego potwierdzenia `USUN`; po usunieciach odswiez indeks przez `python gads.py wiedza indeksuj`. Reczne dodawanie pojedynczej reguly przez agenta AI: ```text Przypisz regule: - tresc reguly do oceny ``` Agent najpierw sprawdza aktualne zadania w `config/tasks.toml`, ocenia czy regule warto dodac, proponuje docelowe brzmienie, typ, temat, ryzyko, rekomendacje i zadanie docelowe. Przy kazdej regule agent musi tez zaproponowac policzalny `machine_condition` i `machine_effect`, jezeli regule da sie bezpiecznie zastosowac w skrypcie. Jesli regula wymaga oceny eksperckiej albo danych, ktorych zadanie nie pobiera, agent ma jasno napisac, ze nie proponuje automatycznego warunku i regule nalezy traktowac jako kontekst dla agenta AI/czlowieka. Agent nie zapisuje nic do `knowledge/rules.jsonl`, dopoki uzytkownik jasno nie odpowie `Dodaj`. Po akceptacji agent dopisuje jedna kompletna linie JSONL do `knowledge/rules.jsonl`, uzywajac tylko istniejacych `task_id`. Jesli nie ma dobrego zadania, agent powinien zaproponowac niedodawanie reguly albo odlozenie jej do czasu dodania nowego zadania. `machine_condition` opisuje twarde warunki na polach dostepnych w planie zadania, np. `channel_type`, `conversions_30d`, `bidding_strategy_type`. `machine_effect` opisuje wplyw na rekomendacje, np. poziom ostroznosci, akcje i powod. Skrypt moze automatycznie stosowac tylko takie reguly, ktore maja policzalny warunek oparty o dostepne dane. Wieksza porcje przegladu uruchamiaj jawnie: ```powershell python gads.py wiedza przypisz --limit 10 ``` Po imporcie skrypt pokazuje proponowane powiazania regul z zadaniami i pyta, czy dopisac je do `task_ids`. Bez odpowiedzi `TAK` propozycja zostaje oczekujaca albo odrzucona, ale nie staje sie regula zadania. Przy wiekszej bazie uzywaj statusow zamiast recznego kasowania regul: ```powershell python gads.py wiedza archiwizuj --rule-id "" python gads.py wiedza aktywuj --rule-id "" python gads.py wiedza duplikat --rule-id "" --duplicate-of "" ``` Do importu przez API dodaj do `.env`: ```text OPENAI_API_KEY=... KNOWLEDGE_OPENAI_MODEL=gpt-4.1-mini KNOWLEDGE_EMBEDDING_MODEL=text-embedding-3-small KNOWLEDGE_LANCEDB_DIR=C:\opcjonalna\sciezka\poza\synchronizacja ``` Narzedzie nie uzywa API modeli AI podczas analizy klienta. Claude Code, Codex albo Gemini CLI moga uruchamiac te same komendy terminalowe.