1 Introdução & Edições

DeepCerebra Coder é um assistente de codificação agêntico. Diferente de um copilot de preenchimento automático simples, ele planeja, escreve, refatora, executa comandos, chama ferramentas e itera em seu projeto inteiro — com você revisando e aprovando as alterações que ele propõe.

Três maneiras de usá-lo

Este guia foca no aplicativo web em deepcerebra.ai; o aplicativo desktop espelha os mesmos painéis e fluxos de trabalho.

2 Primeiros Passos & Conta

Navegadores suportados

Use uma versão atual do Chrome, Edge ou Brave para a experiência completa — a abertura de uma pasta local depende da API de Acesso ao Sistema de Arquivos do Chromium. Firefox e Safari funcionam para chat e para projetos baseados em Git, mas não podem abrir uma pasta local diretamente.

Criar uma conta

1. Clique em Começar na página inicial.
2. Preencha seu nome de exibição opcional, e-mail, país e data de nascimento (você deve ter pelo menos 18 anos).
3. Escolha seu idioma de interface e uma senha de pelo menos 12 caracteres.
4. Leia o aviso de acordo e confirme. A criação de uma conta significa que você concorda com os Termos de Serviço, Declaração de Privacidade, Descrição dos Serviços e DPA Global.
5. Clique em Criar conta, depois verifique seu e-mail se solicitado e faça login.

Redefinir sua senha

1. Na página de login, clique em Esqueceu a senha?
2. Digite seu e-mail e abra o link de redefinição enviado para sua caixa de entrada.
3. Defina uma nova senha (mínimo de 12 caracteres).

3 O Espaço de Trabalho em Destaque

Após fazer login, você chega ao ambiente de trabalho, que organiza todos os painéis em uma única tela:

• Explorador (esquerda) — a árvore de arquivos para o projeto aberto, com um botão de atualizar e fechar.
• Editor (centro) — conteúdo do arquivo com destaque de sintaxe e uma visão geral do minimapa; diferenças inline aparecem aqui quando o agente propõe alterações.
• Terminal (abaixo do editor, ativar/desativar) — execute comandos e leia a saída.
• Chat (direita) — a conversa com o agente; este é o painel principal, que preenche o espaço.

Arraste o divisor entre o editor e o chat para reequilibrar o layout, e arraste o divisor horizontal para redimensionar o terminal. A barra lateral esquerda também navega para Espaço de Trabalho, Extensões, Chaves API, Faturamento e Feedback.

4 Abrindo um Projeto

4.1 Abrir uma pasta local

1. No Explorador, clique em Abrir pasta do projeto.
2. Escolha uma pasta e conceda permissão ao navegador para lê-la.
3. Os arquivos são lidos para o espaço de trabalho criptografado no navegador — nada é enviado. Você verá uma contagem em tempo real e um resumo final (contagem de arquivos · tamanho, mais quaisquer arquivos ignorados ou truncados).

4.2 Abrir do Git (GitHub / GitLab)

1. Clique em Abrir do Git no Explorador.
2. Escolha a aba GitHub ou GitLab e cole um token de acesso pessoal. Para GitHub, use o escopo repo (clássico) ou um token de granularidade fina com Contents + Pull requests; para GitLab, use o escopo api. Seu token é armazenado no servidor — apenas o conteúdo dos arquivos é puxado para o navegador.
3. Digite o repositório como owner/name (filtre a lista para encontrar o seu), depois escolha uma branch.
4. Opcionalmente, marque Criar uma nova branch de trabalho (por exemplo, dcc/my-feature) para manter seu trabalho isolado da branch padrão.
5. Opcionalmente, habilite o webhook de push para que o Explorador atualize instantaneamente quando colegas de equipe fizerem push (requer uma URL de gateway pública).
6. Clique em Abrir repositório.

4.3 Atualizar, trocar e fechar

• Atualizar (↻ no cabeçalho do Explorador) re-escaneia a pasta ou puxa o mais recente do Git.
• Abrir outra pasta ou Abrir do Git a partir dos botões abaixo da árvore.
• Fechar projeto (ícone de lixeira) apaga o espaço de trabalho no navegador.

4.4 Sessões de chat com escopo de pasta

O histórico do chat está vinculado ao projeto aberto. A troca de pastas inicia automaticamente uma nova sessão e carrega as sessões anteriores dessa pasta, reabrindo a mais recente para que você possa continuar de onde parou.

4.5 Pastas operacionais

Pastas que DeepCerebra usa internamente — .deepcerebra, .sessions — aparecem na árvore, mas estão colapsadas por padrão para não poluir seu código-fonte.

5 Trabalhando com Arquivos

• Clique em um arquivo no Explorador para abri-lo no editor; o minimapa ajuda você a navegar por arquivos longos.
• Arraste um arquivo do Explorador para o prompt do chat para anexá-lo como contexto explícito para sua próxima mensagem.
• Quando o agente propõe edições, o editor mostra uma diferença inline para o arquivo selecionado.

