Cos'è DeepSeek Harness? Il runtime di agenti dove tutto è un plugin

Cos'è DeepSeek Harness?

DeepSeek Harness, abbreviato in dsh, è une agent harness open source di DeepSeek AI sotto licenza MIT. Si colloca tra un modello linguistico e il mondo esterno, fornendo strumenti, sessioni, sandboxing e il loop che porta avanti un compito.

La formulazione di DeepSeek è "Agente = Modello + Harness". Il modello gestisce ragionamento e generazione. L'harness è tutto ciò che permette a quel ragionamento di agire su un filesystem reale e di proseguire senza che tu debba rispiegare il compito a ogni passo.

Gira su Cordis, un framework di plugin antecedente a DeepSeek Harness. Cordis consente alle impostazioni di sostituire in modo indipendente queste parti. Tornerò più avanti sul costo di questa scelta.

Con questa cornice, ecco due idee sbagliate comuni.

DeepSeek Harness non è un modello di IA

Come detto sopra, modello e runtime sono livelli separati. Questa divisione ti consente di cambiare provider senza modificare strumenti o configurazione delle sessioni. Lo stesso runtime può usare DeepSeek, Anthropic, OpenAI o un endpoint compatibile con OpenAI.

DeepSeek Harness è più di un assistente alla programmazione

La modalità Standard crea l'impressione di un assistente di coding, ma è solo una configurazione. Come vedremo, le modalità Minimal e Creator cambiano cosa può usare l'agente. Creare una nuova configurazione richiede comunque lavoro di engineering; gli sviluppatori hanno accesso alle parti.

Come Cordis organizza i plugin di DeepSeek Harness

Come accennato, Cordis è il framework di plugin sotto DeepSeek Harness. Permette a ogni parte di richiedere un servizio senza legarla al codice di un unico provider.

Cordis proviene dall'ecosistema del chatbot Koishi ed è stato creato da uno sviluppatore conosciuto come Shigma; DeepSeek lo distribuisce ed estende. Gli autori descrivono il design nel paper A Programming Paradigm for Spatiotemporal Composability.

Queste basi portano allo slogan principale del progetto e a due termini di Cordis. I nomi suonano accademici, ma il comportamento è abbastanza semplice.

"Tutto è un plugin"

La documentazione dell'architettura di DeepSeek afferma che estendi dsh montando un plugin accanto agli altri. Adapter del modello, strumenti, sessioni, sandbox, storage, scheduling, loop dell'agente e UI sono tutti plugin.

Preso alla lettera, lo slogan esagera. Cordis sta comunque sotto i plugin. Li carica e rimuove, verifica di cosa hanno bisogno ed esegue gli eventi che usano per comunicare tra loro. Cordis è necessario, non un pezzo opzionale in più.

La composabilità spaziale gestisce le dipendenze dei plugin

Un plugin dichiara i servizi di cui ha bisogno senza richiedere una sequenza di avvio scritta a mano. Si attiva quando quei servizi esistono e si disattiva se scompare un servizio richiesto. Le sue dipendenze decidono quando può girare.

DeepSeek chiama questo composabilità spaziale. Le dipendenze dicono a Cordis dove si inserisce un componente, così gli sviluppatori non devono stabilire a mano l'ordine di avvio.

La composabilità temporale annulla gli effetti dei plugin

Cordis tiene traccia anche di registrazioni come event listener, sezioni di prompt e schemi degli strumenti. Rimuovere un plugin rimuove quegli effetti invece di lasciare listener orfani. Questo non annulla un'azione esterna come un comando shell; la reversibilità si applica solo agli effetti tracciati da Cordis.

Architettura di DeepSeek Harness: come si incastra il runtime

Un'istanza in esecuzione è un albero di plugin costruito da impostazioni caricate in un ordine definito. Quelle impostazioni determinano quali parti sono attive.

Cordis collega ogni plugin sostituibile del runtime. Immagine dell'autore.

I servizi Cordis permettono ai plugin di trovarsi

Cordis fornisce una directory condivisa di servizi. I plugin usano chiavi stabili come ctx.tools, ctx.llm, e ctx.sessions invece di importare il codice di un provider specifico. Uno strumento che chiama ctx.llm non ha bisogno di sapere quale adapter del modello c'è dietro.

