← Torna al blog
Aicirca 7 min di lettura

Un motore astrologico da 1.100 regole è ingegnerizzato meglio di molti prodotti AI

Pubblicato 9 nov 2026
Un motore astrologico da 1.100 regole è ingegnerizzato meglio di molti prodotti AI

Un repository TypeScript per il calcolo di carte astrologiche cinesi ha 16.868 stelle su GitHub questa settimana. Più di quanto la maggior parte degli strumenti per sviluppatori ottenga in una vita, per una materia che quasi tutti gli ingegneri occidentali archivierebbero sotto «non è software».

La parte interessante non è la materia. È che il repository è un pezzo di ingegneria migliore di molto di ciò che esce con l'etichetta «prodotto AI».

ziwei-doushu è un motore open source per 紫微斗数, l'astrologia della stella viola, costruito sul sistema insegnato da 倪海厦 nelle sue lezioni 天纪. Le carte sono calcolate interamente nel browser. Non c'è chiave API, non c'è modello, non c'è inferenza. È aritmetica, tabelle di ricerca e 1.100 righe di regole sui pattern.

E arriva con 768 carte di regressione.

Cosa calcola davvero

Se non conosci il dominio, la tabella delle capacità nel README funziona anche come elenco dei modi in cui questo tipo di calcolo va storto.

Correzione del tempo solare vero. Un'ora di nascita registrata su un orologio non è il tempo solare di quel luogo. Il motore corregge la differenza di longitudine più l'equazione del tempo, così una carta calcolata nell'est del paese non finisce un doppio-ora fuori posto. È l'equivalente astrologico di un bug di fuso orario, ed è la prima cosa che si rompe nelle implementazioni ingenue.

Ora legale cinese, dal 1986 al 1991. Il paese ha osservato l'ora legale per sei anni e poi ha smesso. Il motore rileva l'intervallo ma deliberatamente non sottrae l'ora in automatico: il README è esplicito sul fatto che la lettura dell'orologio viene confermata dall'utente e poi convertita tramite un modulo separato, clock-adjust.ts. È l'istinto giusto. Adeguare in silenzio l'input di un utente è come si producono carte sicuramente sbagliate.

Quattro convenzioni per i mesi intercalari. Le scuole non sono d'accordo se un mese intercalare appartenga al mese precedente, a quello successivo, si divida per giorni o valga come mese a sé. Il motore ne fa un'impostazione invece di schierarsi. Lo stesso vale per la luminosità delle stelle, dove tradizioni diverse — e versioni diverse dello stesso software commerciale — usano scale diverse. Sono supportati sette livelli, con una classificazione più grossolana a tre livelli come riserva per la visualizzazione.

Cambio di giorno nella tarda ora zi. Dalle 23:00 alle 23:59 si considera il giorno successivo; dalle 00:00 alle 00:59 il giorno corrente. Se viene indicato il luogo di nascita, il giudizio si basa sul tempo solare vero, così le due regole restano coerenti.

Sopra a questo stanno le quattro trasformazioni e le stelle volanti, dodici collocazioni di spiriti e uccisioni che si spostano tra il livello natale e quello annuale, e una libreria di pattern con più di 1.100 regole: 紫府同宫, 日月并明, 七杀朝斗 e le altre.

A carved wooden printing block and a worn ink brush on coarse paper

I test sono l'argomento

Chiunque può sostenere che il proprio motore di carte è corretto. Questo pubblica una suite di test che gira a ogni push e a ogni pull request, e l'elenco di cosa controlla è la parte più informativa del repository:

768 carte contro le regole ferree del sistema. Gli intervalli di ora legale. Il confine di 立春, dove cambia l'anno in questo calendario e dove quasi ogni implementazione ha un errore di uno. La collocazione di 红鸾 e 天喜. La coerenza dell'indice orario sulle carte di esempio. Le condizioni al contorno dell'indice orario. La validità delle date. Il caso in cui due trasformazioni cadono nello stesso palazzo.

Non è un elenco di marketing. È un elenco scritto da qualcuno che è stato morso da ogni singola voce. Il solo confine di 立春 rompe un'implementazione ingenua ogni anno, per chiunque sia nato nella prima settimana di febbraio.

Installarlo

Tre comandi:

git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm install

