# DeepTutor: Dożywotnie Spersonalizowane Korepetycje

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/) [![Next.js 16](https://img.shields.io/badge/Next.js-16-000000?style=flat-square&logo=next.js&logoColor=white)](https://nextjs.org/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](../../LICENSE) [![GitHub release](https://img.shields.io/github/v/release/HKUDS/DeepTutor?style=flat-square&color=brightgreen)](https://github.com/HKUDS/DeepTutor/releases) [![arXiv](https://img.shields.io/badge/arXiv-2604.26962-b31b1b?style=flat-square&logo=arxiv&logoColor=white)](https://arxiv.org/abs/2604.26962) [![Discord](https://img.shields.io/badge/Discord-Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/eRsjPgMU4t) [![Feishu](https://img.shields.io/badge/Feishu-Group-00D4AA?style=flat-square&logo=feishu&logoColor=white)](../../Communication.md) [![WeChat](https://img.shields.io/badge/WeChat-Group-07C160?style=flat-square&logo=wechat&logoColor=white)](https://github.com/HKUDS/DeepTutor/issues/78) [Funkcje](#-główne-funkcje) · [Zacznij](#-pierwsze-kroki) · [Eksploruj](#-eksploracja-deeptutor) · [CLI](#️-deeptutor-cli--interfejs-natywny-dla-agentów) · [Ekosystem](#-ekosystem--eduhub-i-społeczność-umiejętności) · [Społeczność](#-społeczność)

--- > 🤝 **Zapraszamy do wszelkich form współpracy!** Głosuj na elementy planu działania lub proponuj nowe w [`Roadmap`](https://github.com/HKUDS/DeepTutor/issues/498), a szczegóły dotyczące strategii gałęzi, standardów kodowania i sposobu rozpoczęcia pracy znajdziesz w naszym [Przewodniku dla współtwórców](../../CONTRIBUTING.md). ### 📰 Aktualności - **2026-05-22** 🌐 Oficjalna strona dokumentacji dostępna na [**deeptutor.info**](https://deeptutor.info/) — przewodniki, odniesienia i wycieczki po możliwościach w jednym miejscu. - **2026-04-19** 🎉 20 tys. gwiazdek w 111 dni! Dziękujemy za wsparcie na drodze do prawdziwie spersonalizowanych, inteligentnych korepetycji. - **2026-04-10** 📄 Nasz artykuł jest już dostępny na arXiv — przeczytaj [preprint](https://arxiv.org/abs/2604.26962), aby dowiedzieć się więcej o projekcie i pomysłach stojących za DeepTutor. - **2026-02-06** 🚀 10 tys. gwiazdek w zaledwie 39 dni! Ogromne podziękowania dla naszej niesamowitej społeczności. - **2026-01-01** 🎊 Szczęśliwego Nowego Roku! Dołącz do naszego [Discorda](https://discord.gg/eRsjPgMU4t), [WeChat](https://github.com/HKUDS/DeepTutor/issues/78) lub [Dyskusji](https://github.com/HKUDS/DeepTutor/discussions) — razem kształtujmy przyszłość DeepTutor. - **2025-12-29** 🎓 DeepTutor jest oficjalnie wydany! ## ✨ Główne funkcje DeepTutor to natywne dla agentów środowisko nauki, które łączy korepetycje, rozwiązywanie problemów, generowanie quizów, badania, wizualizacje i ćwiczenia opanowania wiedzy w jednym rozszerzalnym systemie. - **Jedno środowisko dla wszystkich trybów** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading i Immersive Watching współdzielą jedno środowisko uruchomieniowe możliwości oraz kontekst sesji, zachowując wyspecjalizowane pętle i potoki dla poszczególnych zadań. - **Połączony kontekst uczenia się** — bazy wiedzy, książki, szkice Co-Writer, notatniki, banki pytań, persony i Memory można ponownie wykorzystywać w obsługujących je przepływach pracy, z uwzględnieniem uprawnień konta i polityk nauczania. - **Immersyjne uczenie się z wideo** — wklej link do YouTube, aby korzystać z natywnego odtwarzania o podwyższonej ochronie prywatności, zsynchronizowanych napisów, korepetycji osadzonych w znacznikach czasu i wznawialnych postępów; administratorzy mogą przełączyć odtwarzanie na samodzielnie hostowaną instancję Invidious bez ponownego tworzenia materiałów. - **Subagenty i Partners** — z poziomu Chat konsultuj aktywnie działającego agenta (Claude Code, Codex, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw lub DeepSeek) albo Partner, importuj poprzednie konwersacje i uruchamiaj stałych towarzyszy IM na tym samym mózgu. - **Wielosilnikowa wiedza** — wersjonowane biblioteki RAG z LlamaIndex, PageIndex, GraphRAG, LightRAG, zdalnym LightRAG Server, samodzielnie hostowanym WeKnora, biblioteką Tencent IMA lub MarginNote 4, lub podłączonym vault Obsidian, z podłączalnym parsowaniem dokumentów. - **Rozszerzalne narzędzia i umiejętności** — wbudowane narzędzia, serwery MCP, aplikacje CLI, modele generowania obrazów / wideo / głosu oraz instalowalne umiejętności społecznościowe z EduHub. - **Inspektowalna pamięć** — ślady L1, podsumowania powierzchni L2 i synteza L3 sprawiają, że personalizacja jest widoczna i edytowalna; Memory Graph łączy fakty L2 z dowodami L1, a syntezę L3 z powierzchniami, które się do niej przyczyniły. --- ## 🚀 Pierwsze kroki DeepTutor oferuje cztery ścieżki instalacji. Wszystkie współdzielą jeden układ obszaru roboczego: ustawienia żyją w `data/user/settings/` pod katalogiem, z którego uruchamiasz (lub pod `DEEPTUTOR_HOME` / `deeptutor start --home` jeśli ustawisz je jawnie). Dla pełnej aplikacji zalecany przepływ to **wybierz katalog obszaru roboczego → zainstaluj → `deeptutor init` → `deeptutor start`**. ### Content Workspace **Content Workspace** jest oddzielony od prywatnego obszaru roboczego środowiska uruchomieniowego DeepTutor. To folder, który agenci mogą odczytywać i w którym każdy utworzony przez agenta plik, pobranie, uruchomienie kodu, pamięć podręczna i wyrenderowany zasób trafia do katalogu `outputs////` powiązanego z konkretną turą. Ustawienia, klucze API, bazy danych, Memory i wewnętrzny stan aplikacji pozostają poza nim. Bez konfiguracji content workspace to `/data/user/workspace`. Lokalne instalacje PyPI, CLI i ze źródeł mogą wybrać dowolny istniejący, odczytywalny/zapisywalny folder w **Settings → Workspace** albo: ```bash deeptutor workspace show deeptutor workspace set /absolute/path/to/my-folder deeptutor workspace reset ``` Każda możliwość może przeglądać ten sam folder przez wbudowane narzędzia workspace. Model otrzymuje wyłącznie względne ścieżki, takie jak `outputs/...`; gdy użyje `workspace_present`, UI renderuje uwierzytelniony, otwieralny zrzut. Ta sama dokładna względna ścieżka działa też w normalnym linku Markdown lub obrazie. Zmiana pliku źródłowego później nie zmienia już zaprezentowanego zrzutu. Wykonanie jest tylko do odczytu poza `outputs/`. Skopiowanie wygenerowanego pliku gdzie indziej w content workspace wymaga jawnego potwierdzenia **Allow once** dla dokładnie tego źródła i celu. Piaskownica systemowa lub Docker runner egzekwuje tę granicę, gdy jest dostępna; lokalny awaryjny ograniczony podproces jest oznaczony jako **best effort** w ustawieniach Workspace.

Opcja 1 — Instalacja z PyPI · pełna lokalna aplikacja Web + CLI, bez potrzeby klonowania

Pełna lokalna aplikacja Web + CLI, bez potrzeby klonowania. Wymaga **Python 3.11–3.14** i środowiska uruchomieniowego **Node.js 20+** na PATH (spakowany serwer standalone Next.js jest uruchamiany przez `deeptutor start`). ```bash mkdir -p my-deeptutor && cd my-deeptutor pip install -U deeptutor deeptutor init # pyta o porty + dostawcę LLM + opcjonalne osadzanie/wyszukiwanie deeptutor start # uruchamia backend + frontend; utrzymuj terminal otwarty ``` `deeptutor init` pyta o port backendu (domyślnie `8001`), port frontendu (domyślnie `3782`), dostawcę LLM / bazowy URL / klucz API / model, opcjonalnego dostawcę osadzania dla Bazy wiedzy / RAG oraz opcjonalnego dostawcę wyszukiwania dla Web Search. Po `deeptutor start` otwórz adres URL frontendu wydrukowany w terminalu — domyślnie [http://127.0.0.1:3782](http://127.0.0.1:3782). Naciśnij `Ctrl+C` w tym terminalu, aby zatrzymać backend i frontend. Pominięcie `deeptutor init` jest dobre dla szybkiego testu; aplikacja uruchamia się z domyślnymi portami i pustymi ustawieniami modelu, skonfiguruj je później w **Settings → Models**.

Opcja 2 — Instalacja ze źródeł · programowanie przy użyciu kodu źródłowego

Do programowania przy użyciu kodu źródłowego. Użyj **Python 3.11–3.14** i **Node.js 22 LTS**, aby dopasować do CI i Dockera. ```bash git clone https://github.com/HKUDS/DeepTutor.git cd DeepTutor # Utwórz venv (macOS/Linux). Windows PowerShell: # py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1 python3 -m venv .venv && source .venv/bin/activate python -m pip install --upgrade pip # Zainstaluj zależności backendu + frontendu python -m pip install -e . ( cd web && npm ci --legacy-peer-deps ) deeptutor init deeptutor start --dev ``` `deeptutor start` buduje lokalny frontend `web/` na potrzeby produkcji jednorazowo i ponownie go wykorzystuje; `--dev` uruchamia Next.js z automatycznym przeładowywaniem modułów (HMR). Układ konfiguracji, porty i `Ctrl+C` odpowiadają Opcji 1.

Środowisko Conda (zamiast venv)

```bash conda create -n deeptutor python=3.11 conda activate deeptutor python -m pip install --upgrade pip ```

Opcjonalne dodatki instalacyjne — silniki RAG / dev / partners / matrix / math-animator

```bash pip install -e ".[rag-lightrag]" # Wbudowany silnik LightRAG (dokładnie obsługiwany SDK) pip install -e ".[graphrag]" # Silnik Microsoft GraphRAG (Python 3.11–3.13) pip install -e ".[dev]" # narzędzia testów/lint pip install -e ".[partners]" # SDK kanałów IM Partners pip install -e ".[video-learning]" # compatibility extra; captions ship in the full/CLI installs pip install -e ".[matrix]" # kanał Matrix bez E2EE/libolm pip install -e ".[matrix-e2e]" # Matrix E2EE; wymaga libolm pip install -e ".[math-animator]" # addon Manim; wymaga LaTeX/ffmpeg/bibliotek systemowych ```

Dostosowania zależności frontendowych i rozwiązywanie problemów z serwerem deweloperskim

**Zmiana zależności frontendowych:** uruchom `npm install --legacy-peer-deps`, aby odświeżyć `web/package-lock.json`, a następnie zatwierdź zarówno `web/package.json`, jak i `web/package-lock.json`. **Zablokowany serwer deweloperski:** jeśli `deeptutor start --dev` zgłasza istniejący frontend, który nie odpowiada, zatrzymaj PID, który wydrukuje. Jeśli żaden proces Next.js nie jest uruchomiony, pliki blokady są przestarzałe — usuń je i spróbuj ponownie: ```bash rm -f web/.next/dev/lock web/.next/lock deeptutor start --dev ```

Opcja 3 — Docker · jeden samodzielny kontener

Jeden kontener dla pełnej aplikacji Web. Obrazy w GitHub Container Registry: - `ghcr.io/hkuds/deeptutor:latest` — najnowsze stabilne wydanie - `ghcr.io/hkuds/deeptutor:` — dokładne wydanie bez początkowego `v` (na przykład `:1.6.3`); wydania wstępne otrzymują wyłącznie własny tag wersji > Zobacz [CONTAINERIZATION.md](../../CONTAINERIZATION.md) w celu uzyskania informacji o wdrożeniach podman/rootless/read-only-rootfs i pełnym przewodniku per-instalacja. ```bash docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 \ -v deeptutor-data:/app/data \ ghcr.io/hkuds/deeptutor:latest ``` Aby wybrać folder treści hosta przy starcie kontenera, zamontuj go pod stałą ścieżką kontenera i zablokuj DeepTutor do tej ścieżki: ```bash mkdir -p "$PWD/deeptutor-workspace/outputs" docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 \ -v deeptutor-data:/app/data \ -v "$PWD/deeptutor-workspace:/workspace" \ -e DEEPTUTOR_WORKSPACE_ROOT=/workspace \ -e DEEPTUTOR_WORKSPACE_ALLOWED_ROOTS=/workspace \ ghcr.io/hkuds/deeptutor:latest ``` Dla Compose ustaw `DEEPTUTOR_WORKSPACE_HOST=/absolute/host/folder` przed uruchomieniem `python scripts/docker_compose.py up -d`. Gdy pominięte, używany jest `./data/user/workspace`. Ścieżki Dockera są wybierane przy starcie i dlatego pojawiają się jako zablokowane na stronie ustawień Web. > **Tylko `3782` musi być opublikowane.** Przeglądarka komunikuje się wyłącznie z serwerem frontendu; middleware Next.js (`web/proxy.ts`) przekazuje `/api/*` i `/ws/*` do backendu FastAPI **wewnątrz kontenera**. Opublikowanie `8001` (`-p 127.0.0.1:8001:8001`) jest opcjonalne — przydatne tylko do bezpośredniego uderzania w API z curl lub skryptów. Otwórz [http://127.0.0.1:3782](http://127.0.0.1:3782). Kontener tworzy `/app/data/user/settings/*.json` przy pierwszym uruchomieniu; skonfiguruj dostawców modeli ze strony Web Settings. Konfiguracja, klucze API, dzienniki, domyślny Content Workspace, pamięć i bazy wiedzy są przechowywane w woluminie `deeptutor-data`. Oddzielnie zamontowany Content Workspace zachowuje się zamiast tego w swojej ścieżce hosta. Opcjonalne dodatki należą do wdrożenia, nie do powłoki: ustaw `DEEPTUTOR_EXTRAS` (oraz `DEEPTUTOR_APT_PACKAGES` dla bibliotek systemowych), a każdy kontener uruchomiony z tego wdrożenia ponownie je zastosuje, podczas gdy `docker exec … pip install` zostałby utracony przy kolejnym `compose down`. - **Różne porty hosta:** zmień lewą stronę każdego mapowania `-p host:kontener` (np. `-p 127.0.0.1:8088:3782`). Jeśli zmienisz porty po stronie kontenera w `/app/data/user/settings/system.json`, uruchom ponownie i zaktualizuj prawą stronę każdego mapowania, aby pasowała. - **Odłączony:** dodaj `-d`, następnie `docker logs -f deeptutor`, aby śledzić, `docker stop deeptutor`, aby zatrzymać, `docker rm deeptutor` przed ponownym użyciem nazwy. Wolumin `deeptutor-data` przechowuje prywatne dane środowiska uruchomieniowego i domyślny Content Workspace między restartami; oddzielnie zamontowany Content Workspace zachowuje się w swojej ścieżce hosta. **Zdalny Docker / odwrotne proxy:** przeglądarka komunikuje się wyłącznie z serwerem frontendu (`:3782`); middleware Next.js wewnątrz kontenera przekazuje `/api/*` i `/ws/*` do serwera backendu po stronie serwera. W typowym przypadku jednego kontenera nie konfigurujesz w ogóle bazowego adresu API — po prostu skieruj swój reverse proxy / terminator TLS na `:3782`. Bazowy adres API jest potrzebny tylko dla **wdrożenia rozdzielonego** (backend w osobnym kontenerze/hoście): ustaw `next_public_api_base` w `data/user/settings/system.json` na adres sieciowy, którego serwer frontendu używa do osiągnięcia backendu (jest czytany po stronie serwera, nigdy nie wysyłany do przeglądarki). ```json { "next_public_api_base": "http://backend:8001" } ``` `next_public_api_base_external` (i jego alias `public_api_base`) są akceptowane jako fallbacki o niższym priorytecie. CORS używa **źródeł** frontendu, a nie adresów URL API. Przy wyłączonym uwierzytelnianiu DeepTutor domyślnie zezwala na normalne źródła przeglądarki HTTP/HTTPS. Przy włączonym uwierzytelnianiu dodaj dokładne źródła frontendu: ```json { "cors_origins": ["https://deeptutor.example.com"] } ```

Łączenie z Ollama / LM Studio / llama.cpp / vLLM / Lemonade na hoście

Wewnątrz Dockera `localhost` to sam kontener, a nie maszyna hosta. Aby dotrzeć do usługi modelu działającej na hoście, użyj bramy hosta (zalecane): ```bash docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 -p 127.0.0.1:8001:8001 \ --add-host=host.docker.internal:host-gateway \ -v deeptutor-data:/app/data \ ghcr.io/hkuds/deeptutor:latest ``` Następnie w **Settings → Models** wskaż bazowy URL dostawcy na `host.docker.internal`: - Ollama LLM: `http://host.docker.internal:11434/v1` - Ollama embedding: `http://host.docker.internal:11434/api/embed` - LM Studio: `http://host.docker.internal:1234/v1` - llama.cpp: `http://host.docker.internal:8080/v1` - Lemonade: `http://host.docker.internal:13305/api/v1` Docker Desktop (macOS/Windows) zazwyczaj rozwiązuje `host.docker.internal` bez `--add-host`. Na Linuksie flaga jest przenośnym sposobem tworzenia tej nazwy hosta w nowoczesnym Docker Engine. **Alternatywa dla Linuksa — sieć hosta:** dodaj `--network=host` i usuń flagi `-p`. Kontener bezpośrednio współdzieli sieć hosta, więc otwórz [http://127.0.0.1:3782](http://127.0.0.1:3782) (lub `frontend_port` w `system.json`), a usługi hosta są dostępne pod normalnymi adresami URL localhost jak `http://127.0.0.1:11434/v1`. Pamiętaj, że sieciowanie hosta bezpośrednio ujawnia porty kontenera na hoście i może powodować konflikty z istniejącymi usługami — aby utrzymać je na loopback, ustaw `BACKEND_HOST=127.0.0.1` i `FRONTEND_HOST=127.0.0.1` (patrz [CONTAINERIZATION.md](../../CONTAINERIZATION.md)).

Opcja 4 — Tylko CLI · bez interfejsu webowego, z kodu źródłowego

Gdy nie potrzebujesz interfejsu webowego. Pakiet tylko CLI jest instalowany ze źródłowego kodu, a nie z PyPI. ```bash git clone https://github.com/HKUDS/DeepTutor.git cd DeepTutor # Utwórz venv (macOS/Linux). Windows PowerShell: # py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1 python3 -m venv .venv-cli && source .venv-cli/bin/activate python -m pip install --upgrade pip python -m pip install -e ./packaging/deeptutor-cli deeptutor init --cli deeptutor chat ``` `deeptutor init --cli` współdzieli ten sam układ `data/user/settings/` co pełna aplikacja, ale pomija monity o porty backendu/frontendu. Nadal udostępnia selektory Embedding i Search (wybierz **Skip**, gdy ich nie potrzebujesz), zapisuje kluczowe pliki środowiska uruchomieniowego (`system.json`, `auth.json`, `integrations.json`, `interface.json`, `model_catalog.json`, `main.yaml`, `agents.yaml`) i pyta o aktywnego dostawcę LLM i model.

Typowe polecenia

```bash deeptutor chat # interaktywny REPL deeptutor chat --capability deep_solve --tool rag --kb my-kb deeptutor run chat "Explain Fourier transform" deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb deeptutor kb create my-kb --doc textbook.pdf deeptutor memory show deeptutor config show ```

Lokalna instalacja `deeptutor-cli` nie zawiera zasobów webowych ani zależności serwera. Zachowaj kod źródłowy — instalacja edytowalna wskazuje na niego. Aby dodać aplikację Web później, zainstaluj pakiet PyPI (Opcja 1) i uruchom `deeptutor init` + `deeptutor start` z tego samego obszaru roboczego.

Piaskownica wykonania kodu (umiejętności biurowe) · uruchamianie kodu generowanego przez model dla docx / pdf / pptx / xlsx

Wbudowane umiejętności biurowe — **docx / pdf / pptx / xlsx** — działają, sprawiając że model pisze krótki skrypt Python (`python-docx`, `reportlab`, `openpyxl`, …), uruchamia go przez pojedyncze narzędzie `exec` i przedstawia zapisany plik obszaru roboczego. Te narzędzia montują się zawsze, gdy aktywny jest backend piaskownicy. DeepTutor wybiera najsilniejszy skonfigurowany backend w następującej kolejności: - **Runner sidecar:** `DEEPTUTOR_SANDBOX_RUNNER_URL` kieruje wykonanie do utwardzonej usługi o najmniejszych uprawnieniach z `Dockerfile.runner`. - **Linux bubblewrap:** gdy `bwrap` jest dostępny, izoluje proces i pliki. - **Awaryjny ograniczony podproces:** instalacje lokalne i jednokontenerowe używają go tylko wtedy, gdy jest dozwolony; w Dockerze kontener pozostaje dodatkową granicą. Ustawienie `sandbox_allow_subprocess` w `data/user/settings/system.json` (domyślnie `true`) kontroluje wyłącznie ostatni wariant awaryjny. Ustaw je na `false` (lub wyeksportuj `DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0`), aby odmówić wykonania w podprocesie, gdy nie jest dostępny backend runner ani `bwrap`; nie wyłącza to tych silniejszych backendów.

Odniesienie do konfiguracji — pliki konfiguracyjne w data/user/settings/ (JSON/YAML)

Wszystko w `data/user/settings/` to zwykły JSON/YAML. Strona **Settings** w przeglądarce jest zalecanym edytorem. | Plik | Cel | |:---|:---| | `model_catalog.json` | Połączenia dostawców oraz profile LLM, zadań, osadzania, wyszukiwania, TTS, STT, obrazów i wideo, dane uwierzytelniające i aktywne wybory | | `system.json` | Porty backendu/frontendu, publiczna baza API, CORS, weryfikacja SSL, katalog załączników i limity przesyłania/ekstrakcji | | `auth.json` | Opcjonalny przełącznik uwierzytelniania, nazwa użytkownika, hash hasła, ustawienia tokena/cookie | | `integrations.json` | Opcjonalne ustawienia PocketBase i integracji sidecar | | `interface.json` | Preferencje języka interfejsu i języka odpowiedzi modelu / motywu / paska bocznego | | `content_workspace.json` | Powiązania folderów Content Workspace i aktywny wybór obszaru roboczego | | `video_learning.json` | Domyślny dostawca odtwarzania YouTube/Invidious, źródła Invidious i opcjonalny adapter transkrypcji | | `main.yaml` | Domyślne zachowanie środowiska uruchomieniowego i wstrzykiwanie ścieżek | | `agents.yaml` | Ustawienia temperatury i tokenów możliwości/narzędzi | Odwołania Web Search są domyślnie filtrowane: wyświetlane są wyłącznie publiczne adresy URL `http`/`https` bez osadzonych danych uwierzytelniających ani nietypowych portów. Wdrożenia mogą dodać politykę domen skoncentrowaną na edukacji w `data/user/settings/system.json`: ```json { "web_search_source_filtering": { "enabled": true, "blocked_domains": ["spam.example"], "trusted_domains": ["edu.cn", "arxiv.org"] } } ``` Gdy `trusted_domains` nie jest puste, odwołania są ograniczone do tych domen i ich subdomen; `blocked_domains` zawsze ma pierwszeństwo. Plik `.env` w katalogu głównym projektu **nie** jest czytany jako plik konfiguracyjny aplikacji. Dla minimalnej konfiguracji modelu otwórz **Settings → Models**, dodaj profil LLM (bazowy URL / klucz API / nazwa modelu) i zapisz. Dodaj profil osadzania tylko jeśli planujesz korzystać z funkcji Bazy wiedzy / RAG. Profile LLM i modeli zadaniowych udostępniają ustawienie **formatu API**, gdy ich dostawca umożliwia wybór. Pozostaw `Auto` dla zwykłego routingu i mechanizmu awaryjnego albo wybierz `OpenAI Chat Completions`, `OpenAI Responses` lub `Anthropic Messages`; wymuszony tryb Responses nadal działa w sposób fail-closed. Zapisywane pole to `api_format` (`auto`, `openai_chat`, `openai_responses` lub `anthropic`); `wire_api` jest pochodnym stanem kompatybilności. Nadpisania `Auto` / `Supported` / `Not supported` dla poszczególnych modeli obejmują wywoływanie narzędzi, dane wejściowe obrazów, dane wyjściowe JSON i sterowanie rozumowaniem.

Odinstalowanie i czyszczenie

DeepTutor oddziela zainstalowany kod, prywatny obszar roboczy środowiska uruchomieniowego i opcjonalny Content Workspace. Domyślnie obszarem roboczym środowiska uruchomieniowego jest katalog, w którym uruchamiasz `deeptutor init` / `deeptutor start`; `--home PATH` lub `DEEPTUTOR_HOME` go zastępuje. Prywatny stan aplikacji to katalog `data` wewnątrz tego obszaru roboczego, więc wiersz banera startowego zaczynający się od `Workspace:` wskazuje tę lokalizację środowiska uruchomieniowego. Jeśli **Settings → Workspace** wskazuje na inny folder, wykonaj kopię zapasową lub usuń ten folder treści osobno; nie jest on celowo usuwany podczas odinstalowywania DeepTutor. 1. Zatrzymaj aplikację. Naciśnij `Ctrl+C` w terminalu, w którym działa `deeptutor start`, albo uruchom `deeptutor stop [--home PATH]` dla launchera uruchomionego z `--detach`; przed usunięciem danych zatrzymaj wszystkie działające Partners i odłączone kontenery Docker. 2. Usuń dane środowiska uruchomieniowego tylko wtedy, gdy chcesz również wymazać cały stan lokalny. Obejmuje to ustawienia i klucze API, historię czatu, sesje, Memory, Notebooks, Books, stan Reading, Skills, stan Partners, dzienniki, Knowledge Bases, pamięci podręczne parsowania, wygenerowane artefakty i pamięć podręczną środowiska uruchomieniowego spakowanego frontendu. Najpierw skopiuj dokładną ścieżkę `Workspace:` z banera startowego i upewnij się, że jej element potomny `data` jest właściwym katalogiem danych DeepTutor. Jeśli cokolwiek może być potrzebne później, wykonaj kopię zapasową, a następnie przenieś dokładnie ten katalog do Kosza systemu operacyjnego. Nie uruchamiaj polecenia usuwania rekurencyjnego na ścieżce względnej ani nierozwiązanej zmiennej środowiskowej. 3. Usuń zainstalowany pakiet. Użyj polecenia odpowiedniego dla dystrybucji: ```bash python -m pip uninstall deeptutor python -m pip uninstall deeptutor-cli ``` Jeśli środowisko wirtualne utworzono wyłącznie dla DeepTutor, usuń je za pomocą menedżera środowisk. W przypadku instalacji ze źródeł zdezaktywuj środowisko, opuść katalog źródłowy i uruchom `git status --short` wewnątrz dokładnie tego kodu źródłowego. Przenieś go do Kosza dopiero po potwierdzeniu, że nie zawiera niepowiązanej ani niezacommitowanej pracy. 4. Dla ścieżki Docker sprawdź dokładny kontener i nazwany wolumin przed ich usunięciem. Usunięcie woluminu trwale wymazuje dane zarządzane przez Docker: ```bash docker ps -a --filter name=^/deeptutor$ docker volume inspect deeptutor-data docker rm -f deeptutor docker volume rm deeptutor-data ```

## 📖 Eksploracja DeepTutor Zacznij od głównych powierzchni, których będziesz używać na co dzień: Chat, Partners, My Agents, Co-Writer, Book, Knowledge Center, Learning Space, Memory i Settings. Wycieczka obejmuje następnie wdrożenia dla wielu użytkowników dla współdzielonych, izolowanych obszarów roboczych. Jeśli odpowiedź pomija wcześniejsze ograniczenie, przywołuje słabe dowody lub jest sprzeczna z wybranym materiałem, przed otwarciem issue zbierz dane diagnostyczne zgodnie z [`REASONING_SAFETY_CHECKLIST.md`](../../REASONING_SAFETY_CHECKLIST.md).

Strona główna DeepTutor — obszar roboczy Chat z każdą powierzchnią w pasku bocznym

> **Stan zrzutów ekranu:** widok ogólny jest aktualny dla wersji v1.6.5. Poniższe zrzuty powierzchni pozostają odniesieniami z wersji v1.4.6 w trakcie aktualizacji; zobacz [inwentarz zrzutów](../../UI_SCREENSHOT_REFRESH.md). Służą do zrozumienia przepływów, a nie jako dokładna bieżąca nawigacja.

🏗️ Architektura systemu

💬 Chat — Pętla agenta, z której naprawdę korzystasz

Chat to domyślna możliwość i miejsce, gdzie zaczyna się większość pracy. Jeden wątek może rozmawiać normalnie, wywoływać narzędzia, opierać się na wybranych bazach wiedzy, czytać załączniki, generować obrazy, konsultować subagentów, pisać rekordy notatnika i kontynuować z tym samym kontekstem przez tury.

Pętla jest celowo prosta: model myśli w rundach, wywołuje narzędzia gdy są przydatne, obserwuje wyniki i kończy wiadomością bez narzędzi. `ask_user` jest wyjątkowy — zamiast zgadywać, agent może wstrzymać turę, zadać ustrukturyzowane pytanie wyjaśniające i wznowić po odpowiedzi.

Narzędzia przełączalne przez użytkownika to `brainstorm`, `web_search`, `paper_search`, `reason` i `geogebra_analysis` — plus `imagegen` i `videogen` po skonfigurowaniu odpowiedniego modelu generowania. Narzędzia kontekstowe takie jak `rag`, `kb_files`, `knowledge_frontier`, `read_source`, `read_memory`, `write_memory`, `read_skill`, `load_tools`, `exec`, `web_fetch`, `ask_user`, `list_notebook`, `write_note`, `question_bank`, `github`, `consult_subagent`, `workspace_list`, `workspace_read`, `workspace_search`, `workspace_present` i `workspace_export` montują się automatycznie gdy tura ma odpowiedni kontekst. Kontekst dzieli się na dwa rodzaje: **trwały kontekst sesji** (możliwość, obszar roboczy lub kurs, narzędzia, bazy wiedzy, persona, model oraz stan Reading / Mastery) jest zachowany przez tury; **jednorazowe odwołania** (pliki, historia czatu, książki, sekcje do czytania, notatniki, bank pytań, zaimportowani agenci) pochodzą z menu `+` dla jednej tury. Przycisk głosowy jedynie transkrybuje bieżącą wiadomość. Home daje dostęp jednym kliknięciem do **Chat**, **Ask Questions**, **Quiz** i **Visualize**; **Research** do raportów z cytowaniami, **Solve** do rozumowania krok po kroku oraz **Immersive Watching** znajdują się w sekcji *More Capabilities*. **Mastery Path** i **Immersive Reading** mają dedykowane obszary robocze na pasku bocznym; Reading dodaje zweryfikowane, klikalne cytowania, zapisane cytowania i notatki, oparte na źródłach działania czytania na głos / wskazówek do nauki / słownictwa / quizu / tłumaczenia oraz przechwytywanie do notatnika, a Course Study zachowuje własny kontekst związany z kursem.

🤝 Partner — Stali towarzysze na tym samym mózgu

Partners to stali towarzysze z własną duszą, polityką modelu, biblioteką, pamięcią i kanałami. Nie są osobnym silnikiem bota: każda przychodząca wiadomość webowa lub IM staje się normalną turą `ChatOrchestrator` wewnątrz obszaru roboczego z zakresem partnera. Partner to „czat który ma osobowość i numer telefonu."

Każdy partner ma `SOUL.md`, wybór modelu, kanały, politykę narzędzi i przypisaną bibliotekę. Bazy wiedzy, umiejętności i notatniki są kopiowane do `data/partners//workspace/`, więc te same narzędzia RAG, umiejętności, notatnika i pamięci działają bez specjalnych przypadków. Uwierzytelnieni użytkownicy bez uprawnień administratora zachowują prywatne sesje Partner i pamięć relacji, a Partner odczytuje ich pamięć osobistą tylko do odczytu; ruch administratorów, grup i użytkowników niepowiązanych korzysta ze wspólnego zakresu Partner.

Warstwa kanałów jest sterowana schematem i może łączyć się z platformami IM takimi jak Feishu, Telegram, Slack, Discord, DingTalk, QQ/NapCat, WeCom, WhatsApp, Zulip, Mattermost, Matrix, Mochat i Microsoft Teams w zależności od zainstalowanych dodatków i skonfigurowanych danych uwierzytelniających. Partner może być również podłączony jako subagent i konsultowany z normalnej tury czatu — patrz **My Agents** poniżej. Dla szybszej konfiguracji strona kanału Partner może utworzyć aplikację Feishu/Lark lub bota AI WeCom, albo zalogować osobiste konto WeChat, na podstawie kodu QR narysowanego w przeglądarce zamiast w dzienniku serwera. Feishu/Lark wykrywa domenę konta i zapisuje skanującego użytkownika jako początkowego dozwolonego nadawcę. WeCom zachowuje istniejącą listę dozwolonych, a w przeciwnym razie domyślnie zezwala wszystkim użytkownikom, którzy mogą dotrzeć do bota, z widocznym ostrzeżeniem o otwartym dostępie; ręczne formularze kanałów pozostają dostępne, jeśli protokół skanowania dostawcy się zmieni.

🧑‍🚀 My Agents — Konsultuj i importuj innych agentów

My Agents zamienia innych agentów w kontekst dla DeepTutor i wykonuje dwie odrębne rzeczy. **Połącz żywego agenta** — Claude Code, Codex, Antigravity, Kimi, opencode, MiMo Code, Hermes Agent, OpenClaw lub DeepSeek Harness na twoim komputerze, lub jednego z twoich Partners — i konsultuj go z wnętrza tury czatu: DeepTutor faktycznie *uruchamia* drugiego agenta i strumieniuje jego pracę do panelu Activity przez narzędzie `consult_subagent`. Wybierz go i jego limit rund za pomocą chipa Agent lub przefiltruj tę samą listę połączonych agentów za pomocą `@`; wybór pozostaje powiązany z sesją.

Konsultowanie subagenta Claude Code na żywo

**Importuj poprzednie konwersacje** — przynieś swoją istniejącą historię Claude Code i Codex jako nazwane, przeszukiwalne, wznawialne agenty. Historię Claude wybieraj według projektu / katalogu roboczego, a historię Codex według daty kalendarzowej; odświeżenie ponownie synchronizuje ten zakres i pobiera nowe konwersacje. Odwołaj się do jednej z nich z tury Chat przez `+` → My Agents, a DeepTutor czyta ją jako transkrypt osoby trzeciej — pozostaje *ich* konwersacją, nie własnym głosem DeepTutor.

✍️ Co-Writer — Edycja Markdown z uwzględnieniem zaznaczenia

Co-Writer to obszar roboczy Markdown z podzielonym widokiem dla raportów, samouczków, notatek i długich artefaktów uczenia się. Dokumenty są automatycznie zapisywane, renderują podgląd na żywo (matematyka KaTeX, schematy), i mogą być zapisane z powrotem do notatników gdy szkic staje się kontekstem wielokrotnego użytku. Zaimportuj `.docx`, aby rozpocząć szkic, i eksportuj bieżący edytor jako Markdown lub Word.

Jego wyróżniającym pomysłem jest **precyzyjna edycja**: zaznacz fragment i poproś DeepTutor o przepisanie, rozszerzenie lub skrócenie. Agent edycji może ugruntować zmianę w bazie wiedzy lub dowodach webowych i zachowuje ślad swoich wywołań narzędzi. Jeśli szkic nie zmienił się podczas jego pracy, wynik bezpośrednio zastępuje zaznaczony tekst i nadal można go cofnąć za pomocą **Undo**.

📖 Book — Żywe książki z twoich materiałów

Book zamienia wybrane źródła w interaktywną **żywą książkę** — nie statyczny PDF, ale środowisko czytelnicze zbudowane z typowanych bloków. Książka może zaczynać się od baz wiedzy, notatników, banków pytań lub historii czatu; przepływ tworzenia proponuje konspekt rozdziałów przed wygenerowaniem treści, więc przeglądasz kształt zamiast akceptować ślepe jednorazowe wyjście.

Blok quizu w książce Blok animacji Manim w książce Blok interaktywnego widżetu w książce

Każdy rozdział kompiluje się do edytowalnych, typowanych bloków — tekstu, callouts, quizów, fiszek, osi czasu, kodu, figur, interaktywnego HTML, animacji, grafów konceptów, dogłębnych analiz i notatek użytkownika — i ma własny Page Chat. Wstawiaj, przenoś, regeneruj i przepisuj bloki lub zmieniaj ich typ; zaznaczone fragmenty trafiają do skrzynki materiałów do nauki, gdzie można je przejrzeć. Postępy, zakładki, próby quizów, materiały do nauki i Page Chat pozostają prywatne dla każdego czytelnika, nawet gdy książka administratora jest udostępniona tylko do odczytu lub do wspólnej edycji; współdzieloną książkę nadal może usunąć tylko administrator. Każdą książkę można wyeksportować do Markdown, długa kompilacja może być wstrzymywana i wznawiana, a `deeptutor book health` / `refresh-fingerprints` sygnalizują dryf źródeł.

📚 Knowledge Center — Wielosilnikowe biblioteki RAG

Bazy wiedzy to kolekcje dokumentów za RAG — ugruntowują tury Chat, edycje Co-Writer, generowanie Book i konwersacje Partner. Wyróżnikiem jest **wybór silnika wyszukiwania**: **LlamaIndex** (domyślny, hybrydowy wektor + BM25 z opcjonalnym ponownym rankingiem cross-encoder i indeksami FAISS exact-flat lub HNSW), **PageIndex** (wyszukiwanie z rozumowaniem z cytowaniami na poziomie strony, hostowany lub samodzielnie hostowany open source), **GraphRAG** i **LightRAG** (wyszukiwanie oparte na grafach wiedzy), **LightRAG Server** (wyszukiwanie odciążone do zewnętrznej instancji LightRAG którą łączysz przez HTTP), **WeKnora** (wyszukiwanie z bazy wiedzy w samodzielnie hostowanym wdrożeniu, bez lokalnego indeksu ani kopii dokumentów), **Tencent IMA** (biblioteka którą kurujesz w IMA — przeszukiwana, przeglądana i zapisywana z powrotem przez jego OpenAPI), **MarginNote 4** (Twoje dane MN4 — dokumenty, wyciągi, karty mapy myśli i połączenia między nimi — przesyłane przez Add-on aplikacji i przeglądane za pomocą dedykowanych narzędzi), lub podłączony vault **Obsidian** który tutor czyta i zapisuje w miejscu. Każda KB jest powiązana z jednym silnikiem.

Przenosisz istniejącą bibliotekę Obsidian, Hermes lub Markdown? Zobacz [przewodnik po migracji wiedzy](../../KNOWLEDGE_MIGRATION.md), aby poznać ścieżki podłączonego vault i indeksowanej kopii. Tworząc KB, albo **tworzysz nową** (przesyłasz dokumenty i budujesz świeży indeks), albo **łączysz istniejącą** (ponownie używasz indeksu zbudowanego gdzie indziej, czytasz w miejscu bez ponownego indeksowania). Baza wiedzy może też śledzić **repozytoria GitHub** (repozytorium, gałąź i wzorzec glob) lub **adresy URL witryn dokumentacji** (z ograniczoną głębokością przeszukiwania i liczbą stron); synchronizacja na żądanie porównuje skróty treści, aby wykryć elementy dodane, zmienione i usunięte, dzięki czemu śledzona dokumentacja pozostaje aktualna bez ponownego przesyłania. Ponowne indeksowanie zapisuje nowy płaski katalog `version-N` i zachowuje poprzednie, więc działający indeks nigdy nie jest niszczony w trakcie przebudowy. Pojedynczy dokument można usunąć nawet z bazy w stanie **błędu** — usuwając plik, który nie sparsował się poprawnie, bez pełnego usuwania i przebudowy. Parsowanie dokumentów — Tylko tekst, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM lub LiteParse — jest wybierane w **Settings → Knowledge Base**, z domyślnie wyłączonymi pobieraniami lokalnego modelu. Docling może też działać w trybie **zdalnym** względem serwera Docling Serve (bez lokalnej instalacji czy modeli), konfigurowanym przez **Settings → Document Parsing** (`mode=remote`, bazowy URL serwera i opcjonalny klucz API) lub zmienne środowiskowe `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika jest wyłącznie zdalna i wskazuje na serwer Apache Tika skonfigurowany na tej stronie. CLI odzwierciedla cykl życia przez `list/info/create/add/search/set-default/delete`, polecenia dodawania/usuwania źródeł, `list-sources` i `sync`. Wbudowany silnik LightRAG instaluje się poleceniem `pip install 'deeptutor[rag-lightrag]'`. Ten dodatek zawiera obsługiwany SDK LightRAG, ale nie instaluje MinerU. Wybierz MinerU niezależnie w Document Parsing i skonfiguruj jego tryb chmurowy albo zainstaluj jego aktualny lokalny CLI, gdy potrzebne jest strukturalne parsowanie. MinerU akceptuje pliki PDF, popularne obrazy rastrowe, DOCX, PPTX i XLSX; starsze polecenie `magic-pdf` nadal obsługuje wyłącznie pliki PDF. Tryb tylko tekstowy i pozostałe silniki parsowania nie wymagają MinerU.

🌐 Learning Space — Umiejętności, persony i kontekst wielokrotnego użytku

Learning Space to warstwa biblioteki, organizacji i personalizacji. **Conversations & Materials** obejmuje Chat History, notatniki — z rekordami, które można przenosić lub kopiować między notatnikami, oraz eksportem do Markdown — i bank pytań zachowujący twoją odpowiedź, odpowiedź referencyjną i wyjaśnienie. **Personalization** obejmuje persony, umiejętności (podręczniki `SKILL.md`), instalowane jednym kliknięciem **Usługi MCP** oraz **Aplikacje CLI** z katalogu [CLI-Anything](https://github.com/HKUDS/CLI-Anything), każdą z przewodnikiem użycia wczytywanym na żądanie. Oddzielny obszar roboczy **My Courses** grupuje rozmowy według przedmiotów i wątki tutorów; każdy zasób jest oferowany tylko w przepływach pracy, które go obsługują.

Nie musisz pisać każdej umiejętności samodzielnie — **Import from EduHub** przegląda katalog społecznościowy i pobiera umiejętność bezpośrednio do twojej biblioteki przez bramę bezpieczeństwa (patrz [Ekosystem](#-ekosystem--eduhub-i-społeczność-umiejętności)).

🧠 Memory — Inspektowalna personalizacja

Memory to system trzywarstwowy oparty na plikach, który możesz czytać, selekcjonować i audytować — celowo *nie* ukryty magazyn wektorowy. **L1** to lustro obszaru roboczego plus dołączany ślad zdarzeń (`trace//.jsonl`); **L2** to wyselekcjonowane fakty per-powierzchnia (`L2/.md`) z odwołaniami do encji L1; **L3** to synteza między-powierzchniowa (`L3/.md`), która zapisuje uczestniczące powierzchnie L2.

Memory Graph pokazuje całą piramidę — synteza L3 w centrum, L2 w środkowym pierścieniu, ślady L1 na zewnątrz — z dokładnymi krawędziami dowodów L2 → L1 i połączeniami L3 → powierzchnie uczestniczące. Memory jest śledzone przez powierzchnie `chat`, `notebook`, `quiz`, `kb`, `book`, partner i `cowriter`; budżety Update / Audit / Dedup konsolidatora są dostosowywane w **Settings → Memory**.

⚙️ Settings — Jedna płaszczyzna kontroli

Settings to operacyjna płaszczyzna kontroli, otwierająca się paskiem statusu na żywo (stan backendu i pamięć rezydentna), językiem interfejsu i językiem odpowiedzi modelu oraz macierzą **Readiness**, która ocenia każdą możliwość jako blocker, ostrzeżenie lub sugestię — a następnie trwałym, przeszukiwalnym nawigatorem, który pozwala dotrzeć do dowolnej strony jednym kliknięciem: **Appearance** (motyw, stylizacja bloków kodu), **Network** (baza API, porty, CORS), **Workspace** (folder odczytywalny przez agentów i jego współdzielony `outputs/`), **Models** (Połączenia, LLM, Modele zadań, Embedding, Search, Text-to-Speech, Speech-to-Text, Image Generation, Video Generation), **Knowledge Base** (silnik parsowania dokumentów), **Chat** (Video Learning, przeszukiwalne narzędzia, parametry per-możliwość, punkty startowe, limity załączników), **Partners & Agents** (dziewięć lokalnych środowisk uruchomieniowych agentów), **Profil ucznia** (wiek, klasa, program nauczania, język, poziom czytania, styl wyjaśnień), **Guardian** (upoważnieni uczniowie, materiały, raporty, resetowanie poświadczeń), **Memory** (budżety konsolidatora) i **About** (sprawdzanie wersji i bezpieczne aktualizacje). **Połączenie** przechowuje jedno poświadczenie dostawcy i odzwierciedla je w każdej usłudze, którą ten dostawca może obsłużyć, więc klucz wprowadza się raz zamiast wklejać go na pięciu stronach; **modele zadań** przypinają mały, szybki model do pracy, o którą nikt nie prosił — nadawanie nazwy rozmowie, pisanie punktów startowych w composerze — i domyślnie sięgają po aktywny model, gdy pozostawione są puste. **Video Learning** w Settings → Chat domyślnie korzysta z oficjalnego odtwarzacza YouTube IFrame Player o podwyższonej ochronie prywatności. Aby odtwarzać lokalnie, ustaw zarządzane przez administratora źródło API Invidious (na przykład `http://127.0.0.1:3000`), przetestuj je, wybierz Invidious i zapisz. Nowe lub ponownie otwarte filmy natychmiast przejmują dostawcę, zachowując ten sam identyfikator materiału i postęp. Multimedia Invidious są strumieniowane przez proxy zakresów bajtów DeepTutor; nadrzędne adresy URL nie są ani ujawniane przeglądarce, ani zapisywane na dysku. Jeśli instancja ulegnie awarii, DeepTutor pozostaje odłączony od YouTube, dopóki uczeń nie wybierze jawnie natywnego trybu awaryjnego YouTube. Korepetycje oparte na publicznych napisach są opcjonalne: zainstaluj `.[video-learning]`; bez niego odtwarzanie nadal działa, natomiast funkcja **Explain here** oparta na transkrypcji jest wyłączona wraz z podaniem przyczyny.

Większość sekcji używa przepływu szkic-i-zastosuj, więc możesz testować dostawcę przed jego zatwierdzeniem. Możesz też po prostu zapytać w Chat: asystent odczytuje bieżącą konfigurację, stosuje zmianę i mówi, czy potrzebny jest restart lub ponowne indeksowanie — sprawdzając nowy model zanim go zatwierdzi, więc nie może sam przełączyć się na coś nieosiągalnego. Klucze API nigdy nie przechodzą przez model, który zamiast tego otwiera odpowiedni formularz. Cztery motywy dostarczane w zestawie — Default, Cream, Dark i Glass. Pliki `.env` katalogu głównego projektu są celowo ignorowane; konfiguracja środowiska uruchomieniowego żyje pod `data/user/settings/*.json` chyba że `DEEPTUTOR_HOME` lub `deeptutor start --home` wskaże aplikację gdzie indziej. **OpenAI Codex OAuth (eksperymentalne).** Wybranie **OpenAI Codex** w Models → LLM zastępuje pola klucza API logowaniem przez przeglądarkę, które działa względem twojego własnego planu ChatGPT, więc `OPENAI_API_KEY` nie jest potrzebny. Tokeny żyją wyłącznie w `data/system/user-secrets//private/openai-codex/` — w wielokontenerowym wdrożeniu Compose, poza każdym drzewem, do którego ma dostęp piaskownica wykonania kodu — a DeepTutor nigdy nie czyta ani nie modyfikuje twojego logowania CLI `~/.codex`. Lista modeli pochodzi z aktualnego katalogu tego konta; zalogowanie się publikuje profil, ale staje się aktywnym modelem tylko gdy żaden LLM nie jest jeszcze skonfigurowany. Ponieważ token autoryzuje plan jednej osoby, profilu nie da się współdzielić przez uprawnienia użytkowników — każde konto loguje się osobno, w tym zwykli użytkownicy: ich karta znajduje się w Models → LLM, a wynikowe modele, katalog i wylogowanie pozostają prywatne dla tego konta. Domyślne lokalne wdrożenia Docker i Podman używają oddzielnych sieci loopback i podczas logowania wymagają tymczasowego mostu. Postępuj zgodnie z [przewodnikiem po tymczasowym lokalnym moście OAuth Codex](../../CONTAINERIZATION.md#temporary-local-codex-oauth-bridge), aby poznać dokładne komendy dla Docker, Compose, Podman i demontażu. Dla zdalnego wdrożenia `localhost` przeglądarki i `localhost` serwera to dwie różne maszyny, więc sam zwykły reverse proxy nie może przenieść callbacku localhost przeglądarki do serwera. Użyj tunelu SSH jako mostu callback. Tunel dociera do już opublikowanego portu Web; Next.js przepisuje wyłącznie dokładną ścieżkę callback do publicznego brokera callback, a broker waliduje `state` przed przekierowaniem do pierwotnej operacji OAuth. Nasłuch callback pozostaje na loopbacku backendu, porty `1455` i `1457` nie są publikowane, a ta ścieżka obsługuje domyślną sieć bridge Dockera. ```bash ssh -N -L 1455:127.0.0.1:3782 @ ``` Jeśli DeepTutor zgłasza zapasowy port callback `1457`, użyj: ```bash ssh -N -L 1457:127.0.0.1:3782 @ ``` Uruchom tylko tę jedną komendę, która odpowiada rzeczywistemu portowi callback; nigdy nie uruchamiaj obu. `3782` to jedynie przykładowy port Web: to skonfigurowany port frontendu/kontenera, zgłaszany jako `callback_forward_port`. Ta wartość nie gwarantuje, że ten sam port nasłuchuje na `127.0.0.1` hosta SSH. Jeśli Docker lub Podman publikuje inny port hosta, albo reverse proxy nasłuchuje na innym porcie, zamień wyłącznie prawą stronę portu docelowego (`3782` powyżej) na port Web faktycznie nasłuchujący na `127.0.0.1` hosta SSH; zachowaj lewy port callback jako `1455` lub `1457`. `` to host SSH, którego loopback jest właścicielem tego nasłuchującego portu. Jeśli URL przeglądarki wskazuje na reverse proxy lub load balancer, zamień go na poprawny host frontendu SSH. CLI wypisuje komendę tunelu, a następnie od razu próbuje otworzyć przeglądarkę. Przy zdalnym wdrożeniu zostaw stronę autoryzacji otwartą bez jej kończenia, ustanów wypisany tunel w innym terminalu i dopiero wtedy kontynuuj autoryzację. Wykrywanie topologii zdalnej ma granicę localhost. Jeśli sam Web jest osiągany przez przekierowanie localhost SSH lub IDE, przeglądarka nie może stwierdzić, że serwer jest zdalny. Dla bieżącej operacji Web zostaw jej stronę autoryzacji niedokończoną, odczytaj `redirect_uri` w URL autoryzacji tej operacji, aby zidentyfikować port callback `1455` lub `1457`, i utwórz drugi tunel z tego lokalnego portu do rzeczywistego portu Web. Alternatywnie, anuluj tę operację Web i rozpocznij nową przez CLI; wynik CLI należy do nowej operacji i nie może być użyty dla istniejącej operacji Web. Błędy limitu i awarie katalogu są zgłaszane wprost i nigdy nie powodują przełączenia na płatnego dostawcę. Ta ścieżka kompatybilności jest eksperymentalna: interfejs projektu nadrzędnego może się zmienić.

👥 Multi-User — Wdrożenia współdzielone · opcjonalne uwierzytelnianie, izolowane obszary robocze per-użytkownik

Uwierzytelnianie jest **domyślnie wyłączone** — DeepTutor działa jednoosobowo. Włącz je a jedno drzewo `data/` obsługuje obszar roboczy administratora, izolowane obszary robocze per-użytkownik i obszary robocze partnerów obok siebie: ```text data/ ├── user/ # Obszar roboczy administratora + globalne ustawienia ├── users// # Zakres per-użytkownik: historia czatu, pamięć, notatniki, KB ├── partners//workspace/ # Zakres partnera (użytkownika syntetycznego) ├── cli-apps/ # Zainstalowane aplikacje CLI, zamontowane tylko do odczytu w piaskownicy └── system/ # auth · grants · audit · user-secrets/ (tokeny OAuth) ``` **Pierwszy zarejestrowany użytkownik staje się administratorem** i jest właścicielem katalogów modeli, danych uwierzytelniających dostawców, współdzielonych baz wiedzy, umiejętności, kanonicznych współdzielonych książek i uprawnień per-użytkownik. Lokalni użytkownicy utworzeni przez administratora wybierają Standard, Learner lub Custom. Learner blokuje możliwości edukacyjne i politykę materiałów, dodaje profil adaptacyjny oraz obsługuje odwoływalne poświadczenia urządzenia z datą wygaśnięcia i limitami dziennymi; upoważnieni guardians mogą przeglądać raporty, zatwierdzać materiały i resetować poświadczenia. Pozostali użytkownicy otrzymują izolowane obszary robocze oraz ograniczony dostęp do modeli, KB, umiejętności, Partners i współdzielonych książek bez otrzymywania surowych kluczy API. Jeśli `auth.json` zawiera już `username` + `password_hash`, to konto *jest* administratorem: `/register` pozostaje zamknięte, a konta utworzone z `/admin/users` mają zawsze `role=user`, dopóki ich nie awansujesz. **Włącz:** włącz uwierzytelnianie w `data/user/settings/auth.json`, uruchom ponownie `deeptutor start`, zarejestruj pierwszego administratora pod `/register`, następnie dodaj użytkowników z `/admin/users` i przypisz modele, KB, umiejętności, Partners, politykę narzędzi/MCP/aplikacji CLI i dostęp do wykonania kodu przez uprawnienia; skonfiguruj współdzielone książki w panelu **Book access** każdego użytkownika. > PocketBase pozostaje integracją jednoosobową — zostaw `integrations.pocketbase_url` puste dla wdrożeń wieloużytkownikowych chyba że podłączyłeś zewnętrzny magazyn użytkowników.

## ⌨️ DeepTutor CLI — Interfejs natywny dla agentów Jeden plik binarny `deeptutor`, dwa sposoby wejścia: interaktywny **REPL** dla osób żyjących w terminalu i strukturalny **JSON** dla innych agentów które prowadzą DeepTutor jako narzędzie. Te same możliwości, narzędzia i bazy wiedzy w obu przypadkach.

Prowadź sam

`deeptutor chat` otwiera interaktywny REPL i wybiera tryb za pomocą `--capability`; `deeptutor run ""` przyjmuje tę możliwość jako pierwszy argument pozycyjny i kończy się po jednej turze. Oba przyjmują `--tool`, `--kb` i `--config`. ```bash deeptutor chat # interaktywny REPL deeptutor chat --capability deep_solve --kb my-kb --tool rag deeptutor run chat "Explain the Fourier transform" --tool rag --kb textbook deeptutor run chat "Find recent work beyond this material" --kb textbook --tool knowledge_frontier deeptutor run deep_research "Survey 2026 papers on RAG" \ --config mode=report --config depth=standard ``` Podstawowe zarządzanie obszarem roboczym jest dostępne również tutaj — bazy wiedzy (`kb`), sesje (`session`), partnerzy (`partner`), umiejętności (`skill`), notatniki, pamięć i konfiguracja; organizowanie kursów i sesji pozostaje w aplikacji Web. Pełna lista poniżej.

Niech agent prowadzi

DeepTutor jest zbudowany aby być *obsługiwany przez innego agenta*. Dodaj `--format json` do dowolnego `run` a każda tura strumieniuje **NDJSON — jedno zdarzenie na linię** (`content`, `tool_call`, `tool_result`, `done`, …), każda linia oznaczona swoim `session_id`. Uruchomienia są bezpieczne bez TTY: pauza `ask_user` bez TTY automatycznie rozwiązuje się pustą odpowiedzią zamiast zawieszać. ```bash # Jednorazowo, czytelne maszynowo deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json # Łącz tury w jednej sesji stanowej — przechwyć id, ponownie użyj SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \ --config mode=report --config depth=standard --format json \ | jq -r 'select(.type=="done").session_id') deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json ``` Repozytorium zawiera główny [`SKILL.md`](../../SKILL.md) — około 200-liniowy dokument przekazania który uczy każdy LLM używający narzędzi całej powierzchni w jednym czytaniu. Przekaż go Claude Code, Codex lub OpenCode (automatycznie pobierają `SKILL.md`) lub opakuj `deeptutor run` jako narzędzie w pętli LangChain / AutoGen. Pełne przepisy: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).

Odniesienie do poleceń

| Polecenie | Opis | |:---|:---| | `deeptutor init` | Utwórz lub zaktualizuj `data/user/settings` dla bieżącego obszaru roboczego | | `deeptutor doctor [--online]` | Sprawdź, czy obszar roboczy jest gotowy do rozpoczęcia sesji; `--online` sprawdza też skonfigurowanego dostawcę modelu, `--format json` wypisuje raport | | `deeptutor start [--home PATH] [--dev] [--detach] [--no-browser]` | Uruchom backend + frontend razem; opcjonalnie odłącz proces lub pomiń otwieranie przeglądarki | | `deeptutor stop [--home PATH]` | Zatrzymaj launcher uruchomiony z `--detach` | | `deeptutor serve [--port PORT]` | Uruchom tylko backend FastAPI | | `deeptutor workspace show/set/reset` | Sprawdź, wybierz lub przywróć Content Workspace per-użytkownika | | `deeptutor run ` | Uruchom jedną turę możliwości (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `immersive_watching`); dodaj `--format json` dla wyjścia NDJSON | | `deeptutor chat` | Interaktywny REPL z kontrolkami możliwości, narzędzia, KB, notatnika i historii | | `deeptutor partner list/create/start/stop` | Zarządzaj partnerami połączonymi przez IM | | `deeptutor kb list/info/create/add/search/set-default/delete/list-sources/sync` | Zarządzaj bazami wiedzy i synchronizuj zarejestrowane źródła GitHub/Web (z poleceniami dodawania/usuwania źródeł) | | `deeptutor skill search/install/list/remove/login/logout/publish/update` | Zarządzaj umiejętnościami, instaluj z hubów i publikuj własne (`eduhub:` domyślnie, patrz Ekosystem) | | `deeptutor memory show/clear` | Inspekcjonuj dokumenty pamięci L2/L3 lub wyczyść pamięć L1/wszystko | | `deeptutor session list/show/open/rename/delete` | Zarządzaj współdzielonymi sesjami | | `deeptutor notebook list/create/show/add-md/replace-md/remove-record` | Zarządzaj notatnikami z plików Markdown | | `deeptutor book list/health/refresh-fingerprints` | Inspekcjonuj książki i odświeżaj odciski źródeł | | `deeptutor plugin list/info` | Inspekcjonuj zarejestrowane narzędzia i możliwości | | `deeptutor config show` | Wydrukuj podsumowanie konfiguracji | | `deeptutor provider login ` | Uwierzytelnianie dostawcy (`openai-codex` logowanie OAuth; `github-copilot` weryfikuje istniejącą sesję auth Copilot; `codebuddy` weryfikuje uwierzytelnianie SDK CodeBuddy i rozpoczyna logowanie w razie potrzeby) |

Dystrybucja tylko CLI

Pakiet tylko CLI żyje w `packaging/deeptutor-cli`. W tym kodzie źródłowym zainstaluj go ze źródła: ```bash python -m pip install -e ./packaging/deeptutor-cli ``` Nie jest jeszcze opublikowany na PyPI, więc główna sekcja [Pierwsze kroki](#-pierwsze-kroki) zachowuje ścieżkę instalacji ze źródła.

## 🧩 Ekosystem — EduHub i społeczność umiejętności Umiejętności DeepTutor używają otwartego formatu **Agent-Skills** — folder z podręcznikiem `SKILL.md` (frontmatter YAML + Markdown) i opcjonalnymi plikami referencyjnymi. Nic w tym nie jest specyficzne dla DeepTutor, więc każdy rejestr który mówi w tym formacie staje się źródłem dla twojej biblioteki. DeepTutor jest dostarczany z **[EduHub](https://eduhub.deeptutor.info/)** — naszym własnym rejestrem umiejętności skupionym na edukacji — podłączonym jako domyślny hub.

EduHub — Ekosystem umiejętności DeepTutor

[**EduHub**](https://eduhub.deeptutor.info/) to hub społecznościowy który DeepTutor uruchomił do dzielenia się umiejętnościami agentów zorientowanymi na nauczanie — tutorzy sokratejscy, kreatory fiszek, informacje zwrotne na eseje, plany egzaminów, objaśniacze konceptów i więcej. Jest wbudowany w DeepTutor, więc nie ma nic do konfigurowania: gołe slug lub prefiks `eduhub:` rozwiązuje do niego. **Znajdź i zainstaluj** — w przeglądarce otwórz **Learning Space → Skills → Import from EduHub** aby przeglądać katalog i pobrać umiejętność bezpośrednio do swojej biblioteki. Z terminala: ```bash deeptutor skill search "socratic tutor" # wyszukaj EduHub (domyślny hub) deeptutor skill install socratic-tutor # pobierz → weryfikuj → zarejestruj deeptutor skill install eduhub:socratic-tutor@1.2.0 # przypnij hub i wersję deeptutor skill list # lokalne umiejętności z proweniencją hubu ``` **Opublikuj własną** — spakuj `SKILL.md` i podziel się ze społecznością: ```bash deeptutor skill login # logowanie przeglądarki do EduHub deeptutor skill publish ./my-skill # interaktywne: wybierz ścieżkę + tagi, następnie prześlij deeptutor skill update # wycofaj lub wydaj nową wersję ``` EduHub jest również samodzielnym, kompatybilnym z ClawHub rejestrem, więc agenty które nie są DeepTutorem (Claude Code, Codex, …) mogą używać go bezpośrednio przez CLI `eduhub` — `npx eduhub install socratic-tutor`.

Brama bezpieczeństwa importu

Niezależnie od źródła, każdy import przechodzi przez tę samą **bramę bezpieczeństwa** zanim cokolwiek dotknie twojego obszaru roboczego: - **werdykt bezpieczeństwa** rejestru jest sprawdzany jako pierwszy — oznaczone pakiety są odrzucane chyba że przekażesz `--allow-unverified`; - archiwa są rozpakowywane defensywnie z kontrolą przechodzenia poza ścieżkę, liczby wpisów, rozmiaru, współczynnika kompresji, sufiksów i dowiązań symbolicznych; bity wykonywalne są usuwane, a pliki bez rozszerzeń pozostają dozwolone; - frontmatter jest normalizowany do schematu DeepTutor a `always:` jest **usuwane**, więc pobrana umiejętność nigdy nie może wymusić się do każdego systemowego promptu; - proweniencja — hub, wersja, werdykt i czas instalacji — jest zapisywana do `.hub-lock.json` dla audytów i aktualizacji. We wdrożeniach wieloużytkownikowych importy z przeglądarki trafiają do warstwy umiejętności uwierzytelnionego użytkownika, natomiast instalacje z CLI i konsoli administratora są kierowane do obszaru roboczego właściciela/administratora; umiejętności administratora pozostają ukryte i tylko do odczytu dla zwykłych użytkowników do czasu przyznania uprawnień.

Kompatybilność z ClawHub

Ponieważ DeepTutor mówi otwartym formatem Agent-Skills, **[ClawHub](https://clawhub.ai/)** działa również jako pierwszorzędne źródło — jest wbudowany obok EduHub. Wybierz go z prefiksem hubu: ```bash deeptutor skill search "git release notes" --hub clawhub deeptutor skill install clawhub:git-release-notes@1.0.1 deeptutor skill install clawhub:udiedrichsen/stock-analysis ``` Gdy kilku wydawców dzieli ten sam slug, wyszukiwanie pokazuje każdego wydawcę i w pełni zakresowane odniesienie instalacyjne (`clawhub:/`). Dodaj więcej rejestrów w `data/user/settings/skill_hubs.json`: wpis `type: "clawhub"` wskazuje na dowolne kompatybilne HTTP API (EduHub i ClawHub oba je mówią), `type: "command"` opakowuje dowolny CLI pobierania który rejestr dostarcza i `"default"` wybiera hub używany dla gołych slugów. Wszystkie zasilają tę samą bramę importu.

## 🤝 Partnerzy Open Source

Użyj kodu: DEEPTUTOR20 — zdobądź $20 zniżki na pierwszą subskrypcję PageIndex!

## 🌐 Społeczność ### 🔗 Opiekunowie

Bingxi Zhao

Xingyu Hou

Jiahao Zhang

### 📮 Kontakt DeepTutor to projekt open-source prowadzony przez [Bingxi Zhao](https://github.com/pancacake) w ramach Grupy [HKUDS](https://github.com/HKUDS), i iteruje w **w pełni open-source formie**, budowany razem ze społecznością. Do tej pory **NIE** mamy żadnych płatnych produktów online jakiegokolwiek rodzaju. Zapraszamy do kontaktu pod adresem **bingxizhao39@gmail.com** w sprawie dyskusji, pomysłów lub współpracy. ### 🙏 Podziękowania Serdeczne podziękowania dla [**Chao Huang**](https://sites.google.com/view/chaoh), dyrektora Data Intelligence Lab @ HKU, i naszych współpracowników z HKUDS za ciepłe wsparcie — szczególnie [**Jiahao Zhang**](https://github.com/zzhtx258), [**Zirui Guo**](https://github.com/LarFii) i [**Xubin Ren**](https://github.com/Re-bin). Jesteśmy również głęboko wdzięczni **społeczności open-source**: wasze gwiazdki, zgłoszenia, pull requesty i dyskusje kształtują DeepTutor każdego dnia. DeepTutor stoi również na ramionach wybitnych projektów open-source które dostarczyły nam zarówno narzędzia jak i inspirację: | Projekt | Rola / Inspiracja | |:---|:---| | [**LlamaIndex**](https://github.com/run-llama/llama_index) | Kręgosłup potoku RAG i indeksowania dokumentów | | [**nanobot**](https://github.com/HKUDS/nanobot) | Ultralekki silnik agenta który zasilał oryginalny TutorBot *(HKUDS)* | | [**LightRAG**](https://github.com/HKUDS/LightRAG) | Prosty i szybki RAG *(HKUDS)* | | [**AutoAgent**](https://github.com/HKUDS/AutoAgent) | Framework agentów bez kodu *(HKUDS)* | | [**AI-Researcher**](https://github.com/HKUDS/AI-Researcher) | Zautomatyzowany potok badań naukowych *(HKUDS)* | | [**OpenClaw**](https://github.com/openclaw/openclaw) | Otwarta brama agentów i ekosystem umiejętności za ClawHub | | [**Codex**](https://github.com/openai/codex) | Natywny dla agentów CLI kodowania który zainspirował nasz przepływ pracy CLI | | [**Claude Code**](https://github.com/anthropics/claude-code) | Agentowy CLI kodowania który zainspirował pętlę agenta DeepTutor | | [**ManimCat**](https://github.com/Wing900/ManimCat) | Generowanie animacji matematycznych sterowane AI dla Math Animator | ### 🗺️ Plan działania i współtworzenie Chcemy aby DeepTutor stale iterował i się rozwijał — a ostatecznie stał się prezentem który oddajemy społeczności open-source. Nasz [**plan działania**](https://github.com/HKUDS/DeepTutor/issues/498) jest aktualizowany na bieżąco; głosuj na elementy tam lub proponuj nowe. Jeśli chcesz współtworzyć, zapoznaj się z [**Przewodnikiem dla współtwórców**](../../CONTRIBUTING.md) po strategię gałęzi, standardy kodowania i sposób rozpoczęcia.

Mamy nadzieję, że DeepTutor stanie się prezentem dla społeczności. 🎁

Licencjonowany na podstawie [Apache License 2.0](../../LICENSE).