Preset dell'agente e profili del runtime controllano livelli diversi

Se tutto è sostituibile, qualcosa deve comunque decidere cosa montare per una determinata esecuzione, e DeepSeek Harness risponde su due livelli facili da confondere.

La versione breve: un profilo controlla come parte il programma, mentre un preset controlla cosa può fare l'agente. Se usi solo la web app, puoi saltare le prossime due sottosezioni.

Profili del runtime

Un profilo del runtime (web, headless, sdk, sdk-minimal e acp forniti come template) decide come si avvia l'applicazione e quali bundle di plugin Cordis vengono impilati al boot. La maggior parte dei lettori toccherà questo livello solo eseguendo dsh web o un comando simile.

Preset dell'agente

Un preset dell'agente (Standard, PTC, Minimal o Creator) decide cosa può usare una sessione attiva. Un file di patch può cambiare il preset senza toccare il sorgente di Harness.

Il loop dell'agente coordina turni, step e chiamate agli strumenti

DeepSeek distingue uno step da un turno. Uno step è una richiesta al modello più le sue chiamate agli strumenti. Un turno è zero o più step: si apre prima che il suo primo input venga preso in carico e si chiude quando non c'è più nulla in sospeso. La maggior parte dei turni esegue diversi step prima che l'agente possa rispondere, ma un input rifiutato chiude un turno che non ha speso step.

Un turno può contenere diversi step. Immagine dell'autore.

Le sessioni usano un log di eventi in sola append

Questa è la parte che ritengo più importante. Una sessione è un log di eventi tipizzati in sola append, non un array di messaggi di chat. Harness costruisce la cronologia del modello a partire da quel log, e la documentazione delle sessioni richiede che qualsiasi cosa inviata al modello sia recuperabile da esso.

Ripresa, fork, ricerca, replay e la vista Trajectory si basano tutte su quel flusso di eventi.

Riderivare la cronologia non è una riesecuzione deterministica. L'output del modello e lo stato esterno possono differire, ma il log fornisce comunque un resoconto ispezionabile di ciò che è accaduto.

La cronologia di sessione è un log in sola append. Immagine dell'autore.

Come DeepSeek Harness controlla strumenti e sandbox

Un modello può richiedere uno strumento per nome, ma non può eseguirlo direttamente. Tra la richiesta e una modifica al filesystem ci sono due controlli separati.

La pipeline di esecuzione degli strumenti

La chiamata passa attraverso un controllo delle policy, l'esecuzione e la gestione del risultato. Il modello sceglie lo strumento; il runtime decide se e come viene eseguito.

Il runtime decide come vengono eseguiti gli strumenti. Immagine dell'autore.

Sandboxing vs. approvazioni

• Approvazione chiede se l'utente debba confermare un'azione. 
• Sandboxing limita dove e come viene eseguita. 

DeepSeek le mantiene separate, anche se i preset di permessi raggruppano entrambi i controlli, proprio come un runtime di container separa i permessi di processo dai confini di esecuzione.

Vale la pena sottolinearlo ora, perché ci tornerò nella sezione limitazioni: dire a un modello in un system prompt di "leggere solo i file" è un suggerimento che può seguire, non un confine imposto come una restrizione di sandbox a livello di OS.

Modalità di DeepSeek Harness: Standard, PTC, Minimal e Creator

DeepSeek Harness offre quattro modalità diverse. Nessuna di queste quattro è superiore alle altre. Sono quattro risposte a "quanto del runtime dovrebbe essere esposto a questa sessione", e quella giusta dipende dal compito. Come mostrato nella sezione sull'architettura, ogni modalità cambia l'insieme di strumenti a disposizione dell'agente.

Quattro modalità condividono una base di runtime. Immagine dell'autore.

Modalità Standard

La base general-purpose: 

• Modifica file
• Accesso alla shell
• Ricerca su file e web
• Skills
• Pianificazione
• Obiettivi
• Sottoagenti
• Workflow

Per il lavoro ordinario su repository, è da qui che inizierei.

Modalità PTC

