Troubleshooting PL

Rozwiązywanie problemów

🌍 English · Polski · Français · Deutsch · 中文

Rozwiązania typowych problemów z ECLI. Jeśli Twojego problemu tu nie ma, sprawdź GitHub Discussions i Issues.

Pierwsze kroki przy każdym problemie

1. Sprawdź editor.log w katalogu konfiguracji — większość błędów jest tam logowana z trace.
2. Uruchom w trybie czystym aby wykluczyć config/pluginy: ecli --no-config --no-plugins.
3. Zanotuj wersję ECLI i platformę: ecli --version i uname -a (lub wersja Windows).
4. Przeszukaj istniejące issues przed otwarciem nowego.

---

Problemy z instalacją

Polecenie ecli nie znalezione

ECLI zainstalowane ale nie jest w PATH.

Linux / FreeBSD / macOS:

• Pakiety natywne instalują do /usr/local/bin/ (zwykle w PATH).
• PyPI user install (pip install --user) trafia do ~/.local/bin/ — dodaj do PATH:

  export PATH="$HOME/.local/bin:$PATH"

• Znajdź lokalizację: pip show -f ecli-editor | grep ecli

Windows:

• Installer dodaje do PATH automatycznie. Otwórz nową sesję PowerShell aby załapać zmianę.
• Dla pip install: upewnij się że katalog Scripts Pythona jest w PATH.

macOS: "ecli is damaged and can't be opened"

Fałszywy alarm Gatekeeper. Zastosuj bypass kwarantanny:

xattr -d com.apple.quarantine /usr/local/bin/ecli

Jeśli nie pomaga, plik mógł zostać uszkodzony przy pobieraniu. Pobierz ponownie i zweryfikuj sidecar .sha256.

macOS: "ecli cannot be opened because the developer cannot be verified"

To samo — ECLI jest ad-hoc signed, nie notarized. Użyj:

• System Settings → Privacy & Security → "Open Anyway"
• Lub xattr -d com.apple.quarantine /usr/local/bin/ecli

Windows: "VCRUNTIME140.dll missing"

Zainstaluj Microsoft Visual C++ Redistributable:

• Najnowszy x64

Większość Windows ma to pre-installed. Dotyczy tylko portable EXE na okrojonych obrazach Windows.

Linux: libncursesw.so.6: cannot open shared object file

Zainstaluj runtime ncurses:

# Debian / Ubuntu
sudo apt install libncursesw6 libtinfo6

# Fedora / RHEL
sudo dnf install ncurses-libs

FreeBSD: pkg install nie powiódł się z błędami zależności

Upewnij się że repo pkg są aktualne:

sudo pkg update -f
sudo pkg install ./ecli_0.1.3_freebsd_x86_64.pkg

---

Problemy z wyświetlaniem

Pokraczne kolory / złe kolory

Twój terminal nie raportuje wsparcia truecolor. Sprawdź:

echo $TERM
echo $COLORTERM

Oczekiwane:

• TERM = xterm-256color, xterm-truecolor lub podobne
• COLORTERM = truecolor lub 24bit

Napraw:

export TERM=xterm-256color
export COLORTERM=truecolor

Dodaj do ~/.bashrc / ~/.zshrc aby zachować.

W tmux:

# ~/.tmux.conf
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB"

Znaki box-drawing renderują się źle (np. +----+ zamiast ┌────┐)

Terminal nie skonfigurowany na UTF-8. Napraw:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Na Linuksie wygeneruj locale jeśli brak:

sudo locale-gen en_US.UTF-8

Status bar / numery linii nierównane

Prawdopodobnie problem z fontem. Użyj monospace fonta z konsystentnymi szerokościami glifów. Polecane:

• Fira Code
• JetBrains Mono
• Cascadia Code
• Iosevka

Unikaj fontów proporcjonalnych lub o zmiennej szerokości.

Mruganie ekranu przy scrollu

Problem z buforowaniem emulatora terminala. Spróbuj:

• Zaktualizować emulator do najnowszej wersji
• Wyłączyć animacje terminala
• Spróbować innego emulatora (Alacritty, WezTerm, Kitty są bardzo szybkie)

---

Problemy z edytorem

Plik nie chce się zapisać: "Permission denied"

Nie masz uprawnień zapisu do pliku lub jego katalogu. Sprawdź:

ls -la /sciezka/do/pliku

Jeśli właścicielem jest root: sudo ecli /sciezka/do/pliku. Ale generalnie pliki systemowe powinny być edytowane świadomie, nie przez przypadek.

Utracona praca po crashu

ECLI domyślnie nie autosave'uje. Sprawdź:

• editor.log na trace crashu
• ~/.cache/ecli/ na pliki tymczasowe

Włącz autosave w configu aby zapobiec utracie:

[editor]
autosave = true
autosave_interval_seconds = 30

Zgłoś crash z zawartością logu jako issue.

Kodowanie wygląda źle (UTF-8 → mojibake)

Wymuś kodowanie przy otwarciu:

ecli --encoding utf-8 file.txt

Lub w configu:

[editor]
default_encoding = "utf-8"
fallback_encoding = "latin1"

