README_PT.md

 

DeepTutor: Tutoria Personalizada Vitalícia

 

   

                     

Recursos · Começar · Explorar · CLI · Ecossistema · Comunidade

---

🤝 Damos as boas-vindas a todo tipo de contribuições! Vote em itens do roadmap ou proponha novos em Roadmap, e consulte o nosso Guia de Contribuição para a estratégia de branches, padrões de código e como começar.

📰 Notícias

• 2026-05-22 🌐 Site oficial de documentação disponível em deeptutor.info — guias, referências e tours de capacidades num só lugar.
• 2026-04-19 🎉 Atingimos 20k estrelas em 111 dias! Obrigado pelo apoio incrível rumo a uma tutoria verdadeiramente personalizada e inteligente para todos.
• 2026-04-10 📄 O nosso artigo está agora no arXiv! Leia o preprint para saber mais sobre o design e as ideias por trás do DeepTutor.
• 2026-02-06 🚀 Atingimos 10k estrelas em apenas 39 dias! Um enorme obrigado à nossa incrível comunidade pelo apoio!
• 2026-01-01 🎊 Feliz Ano Novo! Junte-se ao nosso Discord, WeChat ou Discussions — juntos damos forma ao futuro do DeepTutor!
• 2025-12-29 🎓 DeepTutor está oficialmente lançado!

✨ Recursos Principais

O DeepTutor é um espaço de trabalho de aprendizagem nativo de agentes que conecta tutoria, resolução de problemas, geração de quizzes, pesquisa, visualização e prática de domínio num sistema extensível.

• Um runtime para todos os modos — Chat, Quiz, Research, Visualize, Solve, Mastery Path e Immersive Reading correm no mesmo loop de agente, pelo que muda o objetivo, não o motor, e o contexto acompanha o utilizador.
• Contexto de aprendizado conectado — bases de conhecimento, livros, rascunhos Co-Writer, cadernos, bancos de questões, personas e Memory permanecem disponíveis em todos os fluxos de trabalho em vez de viverem em ferramentas isoladas.
• Subagentes e Partners — consultar uma CLI de programação ao vivo (Claude Code, Codex, Gemini, Kimi, opencode ou MiMo) ou um Partner a partir de qualquer turno (ou importar as suas conversas anteriores), e correr companheiros IM persistentes no mesmo cérebro.
• Conhecimento multi-motor — bibliotecas RAG com versões: LlamaIndex, PageIndex, GraphRAG, LightRAG, um LightRAG Server remoto, uma biblioteca Tencent IMA ou MarginNote 4, ou um vault Obsidian vinculado, com análise de documentos conectável.
• Ferramentas e habilidades extensíveis — ferramentas integradas, servidores MCP, aplicações CLI, modelos de geração de imagem / vídeo / voz e habilidades da comunidade instaláveis do EduHub.
• Memória inspecionável — rastreamentos L1, resumos de superfície L2 e síntese L3 tornam a personalização visível e editável, com um Memory Graph que rastreia cada afirmação até à sua evidência.

---

🚀 Começar

O DeepTutor inclui quatro caminhos de instalação. Todos partilham um layout de espaço de trabalho: as configurações vivem em data/user/settings/ sob o diretório a partir do qual é iniciado (ou sob DEEPTUTOR_HOME / deeptutor start --home se definido explicitamente). Para a aplicação completa, o fluxo recomendado é escolher um diretório de espaço de trabalho → instalar → deeptutor init → deeptutor start.

Opção 1 — Instalar a partir do PyPI · aplicação web local completa + CLI, sem necessidade de clonar

Aplicação web local completa + CLI, sem necessidade de clonar. Requer Python 3.11–3.13 e um runtime Node.js 20+ no PATH (o servidor standalone Next.js empacotado é iniciado por deeptutor start).

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # solicita portas + provedor LLM + embedding opcional
deeptutor start    # inicia backend + frontend; manter o terminal aberto

deeptutor init solicita a porta de backend (predefinição 8001), a porta de frontend (predefinição 3782), provedor LLM / URL base / chave API / modelo e um provedor de embeddings opcional para Base de Conhecimento / RAG.

Após deeptutor start, abra a URL do frontend impressa no terminal — por predefinição http://127.0.0.1:3782. Prima Ctrl+C nesse terminal para parar tanto o backend como o frontend. Omitir deeptutor init é adequado para um teste rápido; a aplicação arranca com portas predefinidas e configuração de modelo vazia, configure-as depois em Settings → Models.

Opção 2 — Instalar a partir do Código-Fonte · desenvolver num checkout

Para desenvolvimento num checkout. Use Python 3.11–3.13 e Node.js 22 LTS para coincidir com CI e Docker.

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

# Criar um 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

# Instalar dependências de backend + frontend
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )

deeptutor init
deeptutor start --dev

deeptutor start compila o frontend web/ local para produção uma vez e reutiliza-o; --dev executa o Next.js com HMR. O layout de configuração, as portas e o Ctrl+C correspondem à Opção 1.

Ambiente Conda (em vez de venv)

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

Extras de instalação opcionais — dev / partners / matrix / math-animator

pip install -e ".[dev]"             # ferramentas de testes/lint
pip install -e ".[partners]"        # SDKs de canais IM de Partners + cliente MCP
pip install -e ".[matrix]"          # canal Matrix sem E2EE/libolm
pip install -e ".[matrix-e2e]"      # Matrix E2EE; requer libolm
pip install -e ".[math-animator]"   # add-on Manim; requer LaTeX/ffmpeg/libs do sistema