6 Conversando com o Agente

Escreva uma solicitação

Descreva o que você deseja em linguagem simples — faça uma pergunta, solicite um recurso ou aponte um bug. Seja específico sobre arquivos, frameworks e restrições para obter o melhor resultado. Anexe arquivos relevantes arrastando-os para o prompt.

Leia as respostas, estilo Cursor

As respostas são organizadas como no Cursor: o raciocínio do agente é separado do entregável. Cada bloco de resposta tem um ícone de cópia no canto superior direito para que você possa copiar um relatório finalizado, um documento ou um comando que você deve executar.

Direcionar ou parar uma execução

• Use Parar para interromper uma execução que está indo na direção errada, depois refine seu prompt.
• Dê dicas (por exemplo, "use lxml em vez de html.parser") para tirar o agente de um loop.

7 Os Quatro Modos de Chat

Escolha um modo no seletor de modo ao lado do prompt. Cada um ajusta o quanto o agente planeja e com que liberdade ele edita:

8 Revisando & Aplicando Alterações

Quando o agente propõe alterações de arquivo, um painel de Alterações Propostas aparece acima da entrada do chat, listando cada arquivo tocado com contagens de linhas adicionadas (+) e removidas (−).

• Clique em uma linha de arquivo para abrir sua diferença inline no editor.
• Aplicar ou Rejeitar um único arquivo, ou usar Aplicar todos / Rejeitar todos.
• As alterações aplicadas são marcadas como applied (e · disk quando escritas em uma pasta real).
• Se não houver uma pasta gravável, um selo de somente espaço de trabalho indica que as alterações se aplicam ao espaço de trabalho no navegador.

9 Terminal Integrado

Alterne o terminal abaixo do editor para executar builds, testes e scripts. Com sua autorização, o agente pode executar comandos e ler sua saída para verificar seu trabalho; comandos de longa duração transmitem a saída para que você possa acompanhar o progresso. Feche o terminal pelo cabeçalho quando não precisar dele.

10 Modo Plano & Execução

Para objetivos maiores, use o modo Plano (ou peça ao agente para planejar primeiro). O planejador escaneia seu projeto, decompõe o objetivo em tarefas cientes de dependências e atribui cada uma ao especialista certo (arquiteto, codificador, testador, documentação).

• Revise & edite o plano — adicione, remova ou modifique tarefas antes da execução.
• Execute camada por camada — tarefas independentes são executadas juntas; o planejador pode replanejar se uma tarefa falhar.
• Pause, retome ou aborte a execução a qualquer momento.

11 Escolhendo Modelos & Auto

Abra o seletor de modelo ao lado do prompt. As opções são agrupadas como:

• Auto — deixe DeepCerebra escolher o melhor modelo disponível (recomendado).
• Local (sua GPU) — modelos servidos da sua própria máquina (veja §13).
• Gateways de plataforma — modelos hospedados, agrupados por gateway e depois por fornecedor (por exemplo, Anthropic, OpenAI, Google).

Como funciona a seleção automática

No modo Auto, DeepCerebra usa roteamento adaptativo em camadas: tarefas simples vão para um modelo rápido e econômico, enquanto trabalhos complexos ou com muita necessidade de planejamento (por exemplo, modo Plano) são roteados para um modelo mais forte. Isso equilibra custo e qualidade automaticamente, então você raramente precisa escolher manualmente.

12 Traga Sua Própria Chave (BYOK)

Você pode rotear solicitações através de sua própria conta de provedor em vez de usar o consumo medido da plataforma.

1. Abra Chaves API na barra lateral.
2. Em Traga Sua Própria Chave, escolha um provedor (por exemplo, ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY).
3. Cole o valor da chave e clique em Salvar. As chaves são criptografadas em repouso e nunca são retornadas ao navegador — apenas uma prévia mascarada é mostrada.

Modelos da plataforma (DeepCerebra) não precisam de chave. Remova uma chave a qualquer momento com Remover.

13 Máquina Local: Modelos GPU & Console (DCC Bridge)

O DCC Bridge conecta seu próprio computador ao aplicativo web através de um pequeno dcc-bridge conector, desbloqueando duas capacidades de uma vez:

• Modelos GPU locais — modelos servidos por Ollama ou LM Studio em sua máquina aparecem no seletor de modelo em Local (sua GPU).
• Console / terminal em sua máquina — o terminal web e o agente podem executar comandos reais em seu computador, incluindo ferramentas CLI que você já configurou (Railway, AWS CLI, OVH CLI, gh, docker, kubectl, WSL, …) com suas credenciais existentes.

O conector faz chamadas externas através de um WebSocket autenticado — sem necessidade de portas de entrada, e funciona atrás de NAT e firewalls. Ele roda em Windows, macOS e Linux (Python 3.10+).

