README_RU.md

 

DeepTutor: Пожизненное Персонализированное Обучение

 

                     

Возможности · Начать · Исследовать · CLI · Экосистема · Сообщество

---

🤝 Мы приветствуем любые вклады в проект! Голосуйте за элементы дорожной карты или предлагайте новые на странице Roadmap, а также изучите наше Руководство по участию с описанием стратегии ветвления, стандартов кодирования и инструкций по началу работы.

📰 Новости

• 2026-09-20 🎉 40 тысяч звёзд за 9 месяцев! Мы продолжим расширять учебную экосистему DeepTutor.
• 2026-05-22 🌐 Официальный сайт документации запущен на deeptutor.info — руководства, справочники и туры по возможностям в одном месте.
• 2026-04-19 🎉 20 тысяч звёзд за 111 дней! Благодарим за поддержку на пути к по-настоящему персонализированному интеллектуальному обучению.
• 2026-04-10 📄 Наша статья опубликована на arXiv — прочитайте препринт о дизайне и идеях, лежащих в основе DeepTutor.
• 2026-02-06 🚀 10 тысяч звёзд всего за 39 дней! Огромная благодарность нашему удивительному сообществу.
• 2026-01-01 🎊 С Новым Годом! Присоединяйтесь к нашему Discord, WeChat или Обсуждениям — давайте вместе формировать DeepTutor.
• 2025-12-29 🎓 DeepTutor официально выпущен!

✨ Ключевые возможности

DeepTutor — это агентная учебная рабочая среда, объединяющая репетиторство, решение задач, генерацию викторин, исследования, визуализацию и практику освоения в одной расширяемой системе.

• Единая среда выполнения для всех режимов — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading и Audio Overview работают в единой среде выполнения и используют общий контекст сессии, но сохраняют специализированные циклы и конвейеры для своих задач.
• Task Board — отслеживайте учебные задачи в колонках «Сделать», «В работе» и «Готово»: добавляйте заметки, перемещайте карточки перетаскиванием или доступными с клавиатуры кнопками и восстанавливайте их из архива. Карточки остаются в текущем рабочем пространстве и используют действующие настройки оформления и языка; настройка модели не требуется.
• Связанный контекст обучения — базы знаний, книги, черновики Co-Writer, блокноты, банки вопросов, персоны и Memory можно повторно использовать в поддерживающих их рабочих процессах с учётом грантов учётной записи и политик обучения.
• Иммерсивное обучение по видео — добавляйте ссылки YouTube или Bilibili в Reading для нативного воспроизведения, поиска по транскрипту, репетиторства с привязкой ко временным меткам, сохранения заметок и возобновления прогресса; для субтитров YouTube и просмотра каталога можно использовать экземпляр Invidious, настроенный администратором.
• Субагенты и Partners — из Chat обращайтесь к живой агентной среде (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw или DeepSeek) или к Partner, импортируйте прошлые разговоры и запускайте постоянных IM-компаньонов на том же мозге.
• Многодвигательные знания — версионированные RAG-библиотеки на основе LlamaIndex, PageIndex, GraphRAG, LightRAG, удалённого LightRAG Server, самостоятельно размещённого WeKnora, библиотеки Tencent IMA или MarginNote 4, подключённого архива Kiwix ZIM либо связанного хранилища Obsidian, с подключаемым разбором документов. См. нативные ролевые модели LightRAG для независимых настроек извлечения, запросов и обработки изображений, создания только со значениями по умолчанию и подтверждённых пересборок.
• Расширяемые инструменты и навыки — встроенные инструменты, MCP-серверы, CLI-приложения, модели генерации изображений / видео / голоса и устанавливаемые навыки сообщества из EduHub.
• Проверяемая память — трассировки L1, сводки поверхностей L2 и синтез L3 делают персонализацию видимой и редактируемой; Memory Graph связывает факты L2 с доказательствами L1, а синтез L3 — с участвующими поверхностями.

---

🚀 Начало работы

Поручите настройку DeepTutor своему агенту

Скопируйте этот запрос в ИИ-агент с доступом к терминалу (например, Codex или Claude Code):

Help me install and configure DeepTutor locally from https://github.com/HKUDS/DeepTutor.
Clone the repository, or reuse my existing checkout, and read SKILL.md and
docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,
configure my model provider, verify the setup, and start the Web app.
Ask me for any missing provider, model, or credential-source information;
do not print API keys. Preserve my existing files and settings, and finish
with the access URL and the results of your checks.

Руководство по настройке с помощью агента описывает весь процесс, включая неинтерактивную настройку через CLI. Для самостоятельной установки выберите один из способов ниже.

DeepTutor поставляется с четырьмя путями установки. Все они используют одну структуру каталога среды выполнения: приватные настройки хранятся в data/user/settings/ в директории запуска (или в DEEPTUTOR_HOME / deeptutor start --home, если задано явно). Для полного приложения рекомендуемый процесс: выбрать каталог среды выполнения → установить → deeptutor init → deeptutor start.

Пробный запуск Docker одной командой

Если Docker ещё не установлен, сначала установите Docker. Затем попробуйте полное приложение без настройки Python или Node.js:

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Откройте http://127.0.0.1:3782, настройте провайдеров моделей в разделе Настройки → Провайдеры и нажмите Ctrl+C, когда закончите. Именованный том deeptutor-data сохраняет настройки и локальные данные для следующего запуска.

Рабочее пространство для контента

Рабочее пространство для контента отделено от приватного каталога среды выполнения DeepTutor. Это папка, которую могут читать агенты; созданные файлы находятся в outputs/<capability>/<session>/<turn>/. Пользовательские рабочие пространства изолируют разговоры, учебные материалы, прогресс и кэши в приватном дереве .deeptutor/data/, недоступном файловым инструментам. Настройки, учётные данные и Memory остаются общими на уровне аккаунта.

Без настройки Рабочее пространство для контента — это <runtime-home>/data/user/workspace. В локальных установках из PyPI, CLI и исходного кода папки выбираются в Настройки → Рабочие пространства; папку по умолчанию можно задать так:

deeptutor workspace show
deeptutor workspace set /absolute/path/to/my-folder
deeptutor workspace reset

Возможности просматривают выбранное рабочее пространство через встроенные инструменты рабочего пространства. Модель получает только относительные пути вроде outputs/...; когда она использует workspace_present, интерфейс отображает аутентифицированный, открываемый снимок. Тот же самый относительный путь работает и в обычной Markdown-ссылке или изображении. Последующее изменение исходного файла не меняет уже представленный снимок.

Пространство Обучения управляет библиотекой ресурсов. В Настройки → Рабочие пространства можно назначить каждому пространству навыки, MCP-сервисы и базы знаний или сохранить существующие правила доступа. Существующие пространства сохраняют текущий доступ, пока новый выбор не будет сохранён. Назначения ссылаются на исходные ресурсы без копирования учётных данных или индексов знаний; навыки конкретного пространства могут переопределять общие версии. См. назначение ресурсов рабочим пространствам.

Выполнение доступно только для чтения за пределами outputs/. Копирование созданного файла в другое место Рабочего пространства для контента требует явного подтверждения Разрешить один раз для конкретной пары источник/назначение. Системная песочница или Docker runner обеспечивают эту границу, когда доступны; локальный резервный вариант с ограниченным подпроцессом отображается в настройках рабочего пространства как выполняется по возможности (best effort).

Вариант 1 — Установка из PyPI · полное локальное веб-приложение + CLI, клонирование не требуется

Полное локальное веб-приложение + CLI без необходимости клонирования. Требуется Python 3.11–3.14 и среда выполнения Node.js 20+ в PATH (упакованный автономный сервер Next.js запускается командой deeptutor start).

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # prompts for ports + LLM provider + optional embedding/search
deeptutor start    # starts backend + frontend; keep the terminal open

deeptutor init запрашивает порт бэкенда (по умолчанию 8001), порт фронтенда (по умолчанию 3782), провайдер LLM / базовый URL / API-ключ / модель, необязательный провайдер встраивания для базы знаний / RAG и необязательный провайдер поиска для Web Search.

После deeptutor start откройте URL фронтенда, напечатанный в терминале — по умолчанию http://127.0.0.1:3782. Нажмите Ctrl+C в этом терминале, чтобы остановить бэкенд и фронтенд. Пропустить deeptutor init можно для быстрого пробного запуска; приложение загружается с портами по умолчанию и пустыми настройками модели, которые можно настроить позже в Настройки → Провайдеры и Языковые модели.

