first commit
This commit is contained in:
397
AGENTS.md
Normal file
397
AGENTS.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
analiza-klienta
|
||||
```
|
||||
|
||||
uruchom:
|
||||
|
||||
```powershell
|
||||
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.
|
||||
|
||||
```text
|
||||
┌────┬──────────────────────┐
|
||||
│ Nr │ Domena │
|
||||
├────┼──────────────────────┤
|
||||
│ 1 │ aruba.rzeszow.pl │
|
||||
└────┴──────────────────────┘
|
||||
```
|
||||
|
||||
Po wyborze numeru klienta uruchom:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```text
|
||||
┌─────┬─────────────────────────────────┐
|
||||
│ 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:
|
||||
|
||||
```text
|
||||
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`:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```powershell
|
||||
python gads.py analiza-klienta --client-number <numer-klienta> --task-number <numer-zadania> --plan-only
|
||||
```
|
||||
|
||||
Preferowana komenda dla wyboru z listy:
|
||||
|
||||
```powershell
|
||||
python gads.py analiza-klienta --client-number <numer-klienta> --select <wybor> --plan-only
|
||||
```
|
||||
|
||||
Po wyborze calej grupy uruchom:
|
||||
|
||||
```powershell
|
||||
python gads.py analiza-klienta --client-number <numer-klienta> --select 1.0 --plan-only
|
||||
```
|
||||
|
||||
Po wyborze wszystkich grup uruchom:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```text
|
||||
clients/<domena>/plans/
|
||||
```
|
||||
|
||||
Przeanalizuj plan krotko i konkretnie. Nie wdrazaj zmian bez zgody uzytkownika.
|
||||
|
||||
Po akceptacji uzytkownika uruchom wdrozenie dokladnie zapisanego planu:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
analiza-klienta aruba.rzeszow.pl 02-2026
|
||||
```
|
||||
|
||||
uruchom:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```text
|
||||
raport-klienta
|
||||
```
|
||||
|
||||
uruchom:
|
||||
|
||||
```powershell
|
||||
python gads.py raport-klienta
|
||||
```
|
||||
|
||||
Pokaz uzytkownikowi liste klientow i popros o numer. Po wyborze klienta oraz miesiaca uruchom:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```powershell
|
||||
python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-recommendations TAK
|
||||
```
|
||||
|
||||
Dopiero wtedy komenda generuje lokalny raport HTML w:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```powershell
|
||||
python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-upload TAK
|
||||
```
|
||||
|
||||
Po wysylce podaj URL:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
config/tasks.toml
|
||||
```
|
||||
|
||||
Dodawaj nowe zadania do odpowiednich grup, z czytelna nazwa dla uzytkownika.
|
||||
|
||||
Szczegolowa instrukcja rozbudowy narzedzia jest w:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```powershell
|
||||
python gads.py wiedza przypisz
|
||||
```
|
||||
|
||||
## Reguly i wyjatki klientow
|
||||
|
||||
Ustawienia globalne i wyjatki per klient sa w:
|
||||
|
||||
```text
|
||||
config/clients.toml
|
||||
```
|
||||
|
||||
Przyklad globalnych regul dla kampanii PLA:
|
||||
|
||||
```toml
|
||||
[global_rules.pla_settings]
|
||||
require_presence_only = true
|
||||
require_high_priority = true
|
||||
```
|
||||
|
||||
Wyjatek per klient:
|
||||
|
||||
```toml
|
||||
[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
Block a user