13.1 Emparelhe seu computador

1. Clique no ícone do laptop na barra de atividades esquerda — Máquina Local (GPU + Console). (O mesmo painel abre do rodapé do seletor de modelo via Gerenciar GPU local….)
2. Certifique-se de que o botão Execução local esteja ativado, nomeie o dispositivo e clique em Adicionar este computador. Copie o token de emparelhamento único (dcc_brg_…) e o comando do conector pronto para colar — o token é mostrado exatamente uma vez.

13.2 Instalar & executar o conector

pip install git+https://github.com/mohammadkhair7/DeepCerebra-connector

# then run the command copied from the pairing card, e.g.:
python -m dcc_bridge --gateway wss://deepcerebra.ai --token dcc_brg_xxxxx

• Use o mesmo domínio que você usa no navegador como gateway (wss://deepcerebra.ai ou wss://deepcerebra.io) — o cartão de emparelhamento preenche o correto. Os dois sites são implantações separadas com contas e tokens separados.
• Para modelos GPU, mantenha Ollama em execução, ou habilite o servidor local do LM Studio (porta padrão 1234) com um modelo carregado.
• Dispositivos emparelhados mostram status online/offline, contagem de modelos e escopo de execução; você pode Revogar um dispositivo a qualquer momento.

13.3 Use seu console a partir do aplicativo web

Por padrão, os comandos são confinados a uma pasta de espaço de trabalho dedicada (~/DeepCerebra). Para trabalhar em suas pastas de projeto reais com seus CLIs pré-configurados, conceda-lhes explicitamente ao iniciar o conector:

# grant one or more real folders (repeatable)
python -m dcc_bridge --gateway wss://deepcerebra.ai --token dcc_brg_xxxxx --host-dir "F:\MyProjects"

# or the whole machine (prints a warning; prefer --host-dir)
python -m dcc_bridge ... --allow-any-dir

Em seguida, abra o painel Terminal, clique no popover Alvo de execução (ícone do laptop), escolha Meu computador, e selecione um diretório de trabalho. Tanto seus comandos digitados quanto os comandos de build/teste do agente serão então executados em sua máquina.

14 Fluxo de Trabalho de Colaboração Git

Com um projeto baseado em Git aberto, uma barra de branch aparece no Explorador mostrando sua branch atual e duas ações:

• Fazer check-in (commit) — revise a contagem de arquivos alterados, escreva uma mensagem de commit e faça commit para sua branch de trabalho.
• Integrar — abra um pull request da sua branch de trabalho para a branch padrão (por exemplo, main). Você deve estar em uma branch de trabalho, não na branch padrão.

Se o webhook de push estiver habilitado, o Explorador atualiza automaticamente quando colegas de equipe fazem push, mantendo todos sincronizados — a base para o desenvolvimento colaborativo em equipe através do DeepCerebra.

15 Servidores MCP

Estenda o agente com ferramentas e dados externos via Model Context Protocol. Configure servidores em um arquivo .deepcerebra/mcp.json, por exemplo:

{
  "mcpServers": {
    "my-tools": {
      "url": "https://example.com/mcp",
      "disabled": false,
      "allowlist": ["search_issues", "get_pr"],
      "autoApprove": ["create_issue"],
      "auth": { "type": "bearer", "tokenEnv": "MY_TOKEN" }
    }
  }
}

As ferramentas MCP habilitadas ficam disponíveis para o agente automaticamente quando são relevantes para sua solicitação. Locais (stdio) e remotos (http/sse) servidores são ambos suportados.

Segurança integrada

• Negar por padrão — quando um servidor lista uma allowlist, apenas essas ferramentas podem ser executadas.
• Aprovação para ferramentas de alto risco — ferramentas mutáveis (gravar/excluir/implantar/…) exigem aprovação, a menos que você as pré-aprove em autoApprove.
• Limitação de taxa, sanitização de argumentos e saída, e um log de auditoria se aplicam a cada chamada.

Recursos & prompts

Se um servidor expõe recursos MCP ou modelos de prompt, o agente ganha automaticamente ferramentas para usá-los (mcp_list_resources, mcp_read_resource, mcp_list_prompts, mcp_get_prompt).

Autenticação para servidores remotos

Adicione um bloco auth a um servidor remoto. Segredos suportam interpolação ${ENV_VAR}:

// Token bearer estático (literal ou do ambiente)
"auth": { "type": "bearer", "token": "${GITHUB_TOKEN}" }
"auth": { "type": "bearer", "tokenEnv": "GITHUB_TOKEN" }

// Cabeçalho personalizado (por exemplo, chave API)
"auth": { "type": "header", "header": "x-api-key", "value": "${MY_KEY}" }

// Credenciais de cliente OAuth 2.0
"auth": {
  "type": "oauth", "grant": "client_credentials",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "clientId": "${MCP_CLIENT_ID}", "clientSecret": "${MCP_CLIENT_SECRET}",
  "scope": "mcp.read mcp.write"
}

16 Personalizando o Agente: Regras, Habilidades, Hooks, Subagentes & Plugins

Você pode moldar como o agente pensa e age com uma convenção única, baseada em arquivos — o diretório .deepcerebra/ — que funciona de forma idêntica na aplicação desktop, na aplicação web e na API. Na aplicação web, gerencie tudo isso na visualização Agente; no desktop e via API, são arquivos simples que você comita com seu projeto.

Escopos & precedência

A configuração é descoberta a partir de vários escopos; quando o mesmo item existe em mais de um, o de maior precedência vence:

team/org  <  global (~/.deepcerebra)  <  workspace (<repo>/.deepcerebra)
(mais baixo)                                              (mais alto)

• Espaço de trabalho — <repo>/.deepcerebra/…, commitado com o projeto.
• Global — ~/.deepcerebra/…, seus padrões pessoais em todos os projetos.
• Equipe / organização — uma linha de base compartilhada (menor precedência) para que um usuário ou projeto possa sempre substituí-la. No aplicativo web, defina o Escopo de uma regra como Equipe.

Regras (direcionamento)

As regras são instruções persistentes — padrões de codificação, convenções de arquitetura, contexto de domínio — injetadas no prompt do sistema do agente. Elas residem como arquivos Markdown em .deepcerebra/steering/, além do padrão AGENTS.md sempre ativo. O frontmatter controla quando uma regra é carregada:

---
inclusion: fileMatch          # always | fileMatch | auto | manual
globs: "src/**/*.ts"          # or fileMatchPattern
name: api-design
description: REST conventions
---
# Design de API
- Use substantivos de recurso REST, no plural.

• always — a cada turno (o padrão).
• fileMatch — somente quando um arquivo em contexto corresponde a globs.
• auto — quando sua solicitação corresponde ao name/description da regra.
• manual — somente quando você o referencia como #name ou /name.

Um AGENTS.md raiz se aplica a todo o repositório; um AGENTS.md aninhado (por exemplo, services/api/AGENTS.md) se aplica apenas aos arquivos sob essa pasta. No aplicativo web, a visualização Agente → Direcionamento oferece a cada regra um seletor de Escopo (Global / Projeto / Equipe).

Habilidades

Habilidades são playbooks reutilizáveis que o agente carrega sob demanda. Cada habilidade é uma pasta com um SKILL.md em .deepcerebra/skills/:

---
name: deploy-release
description: How to cut and publish a versioned release.
disable-model-invocation: false   # true => manual-only (/skill)
---
# Implantar uma versão
1. Aumentar a versão, construir e testar.
2. Marcar e publicar.

O agente vê um catálogo leve (nome + descrição) e puxa o corpo completo com a ferramenta load_skill quando relevante. Você também pode invocar uma explicitamente com /skill <name>. Defina disable-model-invocation: true para tornar uma habilidade apenas manual.

Hooks

Hooks executam automação em eventos de ciclo de vida. Defina-os como .deepcerebra/hooks/*.hook.json:

{
  "title": "Formatar ao salvar",
  "event": "fileSave",
  "filePattern": ["**/*.ts"],
  "action": { "type": "shell", "command": "npm run lint:fix -- $FILE" },
  "enabled": true
}