La modalità PTC mantiene quasi tutto il set di strumenti di Standard ma cambia come il modello vi accede. (Dalla versione 0.1.2, la modalità Web PTC non espone più di default lo strumento general-purpose workflow.) 

Invece di richiedere singoli strumenti su più step del modello, il modello scrive un programma contro un SDK generato. Quel programma può chiamare diversi strumenti tramite run_code. Ogni chiamata passa comunque dagli stessi controlli di policy, quindi PTC cambia come il modello enuncia il piano, non cosa gli è consentito fare.

La pagina di prodotto usa ancora l'etichetta "Code mode", ma una release ufficiale più recente l'ha rinominata in modalità PTC mantenendo leggibili le vecchie conversazioni. Userò sempre modalità PTC; le FAQ tornano su cosa potrebbero significare quelle iniziali.

Modalità Minimal

La modalità Minimal riduce l'ambiente a due strumenti: una shell persistente e un editor di file con sostituzione di stringhe. DeepSeek la usa per i benchmark dei modelli perché i risultati dei test dipendono in parte dall'harness del modello, non solo dai suoi pesi.

Modalità Creator

La modalità Creator consente agli sviluppatori di ispezionare il runtime e testare i plugin Cordis in memoria. Serve per costruire preset, e non la definirei auto-migliorante in un senso più profondo.

Cosa rende DeepSeek Harness diverso da altri framework di agenti?

DeepSeek Harness si distingue da molti framework di agenti rendendo sostituibili le parti più basse del runtime. Stavo quasi per includerlo nella sezione sull'architettura, ma la distinzione è facile da perdere. Cordis gestisce queste modifiche attraverso un unico sistema di plugin.

Puoi cambiare come opera l'agente, non solo gli strumenti che può chiamare. Il log di eventi crea anche un'esecuzione che gli sviluppatori possono ispezionare, invece di leggerla solo come una trascrizione di chat. Le modalità Minimal e Creator consentono poi di testare il runtime da direzioni opposte.

DeepSeek Harness vs. Claude Code, Codex e OpenCode

Una checklist di funzionalità perderebbe il punto. Ogni concorrente supporta estensioni; la domanda utile è quali parti gli sviluppatori possono cambiare. La distinzione sembra piccola, ma non lo è. Il nostro confronto dedicato tra Harness e Claude Code usa lo stesso modello in entrambi e copre setup, log e costi.

DeepSeek Harness vs. Claude Code

Claude Code supporta istruzioni di progetto, skills, hook, MCP, sottoagenti e un Agent SDK, e mantiene fisso il suo loop integrato. DeepSeek Harness consente agli sviluppatori di sostituire loop, adapter del modello e livello di storage tramite impostazioni.

DeepSeek Harness vs. Codex

Codex richiede un confronto più accurato perché anche la sua CLI e l'App Server sono open source. Fornisce un agent harness che gli sviluppatori estendono tramite punti di ingresso documentati. DeepSeek Harness è costruito attorno alla modifica del runtime stesso. Offrono livelli di controllo diversi.

DeepSeek Harness vs. OpenCode

OpenCode è già open source, funziona con diversi provider di modelli e usa un'architettura client-server. Puoi configurarne strumenti, permessi, sessioni e provider. I suoi plugin estendono un core server fisso, mentre DeepSeek rende sostituibili anche loop e archivio sessioni.

Quando usare DeepSeek Harness

Sostituire parti del runtime non è utile di per sé. Il controllo extra conta solo quando risolve un problema che hai già.

• Quando il runtime stesso fa parte del progetto. Se stai modificando adapter del modello, loop dell'agente, storage o comportamento delle sessioni, non solo costruendo sopra un agente, questa è la scelta più diretta.
• Quando confronti modelli in un ambiente controllato. Usare lo stesso runtime mantiene più elementi del test fissi quando cambi modello, anche se i modelli possono comunque differire nell'uso degli strumenti e nello stile di ragionamento.
• Quando è importante il debugging di un'esecuzione complessa. Il log degli eventi di sessione e la vista Trajectory facilitano la ricostruzione di cosa ha visto un modello e quali strumenti sono stati eseguiti.
• Quando testi gli internals degli agenti. La modalità Creator e Cordis sono per sviluppatori che studiano come sono composti gli agenti, più che per chi ha solo bisogno di codice applicativo scritto.

