Przewodnik użytkownika Chat

Ten przewodnik pokazuje krok po kroku jak używać modułu Chat do interaktywnej komunikacji z Claude AI.

Tworzenie nowej sesji

1. Otwórz stronę Chat

Przejdź do: http://localhost:8080/chat

2. Wybierz worker

Na stronie głównej Chat zobaczysz listę dostępnych workerów:

📦 SemBot Frontend (angular)
📦 SemBot Backend (laravel)
📦 SemBot Test Automation
📦 Code gen manager

3. Kliknij na wybrany worker

System automatycznie:

Utworzy nowy UUID sesji
Utworzy katalog .chat/{uuid}/
Zapisze plik chat.json z metadanymi
Przekieruje do strony sesji /chat/{uuid}

4. Wypełnij metadata (opcjonalne)

Po utworzeniu sesji możesz edytować metadane w pliku chat.json:

json

{
  "session_id": "generated-uuid",
  "task_id": "TASK-001",
  "task_link": "https://github.com/org/repo/issues/123",
  "title": "Implementacja modułu zarządzania użytkownikami",
  "description": "Konwersacja dotycząca implementacji...",
  "author": "712020:499ddb09-7cab-4147-910d-d38e7b2fa575"
}

Interfejs sesji Chat

Layout strony

┌─────────────────────────────────────────────────────────┬──────────────┐
│ Header:                                                 │ [Info] [x]   │
│ 📘 Implementacja modułu zarządzania użytkownikami      │              │
│ 👤 Tomasz Kowalski  📋Task | 🐙GitHub | 💬Chat         │              │
│ 🔗 TASK-001                                             │              │
├─────────────────────────────────────────────────────────┤              │
│ Tabs: [💬 Chat] [🐳 Docker]                            │              │
│                                                         │   Sidebar    │
│ ┌─────────────────────────────────────────────────┐   │  (Szczegóły) │
│ │ [Textarea: wpisz wiadomość...]      [Wyślij]    │   │              │
│ └─────────────────────────────────────────────────┘   │              │
├─────────────────────────────────────────────────────────┤              │
│                                                         │              │
│ Message Area (newest at top):                          │              │
│                                                         │              │
│ ┌───────────────────────────────────────────────────┐ │              │
│ │ 🤖 Asystent                            12:04      │ │              │
│ │ Odpowiedź na pytanie...                           │ │              │
│ │ [📋 Pokaż output]                                  │ │              │
│ └───────────────────────────────────────────────────┘ │              │
│ ┌───────────────────────────────────────────────────┐ │              │
│ │ 👤 Ty                                  12:04      │ │              │
│ │ która jest godzina?                               │ │              │
│ └───────────────────────────────────────────────────┘ │              │
│                                                         │              │
└─────────────────────────────────────────────────────────┴──────────────┘

Elementy interfejsu

Tytuł - z pliku chat.json (title)
Autor - nazwa + linki do Task, GitHub, Chat
Task ID - jeśli skonfigurowany, kliknięcie otwiera task_link
Przycisk Info - pokazuje/ukrywa sidebar z szczegółami

Tabs

💬 Chat - główny widok konwersacji
🐳 Docker - logi kontenera Docker (jeśli używany)

Input Area

Textarea - pole na wpisanie wiadomości
Przycisk Wyślij - wysyła wiadomość do Claude

Message Area

Wiadomości - wyświetlane jako pary Q&A
Kolejność - newest at top (Answer powyżej Question)
Output toggle - przycisk do pokazania/ukrycia raw output LLM

Pokazuje metadane sesji:

Tytuł i opis
Task ID i link (jeśli skonfigurowany)
Lista workerów
Executor i model
Statystyki (liczba wiadomości, daty)

Wysyłanie wiadomości

1. Wpisz pytanie

W textarea wpisz pytanie lub instrukcję dla Claude:

która jest godzina?

2. Kliknij "Wyślij"

System:

Wysyła request POST /api/chat/sessions/{uuid}/messages
Wykonuje Claude CLI: claude --session {uuid} "która jest godzina?"
Zapisuje parę Q&A w messages/msg_{timestamp}_{id}.json
Zapisuje raw output w llm_outputs/claude_{timestamp}.json
Zwraca odpowiedź do frontendu

