1 Introducció i edicions

DeepCerebra Coder és un assistent de codificació agentic. A diferència d'un copilot d'autocompletat simple, planifica, escriu, refactoritza, executa ordres, crida eines i itera a través de tot el teu projecte — amb tu revisant i aprovant els canvis que proposa.

Tres maneres d'utilitzar-lo

Aquesta guia se centra en l'aplicació web a deepcerebra.ai; l'aplicació d'escriptori reflecteix els mateixos panells i fluxos de treball.

2 Primers passos i compte

Navegadors compatibles

Utilitza una versió actual de Chrome, Edge o Brave per a l'experiència completa — obrir una carpeta local depèn de l'API d'accés al sistema de fitxers de Chromium. Firefox i Safari funcionen per al xat i per a projectes basats en Git, però no poden obrir una carpeta local directament.

Crear un compte

1. Fes clic a Comença a la pàgina d'inici.
2. Omple el teu nom de visualització opcional, correu electrònic, país i data de naixement (has de tenir almenys 18 anys).
3. Tria el teu idioma d'interfície i una contrasenya d'almenys 12 caràcters.
4. Llegeix l'avís d'acord i confirma. Crear un compte significa que acceptes els Termes del servei, la Declaració de privadesa, la Descripció dels serveis, i el DPA global.
5. Fes clic a Crear compte, després verifica el teu correu electrònic si se't demana, i inicia sessió.

Restablir la teva contrasenya

1. A la pàgina d'inici de sessió, fes clic a Has oblidat la contrasenya?
2. Introdueix el teu correu electrònic i obre l'enllaç de restabliment enviat a la teva safata d'entrada.
3. Estableix una nova contrasenya (mínim 12 caràcters).

3 L'espai de treball d'un cop d'ull

Després d'iniciar sessió, aterraràs a l'entorn de treball, que posa tots els panells en una sola pantalla:

• Explorador (esquerra) — l'arbre de fitxers del projecte obert, amb un botó d'actualització i tancament.
• Editor (centre) — contingut del fitxer amb ressaltat de sintaxi i una vista general del minimapa; els diffs en línia apareixen aquí quan l'agent proposa canvis.
• Terminal (sota l'editor, activa/desactiva) — executa ordres i llegeix la sortida.
• Xat (dreta) — la conversa de l'agent; aquest és el panell principal que ocupa l'espai.

Arrossega el divisor entre l'editor i el xat per reequilibrar la disposició, i arrossega el divisor horitzontal per redimensionar el terminal. La barra lateral esquerra també navega a Espai de treball, Extensions, Claus API, Facturació i Comentaris.

4 Obrir un projecte

4.1 Obrir una carpeta local

1. A l'Explorador, fes clic a Obrir carpeta del projecte.
2. Tria una carpeta i concedeix al navegador permís per llegir-la.
3. Els fitxers es llegeixen a l'espai de treball xifrat del navegador — no es puja res. Veuràs un recompte en temps real i un resum final (nombre de fitxers · mida, més qualsevol fitxer saltat o truncat).

4.2 Obrir des de Git (GitHub / GitLab)

1. Fes clic a Obrir des de Git a l'Explorador.
2. Tria la pestanya GitHub o GitLab i enganxa un testimoni d'accés personal. Per a GitHub, utilitza l'àmbit repo (clàssic) o un testimoni de gra fi amb Continguts + Sol·licituds d'extracció; per a GitLab, utilitza l'àmbit api. El teu testimoni s'emmagatzema al servidor — només el contingut dels fitxers s'extreu al navegador.
3. Escriu el repositori com a owner/name (filtra la llista per trobar el teu), després tria una branca.
4. Opcionalment, marca Crear una nova branca de treball (p. ex., dcc/my-feature) per mantenir el teu treball aïllat de la branca per defecte.
5. Opcionalment, habilita el webhook de push perquè l'Explorador s'actualitzi instantàniament quan els companys d'equip facin push (necessita una URL de passarel·la pública).
6. Fes clic a Obrir repositori.

4.3 Actualitzar, canviar i tancar

• Actualitzar (↻ a la capçalera de l'Explorador) torna a escanejar la carpeta o extreu l'última versió de Git.
• Obrir una altra carpeta o Obrir des de Git des dels botons sota l'arbre.
• Tancar projecte (icona de paperera) esborra l'espai de treball del navegador.

4.4 Sessions de xat amb àmbit de carpeta

L'historial de xat està vinculat al projecte obert. Canviar de carpeta inicia automàticament una nova sessió i carrega les sessions anteriors d'aquesta carpeta, reobrint la més recent perquè puguis reprendre on ho vas deixar.

4.5 Carpetes operatives

Les carpetes que DeepCerebra utilitza internament — .deepcerebra, .sessions — apareixen a l'arbre però estan col·lapsades per defecte perquè no desordenen el teu codi font.

5 Treballar amb fitxers

• Fes clic a un fitxer a l'Explorador per obrir-lo a l'editor; el minimapa t'ajuda a navegar per fitxers llargs.
• Arrossega un fitxer de l'Explorador a la sol·licitud de xat per adjuntar-lo com a context explícit per al teu pròxim missatge.
• Quan l'agent proposa edicions, l'editor mostra un diff en línia per al fitxer seleccionat.

6 Xatejar amb l'agent

Escriure una sol·licitud

Descriu el que vols en llenguatge senzill — fes una pregunta, sol·licita una característica o assenyala un error. Sigues específic sobre fitxers, frameworks i restriccions per obtenir el millor resultat. Adjunta fitxers rellevants arrossegant-los a la sol·licitud.

Llegir respostes, estil Cursor

Les respostes s'organitzen com a Cursor: el raonament de l'agent se separa del resultat final. Cada bloc de resposta té una icona de còpia a la cantonada superior dreta perquè puguis copiar un informe acabat, un document o una ordre que hagis d'executar.

Dirigir o aturar una execució

• Utilitza Aturar per aturar una execució que va en la direcció equivocada, i després refina la teva sol·licitud.
• Dona pistes (p. ex., "utilitza lxml en lloc de html.parser") per treure l'agent d'un bucle.

7 Els quatre modes de xat

Tria un mode del selector de modes al costat de la sol·licitud. Cadascun ajusta quant planifica l'agent i amb quina llibertat edita:

8 Revisar i aplicar canvis

Quan l'agent proposa canvis de fitxer, apareix un panell de Canvis proposats a sobre de l'entrada del xat, que enumera cada fitxer afectat amb el recompte de línies afegides (+) i eliminades (−).

• Fes clic a una fila de fitxer per obrir el seu diff en línia a l'editor.
• Aplicar o Rebutjar un sol fitxer, o utilitzar Aplicar tot / Rebutjar tot.
• Els canvis aplicats es marquen com a applied (i · disk quan s'escriuen a una carpeta real).
• Si no hi ha una carpeta escrivible, una insígnia de només espai de treball indica que els canvis s'apliquen a l' espai de treball del navegador.

9 Terminal integrat

Activa el terminal sota l'editor per executar compilacions, proves i scripts. Amb la teva autorització, l'agent pot executar ordres i llegir la seva sortida per verificar el seu treball; les ordres de llarga durada transmeten la sortida perquè puguis veure el progrés. Tanca el terminal des de la seva capçalera quan no el necessitis.

10 Mode de planificació i execució

Per a objectius més grans, utilitza el mode Planificar (o demana a l'agent que planifiqui primer). El planificador escaneja el teu projecte, descompon l'objectiu en tasques que tenen en compte les dependències i assigna cadascuna a l'especialista adequat (arquitecte, programador, provador, documentació).

• Revisa i edita el pla — afegeix, elimina o modifica tasques abans de l'execució.
• Executa capa per capa — les tasques independents s'executen juntes; el planificador pot replanificar si una tasca falla.
• Pausa, reprèn o avorta l'execució en qualsevol moment.

11 Triar models i mode automàtic

Obre el selector de models al costat de la sol·licitud. Les opcions s'agrupen com:

• Automàtic — deixa que DeepCerebra triï el millor model disponible (recomanat).
• Local (la teva GPU) — models servits des de la teva pròpia màquina (vegeu §13).
• Passarel·les de plataforma — models allotjats, agrupats per passarel·la i després per proveïdor (p. ex., Anthropic, OpenAI, Google).

Com funciona la selecció automàtica

En mode automàtic, DeepCerebra utilitza un encaminament adaptatiu per nivells: les tasques senzilles van a un model ràpid i econòmic, mentre que el treball complex o amb molta planificació (per exemple, el mode Planificar) s'encamina a un model més potent. Això equilibra el cost i la qualitat automàticament, de manera que rarament necessitaràs triar manualment.

12 Porta la teva pròpia clau (BYOK)

Pots encaminar les sol·licituds a través del teu propi compte de proveïdor en lloc de l'ús mesurat de la plataforma.

1. Obre Claus API des de la barra lateral.
2. A Porta la teva pròpia clau, tria un proveïdor (p. ex., ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY).
3. Enganxa el valor de la clau i fes clic a Desar. Les claus s'encripten en repòs i mai es retornen al navegador — només es mostra una previsualització emmascarada.

Els models de plataforma (DeepCerebra) no necessiten clau. Elimina una clau en qualsevol moment amb Eliminar.

13 Màquina local: models GPU i consola (DCC Bridge)

El DCC Bridge connecta el teu propi ordinador a l'aplicació web mitjançant un petit connector dcc-bridge, desbloquejant dues capacitats alhora:

• Models GPU locals — els models servits per Ollama o LM Studio a la teva màquina apareixen al selector de models sota Local (la teva GPU).
• Consola / terminal a la teva màquina — el terminal web i l'agent poden executar ordres reals al teu ordinador, incloses les eines CLI que ja has configurat (Railway, AWS CLI, OVH CLI, gh, docker, kubectl, WSL, …) amb les seves credencials existents.

El connector es connecta cap a fora mitjançant un WebSocket autenticat — no es necessiten ports d'entrada, i funciona darrere de NAT i tallafocs. S'executa a Windows, macOS i Linux (Python 3.10+).

13.1 Emparellar el teu ordinador

1. Fes clic a la icona de l'ordinador portàtil a la barra d'activitats esquerra — Màquina local (GPU + Consola). (El mateix panell s'obre des del peu de pàgina del selector de models mitjançant Gestionar GPU local….)
2. Assegura't que l'interruptor de Execució local estigui activat, posa un nom al dispositiu i fes clic a Afegir aquest ordinador. Copia el token d'emparellament d'un sol ús (dcc_brg_…) i l'ordre del connector llesta per enganxar — el token es mostra exactament una vegada.

13.2 Instal·lar i executar el connector

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

# després executa l'ordre copiada de la targeta d'emparellament, p. ex.:
python -m dcc_bridge --gateway wss://deepcerebra.ai --token dcc_brg_xxxxx

• Utilitza el mateix domini que utilitzes al navegador com a passarel·la (wss://deepcerebra.ai o wss://deepcerebra.io) — la targeta d'emparellament preomple el correcte. Els dos llocs són desplegaments separats amb comptes i tokens separats.
• Per als models GPU, mantén Ollama en execució, o habilita el servidor local de LM Studio (port per defecte 1234) amb un model carregat.
• Els dispositius emparellats mostren l'estat en línia/fora de línia, el recompte de models i l'àmbit d'execució; pots Revocar un dispositiu en qualsevol moment.

13.3 Utilitza la teva consola des de l'aplicació web

Per defecte, les ordres es confinen a una carpeta de l'espai de treball dedicada (~/DeepCerebra). Per treballar a les teves carpetes de projecte reals amb les teves CLIs preconfigurades, concedeix-les explícitament en iniciar el connector:

# concedeix una o més carpetes reals (repetible)
python -m dcc_bridge --gateway wss://deepcerebra.ai --token dcc_brg_xxxxx --host-dir "F:\MyProjects"

# o tota la màquina (imprimeix un avís; prefereix --host-dir)
python -m dcc_bridge ... --allow-any-dir

Després, obre el panell Terminal, fes clic al popover de Destí d'execució (icona de l'ordinador portàtil), tria El meu ordinador i selecciona un directori de treball. Tant les teves ordres escrites com les ordres de compilació/prova de l'agent s'executen llavors a la teva màquina.

14 Flux de treball de col·laboració Git

Amb un projecte basat en Git obert, apareix una barra de branques a l'Explorador que mostra la teva branca actual i dues accions:

• Registrar (commit) — revisa el recompte de fitxers canviats, escriu un missatge de commit i fes commit a la teva branca de treball.
• Integrar — obre una sol·licitud d'extracció des de la teva branca de treball a la branca per defecte (p. ex., main). Has d'estar en una branca de treball, no en la branca per defecte.

Si el webhook de push està habilitat, l'Explorador s'actualitza automàticament quan els companys d'equip fan push, mantenint tothom sincronitzat — la base per al desenvolupament col·laboratiu en equip a través de DeepCerebra.

15 Servidors MCP

Estén l'agent amb eines i dades externes mitjançant el Protocol de Context del Model. Configura servidors en un fitxer .deepcerebra/mcp.json, per exemple:

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

Les eines MCP habilitades estan disponibles per a l'agent automàticament quan són rellevants per a la teva sol·licitud. Locals (stdio) i remots (http/sse) servidors són tots dos compatibles.

Seguretat integrada

• Denegar per defecte — quan un servidor llista una allowlist, només aquestes eines poden executar-se.
• Aprovació per a eines d'alt risc — les eines que muten (escriure/eliminar/desplegar/…) requereixen aprovació tret que les pre-aprovis a autoApprove.
• Limitació de velocitat, sanejament d'arguments i sortida, i un registre d'auditoria s'apliquen a cada crida.

Recursos i sol·licituds

Si un servidor exposa recursos o plantilles de sol·licitud MCP, l'agent obté automàticament eines per utilitzar-los (mcp_list_resources, mcp_read_resource, mcp_list_prompts, mcp_get_prompt).

Autenticació per a servidors remots

Afegeix un bloc auth a un servidor remot. Els secrets admeten la interpolació ${ENV_VAR}:

// Token bearer estàtic (literal o de l'entorn)
"auth": { "type": "bearer", "token": "${GITHUB_TOKEN}" }
"auth": { "type": "bearer", "tokenEnv": "GITHUB_TOKEN" }

// Capçalera personalitzada (p. ex., clau API)
"auth": { "type": "header", "header": "x-api-key", "value": "${MY_KEY}" }

// Credencials de client 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 Personalitzar l'agent: regles, habilitats, hooks, subagents i connectors

Pots modelar com pensa i actua l'agent amb una única convenció basada en fitxers — el directori .deepcerebra/ — que funciona de manera idèntica a l'aplicació d'escriptori, l' aplicació web i l'API. A l'aplicació web, gestiona tot això sota la vista d'Agent; a l'escriptori i mitjançant l'API són fitxers plans que fas commit amb el teu projecte.

Àmbits i precedència

La configuració es descobreix des de diversos àmbits; quan el mateix element existeix en més d'un, el de major precedència guanya:

team/org  <  global (~/.deepcerebra)  <  workspace (<repo>/.deepcerebra)
(més baixa)                                              (més alta)

• Espai de treball — <repo>/.deepcerebra/…, amb commit amb el projecte.
• Global — ~/.deepcerebra/…, els teus valors predeterminats personals per a tots els projectes.
• Equip / organització — una línia de base compartida (precedència més baixa) perquè un usuari o projecte sempre pugui anul·lar-la. A l'aplicació web, estableix l'Àmbit d'una regla a Equip.

Regles (direcció)

Les regles són instruccions persistents — estàndards de codificació, convencions d'arquitectura, context de domini — injectades a la sol·licitud del sistema de l'agent. Viuen com a fitxers Markdown sota .deepcerebra/steering/, a més de l'estàndard AGENTS.md sempre actiu. El frontmatter controla quan es carrega una regla:

---
inclusion: fileMatch          # always | fileMatch | auto | manual
globs: "src/**/*.ts"          # or fileMatchPattern
name: api-design
description: REST conventions
---
# Disseny d'API
- Utilitza substantius de recursos REST, en plural.

• always — cada torn (el valor per defecte).
• fileMatch — només quan un fitxer en context coincideix amb globs.
• auto — quan la teva sol·licitud coincideix amb el name/description de la regla.
• manual — només quan el referencies com a #name o /name.

Un AGENTS.md arrel s'aplica a tot el repositori; un AGENTS.md niuat (p. ex., services/api/AGENTS.md) s'aplica només als fitxers d'aquesta carpeta. A l'aplicació web, la vista Agent → Direcció ofereix a cada regla un selector d'Àmbit (Global / Projecte / Equip).

Habilitats

Les habilitats són llibres de jugades reutilitzables que l'agent carrega a demanda. Cada habilitat és una carpeta amb un SKILL.md sota .deepcerebra/skills/:

---
name: deploy-release
description: How to cut and publish a versioned release.
disable-model-invocation: false   # true => manual-only (/skill)
---
# Desplegar una versió
1. Augmenta la versió, compila i prova.
2. Etiqueta i publica.

L'agent veu un catàleg lleuger (nom + descripció) i extreu el cos complet amb l'eina load_skill quan és rellevant. També pots invocar-ne una explícitament amb /skill <name>. Estableix disable-model-invocation: true per fer que una habilitat sigui només manual.

Hooks

Els hooks executen automatització en esdeveniments del cicle de vida. Defineix-los com a .deepcerebra/hooks/*.hook.json:

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

Els esdeveniments inclouen promptSubmit, preToolUse, postToolUse, fileCreate, fileSave, fileDelete, preTask, postTask, sessionStart, preCompact i agentStop (també s'accepten les grafies de Cursor/Claude). Una acció és shell (executar una ordre) o agentPrompt (preguntar a l'agent). Un hook preToolUse pot permetre, denegar o preguntar per la crida a l'eina que intercepta.

Subagents

Els subagents són agents especialistes que defineixes i als quals delegues. Cadascun és un fitxer Markdown sota .deepcerebra/agents/ amb frontmatter més un cos (la seva sol·licitud del 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
---
Ets un revisor de seguretat meticulós…

L'agent principal delega amb task (bloqueig), task_async + task_status / task_result (segon pla), o task_parallel (fan-out).

Connectors

Un connector agrupa regles, habilitats, hooks, subagents i servidors MCP en un sol paquet instal·lable sota .deepcerebra/plugins/<name>/, descrit per un manifest plugin.json:

{
  "name": "Estàndards Acme",
  "version": "1.2.0",
  "description": "Regles Acme + habilitats + agents de revisió.",
  "enabled": true
}

El contingut dels connectors es fusiona amb la precedència més baixa, de manera que les teves pròpies regles i habilitats sempre anul·len les d'un connector. Deshabilita un connector amb "enabled": false o un fitxer marcador .disabled.

17 Estudi de flux de treball agentic i agents basats en esdeveniments

L'Estudi de flux de treball és un dissenyador visual per a l'automatització multiagent. Composa etapes — cadascuna un agent, un pas especialista o una primitiva de control — en un gràfic, connecta-les amb dependències i executa tota l'orquestració al motor amb progrés en temps real per etapa, pressupostos i portes d'aprovació humana. Els fluxos de treball es guarden com una definició YAML/JSON portàtil que pots exportar, importar, versionar a Git i executar des de l'API o la CLI.

17.1 Construir un flux de treball

• Paleta (esquerra) — arrossega tipus d'etapes, tipus d'agent predefinits (recerca, generació de codi, QA, escriptor de documents, dispositiu mèdic, assessor de patents i els teus propis tipus personalitzats), habilitats de la Biblioteca d'Habilitats i eines al llenç.
• Llenç (centre) — organitza les etapes i dibuixa arestes; una aresta significa "aquesta etapa depèn d'aquella" i alimenta automàticament la sortida ascendent a la sol·licitud descendent.
• Inspector (dreta, redimensionable) — configura l'etapa seleccionada: la seva sol·licitud, habilitats, eines, anul·lació de model per etapa, artefacte de sortida, porta, esdeveniments i paràmetres específics del tipus.
• Plantilles — comença des d'un projecte predefinit (Pipeline de lliurament, Iniciador SaaS, Pipeline de dades amb avaluacions, Centre de comunicacions amb clients, Disseny → Aplicació verificada) i personalitza-lo.
• Generar — descriu l'aplicació o el procés en llenguatge senzill i el Creador d'Agents genera un gràfic de flux de treball complet i validat que pots revisar, ajustar i executar.

17.2 La biblioteca d'etapes

17.3 Agents basats en esdeveniments (la malla d'agents)

Cada etapa — independentment del tipus — pot publicar i subscriure's a esdeveniments tipificats al bus d'esdeveniments de l'espai de treball, de manera que els agents es coordinen com serveis en un teixit de missatges en lloc de només a través del DAG:

• Classes d'esdeveniments — cada esdeveniment porta una classe: lifecycle, agent, business, data, system, schedule, chat, external o alert — filtrable en subscripcions i reproducció.
• Modes de subscripció — trigger (l'etapa s'executa quan arriba un esdeveniment coincident; una execució amb etapes aparcades roman resident com a escoltant), gate (una porta de màquina aprovada per un esdeveniment en lloc d'un clic humà), i data (la càrrega útil es fusiona amb el context de l'etapa).
• Inici per esdeveniment — qualsevol agent pot ser iniciat per un orquestrador o un altre agent publicant a la seva adreça agent.<stage-id>.request.
• Disparadors d'execució — el bloc triggers: d'un flux de treball l'arma per iniciar-se amb webhooks entrants, programacions cron, esdeveniments o xat — fins i tot mentre l'Estudi està tancat.
• Execucions en viu — el panell d'execució transmet esdeveniments del cicle de vida mitjançant SSE: inicis/finalitzacions d'etapes, portes, alertes i previsualitzacions apareixen instantàniament.
• Registre durador i reproducció — els esdeveniments persisteixen per espai de treball i es poden reproduir per patró de tema i classe per a auditoria i depuració.

17.3.1 Cua d'esdeveniments per a agents

Els agents que reaccionen a esdeveniments poden declarar una cua amb nom duradora perquè els esdeveniments coincidents no es perdin mai mentre l'agent està ocupat o abans que una execució estigui escoltant. En una subscripció de disparador, configureu queue: <name> — el motor vincula aquest tema a una cua FIFO al bus d'esdeveniments de l'espai de treball (persistida a .deepcerebra/workflows/events/queues/). Cada esdeveniment coincident publicat a partir d'aquest moment es captura a la cua; quan l'etapa esdevé executable, el motor extreu els esdeveniments en ordre de més antic a més nou i els consumeix un a un.

• Res perdut — els esdeveniments publicats mentre el flux de treball està tancat, mentre una altra etapa s'està executant, o mentre l'execució encara espera dependències, s'encuen en lloc de descartar-se.
• count per subscripció — requereix N esdeveniments en cua (o lliurats) abans que la subscripció es satisfaci (útil quan diversos treballadors han d'informar).
• Studio — al panell d'Esdeveniments de l'Inspector, configureu el camp queue en una subscripció de disparador; activeu els disparadors o inicieu una execució per crear la vinculació automàticament.
• API i eines — GET /api/workflow/queues enumera la profunditat i les vinculacions; GET /api/workflow/queues/{name} mostra els esdeveniments pendents; els agents de xat poden cridar event_queue_status i 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 Orquestració de semàfors (protecció de recursos compartits)

Un semàfor limita quantes tasques poden operar simultàniament en un recurs compartit (protegit): una base de dades que s'està escrivint, un magatzem de variables globals, un fitxer o un agent extern amb limitació de velocitat. Adjunteu-ne un a qualsevol etapa amb semaphore: — abans que s'executi la feina de l'etapa, el motor adquireix un permís del semàfor de l'espai de treball amb nom; el permís sempre s'allibera després, fins i tot si l'etapa falla. permits: 1 el converteix en un mutex: només una tasca a la vegada (entre totes les execucions paral·leles a l'espai de treball) executa el pas crític; totes les altres tasques esperen fins que el titular finalitza.

• Serialització entre execucions — els semàfors tenen un abast d'espai de treball i són persistents, de manera que dues execucions de flux de treball concurrents no poden corrompre el mateix recurs protegit.
• Esperant, no penjant — les tasques es bloquegen fins a timeout_s per obtenir un permís; si el recurs es manté a la seva capacitat, l'etapa falla visiblement en lloc de quedar-se penjada per sempre.
• Seguretat contra fallades — cada permís té un ttl_s; si un titular falla sense alliberar-lo, el permís caduca automàticament perquè el recurs mai quedi bloquejat.
• Observabilitat — el bus emet esdeveniments del sistema semaphore.<name>.waiting, .acquired i .released; GET /api/workflow/semaphores mostra la capacitat, els titulars i els permisos disponibles.
• Agents de xat — les eines acquire_semaphore, release_semaphore i semaphore_status coordinen seccions crítiques ad-hoc fora d'un flux de treball.

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 Orquestració de Rendezvous (espera de totes les condicions)

Rendezvous espera fins que múltiples condicions d'esdeveniments es compleixen totes abans que el següent pas continuï — el contrari de "el primer esdeveniment guanya". Configureu join: all al bloc events: de l'etapa: totes les subscripcions de disparador han de ser satisfetes abans que l'etapa s'executi. Combineu-ho amb count: N per subscripció quan diversos agents (o diversos informes d'un agent) han de registrar-se tots — per exemple, l'aprovació del disseny, la finalització de les proves i l'aprovació de seguretat abans que s'executi una etapa de llançament.

• join: any (per defecte) — l'etapa s'executa quan la primera subscripció de disparador és satisfeta.
• join: all — rendezvous: cada subscripció de disparador (cadascuna amb el seu propi tema, filtre de classe i count opcional) ha de ser satisfeta; només llavors l'etapa esdevé executable.
• Càrregues útils — tots els esdeveniments consumits es registren a l'etapa com a trigger_events i s'exposen a les plantilles com a inputs.events (una llista d'objectes d'esdeveniments amb càrregues útils).
• Studio — quan una etapa té dues o més subscripcions de disparador, l'Inspector mostra un selector Join: any — el primer esdeveniment guanya o all — rendezvous (espera de tots); el llenç mostra una insígnia de fusió a les etapes 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 La biblioteca d'eines de l'agent

Les etapes trien eines del mateix registre que utilitza l'agent de xat:

• Nucli — fitxers, git, shell, execució de codi, cerca de codi, automatització del navegador, cerca web, visió/mitjans, generació d'imatges.
• Bases de dades — consultes SQLite, PostgreSQL, MySQL, MongoDB i Redis més create_database, apply_migrations i dump_schema per a capes de dades pròpies.
• Comunicacions — trucades telefòniques i SMS (Twilio) i correu electrònic (SendGrid), amb un mode de simulació que registra a una safata de sortida quan les credencials estan absents — les demostracions mai envien missatges reals per accident.
• DevOps — docker_build / docker_push, compose up/down, desplegaments SSH i cloud-CLI (Fly, Render, Railway, Vercel), també segurs per a simulació.
• Verificació — detecció de pila, execució de suites de proves amb taxes d'aprovació analitzades, auditories de dependències i escaneig de secrets.
• Motors SciCompute — centenars de mètodes científics i d'enginyeria (anomenats Class.method) en matemàtiques, processament de senyals, controls, estadístiques i més.
• Agència Experta i MCP — recerca de domini fonamentada més qualsevol servidor MCP extern que connectis.

17.5 Execució, portes i sortides

• Validar comprova el gràfic (identificadors únics, dependències acícliques, paràmetres de tipus) abans d'executar.
• Les portes humanes pausen l'execució després que l'etapa produeixi el seu esborrany, de manera que aproves el treball real; les portes d'esdeveniments permeten que un altre sistema aprovi automàticament.
• Els pressupostos limiten la despesa per execució i per etapa.
• Desar sortides al projecte copia cada artefacte generat per una execució al teu projecte obert.
• Exportar aplicació converteix el flux de treball en un servei FastAPI autònom; l'API pública /v1 exposa execucions, esdeveniments, disparadors, plantilles i generació per a CI i integracions.

18 Completació predictiva amb Tab

La completació predictiva amb Tab ofereix suggeriments de codi en línia, per omplir al mig, mentre escrius a l'editor — accepta un suggeriment amb Tab. És una funció optativa tant al motor com a l'editor web.

Habilitar-ho

• Motor — estableix la bandera d'entorn DCC_TAB_COMPLETE=1. L'editor crida l'endpoint POST /api/complete del motor, que retorna només el text a inserir al cursor.
• Editor web — habilita-ho en temps de compilació amb VITE_TAB_COMPLETE=1, o en temps d'execució amb localStorage.setItem('dcc.tabComplete', '1') (després recarrega).

Com es comporta

• Els suggeriments apareixen com a text fantasma; prem Tab per acceptar, o continua escrivint per descartar.
• Les sol·licituds es retarden i es poden cancel·lar, de manera que l'escriptura mai es bloqueja.
• Quan la bandera està desactivada, la funció està completament deshabilitada i no es fan sol·licituds de completació.

19 Ús, crèdits i facturació

Obre Facturació des de la barra lateral per gestionar el teu pla i ús. L'ús d'IA es mesura en crèdits de dòlars nord-americans basats en els tokens consumits pels models subjacents.

• Despesa del cicle i crèdit prepagat — fes un seguiment de l'ús d'aquest cicle i de qualsevol saldo prepagat.
• Afegir crèdit per excés — autoritza una quantitat addicional (USD) per continuar utilitzant la IA un cop esgotada la quota inclosa; si el teu pressupost s'esgota, veuràs un bàner que et demanarà que afegeixis crèdit.
• Actualitzar / canviar de pla — canvia de nivell en qualsevol moment.
• Mètode de pagament — afegeix o actualitza la targeta registrada (processada per Stripe).
• Cancel·lar — tria cancel·lar al final del període (manté l'accés fins que finalitzi el període) o cancel·lar ara (reemborsa el residual reemborsable). Consulta la Política de cancel·lació i reemborsament.

20 Obtenir la teva clau API de passarel·la

Una clau API de passarel·la (un testimoni d'accés personal) et permet utilitzar l'API pública de DeepCerebra i la CLI de manera programàtica.

1. Inicia sessió i obre Claus API des de la barra lateral.
2. Desplaça't fins a Claus API de DeepCerebra.
3. Introdueix una etiqueta (p. ex., "pipeline CI" o "CLI de portàtil").
4. Selecciona àmbits — read, chat, code, agent — i una caducitat opcional en dies (en blanc = mai).
5. Fes clic a Generar. La clau completa es mostra només una vegada — fes clic a Copiar i guarda-la de manera segura.

Utilitza-la amb la CLI o l'API a deepcerebra.ai:

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

# o com a testimoni Bearer
curl -H "Authorization: Bearer <your-key>" https://deepcerebra.ai/v1/...

Pots canviar el nom o eliminar (revocar) una clau en qualsevol moment; cada clau mostra el seu prefix, àmbits, data de creació/caducitat i data d'últim ús.

21 Seguretat i privadesa

• Emmagatzematge confidencial al navegador — els fitxers del teu projecte romanen a l'espai de treball xifrat del navegador; només el context mínim necessari per a cada sol·licitud s'envia al servidor.
• Retenció Zero de Dades (ZDR) — les sol·licituds i el codi encaminats als models no es retenen més enllà de la sol·licitud i mai s'utilitzen per entrenar models fundacionals.
• Les claus romanen al servidor — els tokens BYOK i SCM s'encripten en repòs; només es mostren previsualitzacions emmascarades.
• Xifratge — TLS en trànsit; dades del compte xifrades en repòs; contrasenyes hash irreversibles.
• El teu codi és teu — ets propietari del teu contingut i de la sortida generada. Consulta la Declaració de privadesa.

22 Resolució de problemes

"La càrrega de carpetes necessita un navegador Chromium"

Canvia a Chrome, Edge o Brave, o utilitza Obrir des de Git en el seu lloc.

L'agent entra en bucle amb el mateix error

Fes clic a Aturar, després reformula amb una pista o restricció concreta.

Errors de model o de sol·licitud / "pressupost esgotat"

• Comprova la teva connexió i que qualsevol clau BYOK sigui vàlida.
• Canvia a Automàtic perquè DeepCerebra s'encamini a un model disponible.
• Si el teu pressupost d'ús s'ha esgotat, obre Facturació i afegeix crèdit per excés o actualitza el teu pla.

Els models locals no apareixen

• Confirma que el connector dcc-bridge està en execució i que el dispositiu mostra en línia.
• Assegura't que Ollama està en execució, o que el servidor local de LM Studio està habilitat (port per defecte 1234) amb un model carregat.

Connector: "el servidor ha rebutjat la connexió WebSocket: HTTP 401"

• Utilitza el mateix domini que utilitzes al navegador com a --gateway (wss://deepcerebra.ai o wss://deepcerebra.io) — els dos llocs són desplegaments separats, i un token d'un mai funciona a l'altre.
• Copia l'ordre exacta de la targeta d'emparellament a la pàgina de Màquina local.

Els meus canvis no han tingut efecte

• Assegura't que has fet clic a Aplicar (no només has previsualitzat el diff) a Canvis proposats.
• Utilitza l'actualització de l'Explorador per tornar a escanejar la carpeta.

Git: "Estàs a la branca per defecte"

Obre o crea una branca de treball abans d'utilitzar Integrar per obrir una sol·licitud d'extracció.

Encara encallat? Contacta amb support@deepcerebra.ai.

23 DeepCerebra Discovery — Pregunta a les teves dades i documents

Discovery és un chatbot d'investigació per a les teves bases de dades i documents. En lloc de respondre amb una única consulta, funciona com un analista: formula hipòtesis, executa una sèrie de sondes protegides (SQL, graph, cerca de documents, comprovacions d'esquema, corroboració web), descarta les explicacions que l'evidència refuta, i sintetitza una resposta fonamentada — amb gràfics i un rebut de cost transparent. Obre-ho des de la icona de la brúixola a la barra d'activitats (/app/discovery).

23.1 Espais — el teu abast curat

Un Espai agrupa tot el que una línia de qüestionament necessita: connexions de bases de dades, col·leccions de documents, instruccions per a l'analista i pressupostos. Crea'n un amb + Nou espai, després utilitza el panell de configuració de la dreta per a:

• Connecta bases de dades — SQLite, PostgreSQL, MySQL, SQL Server o Snowflake. Introdueix un nom i DSN, fes clic a Prova per verificar la connectivitat (es mostren la latència i la versió del servidor), o importa una configuració de connexió existent com a JSON. Les connexions són de només lectura per defecte.
• Afegeix documents — arrossega i deixa anar fitxers (PDF, DOCX, PPTX, Markdown, text) directament al xat, enganxa una URL o apunta a una ruta de carpeta a l'amfitrió del motor. Els documents es divideixen en trossos, s'incrusten i s'indexen per a la cerca híbrida de vectors + graf de coneixement.
• Importa taules — enganxa o puja CSV/JSON per consultar instantàniament sense cap base de dades.
• Ensenya a l'analista — afegeix definicions de mètriques, regles de negoci i advertiments, consultes de confiança aprovades pel curador, i parells d'exemple pregunta→consulta perquè les respostes utilitzin les teves definicions.

23.2 Fent una pregunta

Escriu una pregunta de la mateixa manera que li preguntaries a un company — per exemple "Why did MRI scan volume dip in March?". El tauler d'investigació transmet tot el procés en directe:

• Hipòtesis — les explicacions candidates sota investigació, cadascuna marcada com a confirmada, refutada o inconclusa a mesura que arriba l'evidència.
• Sondes — cada consulta que executa l'analista, amb el seu estat; es mostra el SQL/Cypher generat per a una transparència total, i cada declaració passa les regles de protecció de només lectura abans de l'execució.
• Evidència — taules de resultats i extractes de documents, citats per número a la resposta final.
• Resposta + gràfics — una conclusió fonamentada que també anomena les explicacions que van ser descartades, a més de gràfics moderns amb temàtica neó compostos a partir de l'evidència.
• Rebut — tokens, cost per sonda i rondes, carregats als teus AI Credits com qualsevol altra execució d'agent.

Les preguntes de seguiment continuen el mateix fil, de manera que l'analista manté el seu context.

23.3 Gràfics, informes i exportacions

Els gràfics es mostren en línia al tauler d'investigació. Utilitza Exporta per descarregar la consulta completa — la resposta, les hipòtesis, l'evidència i els gràfics — com un informe HTML autocontingut o un PDF de qualitat d'impressió, estilitzat amb el sistema de disseny neó.

23.4 Pressupostos i control de costos

Cada espai té pressupostos per consulta: un nombre màxim de sondes, rondes d'investigació, segons i USD. El motor s'atura netament al límit i informa del que ha trobat fins ara. El cost de cada sonda s'especifica al rebut, de manera que sempre saps on s'ha gastat.

23.5 Automatització: API, SDK, Workflow Studio & MCP

• REST API — tot el que fa la interfície d'usuari està disponible a /v1/discovery/* amb un PAT que inclou l'abast discovery (crea'l a Compte → Tokens d'API). Les consultes en streaming utilitzen SSE. Els executors externs poden utilitzar només la planificació d'investigació mitjançant la Thinking API (/v1/think/*, abast think).
• Python SDK — pip install deepcerebra-discovery, després DiscoveryClient(base_url, token).ask(space_id, question).
• Workflow Studio — arrossega l'etapa Consulta de Discovery (discovery.ask) a qualsevol flux de treball per executar una investigació com a pas de pipeline; la resposta, els gràfics i el rebut flueixen a les etapes posteriors.
• MCP — el motor exposa discovery_ask i discovery_list_spaces com a eines MCP, de manera que els clients MCP externs també poden executar investigacions.