Os eventos incluem promptSubmit, preToolUse, postToolUse, fileCreate, fileSave, fileDelete, preTask, postTask, sessionStart, preCompact e agentStop (grafias de Cursor/Claude também são aceitas). Uma ação é shell (executar um comando) ou agentPrompt (perguntar ao agente). Um hook preToolUse pode permitir, negar ou pedir a chamada da ferramenta que ele intercepta.

Subagentes

Subagentes são agentes especialistas que você define e delega. Cada um é um arquivo Markdown em .deepcerebra/agents/ com frontmatter mais um corpo (seu prompt de sistema):

---
name: security-reviewer
description: Audits a diff for security issues; read-only.
model: gpt-5
readonly: true
tools: [read_file, grep_files, list_directory]
background: false
---
Você é um revisor de segurança meticuloso…

O agente principal delega com task (bloqueando), task_async + task_status / task_result (em segundo plano), ou task_parallel (fan-out).

Plugins

Um plugin agrupa regras, habilidades, hooks, subagentes e servidores MCP em um único pacote instalável em .deepcerebra/plugins/<name>/, descrito por um manifesto plugin.json:

{
  "name": "Acme Standards",
  "version": "1.2.0",
  "description": "Acme rules + skills + review agents.",
  "enabled": true
}

O conteúdo do plugin é mesclado com a menor precedência, então suas próprias regras e habilidades sempre substituem as de um plugin. Desabilite um plugin com "enabled": false ou um arquivo marcador .disabled.

17 Estúdio de Fluxo de Trabalho Agêntico & Agentes Orientados a Eventos

