Troubleshooting i FAQ

Najczęstsze problemy i ich rozwiązania w module Chat.

FAQ (Najczęściej zadawane pytania)

Jak działa historia konwersacji?

Chat używa funkcji --session {uuid} z Claude Code CLI:

Każda sesja ma unikalny UUID
Claude automatycznie zachowuje historię między pytaniami
Nie trzeba ręcznie przekazywać kontekstu
Historia jest przechowywana w .claude/sessions/{uuid}/

Czy mogę używać wielu workerów w jednej sesji?

Tak! W chat.json możesz mieć:

json

{
  "workers": [
    "SemBot Frontend (angular)",
    "SemBot Backend (laravel)"
  ]
}

W trybie Docker pierwszy worker z listy jest używany jako główny kontekst, ale Claude ma dostęp do wszystkich sklonowanych repozytoriów.

Jaka jest różnica między local a Docker executor?

Local executor:

Wykonuje komendy Claude CLI na hoście
Używa lokalnego projektu (z worker.path)
Szybsze (brak overhead Docker)
Dzieli środowisko z innymi sesjami

Docker executor:

Wykonuje komendy w izolowanym kontenerze
Klonuje świeże repozytoria
Wolniejsze (startup ~30s)
Pełna izolacja między sesjami

Gdzie są zapisywane wiadomości?

.chat/{session-uuid}/
├── chat.json              # Metadata sesji
├── container.log          # Logi Docker (jeśli używany)
├── messages/
│   └── msg_*.json         # Pary Q&A
└── llm_outputs/
    └── *.json             # Raw output LLM (JSON Lines)

Jak długo sesja jest aktywna?

Sesja jest aktywna dopóki:

is_active: true w chat.json
Użytkownik nie zamknie sesji przez API
Timeout Claude CLI nie zostanie przekroczony (domyślnie 5 minut nieaktywności)

Czy mogę edytować metadata po utworzeniu sesji?

Tak! Edytuj plik chat.json:

json

{
  "title": "Nowy tytuł",
  "description": "Nowy opis",
  "task_id": "TASK-123",
  "task_link": "https://github.com/org/repo/issues/123"
}

Zmiany będą widoczne po odświeżeniu strony.

Jak zmienić executor podczas sesji?

bash

curl -X PUT http://localhost:8080/api/chat/sessions/{uuid}/executor \
  -H "Content-Type: application/json" \
  -d '{"executor":"claude"}'

UWAGA: Zmiana executora nie przenosi historii. Lepiej tworzyć nową sesję.

Czy mogę wznowić zamkniętą sesję?

Tak! Ustaw is_active: true w chat.json:

json

{
  "is_active": true
}

Pełna historia wiadomości jest zachowana.

Jak usunąć sesję?

Usuń katalog sesji:

bash

rm -rf .chat/{session-uuid}/

UWAGA: To usuwa całą historię! Nie ma undo.

Problemy z wiadomościami

Problem: Output nie pokazuje się

Symptomy:

Przycisk "Pokaż output" jest widoczny
Po kliknięciu nic się nie dzieje
Console pokazuje błąd 404

Przyczyny:

Plik output nie istnieje w llm_outputs/
answer.output_path jest nieprawidłowy
Endpoint /render nie działa

Debug:

bash

# Sprawdź pliki output
ls .chat/{uuid}/llm_outputs/

# Sprawdź message
cat .chat/{uuid}/messages/msg_*.json | jq '.answer.output_path'

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

Fix:

Upewnij się że GetLLMOutputFile() jest zaimplementowane w chat_service.go
Sprawdź czy RenderLLMOutput() handler jest zarejestrowany
Sprawdź uprawnienia do plików w llm_outputs/

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

Symptomy:

Question jest na górze
Answer jest poniżej

Oczekiwane: Answer na górze (newest first), Question poniżej

Fix: Sprawdź chat_detail.js:

javascript

// Display Answer part FIRST (on top)
if (message.answer) {
    const answerDiv = this.createMessageElement(message.answer);
    chatMessages.appendChild(answerDiv);
}

// Display Question part SECOND (below answer)
if (message.question) {
    const questionDiv = this.createMessageElement(message.question);
    chatMessages.appendChild(questionDiv);
}