3. Odpowiedź pojawia się automatycznie

Frontend:

Dodaje wiadomość do listy (Answer na górze)
Pokazuje output toggle button (jeśli jest output)
Przewija widok do najnowszej wiadomości

Przykład pary Q&A

Question (Ty):

która jest godzina?

Answer (Asystent):

Aktualna godzina to 12:04.

[📋 Pokaż output]

Przykład z output toggle

Po kliknięciu "Pokaż output":

┌─────────────────────────────────────────────────┐
│ Raw Output (JSON Lines):                        │
├─────────────────────────────────────────────────┤
│ {"type":"system","subtype":"init",...}          │
│ {"type":"assistant","message":{...}}            │
│ {"type":"result","subtype":"success",...}       │
└─────────────────────────────────────────────────┘

Output jest renderowany przez utils.FormatClaudeOutput() - ten sam parser co w tasks.

Slash commands (komendy specjalne)

Chat obsługuje slash commands dla szybkich operacji:

`/podsumuj`

Podsumowuje konwersację:

/podsumuj

`/wyjasnij`

Wyjaśnia ostatni kod lub koncepcję:

/wyjasnij

`/utworz_taska`

Tworzy task z konwersacji:

/utworz_taska

Praca z Docker

Kiedy używać Docker?

Docker executor jest używany gdy:

Worker ma docker_compose_path w konfiguracji
Chcesz izolowane środowisko z pełnym projektem
Potrzebujesz świeżego klona repozytorium
Chcesz oddzielić sesje Chat od lokalnego środowiska

Jak działa Docker w Chat?

System tworzy kontener chat-{uuid}
Montuje katalog sesji .chat/{uuid}/ jako /app/session
Montuje zasoby Claude Code jako /app/worker/.claude
Klonuje repozytoria do /app/worker/{repo-name}
Instaluje Claude CLI w kontenerze
Wykonuje komendy w kontekście kontenera

Docker tab

Zakładka 🐳 Docker pokazuje:

Status kontenera

Container: chat-abc123...
Status: Running ✅
Worker: sbf (SemBot Frontend angular)

Logi kontenera

[2025-10-06 12:04:03] 📦 Installing dependencies...
[2025-10-06 12:04:05] ✅ git installed
[2025-10-06 12:04:06] ⬇️ Installing Claude CLI...
[2025-10-06 12:04:10] ✅ Claude CLI installed
[2025-10-06 12:04:11] 🔑 Setting up SSH...
[2025-10-06 12:04:12] 📂 Cloning repositories...
[2025-10-06 12:04:20] ✅ Cloned: sembot-angular
[2025-10-06 12:04:21] ✅ Container ready

Zarządzanie kontenerem Docker

Kontenery są zarządzane automatycznie, ale możesz też:

Sprawdzić status

bash

curl http://localhost:8080/api/chat/sessions/{uuid}/docker/status

Odpowiedź:

json

{
  "running": true,
  "worker_tag": "sbf",
  "container_name": "chat-abc123..."
}

Pobrać logi

bash

curl http://localhost:8080/api/chat/sessions/{uuid}/docker/logs

Zatrzymać kontener

bash

curl -X POST http://localhost:8080/api/chat/sessions/{uuid}/docker/stop

Przegląd sesji

Lista wszystkich sesji

bash

GET /api/chat/sessions

Odpowiedź:

json

[
  {
    "uuid": "abc123...",
    "worker": {
      "name": "SemBot Frontend (angular)"
    },
    "metadata": {
      "title": "Implementacja modułu...",
      "author": "tkowalski29"
    },
    "message_count": 15,
    "created_at": "2025-10-06T10:30:00Z",
    "updated_at": "2025-10-06T12:16:00Z",
    "is_active": true
  }
]

Szczegóły sesji

bash

GET /api/chat/sessions/{uuid}

Odpowiedź zawiera:

Pełną listę wiadomości (Q&A pairs)
Metadata z author_mapping
Informacje o workerze
Statystyki

Ostatnie sesje

bash

GET /api/chat/recent-sessions

Zwraca listę sesji posortowaną po updated_at (malejąco).

Zmiana executora/modelu

Zmiana executora

bash

PUT /api/chat/sessions/{uuid}/executor
{
  "executor": "claude"
}

Zmiana modelu

bash