O Estúdio de Fluxo de Trabalho é um designer visual para automação multiagente. Você compõe estágios — cada um um agente, uma etapa especialista ou uma primitiva de controle — em um grafo, conecta-os com dependências e executa toda a orquestração no motor com progresso em tempo real por estágio, orçamentos e portões de aprovação humana. Os fluxos de trabalho são salvos como uma definição YAML/JSON portátil que você pode exportar, importar, versionar no Git e executar a partir da API ou CLI.

17.1 Construindo um fluxo de trabalho

• Paleta (esquerda) — arraste tipos de estágio, tipos de agente prontos (pesquisa, geração de código, QA, escritor de documentos, dispositivo médico, consultor de patentes e seus próprios tipos personalizados), habilidades da Biblioteca de Habilidades e ferramentas para a tela.
• Tela (centro) — organize os estágios e desenhe as arestas; uma aresta significa "este estágio depende daquele" e alimenta automaticamente a saída do estágio anterior no prompt do estágio seguinte.
• Inspetor (direita, redimensionável) — configure o estágio selecionado: seu prompt, habilidades, ferramentas, substituição de modelo por estágio, artefato de saída, portão, eventos e parâmetros específicos do tipo.
• Modelos — comece a partir de um projeto integrado (Pipeline de Lançamento, SaaS Starter, Pipeline de Dados com Avaliações, Central de Comunicações com Clientes, Design → Aplicativo Verificado) e personalize-o.
• Gerar — descreva o aplicativo ou processo em linguagem simples e o Construtor de Agentes gera um grafo de fluxo de trabalho completo e validado que você pode revisar, ajustar e executar.

17.2 A biblioteca de estágios

17.3 Agentes orientados a eventos (a malha de agentes)

Cada estágio — independentemente do tipo — pode publicar e assinar eventos tipados no barramento de eventos do espaço de trabalho, para que os agentes coordenem como serviços em uma malha de mensagens, em vez de apenas através do DAG:

• Classes de evento — cada evento carrega uma classe: lifecycle, agent, business, data, system, schedule, chat, external ou alert — filtráveis em assinaturas e replay.
• Modos de assinatura — trigger (o estágio é executado quando um evento correspondente chega; uma execução com estágios estacionados permanece residente como escutando), gate (um portão de máquina aprovado por um evento em vez de um clique humano) e data (o payload é mesclado no contexto do estágio).
• Início por evento — qualquer agente pode ser iniciado por um orquestrador ou outro agente publicando em seu endereço agent.<stage-id>.request.
• Gatilhos de execução — o bloco triggers: de um fluxo de trabalho o arma para iniciar em webhooks de entrada, agendamentos cron, eventos ou chat — mesmo enquanto o Estúdio está fechado.
• Execuções ao vivo — o painel de execução transmite eventos de ciclo de vida via SSE: inícios/conclusões de estágio, portões, alertas e prévias aparecem instantaneamente.
• Log durável & replay — os eventos persistem por espaço de trabalho e podem ser reproduzidos por padrão de tópico e classe para auditoria e depuração.

17.3.1 Enfileiramento de eventos para agentes

Agentes que reagem a eventos podem declarar uma fila nomeada durável para que eventos correspondentes nunca sejam perdidos enquanto o agente está ocupado ou antes de uma execução estar escutando. Em uma assinatura de gatilho, defina queue: <name> — o motor vincula esse tópico a uma fila FIFO no barramento de eventos do espaço de trabalho (persistida em .deepcerebra/workflows/events/queues/). Cada evento correspondente publicado a partir desse ponto é capturado na fila; quando o estágio se torna executável, o motor retira os eventos na ordem do mais antigo para o mais novo e os consome um por um.

• Nada perdido — eventos publicados enquanto o fluxo de trabalho está fechado, enquanto outro estágio está em execução, ou enquanto a execução ainda está aguardando dependências são enfileirados em vez de descartados.
• count por assinatura — exige N eventos enfileirados (ou entregues) antes que a assinatura seja satisfeita (útil quando vários trabalhadores devem reportar).
• Estúdio — no painel de Eventos do Inspetor, defina o campo queue em uma assinatura de gatilho; arme gatilhos ou inicie uma execução para criar a vinculação automaticamente.
• API & ferramentas — GET /api/workflow/queues lista profundidade e vinculações; GET /api/workflow/queues/{name} visualiza eventos pendentes; agentes de chat podem chamar event_queue_status e pop_queued_event.

events:
  subscribe:
    - topic: ticket.created
      mode: trigger
      queue: triage-inbox        # durable FIFO — events wait here for this agent
      map:
        payload.ticket_id: ticket_id

17.3.2 Orquestração de semáforo (proteção de recurso compartilhado)