Problem: Duplikaty wiadomości

Symptomy:

Ta sama wiadomość pojawia się wielokrotnie
Po odświeżeniu strony duplikaty znikają

Przyczyny:

Frontend dodaje wiadomość przed i po wysłaniu
Brak sprawdzania czy wiadomość już istnieje

Fix: Dodaj sprawdzanie data-message-id przed dodaniem:

javascript

// Check if message already exists
if (document.querySelector(`[data-message-id="${message.id}"]`)) {
    return; // Skip, already displayed
}

Problem: Nowe wiadomości nie pojawiają się

Symptomy:

Wiadomość wysłana przez API
Brak odpowiedzi w UI
Console pokazuje błąd

Debug:

bash

# Sprawdź czy wiadomość została zapisana
ls -la .chat/{uuid}/messages/

# Sprawdź ostatnią wiadomość
cat .chat/{uuid}/messages/msg_*.json | tail -n 1 | jq .

# Sprawdź API
curl http://localhost:8080/api/chat/sessions/{uuid}

Przyczyny:

Błąd w SendMessage() handler
Błąd wykonania Claude CLI
Problem z zapisem do pliku

Fix: Sprawdź logi serwera:

bash

# Go server logs
tail -f /var/log/code-gen-manager.log

# Docker logs (if used)
docker logs chat-{uuid}

Problemy z Docker

Problem: Kontener nie startuje

Symptomy:

POST /docker/start zwraca błąd
Status pokazuje running: false

Debug:

bash

# Sprawdź logi compose
cd .docker/chat-{uuid}/
docker-compose logs

# Sprawdź logi kontenera
docker logs chat-{uuid}

# Sprawdź status
docker ps -a | grep chat-{uuid}

Częste przyczyny:

Brak docker_compose_path

yaml

workers:
  - name: "Worker"
    docker_compose_path: "/path/to/docker/worker"  # WYMAGANE

Nieprawidłowe zmienne środowiskowe

bash

# Sprawdź .docker/chat-{uuid}/docker-compose.yml
cat .docker/chat-{uuid}/docker-compose.yml | grep "SESSION_ID"

Brak dostępu do SSH keys

yaml

volumes:
  - ~/.ssh:/root/.ssh:ro  # Sprawdź czy istnieje

Port conflict

bash

# Sprawdź czy port jest zajęty
docker ps | grep 8080

Fix:

bash

# Wymuś restart
docker-compose -f .docker/chat-{uuid}/docker-compose.yml down
docker-compose -f .docker/chat-{uuid}/docker-compose.yml up -d

# Sprawdź logi startowe
docker logs -f chat-{uuid}

Problem: Claude CLI nie działa w kontenerze

Symptomy:

Kontener uruchomiony
Błąd: claude: command not found

Debug:

bash

# Wejdź do kontenera
docker exec -it chat-{uuid} sh

# Sprawdź instalację
which claude
claude --version

# Sprawdź PATH
echo $PATH

# Sprawdź logi instalacji
cat /app/chat/container.log | grep "Claude CLI"

Przyczyny:

Instalacja się nie powiodła
Claude CLI nie jest w PATH
Nieprawidłowe uprawnienia

Fix:

bash

# Reinstaluj w kontenerze
docker exec -it chat-{uuid} sh -c "curl -fsSL https://claude.ai/cli/install.sh | sh"

# Dodaj do PATH jeśli potrzeba
docker exec -it chat-{uuid} sh -c "export PATH=$PATH:/usr/local/bin"

Problem: Nie może sklonować repozytorium

Symptomy:

Logi pokazują: Permission denied (publickey)
Repozytorium nie zostało sklonowane

Debug:

bash

# Test SSH w kontenerze
docker exec -it chat-{uuid} ssh -T [email protected]

# Sprawdź klucze
docker exec -it chat-{uuid} ls -la /root/.ssh/

# Sprawdź ssh-agent
docker exec -it chat-{uuid} ssh-add -l

Fix:

Upewnij się że klucze są zamontowane:

yaml

volumes:
  - ~/.ssh:/root/.ssh:ro

Sprawdź uprawnienia kluczy (na hoście):

bash

chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/*.pub

Dodaj klucze do ssh-agent (w kontenerze):

bash

docker exec -it chat-{uuid} sh -c "
    eval \$(ssh-agent -s)
    ssh-add /root/.ssh/id_rsa
"

Test połączenia:

bash

docker exec -it chat-{uuid} ssh -T [email protected]
# Output: "Hi username! You've successfully authenticated..."

Problem: "Resource busy" przy kopiowaniu .claude.json

Symptomy:

Logi pokazują: rm: can't remove '/root/.claude.json': Resource busy
Container nie startuje poprawnie

Przyczyna: Plik .claude.json jest montowany jako volume i nie może być usunięty

Fix: Użyj cat > zamiast rm && cp w start.sh:

bash

# ❌ NIE DZIAŁA (Resource busy)
rm -f /root/.claude.json
cp /root/.claude.json.backup /root/.claude.json

# ✅ DZIAŁA (overwrite bez deletion)
cat /root/.claude.json.backup > /root/.claude.json

Problem: Kontener używa za dużo CPU/RAM

Debug:

bash

# Sprawdź zużycie
docker stats chat-{uuid}

Fix: Dodaj limity w docker-compose.yml:

yaml

services:
  chat-worker:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 2G

Problem: Kontener nie zatrzymuje się

Symptomy:

POST /docker/stop timeout
docker stop nie działa

Fix:

bash

# Force kill
docker kill chat-{uuid}

# Remove
docker rm -f chat-{uuid}

# Sprawdź network
docker network ls | grep chat
docker network rm chat-{uuid}_chat-network

Problemy z konfiguracją

Problem: Worker nie pojawia się na liście

Symptomy:

Worker jest w config.yml
Nie pojawia się w /api/chat/workers

Debug:

bash

# Sprawdź config
cat config.yml | grep -A 10 "workers:"

# Sprawdź czy serwer się uruchomił
curl http://localhost:8080/api/chat/workers

Przyczyny:

Błąd składni YAML
Worker nie ma wymaganych pól
Serwer nie przeładował konfiguracji

Fix:

Zweryfikuj YAML:

bash

# Install yamllint
pip install yamllint

# Validate
yamllint config.yml

Sprawdź wymagane pola:

yaml

workers:
  - name: "Worker Name"  # WYMAGANE
    path: "/path/to/worker"  # WYMAGANE
    tags: ["tag"]  # WYMAGANE

Restart serwera:

bash

# Kill i restart
pkill code-gen-manager
go run main.go

Problem: Author mapping nie działa

Symptomy:

Author ID w metadata
Brak linków do GitHub/Task/Chat
author_mapping jest puste

Debug:

bash

# Sprawdź metadata
curl http://localhost:8080/api/chat/sessions/{uuid}/metadata | jq '.author_mapping'

# Sprawdź config
cat config.yml | grep -A 20 "author_mapping:"

Przyczyny:

Author ID nie pasuje do konfiguracji
Brak url_patterns w config
Błąd w GetAuthorMapping() method

Fix:

Dodaj mapowanie w config.yml:

yaml

github:
  author_mapping:
    "user-id":
      real_name: "John Doe"
      initials: "JD"
      task: "task-id"
      git: "github-username"
      chat: "discord-id"
  url_patterns:
    task: "[email protected]:{USER_NAME}"
    git: "[email protected]:{USER_NAME}"
    chat: "https://discord.com/users/{USER_NAME}"

Sprawdź czy author ID pasuje:

bash

# W chat.json
cat .chat/{uuid}/chat.json | jq '.author'
# Output: "user-id"

# Musi pasować do klucza w author_mapping

Problem: Executor nie zmienia się

Symptomy:

PUT /executor zwraca sukces
Sesja nadal używa starego executora

Debug:

bash

# Sprawdź metadata
curl http://localhost:8080/api/chat/sessions/{uuid}/metadata | jq '.executor'

# Sprawdź chat.json
cat .chat/{uuid}/chat.json | jq '.executor'

Fix:

Upewnij się że UpdatePreferredExecutor() zapisuje do chat.json
Sprawdź czy frontend odświeża dane po PUT
Restart sesji (może wymagać nowej sesji)

Problemy z wydajnością

Problem: Wolne ładowanie sesji

Symptomy:

GET /sessions/{uuid} trwa >5s
Strona się zawiesza

Przyczyny:

Zbyt wiele wiadomości w sesji (>1000)
Duże pliki output LLM
Powolny dostęp do dysku

Fix:

Paginacja wiadomości:

javascript

// Load only last 50 messages
const recentMessages = session.messages.slice(-50);

Lazy loading output:

javascript

// Load output only on button click, not on page load

Indeksowanie:

bash

# Create index file with message IDs
ls .chat/{uuid}/messages/ | jq -R '{id: .}' > .chat/{uuid}/messages.index.json

Problem: Duże zużycie dysku

Debug:

bash

# Sprawdź rozmiar sesji
du -sh .chat/*

# Sprawdź największe pliki
find .chat -type f -exec du -h {} \; | sort -rh | head -20

Fix:

Czyszczenie starych sesji:

bash

# Usuń sesje starsze niż 30 dni
find .chat -type d -mtime +30 -exec rm -rf {} \;

Kompresja outputów:

bash

# Compress old outputs
find .chat/*/llm_outputs -name "*.json" -mtime +7 -exec gzip {} \;

