Project-Pro/google-ads-ver-2
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
google-ads-ver-2/AGENTS.md
Jacek Pyziak def1fae0fc update
2026-05-15 20:32:50 +02:00

19 KiB
Raw Permalink Blame History

Instrukcja dla agentow AI

Ten projekt jest terminalowym narzedziem do pracy na kontach Google Ads. Agent AI nie uzywa API modeli. Agent uruchamia komendy terminalowe, czyta pliki z tego katalogu i prowadzi uzytkownika etapami.

Najwazniejszy przeplyw

Uzytkownik nie ma pamietac nazw technicznych zadan.

Gdy uzytkownik napisze:

analiza-zadania

uruchom:

python gads.py analiza-zadania

Pokaz uzytkownikowi pelna liste zadan z podzialem na grupy i opcje zbiorcze, a potem popros o numer. Nie wolno pomijac listy zadan ani zastepowac jej samym komunikatem typu wybierz numer. Jesli wynik komendy zostal skrocony przez narzedzie terminalowe, odczytaj go ponownie albo pokaz liste zadan z config/tasks.toml. Nie koncz odpowiedzi po komunikacie narzedzia typu ... +86 lines albo ctrl+t to view transcript. Jesli interfejs zwinal wynik, przepisz w odpowiedzi pelna liste zadan i opcji zbiorczych na podstawie widocznego wyniku albo config/tasks.toml, a dopiero potem popros o numer.

Po wyborze zadania w trybie analiza-zadania obsluguj klientow pojedynczo. Nie wolno uruchomic zadania dla wszystkich klientow, a potem pokazac jednej zbiorczej tabeli Podsumowanie po klientach jako glownego wyniku. Dla kazdego klienta osobno:

  1. uruchom plan-only dla wybranego zadania,
  2. odczytaj plan tego klienta,
  3. pokaz konkretne problemy, rekomendacje i ewentualne zmiany dla tego jednego klienta,
  4. zapytaj uzytkownika, co zrobic z tym klientem,
  5. dopiero po decyzji uzytkownika przejdz do kolejnego klienta.

Jesli zadanie nie ma zmian do wdrozenia, nadal pokaz pelna liste problemow i rekomendacji dla tego klienta, a potem zapytaj, czy przejsc do kolejnego klienta. Nie zastepuj tego zbiorczym podsumowaniem wszystkich klientow.

Gdy uzytkownik napisze:

analiza-klienta

uruchom:

python gads.py analiza-klienta

Pokaz uzytkownikowi liste klientow i popros o numer. Liste klientow pokazuj jako tabele terminalowa z kolumnami Nr i Domena, np.:

Zawsze pokazuj pelna liste klientow widoczna w terminalu. Nie streszczaj jej tekstem typu Masz 10 klientow. Nie ukrywaj listy za komunikatem o rozwinieciu wyniku narzedzia, np. +24 lines albo ctrl+o to expand. Jesli wynik komendy zostal skrocony przez narzedzie terminalowe, odczytaj go ponownie albo uruchom komende tak, zeby pokazac uzytkownikowi cala tabele klientow.

┌────┬──────────────────────┐
│ Nr │ Domena               │
├────┼──────────────────────┤
│ 1  │ aruba.rzeszow.pl     │
└────┴──────────────────────┘

Po wyborze numeru klienta uruchom:

python gads.py analiza-klienta --client-number <numer>

Pokaz uzytkownikowi liste zadan. Zadania musza byc prezentowane z podzialem na grupy nadrzedne, np. KAMPANIE PLA, WYKLUCZENIA, KAMPANIE SEARCH. Nie wolno pokazywac samej tabeli zadan bez naglowka grupy. Nawet gdy jest tylko jedna grupa i jedno zadanie, pokaz naglowek grupy. Nie wolno laczyc zadan i opcji zbiorczych w jednej tabeli. Zadania sa w tabelach pod naglowkami grup, a opcje zbiorcze sa w osobnej sekcji Opcje zbiorcze.