Ajustes de dependências do frontend e resolução de problemas do servidor de desenvolvimento

Alterar dependências do frontend: execute npm install --legacy-peer-deps para atualizar web/package-lock.json, depois confirme tanto web/package.json como web/package-lock.json.

Servidor de desenvolvimento bloqueado: se deeptutor start --dev reportar um frontend existente que não responde, pare o PID que imprime. Se não houver nenhum processo Next.js em execução, os ficheiros de bloqueio estão desatualizados — remova-os e tente novamente:

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

Opção 3 — Docker · um contentor autossuficiente

Um contentor para a aplicação web completa. Imagens no GitHub Container Registry:

• ghcr.io/hkuds/deeptutor:latest — lançamento estável
• ghcr.io/hkuds/deeptutor:pre — pré-lançamento, quando disponível

Consulte CONTAINERIZATION.md para implementações podman/rootless/read-only-rootfs e o guia completo por instalação.

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

Apenas 3782 precisa de ser publicado. O navegador comunica exclusivamente com a origem do frontend; o middleware Next.js (web/proxy.ts) reencaminha /api/* e /ws/* para o backend FastAPI dentro do contentor. Publicar 8001 (-p 127.0.0.1:8001:8001) é opcional — útil apenas para aceder à API diretamente com curl ou scripts.

Abra http://127.0.0.1:3782. O contentor cria /app/data/user/settings/*.json no primeiro arranque; configure os provedores de modelos a partir da página de Settings web. A configuração, as chaves API, os logs, os ficheiros do espaço de trabalho, a memória e as bases de conhecimento persistem no volume deeptutor-data. Extras opcionais pertencem à implementação, não a uma shell: defina DEEPTUTOR_EXTRAS (e DEEPTUTOR_APT_PACKAGES para bibliotecas de sistema) e cada contentor iniciado a partir dela reaplica-os, ao passo que um docker exec … pip install seria perdido no compose down seguinte.

• Portas de host diferentes: altere o lado esquerdo de cada mapeamento -p host:container (ex. -p 127.0.0.1:8088:3782). Se alterar as portas do lado do contentor em /app/data/user/settings/system.json, reinicie e atualize o lado direito de cada mapeamento para corresponder.
• Desconectado: adicione -d, depois docker logs -f deeptutor para seguir, docker stop deeptutor para parar, docker rm deeptutor antes de reutilizar o nome. O volume deeptutor-data mantém as suas configurações e espaço de trabalho entre reinicializações.

Docker remoto / proxy inverso: o navegador comunica apenas com a origem do frontend (:3782); o middleware Next.js dentro do contentor reencaminha /api/* e /ws/* para o servidor de backend do lado do servidor. Para o caso comum de contentor único, não configura uma base de API — apenas aponte o seu proxy inverso / terminador TLS para :3782. Só precisa de uma base de API para uma implementação separada (backend num contentor/host separado): defina next_public_api_base em data/user/settings/system.json para o endereço interno que o servidor frontend usa para alcançar o backend (é lido do lado do servidor, nunca enviado ao navegador).

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

next_public_api_base_external (e o seu alias public_api_base) são aceites como fallbacks de menor precedência. CORS usa origens de frontend, não URLs de API. Com a autenticação desativada, o DeepTutor permite origens normais de navegador HTTP/HTTPS por predefinição. Com a autenticação ativada, adicione as origens exatas do frontend:

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

Ligar ao Ollama / LM Studio / llama.cpp / vLLM / Lemonade no host

Dentro do Docker, localhost é o próprio contentor, não a sua máquina host. Para alcançar um serviço de modelo em execução no host, use o host gateway (recomendado):

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

Depois em Settings → Models, aponte o URL Base do provedor para 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

O Docker Desktop (macOS/Windows) geralmente resolve host.docker.internal sem --add-host. No Linux, o flag é a forma portátil de criar esse nome de host no Docker Engine moderno.

Alternativa para Linux — rede do host: adicione --network=host e remova os flags -p. O contentor partilha a rede do host diretamente, por isso abra http://127.0.0.1:3782 (ou o frontend_port em system.json), e os serviços do host podem ser alcançados com URLs de localhost normais como http://127.0.0.1:11434/v1. Note que a rede do host expõe as portas do contentor diretamente no host e pode entrar em conflito com serviços existentes — para os manter no loopback, defina BACKEND_HOST=127.0.0.1 e FRONTEND_HOST=127.0.0.1 (consulte CONTAINERIZATION.md).

Opção 4 — Apenas CLI · sem UI web, a partir de um checkout de fonte

Quando não precisa da UI web. O pacote de apenas CLI é instalado a partir de um checkout de fonte, não a partir do PyPI.

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

# Criar um 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 partilha o mesmo layout data/user/settings/ que a aplicação completa mas omite as solicitações de portas de backend/frontend e define embeddings como desativado (escolha Yes se planear usar deeptutor kb … ou ferramentas RAG). Ainda escreve um layout de runtime completo (system.json, auth.json, integrations.json, model_catalog.json, main.yaml, agents.yaml) e ainda solicita o provedor LLM e modelo ativos.

Comandos comuns

deeptutor chat                                          # REPL interativo
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

A instalação local de deeptutor-cli não inclui ativos web nem dependências de servidor. Mantenha o checkout de fonte por perto — a instalação editável aponta para ele. Para adicionar a aplicação web mais tarde, instale o pacote PyPI (Opção 1) e execute deeptutor init + deeptutor start a partir do mesmo espaço de trabalho.

Sandbox de Execução de Código (skills de escritório) · executar código gerado pelo modelo para docx / pdf / pptx / xlsx

As skills de escritório integradas — docx / pdf / pptx / xlsx — funcionam fazendo com que o modelo escreva um script Python curto (python-docx, reportlab, openpyxl, …), o execute através das ferramentas exec / code_execution e devolva um URL de download. Essas ferramentas montam sempre que um backend de sandbox está ativo, o que é o caso por predefinição em cada forma de implementação:

• Local (Opção 1 / 2) e Docker (Opção 3, contentor único): um sandbox de subprocesso restrito executa o código do modelo (localmente no host, ou dentro do contentor sob Docker — o contentor sendo o seu próprio limite de isolamento).
• docker-compose: encaminhado em vez disso para um sidecar runner endurecido e com privilégios mínimos (Dockerfile.runner) via DEEPTUTOR_SANDBOX_RUNNER_URL — a postura mais sólida, e preferida automaticamente quando presente.

O sandbox de subprocesso é controlado pela configuração sandbox_allow_subprocess em data/user/settings/system.json (predefinição true). Executar código gerado pelo modelo no seu host é uma decisão real de confiança — defina-o como false (ou exporte DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0) para desativar a execução do lado do host, à custa das skills de escritório já não conseguirem produzir ficheiros.

Referência de configuração — ficheiros de configuração sob data/user/settings/ (JSON/YAML)

Tudo sob data/user/settings/ é JSON/YAML simples. A página Settings no navegador é o editor recomendado.

Ficheiro	Propósito
model_catalog.json	Perfis de provedores LLM, embeddings e pesquisa; chaves API; modelos ativos
system.json	Portas de backend/frontend, base de API pública, CORS, verificação SSL, diretório de anexos e limites de carregamento/extração
auth.json	Interruptor de autenticação opcional, nome de utilizador, hash de palavra-passe, configurações de token/cookie
integrations.json	Configurações opcionais de PocketBase e integrações sidecar
interface.json	Preferências de idioma da UI e de saída do modelo / tema / barra lateral
main.yaml	Predefinições de comportamento de runtime e injeção de caminhos
agents.yaml	Configurações de temperatura e tokens de capacidades/ferramentas

O .env da raiz do projeto não é lido como ficheiro de configuração da aplicação. Para uma configuração mínima do modelo, abra Settings → Models, adicione um perfil LLM (URL Base / chave API / nome do modelo) e guarde. Adicione um perfil de embeddings apenas se planear usar funcionalidades de Base de Conhecimento / RAG.

📖 Explorar o DeepTutor

Comece pelas superfícies principais que usará no dia a dia: Chat, Partners, Meus Agentes, Co-Writer, Book, Centro de Conhecimento, Espaço de Aprendizado, Memory e Configurações. O tour cobre também as implementações Multi-Utilizador para espaços de trabalho partilhados e isolados.

🏗️ Arquitetura do sistema

💬 Chat — O Loop de Agente que Realmente Usa

Chat é a capacidade predefinida e o lugar onde a maior parte do trabalho começa. Um único thread pode conversar normalmente, chamar ferramentas, fundamentar-se em bases de conhecimento selecionadas, ler anexos, gerar imagens, consultar subagentes, escrever registos de notebook e continuar com o mesmo contexto entre turnos.

O loop é deliberadamente simples: o modelo pensa em rondas, chama ferramentas quando útil, observa os resultados e termina com uma mensagem sem ferramentas. ask_user é especial — em vez de adivinhar, o agente pode pausar o turno, fazer uma pergunta de esclarecimento estruturada e retomar assim que responder.

As ferramentas ativáveis pelo utilizador são brainstorm, web_search, paper_search, reason e geogebra_analysis — mais imagegen e videogen depois de configurar o modelo de geração correspondente. Ferramentas contextuais como rag, kb_files, read_source, read_memory, write_memory, read_skill, load_tools, exec, web_fetch, ask_user, list_notebook, write_note, question_bank, github e consult_subagent montam automaticamente quando o turno tem o contexto certo.

O contexto é de dois tipos: contexto de sessão fixo (subagente, bases de conhecimento, persona, modelo, voz) vive na barra de ferramentas do compositor e persiste entre turnos; referências únicas (ficheiros, histórico de chat, livros, notebooks, banco de questões, agentes importados) vêm do menu + para um único turno.

Chat é também o ponto de lançamento para capacidades mais profundas: Quiz para geração de perguntas, Visualize para gráficos / diagramas / animações, Mastery Path para fluxos de planos de aprendizagem, e Immersive Reading — um documento aberto ao lado do thread, com cada afirmação citada até à página de onde veio. Research para relatórios com citações e Solve para raciocínio trabalhado ficam em More Capabilities.

🤝 Partner — Companheiros Persistentes no Mesmo Cérebro

Os Partners são companheiros persistentes com a sua própria alma, política de modelo, biblioteca, memória e canais. Não são um motor de bot separado: cada mensagem web ou IM recebida torna-se um turno normal do ChatOrchestrator dentro de um espaço de trabalho com âmbito de partner. Um partner é "um chat que tem personalidade e número de telefone."

Cada partner tem um SOUL.md, seleção de modelo, canais, política de ferramentas e biblioteca atribuída. As bases de conhecimento, skills e notebooks são copiadas para data/partners/<id>/workspace/, pelo que as mesmas ferramentas de RAG, skill, notebook e memória funcionam sem casos especiais. Um partner lê a memória do seu proprietário mas escreve apenas a sua própria.

A camada de canais é orientada por esquema e pode ligar-se a plataformas IM como Feishu, Telegram, Slack, Discord, DingTalk, QQ/NapCat, WeCom, WhatsApp, Zulip, Mattermost, Matrix, Mochat e Microsoft Teams dependendo dos extras instalados e das credenciais configuradas. Um partner também pode ser conectado como subagente e consultado a partir de um turno de chat normal — veja Meus Agentes abaixo.

Para uma configuração mais rápida, a página de canal do Partner pode criar uma aplicação Feishu/Lark ou um bot de IA WeCom, ou iniciar sessão numa conta pessoal de WeChat, a partir de um código QR desenhado no navegador em vez do log do servidor. O Feishu/Lark deteta o domínio da conta e guarda o utilizador que fez a leitura como o remetente permitido inicial. O WeCom mantém uma lista de permissões existente e, caso contrário, assume por predefinição todos os utilizadores que conseguem alcançar o bot, com um aviso visível de acesso aberto; os formulários de canal manuais permanecem disponíveis caso o protocolo de leitura de um provedor mude.

🧑‍🚀 Meus Agentes — Consultar e Importar Outros Agentes

Meus Agentes transforma outros agentes em contexto para o DeepTutor, e faz duas coisas distintas. Conectar um agente ao vivo — um Claude Code, Codex, Gemini, Antigravity, Kimi, opencode ou MiMo Code CLI na sua máquina, ou um dos seus Partners — e consultá-lo a partir de dentro de um turno de chat: o DeepTutor executa mesmo o outro agente e transmite o seu trabalho para o painel de Atividade via a ferramenta consult_subagent. Selecione-o com o chip de Agente (ou escreva @), e defina quantas rondas a consulta pode ter.

Importar conversas anteriores — traga o seu histórico existente do Claude Code e Codex como agentes nomeados, pesquisáveis e retomáveis. Escolha quais os dias a importar; atualizar ressincroniza-os. Referencie uma conversa importada a partir de qualquer turno de chat via + → Meus Agentes, e o DeepTutor lê-a como uma transcrição de terceiros — permanece a conversa deles, não a voz própria do DeepTutor.

✍️ Co-Writer — Rascunho Markdown com Consciência de Seleção

Co-Writer é um espaço de trabalho Markdown de vista dividida para relatórios, tutoriais, notas e artefactos de aprendizagem de formato longo. Os documentos guardam automaticamente, renderizam uma pré-visualização em tempo real (matemática KaTeX, cercas de diagramas) e podem ser guardados de volta em notebooks quando um rascunho se torna contexto reutilizável.

A sua ideia central é a edição cirúrgica: selecione um trecho e peça ao DeepTutor para reescrever, expandir ou encurtar. O agente de edição pode fundamentar a alteração numa base de conhecimento ou evidência web, mantém um rasto das suas chamadas de ferramentas e mostra cada alteração como um diff aceitar/rejeitar — pelo que nada aterra até que aprove.

📖 Book (Livro) — Livros Vivos dos Seus Materiais

Book converte fontes selecionadas num livro vivo interativo — não um PDF estático, mas um ambiente de leitura construído a partir de blocos tipados. Um livro pode começar a partir de bases de conhecimento, notebooks, bancos de perguntas ou histórico de chat; o fluxo de criação propõe uma estrutura de capítulos antes de o conteúdo ser gerado, para que os utilizadores possam rever a forma em vez de aceitar uma saída cega de disparo único.

   

Cada capítulo compila em blocos tipados — texto, callouts, quizzes, cartões flash, linhas do tempo, código, figuras, HTML interativo, animações, gráficos de conceitos, mergulhos profundos e notas de utilizador — e cada página tem o seu próprio Page Chat. Os blocos são editáveis: inserir, mover, regenerar, reescrever um corpo, ou mudar um tipo sem refazer o capítulo. Páginas visitadas, marcadores e tentativas de quiz acumulam-se numa pontuação de conclusão e capítulos fracos; qualquer livro exporta para Markdown. Uma compilação longa pausa e retoma; deeptutor book health e refresh-fingerprints assinalam conhecimento de origem que divergiu.

📚 Centro de Conhecimento — Bibliotecas RAG Multi-Motor

As bases de conhecimento são as coleções de documentos por trás do RAG — fundamentam os turnos do Chat, edições do Co-Writer, geração do Book e conversas do Partner. O que é distintivo é uma escolha de motores de recuperação: LlamaIndex (o padrão, vetor local + BM25), PageIndex (recuperação de raciocínio com citações ao nível da página, alojado ou OSS auto-hospedado), GraphRAG e LightRAG (recuperação de grafo de conhecimento), LightRAG Server (recuperação delegada a uma instância externa de LightRAG conectada via HTTP), Tencent IMA (uma biblioteca que cura no IMA — pesquisada, navegada e escrita de volta através da sua OpenAPI), MarginNote 4 (os seus dados de estudo MN4 — documentos, excertos, cartões de mapa mental e as ligações entre eles — enviados pelo Add-on da aplicação e navegados com ferramentas dedicadas), ou um vault Obsidian vinculado que o tutor lê e escreve no lugar. Cada KB está vinculada a um motor.

Ao criar uma KB, pode criar nova (carregar documentos e construir um índice novo) ou vincular existente (reutilizar um índice construído noutro lugar, ler no lugar sem reindexação). Uma KB também pode rastrear fontes GitHub — um repositório, branch e glob cujo Markdown é obtido e ressincronizado a pedido, para que a documentação que segue se mantenha atual sem reenvio. A reindexação escreve um novo diretório plano version-N e mantém os anteriores, pelo que um índice funcional nunca é destruído a meio de uma reconstrução. Um único documento pode ser removido mesmo de uma base em estado de erro — descartando um ficheiro que falhou a análise sem uma eliminação e reconstrução completas. A análise de documentos — Somente Texto, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM ou LiteParse — é escolhida em Settings → Knowledge Base, com downloads de modelos locais desativados por predefinição. O Docling também pode correr em modo remoto contra um servidor Docling Serve (sem necessidade de instalação local nem de modelos), configurado através de Settings → Document Parsing (mode=remote, um URL base do servidor e uma chave API opcional) ou das variáveis de ambiente DOCLING_MODE / DOCLING_API_BASE_URL / DOCLING_API_TOKEN. O Tika é apenas remoto e aponta para um servidor Apache Tika (TIKA_SERVER_URL). A CLI espelha o ciclo de vida com deeptutor kb list, info, create, add, search, set-default e delete.

🌐 Espaço de Aprendizado — Skills, Personas e Contexto Reutilizável

O Espaço de Aprendizado é a camada de biblioteca e personalização — onde vivem as coisas que persistem. Conversas e Materiais contém o seu histórico de chat, notebooks — agora com a sua própria consola, com registos que se movem ou copiam entre notebooks e uma exportação em Markdown — e um banco de questões (cada pergunta guardada mantém a sua resposta, a resposta de referência e uma explicação). Personalização contém caminhos de domínio, personas (predefinições de comportamento como par, assistente de pesquisa, professor), skills (playbooks SKILL.md que o modelo lê a pedido), Serviços MCP — uma loja curada de servidores MCP alojados que instala para si mesmo com um clique, além de qualquer servidor remoto que configure por URL — e Aplicações CLI, ferramentas de linha de comandos do catálogo CLI-Anything que o agente de chat chama diretamente, com o guia de utilização próprio de cada aplicação carregado a pedido. Tudo aqui pode ser reutilizado a partir do Chat, Partners, Co-Writer e Book.

Não tem de escrever cada skill você mesmo — Importar do EduHub navega no catálogo da comunidade e descarrega uma skill diretamente para a sua biblioteca através de uma porta de segurança (veja Ecossistema).

🧠 Memória — Personalização Inspecionável

A Memória é um sistema de três camadas suportado por ficheiros que pode ler, curar e auditar — deliberadamente não um armazém de vetores oculto. L1 é o espelho do espaço de trabalho mais um rasto de eventos append-only (trace/<surface>/<date>.jsonl); L2 são factos curados por superfície (L2/<surface>.md); L3 é a síntese entre superfícies (L3/<profile|recent|scope|preferences>.md). Como L2 cita L1 e L3 cita L2, nada no seu perfil é incontabilizável.

O Memory Graph mostra toda a pirâmide — síntese L3 no centro, L2 no anel do meio, rastreamentos L1 no exterior — para que possa rastrear qualquer afirmação sintetizada até ao evento bruto exato que lhe deu origem. A memória é rastreada nas superfícies chat, notebook, quiz, kb, book, partner e cowriter; os orçamentos de Atualização / Auditoria / Deduplicação do consolidador são ajustados em Settings → Memory.

⚙️ Configurações — Um Plano de Controlo

Configurações é o plano de controlo operacional, com uma faixa de estado em tempo real (saúde do backend e memória residente em toda a árvore de processos) e um cartão por área: Aparência (tema, idioma da UI e de saída do modelo, estilo de blocos de código), Rede (base de API, portas, CORS), Modelos (LLM, Embedding, Search, Text-to-Speech, Speech-to-Text, Geração de Imagem, Geração de Vídeo), Base de Conhecimento (motor de análise de documentos), Chat (ferramentas, parâmetros por capacidade, limites de anexos), Partners e Agentes (os subagentes que pode consultar a partir de um turno) e Memória (os orçamentos do consolidador).

A maioria das secções usa um fluxo de rascunho e aplicação, para que possa testar um provedor antes de o confirmar. Também pode simplesmente pedir no Chat: o assistente lê a configuração atual, aplica uma alteração e diz se é necessário reiniciar ou reindexar — testando um novo modelo antes de o confirmar, para que nunca possa mudar-se sozinho para algo inacessível. As chaves API nunca passam pelo modelo, que em vez disso abre o formulário correspondente para si. Quatro temas incluídos — Default, Cream, Dark e Glass. Os ficheiros .env da raiz do projeto são intencionalmente ignorados; a configuração de runtime vive sob data/user/settings/*.json a menos que DEEPTUTOR_HOME ou deeptutor start --home aponte a aplicação para outro lugar.

OpenAI Codex OAuth (experimental). Escolher OpenAI Codex em Models → LLM substitui os campos de chave API por um login no navegador que corre contra o seu próprio plano ChatGPT, pelo que não é necessária nenhuma OPENAI_API_KEY. Os tokens vivem apenas em data/system/user-secrets/<owner>/private/openai-codex/ — na implementação multi-contentor com Compose, fora de qualquer árvore que o sandbox de execução possa alcançar — e o DeepTutor nunca lê nem modifica o seu login CLI ~/.codex. A lista de modelos vem do catálogo ao vivo dessa conta; iniciar sessão publica o perfil mas só se torna o modelo ativo quando ainda não há nenhum LLM configurado, pelo que nunca redireciona uma implementação sem o seu conhecimento. Como um token autoriza o plano de uma pessoa, o perfil não é partilhável através de concessões de utilizador — cada conta inicia sessão por si própria, incluindo utilizadores comuns: o seu cartão está em Models → LLM, e os modelos, o catálogo e o logout resultantes permanecem privados dessa conta, e o navegador tem de alcançar a máquina que executa o backend (num servidor remoto, execute deeptutor provider login openai-codex lá em vez disso). Erros de quota e falhas de catálogo são reportados tal como ocorrem e nunca recorrem a um provedor pago. Este caminho de compatibilidade é experimental: a interface upstream pode mudar.

As implementações locais predefinidas com Docker e Podman usam redes loopback separadas e precisam de uma ponte temporária durante o início de sessão. Siga o guia da ponte OAuth temporária local do Codex para os comandos exatos de Docker, Compose, Podman e desmontagem.

Para uma implementação remota, o localhost do navegador e o localhost do servidor são máquinas diferentes, pelo que um proxy inverso comum sozinho não consegue transportar o callback localhost do navegador até ao servidor. Use um túnel SSH como ponte de callback. O túnel alcança a porta Web já publicada; o Next.js reencaminha apenas o caminho exato de callback para o broker de callback público, e o broker valida state antes de encaminhar para a operação OAuth original. O listener de callback permanece no loopback do backend, as portas 1455 e 1457 não são publicadas, e este caminho suporta a rede bridge predefinida do Docker.

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

Se o DeepTutor reportar a porta de callback de reserva 1457, use:

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

Execute apenas o comando que corresponde à porta de callback real; nunca execute ambos. 3782 é apenas a porta Web de exemplo: é a porta de frontend/contentor configurada, reportada como callback_forward_port. Esse valor não garante que a mesma porta esteja à escuta no 127.0.0.1 do host SSH. Se o Docker ou o Podman publicarem uma porta de host diferente, ou um proxy inverso escutar numa porta diferente, substitua apenas a porta de destino do lado direito (3782 acima) pela porta Web que realmente está à escuta no 127.0.0.1 do host SSH; mantenha a porta de callback do lado esquerdo como 1455 ou 1457. <server-host> é o host SSH cujo loopback possui essa porta à escuta. Se o URL do navegador nomear um proxy inverso ou balanceador de carga, substitua-o pelo host frontend SSH correto.

A CLI imprime o comando do túnel e depois tenta imediatamente abrir o navegador. Numa implementação remota, mantenha a página de autorização aberta sem a concluir, estabeleça o túnel impresso noutro terminal, e só depois continue a autorização.

A deteção de topologia remota tem um limite de localhost. Se o próprio Web for alcançado através de um encaminhamento localhost SSH ou de IDE, o navegador não consegue saber que o servidor é remoto. Para a operação Web atual, deixe a sua página de autorização por concluir, leia redirect_uri no URL de autorização dessa operação para identificar a porta de callback 1455 ou 1457, e crie o segundo túnel a partir dessa porta local para a porta Web real. Em alternativa, cancele essa operação Web e inicie uma nova com a CLI; a saída da CLI pertence à nova operação e não deve ser usada para a operação Web existente. Erros de quota e falhas de catálogo são reportados tal como ocorrem e nunca recorrem a um provedor pago. Este caminho de compatibilidade é experimental: a interface upstream pode mudar.

👥 Multi-Utilizador — Implementações Partilhadas · autenticação opcional, espaços de trabalho isolados por utilizador

A autenticação está desativada por predefinição — o DeepTutor corre em modo de utilizador único. Ative-a e uma árvore data/ aloja um espaço de trabalho de administrador, espaços de trabalho por utilizador isolados e espaços de trabalho de partners lado a lado:

data/
├── user/                    # Espaço de trabalho de administrador + configurações globais
├── users/<uid>/             # Âmbito por utilizador: histórico de chat, memória, notebooks, KBs
├── partners/<id>/workspace/ # Âmbito de partner (utilizador sintético)
├── cli-apps/                # Aplicações CLI instaladas, montadas em leitura apenas no sandbox
└── system/                  # auth · grants · audit · user-secrets/<owner> (tokens OAuth)

O primeiro utilizador registado torna-se administrador e possui catálogos de modelos, credenciais de provedores, bases de conhecimento partilhadas, skills e concessões por utilizador. Os restantes obtêm um espaço de trabalho isolado e uma página de Settings editada — modelos, KBs e skills atribuídos pelo administrador aparecem como opções com âmbito somente leitura, nunca como chaves API brutas.

Ativar: ligue a autenticação em data/user/settings/auth.json, reinicie deeptutor start, registe o primeiro administrador em /register, depois adicione utilizadores em /admin/users e atribua modelos, KBs, skills, Partners, política de ferramentas/MCP/aplicações CLI e acesso de execução de código através de concessões.

O PocketBase continua a ser uma integração de utilizador único — mantenha integrations.pocketbase_url em branco para implementações multi-utilizador a menos que tenha ligado um armazém de utilizadores externo.

⌨️ DeepTutor CLI — Interface Nativa de Agentes

Um binário deeptutor, duas formas de entrada: um REPL interativo para pessoas que vivem no terminal, e JSON estruturado para outros agentes que conduzem o DeepTutor como uma ferramenta. As mesmas capacidades, ferramentas e bases de conhecimento de qualquer forma.

Conduzir você mesmo

deeptutor chat abre um REPL interativo; deeptutor run <capability> "<message>" dispara um único turno e sai. Ambos usam os mesmos flags --capability, --tool, --kb e --config.

deeptutor chat                                              # REPL interativo
deeptutor chat --capability deep_solve --kb my-kb --tool rag
deeptutor run chat "Explain the Fourier transform" --tool rag --kb textbook
deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard

Tudo o que a aplicação Web faz também está aqui — bases de conhecimento (kb), sessões (session), partners (partner), skills (skill), notebooks, memória e configuração. Lista completa abaixo.

Deixar um agente conduzir

O DeepTutor foi construído para ser operado por outro agente. Adicione --format json a qualquer run e cada turno transmite NDJSON — um evento por linha (content, tool_call, tool_result, done, …), cada linha marcada com o seu session_id. As execuções são seguras sem TTY: uma pausa ask_user sem TTY resolve-se automaticamente com uma resposta vazia em vez de bloquear.

# Disparo único, legível por máquina
deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json

# Encadear turnos numa sessão com estado — capturar o id, reutilizá-lo
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

O repositório inclui um SKILL.md raiz — um documento de transferência de ~150 linhas que ensina qualquer LLM com uso de ferramentas toda a superfície numa leitura. Passe-o ao Claude Code, Codex ou OpenCode (eles pegam no SKILL.md automaticamente), ou envolva deeptutor run como uma ferramenta num loop LangChain / AutoGen. Receitas completas: Agent Handoff.

Referência de comandos

Comando	Descrição
deeptutor init	Criar ou atualizar data/user/settings para o espaço de trabalho atual
deeptutor doctor [--online]	Verificar se o espaço de trabalho está pronto para iniciar uma sessão; --online também sonda o provedor de modelo configurado, --format json imprime o relatório
deeptutor start [--home PATH] [--dev]	Lançar backend + frontend juntos
deeptutor serve [--port PORT]	Iniciar apenas o backend FastAPI
deeptutor run <capability> <message>	Executar um turno de capacidade único (chat, deep_solve, deep_question, deep_research, visualize, math_animator, mastery_path); adicionar --format json para saída NDJSON
deeptutor chat	REPL interativo com controlos de capacidade, ferramenta, KB, notebook e histórico
deeptutor partner list/create/start/stop	Gerir partners ligados por IM
deeptutor kb list/info/create/add/search/set-default/delete	Gerir bases de conhecimento LlamaIndex
deeptutor skill search/install/list/remove/login/logout/publish/update	Gerir habilidades, instalar de hubs e publicar as suas (eduhub:<slug> por padrão, veja Ecossistema)
deeptutor memory show/clear	Inspecionar documentos de memória L2/L3 ou limpar memória L1/toda
deeptutor session list/show/open/rename/delete	Gerir sessões partilhadas
deeptutor notebook list/create/show/add-md/replace-md/remove-record	Gerir notebooks a partir de ficheiros Markdown
deeptutor book list/health/refresh-fingerprints	Inspecionar livros e atualizar impressões digitais de fontes
deeptutor plugin list/info	Inspecionar ferramentas e capacidades registadas
deeptutor config show	Imprimir resumo de configuração
deeptutor provider login <provider>	Autenticação de provedor (openai-codex login OAuth; github-copilot valida uma sessão de autenticação Copilot existente; codebuddy valida a autenticação do SDK CodeBuddy e inicia o login quando necessário)

Distribuição de apenas CLI

O pacote de apenas CLI encontra-se em packaging/deeptutor-cli. Neste checkout, instale-o a partir de fonte:

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

Ainda não está publicado no PyPI, por isso a secção principal de Começar mantém o caminho de instalação a partir de fonte.

🧩 Ecossistema — EduHub e a Comunidade de Skills

As skills do DeepTutor usam o formato aberto Agent-Skills — uma pasta com um playbook SKILL.md (frontmatter YAML + Markdown) e ficheiros de referência opcionais. Nada nisto é específico do DeepTutor, por isso qualquer registo que fale o formato torna-se uma fonte para a sua biblioteca. O DeepTutor inclui o EduHub — o nosso próprio registo de skills focado em educação — como hub padrão.

EduHub — o ecossistema de habilidades do DeepTutor

EduHub é o hub da comunidade que o DeepTutor lançou para partilhar skills de agentes orientadas para o ensino — tutores socráticos, construtores de cartões flash, feedback de redações, planos de exames, explicadores de conceitos e muito mais. Está integrado no DeepTutor, por isso não há nada a configurar: um slug simples ou um prefixo eduhub: resolve para ele.

Encontrar e instalar — no navegador, abra Espaço de Aprendizado → Skills → Importar do EduHub para navegar no catálogo e descarregar uma skill diretamente para a sua biblioteca. Do terminal:

deeptutor skill search "socratic tutor"               # pesquisar EduHub (o hub padrão)
deeptutor skill install socratic-tutor                # buscar → verificar → registar
deeptutor skill install eduhub:socratic-tutor@1.2.0   # fixar um hub e uma versão
deeptutor skill list                                  # skills locais com a sua proveniência de hub

Publicar a sua própria — empacote um SKILL.md e partilhe-o de volta com a comunidade:

deeptutor skill login                                 # login no navegador para o EduHub
deeptutor skill publish ./my-skill                    # interativo: escolher uma faixa + etiquetas, depois carregar
deeptutor skill update                                # reverter ou lançar uma nova versão

O EduHub também é um registo independente compatível com ClawHub, por isso agentes que não são o DeepTutor (Claude Code, Codex, …) podem usá-lo diretamente através da CLI eduhub — npx eduhub install socratic-tutor.

A porta de segurança de importação

Seja qual for a fonte, cada importação passa pela mesma porta de segurança antes de qualquer coisa tocar no seu espaço de trabalho:

• o veredicto de segurança do registo é verificado primeiro — os pacotes sinalizados são recusados a menos que passe --allow-unverified;
• os arquivos são extraídos defensivamente (proteções zip-slip / zip-bomb) atrás de uma lista branca de sufixos de texto/script, para que binários nunca aterrem no espaço de trabalho;
• o frontmatter é normalizado para o esquema do DeepTutor e always: é removido, por isso uma skill descarregada nunca pode forçar-se em cada prompt do sistema;
• a proveniência — hub, versão, veredicto e hora de instalação — é escrita em .hub-lock.json para auditorias e atualizações.

Em implementações multi-utilizador, instalar é exclusivo do administrador: uma nova skill aterra no catálogo do administrador e permanece invisível para outros utilizadores até que uma concessão a atribua, para que um administrador possa verificá-la antes de a implementar.

Também compatível com ClawHub

Como o DeepTutor fala o formato aberto Agent-Skills, o ClawHub também funciona como fonte de primeira classe — está integrado juntamente com o EduHub. Escolha-o com o prefixo de hub:

deeptutor skill search "git release notes" --hub clawhub
deeptutor skill install clawhub:git-release-notes@1.0.1

Adicione mais registos em settings/skill_hubs.json: uma entrada type: "clawhub" aponta para qualquer API HTTP compatível (EduHub e ClawHub falam ambos), type: "command" envolve qualquer CLI de busca que um registo forneça, e "default" escolhe o hub usado para slugs simples. Todos eles alimentam a mesma porta de importação.

🤝 Parceiros de Código Aberto

Usando o código: DEEPTUTOR20 — obtenha $20 de desconto na sua primeira subscrição PageIndex!

🌐 Comunidade

📮 Contacto

O DeepTutor é um projeto de código aberto liderado por Bingxi Zhao dentro do Grupo HKUDS, e itera numa forma totalmente de código aberto, construído em conjunto com a comunidade. Até agora, NÃO temos produtos online pagos de qualquer forma. Sinta-se à vontade para contactar em bingxizhao39@gmail.com para discussões, ideias ou colaboração.

🙏 Agradecimentos

Um agradecimento sincero a Chao Huang, diretor do Data Intelligence Lab @ HKU, e aos nossos colegas do HKUDS pelo seu caloroso apoio — especialmente Jiahao Zhang, Zirui Guo e Xubin Ren. Também somos profundamente gratos à comunidade de código aberto: as suas estrelas, issues, pull requests e discussões moldam o DeepTutor todos os dias.

O DeepTutor também assenta nos ombros de projetos de código aberto excepcionais que nos deram tanto ferramentas como inspiração:

Projeto	Papel / Inspiração
LlamaIndex	Espinha dorsal da pipeline RAG e indexação de documentos
nanobot	Motor de agente ultraligeiro que alimentou o TutorBot original (HKUDS)
LightRAG	RAG Simples e Rápido (HKUDS)
AutoAgent	Framework de Agentes Sem Código (HKUDS)
AI-Researcher	Pipeline de investigação automatizada (HKUDS)
OpenClaw	Gateway aberto de agentes e ecossistema de skills por trás do ClawHub
Codex	CLI de programação nativa de agentes que inspirou o nosso fluxo de trabalho CLI
Claude Code	CLI de programação agêntica que inspirou o loop de agente do DeepTutor
ManimCat	Geração de animações matemáticas impulsionada por IA para o Math Animator

🗺️ Roadmap & Contribuir

Queremos que o DeepTutor continue a iterar e a melhorar — e, em última análise, a tornar-se um presente que devolvemos à comunidade de código aberto. O nosso roadmap é atualizado continuamente; vote em itens lá ou proponha novos. Se quiser contribuir, veja o Guia de Contribuição para a estratégia de branches, padrões de código e como começar.

Esperamos que o DeepTutor se torne um presente para a comunidade. 🎁

Licenciado sob Apache License 2.0.