DeepTutor — агентное рабочее пространство для обучения с RAG, памятью и CLI

DeepTutor — это open-source рабочее пространство для обучения от группы HKUDS. Не чат-бот и не набор промптов, а агентная система, где репетитор, поиск по базе знаний, генерация вопросов, исследование, визуализация и практика живут на одном рантайме. Бэкенд написан на Python (FastAPI), фронтенд — на Next.js 16, лицензия Apache 2.0. На момент публикации у репозитория около 40 000 звёзд, последний релиз — v1.6.11. Дизайн и идеи описаны в препринте на arXiv, документация живёт на deeptutor.info.

Один рантайм на все режимы

Чат, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading и Immersive Watching делят один capability-рантайм и общий контекст сессии, но сохраняют собственные циклы и пайплайны под каждый режим.

Агентный цикл в чате сознательно простой: модель думает раундами, при необходимости вызывает инструмент, наблюдает результат и завершает ход сообщением без вызовов. Отдельный инструмент 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, list_notebook, write_note, question_bank, github, consult_subagent, workspace_list, workspace_read, workspace_search, workspace_present, workspace_export.

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

Мультидвижковый RAG

Базы знаний — это коллекции документов, на которых grounded-ответы в чате, правки в Co-Writer, генерация книг и диалоги с Partners. Отличительная черта — выбор движка поиска под каждую базу: к базе привязан ровно один движок.

Парсинг документов выбирается отдельно: Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM или LiteParse. База может также отслеживать GitHub-репозитории (repo, branch, glob) и URL документационных сайтов с ограниченной глубиной обхода и ресинхронизацией раз в 24 часа. Переиндексация пишет новый плоский каталог version-N и сохраняет предыдущие, поэтому рабочий индекс не уничтожается посреди пересборки.

Память в три слоя

Память файловая и намеренно инспектируемая — это не скрытое векторное хранилище:

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

Memory Graph показывает всю пирамиду: синтез L3 в центре, L2 в среднем кольце, трассы L1 снаружи, с точными рёбрами L2 → L1 и L3 → поверхности. Память ведётся по поверхностям chat, notebook, quiz, kb, book, partner, cowriter.

Content Workspace и песочница

Content Workspace отделён от приватного runtime home. Это папка, которую агенты могут читать, а сгенерированные файлы кладутся в outputs/<capability>/<session>/<turn>/. Вне outputs/ запись запрещена; копирование сгенерированного файла в другое место внутри workspace требует явного подтверждения «Allow once» для конкретной пары источник-приёмник. Границу обеспечивает системная песочница или Docker-раннер, локальный fallback через ограниченный subprocess помечен в настройках как best effort.

Бэкенд песочницы выбирается по убыванию надёжности: runner-sidecar (DEEPTUTOR_SANDBOX_RUNNER_URL), Linux bubblewrap, затем ограниченный subprocess. Параметр sandbox_allow_subprocess в data/user/settings/system.json управляет только последним fallback — более сильные бэкенды он не отключает.

Установка: четыре пути

Из PyPI — полный веб-приложение и CLI без клонирования:

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init
deeptutor start

Нужны Python 3.11–3.14 и Node.js 20+ в PATH. deeptutor init спрашивает порт бэкенда (по умолчанию 8001), порт фронтенда (3782), провайдера LLM, base URL, ключ и модель, опционально embedding и поиск. Веб-интерфейс открывается на http://127.0.0.1:3782, остановка — Ctrl+C.

Из исходников — вариант для разработки, с venv или conda, затем python -m pip install -e ., npm ci в web/, deeptutor start --dev для HMR. Есть набор extras: rag-lightrag, graphrag, dev, partners, matrix, math-animator.

В Docker — один самодостаточный контейнер с образом на GitHub Container Registry:

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