PUT /api/chat/sessions/{uuid}/model
{
  "model": "claude-sonnet-4-5-20250929"
}

Zamknięcie sesji

Przez API

bash

POST /api/chat/sessions/{uuid}/close

To:

Ustawia is_active: false w chat.json
Zatrzymuje kontener Docker (jeśli używany)
Zachowuje wszystkie wiadomości i outputy

Ręcznie

Możesz też ręcznie edytować chat.json:

json

{
  "is_active": false
}

Praca z outputem LLM

Pobranie listy outputów

bash

GET /api/chat/sessions/{uuid}/outputs

Odpowiedź:

json

[
  {
    "filename": "claude_20251006_120403.json",
    "path": "/path/to/.chat/{uuid}/llm_outputs/claude_20251006_120403.json",
    "size": 4231
  }
]

Pobranie konkretnego outputu

bash

GET /api/chat/sessions/{uuid}/outputs/claude_20251006_120403.json

Odpowiedź:

json

{
  "filename": "claude_20251006_120403.json",
  "path": "/path/to/file.json",
  "raw_output": "{\"type\":\"system\",...}\n{\"type\":\"assistant\",...}",
  "size": 4231
}

Renderowanie outputu jako HTML

bash

GET /api/chat/sessions/{uuid}/outputs/claude_20251006_120403.json/render

Zwraca sformatowany HTML (używa utils.FormatClaudeOutput()).

Najlepsze praktyki

1. Nazwij sesję opisowo

W chat.json ustaw znaczący title:

json

{
  "title": "Implementacja logowania użytkowników",
  "description": "Dodanie JWT auth do API"
}

2. Przypisz task ID

Jeśli sesja dotyczy konkretnego taska:

json

{
  "task_id": "TASK-123",
  "task_link": "https://github.com/org/repo/issues/123"
}

3. Używaj slash commands

Zamiast pisać pełne instrukcje:

❌ Możesz podsumować naszą konwersację? ✅ /podsumuj

4. Sprawdzaj output dla debugowania

Jeśli odpowiedź nie jest taka jak oczekiwana, kliknij "Pokaż output" aby zobaczyć:

Czy były błędy
Ile tokenów użyto
Jaki był pełny request/response

5. Zamykaj nieaktywne sesje

Aby utrzymać porządek:

bash

POST /api/chat/sessions/{uuid}/close

6. Korzystaj z Docker dla izolacji

Dla ważnych projektów używaj workera z Docker:

Świeży stan projektu
Izolacja od lokalnego środowiska
Pełne logi w kontenerze

Przykładowy workflow

Scenariusz: Implementacja nowej funkcji

Utwórz sesję - wybierz worker (np. SemBot Frontend)
Edytuj metadata - ustaw title, task_id, task_link
Zadaj pierwsze pytanie - "Jak zaimplementować formularz logowania?"
Claude odpowiada - pokazuje przykład kodu
Zadaj follow-up - "A jak walidować email?"
Claude odpowiada - dodaje walidację
Sprawdź output - kliknij "Pokaż output" aby zobaczyć pełny kontekst
Zakończ sesję - POST /close gdy skończysz

Całość zapisana jako historia

.chat/abc123.../
├── chat.json (metadata)
├── messages/
│   ├── msg_001.json (Q: jak zaimplementować? A: przykład kodu)
│   └── msg_002.json (Q: jak walidować? A: walidacja)
└── llm_outputs/
    ├── claude_001.json (raw output msg 1)
    └── claude_002.json (raw output msg 2)

Rozwiązywanie problemów

Problem: Output nie pokazuje się

Sprawdź:

Czy plik istnieje w llm_outputs/?
Czy answer.output_path w message jest poprawny?
Czy endpoint /render działa?

Fix:

bash

# Sprawdź plik
ls .chat/{uuid}/llm_outputs/

# Przetestuj render
curl http://localhost:8080/api/chat/sessions/{uuid}/outputs/{filename}/render

Problem: Wiadomości w złej kolejności

Oczekiwane: Answer na górze, Question poniżej Jeśli odwrotnie: problem z frontendem (chat_detail.js)

Problem: Docker nie startuje

Sprawdź:

Czy worker ma docker_compose_path?
Czy docker-compose.yml istnieje?
Czy zmienne środowiskowe są ustawione?

