Come il generatore di libri InkOS mantiene il contesto sotto controllo attraverso centinaia di capitoli

Chiunque abbia provato a scrivere narrativa lunga con modelli linguistici conosce quel momento in cui tutto inizia a sgretolarsi. Verso il terzo o quarto capitolo, l'eroe "resuscita" inaspettatamente un compagno che era morto, confonde le location e lo stile narrativo scivola in generalizzazioni noiose come "ha imparato una lezione importante e andato avanti".

Il problema qui non è solo la dimensione della finestra di contesto. Anche se inserisci cinquantamila parole precedenti nella rete neurale, il modello inizierà comunque a sbagliare i dettagli o a produrre cliché.

Recentemente ho scoperto un progetto open chiamato InkOS (che ha già raccolto oltre 8.500 stelle su GitHub). È un framework TypeScript completo per la gestione narrativa, la generazione di web novel, giochi interattivi e scenari. Gli autori hanno cercato di consolidare il controllo su memoria, stile e trama.

Qual è l'idea e perché i prompt ordinari non sono sufficienti

InkOS gestisce la creazione del testo attraverso una catena di agenti specializzati. Invece di chiedere a una singola rete neurale di "scrivere un capitolo tenendo conto della trama", il sistema divide il processo in ruoli chiari.

Un agente (Planner) definisce la direzione del capitolo corrente, un altro (Writer) produce la bozza, un terzo (Observer) estrae fatti sul mondo e sui personaggi dal testo, e un quarto (Auditor) controlla la versione finita per contraddizioni.

Il testo passa attraverso un imbuto di controllo:

Se l'auditor nota che un personaggio improvvisamente estrae una spada che era stata persa due capitoli prima, il capitolo viene rispedito indietro per una revisione automatica da parte di un agente editor.

Memoria a tre livelli e protezione contro le allucinazioni

L'aspetto tecnico più interessante di InkOS riguarda come il progetto memorizza lo stato del mondo fittizio. Se ti affidi all'agente LLM stesso per riscrivere l'intero stato in un file Markdown, la struttura si degraderà rapidamente.

Gli autori hanno applicato un approccio ibrido:

1. Database rigorosamente strutturato. Lo stato dell'inventario, i dispositivi della trama, gli stati delle relazioni tra personaggi vengono memorizzati in formato JSON e validati con schemi Zod. L'agente non emette nuovamente l'intero JSON, ma solo un pacchetto delta differenziale (JSON delta), che il codice del progetto applica allo stato in modo immutabile.
2. Database SQLite locale. Nelle versioni Node.js 22+, il sistema si connette automaticamente a SQLite per il recupero vettoriale e per keyword di eventi passati, annotazioni compresse e fatti.
3. Proiezioni in Markdown. File come current_state.md o pending_hooks.md vengono generati automaticamente dal JSON validato. Servono come riferimento visivo per l'autore umano e per il passaggio nel contesto del generatore.

Grazie a questa separazione, il modello non può eliminare accidentalmente un ramo della trama o corrompere il formato del file state.json.

Combattere la lucidatura della rete neurale e audit automatico

Tutti hanno notato lo stile caratteristico dei modelli linguistici. Uso eccessivo di riempitivi, lunghezza uniforme delle frasi, amore per le conclusioni morali profonde alla fine di ogni paragrafo.

InkOS include un modulo integrato di controllo del testo con 37 parametri. Monitora il ritmo delle frasi, la frequenza di ripetizione delle parole e caccia i cliché banali.

Inoltre, il motore include un comando di analisi dello stile:

inkos style analyze sample_author.txt
inkos style import sample_author.json --book my-novel

L'utilità estrae un'impronta digitale numerica dal testo di riferimento (distribuzione della lunghezza delle frasi, dizionario delle frequenze, densità del dialogo) e genera una linea guida. Quando genera nuovi capitoli, produce non testo astratto, ma materiale rigorosamente adattato a questa impronta.

Mondi interattivi e RPG testuali

Nella versione 1.5, gli sviluppatori hanno aggiunto la modalità Play di InkOS. È uno strumento per lanciare mondi testuali con azioni libere o diramazione a turni.

In modalità Play, viene impostato il cosiddetto contratto del mondo. Ad esempio, regole di indagine detective o simulatore di sopravvivenza. Un agente di sistema traccia il tempo, l'inventario, gli oggetti e le prove, generando interfacce di scelta o elaborando l'input dell'utente in linguaggio naturale.

Sotto il cofano, vengono utilizzati meccanismi per la generazione dinamica di illustrazioni per scene e oggetti, oltre al supporto per pacchetti di abilità standard SKILL.md.

Come funziona internamente

Il progetto è interamente scritto in TypeScript. L'interfaccia web (Studio) gira su Vite, React e Hono. La console interattiva è implementata tramite TUI, e una CLI tradizionale è disponibile per gli appassionati di automazione.

Il framework degli agenti è costruito sopra la libreria pi-mono (@mariozechner/pi-agent-core).

Una soluzione comoda è il routing flessibile dei modelli. La scrittura di narrativa può essere assegnata, ad esempio, a Claude 3.5 Sonnet o Kimi K2.7, mentre i compiti di audit, l'assemblaggio di JSON delta e la validazione possono essere delegati a modelli più veloci ed economici tramite OpenRouter, Gemini o Ollama locale.

La configurazione del routing viene impostata tramite coppie:

inkos config set-model writer kimi-k2.5 --provider custom --base-url https://api.moonshot.cn/v1
inkos config set-model auditor gemini-2.5-flash --provider google

Come eseguire localmente

Il pacchetto è disponibile su npm:

npm i -g @actalk/inkos

Creare il tuo primo libro e lanciare uno studio locale richiede solo tre comandi:

inkos init my-story
cd my-story
inkos studio

Si apre un pannello web nel browser sulla porta 4567. Lì puoi inserire le chiavi API per i provider richiesti, impostare il concetto dell'opera e lanciare il processo di pianificazione dei primi capitoli.

Sono disponibili comandi diretti per il lavoro da console:

inkos book create --title "Забытый код" --genre sci-fi
inkos plan chapter Забытый код --context "Герой обнаруживает странный архив в серверной"
inkos write next Забытый код

Chi trarrà beneficio da questo progetto

InkOS non è solo un altro wrapper attorno a ChatGPT. È un ambiente di sviluppo strutturato per chi lavora sistematicamente con la narrativa.

Il progetto sarà utile per:

• Designer narrativi e sceneggiatori di giochi per sviluppare missioni e dialoghi ramificati.
• Autori di web novel che hanno bisogno di un assistente che mantenga cronologia e fatti.
• Sviluppatori che creano bot AI basati su testo con memoria e regole interne del mondo.

Naturalmente, il codice sorgente e i prompt sono orientati verso il cinese e l'inglese, ma la configurazione flessibile dei prompt-pack all'interno della cartella prompt/ permette di adattare la generazione a qualsiasi lingua. La licenza AGPL-3.0 permette di distribuire il sistema localmente sul proprio server senza dipendere da cloud proprietari.