Potrebbe essere superfluo per semplici chiamate di modello o per team che vogliono un agente di coding pronto all'uso senza toccarne gli internals. Sostituire più parti vale lo sforzo extra solo quando quel controllo risolve un problema reale.

Limitazioni di DeepSeek Harness: stato di Developer Preview e rischi di sicurezza

Tutta l'architettura di cui sopra conta poco senza un resoconto chiaro di dove oggi questo strumento è carente.

È ancora una developer preview

Il repository di DeepSeek afferma chiaramente che ci saranno breaking change. È già successo: la rinomina da Code a PTC è arrivata con modifiche alle API delle sessioni e la rimozione di un'opzione di storage SQLite opzionale. Fissa le versioni. Saltare questo passaggio e sperare che la configurazione resti stabile non è un piano.

Più controllo significa anche più complessità

Rendere sostituibile una parte maggiore del runtime dà anche agli sviluppatori più cose da imparare: dipendenze dei plugin, impostazioni, differenze tra provider e compatibilità di versione. È il solito trade-off tra comodità e controllo.

DeepSeek Harness è locale?

DeepSeek Harness archivia per impostazione predefinita contenuti di sessione, registri degli strumenti e impostazioni in locale, secondo la sua informativa sul trattamento dati. Puoi disattivare i report anonimi su impostazioni ed elenchi di progetti. 

Ma un provider di modelli esterno, uno strumento web, un server MCP o un plugin possono comunque inviare dati fuori dalla tua macchina secondo le proprie policy. "Local-first" non copre ogni servizio a cui ti connetti.

Eseguire agenti comporta rischi di sicurezza

Un runtime che può modificare file, eseguire comandi e caricare plugin di terze parti può causare danni reali. L'avviso di sicurezza di DeepSeek afferma che il progetto non ha avuto un audit di sicurezza. Sandboxing, approvazioni e controlli di permessi riducono il rischio ma non garantiscono isolamento.

Eseguire il software sulla tua macchina non elimina quel rischio. Usa permessi limitati e un ambiente usa e getta per lavoro non affidabile, e fai attenzione a contenuti che possono contenere istruzioni nascoste.

Perché il comportamento dell'agente dipende da più del modello

Il comportamento dell'agente dipende dal runtime oltre che dal modello. Torniamo a "Agente = Modello + Harness", e la stessa divisione si applica agli agenti LLM aldilà di DeepSeek.

Ciò che un modello può produrre dipende dai suoi pesi. Ciò che fa un agente dipende anche da quale contesto arriva al modello, quali azioni è autorizzato a compiere e quanto è vincolata l'esecuzione. Nulla di questo risiede nei pesi.

DeepSeek Harness mette in mostra lo strato circostante suddividendolo in parti nominate che gli sviluppatori possono sostituire. La modalità Minimal mostra perché questo conta oltre DeepSeek: un punteggio di benchmark riflette in parte l'harness usato per il test, non solo il modello. L'harness non rende un modello più intelligente. Cambia l'impostazione in cui il modello lavora.

Conclusione

La frase d'apertura è quella da ricordare: il modello ragiona, ma il runtime decide a cosa può arrivare quel ragionamento e cosa può fare. DeepSeek Harness rende modificabile quel runtime, dall'adapter del modello e gli strumenti fino all'archivio delle sessioni e al loop dell'agente.

Quel controllo ha un costo. Sostituire più parti del runtime significa dover gestire più del suo setup, dei cambi di versione e dei confini di sicurezza. Un'anteprima per sviluppatori con accesso alla shell non è qualcosa da installare e dimenticare.

La mia opinione è semplice: usa DeepSeek Harness quando il runtime stesso fa parte del lavoro. Se ti servono solo modifiche al repository, un agente di coding pronto ti chiederà meno.

Il nostro tutorial su DeepSeek Harness copre il setup. La guida alle alternative a Claude Code confronta altri agenti di coding, mentre Introduzione agli agenti AI copre le basi date per scontate in questo articolo.