davide/agent-wiki-ui
1
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
agent-wiki-ui/docs/adr/0001-gui-multipiattaforma-avalonia.md
T
davideandClaude Sonnet 5.5 6080a65edc Test del motore Antigravity e allineamento dei doc 
Test unitari e di processo per AG-01…AG-12 e UP-21, righe della matrice spuntate.
Percorsi aggiornati in ROADMAP, ADR-0001 e TESTING; PROJECT_STATE con lo stato dei
test e il debito sulla prova con agy reale.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-22 11:47:08 +02:00

5.1 KiB
Raw Permalink Blame History

ADR-0001 — GUI multipiattaforma in solo C# con Avalonia

  • Stato: Accettata (implementata; restano due verifiche, vedi sotto)
  • Data: 2026-10-15
  • Sostituisce: la parte "GUI WinForms + WebView2 + ui.html" di MVP.md (le sezioni interessate rimandano a questo ADR)

Contesto

L'app nasce per Windows: GUI WinForms con un solo WebView2 che carica ui.html (HTML/CSS/JS), CLI in Program.cs. L'obiettivo ora è avere un eseguibile standalone per Windows e Linux nel modo più semplice, scritto interamente in C#, senza HTML.

Oggi non è possibile: WinForms e WebView2 sono solo Windows, il csproj punta a net10.0-windows, la cronologia usa %LOCALAPPDATA%. La CLI invece è già portabile.

Criteri di decisione

  1. Un solo codice sorgente, compilabile per win-x64 e linux-x64.
  2. Standalone: publish single-file self-contained, senza runtime né librerie da installare oltre a quanto offre un normale desktop.
  3. Solo C# (e XAML per il layout): niente HTML/CSS/JS.
  4. Mantenere la GUI a finestra (chat con barra laterale, markdown, selettori modello/effort).
  5. Riuso massimo della logica esistente (claude -p, sessioni, cronologia JSON, Markdig).

Opzioni considerate

Opzione Esito Motivo
Mantenere WinForms + WebView2 Scartata Solo Windows, e richiede HTML.
Photino / WebView nativa Scartata Richiede HTML e, su Linux, webkit2gtk da installare: non standalone.
Server HTTP locale (Kestrel) + browser Scartata Portabile e semplice, ma la UI resta HTML e non è una finestra propria.
MAUI Scartata Nessun supporto desktop Linux ufficiale.
Terminal.Gui (TUI) Alternativa Puro C#, binario leggero, ma è un'interfaccia da terminale, non una finestra.
Avalonia UI Scelta GUI nativa, C# + XAML, render Skia, Windows e Linux, publish single-file self-contained.

Decisione

La GUI viene riscritta con Avalonia UI:

  • Layout in XAML, logica in C# con ViewModel e binding. ui.html, il protocollo WebMessage e le dipendenze WinForms/WebView2 spariscono.
  • Rendering markdown con un renderer proprio che trasforma l'albero di Markdig in controlli Avalonia (src/agent-wiki-ui/Gui/MarkdownView.cs), al posto della conversione in HTML. Si è scelto di non usare Markdown.Avalonia perché l'ultima versione pubblicata (11.0.x) è per Avalonia 11, mentre si usa Avalonia 12. I link http(s) si aprono nel browser di sistema.
  • Un solo progetto con target net10.0 (non più net10.0-windows). Due publish single-file self-contained: win-x64 e linux-x64.
  • La CLI (Program.cs con argomenti) resta com'è e funziona su entrambi i sistemi.
  • La cronologia usa Environment.SpecialFolder.LocalApplicationData (%LOCALAPPDATA% su Windows, ~/.local/share su Linux), sottocartella <nome-app>/chats. Il nome viene da un'unica costante (vedi Nome del progetto).
  • La logica di avvio del processo (cartella dell'exe, stdin chiuso, ArgumentList) viene estratta in un solo punto condiviso da CLI e GUI, eliminando la duplicazione oggi segnalata in AGENT.md (già CLAUDE.md). Si lega all'astrazione "motore" di ADR-0002.
  • L'aspetto (token di colore, tipografia, accessibilità) resta definito in MVP.md → "Design (UI/UX)", tradotto in risorse/stili Avalonia. Il tema segue il sistema (chiaro/scuro) tramite ThemeVariant.

Conseguenze

Positive

  • Un solo eseguibile per sistema, senza dipendenze di runtime.
  • Nessun HTML/JS da mantenere; il vincolo STA di WinForms/WebView2 non c'è più.
  • Pulizia della duplicazione CLI/GUI.

Negative / costi

  • Riscrittura della sola parte GUI (Gui.cs + ui.html), più ampia di una soluzione basata sul browser.
  • Eseguibile più pesante (include Avalonia/Skia).
  • Perdita di alcune comodità del web: la resa del markdown (tabelle, blocchi di codice, pulsante Copia) dipende dalla libreria scelta e va riprodotta o adattata.
  • Su Linux serve un desktop con X11 o XWayland e le librerie di base (fontconfig ecc.).

Da verificare (prima di passare a "Accettata")

  • Rendering markdown: tabelle, citazioni, liste, codice, link ed enfasi verificati con uno screenshot headless in tema chiaro e scuro (libreria Markdown.Avalonia scartata, vedi Decisione).
  • Il publish single-file linux-x64 (48 MB con compressione) parte; verificato su WSL2 con WSLg. Da verificare su una distribuzione desktop pulita.
  • Il publish single-file win-x64 si compila e la CLI parte (provata da WSL tramite interoperabilità). Da verificare la GUI su Windows nativo.
  • claude viene trovato nel PATH su Linux e la CLI mantiene exit code e codice 127 (provato con un claude finto).
  • Il tema chiaro/scuro segue il sistema anche su Linux (impostato con RequestedThemeVariant="Default"; non verificato su un desktop reale).
  • Le chat esistenti restano leggibili (stesso formato JSON). Se il nome cambia cambia anche la cartella dati: la vecchia cartella viene migrata (fatto per LlmRun → agent-wiki-ui).

Riferimenti

Reference in new issue View Git Blame Copy Permalink