Perfezionamenti finali: AGENTS.md per installazione automatica, README coerente, file obsoleti rimossi
This commit is contained in:
Noe
parent
cbfe608ecc
commit
341a0b12d2
5 changed files with 407 additions and 827 deletions
400
AGENTS.md
Normal file
400
AGENTS.md
Normal file
|
|
@ -0,0 +1,400 @@
|
|||
# AGENTS.md — Orto Skills Installation & Setup Agent Instructions
|
||||
|
||||
**Per agenti OpenClaw che ricevono pacchetto orto-skills e devono installare le skill**
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Scopo
|
||||
|
||||
Quando un utente carica il pacchetto `orto-skills-v*.tar.gz` in chat e chiede di installare le skill, un agente deve:
|
||||
|
||||
1. **Estrarre** il pacchetto `.tar.gz`
|
||||
2. **Eseguire** `INSTALL.sh` per copiare le skill in `~/.openclaw/skills/orto-suite/`
|
||||
3. **Verificare** che i 9 SKILL.md + 8 reference file siano presenti
|
||||
4. **Guida utente** verso il prossimo step (creazione orto)
|
||||
|
||||
---
|
||||
|
||||
## 📋 Step-by-Step Per l'Agente
|
||||
|
||||
### Fase 1: Ricevere il Pacchetto
|
||||
|
||||
**Trigger:** Utente carica file `.tar.gz` e chiede "installa", "estrai", "setup"
|
||||
|
||||
**Azioni agente:**
|
||||
```
|
||||
✅ Detect file upload
|
||||
✅ Verify filename ends with .tar.gz
|
||||
✅ Verify size ~77 KB (orto-skills-v1.0-dist.tar.gz)
|
||||
```
|
||||
|
||||
**Messaggio all'utente:**
|
||||
```
|
||||
📦 Ho ricevuto il pacchetto!
|
||||
- Filename: orto-skills-v1.0-dist.tar.gz
|
||||
- Size: 77 KB ✓
|
||||
|
||||
Procedo con estrazione e installazione...
|
||||
(30-45 secondi)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fase 2: Estrarre il Pacchetto
|
||||
|
||||
**Dove:** Cartella temporanea (es: `/tmp/orto-install-<timestamp>/`)
|
||||
|
||||
**Comandi eseguiti dall'agente:**
|
||||
```bash
|
||||
# 1. Crea cartella temporanea
|
||||
WORK_DIR=$(mktemp -d)
|
||||
cd $WORK_DIR
|
||||
|
||||
# 2. Estrai tar.gz
|
||||
tar -xzf /tmp/uploads/orto-skills-v1.0-dist.tar.gz
|
||||
|
||||
# 3. Verifica struttura
|
||||
ls -la orto-skills/
|
||||
└─ orto-suite/
|
||||
└─ INSTALL.sh
|
||||
└─ README.md
|
||||
└─ ...
|
||||
```
|
||||
|
||||
**Verifiche:**
|
||||
```
|
||||
✅ orto-skills/ estratto
|
||||
✅ orto-suite/ presente
|
||||
✅ INSTALL.sh presente e executable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fase 3: Eseguire INSTALL.sh
|
||||
|
||||
**Azioni agente:**
|
||||
```bash
|
||||
# Navigare in cartella estratta
|
||||
cd $WORK_DIR/orto-skills
|
||||
|
||||
# Eseguire script di installazione
|
||||
./INSTALL.sh
|
||||
```
|
||||
|
||||
**Output atteso:**
|
||||
```
|
||||
✅ Source directory found
|
||||
✅ Copying orto-suite to ~/.openclaw/skills/orto-suite/
|
||||
✅ Copied successfully
|
||||
✅ Verifying installation...
|
||||
✅ Found 9 SKILL.md files
|
||||
✅ Found 8 reference files
|
||||
✅ Installation verified
|
||||
|
||||
║ ✅ INSTALLATION COMPLETED SUCCESSFULLY
|
||||
```
|
||||
|
||||
**Se utente risponde "n" al prompt di overwrite:**
|
||||
```
|
||||
⚠️ Installazione non eseguita (utente ha rifiutato)
|
||||
Vuoi procedere con overwrite? Scrivi "sì" per continuare
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fase 4: Verificare Installazione
|
||||
|
||||
**Azioni agente:**
|
||||
```bash
|
||||
# Verifica file installati
|
||||
ls -la ~/.openclaw/skills/orto-suite/
|
||||
|
||||
# Conta SKILL.md
|
||||
find ~/.openclaw/skills/orto-suite -name "SKILL.md" | wc -l
|
||||
|
||||
# Conta reference files
|
||||
ls ~/.openclaw/skills/orto-suite/references/*.md | wc -l
|
||||
|
||||
# Test symlink resolution
|
||||
ls ~/.openclaw/skills/orto-suite/orto-init/references/*.md | wc -l
|
||||
```
|
||||
|
||||
**Criterio successo:**
|
||||
```
|
||||
✅ 9 SKILL.md trovati
|
||||
✅ 8 reference files trovati
|
||||
✅ Symlink risolti: tutti 8 reference file accessibili
|
||||
✅ Directory structure coerente
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fase 5: Guida Utente al Prossimo Step
|
||||
|
||||
**Messaggio di successo:**
|
||||
```
|
||||
🎉 INSTALLAZIONE COMPLETATA!
|
||||
|
||||
✅ 9 skill installate in ~/.openclaw/skills/orto-suite/
|
||||
✅ 8 reference files centralizzati
|
||||
✅ Symlink verif ied ✓
|
||||
|
||||
Adesso puoi:
|
||||
|
||||
1️⃣ Creare il tuo primo orto:
|
||||
"Voglio creare un orto a Roma, Lazio"
|
||||
|
||||
2️⃣ Oppure se hai domande:
|
||||
"Dove si trova il mio orto? Come funziona il sistema?"
|
||||
|
||||
Pronto? 🌱
|
||||
```
|
||||
|
||||
**Se fallisce:**
|
||||
```
|
||||
❌ INSTALLAZIONE FALLITA
|
||||
|
||||
Errore: [descrizione errore dal log]
|
||||
|
||||
Possibili soluzioni:
|
||||
1. Verifica che il pacchetto sia integro
|
||||
2. Controlla che ~/.openclaw/skills/ sia scrivibile
|
||||
3. Riprova con: "Installa di nuovo"
|
||||
|
||||
Se persiste, contatta support.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Dettagli Tecnici Per Agenti
|
||||
|
||||
### Percorsi Chiave
|
||||
|
||||
```
|
||||
Pacchetto uploaddato: /tmp/uploads/orto-skills-v1.0-dist.tar.gz
|
||||
Lavoro temporaneo: /tmp/orto-install-<timestamp>/
|
||||
Estratto pacchetto: /tmp/orto-install-<timestamp>/orto-skills/
|
||||
Script INSTALL.sh: /tmp/orto-install-<timestamp>/orto-skills/INSTALL.sh
|
||||
Destinazione finale: ~/.openclaw/skills/orto-suite/
|
||||
```
|
||||
|
||||
### Cartella Installata (Struttura)
|
||||
|
||||
```
|
||||
~/.openclaw/skills/orto-suite/
|
||||
├── orto-init/
|
||||
│ ├── SKILL.md
|
||||
│ ├── references → ../references (symlink)
|
||||
│ ├── assets/
|
||||
│ └── scripts/
|
||||
├── orto-agronomo/
|
||||
├── orto-calendario/
|
||||
├── orto-fitopatologo/
|
||||
├── orto-irrigazione/
|
||||
├── orto-layout/
|
||||
├── orto-meteo-decisioni/
|
||||
├── orto-onboarding/
|
||||
├── orto-orchestratore/
|
||||
└── references/ (8 file)
|
||||
├── colture_it.md
|
||||
├── calendario_it.md
|
||||
├── malattie_trattamenti.md
|
||||
├── irrigazione_parametri.md
|
||||
├── consociazioni_layout.md
|
||||
├── meteo_soglie.md
|
||||
├── conflitti_risoluzione.md
|
||||
└── qa_checklist.md
|
||||
```
|
||||
|
||||
### Comandi di Verifica
|
||||
|
||||
```bash
|
||||
# Totale file SKILL.md
|
||||
find ~/.openclaw/skills/orto-suite -name "SKILL.md" | wc -l
|
||||
# Atteso: 9
|
||||
|
||||
# Totale reference files
|
||||
ls ~/.openclaw/skills/orto-suite/references/*.md | wc -l
|
||||
# Atteso: 8
|
||||
|
||||
# Verifica symlink
|
||||
readlink ~/.openclaw/skills/orto-suite/orto-init/references
|
||||
# Atteso: ../references (output testuale)
|
||||
|
||||
# Test accesso via symlink
|
||||
ls ~/.openclaw/skills/orto-suite/orto-agronomo/references/*.md | wc -l
|
||||
# Atteso: 8
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Flusso di Installazione Completo
|
||||
|
||||
```
|
||||
┌─ UTENTE AZIONI ──────────────┐ ┌─ AGENTE AZIONI ──────────┐
|
||||
│ │ │ │
|
||||
│ 1. Carica .tar.gz │──→ │ 1. Detect + verify file │
|
||||
│ │ │ │
|
||||
│ 2. "Installa le skill" │──→ │ 2. Extract tar.gz │
|
||||
│ │ │ │
|
||||
│ 3. [Aspetta] │ │ 3. Run INSTALL.sh │
|
||||
│ (30-45 secondi) │ │ │
|
||||
│ │ │ 4. Verify installation │
|
||||
│ 4. Riceve conferma │←── │ │
|
||||
│ ✅ Installazione ok │ │ 5. Report to user │
|
||||
│ │ │ │
|
||||
│ 5. "Crea orto a Roma" │──→ │ 6. Invoke orto-init │
|
||||
│ │ │ │
|
||||
└──────────────────────────────┘ └──────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Gestione Errori
|
||||
|
||||
### Errore: File Corrotto
|
||||
|
||||
**Scenario:** Decompressione fallisce
|
||||
|
||||
```bash
|
||||
# Agente:
|
||||
tar -tzf /tmp/uploads/orto-skills-v1.0-dist.tar.gz > /dev/null 2>&1
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ File corrupted or invalid tar.gz"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
**Messaggio utente:**
|
||||
```
|
||||
❌ ERRORE: Pacchetto corrotto
|
||||
|
||||
Il file non è un tar.gz valido.
|
||||
Controlla di aver scaricato il file corretto da:
|
||||
https://github.com/...
|
||||
|
||||
Scarica di nuovo e riprova.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Errore: INSTALL.sh Non Eseguibile
|
||||
|
||||
**Scenario:** Permission denied
|
||||
|
||||
```bash
|
||||
# Agente:
|
||||
chmod +x orto-skills/INSTALL.sh
|
||||
./orto-skills/INSTALL.sh
|
||||
```
|
||||
|
||||
**Messaggio utente:**
|
||||
```
|
||||
⚠️ ATTENZIONE: Script non eseguibile
|
||||
|
||||
Ho corretto i permessi e riprovo...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Errore: ~/.openclaw/skills/ Non Scrivibile
|
||||
|
||||
**Scenario:** Permission denied su destinazione
|
||||
|
||||
```bash
|
||||
# Agente:
|
||||
if [ ! -w ~/.openclaw/skills ]; then
|
||||
echo "❌ Directory not writable"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
**Messaggio utente:**
|
||||
```
|
||||
❌ ERRORE: Permessi insufficienti
|
||||
|
||||
La cartella ~/.openclaw/skills/ non è scrivibile.
|
||||
Questo può accadere se:
|
||||
1. Il sistema file è read-only
|
||||
2. Hai cambiato permessi manualmente
|
||||
|
||||
Contatta il tuo amministratore di sistema.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist Per Agenti
|
||||
|
||||
Quando ricevi richiesta di installazione:
|
||||
|
||||
- [ ] Detect file upload (.tar.gz)
|
||||
- [ ] Verify file size and name
|
||||
- [ ] Extract in temporary directory
|
||||
- [ ] Verify orto-skills/ structure
|
||||
- [ ] Verify orto-suite/ present
|
||||
- [ ] Verify INSTALL.sh executable
|
||||
- [ ] Run INSTALL.sh
|
||||
- [ ] Parse output (success vs failure)
|
||||
- [ ] If failed, handle error
|
||||
- [ ] If success, verify installation
|
||||
- [ ] Count SKILL.md (9 expected)
|
||||
- [ ] Count reference files (8 expected)
|
||||
- [ ] Test symlink resolution
|
||||
- [ ] Report success/failure to user
|
||||
- [ ] Suggest next step (orto-init)
|
||||
- [ ] Cleanup temporary directory
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps Per Utente
|
||||
|
||||
Dopo installazione, guidare utente verso:
|
||||
|
||||
### Opzione A: Setup Interattivo
|
||||
```
|
||||
"Mi guidi a creare il mio primo orto?"
|
||||
|
||||
Agente guiderà attraverso:
|
||||
1. Localizzazione (provincia, regione)
|
||||
2. Profilo orto (spazio, dieta, tempo disponibile)
|
||||
3. Generazione piano completo
|
||||
```
|
||||
|
||||
### Opzione B: Solo Info
|
||||
```
|
||||
"Voglio saperne di più sulle skill"
|
||||
|
||||
Agente presenterà:
|
||||
- Elenco 9 skill disponibili
|
||||
- Workflow tipico: init → onboarding → agronomo → orchestratore
|
||||
- Esempi di output
|
||||
```
|
||||
|
||||
### Opzione C: Manuale
|
||||
```
|
||||
"Come uso le skill?"
|
||||
|
||||
Agente guiderà all'README.md e INSTALL_INTERACTIVE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 Supporto
|
||||
|
||||
Se agente riceve errore non documentato:
|
||||
|
||||
```
|
||||
❓ ERRORE NON RICONOSCIUTO
|
||||
|
||||
Dettagli:
|
||||
[descrizione errore completa]
|
||||
|
||||
Questo potrebbe essere un problema di sistema.
|
||||
Per supporto: contatta il tuo amministratore OpenClaw
|
||||
|
||||
Log salvato in: ~/.openclaw/logs/orto-install-<timestamp>.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
_Last Updated: 2026-03-07 02:17 GMT+1_
|
||||
Loading…
Add table
Add a link
Reference in a new issue