1 Introduzione e Edizioni

DeepCerebra Coder è un assistente di codifica agentico. A differenza di un semplice copilot con autocompletamento, pianifica, scrive, rifattorizza, esegue comandi, chiama strumenti e itera su tutto il tuo progetto — con te che rivedi e approvi le modifiche che propone.

Tre modi per usarlo

Questa guida si concentra sull'app web all'indirizzo deepcerebra.ai; l'app desktop rispecchia gli stessi pannelli e flussi di lavoro.

2 Per iniziare e Account

Browser supportati

Utilizza una versione attuale di Chrome, Edge o Brave per un'esperienza completa — l'apertura di una cartella locale si basa sull'API Chromium File System Access. Firefox e Safari funzionano per la chat e per i progetti basati su Git, ma non possono aprire direttamente una cartella locale.

Crea un account

1. Clicca su Inizia sulla pagina di destinazione.
2. Inserisci il tuo nome visualizzato (opzionale), email, paese e data di nascita (devi avere almeno 18 anni).
3. Scegli la tua lingua dell'interfaccia e una password di almeno 12 caratteri.
4. Leggi l'informativa sull'accordo e conferma. La creazione di un account implica l'accettazione dei Termini di Servizio, dell'Informativa sulla Privacy, della Descrizione dei Servizi e del DPA Globale.
5. Clicca su Crea account, quindi verifica la tua email se richiesto, ed effettua l'accesso.

Reimposta la tua password

1. Nella pagina di accesso, clicca su Password dimenticata?
2. Inserisci la tua email e apri il link di reimpostazione inviato alla tua casella di posta.
3. Imposta una nuova password (minimo 12 caratteri).

3 Panoramica dell'Area di Lavoro

Dopo aver effettuato l'accesso, atterrerai nell'ambiente di lavoro, che raggruppa tutti i pannelli in un'unica schermata:

