davideandClaude Sonnet 5.5
f2086de31d
- Nuovo ADR-0007: convenzione in tre parti (indice con gli id delle figure, catalogo JSON con campi minimi, istruzioni solo-query) e ripartizione dei compiti tra wiki, motore e app. Nessuna cartella o formato imposti dall'app. - ADR-0006, README, ROADMAP, PROJECT_STATE, TESTING: esempi resi generici (nessun riferimento a una wiki specifica) e nota sull'assenza di uno standard. - Test delle immagini con struttura e testi neutri. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
84 lines
7.6 KiB
Markdown
84 lines
7.6 KiB
Markdown
# agent-wiki-ui
|
|
|
|
Eseguibile C# (.NET 10, Windows e Linux) che lancia Claude Code (`claude -p`) o Codex (`codex exec`) nella cartella in cui risiede l'eseguibile. Senza argomenti apre una GUI di chat (Avalonia), con argomenti funziona da riga di comando.
|
|
|
|
## Requisiti
|
|
- `claude` (Claude Code) installato e nel PATH, già autenticato; per Codex lo stesso con `codex`. Istruzioni: [docs/INSTALL.md](docs/INSTALL.md)
|
|
- Per sviluppare: .NET SDK 10
|
|
- Per usare l'eseguibile pubblicato: nessun runtime (è self-contained). Su Linux serve un desktop con X11 o XWayland per la GUI.
|
|
|
|
## Uso
|
|
|
|
GUI (nessun argomento): finestra di chat in stile claude.ai, con la conversazione in markdown in alto e il campo messaggio in basso (`Invio` invia, `Maiusc+Invio` va a capo, "Nuova chat" azzera il contesto). Il riquadro **Impostazioni** (in alto a destra) permette di scegliere la **CLI** (Claude Code o Codex), il **modello** e l'**effort** di ragionamento. All'avvio, e a ogni cambio di CLI, sono scelti il modello più piccolo (Haiku 5.5 per Claude Code, GPT-5.6 Luna per Codex) ed effort `low`, per risposte rapide e economiche; "Predefinito" = nessun flag, vale la config del motore. Le chat si salvano su disco e l'ultima si riapre all'avvio. Sempre nel riquadro, la sezione **Aggiornamenti** dice se Claude Code e Codex hanno una versione nuova (pulsante evidenziato) e li aggiorna uno alla volta.
|
|
```
|
|
dotnet run --project src/agent-wiki-ui
|
|
```
|
|
|
|
CLI (con argomenti): il prompt viene stampato su terminale, l'exit code è quello del motore (127 se non è nel PATH). Di default usa Claude Code; `--engine codex` usa Codex.
|
|
```
|
|
dotnet run --project src/agent-wiki-ui -- "spiega questo progetto"
|
|
dotnet run --project src/agent-wiki-ui -- --engine codex "spiega questo progetto"
|
|
```
|
|
|
|
## Creare gli eseguibili (Windows e Linux)
|
|
Ogni eseguibile è un **unico file** che include il runtime .NET: chi lo usa non deve installare nulla. Per crearlo serve solo il .NET SDK 10 sulla macchina che compila, e **da ciascun sistema si creano entrambi gli eseguibili** (da Windows anche quello per Linux, e viceversa).
|
|
|
|
### 1. Installare il .NET SDK 10
|
|
- **Windows** (PowerShell o Prompt dei comandi): `winget install Microsoft.DotNet.SDK.10`, oppure il programma di installazione da [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download).
|
|
- **Linux / WSL / macOS**: pacchetto della distribuzione o script ufficiale da [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download). Funziona anche su ARM64 (Raspberry Pi): `curl -sSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh && bash /tmp/dotnet-install.sh --channel 10.0`, poi `export DOTNET_ROOT=$HOME/.dotnet PATH=$PATH:$HOME/.dotnet` (da mettere in `~/.bashrc`).
|
|
- Controllo: `dotnet --version` deve stampare `10.x`.
|
|
|
|
### 2. Creare gli eseguibili
|
|
Dalla cartella del progetto.
|
|
|
|
| Sistema | Comando | Scelta del sistema di destinazione |
|
|
|---|---|---|
|
|
| **Linux, WSL, macOS** (bash) | `scripts/publish.sh` | `scripts/publish.sh linux-x64` |
|
|
| **Windows** (PowerShell) | `.\scripts\publish.ps1` | `.\scripts\publish.ps1 win-x64` |
|
|
|
|
Senza argomenti si creano entrambi. Su Windows, se PowerShell rifiuta di eseguire lo script (criteri di esecuzione): `powershell -ExecutionPolicy Bypass -File .\scripts\publish.ps1`.
|
|
|
|
Risultato (circa 47 MB per file), in `dist/`, ignorata da git:
|
|
|
|
| Sistema | File |
|
|
|---|---|
|
|
| Windows x64 | `dist/win-x64/agent-wiki-ui.exe` |
|
|
| Linux x64 | `dist/linux-x64/agent-wiki-ui` |
|
|
|
|
Altri identificatori (per esempio `win-arm64`, `linux-arm64`) si passano allo script allo stesso modo (`scripts/publish.sh linux-arm64`, risultato in `dist/linux-arm64/`), ma non sono verificati. Su un Raspberry Pi servono anche i motori: per Claude Code vedi [docs/INSTALL.md](docs/INSTALL.md). Lo script è solo una comodità: il comando sotto fa la stessa cosa.
|
|
|
|
**Senza script** (identico su qualsiasi sistema; sostituisci `<rid>` con `win-x64` o `linux-x64`):
|
|
```
|
|
dotnet publish src/agent-wiki-ui -c Release -r <rid> --self-contained -p:PublishSingleFile=true -o dist/<rid>
|
|
```
|
|
Senza `-o` il risultato è in `bin/Release/net10.0/<rid>/publish/`.
|
|
|
|
Verificato: da Linux/WSL entrambi gli eseguibili; da Windows nativo (PowerShell 5.1, SDK 10.0.203) entrambi, e il `.exe` creato parte.
|
|
|
|
**Usarli**
|
|
- Windows: doppio clic su `agent-wiki-ui.exe` per la GUI (non si apre nessuna finestra di console), oppure da terminale `agent-wiki-ui.exe "prompt"` per la CLI. Da `cmd` o PowerShell il prompt torna subito e l'output compare dopo; per aspettare la fine e leggere l'exit code usa `start /wait agent-wiki-ui.exe "prompt"` (cmd) o `Start-Process -Wait -NoNewWindow agent-wiki-ui.exe "prompt"` (PowerShell); `& .\agent-wiki-ui.exe "prompt" | Out-Host` aspetta ma non dà l'exit code. Spiegazione in [ADR-0005](docs/adr/0005-windows-senza-console.md). Il file non è firmato: Windows può mostrare un avviso di sicurezza al primo avvio.
|
|
- Linux: `chmod +x agent-wiki-ui` (se serve) e poi `./agent-wiki-ui`. La GUI richiede un desktop con X11 o XWayland.
|
|
- Al primo avvio le librerie native (Skia, HarfBuzz) vengono estratte in una cartella temporanea: il primo avvio è un po' più lento.
|
|
- 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)
|
|
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 `` 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:
|
|
```
|
|
<wiki>/ radice del progetto, con CLAUDE.md (schema completo della wiki)
|
|
index.md indice delle pagine, con gli id delle figure di ogni pagina
|
|
<catalogo-figure>.json catalogo: metadati di ogni figura (file, didascalia, posizione, avvertenze)
|
|
<cartella-immagini>/<file> 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: il `CLAUDE.md` chiede di trovare la figura nel catalogo e di citarla con un percorso relativo alla radice (``), 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).
|
|
|
|
> **Stato: MVP** (prima della 1.0): la parte funzionale c'è, i test automatici e alcune verifiche su macchine reali mancano. Dettagli in [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md).
|
|
|
|
Documentazione: [docs/README.md](docs/README.md) (indice, regole, decisioni), [docs/MVP.md](docs/MVP.md), [docs/ROADMAP.md](docs/ROADMAP.md).
|