Archiwizacja:

bash

# Archive old sessions
tar czf chat-archive-$(date +%Y%m%d).tar.gz .chat/*/
mv chat-archive-*.tar.gz /archive/

Problemy z bezpieczeństwem

Problem: Path traversal w GetLLMOutputFile

UWAGA: System ma zabezpieczenie, ale warto znać:

// Security check in chat_service.go
absLLMOutputDir, _ := filepath.Abs(llmOutputDir)
absFilePath, _ := filepath.Abs(filePath)
if !strings.HasPrefix(absFilePath, absLLMOutputDir) {
    return nil, fmt.Errorf("invalid file path")
}

Test:

bash

# Should return error (path traversal attempt)
curl http://localhost:8080/api/chat/sessions/{uuid}/outputs/../../../etc/passwd

Problem: Nieautoryzowany dostęp do sesji

Obecna sytuacja: Brak autoryzacji - każdy może dostać się do każdej sesji znając UUID

Rozwiązanie (TODO):

Dodaj JWT authentication
Sprawdzaj author w metadata vs aktualny user
Role-based access control (RBAC)

Narzędzia diagnostyczne

Chat Doctor Script

Stwórz skrypt diagnostyczny chat-doctor.sh:

bash

#!/bin/bash
# Chat Doctor - diagnozuje problemy z sesją

SESSION_UUID=$1

if [ -z "$SESSION_UUID" ]; then
    echo "Usage: ./chat-doctor.sh {session-uuid}"
    exit 1
fi

echo "🔍 Diagnosing session: $SESSION_UUID"
echo ""

# 1. Check if session exists
if [ ! -d ".chat/$SESSION_UUID" ]; then
    echo "❌ Session directory not found"
    exit 1
fi
echo "✅ Session directory exists"

# 2. Check chat.json
if [ ! -f ".chat/$SESSION_UUID/chat.json" ]; then
    echo "❌ chat.json not found"
else
    echo "✅ chat.json exists"
    if jq empty ".chat/$SESSION_UUID/chat.json" 2>/dev/null; then
        echo "✅ chat.json is valid JSON"
    else
        echo "❌ chat.json is invalid JSON"
    fi
fi

# 3. Check messages
MSG_COUNT=$(ls .chat/$SESSION_UUID/messages/ 2>/dev/null | wc -l)
echo "📊 Messages: $MSG_COUNT"

# 4. Check outputs
OUT_COUNT=$(ls .chat/$SESSION_UUID/llm_outputs/ 2>/dev/null | wc -l)
echo "📊 LLM outputs: $OUT_COUNT"

# 5. Check Docker (if used)
CONTAINER_NAME="chat-$SESSION_UUID"
if docker ps -a | grep -q "$CONTAINER_NAME"; then
    if docker ps | grep -q "$CONTAINER_NAME"; then
        echo "✅ Docker container running"
    else
        echo "⚠️  Docker container exists but not running"
    fi
else
    echo "ℹ️  No Docker container (local execution)"
fi

# 6. Check API
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/api/chat/sessions/$SESSION_UUID)
if [ "$HTTP_CODE" = "200" ]; then
    echo "✅ API accessible (HTTP $HTTP_CODE)"
else
    echo "❌ API error (HTTP $HTTP_CODE)"
fi

echo ""
echo "✅ Diagnosis complete"

Użycie:

bash

chmod +x chat-doctor.sh
./chat-doctor.sh abc123-def456-...

Dalsze kroki

Jeśli problem nie został rozwiązany:

Sprawdź logi serwera:

bash

tail -f /var/log/code-gen-manager.log

Sprawdź logi Docker (jeśli używany):

bash

docker logs -f chat-{uuid}

Włącz debug mode:

// W main.go
log.SetLevel(log.DebugLevel)

Zgłoś issue:

Opisz problem szczegółowo
Dołącz logi
Podaj kroki do reprodukcji
Wersja systemu i Claude CLI

Zobacz także

Konfiguracja → - szczegóły konfiguracji
API Reference → - pełna dokumentacja API
Docker → - problemy specyficzne dla Docker
Przegląd → - architektura i struktura

Troubleshooting i FAQ ​

FAQ (Najczęściej zadawane pytania) ​

Jak działa historia konwersacji? ​

Czy mogę używać wielu workerów w jednej sesji? ​

Jaka jest różnica między local a Docker executor? ​

Gdzie są zapisywane wiadomości? ​

Jak długo sesja jest aktywna? ​

Czy mogę edytować metadata po utworzeniu sesji? ​

Jak zmienić executor podczas sesji? ​

Czy mogę wznowić zamkniętą sesję? ​

Jak usunąć sesję? ​

Problemy z wiadomościami ​

Problem: Output nie pokazuje się ​

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

Problem: Duplikaty wiadomości ​

Problem: Nowe wiadomości nie pojawiają się ​

Problemy z Docker ​

Problem: Kontener nie startuje ​

Problem: Claude CLI nie działa w kontenerze ​

Problem: Nie może sklonować repozytorium ​

Problem: "Resource busy" przy kopiowaniu .claude.json ​

Problem: Kontener używa za dużo CPU/RAM ​

Problem: Kontener nie zatrzymuje się ​

Problemy z konfiguracją ​

Problem: Worker nie pojawia się na liście ​

Problem: Author mapping nie działa ​

Problem: Executor nie zmienia się ​

Problemy z wydajnością ​

Problem: Wolne ładowanie sesji ​

Problem: Duże zużycie dysku ​

Problemy z bezpieczeństwem ​

Problem: Path traversal w GetLLMOutputFile ​

Problem: Nieautoryzowany dostęp do sesji ​

Narzędzia diagnostyczne ​

Chat Doctor Script ​

Dalsze kroki ​

Zobacz także ​

Troubleshooting i FAQ

FAQ (Najczęściej zadawane pytania)

Jak działa historia konwersacji?

Czy mogę używać wielu workerów w jednej sesji?

Jaka jest różnica między local a Docker executor?

Gdzie są zapisywane wiadomości?

Jak długo sesja jest aktywna?

Czy mogę edytować metadata po utworzeniu sesji?

Jak zmienić executor podczas sesji?

Czy mogę wznowić zamkniętą sesję?

Jak usunąć sesję?

Problemy z wiadomościami

Problem: Output nie pokazuje się

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

Problem: Duplikaty wiadomości

Problem: Nowe wiadomości nie pojawiają się

Problemy z Docker

Problem: Kontener nie startuje

Problem: Claude CLI nie działa w kontenerze

Problem: Nie może sklonować repozytorium

Problem: "Resource busy" przy kopiowaniu .claude.json

Problem: Kontener używa za dużo CPU/RAM

Problem: Kontener nie zatrzymuje się

Problemy z konfiguracją

Problem: Worker nie pojawia się na liście

Problem: Author mapping nie działa

Problem: Executor nie zmienia się

Problemy z wydajnością

Problem: Wolne ładowanie sesji

Problem: Duże zużycie dysku

Problemy z bezpieczeństwem

Problem: Path traversal w GetLLMOutputFile

Problem: Nieautoryzowany dostęp do sesji

Narzędzia diagnostyczne

Chat Doctor Script

Dalsze kroki

Zobacz także