Nie pokazuj tak:

┌─────┬─────────────────────────────────┐
│ Nr  │ Zadanie                         │
├─────┼─────────────────────────────────┤
│ 1.1 │ Synchronizacja kampanii PLA_CL1 │
│ 1.2 │ Sprawdzenie ustawien            │
│ 1.0 │ Wszystkie z grupy PLA           │
│ ALL │ Wszystkie zadania               │
└─────┴─────────────────────────────────┘

To jest bledne, bo miesza pojedyncze zadania z wyborami zbiorczymi i usuwa naglowek grupy.

Format listy zadan:

Klient: investagd.pl

========================================================================
KAMPANIE PLA
========================================================================
┌────┬─────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────┐
│ Nr  │ Zadanie                         │ Opis                                                                                      │
├────┼─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
│ 1.1 │ Synchronizacja kampanii PLA_CL1 │ Porownuje kampanie [PLA_CL1] z produktami w adsPRO i przygotowuje plan zmian grup reklam. │
└────┴─────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────┘

W kazdej grupie pokazuj zadania jako tabele terminalowa z kolumnami Nr, Zadanie, Opis. Po tabelach zadan pokaz tez Opcje zbiorcze:

Opcje zbiorcze
┌─────┬────────────────────────────────────────────┐
│ Nr  │ Zakres                                     │
├─────┼────────────────────────────────────────────┤
│ 1.0 │ Wszystkie zadania z grupy: Kampanie PLA    │
├─────┼────────────────────────────────────────────┤
│ ALL │ Wszystkie zadania ze wszystkich grup       │
└─────┴────────────────────────────────────────────┘

Numeracja ma format grupa.zadanie. Przyklad: 1.1 to pierwsze zadanie w pierwszej grupie, 2.3 to trzecie zadanie w drugiej grupie. Opcja zbiorcza grupy zawsze konczy sie na .0, np. 1.0, 2.0. ALL pokazuj tylko raz na koncu listy opcji zbiorczych.

Jesli uzytkownik wybierze numer pojedynczego zadania, uruchom tylko to zadanie. Jesli uzytkownik wybierze 1.0, 2.0 itd., uruchom wszystkie zadania z tej grupy po kolei. Jesli uzytkownik wybierze ALL, uruchom wszystkie zadania ze wszystkich grup po kolei.

W trybie zbiorczym NIE zbieraj wszystkich planow do jednej wspolnej decyzji. Kazde zadanie obsluguj osobno:

  1. uruchom --plan-only dla pierwszego zadania,
  2. przeczytaj plan pierwszego zadania,
  3. pokaz krotka analize pierwszego zadania,
  4. zapytaj, czy wdrozyc ten jeden plan,
  5. po decyzji uzytkownika wdroz albo pomin ten jeden plan,
  6. dopiero potem przejdz do kolejnego zadania.

Nie pytaj: Czy wdrozyc oba plany?. Pytaj: Czy wdrozyc plan zadania 1/2?.

Po wyborze numeru zadania uruchom najpierw tylko przygotowanie planu:

python gads.py analiza-klienta --client-number <numer-klienta> --task-number <numer-zadania> --plan-only

Preferowana komenda dla wyboru z listy:

python gads.py analiza-klienta --client-number <numer-klienta> --select <wybor> --plan-only

Po wyborze calej grupy uruchom:

python gads.py analiza-klienta --client-number <numer-klienta> --select 1.0 --plan-only

Po wyborze wszystkich grup uruchom:

python gads.py analiza-klienta --client-number <numer-klienta> --select ALL --plan-only

Zadania zbiorcze musza isc sekwencyjnie: nastepne zadanie startuje dopiero po zakonczeniu poprzedniego, lacznie z decyzja uzytkownika o wdrozeniu albo pominieciu planu.