Публиковать наружу нужно только порт 3782: браузер общается только с origins фронтенда, а middleware Next.js проксирует /api/* и /ws/* на бэкенд внутри контейнера. Подробности развёртывания, Podman и read-only rootfs — в гайде по контейнеризации.

Только CLI — из исходников, пакет packaging/deeptutor-cli пока не опубликован на PyPI:

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

CLI как инструмент для другого агента

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

deeptutor chat --capability deep_solve --kb my-kb --tool rag
deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard

С флагом --format json каждый ход стримится как NDJSON — по событию в строке (content, tool_call, tool_result, done), каждая строка помечена своим session_id. Такие запуски безопасны для headless-сценариев: пауза ask_user без TTY автоматически разрешается пустым ответом, а не зависает.

# Склеить ходы в одной stateful-сессии
SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" --format json \
  | jq -r 'select(.type=="done").session_id')
deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json

В корне репозитория лежит SKILL.md — документ-передача на ~200 строк, который учит любой tool-using LLM всей поверхности за одно чтение. Его можно отдать Claude Code, Codex или OpenCode (они подхватывают SKILL.md автоматически) либо обернуть deeptutor run в инструмент цикла LangChain / AutoGen. Готовые рецепты — в руководстве по handoff.

Субагенты, Partners и навыки

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

Partners — постоянные компаньоны со своим SOUL.md, политикой модели, библиотекой, памятью и каналами. Это не отдельный движок ботов: каждое входящее сообщение из веба или мессенджера становится обычным ходом ChatOrchestrator в workspace партнёра. Слой каналов схема-ориентирован и подключает Feishu, Telegram, Slack, Discord, DingTalk, QQ/NapCat, WeCom, WhatsApp, Zulip, Mattermost, Matrix, Mochat и Microsoft Teams — в зависимости от установленных extras и учётных данных.

Навыки используют открытый формат Agent-Skills: папка с плейбуком SKILL.md (YAML-фронтматтер плюс Markdown) и необязательными файлами-ссылками. Встроенный EduHub — собственный реестр обучающих навыков, а ClawHub работает как равноправный источник через префикс хаба.

deeptutor skill search "socratic tutor"
deeptutor skill install eduhub:socratic-tutor@1.2.0
deeptutor skill publish ./my-skill

Любой импорт проходит общий защитный шлюз: проверяется вердикт безопасности реестра, архив распаковывается защитно (path traversal, число записей, размер, коэффициент сжатия, суффиксы, симлинки), биты исполнения снимаются, а поле always: из фронтматтера вырезается — скачанный навык не может вклиниться в каждый системный промпт. Провенанс (хаб, версия, вердикт, время установки) пишется в .hub-lock.json.

Конфигурация и многопользовательский режим

Всё лежит в data/user/settings/ в виде обычных JSON и YAML: каталог провайдеров и профилей моделей в model_catalog.json, порты и CORS в system.json, аутентификация в auth.json, интерфейс в interface.json, парсинг в document_parsing.json, температуры и токены в agents.yaml. Рекомендуемый редактор — страница Settings; корневой .env намеренно не читается.

Аутентификация выключена по умолчанию, и DeepTutor работает в однопользовательском режиме. После включения один каталог data/ содержит админское workspace, изолированные workspace пользователей и workspace партнёров. Первый зарегистрированный пользователь становится админом и владеет каталогом моделей, учётными данными провайдеров, общими базами знаний, навыками и правами выдачи. Остальные получают изолированные рабочие пространства и ограниченный доступ без сырых API-ключей.

Проверить готовность рантайма к старту сессии можно командой deeptutor doctor — с флагом --online она дополнительно пингует настроенного провайдера модели.

Итог

DeepTutor интересен прежде всего как образец того, что происходит, когда агентная архитектура доводится до полноценного приложения: единый рантайм вместо набора скриптов, память, которую можно прочитать и починить, честный выбор между движками RAG, чёткие границы песочницы и CLI-интерфейс, рассчитанный в том числе на то, чтобы им управлял другой агент. Цена этого — крупная кодовая база и высокая скорость релизов: v1.6.11 вышел 24 сентября 2026 года, а предыдущие релизные записи занимают в README целый раздел.

Лицензия — Apache 2.0, файл LICENSE. Участие в проекте описано в гайде для контрибьюторов, а список идей для голосования — в роадмапе.