Debug:

bash

# Sprawdź logi
docker logs chat-{uuid}

# Status kontenera
docker ps -a | grep chat-{uuid}

Następne kroki

API Reference → - pełna dokumentacja endpointów
Docker setup → - szczegóły konfiguracji Docker
Troubleshooting → - więcej problemów i rozwiązań

Przewodnik użytkownika Chat ​

Tworzenie nowej sesji ​

1. Otwórz stronę Chat ​

2. Wybierz worker ​

3. Kliknij na wybrany worker ​

4. Wypełnij metadata (opcjonalne) ​

Interfejs sesji Chat ​

Layout strony ​

Elementy interfejsu ​

Header ​

Tabs ​

Input Area ​

Message Area ​

Sidebar (Info) ​

Wysyłanie wiadomości ​

1. Wpisz pytanie ​

2. Kliknij "Wyślij" ​

3. Odpowiedź pojawia się automatycznie ​

Przykład pary Q&A ​

Przykład z output toggle ​

Slash commands (komendy specjalne) ​

/podsumuj ​

/wyjasnij ​

/utworz_taska ​

Praca z Docker ​

Kiedy używać Docker? ​

Jak działa Docker w Chat? ​

Docker tab ​

Status kontenera ​

Logi kontenera ​

Zarządzanie kontenerem Docker ​

Sprawdzić status ​

Pobrać logi ​

Zatrzymać kontener ​

Przegląd sesji ​

Lista wszystkich sesji ​

Szczegóły sesji ​

Ostatnie sesje ​

Zmiana executora/modelu ​

Zmiana executora ​

Zmiana modelu ​

Zamknięcie sesji ​

Przez API ​

Ręcznie ​

Praca z outputem LLM ​

Pobranie listy outputów ​

Pobranie konkretnego outputu ​

Renderowanie outputu jako HTML ​

Najlepsze praktyki ​

1. Nazwij sesję opisowo ​

2. Przypisz task ID ​

3. Używaj slash commands ​

4. Sprawdzaj output dla debugowania ​

5. Zamykaj nieaktywne sesje ​

6. Korzystaj z Docker dla izolacji ​

Przykładowy workflow ​

Scenariusz: Implementacja nowej funkcji ​

Całość zapisana jako historia ​

Rozwiązywanie problemów ​

Problem: Output nie pokazuje się ​

Problem: Wiadomości w złej kolejności ​

Problem: Docker nie startuje ​

Następne kroki ​

Przewodnik użytkownika Chat

Tworzenie nowej sesji

1. Otwórz stronę Chat

2. Wybierz worker

3. Kliknij na wybrany worker

4. Wypełnij metadata (opcjonalne)

Interfejs sesji Chat

Layout strony

Elementy interfejsu

Header

Tabs

Input Area

Message Area

Sidebar (Info)

Wysyłanie wiadomości

1. Wpisz pytanie

2. Kliknij "Wyślij"

3. Odpowiedź pojawia się automatycznie

Przykład pary Q&A

Przykład z output toggle

Slash commands (komendy specjalne)

`/podsumuj`

`/wyjasnij`

`/utworz_taska`

Praca z Docker

Kiedy używać Docker?

Jak działa Docker w Chat?

Docker tab

Status kontenera

Logi kontenera

Zarządzanie kontenerem Docker

Sprawdzić status

Pobrać logi

Zatrzymać kontener

Przegląd sesji

Lista wszystkich sesji

Szczegóły sesji

Ostatnie sesje

Zmiana executora/modelu

Zmiana executora

Zmiana modelu

Zamknięcie sesji

Przez API

Ręcznie

Praca z outputem LLM

Pobranie listy outputów

Pobranie konkretnego outputu

Renderowanie outputu jako HTML

Najlepsze praktyki

1. Nazwij sesję opisowo

2. Przypisz task ID

3. Używaj slash commands

4. Sprawdzaj output dla debugowania

5. Zamykaj nieaktywne sesje

6. Korzystaj z Docker dla izolacji

Przykładowy workflow

Scenariusz: Implementacja nowej funkcji

Całość zapisana jako historia

Rozwiązywanie problemów

Problem: Output nie pokazuje się

Problem: Wiadomości w złej kolejności

Problem: Docker nie startuje

Następne kroki