Nastepnie odczytaj zapisany plan z:

clients/<domena>/plans/

Przeanalizuj plan krotko i konkretnie. Nie wdrazaj zmian bez zgody uzytkownika.

Po akceptacji uzytkownika uruchom wdrozenie dokladnie zapisanego planu:

python gads.py analiza-klienta --client-number <numer-klienta> --task-number <numer-zadania> --apply-plan <sciezka-do-planu-json> --confirm-apply TAK

Po wykonaniu zadania, odrzuceniu planu albo decyzji o niewdrazaniu zmian zapytaj uzytkownika, co dalej:

Co dalej?
1. Lista zadan tego samego klienta
2. Lista klientow
3. Zakoncz

Popros uzytkownika tylko o numer. Po wyborze:

  • 1 pokaz liste zadan tego samego klienta,
  • 2 pokaz liste klientow,
  • 3 zakoncz.

Raport klienta

Gdy uzytkownik poprosi o raport klienta albo poda komende w stylu:

analiza-klienta aruba.rzeszow.pl 02-2026

uruchom:

python gads.py analiza-klienta aruba.rzeszow.pl 02-2026

To jest alias dla generowania miesiecznego raportu HTML klienta. Obslugiwane sa formaty miesiaca MM-YYYY, MM.YYYY i YYYY-MM.

Jesli uzytkownik napisze tylko:

raport-klienta

uruchom:

python gads.py raport-klienta

Pokaz uzytkownikowi liste klientow i popros o numer. Po wyborze klienta oraz miesiaca uruchom:

python gads.py raport-klienta --client-number <numer-klienta> --month <YYYY-MM>

Komenda najpierw pobiera dane i zatrzymuje sie przed generowaniem HTML. Tworzy plik roboczy:

scripts/reports/output/<domena>_<YYYY-MM>_recommendations.json

Wnioski i rekomendacje przygotowuje agent AI, nie skrypt. Agent ma przeczytac dane raportu i kontekst w pliku rekomendacji, uzupelnic recommendations konkretnymi wnioskami, pokazac je uzytkownikowi i zapytac o akceptacje.

Wnioski pisz z perspektywy osoby, ktora obsluguje konto Google Ads klienta. Nie pisz do klienta, ze warto cos sprawdzic, trzeba zweryfikowac albo nalezy przeanalizowac, jakby decyzja byla po jego stronie. Pisz decyzyjnie: co robimy, co zostawiamy, co ograniczamy, co kontrolujemy i jaki jest nastepny krok po naszej stronie. Unikaj bezosobowych, nijakich rekomendacji.

W tekstach raportu dla klienta uzywaj poprawnych polskich znakow. Dotyczy to szczegolnie tytulow, wnioskow i rekomendacji w pliku recommendations. Nie zapisuj tam wersji bez ogonkow typu zwiekszamy, wartosc, srednia, jezeli tekst trafi do HTML widocznego dla klienta.

Po akceptacji wnioskow uruchom:

python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-recommendations TAK

Dopiero wtedy komenda generuje lokalny raport HTML w:

scripts/reports/output/<domena>/<YYYY-MM>/index.html

Jeżeli klient ma w config/clients.toml ustawione sales_history_sheet, historia sprzedaży miesięcznej oraz trzy kafelki w sekcji E-commerce — Sprzedaż mają pochodzić z tego arkusza Google Sheet. Arkusz powinien zawierać kolumny: Miesiąc, Transakcje, Przychody, Średnia wartość koszyka. Nie zastępuj tych danych GA4, jeżeli arkusz jest skonfigurowany.

Po wygenerowaniu raportu pokaz uzytkownikowi sciezke do pliku i popros o akceptacje przed wysylka na serwer. Nie wysylaj raportu bez jasnej zgody uzytkownika.

Po akceptacji uruchom upload:

python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-upload TAK

Po wysylce podaj URL:

https://adspro.projectpro.pl/raporty/<slug>/<YYYY-MM>/

Zasady komunikacji

  • Pisz po polsku.
  • Prowadz uzytkownika etapami: klient -> grupa zadan -> zadanie -> plan -> akceptacja -> wdrozenie.
  • Nie wymagaj od uzytkownika zapamietywania technicznych identyfikatorow zadan.
  • Nie uzywaj skrotow bez potrzeby. Pisz grupa reklam, nie AG.
  • Pisz wdrozenie zmian, nie mutacja.
  • Pisz Docelowy ROAS, nie tROAS, chyba ze cytujesz nazwe techniczna.
  • Odpowiedzi analityczne maja byc krotkie: co zostanie zrobione, ile elementow, jakie ryzyko, czy rekomendujesz wdrozenie.
  • Odpowiedzi analityczne po odczytaniu planu musza zawierac tabele. Nie streszczaj planu samymi punktami.

Minimalny format analizy planu:

Zadanie 1/2: Synchronizacja kampanii PLA_CL1

Podsumowanie po kampaniach
┌──────────────────────┬────────┬───────┬───────────┬─────────────┐
│ Kampania             │ Utworz │ Wlacz │ Wstrzymaj │ Zmien nazwe │
├──────────────────────┼────────┼───────┼───────────┼─────────────┤
│ [PLA_CL1] pozostale  │ 0      │ 1     │ 0         │ 0           │
│ [PLA_CL1] worki      │ 0      │ 8     │ 0         │ 0           │
└──────────────────────┴────────┴───────┴───────────┴─────────────┘

Najwazniejsze dzialania
┌────┬─────────────────────┬────────────────────────────────────────┐
│ Nr │ Kampania            │ Dzialanie                              │
├────┼─────────────────────┼────────────────────────────────────────┤
│ 1  │ [PLA_CL1] pozostale │ Wlacz grupe reklam: nazwa grupy        │
└────┴─────────────────────┴────────────────────────────────────────┘

Ryzyko: niskie.
Rekomendacja: wdrozyc.

Jesli lista dzialan jest dluga, pokaz tabele z pierwszymi 10 pozycjami i dopisz liczbe pozostalych. Nadal pokaz pelne podsumowanie po kampaniach.

Bezpieczenstwo

  • Najpierw zawsze tworz plan przez --plan-only.
  • Nie wdrazaj planu, dopoki uzytkownik jasno nie zaakceptuje.
  • Wdrazaj tylko plan zapisany w pliku JSON.
  • Po wdrozeniu sprawdz i podaj sciezki historii:
    • clients/<domena>/history/YYYY-MM-DD.jsonl
    • clients/<domena>/changes/YYYY-MM-DD.md
  • Po wykonaniu albo odrzuceniu zadania zawsze zaproponuj powrot do listy zadan albo listy klientow.

Konfiguracja zadan

Lista grup i zadan jest w:

config/tasks.toml

Dodawaj nowe zadania do odpowiednich grup, z czytelna nazwa dla uzytkownika.

Szczegolowa instrukcja rozbudowy narzedzia jest w:

DEVELOPMENT.md

Zadania: Produkty

Grupa Produkty jest podzielona na trzy osobne zadania:

  • Optymalizacja tytulow produktow pobiera z adsPRO tylko produkty bez zoptymalizowanego tytulu.
  • Optymalizacja kategorii Google pobiera z adsPRO tylko produkty bez kategorii Google.
  • Uzupelnienie unit pricing pobiera z adsPRO tylko produkty bez unit pricing.