Nie mogę wpisać niektórych znaków (klawiatury międzynarodowe)

ECLI obsługuje większość input Unicode przez terminal. Jeśli klawisz jest przechwytywany:

• Sprawdź konflikty w [keybindings]
• Niektóre terminale przechwytują Alt+litera dla menu — wyłącz w ustawieniach terminala

---

Problemy z panelem AI

"API key not configured"

Albo:

• Provider jest ustawiony jako domyślny ale brak skonfigurowanego klucza. Dodaj do configu lub env var.
• Nazwa providera jest przekręcona (anthrpoic vs anthropic).

Sprawdź:

ecli --check-config

"Connection refused" (Ollama)

Daemon Ollama nie działa.

ollama serve

Lub w tle:

ollama serve > /tmp/ollama.log 2>&1 &

Zweryfikuj:

curl http://localhost:11434/api/tags

"Rate limit exceeded"

Trafiłeś na limit requestów providera. Albo:

• Poczekaj (limity zwykle resetują się co minutę lub godzinę)
• Przełącz na innego providera klawiszem Tab w panelu AI
• Zmniejsz częstotliwość requestów

Odpowiedzi AI są bardzo wolne

• Anthropic/OpenAI — sprawdź latencję sieci: curl -w "@-" -o /dev/null -s https://api.anthropic.com < <(echo 'time_total: %{time_total}\n')
• Ollama — rozmiar lokalnego modelu ma znaczenie. Spróbuj mniejszy model (ollama pull qwen2.5-coder:7b).
• HuggingFace free tier — cold-start delays są normalne. Przełącz na Inference Endpoints dla produkcji.

AI zwraca pustą odpowiedź

Niektórzy providerzy zwracają pusto gdy:

• Naruszenie content policy (filtr po stronie providera)
• Przekroczona długość kontekstu — zmniejsz input
• Timeout streamu — zwiększ timeout_seconds w configu

Bloki kodu w odpowiedzi AI nie renderują się dobrze

Znana limitacja w 0.1.x — pełne renderowanie Markdown w panelu AI planowane na v0.2. Obecnie panel pokazuje raw tekst z lekkimi syntax cues.

---

Problemy z panelem Git

Panel Git pokazuje "Not a Git repository"

Otwórz ECLI z wnętrza repo Git, lub użyj cd aby tam przejść przed uruchomieniem.

Autentykacja się nie udaje przy push

ECLI wywołuje git, więc credentials działają tak jak Twój git:

• HTTPS — Git Credential Manager lub zapisane credentials
• SSH — ssh-agent z załadowanym kluczem

Test poza ECLI najpierw:

git push origin main

Jeśli to nie działa, napraw config gita, nie ECLI.

Widok diff pokazuje binarny śmietnik

ECLI nie wyświetla diffów dla plików binarnych. Jeśli widzisz śmieci, plik może być błędnie wykryty jako tekst. Skonfiguruj gitattributes:

# .gitattributes
*.pdf binary
*.png binary

---

Problemy z LSP

Brak autouzupełniania

LSP wyłączony lub serwer nie działa. Sprawdź:

[lsp]
enabled = true

[lsp.python]
command = "pylsp"

Zweryfikuj że binary LSP istnieje:

which pylsp

LSP server crashuje

Sprawdź editor.log na output stderr serwera. Typowe przyczyny:

• Zły working directory — LSP potrzebuje root projektu
• Brakujące zależności (Python venv nieaktywowany, etc.)
• Niezgodna wersja serwera — zaktualizuj language server

---

Problemy z pluginami

Plugin załadowany ale nie pokazuje się w palette

String w dekoratorze @command("name") to match dla palette. Naciśnij Ctrl+P i wpisz dokładną nazwę.

Plugin crashuje ECLI przy starcie

Uruchom z --no-plugins aby zizolować:

ecli --no-plugins

Jeśli to działa, usuń lub wyłącz problematyczny plugin w [plugins] enabled = [...].

Sprawdź editor.log na trace pluginu.

---

Problemy z performance

ECLI używa dużo CPU

Najprawdopodobniej parsing Tree-sitter na dużych plikach. Spróbuj:

[editor]
treesitter_threshold_kb = 1024   # wyłącz TS dla plików większych niż 1 MB

Lub wyłącz podświetlanie całkowicie dla sesji:

ecli --no-syntax file.txt

Pamięć rośnie z czasem

Możliwy leak w długiej sesji. Workaround: restart ECLI. Zgłoś issue z editor.log i outputem ps -o pid,rss,command -p $(pidof ecli).

---

Jak zgłosić dobry issue

W bug raporcie zawrzyj:

1. Wersję ECLI (ecli --version)
2. OS i architekturę (uname -a lub systeminfo na Windows)
3. Wersję Pythona jeśli z PyPI (python3 --version)
4. Emulator terminala i jego wersję
5. Kroki reprodukcji
6. Oczekiwane vs faktyczne zachowanie
7. Fragmenty editor.log (zredaguj sekrety)
8. Twój config.toml (zredaguj klucze API)

To dramatycznie zwiększa szanse na szybką naprawę.