Транскрибирование с микрофона в браузере: адаптеры STT, совместимые с OpenAI, передают аудио из браузера провайдеру без локального преобразования. Нативные адаптеры STT DashScope и Volcengine преобразуют WebM/Opus из браузера в WAV с частотой 16 kHz; для этого исполняемый файл ffmpeg должен быть доступен в PATH DeepTutor. Канонический монофонический PCM WAV с частотой 16 kHz не требует такого преобразования. Для установки из PyPI в Windows при использовании любого из нативных адаптеров установите FFmpeg, добавьте его каталог bin в PATH сервиса и перезапустите DeepTutor. Ошибки преобразования отображаются под полем ввода чата.

Вариант 2 — Установка из исходного кода · разработка на основе чекаута

Для разработки на основе чекаута. Используйте Python 3.11–3.14 и Node.js 22 LTS для соответствия CI и Docker.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# Create a 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

# Install backend + frontend deps
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )

deeptutor init
deeptutor start --dev

deeptutor start один раз собирает продакшен-сборку локального фронтенда web/ и переиспользует её; --dev запускает Next.js с горячей заменой модулей (HMR). Структура конфигурации, порты и Ctrl+C соответствуют Варианту 1.

Среда Conda (вместо venv)

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

Необязательные дополнения при установке — движки RAG / dev / partners / matrix / math-animator

pip install -e ".[rag-lightrag]"    # Built-in LightRAG engine (exact supported SDK)
pip install -e ".[graphrag]"        # Microsoft GraphRAG engine (Python 3.11–3.13)
pip install -e ".[dev]"             # tests/lint tools
pip install -e ".[partners]"        # Partner IM channel SDKs
pip install -e ".[video-learning]"  # compatibility extra; captions ship in the full/CLI installs
pip install -e ".[matrix]"          # Matrix channel without E2EE/libolm
pip install -e ".[matrix-e2e]"      # Matrix E2EE; requires libolm
pip install -e ".[math-animator]"   # Manim addon; requires LaTeX/ffmpeg/system libs

Настройка зависимостей фронтенда и устранение неполадок сервера разработки

Изменение зависимостей фронтенда: запустите npm install --legacy-peer-deps для обновления web/package-lock.json, затем зафиксируйте оба файла web/package.json и web/package-lock.json.

Зависший сервер разработки: если deeptutor start --dev сообщает о существующем фронтенде, который не отвечает, остановите PID, который он печатает. Если процесс Next.js фактически не запущен, файлы блокировки устарели — удалите их и повторите попытку:

rm -f web/.next/dev/lock web/.next/lock
deeptutor start --dev

Вариант 3 — Docker · один автономный контейнер

Один контейнер для полного веб-приложения. Образы в GitHub Container Registry:

• ghcr.io/hkuds/deeptutor:latest — последний стабильный выпуск
• ghcr.io/hkuds/deeptutor:<version> — точный выпуск без начальной v (например, :1.6.3); предварительные выпуски получают только собственный тег версии

Смотрите CONTAINERIZATION.md для развёртываний на podman/rootless/read-only-rootfs и полного руководства по установке.

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Чтобы выбрать папку содержимого хоста при запуске контейнера, смонтируйте её по стабильному пути внутри контейнера и закрепите DeepTutor на этом пути:

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

Для Compose задайте DEEPTUTOR_WORKSPACE_HOST=/absolute/host/folder перед запуском python scripts/docker_compose.py up -d. Если не указано, используется ./data/user/workspace. Пути Docker выбираются при запуске, поэтому на странице веб-настроек они отображаются как заблокированные.

