diff --git a/README.md b/README.md index 5abe5cd..7a86304 100644 --- a/README.md +++ b/README.md @@ -62,14 +62,18 @@ Verificato: da Linux/WSL entrambi gli eseguibili; da Windows nativo (PowerShell - I motori (`claude`, `codex`) devono essere installati e nel PATH dello stesso sistema: vedi [docs/INSTALL.md](docs/INSTALL.md). ## Immagini nelle risposte (wiki con catalogo di figure) -Se la risposta contiene `![didascalia](percorso)` e il file esiste, la chat mostra l'immagine; altrimenti compare il testo `[didascalia]`. Gli URL `http(s)` non si scaricano. Un percorso relativo si cerca nella cartella dell'eseguibile e poi in quelle superiori, quindi funziona con una **wiki** come `cyber-tesi`: +Non esiste (ancora) uno standard per cartella e catalogo delle immagini: la struttura qui sotto è solo un **esempio** e può cambiare. L'app non la conosce: mostra il file indicato dal percorso scritto nella risposta, ovunque stia. + +Se la risposta contiene `![didascalia](percorso)` e il file esiste, la chat mostra l'immagine; altrimenti compare il testo `[didascalia]`. Gli URL `http(s)` non si scaricano. Un percorso relativo si cerca nella cartella dell'eseguibile e poi in quelle superiori, quindi funziona con una **wiki** (cartella di pagine markdown con un indice, un catalogo delle figure e le immagini) anche se l'eseguibile sta in una sottocartella dedicata alle sole query: ``` -cyber-tesi/ radice del progetto, con CLAUDE.md (le istruzioni per il motore) - raw/immagini.json catalogo: metadati di ogni figura (file, didascalia, posizione, avvertenze) - raw/immagini/.jpg cartella delle immagini - agent-wiki-ui/agent-wiki-ui l'eseguibile (il motore parte qui e legge il CLAUDE.md della cartella superiore) +/ radice del progetto, con CLAUDE.md (schema completo della wiki) + index.md indice delle pagine, con gli id delle figure di ogni pagina + .json catalogo: metadati di ogni figura (file, didascalia, posizione, avvertenze) + / le immagini + query/CLAUDE.md istruzioni solo-query (sola lettura, instradamento per indici, regole per le figure) + query/agent-wiki-ui l'eseguibile, da avviare da qui: il motore legge sia query/CLAUDE.md sia quello della radice ``` -Il catalogo lo legge il motore, non l'app: nel `CLAUDE.md` si chiede di trovare la figura nel catalogo e di citarla con un percorso relativo alla radice, per esempio `![Figura 1](raw/immagini/.jpg)`, con sotto la didascalia, la posizione e il link alla nota della figura. L'app mostra l'immagine e lascia la didascalia come testo markdown. Dettagli: [ADR-0006](docs/adr/0006-immagini-nel-markdown.md). +Il catalogo lo legge il motore, non l'app: il `CLAUDE.md` chiede di trovare la figura nel catalogo e di citarla con un percorso relativo alla radice (`![Figura 1](/)`), con sotto la didascalia, la posizione e il link alla nota della figura. L'app mostra l'immagine e lascia la didascalia come testo markdown. Dettagli: [ADR-0006](docs/adr/0006-immagini-nel-markdown.md). Per preparare una wiki alle query (indice con la mappa delle figure, catalogo, istruzioni solo-query) c'è una convenzione, [ADR-0007](docs/adr/0007-schema-wiki-per-query-con-immagini.md),. ## Piattaforme Windows e Linux con lo stesso codice ([ADR-0001](docs/adr/0001-gui-multipiattaforma-avalonia.md)). Motori supportati: Claude Code e Codex CLI, già installati da terminale; Antigravity CLI è pianificato: [ADR-0002](docs/adr/0002-motori-cli-claude-codex-antigravity.md). diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 5db0b2a..0106aa2 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -43,6 +43,7 @@ Da [MVP.md](MVP.md). Restano non spuntati finché non hanno test automatici (reg | [0004](adr/0004-aggiornamento-dei-cli.md) Aggiornamento dei CLI | Proposta | | [0005](adr/0005-windows-senza-console.md) Windows senza console | Proposta | | [0006](adr/0006-immagini-nel-markdown.md) Immagini nel markdown (solo file locali) | Proposta (implementata, test verdi) | +| [0007](adr/0007-schema-wiki-per-query-con-immagini.md) Schema di una wiki interrogabile, con immagini | Proposta (solo documentazione; nessun codice) | ## Per chiudere l'MVP Proposta, derivata dai punti aperti sopra; da confermare. diff --git a/docs/README.md b/docs/README.md index ddd99ee..d796dd8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -53,3 +53,4 @@ Non si scrive nulla nei puntatori: ogni modifica va in AGENT.md. Per un altro st | [0004](adr/0004-aggiornamento-dei-cli.md) | Aggiornamento dei CLI dalle Impostazioni | Proposta | | [0005](adr/0005-windows-senza-console.md) | Windows: eseguibile senza finestra di console | Proposta | | [0006](adr/0006-immagini-nel-markdown.md) | Immagini nel markdown: solo file locali | Proposta | +| [0007](adr/0007-schema-wiki-per-query-con-immagini.md) | Schema di una wiki interrogabile, con immagini | Proposta | diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index b87964e..9b5b989 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -23,6 +23,7 @@ Dettagli dell'MVP in [MVP.md](MVP.md). Stadio attuale e debiti: [PROJECT_STATE.m - [x] GUI: cronologia chat (salvataggio JSON, barra laterale, riapertura con `--resume`, eliminazione) - [ ] GUI: streaming della risposta (`--output-format stream-json`), stop, rinomina/ricerca chat - [x] GUI: immagini nel markdown da percorso locale, con ripiego sul testo alternativo ([ADR-0006](adr/0006-immagini-nel-markdown.md); test MD-14, MD-19…MD-30); immagini remote rimandate +- [x] Schema di una wiki interrogabile con immagini: convenzione per le istruzioni solo-query, l'indice e il catalogo ([ADR-0007](adr/0007-schema-wiki-per-query-con-immagini.md)); da provare con la chat reale su una wiki di esempio - [ ] Config file accanto all'exe - [ ] Test automatici e CI (vedi Fase 6) diff --git a/docs/TESTING.md b/docs/TESTING.md index bcb85f1..82e0293 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -187,7 +187,7 @@ Si provano con `FakeClaude`/`FakeCodex` che rispondono a `--version` e `update`; | MD-25 | Immagine dentro un link, in una lista o in una tabella ⇒ resa senza rompere intervalli dei link (MD-13) né il layout | R | `Immagine_in_contesti_annidati` | [x] | | MD-26 | Cambio di tema con immagini presenti ⇒ vista ricostruita, immagini ancora mostrate | R | `Immagine_cambio_tema` | [x] | | MD-27 | Il caricamento è in background: subito dopo il rendering c'è il segnaposto `[alt]` e un'immagine in attesa; a fine decodifica compare l'immagine; un file corrotto lascia `[alt]` | R | `Immagine_caricamento_in_background` | [x] | -| MD-28 | Percorso relativo non presente nella cartella dell'exe ma in una cartella superiore (radice del progetto, es. `raw/immagini/` con l'exe in una sottocartella) ⇒ immagine mostrata | R | `Immagine_percorso_relativo_alla_radice` | [x] | +| MD-28 | Percorso relativo non presente nella cartella dell'exe ma in una cartella superiore (radice del progetto, es. `figure/` con l'exe in una sottocartella) ⇒ immagine mostrata | R | `Immagine_percorso_relativo_alla_radice` | [x] | | MD-29 | Se il file esiste in più cartelle, vince la più vicina all'exe; se non esiste in nessuna ⇒ testo alternativo | R | `Immagine_cartella_piu_vicina` | [x] | | MD-30 | Struttura tipo wiki (catalogo JSON + cartella immagini + risposta con immagine, didascalia e link `[[fig-NNN]]` sotto): l'immagine compare e la didascalia resta testo; l'app non legge il JSON | R | `Immagine_risposta_stile_wiki` | [x] | | MD-15 | HTML grezzo disabilitato: i tag compaiono come testo, non come elementi | R | `Html_disabilitato` | [ ] | diff --git a/docs/adr/0006-immagini-nel-markdown.md b/docs/adr/0006-immagini-nel-markdown.md index 5d0fc5c..4de38ba 100644 --- a/docs/adr/0006-immagini-nel-markdown.md +++ b/docs/adr/0006-immagini-nel-markdown.md @@ -22,8 +22,9 @@ Il renderer markdown ([Gui/MarkdownView.cs](../../src/agent-wiki-ui/Gui/Markdown ## Decisione - `![alt](destinazione)` mostra l'immagine se la destinazione è un **percorso locale**: assoluto, relativo oppure un URI `file://`. -- **Percorsi relativi: radice del progetto.** Il motore gira nella cartella dell'exe, ma le istruzioni che segue (il `CLAUDE.md` di una wiki) stanno di solito in una cartella superiore e scrivono i percorsi relativi a *quella* radice (esempio: la wiki `cyber-tesi`, con l'exe in `cyber-tesi/agent-wiki-ui/` e le istruzioni «`![Figura N](raw/immagini/)`, percorso relativo alla radice del repo»). Un percorso relativo si cerca quindi nella cartella dell'exe e poi in ciascuna cartella superiore, fino alla radice del filesystem; vince la prima in cui il file esiste (la più vicina all'exe). -- **Cataloghi e metadati restano del motore.** Struttura tipo `cyber-tesi`: un catalogo JSON con i metadati delle figure (`raw/immagini.json`: file, didascalia stampata e generata, posizione, avvertenze) e una cartella delle immagini (`raw/immagini/`). Chi legge il catalogo e sceglie le figure è il motore, guidato dalle istruzioni della wiki; l'app non legge né interpreta il catalogo: mostra le immagini che la risposta cita in markdown, e la didascalia, la posizione e le avvertenze che il motore scrive sotto l'immagine sono testo markdown normale. +- **Percorsi relativi: radice del progetto.** Il motore gira nella cartella dell'exe, ma le istruzioni che segue (il `CLAUDE.md` di una wiki) stanno di solito in una cartella superiore e scrivono i percorsi relativi a *quella* radice (esempio: una wiki con l'exe in `/query/`, accanto a un `CLAUDE.md` solo-query, e istruzioni del tipo «`![Figura N](/)`, percorso relativo alla radice del repo»). Un percorso relativo si cerca quindi nella cartella dell'exe e poi in ciascuna cartella superiore, fino alla radice del filesystem; vince la prima in cui il file esiste (la più vicina all'exe). +- **Nessuno standard imposto (prototipo).** L'app non conosce né una cartella delle immagini né un formato di catalogo: la cartella delle immagini e il catalogo sono la convenzione di ciascuna wiki, non un requisito. Cartella e catalogo possono cambiare; la wiki lo dice al motore nelle sue istruzioni, e l'app mostra qualunque file locale raggiungibile con il percorso scritto nella risposta. +- **Cataloghi e metadati restano del motore.** Struttura tipo di una wiki con figure: un catalogo JSON con i metadati delle figure (file, didascalia stampata e generata, posizione, avvertenze) e una cartella delle immagini. Chi legge il catalogo e sceglie le figure è il motore, guidato dalle istruzioni della wiki; l'app non legge né interpreta il catalogo: mostra le immagini che la risposta cita in markdown, e la didascalia, la posizione e le avvertenze che il motore scrive sotto l'immagine sono testo markdown normale. - Formati: png, jpg/jpeg, gif (primo fotogramma), webp, bmp. Altre estensioni ⇒ ripiego. - Limiti: file fino a **20 MB**; se l'immagine è più larga di **1600 px** si decodifica a 1600 px di larghezza, per non occupare memoria inutile. In visualizzazione l'immagine non supera la larghezza della colonna dei messaggi (proporzioni mantenute) e non è mai ingrandita oltre l'originale. - Un paragrafo fatto solo di immagini le mostra come blocchi; un'immagine dentro una riga di testo (o dentro un link) è inline, con larghezza massima di 480 px. @@ -40,6 +41,7 @@ Il renderer markdown ([Gui/MarkdownView.cs](../../src/agent-wiki-ui/Gui/Markdown - Quali formati decodifica davvero Avalonia 12 con Skia su Windows e Linux (in particolare webp e gif) e se il limite di 20 MB è adeguato. - Il comportamento dei percorsi Windows (`C:\…`, UNC) e di quelli WSL (`/mnt/c/…`). - Se la ricerca nelle cartelle superiori debba fermarsi alla prima cartella con un marcatore di progetto (`CLAUDE.md`, `.git`) invece di salire fino alla radice del filesystem. +- Se e quando emergerà uno standard per cataloghi e cartelle delle immagini (nomi, campi minimi come file, didascalia, posizione), valutare un nuovo ADR; per ora è fuori dall'app. ## Riferimenti - [MVP.md](../MVP.md) → "GUI (chat)"; matrice MD-14, MD-19…MD-30 in [TESTING.md](../TESTING.md). diff --git a/docs/adr/0007-schema-wiki-per-query-con-immagini.md b/docs/adr/0007-schema-wiki-per-query-con-immagini.md new file mode 100644 index 0000000..c3bfd9b --- /dev/null +++ b/docs/adr/0007-schema-wiki-per-query-con-immagini.md @@ -0,0 +1,62 @@ +# ADR-0007 — Schema di una wiki interrogabile, con immagini (prototipo) + +- **Stato**: Proposta +- **Data**: 2026-10-15 +- **Collegato a**: [ADR-0006](0006-immagini-nel-markdown.md) (l'app mostra le immagini citate nella risposta) + +## Contesto +agent-wiki-ui è il terminale di chat per interrogare una wiki mantenuta da un motore (Claude Code, Codex), per esempio una wiki di studio o di documentazione tecnica: pagine markdown, un indice, un catalogo JSON delle figure con i metadati e una cartella di immagini. Per rispondere in modo strutturato — meglio di un RAG, che recupera frammenti di testo e perde le relazioni — il motore deve sapere **dove cercare** (indice → pagina → tabella o figura) e **come citare** un'immagine perché la chat la stampi. Oggi questo sapere sta in un file scritto per una sola wiki. Non esiste uno standard: la cartella delle immagini e il formato del catalogo cambiano da wiki a wiki, ed è un prototipo. + +## Criteri di decisione +1. Un solo posto per i percorsi delle immagini, senza duplicarli a mano. +2. Le mappe sono derivate dal catalogo (si rigenerano), non scritte a mano. +3. Nessuna cartella o nome di file imposti: la wiki dichiara la sua struttura. +4. Degrado sicuro: un percorso sbagliato dà `[alt]` nella chat (ADR-0006), mai un errore. +5. Nessun codice nell'app: la logica sta nelle istruzioni al motore e negli script della wiki. +6. Pochi campi minimi, perché lo standard possa nascere dall'uso. + +## Opzioni considerate +| Opzione | Esito | Motivo | +|---|---|---| +| Solo RAG sul testo (embedding di `search_text`) | Scartata come unica via | Perde la struttura che rende affidabile la risposta: dato → pagina unica, avvertenze, difetti noti, figura → file. Resta come ripiego (ricerca testuale). | +| L'app legge il catalogo e inserisce le immagini nelle risposte | Scartata | Lega l'app a un formato non standard e duplica la scelta delle figure, che il motore fa già leggendo la domanda. | +| **Schema in tre parti, letto dal motore; l'app stampa** | **Scelta** | Conserva la struttura, non tocca l'app, si adatta a wiki diverse. | + +## Decisione +Una wiki interrogabile ha tre parti. Il formato è una convenzione consigliata, non un requisito dell'app. + +1. **Indice** (`index.md`): catalogo delle pagine, una riga per pagina, `- [[pagina]] — sintesi`. Una pagina con figure aggiunge in coda gli id del catalogo: `· figure: fig-026, fig-027`. L'indice non elenca le figure una per una e non contiene percorsi di file. +2. **Catalogo delle figure** (JSON, nome e posizione dichiarati nello schema della wiki). Campi minimi per figura: + - `id` stabile, `label` (ad es. «Figura 26»); + - `caption_printed` (testo della fonte, alla lettera) e, a parte, ogni testo generato dall'immagine, contrassegnato come non verificato; + - `location` (sezione e riga nella fonte); + - `panels[]` con `file` e `path` (relativo alla cartella del catalogo) e una descrizione; + - `quality`: `flags` e `review_notes`. + Indici facoltativi per sezione, composto, tipo e concetto. L'ordine di preferenza per trovare una figura è: indice dell'indice → pagina → `figures` nel frontmatter → indici del catalogo → ricerca testuale. +3. **Istruzioni per le query**: un file `CLAUDE.md` (per Codex `AGENTS.md`) in una cartella dedicata sotto la radice della wiki, da cui si avvia l'app. Si aggiunge a quello della radice e prevale su di esso. Impone la **sola lettura**, instrada le domande per tipo verso l'indice giusto e fissa le regole per le immagini. + +**Regole per le immagini nella risposta:** +- Il percorso si ricava da catalogo e `path`, si **verifica che esista** e si scrive **relativo alla radice** della wiki, senza `..` (l'app lo cerca nella sua cartella e poi nelle superiori, ADR-0006). +- Subito sotto: didascalia stampata alla lettera, posizione nella fonte, link alla nota della figura; una riga di avvertenza se `flags` o `review_notes`. +- Ciò che deriva dall'immagine (descrizioni, valori letti da un grafico) si dichiara non verificato. Massimo 3-4 immagini per risposta. + +**Percorsi derivati.** Se il catalogo ha percorsi relativi alla propria cartella, la wiki genera con uno script una mappa figura → percorso dalla radice → pagine che la citano (per esempio colonne in più di `figure-indice.md`). Lo script, e un controllo in fase di lint che ogni percorso della mappa esista, sono della wiki, non di questo repo. + +**Chi fa cosa** +| Parte | Compito | +|---|---| +| Wiki | Mantiene indice, catalogo e immagini; rigenera la mappa; controlla che i percorsi esistano | +| Motore | Instrada la domanda, legge indici e pagine, sceglie le figure, scrive il markdown con l'immagine e la didascalia | +| App | Stampa il markdown; mostra l'immagine se il file esiste, altrimenti `[alt]` | + +## Conseguenze +**Positive**: una risposta ripercorre indice → pagina → figura invece di cercare frammenti; i percorsi stanno in un solo posto e si rigenerano; l'app non cambia; wiki diverse adottano lo stesso modello cambiando pochi campi. +**Negative**: il rispetto dello schema dipende dal motore che segue le istruzioni (può sbagliare percorso: l'app lo mostra come `[alt]`); la wiki deve mantenere lo script e il controllo dei percorsi; lo standard è provvisorio. + +## Da verificare +- Che Claude Code, avviato dalla cartella dedicata, legga e rispetti sia il file di quella cartella sia quello della radice (prova con la chat reale su una wiki di esempio). +- L'equivalente per Codex (`AGENTS.md`) e come si comporta con le immagini nei suoi comandi. +- Se il campo minimo `path` debba diventare un percorso dalla radice nel catalogo stesso, eliminando la mappa derivata. + +## Riferimenti +- Uso con le immagini: [README.md](../../README.md), sezione «Immagini nelle risposte». diff --git a/tests/agent-wiki-ui.Tests/Gui/MarkdownImageTests.cs b/tests/agent-wiki-ui.Tests/Gui/MarkdownImageTests.cs index a745f03..b3abfb6 100644 --- a/tests/agent-wiki-ui.Tests/Gui/MarkdownImageTests.cs +++ b/tests/agent-wiki-ui.Tests/Gui/MarkdownImageTests.cs @@ -207,14 +207,14 @@ public sealed class MarkdownImageTests : IDisposable Assert.Contains("[guasta]", Text(view)); } - // Struttura tipo wiki: /raw/immagini.json, /raw/immagini/, exe in /agent-wiki-ui/ + // Struttura tipo wiki: /catalogo.json, /figure/, exe in /query/ string Wiki(string name, params string[] files) { var root = Path.Combine(dir, name); - Directory.CreateDirectory(Path.Combine(root, "raw", "immagini")); - Directory.CreateDirectory(Path.Combine(root, "agent-wiki-ui")); - foreach (var f in files) File.WriteAllBytes(Path.Combine(root, "raw", "immagini", f), PngFactory.Create(24, 12)); - File.WriteAllText(Path.Combine(root, "raw", "immagini.json"), "{\"figures\":[]}"); + Directory.CreateDirectory(Path.Combine(root, "figure")); + Directory.CreateDirectory(Path.Combine(root, "query")); + foreach (var f in files) File.WriteAllBytes(Path.Combine(root, "figure", f), PngFactory.Create(24, 12)); + File.WriteAllText(Path.Combine(root, "catalogo.json"), "{\"figures\":[]}"); return root; } @@ -222,7 +222,7 @@ public sealed class MarkdownImageTests : IDisposable public void Immagine_percorso_relativo_alla_radice() { var root = Wiki("wiki-a", "fig1.png"); - var (_, view) = Show("![Figura 1](raw/immagini/fig1.png)", baseDir: Path.Combine(root, "agent-wiki-ui")); + var (_, view) = Show("![Figura 1](figure/fig1.png)", baseDir: Path.Combine(root, "query")); Assert.Single(Images(view)); Assert.DoesNotContain("[Figura 1]", Text(view)); } @@ -231,16 +231,16 @@ public sealed class MarkdownImageTests : IDisposable public void Immagine_cartella_piu_vicina() { var root = Wiki("wiki-b"); - File.WriteAllBytes(Path.Combine(root, "raw", "immagini", "x.png"), PngFactory.Create(30, 30)); - var exeDir = Path.Combine(root, "agent-wiki-ui"); - Directory.CreateDirectory(Path.Combine(exeDir, "raw", "immagini")); - File.WriteAllBytes(Path.Combine(exeDir, "raw", "immagini", "x.png"), PngFactory.Create(10, 10)); + File.WriteAllBytes(Path.Combine(root, "figure", "x.png"), PngFactory.Create(30, 30)); + var exeDir = Path.Combine(root, "query"); + Directory.CreateDirectory(Path.Combine(exeDir, "figure")); + File.WriteAllBytes(Path.Combine(exeDir, "figure", "x.png"), PngFactory.Create(10, 10)); - var (_, view) = Show("![x](raw/immagini/x.png)", baseDir: exeDir); + var (_, view) = Show("![x](figure/x.png)", baseDir: exeDir); var bmp = Assert.IsAssignableFrom(Assert.Single(Images(view)).Source); Assert.Equal(new PixelSize(10, 10), bmp.PixelSize); // vince la cartella più vicina all'exe - var (_, nowhere) = Show("![y](raw/immagini/non-esiste.png)", baseDir: exeDir); + var (_, nowhere) = Show("![y](figure/non-esiste.png)", baseDir: exeDir); Assert.Empty(Images(nowhere)); Assert.Contains("[y]", Text(nowhere)); } @@ -248,18 +248,18 @@ public sealed class MarkdownImageTests : IDisposable [AvaloniaFact] public void Immagine_risposta_stile_wiki() { - var root = Wiki("wiki-c", "455dd3d0.png"); + var root = Wiki("wiki-c", "schema-a.png"); var risposta = """ - La struttura generica è in Figura 1. + Lo schema è in Figura 1. - ![Figura 1](raw/immagini/455dd3d0.png) + ![Figura 1](figure/schema-a.png) - Figura 1 - struttura generica di un dichetopirrolopirrolo · §1.1 r.73 · [[fig-001]] + Figura 1 - schema generale del sistema · §2.1 r.40 · [[fig-001]] """; - var (_, view) = Show(risposta, baseDir: Path.Combine(root, "agent-wiki-ui")); + var (_, view) = Show(risposta, baseDir: Path.Combine(root, "query")); Assert.Single(Images(view)); var text = Text(view); - Assert.Contains("Figura 1 - struttura generica", text); + Assert.Contains("Figura 1 - schema generale", text); Assert.Contains("[[fig-001]]", text); // il link alla nota resta testo: l'app non legge il catalogo JSON } }