• Esplora risorse (sinistra) — l'albero dei file per il progetto aperto, con un pulsante di aggiornamento e chiusura.
• Editor (centro) — contenuti del file con evidenziazione della sintassi e una panoramica minimap; i diff inline appaiono qui quando l'agente propone modifiche.
• Terminale (sotto l'editor, attiva/disattiva) — esegui comandi e leggi l'output.
• Chat (destra) — la conversazione con l'agente; questo è il pannello principale, che occupa lo spazio.

Trascina il divisore tra l'editor e la chat per riequilibrare il layout, e trascina il divisore orizzontale per ridimensionare il terminale. La barra laterale sinistra naviga anche a Area di Lavoro, Estensioni, Chiavi API, Fatturazione e Feedback.

4 Apertura di un Progetto

4.1 Apri una cartella locale

1. Nell'Esplora risorse, clicca su Apri cartella progetto.
2. Scegli una cartella e concedi al browser il permesso di leggerla.
3. I file vengono letti nell'area di lavoro crittografata nel browser — nulla viene caricato. Vedrai un conteggio in tempo reale e un riepilogo finale (conteggio file · dimensione, più eventuali file saltati o troncati).

4.2 Apri da Git (GitHub / GitLab)

1. Clicca su Apri da Git nell'Esplora risorse.
2. Scegli la scheda GitHub o GitLab e incolla un token di accesso personale. Per GitHub usa lo scope repo (classico) o un token a grana fine con Contents + Pull requests; per GitLab usa lo scope api. Il tuo token è memorizzato sul server — solo i contenuti dei file vengono caricati nel browser.
3. Digita il repository come owner/name (filtra l'elenco per trovare il tuo), quindi scegli un branch.
4. Facoltativamente, seleziona Crea un nuovo branch di lavoro (es. dcc/my-feature) per mantenere il tuo lavoro isolato dal branch predefinito.
5. Facoltativamente, abilita il webhook di push in modo che l'Esplora risorse si aggiorni istantaneamente quando i colleghi effettuano un push (richiede un URL di gateway pubblico).
6. Clicca su Apri repository.

4.3 Aggiorna, cambia e chiudi

• Aggiorna (↻ nell'intestazione dell'Esplora risorse) riesamina la cartella o scarica l'ultima versione da Git.
• Apri un'altra cartella o Apri da Git dai pulsanti sotto l'albero.
• Chiudi progetto (icona cestino) cancella l'area di lavoro nel browser.

4.4 Sessioni di chat con ambito cartella

La cronologia della chat è legata al progetto aperto. Il cambio di cartella avvia automaticamente una nuova sessione e carica le sessioni precedenti di quella cartella, riaprendo la più recente in modo da poter riprendere da dove avevi lasciato.

4.5 Cartelle operative

Le cartelle che DeepCerebra utilizza internamente — .deepcerebra, .sessions — appaiono nell'albero ma sono compresse per impostazione predefinita in modo da non ingombrare il tuo codice sorgente.

5 Lavorare con i File

• Clicca su un file nell'Esplora risorse per aprirlo nell'editor; la minimap ti aiuta a navigare file lunghi.
• Trascina un file dall'Esplora risorse nel prompt della chat per allegarlo come contesto esplicito per il tuo prossimo messaggio.
• Quando l'agente propone modifiche, l'editor mostra un diff inline per il file selezionato.

6 Chattare con l'Agente

Scrivi una richiesta

Descrivi ciò che desideri in linguaggio semplice — fai una domanda, richiedi una funzionalità o segnala un bug. Sii specifico riguardo a file, framework e vincoli per ottenere il miglior risultato. Allega i file pertinenti trascinandoli nel prompt.

Leggi le risposte, stile Cursor

Le risposte sono organizzate come Cursor: il ragionamento dell'agente è separato dal prodotto finale. Ogni blocco di risposta ha un'icona di copia nell'angolo in alto a destra in modo da poter copiare un rapporto finito, un documento o un comando che devi eseguire.

Dirigere o interrompere un'esecuzione

• Usa Stop per interrompere un'esecuzione che sta andando nella direzione sbagliata, quindi affina il tuo prompt.
• Dai suggerimenti (es. "usa lxml invece di html.parser") per far uscire l'agente da un loop.

7 Le Quattro Modalità di Chat

Scegli una modalità dal selettore di modalità accanto al prompt. Ciascuna regola quanto l'agente pianifica e quanto liberamente modifica:

8 Revisione e Applicazione delle Modifiche

Quando l'agente propone modifiche ai file, un pannello Modifiche Proposte appare sopra l'input della chat, elencando ogni file toccato con il conteggio delle righe aggiunte (+) e rimosse (−).

• Clicca su una riga di file per aprire il suo diff inline nell'editor.
• Applica o Rifiuta un singolo file, oppure usa Applica tutto / Rifiuta tutto.
• Le modifiche applicate sono contrassegnate come applied (e · disk quando scritte su una cartella reale).
• Se non c'è una cartella scrivibile, un badge solo area di lavoro indica che le modifiche si applicano all'area di lavoro nel browser.

9 Terminale Integrato

Attiva/disattiva il terminale sotto l'editor per eseguire build, test e script. Con la tua autorizzazione, l'agente può eseguire comandi e leggere il loro output per verificare il suo lavoro; i comandi a lunga esecuzione trasmettono l'output in streaming in modo da poter monitorare i progressi. Chiudi il terminale dalla sua intestazione quando non ti serve.

10 Modalità Piano ed Esecuzione

Per obiettivi più grandi, usa la modalità Pianifica (o chiedi all'agente di pianificare prima). Il pianificatore scansiona il tuo progetto, scompone l'obiettivo in attività consapevoli delle dipendenze e assegna ciascuna allo specialista giusto (architetto, programmatore, tester, documentazione).

• Rivedi e modifica il piano — aggiungi, rimuovi o modifica le attività prima dell'esecuzione.
• Esegui strato per strato — le attività indipendenti vengono eseguite insieme; il pianificatore può ripianificare se un'attività fallisce.
• Metti in pausa, riprendi o annulla l'esecuzione in qualsiasi momento.

11 Scelta dei Modelli e Auto

Apri il selettore di modelli accanto al prompt. Le opzioni sono raggruppate come:

• Auto — lascia che DeepCerebra scelga il miglior modello disponibile (consigliato).
• Locale (la tua GPU) — modelli serviti dalla tua macchina (vedi §13).
• Gateway di piattaforma — modelli ospitati, raggruppati per gateway e poi per fornitore (es. Anthropic, OpenAI, Google).

Come funziona la selezione Auto

In modalità Auto, DeepCerebra utilizza un routing a livelli e adattivo: i compiti semplici vanno a un modello veloce ed economico, mentre il lavoro complesso o che richiede molta pianificazione (ad esempio, la modalità Pianifica) viene instradato a un modello più potente. Questo bilancia automaticamente costi e qualità, quindi raramente è necessario scegliere manualmente.

12 Porta la Tua Chiave (BYOK)

Puoi instradare le richieste tramite il tuo account fornitore invece di utilizzare l'uso a consumo della piattaforma.

1. Apri Chiavi API dalla barra laterale.
2. Sotto Porta la Tua Chiave, scegli un fornitore (es. ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY).
3. Incolla il valore della chiave e clicca su Salva. Le chiavi sono crittografate a riposo e non vengono mai restituite al browser — viene mostrata solo un'anteprima mascherata.

I modelli della piattaforma (DeepCerebra) non richiedono alcuna chiave. Rimuovi una chiave in qualsiasi momento con Rimuovi.

13 Macchina Locale: Modelli GPU e Console (DCC Bridge)

Il DCC Bridge collega il tuo computer all'app web tramite un piccolo connettore dcc-bridge, sbloccando due funzionalità contemporaneamente:

• Modelli GPU locali — i modelli serviti da Ollama o LM Studio sulla tua macchina appaiono nel selettore di modelli sotto Locale (la tua GPU).
• Console / terminale sulla tua macchina — il terminale web e l'agente possono eseguire comandi reali sul tuo computer, inclusi gli strumenti CLI che hai già configurato (Railway, AWS CLI, OVH CLI, gh, docker, kubectl, WSL, …) con le loro credenziali esistenti.

Il connettore si connette in uscita tramite un WebSocket autenticato — non sono necessarie porte in entrata, e funziona dietro NAT e firewall. Funziona su Windows, macOS e Linux (Python 3.10+).

13.1 Associa il tuo computer

1. Clicca sull'icona del laptop nella barra delle attività a sinistra — Macchina Locale (GPU + Console). (Lo stesso pannello si apre dal piè di pagina del selettore di modelli tramite Gestisci GPU locale….)
2. Assicurati che l'interruttore Esecuzione locale sia abilitato, dai un nome al dispositivo e clicca su Aggiungi questo computer. Copia il token di associazione monouso (dcc_brg_…) e il comando del connettore pronto per essere incollato — il token viene mostrato esattamente una volta.

13.2 Installa ed esegui il connettore

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

• Usa lo stesso dominio che usi nel browser come gateway (wss://deepcerebra.ai o wss://deepcerebra.io) — la scheda di associazione precompila quello corretto. I due siti sono distribuzioni separate con account e token separati.
• Per i modelli GPU, mantieni Ollama in esecuzione, o abilita il server locale di LM Studio (porta predefinita 1234) con un modello caricato.
• I dispositivi associati mostrano lo stato online/offline, il conteggio dei modelli e l'ambito di esecuzione; puoi Revocare un dispositivo in qualsiasi momento.

13.3 Usa la tua console dall'app web

Per impostazione predefinita, i comandi sono confinati a una cartella di lavoro dedicata (~/DeepCerebra). Per lavorare nelle tue cartelle di progetto reali con i tuoi CLI preconfigurati, concedi loro esplicitamente l'accesso all'avvio del connettore:

# 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

Quindi apri il pannello Terminale, clicca sul popover Target di esecuzione (icona laptop), scegli Il mio computer e seleziona una directory di lavoro. Sia i comandi digitati che i comandi di build/test dell'agente verranno quindi eseguiti sulla tua macchina.

14 Flusso di Lavoro di Collaborazione Git

Con un progetto basato su Git aperto, una barra del branch appare nell'Esplora risorse mostrando il tuo branch attuale e due azioni:

• Check-in (commit) — rivedi il conteggio dei file modificati, scrivi un messaggio di commit ed esegui il commit sul tuo branch di lavoro.
• Integra — apri una pull request dal tuo branch di lavoro nel branch predefinito (es. main). Devi essere su un branch di lavoro, non sul branch predefinito.

Se il webhook di push è abilitato, l'Esplora risorse si aggiorna automaticamente quando i colleghi effettuano un push, mantenendo tutti sincronizzati — la base per lo sviluppo collaborativo in team tramite DeepCerebra.

15 Server MCP

Estendi l'agente con strumenti e dati esterni tramite il Model Context Protocol. Configura i server in un file .deepcerebra/mcp.json, ad esempio:

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

Gli strumenti MCP abilitati diventano disponibili all'agente automaticamente quando sono pertinenti alla tua richiesta. Locali (stdio) e remoti (http/sse) sono entrambi supportati.

Sicurezza integrata

• Nega per impostazione predefinita — quando un server elenca una allowlist, solo quegli strumenti possono essere eseguiti.
• Approvazione per strumenti ad alto rischio — gli strumenti mutanti (scrittura/eliminazione/distribuzione/…) richiedono approvazione a meno che tu non li pre-approvi in autoApprove.
• Limitazione della frequenza, sanificazione degli argomenti e dell'output, e un log di audit si applicano a ogni chiamata.

Risorse e prompt

Se un server espone risorse MCP o modelli di prompt, l'agente acquisisce automaticamente strumenti per utilizzarli (mcp_list_resources, mcp_read_resource, mcp_list_prompts, mcp_get_prompt).

Autenticazione per server remoti

Aggiungi un blocco auth a un server remoto. I segreti supportano l'interpolazione ${ENV_VAR}:

// Static bearer token (literal or from env)
"auth": { "type": "bearer", "token": "${GITHUB_TOKEN}" }
"auth": { "type": "bearer", "tokenEnv": "GITHUB_TOKEN" }

// Custom header (e.g. API key)
"auth": { "type": "header", "header": "x-api-key", "value": "${MY_KEY}" }

// OAuth 2.0 client-credentials
"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 Personalizzazione dell'Agente: Regole, Skill, Hook, Subagenti e Plugin

Puoi modellare il modo in cui l'agente pensa e agisce con una singola convenzione basata su file — la directory .deepcerebra/ — che funziona in modo identico nell'app desktop, nell'app web e nell'API. Nell'app web, gestisci tutto questo sotto la vista Agente; su desktop e tramite l'API sono semplici file che commetti con il tuo progetto.

Ambiti e precedenza

La configurazione viene scoperta da diversi ambiti; quando lo stesso elemento esiste in più di uno, quello con precedenza più alta vince:

team/org  <  global (~/.deepcerebra)  <  workspace (<repo>/.deepcerebra)
(lowest)                                              (highest)

• Area di lavoro — <repo>/.deepcerebra/…, commessa con il progetto.
• Globale — ~/.deepcerebra/…, le tue impostazioni predefinite personali per tutti i progetti.
• Team / org — una base condivisa (precedenza più bassa) in modo che un utente o un progetto possa sempre sovrascriverla. Nell'app web, imposta lo Scope di una regola su Team.

Regole (guida)

Le regole sono istruzioni persistenti — standard di codifica, convenzioni architetturali, contesto di dominio — iniettate nel prompt di sistema dell'agente. Vivono come file Markdown sotto .deepcerebra/steering/, più lo standard sempre attivo AGENTS.md. Il frontmatter controlla quando una regola viene caricata:

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

• always — ogni turno (il predefinito).
• fileMatch — solo quando un file nel contesto corrisponde a globs.
• auto — quando la tua richiesta corrisponde a name/description della regola.
• manual — solo quando lo riferisci come #name o /name.

Un AGENTS.md radice si applica a tutto il repository; un AGENTS.md annidato (es. services/api/AGENTS.md) si applica solo ai file sotto quella cartella. Nell'app web, la vista Agente → Guida offre a ogni regola un selettore di Ambito (Globale / Progetto / Team).

Skill

Le skill sono playbook riutilizzabili che l'agente carica su richiesta. Ogni skill è una cartella con un SKILL.md sotto .deepcerebra/skills/:

---
name: deploy-release
description: How to cut and publish a versioned release.
disable-model-invocation: false   # true => manual-only (/skill)
---
# Deploy a release
1. Bump the version, build, and test.
2. Tag and publish.

L'agente vede un catalogo leggero (nome + descrizione) e carica il corpo completo con lo strumento load_skill quando pertinente. Puoi anche invocarne uno esplicitamente con /skill <name>. Imposta disable-model-invocation: true per rendere una skill solo manuale.

Hook

Gli hook eseguono l'automazione su eventi del ciclo di vita. Definisci gli hook come .deepcerebra/hooks/*.hook.json:

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

Gli eventi includono promptSubmit, preToolUse, postToolUse, fileCreate, fileSave, fileDelete, preTask, postTask, sessionStart, preCompact e agentStop (sono accettate anche le grafie Cursor/Claude). Un'azione è o shell (esegui un comando) o agentPrompt (chiedi all'agente). Un hook preToolUse può consentire, negare o chiedere la chiamata dello strumento che intercetta.

Subagenti

I subagenti sono agenti specialisti che definisci e a cui deleghi. Ciascuno è un file Markdown sotto .deepcerebra/agents/ con frontmatter più un corpo (il suo prompt di 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
---
You are a meticulous security reviewer…

L'agente principale delega con task (bloccante), task_async + task_status / task_result (in background), o task_parallel (fan-out).

Plugin

Un plugin raggruppa regole, skill, hook, subagenti e server MCP in un unico pacchetto installabile sotto .deepcerebra/plugins/<name>/, descritto da un manifesto plugin.json:

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

I contenuti dei plugin vengono uniti con la precedenza più bassa, quindi le tue regole e skill sovrascrivono sempre quelle di un plugin. Disabilita un plugin con "enabled": false o un file marcatore .disabled.

17 Studio di Workflow Agentico e Agenti basati su Eventi

Lo Studio di Workflow è un designer visuale per l'automazione multi-agente. Componi fasi — ciascuna un agente, un passo specialistico o una primitiva di controllo — in un grafo, le connetti con dipendenze ed esegui l'intera orchestrazione sul motore con progressi in tempo reale per fase, budget e gate di approvazione umana. I workflow vengono salvati come una definizione YAML/JSON portatile che puoi esportare, importare, versionare in Git ed eseguire dall'API o dalla CLI.

17.1 Costruire un workflow

• Palette (sinistra) — trascina tipi di fase, tipi di agente predefiniti (ricerca, generazione di codice, QA, scrittore di documenti, dispositivo medico, consulente brevetti e i tuoi tipi personalizzati), skill dalla Libreria Skill e strumenti sulla tela.
• Tela (centro) — organizza le fasi e disegna i bordi; un bordo significa "questa fase dipende da quella" e alimenta automaticamente l'output a monte nel prompt a valle.
• Ispezionatore (destra, ridimensionabile) — configura la fase selezionata: il suo prompt, skill, strumenti, override del modello per fase, artefatto di output, gate, eventi e parametri specifici del tipo.
• Modelli — parti da un blueprint integrato (Pipeline Ship-It, SaaS Starter, Data Pipeline con Evals, Customer Comms Hub, Design → App Verificata) e personalizzalo.
• Genera — descrivi l'app o il processo in linguaggio semplice e l'Agent Builder genera un grafo di workflow completo e validato che puoi rivedere, adattare ed eseguire.

17.2 La libreria delle fasi

17.3 Agenti basati su eventi (la mesh di agenti)

Ogni fase — indipendentemente dal tipo — può pubblicare e sottoscrivere eventi tipizzati sul bus di eventi dell'area di lavoro, in modo che gli agenti si coordinino come servizi su un fabric di messaggi piuttosto che solo tramite il DAG:

• Classi di eventi — ogni evento porta una classe: lifecycle, agent, business, data, system, schedule, chat, external o alert — filtrabile nelle sottoscrizioni e nel replay.
• Modalità di sottoscrizione — trigger (la fase viene eseguita quando arriva un evento corrispondente; un'esecuzione con fasi in attesa rimane residente come in ascolto), gate (un gate macchina approvato da un evento invece di un clic umano) e data (il payload viene unito nel contesto della fase).
• Avvio tramite evento — qualsiasi agente può essere avviato da un orchestratore o da un altro agente pubblicando al suo indirizzo agent.<stage-id>.request.
• Trigger di esecuzione — il blocco triggers: di un workflow lo abilita ad avviarsi su webhook in entrata, pianificazioni cron, eventi o chat — anche mentre lo Studio è chiuso.
• Esecuzioni live — il pannello di esecuzione trasmette eventi del ciclo di vita tramite SSE: avvii/completamenti di fase, gate, avvisi e anteprime appaiono istantaneamente.
• Log durevole e replay — gli eventi persistono per area di lavoro e possono essere riprodotti per pattern di argomento e classe per audit e debug.

17.3.1 Accodamento di eventi per gli agenti

Gli agenti che reagiscono agli eventi possono dichiarare una coda nominata durevole in modo che gli eventi corrispondenti non vadano mai persi mentre l'agente è occupato o prima che un'esecuzione sia in ascolto. Su una sottoscrizione di trigger, imposta queue: <name> — il motore associa quell'argomento a una coda FIFO sul bus di eventi dello spazio di lavoro (persistente sotto .deepcerebra/workflows/events/queues/). Ogni evento corrispondente pubblicato da quel momento in poi viene catturato nella coda; quando lo stage diventa eseguibile, il motore estrae gli eventi in ordine dal più vecchio al più recente e li consuma uno alla volta.

• Nessuna perdita — gli eventi pubblicati mentre il workflow è chiuso, mentre un altro stage è in esecuzione o mentre l'esecuzione è ancora in attesa di dipendenze vengono accodati invece di essere scartati.
• count per sottoscrizione — richiede N eventi accodati (o consegnati) prima che la sottoscrizione sia soddisfatta (utile quando più worker devono segnalare).
• Studio — nel pannello Eventi dell'Inspector, imposta il campo queue su una sottoscrizione di trigger; arma i trigger o avvia un'esecuzione per creare automaticamente l'associazione.
• API e strumenti — GET /api/workflow/queues elenca profondità e associazioni; GET /api/workflow/queues/{name} visualizza gli eventi in sospeso; gli agenti di chat possono chiamare 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 Orchestrazione dei semafori (protezione delle risorse condivise)

Un semaforo limita il numero di task che possono operare simultaneamente su una risorsa condivisa (protetta): un database in fase di scrittura, un archivio di variabili globali, un file o un agente esterno con limitazione di frequenza. Associalo a qualsiasi stage con semaphore: — prima che il lavoro dello stage venga eseguito, il motore acquisisce un permesso del semaforo nominato dello spazio di lavoro; il permesso viene sempre rilasciato in seguito, anche se lo stage fallisce. permits: 1 lo rende un mutex: solo un task alla volta (tra tutte le esecuzioni parallele nello spazio di lavoro) esegue il passo critico; ogni altro task attende che il detentore finisca.

• Serializzazione tra esecuzioni — i semafori sono con ambito di spazio di lavoro e persistenti, quindi due esecuzioni di workflow concorrenti non possono corrompere la stessa risorsa protetta.
• In attesa, non bloccato — i task si bloccano fino a timeout_s per un permesso; se la risorsa rimane a capacità massima, lo stage fallisce visibilmente invece di rimanere bloccato per sempre.
• Sicurezza in caso di crash — ogni permesso ha un ttl_s; se un detentore si blocca senza rilasciare, il permesso scade automaticamente in modo che la risorsa non sia mai in deadlock.
• Osservabilità — il bus emette eventi di sistema semaphore.<name>.waiting, .acquired e .released; GET /api/workflow/semaphores mostra capacità, detentori e permessi disponibili.
• Agenti di chat — gli strumenti acquire_semaphore, release_semaphore e semaphore_status coordinano sezioni critiche ad-hoc al di fuori di un workflow.

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 Orchestrazione Rendezvous (attesa di tutte le condizioni)

Rendezvous attende che molteplici condizioni di evento siano tutte soddisfatte prima che il passo successivo proceda — l'opposto di "il primo evento vince." Imposta join: all nel blocco events: dello stage: ogni sottoscrizione di trigger deve essere soddisfatta prima che lo stage venga eseguito. Combina con count: N per sottoscrizione quando più agenti (o più report da un singolo agente) devono tutti effettuare il check-in — ad esempio, l'approvazione del design, il completamento dei test e l'approvazione della sicurezza prima che uno stage di rilascio venga eseguito.

• join: any (predefinito) — lo stage viene eseguito quando la prima sottoscrizione di trigger è soddisfatta.
• join: all — rendezvous: ogni sottoscrizione di trigger (ciascuna con il proprio argomento, filtro di classe e count opzionale) deve essere soddisfatta; solo allora lo stage diventa eseguibile.
• Payload — tutti gli eventi consumati vengono registrati sullo stage come trigger_events ed esposti ai template come inputs.events (un elenco di oggetti evento con payload).
• Studio — quando uno stage ha due o più sottoscrizioni di trigger, l'Inspector mostra un selettore Join: any — il primo evento vince o all — rendezvous (attendi tutti); la tela mostra un badge di unione sugli stage 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 La libreria degli strumenti dell'agente

Le fasi scelgono gli strumenti dallo stesso registro utilizzato dall'agente di chat:

• Core — file, git, shell, esecuzione codice, ricerca codice, automazione browser, ricerca web, visione/media, generazione immagini.
• Database — query SQLite, PostgreSQL, MySQL, MongoDB e Redis più create_database, apply_migrations e dump_schema per livelli dati di proprietà.
• Comunicazioni — chiamate telefoniche e SMS (Twilio) ed email (SendGrid), con una modalità di simulazione che registra in una casella in uscita quando le credenziali sono assenti — le demo non inviano mai messaggi reali per errore.
• DevOps — docker_build / docker_push, compose up/down, deploy SSH e cloud-CLI (Fly, Render, Railway, Vercel), anche sicuri per la simulazione.
• Verifica — rilevamento dello stack, esecuzione di suite di test con tassi di superamento analizzati, audit delle dipendenze e scansione dei segreti.
• Motori SciCompute — centinaia di metodi scientifici e ingegneristici (denominati Class.method) in matematica, elaborazione del segnale, controlli, statistiche e altro ancora.
• Agenzia Esperta e MCP — ricerca di dominio fondata più qualsiasi server MCP esterno che connetti.

17.5 Esecuzione, gate e output

• Convalida controlla il grafo (ID unici, dipendenze acicliche, parametri di tipo) prima dell'esecuzione.
• I gate umani mettono in pausa l'esecuzione dopo che la fase produce la sua bozza, in modo che tu approvi il lavoro reale; i gate di evento consentono a un altro sistema di approvare automaticamente.
• I Budget limitano la spesa per esecuzione e per fase.
• Salva output nel progetto copia ogni artefatto generato da un'esecuzione nel tuo progetto aperto.
• Esporta App trasforma il workflow in un servizio FastAPI standalone; l'API pubblica /v1 espone esecuzioni, eventi, trigger, template e generazione per CI e integrazioni.

18 Completamento Predittivo con Tab

Il completamento predittivo con Tab offre suggerimenti di codice inline, "fill-in-the-middle", mentre digiti nell'editor — accetta un suggerimento con Tab. È opt-in sia sul motore che sull'editor web.

Abilitalo

• Motore — imposta il flag di ambiente DCC_TAB_COMPLETE=1. L'editor chiama l'endpoint POST /api/complete del motore, che restituisce solo il testo da inserire al cursore.
• Editor web — abilita in fase di build con VITE_TAB_COMPLETE=1, o in fase di runtime con localStorage.setItem('dcc.tabComplete', '1') (quindi ricarica).

Come si comporta

• I suggerimenti appaiono come testo fantasma; premi Tab per accettare, o continua a digitare per ignorare.
• Le richieste sono "debounced" e annullabili, quindi la digitazione non è mai bloccata.
• Quando il flag è disattivato, la funzionalità è completamente disabilitata e non vengono effettuate richieste di completamento.

19 Utilizzo, Crediti e Fatturazione

Apri Fatturazione dalla barra laterale per gestire il tuo piano e l'utilizzo. L'utilizzo dell'IA è misurato in crediti in dollari USA basati sui token consumati dai modelli sottostanti.

• Spesa del ciclo e credito prepagato — monitora l'utilizzo in questo ciclo e qualsiasi saldo prepagato.
• Aggiungi credito per eccesso di utilizzo — autorizza un importo aggiuntivo (USD) per continuare a utilizzare l'IA dopo che l'importo incluso è stato speso; se il tuo budget è esaurito vedrai un banner che ti invita ad aggiungere credito.
• Aggiorna / cambia piano — cambia livello in qualsiasi momento.
• Metodo di pagamento — aggiungi o aggiorna la carta registrata (elaborata da Stripe).
• Annulla — scegli annulla alla fine del periodo (mantieni l'accesso fino alla fine del periodo) o annulla ora (rimborso del residuo rimborsabile). Consulta la Politica di Cancellazione e Rimborso.

20 Ottenere la Chiave API del Gateway

Una chiave API del gateway (un token di accesso personale) ti consente di utilizzare l'API pubblica e la CLI di DeepCerebra in modo programmatico.

1. Accedi e apri Chiavi API dalla barra laterale.
2. Scorri fino a Chiavi API DeepCerebra.
3. Inserisci un'etichetta (es. "CI pipeline" o "CLI laptop").
4. Seleziona gli scope — read, chat, code, agent — e una scadenza opzionale in giorni (vuoto = mai).
5. Clicca su Genera. La chiave completa viene mostrata solo una volta — clicca su Copia e conservala in modo sicuro.

Usala con la CLI o l'API all'indirizzo 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/...

Puoi rinominare o eliminare (revocare) una chiave in qualsiasi momento; ogni chiave mostra il suo prefisso, gli scope, la data di creazione/scadenza e l'ultima data di utilizzo.

21 Sicurezza e Privacy

• Archiviazione riservata nel browser — i tuoi file di progetto rimangono nell'area di lavoro crittografata del browser; solo il contesto minimo necessario per ogni richiesta viene inviato al server.
• Zero Data Retention (ZDR) — i prompt e il codice instradati ai modelli non vengono conservati oltre la richiesta e non vengono mai utilizzati per addestrare modelli di base.
• Le chiavi rimangono lato server — i token BYOK e SCM sono crittografati a riposo; vengono mostrate solo anteprime mascherate.
• Crittografia — TLS in transito; dati dell'account crittografati a riposo; password hashate irreversibilmente.
• Il tuo codice è tuo — possiedi i tuoi contenuti e l'output generato. Consulta l' Informativa sulla Privacy.

22 Risoluzione dei Problemi

"Il caricamento della cartella richiede un browser Chromium"

Passa a Chrome, Edge o Brave, oppure usa Apri da Git.

L'agente si blocca sullo stesso errore

Clicca su Stop, quindi riformula con un suggerimento o un vincolo concreto.

Errori del modello o della richiesta / "budget esaurito"

• Controlla la tua connessione e che qualsiasi chiave BYOK sia valida.
• Passa ad Auto in modo che DeepCerebra instradi a un modello disponibile.
• Se il tuo budget di utilizzo è esaurito, apri Fatturazione e aggiungi credito per eccesso di utilizzo o aggiorna il tuo piano.

I modelli locali non appaiono

• Conferma che il connettore dcc-bridge sia in esecuzione e che il dispositivo mostri lo stato online.
• Assicurati che Ollama sia in esecuzione, o che il server locale di LM Studio sia abilitato (porta predefinita 1234) con un modello caricato.

Connettore: "connessione WebSocket rifiutata dal server: HTTP 401"

• Usa lo stesso dominio che usi nel browser come --gateway (wss://deepcerebra.ai o wss://deepcerebra.io) — i due siti sono distribuzioni separate e un token di uno non funziona mai sull'altro.
• Copia il comando esatto dalla scheda di associazione nella pagina Macchina Locale.

Le mie modifiche non hanno avuto effetto

• Assicurati di aver cliccato su Applica (non solo di aver visualizzato l'anteprima del diff) in Modifiche Proposte.
• Usa l'aggiornamento dell'Esplora risorse per riesaminare la cartella.

Git: "Sei sul branch predefinito"

Apri o crea un branch di lavoro prima di usare Integra per aprire una pull request.

Ancora bloccato? Contatta support@deepcerebra.ai.

23 DeepCerebra Discovery — Chiedi ai tuoi dati & documenti

Discovery è un chatbot investigativo per i tuoi database e documenti. Invece di rispondere con una singola query, funziona come un analista: forma ipotesi, esegue una serie di indagini controllate (SQL, grafi, ricerca di documenti, controlli di schema, corroborazione web), elimina le spiegazioni che le prove confutano e sintetizza una risposta fondata — con grafici e una ricevuta dei costi trasparente. Aprilo dall'icona della bussola nella barra delle attività (/app/discovery).

23.1 Spazi — il tuo ambito curato

Uno Spazio raggruppa tutto ciò di cui una linea di interrogazione ha bisogno: connessioni a database, raccolte di documenti, istruzioni per l'analista e budget. Creane uno con + Nuovo spazio, quindi usa il pannello di configurazione a destra per:

• Connetti database — SQLite, PostgreSQL, MySQL, SQL Server o Snowflake. Inserisci un nome e un DSN, clicca Test per verificare la connettività (vengono mostrate la latenza e la versione del server), o importa una configurazione di connessione esistente come JSON. Le connessioni sono di sola lettura per impostazione predefinita.
• Aggiungi documenti — trascina e rilascia file (PDF, DOCX, PPTX, Markdown, text) direttamente nella chat, incolla un URL o indica un percorso di cartella sull'host del motore. I documenti vengono suddivisi in chunk, incorporati e indicizzati per la ricerca ibrida vettoriale + knowledge-graph.
• Importa tabelle — incolla o carica CSV/JSON per interrogare istantaneamente senza alcun database.
• Insegna all'analista — aggiungi definizioni di metriche, regole aziendali e avvertenze, query fidate approvate dal curatore ed esempi di coppie domanda→query in modo che le risposte utilizzino le tue definizioni.

23.2 Porre una domanda

Digita una domanda come la faresti a un collega — ad esempio "Why did MRI scan volume dip in March?". La bacheca di investigazione mostra l'intero processo in tempo reale:

• Ipotesi — le spiegazioni candidate sotto investigazione, ciascuna contrassegnata come supportata, confutata o inconcludente man mano che arrivano le prove.
• Indagini — ogni query eseguita dall'analista, con il suo stato; SQL/Cypher generato è mostrato per la massima trasparenza, e ogni istruzione supera le regole di protezione di sola lettura prima dell'esecuzione.
• Prove — tabelle dei risultati ed estratti di documenti, citati per numero nella risposta finale.
• Risposta + grafici — una conclusione fondata che nomina anche le spiegazioni che sono state escluse, più grafici moderni a tema neon composti dalle prove.
• Ricevuta — token, costo per indagine e round, addebitati ai tuoi AI Credits come qualsiasi altra esecuzione di agente.

Le domande di follow-up continuano lo stesso thread, in modo che l'analista mantenga il suo contesto.

23.3 Grafici, report & esportazioni

I grafici vengono renderizzati in linea sulla bacheca di investigazione. Usa Esporta per scaricare l'intera richiesta — la risposta, le ipotesi, le prove e i grafici — come un report HTML autonomo o un PDF di qualità di stampa, stilizzato con il sistema di design neon.

23.4 Budget & controllo dei costi

Ogni spazio prevede budget per richiesta: un numero massimo di indagini, round di investigazione, secondi e USD. Il motore si ferma in modo pulito al limite e riporta ciò che ha trovato finora. Il costo di ogni indagine è dettagliato sulla ricevuta, così sai sempre dove sono andate le spese.

23.5 Automazione: API, SDK, Workflow Studio & MCP

• REST API — tutto ciò che fa l'interfaccia utente è disponibile sotto /v1/discovery/* con un PAT che porta lo scope discovery (crealo sotto Account → Token API). Le richieste in streaming usano SSE. Gli esecutori esterni possono prendere in prestito solo la pianificazione investigativa tramite la Thinking API (/v1/think/*, scope think).
• Python SDK — pip install deepcerebra-discovery, quindi DiscoveryClient(base_url, token).ask(space_id, question).
• Workflow Studio — trascina lo stage Richiesta Discovery (discovery.ask) in qualsiasi workflow per eseguire un'investigazione come passaggio della pipeline; la risposta, i grafici e la ricevuta fluiscono agli stage successivi.
• MCP — il motore espone discovery_ask e discovery_list_spaces come strumenti MCP, in modo che anche i client MCP esterni possano eseguire investigazioni.