Публиковать нужно только порт 3782. Браузер обращается исключительно к источнику фронтенда; промежуточный слой Next.js (web/proxy.ts) перенаправляет /api/* и /ws/* на бэкенд FastAPI внутри контейнера. Публикация 8001 (-p 127.0.0.1:8001:8001) необязательна — полезна только при прямом обращении к API через curl или скрипты.

Откройте http://127.0.0.1:3782. Контейнер создаёт /app/data/user/settings/*.json при первом запуске; настройте провайдеров моделей на странице веб-настроек. Конфигурация, API-ключи, логи, Рабочее пространство для контента по умолчанию, память и базы знаний сохраняются в томе deeptutor-data. Отдельно смонтированное Рабочее пространство для контента вместо этого сохраняется по своему пути на хосте. Необязательные дополнения принадлежат развёртыванию, а не оболочке: задайте DEEPTUTOR_EXTRAS (и DEEPTUTOR_APT_PACKAGES для системных библиотек), и каждый контейнер, запущенный из него, будет повторно применять их, тогда как docker exec … pip install будет потерян при следующем compose down.

• Другие порты хоста: измените левую часть каждого маппинга -p host:container (например, -p 127.0.0.1:8088:3782). Если вы измените порты на стороне контейнера в /app/data/user/settings/system.json, перезапустите и обновите правую часть каждого маппинга.
• Фоновый режим: добавьте -d, затем docker logs -f deeptutor для слежения, docker stop deeptutor для остановки, docker rm deeptutor перед повторным использованием имени. Том deeptutor-data сохраняет приватные данные среды выполнения и Рабочее пространство для контента по умолчанию между перезапусками; отдельно смонтированное Рабочее пространство для контента сохраняется по своему пути на хосте.

Удалённый Docker / обратный прокси: браузер обращается только к источнику фронтенда (:3782); промежуточный слой Next.js внутри контейнера перенаправляет /api/* и /ws/* на бэкенд на стороне сервера. В типичном случае с одним контейнером вы вообще не настраиваете базовый URL API — просто направьте ваш обратный прокси / TLS-терминатор на :3782. Базовый URL API нужен только для разделённого развёртывания (бэкенд в отдельном контейнере/хосте): установите next_public_api_base в data/user/settings/system.json на внутрисетевой адрес, который фронтенд-сервер использует для достижения бэкенда (он читается на стороне сервера, никогда не отправляется браузеру).

{
  "next_public_api_base": "http://backend:8001"
}

next_public_api_base_external (и его псевдоним public_api_base) принимаются как запасные варианты с более низким приоритетом. CORS использует источники фронтенда, а не URL API. При отключённой аутентификации DeepTutor разрешает обычные HTTP/HTTPS источники браузера по умолчанию. При включённой аутентификации добавьте точные источники фронтенда:

{
  "cors_origins": ["https://deeptutor.example.com"]
}

Подключение к Ollama / LM Studio / llama.cpp / vLLM / Lemonade на хосте

Внутри Docker localhost — это сам контейнер, а не хост-машина. Чтобы обратиться к модельному сервису, запущенному на хосте, используйте шлюз хоста (рекомендуется):

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

Затем в Настройки → Провайдеры укажите базовый URL провайдера как 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) обычно разрешает host.docker.internal без --add-host. На Linux этот флаг — переносимый способ создания этого имени хоста в современном Docker Engine.

Альтернатива для Linux — сетевой режим хоста: добавьте --network=host и уберите флаги -p. Контейнер напрямую использует сеть хоста, поэтому откройте http://127.0.0.1:3782 (или frontend_port в system.json), а сервисы хоста доступны через обычные localhost-URL, например http://127.0.0.1:11434/v1. Обратите внимание, что хостовый сетевой режим открывает порты контейнера напрямую на хосте и может конфликтовать с существующими сервисами — чтобы оставить их на loopback, установите BACKEND_HOST=127.0.0.1 и FRONTEND_HOST=127.0.0.1 (см. CONTAINERIZATION.md).

Вариант 4 — Только CLI · без веб-интерфейса, из чекаута исходного кода

Когда веб-интерфейс не нужен. Пакет только для CLI устанавливается из чекаута исходного кода, а не из PyPI.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# Create a 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 использует ту же структуру data/user/settings/, что и полное приложение, но пропускает запросы портов бэкенда/фронтенда. Он по-прежнему предлагает селекторы Embedding и Search (выберите Skip, если они не нужны), записывает основные файлы среды выполнения (system.json, auth.json, integrations.json, interface.json, model_catalog.json, main.yaml, agents.yaml) и запрашивает активный провайдер и модель LLM.

Основные команды

deeptutor chat                                          # interactive 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

Локальная установка deeptutor-cli не включает веб-ресурсы или серверные зависимости. Сохраните чекаут исходного кода — редактируемая установка указывает на него. Чтобы позже добавить веб-приложение, установите пакет PyPI (Вариант 1) и запустите deeptutor init + deeptutor start из того же рабочего пространства.

Песочница выполнения кода (офисные навыки) · запуск сгенерированного моделью кода для docx / pdf / pptx / xlsx

Встроенные офисные навыки — docx / pdf / pptx / xlsx — работают, заставляя модель написать короткий Python-скрипт (python-docx, reportlab, openpyxl, …), запустить его через единый инструмент exec и представить сохранённый файл рабочего пространства. Эти инструменты монтируются, когда активен любой бэкенд песочницы. DeepTutor выбирает наиболее надёжный настроенный бэкенд в следующем порядке:

• Runner sidecar: DEEPTUTOR_SANDBOX_RUNNER_URL направляет выполнение в защищённый сервис с минимальными привилегиями из Dockerfile.runner.
• Linux bubblewrap: если доступен bwrap, он изолирует процесс и файлы.
• Резервный ограниченный подпроцесс: локальные и одноконтейнерные установки используют его только при наличии разрешения; в Docker контейнер остаётся дополнительной границей.

Настройка sandbox_allow_subprocess в data/user/settings/system.json (по умолчанию true) управляет только последним резервным вариантом. Установите её в false (или экспортируйте DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0), чтобы запретить выполнение через подпроцесс при отсутствии бэкенда runner или bwrap; более надёжные бэкенды при этом не отключаются.

Справочник конфигурации — файлы конфигурации в data/user/settings/ (JSON/YAML)

Всё в data/user/settings/ — это обычный JSON/YAML. Для редактирования рекомендуется страница Настройки; регистрационные данные рабочих пространств хранятся отдельно в data/user/.runtime/workspaces.sqlite3.

Файл	Назначение
model_catalog.json	Подключения провайдеров, а также профили LLM, задач, встраивания, поиска, TTS, STT, изображений и видео, учётные данные и активные варианты выбора
system.json	Порты бэкенда/фронтенда, публичный базовый URL API, CORS, верификация SSL, директория вложений и лимиты загрузки/извлечения
auth.json	Необязательное переключение аутентификации, имя пользователя, хэш пароля, настройки токенов/куки
integrations.json	Необязательные настройки интеграции PocketBase и сайдкара
interface.json	Язык интерфейса и вывода модели / тема / настройки боковой панели
document_parsing.json	Выбор движка разбора и модели описания изображений, удалённые конечные точки и параметры конкретного движка
video_learning.json	Провайдер субтитров YouTube, источники Invidious и доступ к учётной записи, настройки транскриптов
main.yaml	Значения по умолчанию для среды выполнения и внедрение пути
agents.yaml	Настройки температуры и токенов для возможностей/инструментов

Ссылки Web Search по умолчанию фильтруются: отображаются только публичные URL http/https без встроенных учётных данных и необычных портов. В развёртываниях можно добавить политику доменов с упором на образование в data/user/settings/system.json:

{
  "web_search_source_filtering": {
    "enabled": true,
    "blocked_domains": ["spam.example"],
    "trusted_domains": ["edu.cn", "arxiv.org"]
  }
}

Если trusted_domains не пуст, ссылки ограничиваются этими доменами и их поддоменами; blocked_domains всегда имеет приоритет.

Корневой файл .env проекта не читается как файл конфигурации приложения. Для минимальной настройки модели сохраните базовый URL и API-ключ в разделе Настройки → Провайдеры, затем добавьте и выберите LLM в разделе Языковые модели. Добавляйте профиль встраивания только если планируете использовать функции базы знаний / RAG.

Для API Route выберите API Route в разделе Настройки → Провайдеры и введите ключ API Route. Предустановленная конфигурация использует https://global.api-route.com/v1; затем добавьте модель с её идентификатором API Route в разделе Языковые модели. Инструкции по настройке ключа и модели приведены в кратком руководстве API Route.

Профили LLM и моделей задач предоставляют настройку формата API, если их провайдер поддерживает выбор. Оставьте Auto для обычной маршрутизации и резервного варианта или выберите OpenAI Chat Completions, OpenAI Responses либо Anthropic Messages; принудительный режим Responses по-прежнему работает с отказом по умолчанию. Сохраняемое поле — api_format (auto, openai_chat, openai_responses или anthropic); wire_api — производное состояние совместимости. Переопределения Auto / Supported / Not supported для каждой модели охватывают вызов инструментов, ввод изображений, вывод JSON и элементы управления рассуждением.

Удаление и очистка

DeepTutor отделяет установленный код, приватное рабочее пространство среды выполнения и необязательное Рабочее пространство для контента. По умолчанию рабочим пространством среды выполнения служит директория, в которой вы запускаете deeptutor init / deeptutor start; --home PATH или DEEPTUTOR_HOME переопределяет её. Приватное состояние приложения — это директория data внутри этого рабочего пространства, поэтому строка баннера запуска, начинающаяся с Workspace:, указывает это расположение среды выполнения. Если Настройки → Рабочее пространство указывают на другую папку, создайте резервную копию или удалите эту папку с контентом отдельно; она намеренно не стирается при удалении DeepTutor.

1. Остановите приложение. Нажмите Ctrl+C в терминале, где выполняется deeptutor start, или запустите deeptutor stop [--home PATH] для лаунчера, запущенного с --detach; перед удалением данных остановите все работающие Partners и отсоединённые контейнеры Docker.

2. Удаляйте данные среды выполнения только в том случае, если хотите стереть всё локальное состояние. Сюда входят настройки и API-ключи, история чата, сессии, Memory, Notebooks, Books, состояние Reading, Skills, состояние Partners, журналы, Knowledge Bases, кэши разбора, созданные артефакты и кэш среды выполнения упакованного фронтенда.

   Сначала скопируйте точный путь Workspace: из баннера запуска и убедитесь, что его дочерняя директория data — это нужная директория данных DeepTutor. Если что-либо может понадобиться позже, создайте резервную копию, а затем переместите именно эту директорию в Корзину операционной системы. Не выполняйте команду рекурсивного удаления для относительного пути или неразрешённой переменной окружения.

3. Удалите установленный пакет. Используйте команду, соответствующую дистрибутиву:

   python -m pip uninstall deeptutor
   python -m pip uninstall deeptutor-cli

   Если виртуальная среда была создана только для DeepTutor, удалите её через менеджер сред. Для установки из исходного кода деактивируйте среду, выйдите из директории исходного кода и выполните git status --short внутри именно этого чекаута. Перемещайте чекаут в Корзину только после того, как убедитесь, что в нём нет посторонних или незакоммиченных изменений.

4. При использовании Docker перед удалением проверьте точный контейнер и именованный том. Удаление тома навсегда стирает данные, управляемые Docker:

   docker ps -a --filter name=^/deeptutor$
   docker volume inspect deeptutor-data
   docker rm -f deeptutor
   docker volume rm deeptutor-data

📖 Обзор DeepTutor

Начните с основных поверхностей, которые вы будете использовать ежедневно: Chat, Partners, My Agents, Co-Writer, Book, Knowledge Center, Learning Space, Memory и Settings. Затем тур охватывает многопользовательские развёртывания для общих изолированных рабочих пространств.

Если ответ теряет ранее заданное ограничение, ссылается на слабые доказательства или противоречит выбранному материалу, соберите диагностические данные по REASONING_SAFETY_CHECKLIST.md, прежде чем открывать issue.

Состояние скриншотов: общий обзор обновлен для v1.6.5. Скриншоты поверхностей ниже остаются справочными изображениями v1.4.6 до завершения обновления. Используйте их для понимания рабочих процессов, а не как точную текущую навигацию.

🏗️ Архитектура системы

💬 Чат — Цикл Агента, Который Вы Используете на Практике

Чат — это возможность по умолчанию и место, где начинается большинство работ. Один поток может нормально общаться, вызывать инструменты, опираться на выбранные базы знаний, читать вложения, генерировать изображения, обращаться к субагентам, записывать в блокнот и продолжать с тем же контекстом в последующих ходах.

Цикл намеренно прост: модель думает раундами, вызывает инструменты при необходимости, наблюдает результаты и завершает сообщением без инструментов. ask_user особенный — вместо угадывания агент может приостановить ход, задать структурированный уточняющий вопрос и возобновить работу, когда вы ответите.

Переключаемые пользователем инструменты: brainstorm, web_search, paper_search, zotero_search, reason и geogebra_analysis — плюс imagegen и videogen после настройки соответствующей генеративной модели. Контекстные инструменты, такие как 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 и workspace_export, монтируются автоматически, когда ход имеет подходящий контекст.

Контекст бывает двух видов: постоянный контекст сессии (возможность, рабочее пространство или курс, инструменты, базы знаний, персонаж, модель и состояние Reading / Mastery) сохраняется между ходами; одноразовые ссылки (файлы, история чата, книги, разделы чтения, блокноты, выбранные записи банка вопросов, импортированные агенты) берутся из меню + для одного хода. Кнопка голосового ввода только транскрибирует текущее сообщение.

На главной странице Chat, Ask Questions, Quiz и Visualize доступны в один клик; Research для цитируемых отчётов и Solve для пошаговых рассуждений находятся в разделе Дополнительные возможности. Персонализированное обучение объединяет Book, Mastery Path, Immersive Reading и Практику; Reading объединяет документы, видео и аудио с проверенными цитатами, сохранёнными заметками, естественным чтением вслух отрывков из источников / сопровождением обучения / работой со словарём / викторинами / переводом и сохранением в блокнот, а Course Study сохраняет контекст, привязанный к курсу.

🤝 Partner — Постоянные Компаньоны на Том Же Мозге

Партнёры — это постоянные компаньоны со своей душой, политикой модели, библиотекой, памятью и каналами. Они не являются отдельным движком бота: каждое входящее веб- или IM-сообщение становится обычным ходом ChatOrchestrator внутри рабочего пространства, ограниченного партнёром. Партнёр — это «чат с личностью и номером телефона».

Каждый партнёр имеет SOUL.md, выбор модели, каналы, политику инструментов и назначенную библиотеку. Его библиотека либо копирует базы знаний, навыки и блокноты в data/partners/<id>/workspace/, либо остаётся связанной с файлами и ресурсами существующего рабочего пространства; душа, разговоры и память Partner остаются отдельными. Аутентифицированные пользователи без прав администратора сохраняют приватные сессии Partner и память отношений, а Partner читает их личную память только для чтения; трафик администраторов, групп и непривязанных пользователей использует общую область Partner.

Слой каналов управляется схемой и может подключаться к IM-платформам, таким как Feishu, Telegram, Slack, Discord, DingTalk, QQ/NapCat, WeCom, WhatsApp, Zulip, Mattermost, Matrix, Mochat и Microsoft Teams, в зависимости от установленных дополнений и настроенных учётных данных. Партнёр также может быть подключён как субагент и использован из обычного хода чата — см. Мои Агенты ниже.

Для более быстрой настройки страница канала Партнёра может создать приложение Feishu/Lark или AI-бота WeCom, либо войти с личной учётной записью WeChat — по QR-коду, отображаемому в браузере, а не в логе сервера. Feishu/Lark определяет домен учётной записи и сохраняет пользователя, выполнившего сканирование, как первого разрешённого отправителя. WeCom сохраняет существующий белый список, а иначе по умолчанию разрешает доступ всем пользователям, которые могут связаться с ботом, с заметным предупреждением об открытом доступе; ручные формы канала остаются доступны, если протокол сканирования провайдера изменится.

🧑‍🚀 Мои Агенты — Консультация и Импорт Других Агентов

Мои Агенты превращают других агентов в контекст для DeepTutor и делают две разные вещи. Подключите живого агента — Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo Code, Hermes Agent, OpenClaw или DeepSeek Harness на вашей машине, удалённый шлюз Hermes либо одного из ваших Партнёров — и обращайтесь к нему изнутри хода чата: DeepTutor фактически запускает другого агента и транслирует его работу в панель Activity через инструмент consult_subagent. Выберите его и лимит раундов с помощью чипа Agent или отфильтруйте тот же список подключённых агентов через @; выбор остаётся привязанным к сессии.

Подключите Grok CLI. Установите Grok CLI от xAI на машине, на которой запущен бэкенд DeepTutor, выполните там grok login и убедитесь, что grok --help выводит --output-format streaming-json. Затем откройте Мои Агенты → Подключить, выберите Grok CLI и укажите рабочую директорию. Обнаружение проверяет поддержку протокола исполняемым файлом; оно не проверяет вход в систему или доступ к модели. Коннектор проверен с Grok CLI 1.0.3; не связанные с ним сторонние команды, также называющиеся grok, не поддерживаются.

В разделе Настройки → Партнёры и агенты → Grok CLI оставьте модель и уровень усилий рассуждения пустыми, чтобы использовать значения CLI по умолчанию, либо укажите значения, поддерживаемые выводом grok models вашей учётной записи. Системные инструкции передаются через --rules. Режим разрешений по умолчанию — dontAsk: Grok использует собственные правила и встроенную обработку операций только для чтения, а операции, требующие подтверждения, отклоняются. Это политика разрешений CLI, а не файловая песочница. Более широкие режимы можно выбрать явно в настройках; дополнительные флаги CLI остаются доступны через backends.grok.extra_args в API настроек субагентов.

Grok использует собственную аутентификацию и хранение сессий; DeepTutor не копирует его учётные данные. Последующие консультации возобновляют сессию соединения в той же рабочей директории. Текст и активность инструментов транслируются в реальном времени; приватные данные размышлений не передаются. Память Grok между сессиями отключена по умолчанию. Этот коннектор поддерживает текстовые вопросы и инструменты CLI, но не передачу изображений и не импорт прошлых разговоров Grok. В Docker установите и авторизуйте Grok внутри контейнера бэкенда; CLI, установленный только на компьютере браузера, недоступен.

Импортируйте прошлые разговоры — загрузите существующую историю ChatGPT, Claude Code и Codex как доступные для поиска, возобновляемые разговоры. Выберите conversations.json из официального экспорта данных ChatGPT для безопасного, идемпотентного импорта снимка, выбирайте историю Claude по проекту / рабочей директории или историю Codex по календарной дате. Агенты на основе папок остаются обновляемыми, поэтому их выбранная область может подхватывать новые разговоры. Ссылайтесь на один из них из хода Chat через + → Мои Агенты, и DeepTutor читает его как транскрипт третьей стороны — это их разговор, а не собственный голос DeepTutor.

✍️ Co-Writer — Редактирование Markdown с Учётом Выделения

Co-Writer — это разделённое рабочее пространство Markdown для отчётов, руководств, заметок и долгосрочных учебных артефактов. Документы автосохраняются и отображают живой предварительный просмотр (математика KaTeX, ограждения диаграмм), и могут быть сохранены обратно в блокноты, когда черновик становится повторно используемым контекстом. Импортируйте .docx, чтобы начать черновик, и экспортируйте текущий редактор как Markdown или Word.

Его определяющая идея — хирургическое редактирование: выберите фрагмент и попросите DeepTutor переписать, расширить или сократить его. Выберите модель редактирования; она может использовать базу знаний или веб-данные и ведёт журнал вызовов инструментов. Если черновик не изменился за время его работы, результат напрямую заменяет выделенный текст и остаётся обратимым с помощью Undo.

📖 Книга — Живые Книги из Ваших Материалов

Книга превращает выбранные источники в интерактивную живую книгу — не статический PDF, а среда чтения, построенная из типизированных блоков. Книга может начинаться с баз знаний, блокнотов, банков вопросов или истории чата; процесс создания предлагает план глав перед генерацией содержания, поэтому вы рассматриваете структуру вместо того, чтобы принимать слепой одноразовый вывод.

   

Каждая глава компилируется в редактируемые типизированные блоки — текст, выноски, викторины, флэш-карточки, временные шкалы, код, рисунки, интерактивный HTML, анимации, концептуальные графы, углублённые рассуждения и пользовательские заметки — и имеет собственный Page Chat. Вставляйте, перемещайте, регенерируйте и переписывайте блоки или меняйте их тип; выделенные фрагменты попадают в раздел входящих учебных выдержек, где их можно проверить. Прогресс, закладки, попытки прохождения викторин, учебные выдержки и Page Chat остаются личными для каждого читателя, даже если администратор поделился книгой в режиме только для чтения или совместного редактирования; удалять общие книги по-прежнему может только администратор. Любую книгу можно экспортировать в Markdown, длительную компиляцию можно приостанавливать и возобновлять, а deeptutor book health / refresh-fingerprints отмечают расхождения с источниками.

📚 Центр Знаний — Многодвигательные RAG-Библиотеки

Базы знаний — это коллекции документов для RAG, которые обосновывают ходы Chat, редакции Co-Writer, генерацию Book и разговоры с Партнёрами. Отличительной чертой является выбор движков поиска: LlamaIndex (по умолчанию, гибридный векторный поиск + BM25 с необязательным переранжированием cross-encoder и индексами FAISS exact-flat или HNSW), PageIndex (поиск с рассуждением с цитатами на уровне страницы, размещённый или самостоятельно развёрнутый (OSS)), GraphRAG и LightRAG (поиск на основе графа знаний), LightRAG Server (поиск, делегированный внешнему экземпляру LightRAG, подключаемому по HTTP), WeKnora (поиск в базе знаний вашего самостоятельно размещённого развёртывания без локального индекса или копии документов), Tencent IMA (библиотека, которую вы курируете в IMA — доступная для поиска, просмотра и записи через её OpenAPI), MarginNote 4 (ваши учебные данные MN4 — документы, выдержки, карточки интеллект-карт и связи между ними — передаются дополнением (Add-on) приложения и используются с помощью специальных инструментов навигации), Kiwix (доступный для поиска ZIM-архив, предоставляемый по HTTP без локального индексирования), или связанное хранилище Obsidian, которое репетитор читает и записывает на месте. Каждая KB привязана к одному движку.

Переносите существующую библиотеку Obsidian, Hermes или Markdown? В руководстве по миграции знаний описаны варианты с подключённым хранилищем и индексированной копией.

При создании KB можно создать новую (загрузить и проиндексировать документы), связать существующую (повторно использовать индекс на месте) или подключить Kiwix (искать в одном предоставляемом сервером ZIM-архиве по мере необходимости). При создании выберите рабочее пространство для хранения KB; существующую KB можно перенести между рабочими пространствами после предварительного просмотра, сохранив назначения и сохранённые ссылки. База знаний также может отслеживать репозитории GitHub (репозиторий, ветка и glob-шаблон) или URL сайтов документации (с ограничениями глубины обхода и числа страниц, по умолчанию повторно синхронизируются каждые 24 часа); синхронизация сравнивает хеши содержимого, чтобы выявить добавленные, изменённые и удалённые материалы, поэтому документация, за которой вы следите, остаётся актуальной без повторной загрузки, а связанные папки подхватывают новые или изменённые локальные файлы при синхронизации. Переиндексирование записывает новую плоскую директорию version-N и сохраняет предыдущие, поэтому рабочий индекс никогда не уничтожается в процессе перестройки. Отдельный документ можно удалить даже из базы в состоянии error — убрав файл, который не удалось разобрать, без полного удаления и пересборки. Движок разбора документов — только текст, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM или LiteParse — и необязательная модель описания изображений выбираются в Настройки → Знания и документы, с отключёнными по умолчанию загрузками локальных моделей. Docling может также работать в удалённом режиме, обращаясь к серверу Docling Serve (без локальной установки и моделей), который настраивается на той же странице (mode=remote, базовый URL сервера и необязательный API-ключ) или через переменные окружения DOCLING_MODE / DOCLING_API_BASE_URL / DOCLING_API_TOKEN. Tika работает только в удалённом режиме и указывает на сервер Apache Tika, настроенный на этой странице. CLI отражает жизненный цикл через list/info/create/connect-kiwix/add/search/eval/set-default/delete, команды добавления/удаления источников, list-sources и sync.

Встроенный движок LightRAG устанавливается командой pip install 'deeptutor[rag-lightrag]'. Это дополнение содержит поддерживаемый SDK LightRAG, но не устанавливает MinerU. Выбирайте MinerU отдельно в разделе Разбор документов и либо настройте его облачный режим, либо установите актуальный локальный CLI, если нужен структурированный разбор. MinerU принимает PDF, распространённые растровые изображения, DOCX, PPTX и XLSX; устаревшая команда magic-pdf по-прежнему работает только с PDF. Текстовый и другие движки разбора не требуют MinerU.

Нативные запросы LightRAG и инкрементальное индексирование требуют конфигурации встраивания, зафиксированной опубликованным индексом, включая модель, размерность и идентичность конечной точки. Если она меняется, восстановите исходную конфигурацию или пересоберите индекс с текущим встраиванием; индексы без зафиксированной идентичности встраивания требуют пересборки. Раздел сведений о базе знаний и представления версий индекса показывают рекомендации по восстановлению, а файлы остаются доступными для просмотра и скачивания.

Оценка базы знаний. Когда доступны несколько движков, вопрос «какой из них лучше ищет в этих материалах?» требует практической проверки — для этого есть deeptutor kb eval. Подготовьте набор вопросов и ответов (по одному объекту JSON на строку: query и отрывки gold, которые должен возвращать идеальный поиск), затем оцените KB командой deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]. Поиск для каждого примера выполняется тем же способом, что и в ходе чата; ранжированные цитаты сопоставляются с эталонными отрывками по точному тексту или лексическому пересечению (пороги настраиваются через --min-ratio; семантическая эквивалентность не оценивается), а результат содержит Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k. Метрики — чистые функции от ранжирования, поэтому никакая модель не оценивает результат: оценки воспроизводимы и пригодны для сравнения, а сохранённый базовый результат превращает набор в проверку регрессий при смене модели встраивания, изменении переранжирования или экспериментах с размером фрагментов. Примеры, в которых поиск завершился ошибкой (отсутствующий индекс, неверные учётные данные), не получают оценки и указываются отдельно, не снижая средние значения. PageIndex использует рассуждение для поиска и не возвращает ранжированные фрагменты, поэтому исключён.

{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}

🌐 Пространство Обучения — Навыки, Персоны и Многоразовый Контекст

Пространство Обучения — это уровень библиотеки, организации и персонализации. Разговоры и материалы содержат Chat History, блокноты с перемещаемыми записями и экспортом в Markdown, а также банк вопросов с ответами и объяснениями. Запускайте Практику из выбранных вопросов банка вопросов или из Персонализированного обучения для сеансов повторения, отслеживания ошибок и повторения по расписанию. Персонализация содержит персонажей, навыки (сценарии SKILL.md), устанавливаемые одним кликом MCP-сервисы и CLI-приложения из каталога CLI-Anything, причём руководство по использованию каждого приложения загружается по требованию. Отдельное рабочее пространство My Courses группирует разговоры по предметам и ветки репетиторов; каждый ресурс предлагается только в поддерживающих его рабочих процессах.

Вам не нужно писать каждый навык самостоятельно — Импорт из EduHub просматривает каталог сообщества и загружает навык прямо в вашу библиотеку через шлюз безопасности (см. Экосистема).

🧠 Память — Проверяемая Персонализация

Память — это трёхуровневая система на основе файлов, которую можно читать, курировать и проверять — намеренно не скрытое векторное хранилище. L1 — зеркало рабочего пространства плюс трассировка событий только для добавления (trace/<surface>/<date>.jsonl); L2 — курированные факты на уровне поверхности (L2/<surface>.md) со ссылками на сущности L1; L3 — межповерхностный синтез (L3/<profile|recent|scope|preferences>.md), фиксирующий участвующие поверхности L2.

Граф памяти показывает всю пирамиду — синтез L3 в центре, L2 в среднем кольце, трассировки L1 снаружи — с точными рёбрами доказательств L2 → L1 и связями L3 → участвующие поверхности. Память отслеживается по поверхностям chat, notebook, quiz, kb, book, partner и cowriter; бюджеты обновления / аудита / дедупликации консолидатора настраиваются в Настройки → Память.

⚙️ Настройки — Единая Панель Управления

Настройки — это операционная панель управления, которая открывается страницей Общие для выбора языка интерфейса и вывода модели. Навигатор с поиском ведёт на независимые страницы: Личное включает рабочие пространства, миграцию данных, внешний вид и статистику использования; Обучение и разговоры — стартовые подсказки, вложения, Video Learning, управление учащимися и опекунами, Прогресс обучения и Memory; Модели и сервисы — провайдеров, языковые модели, Task-модели, встраивание, поиск, речь и мультимодальную генерацию; Возможности и интеграции — инструменты, параметры возможностей, партнёров и агентов, знания и документы. Система включает сеть, состояние среды выполнения и сведения о проекте; Архивные чаты позволяют искать, восстанавливать или навсегда удалять архивные разговоры. Состояние среды выполнения показывает состояние бэкенда, резидентную память и матрицу Готовности, оценивающую блокирующие проблемы, предупреждения и рекомендации для возможностей. Рабочие пространства разделяют файлы тем и состояние обучения, а миграция данных обеспечивает проверяемый перенос и экспорт. Провайдер хранит адрес и учётные данные поставщика для повторного использования его сервисными моделями; на страницах моделей выбираются сохранённые провайдеры и задаются имена и возможности моделей. Task-модели закрепляют небольшую быструю модель за фоновой работой — названием разговоров и написанием стартовых подсказок — и при пустом значении используют активную модель по умолчанию. Речь объединяет синтез и распознавание речи; мультимодальная генерация объединяет модели изображений и видео. В разделе Партнёры и агенты настраиваются локальные агентные среды и удалённый шлюз Hermes.

Синтез речи Xiaomi MiMo. Добавьте провайдера Xiaomi MiMo с адресом https://api.xiaomimimo.com/v1 и его API-ключом, затем добавьте mimo-v2.5-tts в разделе Настройки → Речь. Выберите предустановленный голос, например mimo_default, 冰糖 или 苏打, формат вывода wav или pcm16 и прослушайте образец перед применением. Голосовые инструкции управляют стилем и скоростью речи. Этот адаптер поддерживает только предустановленные голоса; создание и клонирование голоса требуют отдельных моделей и не поддерживаются. Если старая речевая модель MiMo была настроена через общий адаптер, совместимый с OpenAI, создайте её речевой профиль заново с провайдером Xiaomi MiMo, чтобы использовать протокол chat-completions. См. официальное руководство по синтезу речи MiMo.

Синтез речи MiniMax — в разделе Настройки → Речь выберите MiniMax для преобразования текста в речь и модель speech-2.8-hd. Настройте API-ключ MiniMax и явно выберите системный голос или введите идентификатор пользовательского голоса. Базовый URL API по умолчанию — https://api.minimax.io/v1; для региона Китай используйте https://api.minimaxi.com/v1. Чтение вслух и прослушивание образцов используют нативную конечную точку синтеза речи с выводом в MP3, WAV, FLAC или PCM и настройками частоты дискретизации, скорости и языка. Идентификаторы голосов и доступность для учётных записей описаны в API синтеза речи MiniMax.

Video Learning в разделе Настройки → Обучение и разговоры настраивает субтитры YouTube и доступ к Invidious для Reading. Чтобы использовать Invidious, задайте управляемый администратором адрес его серверного API (например, http://127.0.0.1:3000) и публичный адрес, доступный из браузера, проверьте подключение, выберите Invidious и сохраните настройки. Кнопка Просмотр Invidious в диалоге добавления материалов Reading позволяет искать видео и открывать подключённые подписки и плейлисты. YouTube воспроизводится через официальный плеер с повышенной конфиденциальностью; отсутствие субтитров явно отображается и ограничивает доказательную базу репетитора, но не мешает нативному воспроизведению. Установите .[video-learning] для загрузчика субтитров YouTube по умолчанию. Существующие ссылки Watching переносятся в Reading с сохранением истории разговоров, совместимых транскриптов, заметок и прогресса; новые заметки с временными метками становятся аннотациями Reading. Bilibili использует собственный способ воспроизведения и получения субтитров.

Большинство разделов используют поток черновика и применения, поэтому вы можете протестировать провайдера перед подтверждением. Вы также можете просто попросить об этом в Chat: ассистент читает текущую конфигурацию, применяет изменение и сообщает, требуется ли перезапуск или переиндексация — предварительно проверяя новую модель перед её применением, поэтому он не может переключить себя на что-то недостижимое. API-ключи никогда не проходят через модель — вместо этого она открывает для вас соответствующую форму. В комплект входят четыре темы — Default, Cream, Dark и Glass. Корневые файлы .env проекта намеренно игнорируются; конфигурация среды выполнения хранится в data/user/settings/*.json, если только DEEPTUTOR_HOME или deeptutor start --home не указывает приложению другое место.

OpenAI Codex OAuth (экспериментально). Добавление OpenAI Codex в разделе Настройки → Провайдеры открывает вход через браузер с использованием вашего собственного плана ChatGPT, поэтому OPENAI_API_KEY не требуется. Токены хранятся только в data/system/user-secrets/<owner>/private/openai-codex/ — в многоконтейнерном развёртывании Compose это за пределами любого дерева, доступного песочнице выполнения, — и DeepTutor никогда не читает и не изменяет вашу CLI-авторизацию ~/.codex. Список моделей формируется из актуального каталога этой учётной записи; вход публикует профиль, но тот становится активной моделью, только если LLM ещё не настроен. Поскольку токен авторизует план одного человека, профиль нельзя передать через гранты для пользователей — каждая учётная запись входит сама за себя, включая обычных пользователей: их карточка входа находится в разделе Провайдеры, а получившиеся модели, каталог и выход из системы остаются приватными для этой учётной записи.

При входе и нажатии Обновить модели DeepTutor считывает последнюю стабильную версию @openai/codex из официального реестра npm и использует её как client_version запроса каталога. Это только метаданные: DeepTutor не устанавливает, не скачивает и не обновляет Codex CLI, а запрос к npm не содержит OAuth-учётных данных. У обнаружения есть предельный срок в три секунды и лимит ответа 64 КиБ. Если оно не удаётся, DeepTutor использует последнюю успешную версию для этой учётной записи либо встроенный резервный вариант, если ничего не закэшировано. Новую версию сохраняет только успешно разобранный живой каталог; валидаторы никогда не используются повторно между версиями или поколениями учётных данных. Отклонение версии или несовместимая структура каталога допускает одну повторную попытку с предыдущей версией; сбои аутентификации, ограничения частоты запросов и TLS не считаются проблемами версии и не повторяются как таковые. Неудачное ручное обновление сообщает об ошибке, а не выдаёт старый закэшированный каталог как обновлённый.

История успешных версий сохраняется при обновлении токена той же учётной записи и при ошибках аутентификации каталога, но не делает недействительные данные модели или ETags снова пригодными для использования. Выход из системы очищает локальный кэш этой учётной записи, включая историю версий. Обычные проверки состояния и инференс не обращаются к npm. Новые записи каталога не заменяют уже выбранную вами модель и не перезапускают учебные сессии; появление в каталоге не означает полную совместимость протокола инференса. Фонового обновления версий или настройки версии пользователем не существует.

Локальные развёртывания Docker и Podman по умолчанию используют раздельные loopback-сети и во время входа требуют временного моста. Следуйте руководству по временному локальному мосту Codex OAuth для точных команд Docker, Compose, Podman и отключения моста.

При удалённом развёртывании localhost браузера и localhost сервера — это разные машины, поэтому обычный обратный прокси сам по себе не может доставить обратный вызов (callback) с localhost браузера на сервер. Используйте SSH-туннель в качестве моста для обратного вызова. Туннель ведёт к уже опубликованному порту Web; Next.js переписывает только точный путь обратного вызова на публичный брокер обратных вызовов, а брокер проверяет state, прежде чем перенаправить к исходной операции OAuth. Слушатель обратного вызова остаётся на loopback-интерфейсе бэкенда, порты 1455 и 1457 не публикуются, и этот путь поддерживает сеть Docker bridge по умолчанию.

ssh -N -L 1455:127.0.0.1:3782 <ssh-user>@<server-host>

Если DeepTutor сообщает резервный порт обратного вызова 1457, используйте:

ssh -N -L 1457:127.0.0.1:3782 <ssh-user>@<server-host>

Выполняйте только ту команду, которая соответствует фактическому порту обратного вызова; никогда не запускайте обе. 3782 — это только пример порта Web: это настроенный порт фронтенда/контейнера, указанный как callback_forward_port. Это значение не гарантирует, что тот же порт прослушивается на 127.0.0.1 SSH-хоста. Если Docker или Podman публикует другой хост-порт, или обратный прокси слушает другой порт, замените только правый (целевой) порт (3782 выше) на порт Web, который фактически прослушивается на 127.0.0.1 SSH-хоста; левый порт обратного вызова оставьте равным 1455 или 1457. <server-host> — это SSH-хост, чей loopback владеет этим прослушиваемым портом. Если URL браузера указывает на обратный прокси или балансировщик нагрузки, замените его на правильный SSH-хост фронтенда.

CLI выводит команду туннеля, а затем сразу пытается открыть браузер. При удалённом развёртывании оставьте страницу авторизации открытой, не завершая её, установите выведенный туннель в другом терминале и только после этого продолжите авторизацию.

У определения удалённой топологии есть граница localhost. Если сам Web доступен через переадресацию localhost по SSH или из IDE, браузер не может определить, что сервер удалённый. Для текущей операции Web оставьте её страницу авторизации незавершённой, прочитайте redirect_uri в URL авторизации этой операции, чтобы определить порт обратного вызова 1455 или 1457, и создайте второй туннель от этого локального порта к фактическому порту Web. В качестве альтернативы отмените эту операцию Web и начните новую через CLI; вывод CLI относится к новой операции и не должен использоваться для уже существующей операции Web. Ошибки квоты и сбои каталога показываются как есть и никогда не приводят к переключению на платного провайдера. Этот путь совместимости экспериментален: вышестоящий интерфейс может измениться.

👥 Многопользовательский режим — Общие Развёртывания · необязательная аутентификация, изолированные рабочие пространства

Аутентификация отключена по умолчанию — DeepTutor работает в однопользовательском режиме. Включите её, и одно дерево data/ содержит рабочее пространство администратора, изолированные пользовательские рабочие пространства и партнёрские рабочие пространства рядом:

data/
├── user/                    # Admin workspace + global settings
├── users/<uid>/             # Per-user scope: chat history, memory, notebooks, KBs
├── partners/<id>/workspace/ # Partner (synthetic-user) scope
├── cli-apps/                # Installed CLI apps, mounted read-only into the sandbox
└── system/                  # auth · grants · audit · user-secrets/<owner> (OAuth tokens)

Первый зарегистрированный пользователь становится администратором и владеет каталогами моделей, учётными данными провайдеров, общими базами знаний, навыками, каноническими общими книгами и грантами для пользователей. Локальные пользователи, созданные администратором, выбирают Standard, Learner или Custom. Learner блокирует учебные возможности и политику материалов, добавляет адаптивный профиль и поддерживает отзываемые учётные данные устройства со сроком действия и дневными лимитами; авторизованные guardians могут просматривать отчёты, одобрять материалы и сбрасывать учётные данные. Остальные пользователи получают изолированные рабочие пространства и ограниченный доступ к моделям, KB, навыкам, Partners и общим книгам без получения необработанных API-ключей. Если auth.json уже содержит username + password_hash, эта учётная запись является администратором: /register остаётся закрытым, а учётные записи, созданные в /admin/users, всегда имеют role=user до повышения роли.

Включение: включите аутентификацию в data/user/settings/auth.json, перезапустите deeptutor start, зарегистрируйте первого администратора по адресу /register, затем добавляйте пользователей из /admin/users и назначайте модели, KB, навыки, Partners, политику инструментов/MCP/CLI-приложений и доступ к выполнению кода через гранты; настройте общие книги в панели Book access каждого пользователя.

Для раздельных приватного/публичного источников задайте auth.private_login_hosts (или AUTH_PRIVATE_LOGIN_HOSTS) — список приватных хостов фронтенда, на которых может показываться вход по паролю и регистрация. Фронтенд передаёт входящий HTTP Host на бэкенд как своё утверждение хоста фронтенда (frontend-host assertion). Сохраняйте Host браузера через ваш обратный прокси и настройте публичный входной шлюз так, чтобы он отклонял запросы, называющие приватный хост; не открывайте необработанный порт Next.js, принимающий произвольные значения Host. HTTP Host может быть подделан прямым клиентом, поэтому авторизация приватного хоста зависит от этой границы входного шлюза. По умолчанию бэкенд принимает утверждения хоста фронтенда только с loopback. Если веб-фронтенд подключается из другого контейнера или хоста, задайте AUTH_TRUSTED_FRONTEND_PROXY_IPS — точный IP-адрес этого прокси фронтенда на процессе бэкенда (через запятую, если их несколько). Держите API бэкенда приватным для прокси фронтенда и не включайте в этот список общие клиентские сети. Loopback всегда разрешён; когда список не пуст, аутентифицированный пользователь на приватном источнике может открыть Профиль → Публичный вход с устройства и создать недолговечную, привязанную к хосту ссылку сопряжения для публичного источника HTTPS. Публичная страница /handoff обменивает одноразовый код на такой же недолговечный билет JWE в теле POST-запроса, использует билет один раз и получает обычную сессионную куки HttpOnly.

PocketBase остаётся однопользовательской интеграцией — оставьте integrations.pocketbase_url пустым для многопользовательских развёртываний, если только вы не подключили внешнее хранилище пользователей.

⌨️ DeepTutor CLI — Интерфейс для Агентов

Один бинарный файл deeptutor, два способа входа: интерактивный REPL для тех, кто живёт в терминале, и структурированный JSON для других агентов, которые управляют DeepTutor как инструментом. Одни и те же возможности, инструменты и базы знаний в любом случае.

Управляйте им самостоятельно

deeptutor chat открывает интерактивный REPL и выбирает режим с помощью --capability; deeptutor run <capability> "<message>" принимает эту возможность как первый позиционный аргумент и завершается после одного хода. Обе команды принимают --tool, --kb, --config и --workspace для выбора зарегистрированного рабочего пространства.

deeptutor chat                                              # interactive 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

Основные функции управления рабочим пространством доступны и здесь — базы знаний (kb), сессии (session), партнёры (partner), навыки (skill), блокноты, память и конфигурация; организация курсов и сессий остаётся в веб-приложении. Полный список ниже.

Позвольте агенту управлять им

DeepTutor создан для того, чтобы им управлял другой агент. Добавьте --format json к любой команде run, и каждый ход транслирует NDJSON — одно событие на строку (content, tool_call, tool_result, done, …), каждая строка помечена своим session_id. Запуски безопасны без TTY: пауза ask_user без TTY автоматически разрешается пустым ответом вместо зависания.

# One shot, machine-readable
deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json

# Chain turns in one stateful session — capture the id, reuse it
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

В репозитории есть корневой SKILL.md — краткое руководство для агента по работе с CLI. Явно попросите агента прочитать его; руководство по настройке с помощью агента описывает установку и конфигурацию. Также можно обернуть deeptutor run как инструмент в цикл LangChain / AutoGen. Полные рецепты: Agent Handoff.

Справочник команд

Команда	Описание
deeptutor init [--non-interactive] [--home PATH]	Запустить мастер настройки или создать отсутствующие настройки по умолчанию без запросов
deeptutor doctor [--online]	Проверить, готова ли среда выполнения к запуску сессии; --online также проверяет настроенного провайдера модели, --format json выводит отчёт
deeptutor start [--home PATH] [--dev] [--detach] [--no-browser]	Запустить бэкенд + фронтенд вместе; при необходимости отсоединить процесс или запретить открытие браузера
deeptutor stop [--home PATH]	Остановить лаунчер, запущенный с --detach
deeptutor serve [--port PORT]	Запустить только бэкенд FastAPI
deeptutor workspace show/set/reset	Просмотр, выбор или восстановление персонального Рабочего пространства для контента
deeptutor run <capability> <message>	Запустить один ход возможности (chat, ask_questions, deep_solve, deep_question, deep_research, visualize, math_animator, mastery_path, immersive_reading, course_study, audio_overview); добавьте --format json для вывода NDJSON
deeptutor chat	Интерактивный REPL с управлением возможностями, инструментами, KB, блокнотами и историей
deeptutor partner list/create/start/stop	Управление партнёрами, подключёнными к IM
deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync	Управление базами знаний, подключение архивов Kiwix, оценка качества поиска на наборе вопросов и ответов и синхронизация зарегистрированных источников GitHub/Web (с командами добавления/удаления источников)
deeptutor skill search/install/list/remove/login/logout/publish/update	Управление навыками, установка из хабов и публикация своих (eduhub:<slug> по умолчанию, см. Экосистема)
deeptutor memory show/clear	Просмотр документов памяти L2/L3 или очистка памяти L1/всей памяти
deeptutor session list/show/open/rename/delete	Управление общими сессиями
deeptutor notebook list/create/show/add-md/replace-md/remove-record	Управление блокнотами из файлов Markdown
deeptutor book list/health/refresh-fingerprints	Просмотр книг и обновление исходных отпечатков
deeptutor plugin list/info/state/search/show/install/approve/enable/disable/rollback/uninstall	Просмотр инструментов и возможностей; управление проверенными пакетами плагинов и подтверждением их разрешений
deeptutor config show [--home PATH]	Показать итоговую конфигурацию среды выполнения со скрытыми учётными данными
deeptutor config providers	Вывести поддерживаемых провайдеров настройки и значения по умолчанию в формате JSON
deeptutor config apply FILE [--check] [--home PATH]	Применить JSON настройки без запросов или проверить его без записи настроек
deeptutor provider login <provider>	Аутентификация провайдера (openai-codex вход через OAuth; github-copilot вход через код устройства GitHub; codebuddy проверяет аутентификацию CodeBuddy SDK и запускает вход при необходимости)

Учётные данные GitHub Copilot принадлежат вошедшему в систему владельцу DeepTutor и хранятся только в <runtime-home>/data/system/user-secrets/<owner-id>/private/github-copilot/credentials.v1.json, вне рабочих пространств песочницы. Партнёры CLI/администратора используют учётные данные администратора; остальные пользователи входят отдельно, а профилями Copilot нельзя делиться через гранты моделей. Внешние файлы токенов nanobot/Copilot никогда не импортируются: после обновления повторно выполните deeptutor provider login github-copilot.

При входе проверяется выполнение запроса к модели, обнаруженной в актуальном каталоге; init проверяет выбранную модель и при ошибке прерывает работу без сохранения черновой конфигурации. Успешная аутентификация GitHub сама по себе не подтверждает доступ к моделям Copilot (сохранённая авторизация остаётся, даже если проверка не пройдена). Запросы во время работы используют конечную точку API, полученную при обмене токена, в том числе после его обновления, и учитывают метаданные конечных точек Responses/Chat Completions для каждой модели.

Специальная совместимость Responses для Copilot применяется при отправке запроса без перезаписи сохранённой истории.

Дистрибутив только с CLI

Пакет только с CLI находится в packaging/deeptutor-cli. В этом чекауте установите его из исходного кода:

python -m pip install -e ./packaging/deeptutor-cli

Он ещё не опубликован в PyPI, поэтому основной раздел Начало работы сохраняет путь установки из исходного кода.

🧩 Экосистема — EduHub и Сообщество Навыков

Навыки DeepTutor используют открытый формат Agent-Skills — папку с плейбуком SKILL.md (YAML frontmatter + Markdown) и необязательными справочными файлами. В нём нет ничего специфичного для DeepTutor, поэтому любой реестр, говорящий на этом формате, становится источником для вашей библиотеки. DeepTutor поставляется с EduHub — нашим собственным образовательным реестром навыков — встроенным в качестве хаба по умолчанию.

EduHub — экосистема навыков DeepTutor

EduHub — это хаб сообщества, запущенный DeepTutor для обмена обучающими навыками агентов — сократовские репетиторы, создатели флэш-карточек, обратная связь по эссе, планы экзаменов, объяснители концепций и многое другое. Он встроен в DeepTutor, поэтому настраивать ничего не нужно: голый слаг или префикс eduhub: разрешается в него.

Найти и установить — в браузере откройте Пространство Обучения → Навыки → Импорт из EduHub для просмотра каталога и загрузки навыка прямо в вашу библиотеку. Из терминала:

deeptutor skill search "socratic tutor"               # search EduHub (the default hub)
deeptutor skill install socratic-tutor                # fetch → verify → register
deeptutor skill install eduhub:socratic-tutor@1.2.0   # pin a hub and a version
deeptutor skill list                                  # local skills with their hub provenance

Опубликуйте свой — упакуйте SKILL.md и поделитесь им обратно с сообществом:

deeptutor skill login                                 # browser sign-in to EduHub
deeptutor skill publish ./my-skill                    # interactive: pick a track + tags, then upload
deeptutor skill update                                # roll back or release a new version

EduHub также является отдельным, совместимым с ClawHub реестром, поэтому агенты, отличные от DeepTutor (Claude Code, Codex, …), могут использовать его напрямую через CLI eduhub — npx eduhub install socratic-tutor.

Шлюз безопасности импорта

Независимо от источника, каждый импорт проходит через один шлюз безопасности перед тем, как что-либо коснётся вашего рабочего пространства:

• сначала проверяется вердикт безопасности реестра — отмеченные пакеты отклоняются, если вы не передали --allow-unverified;
• архивы извлекаются безопасно с проверками обхода путей, числа записей, размера, коэффициента сжатия, суффиксов и символических ссылок; биты исполнения снимаются, а файлы без расширения остаются разрешёнными;
• frontmatter нормализуется по схеме DeepTutor, и always: удаляется, поэтому загруженный навык никогда не может принудить себя в каждый системный промпт;
• происхождение — хаб, версия, вердикт и время установки — записывается в .hub-lock.json для аудитов и обновлений.

В многопользовательских развёртываниях импорт через браузер попадает в слой навыков аутентифицированного пользователя, тогда как установки через CLI и консоль администратора направляются в рабочее пространство владельца/администратора; навыки администратора остаются скрытыми и доступными обычным пользователям только для чтения, пока не выдан грант.

Также совместим с ClawHub

Поскольку DeepTutor использует открытый формат Agent-Skills, ClawHub также работает как первоклассный источник — он встроен рядом с EduHub. Выберите его с префиксом хаба:

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

Когда один и тот же слаг используют несколько издателей, поиск показывает каждого издателя и полностью определённую ссылку для установки (clawhub:<ownerHandle>/<slug>).

Добавляйте дополнительные реестры в data/user/settings/skill_hubs.json: запись type: "clawhub" указывает на любой совместимый HTTP API (EduHub и ClawHub оба его поддерживают), type: "command" оборачивает любой CLI получения, который поставляет реестр, а "default" выбирает хаб, используемый для голых слагов. Все они передаются через тот же шлюз импорта.

🤝 Партнёры по открытому коду

Используйте код: DEEPTUTOR20 — скидка $20 на первую подписку PageIndex!

🌐 Сообщество

🔗 Мейнтейнеры

Bingxi Zhao

Xingyu Hou

Jiahao Zhang

📮 Контакты

DeepTutor — это проект с открытым исходным кодом, который ведёт Bingxi Zhao в составе группы HKUDS, и он развивается в полностью открытом формате, создаваясь вместе с сообществом. До сих пор у нас НЕТ платных онлайн-продуктов в каком-либо виде. Не стесняйтесь обращаться по адресу bingxizhao39@gmail.com для обсуждений, идей или сотрудничества.

🙏 Благодарности

Сердечная благодарность Chao Huang, директору Лаборатории интеллектуальных данных @ HKU, и нашим коллегам из HKUDS за их тёплую поддержку — особенно Jiahao Zhang, Zirui Guo и Xubin Ren. Мы также глубоко благодарны сообществу открытого исходного кода: ваши звёзды, вопросы, пул-реквесты и обсуждения каждый день формируют DeepTutor.

DeepTutor также стоит на плечах выдающихся проектов с открытым исходным кодом, которые дали нам инструменты и вдохновение:

Проект	Роль / Вдохновение
LlamaIndex	Конвейер RAG и основа индексирования документов
nanobot	Ультралёгкий движок агентов, обеспечивавший оригинальный TutorBot (HKUDS)
LightRAG	Простой и быстрый RAG (HKUDS)
AutoAgent	Фреймворк агентов без кода (HKUDS)
AI-Researcher	Автоматизированный исследовательский конвейер (HKUDS)
OpenClaw	Открытый шлюз агентов и экосистема навыков за ClawHub
Codex	Агентный CLI кодирования, вдохновивший наш рабочий процесс CLI
Claude Code	Агентный CLI кодирования, вдохновивший цикл агента DeepTutor
ManimCat	Генерация математической анимации на основе ИИ для Math Animator

🗺️ Дорожная карта и участие

Мы хотим, чтобы DeepTutor продолжал развиваться и совершенствоваться — и в конечном итоге стал подарком, который мы возвращаем сообществу открытого исходного кода. Наша дорожная карта обновляется непрерывно; голосуйте там за пункты или предлагайте новые. Если вы хотите участвовать, см. Руководство по участию с описанием стратегии ветвления, стандартов кодирования и инструкций по началу работы.

Мы надеемся, что DeepTutor станет подарком для сообщества. 🎁

Лицензировано по Apache License 2.0.

Привязка ходов Mastery к текущему состоянию

Перед первым запросом к модели ходы Mastery считывают состояние активного пути, используя тот же инструмент состояния и те же ограничения Mastery, что и при явном вызове инструмента. Снимок обновляется для каждого хода, включает активный режим сессии и никогда не кэшируется между ходами. Если чтение не удаётся, используется mastery_status; после изменения пути, режима, плана или прогресса репетитор может обновить состояние через этот инструмент. Оценивание карточек и существующая передача управления остаются без изменений.

Повторяющиеся вложения изображений

Цикл агента отправляет одинаковые встроенные изображения пользователя один раз на запрос, а последующие копии заменяет ссылками на сохранённое изображение. Стабильные метки, действующие только в пределах запроса, обозначают сохранённые встроенные изображения при преобразовании для разных провайдеров и добавлении ходов. Уникальные блоки изображений, удалённые URL, отличающиеся параметры изображений, сообщения ассистента и результаты инструментов сохраняются полностью. Сохранённая история содержит все исходные вложения; ссылки пересоздаются после сокращения истории. Это уменьшает объём повторяющихся данных изображений, но сведения об использовании, сообщаемые провайдером, остаются источником истины для оплаты и попаданий в кэш.