Um semáforo limita quantas tarefas podem operar simultaneamente em um recurso compartilhado (protegido): um banco de dados sendo gravado, um armazenamento de variáveis globais, um arquivo ou um agente externo com limite de taxa. Anexe um a qualquer estágio com semaphore: — antes que o trabalho do estágio seja executado, o motor adquire uma permissão do semáforo nomeado do espaço de trabalho; a permissão é sempre liberada depois, mesmo que o estágio falhe. permits: 1 o torna um mutex: apenas uma tarefa por vez (em todas as execuções paralelas no espaço de trabalho) executa a etapa crítica; todas as outras tarefas esperam até que o detentor termine.

• Serialização entre execuções — os semáforos têm escopo de espaço de trabalho e são persistidos, então duas execuções de fluxo de trabalho concorrentes não podem corromper o mesmo recurso protegido.
• Esperando, não travando — as tarefas bloqueiam até timeout_s por uma permissão; se o recurso permanecer na capacidade máxima, o estágio falha visivelmente em vez de travar para sempre.
• Segurança contra falhas — cada permissão carrega um ttl_s; se um detentor falhar sem liberar, a permissão expira automaticamente para que o recurso nunca fique em deadlock.
• Observabilidade — o barramento emite semaphore.<name>.waiting, .acquired e .released eventos de sistema; GET /api/workflow/semaphores mostra capacidade, detentores e permissões disponíveis.
• Agentes de chat — as ferramentas acquire_semaphore, release_semaphore e semaphore_status coordenam seções críticas ad-hoc fora de um fluxo de trabalho.

semaphore:
  name: emr-db-writer
  permits: 1          # mutex — one writer at a time
  timeout_s: 300      # fail if still waiting after 5 minutes
  ttl_s: 900          # auto-release crashed holders after 15 minutes

17.3.3 Orquestração de Rendezvous (esperar por todas as condições)

Rendezvous espera até que múltiplas condições de evento sejam todas atendidas antes que a próxima etapa prossiga — o oposto de "o primeiro evento vence". Defina join: all no bloco events: do estágio: cada assinatura de gatilho deve ser satisfeita antes que o estágio seja executado. Combine com count: N por assinatura quando vários agentes (ou vários relatórios de um agente) devem todos fazer check-in — por exemplo, aprovação de design, conclusão de teste e aprovação de segurança antes que um estágio de lançamento seja executado.

• join: any (padrão) — o estágio é executado quando a primeira assinatura de gatilho é satisfeita.
• join: all — rendezvous: cada assinatura de gatilho (cada uma com seu próprio tópico, filtro de classe e count opcional) deve ser satisfeita; somente então o estágio se torna executável.
• Payloads — todos os eventos consumidos são registrados no estágio como trigger_events e expostos a templates como inputs.events (uma lista de objetos de evento com payloads).
• Estúdio — quando um estágio tem duas ou mais assinaturas de gatilho, o Inspetor mostra um seletor Join: any — o primeiro evento vence ou all — rendezvous (esperar por todos); a tela mostra um selo de mesclagem em estágios de rendezvous.

events:
  join: all                    # rendezvous — wait for EVERY subscription below
  subscribe:
    - topic: design.approved
      mode: trigger
    - topic: tests.passed
      mode: trigger
    - topic: security.cleared
      mode: trigger
      count: 1

17.4 A biblioteca de ferramentas do agente

Os estágios escolhem ferramentas do mesmo registro que o agente de chat usa:

• Núcleo — arquivos, git, shell, execução de código, busca de código, automação de navegador, busca web, visão/mídia, geração de imagem.
• Bancos de Dados — consultas SQLite, PostgreSQL, MySQL, MongoDB e Redis, além de create_database, apply_migrations e dump_schema para camadas de dados próprias.
• Comunicações — chamadas telefônicas e SMS (Twilio) e e-mail (SendGrid), com um modo de simulação que registra em uma caixa de saída quando as credenciais estão ausentes — demonstrações nunca enviam mensagens reais por acidente.
• DevOps — docker_build / docker_push, compose up/down, implantações SSH e cloud-CLI (Fly, Render, Railway, Vercel), também seguras para simulação.
• Verificação — detecção de pilha, execução de suíte de testes com taxas de aprovação analisadas, auditorias de dependência e varredura de segredos.
• Motores SciCompute — centenas de métodos científicos e de engenharia (nomeados Class.method) em matemática, processamento de sinais, controles, estatística e muito mais.
• Agência Especializada & MCP — pesquisa de domínio fundamentada mais quaisquer servidores MCP externos que você conectar.

17.5 Execução, portões e saídas

• Validar verifica o grafo (IDs únicos, dependências acíclicas, parâmetros de tipo) antes de você executar.
• Portões humanos pausam a execução depois que o estágio produz seu rascunho, para que você aprove o trabalho real; portões de evento permitem que outro sistema aprove automaticamente.
• Orçamentos limitam os gastos por execução e por estágio.
• Salvar saídas no projeto copia cada artefato gerado por uma execução para o seu projeto aberto.
• Exportar Aplicativo transforma o fluxo de trabalho em um serviço FastAPI autônomo; a API pública /v1 expõe execuções, eventos, gatilhos, modelos e geração para CI e integrações.

