199 lines
8.6 KiB
Markdown
199 lines
8.6 KiB
Markdown
# 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/<domena>/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/<domena>_<YYYY-MM>_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/<domena>/<YYYY-MM>/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/<id>"
|
|
```
|
|
|
|
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/<domena>/data/` - pobrane dane robocze.
|
|
- `clients/<domena>/history/YYYY-MM-DD.jsonl` - historia do filtrowania po kliencie, dacie i kampanii.
|
|
- `clients/<domena>/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 "<id_reguly>" --task "<task_id>"
|
|
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 "<id_reguly>"
|
|
python gads.py wiedza aktywuj --rule-id "<id_reguly>"
|
|
python gads.py wiedza duplikat --rule-id "<id_reguly>" --duplicate-of "<id_reguly_nadrzednej>"
|
|
```
|
|
|
|
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.
|