Nie mieszaj tych zakresow w jednym planie. Tytuly produktow wybiera agent AI po analizie produktu, tytulu bazowego, strony produktu albo kontekstu klienta. Kategorie Google wybiera agent AI po analizie produktu, tytulu, strony produktu albo kontekstu klienta. Skrypt nie wybiera automatycznie tytulow ani kategorii Google. Przed wdrozeniem tytulow agent musi uzupelnic docelowe wartosci tytulow w zapisanym planie JSON i dopiero wtedy zapytac uzytkownika o zgode. Przed wdrozeniem kategorii agent musi uzupelnic docelowe wartosci kategorii w zapisanym planie JSON i dopiero wtedy zapytac uzytkownika o zgode. Unit pricing moze byc proponowany przez skrypt, jezeli da sie go jednoznacznie odczytac z nazwy produktu.

Reczne przypisywanie regul

Gdy uzytkownik napisze:

Przypisz regule:
- tresc reguly do oceny

agent ma potraktowac to jako prosbe o kuracje pojedynczej reguly wiedzy.

Kolejnosc pracy:

  1. Sprawdz aktualne grupy i zadania w config/tasks.toml.
  2. Nie przywracaj usunietych zadan ani grup. Jesli lista zadan jest ograniczona, uznaj to za swiadoma decyzje uzytkownika.
  3. Ocen, czy regule warto dodac do narzedzia.
  4. Zaproponuj docelowe brzmienie reguly: condition, recommendation, risk, rule_type, topic, confidence i docelowe task_ids.
  5. Zaproponuj policzalny machine_condition i machine_effect, jezeli regule da sie bezpiecznie zastosowac w skrypcie na danych pobieranych przez dane zadanie.
  6. machine_condition ma uzywac tylko pol, ktore naprawde istnieja w planie danego zadania, np. channel_type, conversions_30d, bidding_strategy_type, budget_context, search_budget_lost_impression_share.
  7. Jesli nie da sie zbudowac bezpiecznego warunku maszynowego, napisz to wprost i zaproponuj zapis reguly bez automatycznego wplywu, jako kontekst dla agenta AI/czlowieka.
  8. Uzywaj tylko istniejacych identyfikatorow zadan z config/tasks.toml.
  9. Jesli nie ma dobrego zadania, powiedz, ze regule lepiej odlozyc albo dodac dopiero po utworzeniu nowego zadania.
  10. Nie zapisuj reguly do knowledge/rules.jsonl, dopoki uzytkownik jasno nie odpowie Dodaj.
  11. Po odpowiedzi Dodaj dopisz jedna kompletna linie JSONL do knowledge/rules.jsonl.

Przy zapisie do knowledge/rules.jsonl uzupelnij pola: id, status, topic, task_ids, suggested_task_ids, rule_type, condition, recommendation, risk, source, source_file, confidence, duplicate_of, supersedes, text, created_at, updated_at. Jezeli regula ma dzialac automatycznie, dodaj tez machine_condition i machine_effect.

Przyklad policzalnej czesci reguly:

{
  "machine_condition": {
    "all": [
      {"field": "channel_type", "op": "eq", "value": "SEARCH"},
      {"field": "conversions_30d", "op": "lt", "value": 15},
      {"field": "bidding_strategy_type", "op": "in", "value": ["MAXIMIZE_CONVERSIONS", "TARGET_CPA", "MAXIMIZE_CONVERSION_VALUE", "TARGET_ROAS"]}
    ]
  },
  "machine_effect": {
    "level": "ostroznie",
    "action": "nie przechodz na automatyzacje konwersyjna",
    "reason_prefix": "Regula wiedzy"
  }
}

Ten tryb jest reczna alternatywa dla komendy:

python gads.py wiedza przypisz

Reguly i wyjatki klientow

Ustawienia globalne i wyjatki per klient sa w:

config/clients.toml

Przyklad globalnych regul dla kampanii PLA:

[global_rules.pla_settings]
require_presence_only = true
require_high_priority = true

Wyjatek per klient:

[clients."example.pl".pla_settings]
require_high_priority = false

Jesli klient ma wylaczona regule, agent nie powinien sugerowac wdrozenia tej zmiany.

Reference in New Issue View Git Blame Copy Permalink