Facoltativamente cp .env.example .env.local, poi npm run dev. La verifica è npm run typecheck per un passaggio TypeScript completo e npm test per la suite di regressione del motore delle carte.

Non serve alcuna chiave API per calcolare o mostrare una carta, e nessuna per la carta di compatibilità. Tutto gira lato client, che è la scelta giusta per qualcosa costruito a partire da una data e da un luogo di nascita.

Il confine tracciato dall'autore, e perché è la cosa più onesta del README

La versione open source non include le rotte API del backend. Il calcolo della carta, la visualizzazione e il calcolo della compatibilità sono tutti locali. Ma l'endpoint di interpretazione AI — /api/interpret — e quello di analisi della compatibilità non sono implementati.

Senza quelli, l'interfaccia dice, semplicemente, che la versione open source non include quell'endpoint. E il README aggiunge una riga che risolve una questione che la gente continuava ad aprire: configurare una chiave API non farà funzionare quelle funzioni. La issue #30 esiste perché gli utenti presumevano il contrario.

È una decisione insolita. La mossa facile sarebbe stata rilasciare uno stub che chiama un modello e produce commenti plausibili. Invece il repository è una calcolatrice che rifiuta di fingere di essere un oracolo. Dato quanto della presenza online di questa materia sia nonsenso detto con sicurezza, uno strumento che si ferma al bordo di ciò che sa calcolare merita attenzione.

I nomi, e perché si legge come una libreria

Il codice è organizzato secondo come la disciplina viene davvero insegnata, ed è per questo che è leggibile.

lib/ziwei/algorithm.ts contiene la sequenza di calcolo: collocare il palazzo della vita, determinare il 局 dei cinque elementi, collocare le quattordici stelle maggiori, collocare le stelle ausiliarie, disporre i cicli decennali e annuali. constants.ts contiene i tronchi, i rami e gli elenchi di stelle. sihua.ts contiene le quattro trasformazioni — 禄, 权, 科, 忌 — compresi i casi di autotrasformazione delle stelle volanti. Poi moduli separati per la libreria di pattern e per le tabelle di luminosità.

Se conosci la materia, quella mappatura è ovvia. Se non la conosci, resta leggibile: costanti, poi aritmetica, poi regole, poi dati vicini all'interpretazione. Il dominio è poco familiare e la struttura no, che è l'aspetto del buon software quando lo costruisce qualcuno che capisce la cosa e non la tendenza.

Anche la scelta di TypeScript conta. Le carte sono un albero di palazzi con stelle dentro ognuno, trasformate da regole che si richiamano. Un sistema di tipi che sa esprimere «un palazzo contiene un elenco di stelle, ognuna con un livello di luminosità da un insieme finito» intercetta un'intera classe di bug in compilazione, e il repository esegue un typecheck completo prima di ogni altra cosa. Per un dominio con così tanti valori enumerati non è decorazione.

Perché un blog di AI scrive di un motore astrologico

Perché è il controesempio pulito di come si costruisce la maggior parte dei prodotti AI in questo momento.

Ecco un sistema in cui ogni output è deterministico, ogni regola è attribuibile a una tradizione con un nome, ogni convenzione ambigua è un interruttore di configurazione invece di un'opinione, e la correttezza è imposta da 768 casi di regressione. Fagli la stessa domanda due volte e ottieni la stessa risposta. Nulla è allucinato, perché nulla è generato.

Poi c'è la parte che esplicitamente non fa: interpretare. Il livello di interpretazione — la parte che richiede giudizio, e dove professionisti diversi saranno in disaccordo — è lasciato all'utente o a un endpoint implementato separatamente.

La maggior parte dei team che costruisce con i modelli linguistici trarrebbe vantaggio dal copiare quella separazione. Calcola ciò che si può calcolare, esattamente, ed esplicita dove comincia l'interpretazione. L'alternativa è un sistema che suona autorevole sulla differenza tra le due cose, che è esattamente il modo di fallire che questo repository è stato progettato per evitare.

Il codice è MIT. Il dataset è CC BY 4.0. I testi classici sono di pubblico dominio. Le parole del docente sono coperte da una licenza non commerciale, e il README lo dice. Tutto è documentato, che è più di quanto riescano a fare molti progetti su materiale molto meno controverso.

Non devi credere nella materia per imparare qualcosa dall'ingegneria. Di solito è il segno di una cosa fatta bene.

Articoli correlati