first commit
This commit is contained in:
271
.sync/Archive/AGENTS.md
Normal file
271
.sync/Archive/AGENTS.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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