Documentazione sul codice BLX

Benvenuti nella documentazione BLXCode. Le guide per l'utente spiegano come eseguire e utilizzare l'app; le guide per sviluppatori spiegano come creare, estendere e contribuire.

Copia pubblicata: GitHub Wiki (sincronizzato automaticamente da questa cartella durante i push su main che tocca docs/**). Modifica la documentazione qui nel repository, non nell'interfaccia utente web della wiki.

Mappa dei documenti

Inizia qui: Per iniziare → Workspaces → Agent Harness

Documenti utente

• Introduzione: prerequisiti, esecuzione di BLXCode, primo spazio di lavoro, dove risiedono i dati, schermata di benvenuto Crea spazio di lavoro, modello per agente/flotta di risorse.
• Impostazioni: impostazioni della scheda centrale ancorata, Chiavi API, Agente BLXCode (testo/immagine/voce), MCP, HeartBeat, Memoria, Editor di codice (Vim), Area di lavoro, Aspetto/temi, Guida/Informazioni, Registro app, Notifiche.
• Aspetto e temi: selettore temi, preimpostazioni, persistenza, eccezioni, dimensione carattere.
• Aree di lavoro: creazione, griglie di terminali, esploratore della barra laterale, Diff file (stage/commit/push), grafico Git (recupera/pull), handoff, persistenza, riga di stato dell'app, trascinamento del contesto della barra laterale (file/cartelle/diff/commit), finestra di dialogo di installazione hook, terminali con nome.
• Remote (SSH) — Impostazioni → Preimpostazioni di connessione remota (password/chiave/agente, segreti crittografati), creazione di spazi di lavoro remoti, terminali remoti + file/git + ripresa della sessione (tmux vs keepalive).
• Anteprima file: anteprime nella scheda centrale per immagini (incl. SVG), video, Markdown renderizzato, codice sorgente con sintassi evidenziata e diagrammi Sirena. Modalità Vim tramite @replit/codemirror-vim. I documenti relativi alle policy del repository (LICENSE, CONTRIBUTING, SECURITY, CHANGELOG, …) vengono visualizzati come Markdown con un banner hero specifico per il tipo, con o senza estensione .md.
• Memoria e attività: pannello Memoria (file, grafico, ricerca), mappa dell'architettura, categorie dinamiche, attività, strumenti di memoria dell'agente, Indicizzatore di memoria (HeartBeat), riquadro Impostazioni memoria.
• Piani — .agents/plans/<slug>/plan.md, indice PLANS.md gestito automaticamente, area di lavoro Multi-Kanban, Galleria diagrammi sirena, sintassi delle attività, pannello Piani, strumenti agente.
• Regole e abilità: carte regole/abilità espandibili, abilità base e abilità utente, finestra di dialogo di installazione.
• Agent Harness: competenze di base (incl. MCP, generazione di prompt), slim prompt, ambiente/shell/git/web, chiavi API web.
• Subagents: esecuzioni parallele, ruoli, sequenza temporale, gruppi di strumenti, limiti.
• Scorciatoie da tastiera: prefisso tmux e accordi legacy, avvisi di notifica, Crea spazio di lavoro, Push-to-Talk.
• Modalità immagine: genera immagini dal pannello dell'agente, impostazioni, limiti, persistenza.
• Provider di agenti — OpenRouter, Anthropic, compatibile con OpenAI + Ollama / LM Studio / Hugging Face / Cloudflare / Together / Portkey / personalizzato, server MCP, nickname agente, onboarding, tipi di contesto della barra laterale.
• Voce — STT, TTS, microfono, Push-to-Talk (Whisper locale/cloud).
• Lingua UI: impostazioni locali, selezione lingua, localizzazione EULA.
• Building: build di versioni Linux, macOS e Windows.
• Risoluzione dei problemi: problemi di avvio, creazione, browser, portachiavi, terminale.

Documenti per gli sviluppatori

• Setup: ambiente locale e comandi di verifica.
• Architettura: suddivisione frontend/backend, agente, memoria, piani, handoff, diagrammi, HeartBeat, Memory Indexer, MCP, Kanban, Sirena, Notifiche, Log app, Linea di stato dell'app, trascinamento del contesto della barra laterale.
• Agent Harness: competenze di base (incl. MCP, generazione di prompt), invio di strumenti, impostazioni web, registro del provider di testo, modulo MCP, guida all'estensione.
• Subagents — subagents.run, runner, protocollo, gruppi di strumenti, nuovi ruoli.
• Tauri IPC: registrazione dei comandi, wrapper, gruppi di comandi, comandi HeartBeat / Memory Indexer / MCP / Kanban / Sirena / Notifiche / Registro app.
• Trasporto remoto SSH: terminali wrappati-ssh, canale exec persistente, routing remoto fs/git, segreti, curriculum, smontaggio, follow-up urgente.
• Architettura vocale — Moduli e flussi STT/TTS.
• Internazionalizzazione: impostazioni locali, contenuto EULA, flusso di lavoro di traduzione.
• Temi — token, ThemeService, aggiunta di temi, regole di lanugine.
• Contributing: stile del codice, regole, test, elenco di controllo delle richieste pull.

Principi del progetto

BLXCode è un workbench desktop locale. Aree di lavoro, terminali, memoria, piani, attività e contesto dell'agente rimangono vicini senza nascondere la posizione dei dati sul disco. Quando il comportamento cambia, aggiorna i documenti accanto al codice in modo che utenti e collaboratori possano andare avanti senza eseguire il reverse engineering dell'app.

Note sulla versione

Le note rivolte all'utente per ciascuna versione si trovano in docs/releases/ (ad esempio v0.5.0.md). Anche i Prerelease utilizzano il nome file esatto del tag, ad esempio v0.5.1-pre.ed4dc.md. Alimentano la finestra di dialogo Novità in-app dopo gli aggiornamenti e dovrebbero rimanere non tecnici. Il registro delle modifiche tecniche rimane in CHANGELOG.md nella radice del repository.