18 Preenchimento Preditivo com Tab

O preenchimento preditivo com Tab oferece sugestões de código inline, preenchendo o meio, enquanto você digita no editor — aceite uma sugestão com Tab. É opcional tanto no motor quanto no editor web.

Habilitá-lo

• Motor — defina a flag de ambiente DCC_TAB_COMPLETE=1. O editor chama o endpoint POST /api/complete do motor, que retorna apenas o texto a ser inserido no cursor.
• Editor web — habilite em tempo de build com VITE_TAB_COMPLETE=1, ou em tempo de execução com localStorage.setItem('dcc.tabComplete', '1') (depois recarregue).

Como se comporta

• As sugestões aparecem como texto fantasma; pressione Tab para aceitar, ou continue digitando para descartar.
• As solicitações são "debounced" e canceláveis, então a digitação nunca é bloqueada.
• Quando a flag está desativada, o recurso é totalmente desabilitado e nenhuma solicitação de preenchimento é feita.

19 Uso, Créditos & Faturamento

Abra Faturamento na barra lateral para gerenciar seu plano e uso. O uso de IA é medido em créditos de dólar americano com base nos tokens consumidos pelos modelos subjacentes.

• Gasto do ciclo & crédito pré-pago — acompanhe o uso neste ciclo e qualquer saldo pré-pago.
• Adicionar crédito de excedente — autorize um valor adicional (USD) para continuar usando IA após o esgotamento da franquia incluída; se seu orçamento estiver esgotado, você verá um banner solicitando que adicione crédito.
• Atualizar / mudar de plano — mude de nível a qualquer momento.
• Método de pagamento — adicione ou atualize o cartão registrado (processado por Stripe).
• Cancelar — escolha cancelar no final do período (mantenha o acesso até o final do período) ou cancelar agora (reembolsar o residual reembolsável). Consulte a Política de Cancelamento & Reembolso.

20 Obtendo Sua Chave API de Gateway

Uma chave API de gateway (um token de acesso pessoal) permite que você use a API pública e o CLI do DeepCerebra programaticamente.

1. Faça login e abra Chaves API na barra lateral.
2. Role até Chaves API DeepCerebra.
3. Insira um rótulo (por exemplo, "pipeline CI" ou "CLI do laptop").
4. Selecione escopos — read, chat, code, agent — e uma expiração opcional em dias (em branco = nunca).
5. Clique em Gerar. A chave completa é mostrada apenas uma vez — clique em Copiar e armazene-a com segurança.

Use-o com o CLI ou a API em deepcerebra.ai:

dcc config set endpoint https://deepcerebra.ai
dcc config set api-key <your-key>

# or as a Bearer token
curl -H "Authorization: Bearer <your-key>" https://deepcerebra.ai/v1/...

Você pode renomear ou excluir (revogar) uma chave a qualquer momento; cada chave mostra seu prefixo, escopos, data de criação/expiração e data do último uso.

21 Segurança & Privacidade

• Armazenamento confidencial no navegador — seus arquivos de projeto permanecem no espaço de trabalho criptografado do navegador; apenas o contexto mínimo necessário por solicitação é enviado ao servidor.
• Retenção Zero de Dados (ZDR) — prompts e código roteados para modelos não são retidos além da solicitação e nunca são usados para treinar modelos de base.
• Chaves permanecem no servidor — tokens BYOK e SCM são criptografados em repouso; apenas prévias mascaradas são mostradas.
• Criptografia — TLS em trânsito; dados da conta criptografados em repouso; senhas hashadas irreversivelmente.
• Seu código é seu — você é o proprietário do seu conteúdo e da saída gerada. Consulte a Declaração de Privacidade.

22 Solução de Problemas

"O carregamento de pastas requer um navegador Chromium"

Mude para Chrome, Edge ou Brave, ou use Abrir do Git.

O agente entra em loop no mesmo erro

Clique em Parar, depois reformule com uma dica ou restrição concreta.

Erros de modelo ou solicitação / "orçamento esgotado"

• Verifique sua conexão e se qualquer chave BYOK é válida.
• Mude para Auto para que DeepCerebra roteie para um modelo disponível.
• Se seu orçamento de uso estiver esgotado, abra Faturamento e adicione crédito de excedente ou atualize seu plano.

Modelos locais não aparecem

• Confirme se o conector dcc-bridge está em execução e o dispositivo mostra online.
• Certifique-se de que Ollama esteja em execução, ou que o servidor local do LM Studio esteja habilitado (porta padrão 1234) com um modelo carregado.

Conector: "servidor rejeitou conexão WebSocket: HTTP 401"

• Use o mesmo domínio que você usa no navegador como --gateway (wss://deepcerebra.ai ou wss://deepcerebra.io) — os dois sites são implantações separadas, e um token de um nunca funciona no outro.
• Copie o comando exato do cartão de emparelhamento na página Máquina Local.

Minhas alterações não tiveram efeito

• Certifique-se de ter clicado em Aplicar (não apenas visualizado a diferença) em Alterações Propostas.
• Use o atualizar do Explorador para re-escanear a pasta.

Git: "Você está na branch padrão"

Abra ou crie uma branch de trabalho antes de usar Integrar para abrir um pull request.

Ainda com problemas? Entre em contato com support@deepcerebra.ai.

23 DeepCerebra Discovery — Pergunte aos Seus Dados & Documentos

Discovery é um chatbot investigativo para os seus bancos de dados e documentos. Em vez de responder com uma única consulta, ele funciona como um analista: forma hipóteses, executa uma série de sondas protegidas (SQL, grafo, pesquisa de documentos, verificações de esquema, corroboração web), descarta as explicações que as evidências refutam e sintetiza uma resposta fundamentada — com gráficos e um recibo de custo transparente. Abra-o a partir do ícone de bússola na barra de atividades (/app/discovery).

23.1 Espaços — o seu escopo curado

Um Espaço agrega tudo o que uma linha de questionamento precisa: conexões de banco de dados, coleções de documentos, instruções para o analista e orçamentos. Crie um com + Novo espaço, depois use o painel de configuração à direita para:

• Conectar bancos de dados — SQLite, PostgreSQL, MySQL, SQL Server ou Snowflake. Insira um nome e DSN, clique em Testar para verificar a conectividade (latência e versão do servidor são mostradas), ou importe uma configuração de conexão existente como JSON. As conexões são somente leitura por padrão.
• Adicionar documentos — arraste & solte arquivos (PDF, DOCX, PPTX, Markdown, texto) diretamente no chat, cole uma URL ou aponte para um caminho de pasta no host do motor. Os documentos são divididos em blocos, incorporados e indexados para pesquisa híbrida de vetor + grafo de conhecimento.
• Importar tabelas — cole ou carregue CSV/JSON para consultar instantaneamente sem qualquer banco de dados.
• Ensinar o analista — adicione definições de métricas, regras de negócios e ressalvas, consultas confiáveis aprovadas pelo curador e pares de exemplo pergunta→consulta para que as respostas usem suas definições.

23.2 Fazendo uma pergunta

Digite uma pergunta da mesma forma que faria a um colega — por exemplo "Why did MRI scan volume dip in March?". O painel de investigação transmite todo o processo ao vivo:

• Hipóteses — as explicações candidatas sob investigação, cada uma marcada como suportada, refutada ou inconclusiva à medida que as evidências chegam.
• Sondas — cada consulta que o analista executa, com seu status; o SQL/Cypher gerado é mostrado para total transparência, e cada instrução passa por regras de proteção somente leitura antes da execução.
• Evidências — tabelas de resultados e trechos de documentos, citados por número na resposta final.
• Resposta + gráficos — uma conclusão fundamentada que também nomeia as explicações que foram descartadas, além de gráficos modernos com tema neon compostos a partir das evidências.
• Recibo — tokens, custo por sonda e rodadas, cobrados dos seus AI Credits como qualquer outra execução de agente.

Perguntas de acompanhamento continuam o mesmo tópico, para que o analista mantenha seu contexto.

23.3 Gráficos, relatórios & exportações

Os gráficos são renderizados inline no painel de investigação. Use Exportar para baixar a consulta completa — a resposta, hipóteses, evidências e gráficos — como um relatório HTML autocontido ou um PDF com qualidade de impressão, estilizado com o sistema de design neon.

23.4 Orçamentos & controle de custos

Cada espaço possui orçamentos por consulta: um número máximo de sondas, rodadas de investigação, segundos e USD. O motor para de forma limpa no limite e relata o que encontrou até agora. O custo de cada sonda é detalhado no recibo, para que você sempre saiba onde o gasto foi.

23.5 Automação: API, SDK, Workflow Studio & MCP

• REST API — tudo o que a UI faz está disponível em /v1/discovery/* com um PAT que possui o escopo discovery (crie-o em Conta → Tokens de API). As consultas de streaming usam SSE. Executores externos podem usar apenas o planejamento investigativo através da Thinking API (/v1/think/*, escopo think).
• Python SDK — pip install deepcerebra-discovery, depois DiscoveryClient(base_url, token).ask(space_id, question).
• Workflow Studio — solte o estágio Discovery Ask (discovery.ask) em qualquer fluxo de trabalho para executar uma investigação como uma etapa de pipeline; a resposta, gráficos e recibo fluem para os estágios subsequentes.
• MCP — o motor expõe discovery_ask e discovery_list_spaces como ferramentas MCP, para que clientes MCP externos também possam executar investigações.