skill-hub: add KDE Plasma plasmoid workflow
This commit is contained in:
enne2
@@ -0,0 +1,26 @@
|
||||
---
|
||||
name: kde-plasmoid
|
||||
description: Progetta, crea, modifica, installa e verifica widget/plasmoidi KDE Plasma 6 (QML, DataSource, grafici Canvas, layout desktop). Usa quando l'utente chiede un widget Plasma o di correggerne stile, dati, posizione o avvio. Non usare per temi globali KDE, applicazioni Qt autonome, estensioni GNOME o widget Plasma 5 senza porting.
|
||||
---
|
||||
|
||||
# KDE Plasma 6: plasmoidi
|
||||
|
||||
## Obiettivo
|
||||
Produrre un plasmoide funzionante e leggibile nel contesto desktop/pannello richiesto, senza alterare altri widget o sessioni. Leggi [references/plasma6.md](references/plasma6.md) prima di implementare o installare.
|
||||
|
||||
## Prerequisiti e gate
|
||||
1. Cerca in qmem le esperienze precedenti; verifica host, versione Plasma, sessione e codice installato. Non trasferire alla cieca path, ID o geometrie di un altro host.
|
||||
2. Ispeziona widget già presenti, codice QML, metadata e backend; concorda con l'utente layout, serie e scala dei grafici quando vi sono più soluzioni sensate.
|
||||
3. Prima di modificare codice, configurazione desktop o installazione, presenta piano, file interessati e verifica e ottieni autorizzazione esplicita. Autorizzazione a creare codice non implica autorizzazione a installare, posizionare sul desktop o riavviare Plasma.
|
||||
4. Conserva una copia del sorgente originale per modifiche rischiose; non sovrascrivere modifiche altrui. Non committare o pubblicare plasmoidi senza richiesta distinta.
|
||||
|
||||
## Workflow
|
||||
1. Identifica ID del pacchetto (`metadata.json`), directory sorgente e installata, modello di refresh e dipendenze. Preferisci l'infrastruttura QML e i backend già usati dal progetto.
|
||||
2. Implementa un widget adattivo con stato iniziale, valori mancanti, errori del backend e aggiornamento periodico ragionevole. Usa colori/scale distinguibili, margini espliciti e unità corrette. Per grafici temporali, registra campioni limitati e ridisegna Canvas su aggiornamenti e resize.
|
||||
3. Verifica JSON, comando del backend e rendering (`plasmawindowed <id>` con timeout). Installa/aggiorna con `kpackagetool6 --type Plasma/Applet --install|--upgrade <dir>` solo se autorizzato.
|
||||
4. Se richiesto, aggiungi al desktop via scripting Plasma verificando prima che non esista già. Per modificare geometrie usa il formato e la risoluzione effettiva; salva un backup della configurazione e controlla che Plasma non riadatti le dimensioni dopo il riavvio.
|
||||
5. Verifica widget presente, valori plausibili confrontati con la fonte, assenza di errori QML nel journal e leggibilità reale della UI. Se la verifica visiva non è disponibile, dichiaralo: `plasmawindowed` e log da soli non attestano il layout.
|
||||
6. Registra in qmem solo lezioni significative, con progetto della skill per la guida e `host-<hostname>` per dati locali verificati. Non salvare segreti o trascrizioni.
|
||||
|
||||
## Criteri di uscita
|
||||
Pacchetto riconosciuto, backend utilizzabile, widget visibile quando richiesto, nessuna collisione o troncamento visivo osservato, assenza di errori QML; riferisci cosa è stato verificato e cosa no.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Plasma 6: implementazione e diagnosi
|
||||
|
||||
## Pacchetto
|
||||
|
||||
```
|
||||
org.example.monitor/
|
||||
metadata.json
|
||||
contents/ui/main.qml
|
||||
contents/scripts/metrics.sh # se serve
|
||||
```
|
||||
|
||||
`metadata.json`: `KPackageStructure: "Plasma/Applet"`, `KPlugin.Id` uguale all'ID del pacchetto, `X-Plasma-API-Minimum-Version: "6.0"`. Evita chiavi Plasma 5 obsolete come `X-Plasma-API` e `X-Plasma-MainScript`. Script nel pacchetto: `Qt.resolvedUrl("../scripts/metrics.sh").toString().replace(/^file:\/\//, "")` (non `plasmoid.file()`).
|
||||
|
||||
## QML e backend
|
||||
|
||||
- Import tipici: `QtQuick`, `org.kde.plasma.plasmoid`, `org.kde.plasma.core as PlasmaCore`, `org.kde.plasma.components 3.0 as PC3`, `org.kde.plasma.plasma5support as P5Support`.
|
||||
- `PlasmoidItem { preferredRepresentation: fullRepresentation; Plasmoid.backgroundHints: PlasmaCore.Types.DefaultBackground; fullRepresentation: Rectangle { ... } }` per widget desktop. Non assegnare `Plasmoid.toolTipSubText`: le proprietà tooltip sono dirette sul `PlasmoidItem`.
|
||||
- Plasma 6 non espone il vecchio engine `systemmonitor` né `PlasmaCore.DataSource`: per comandi usa `P5Support.DataSource { engine: "executable"; interval: 2000; connectedSources: [command]; onNewData: function(source, data) { ... } }`. Controlla `data["exit code"]`, `data.stdout`, campi incompleti e processi che superano l'intervallo. Non avviare fork sovrapposti; usa un timer con guardia `busy` e connect/disconnect se il comando può durare.
|
||||
- `nvidia-smi --id=0 --query-gpu=name,temperature.gpu,utilization.gpu,memory.used,memory.total,power.draw --format=csv,noheader,nounits`: °C, %, MiB, MiB, W. Verifica indice/UUID GPU anziché presumere sempre 0; gestisci `N/A`, comando mancante, driver spento e CSV inatteso. Usa una singola query per aggiornamento anziché una per metrica.
|
||||
- Per sensori AMD verifica unità sysfs: `power1_input` in µW, `freq1_input` in Hz, `temp1_input` in milligradi; non indovinare driver o permessi. CPU e memoria da `/proc` richiedono delta o conversioni appropriate.
|
||||
|
||||
## Layout e grafici
|
||||
|
||||
- Segui lo stile degli altri widget installati: background nativo, card semitrasparenti, testo monospaziato per metriche, accenti distinguibili. Il bordo di accento e il testo devono avere margini indipendenti; `anchors.margins` imposta ANCHE il margine sinistro.
|
||||
- Disegna serie percentuali nel Canvas su scala verticale 0..100, con griglia e legenda; per unità diverse usa assi/scale dichiarati, non sovrapporre valori grezzi. Limitare array storico; ridisegnare con `requestPaint()` sui nuovi dati e al resize. Evita valori `NaN` nelle coordinate.
|
||||
- Non affidarsi solo a `implicitHeight`: il containment può limitare altezza e larghezza. Controlla widget alla dimensione REALE dopo riavvio e correggi clipping o sovrapposizioni. `plasmawindowed` verifica il caricamento ma non la geometria finale desktop.
|
||||
|
||||
## Installazione e desktop
|
||||
|
||||
```sh
|
||||
kpackagetool6 --type Plasma/Applet --install /path/to/package
|
||||
kpackagetool6 --type Plasma/Applet --upgrade /path/to/package
|
||||
kpackagetool6 --type Plasma/Applet --show org.example.monitor
|
||||
qdbus6 org.kde.plasmashell /PlasmaShell org.kde.PlasmaShell.evaluateScript 'print(desktops().map(function(d){return d.id+":"+d.widgets().map(function(w){return w.type+"#"+w.id}).join(",")}).join("\n"))'
|
||||
```
|
||||
|
||||
Per aggiungere dopo verifica duplicati: `var d=desktops()[0]; var found=d.widgets().filter(function(w){return w.type==="org.example.monitor"}); var w=found.length ? found[0] : d.addWidget("org.example.monitor"); print(w.id)`. Scegli il desktop corretto quando ve ne sono più di uno.
|
||||
|
||||
La geometria è nella configurazione `~/.config/plasma-org.kde.plasma.desktop-appletsrc`, sezione containment, chiave `ItemGeometries-<larghezza>x<altezza>` (ed eventualmente `ItemGeometriesHorizontal`), formato `Applet-<id>:x,y,w,h,0` con CINQUE campi. Per scriverla via scripting imposta `d.currentConfigGroup=[]` e usa `d.readConfig(key, "")` / `d.writeConfig(key, value)` preservando gli altri widget. Verifica schermo e containment correnti, evita sovrapposizioni. Dopo un backup e con consenso, `systemctl --user restart plasma-plasmashell.service`; non usare `refreshCurrentShell` come scorciatoia: può terminare plasmashell senza respawn. Rileggi la geometria dopo il restart: Plasma può adattarla ai minimi del widget.
|
||||
|
||||
Diagnosi: `timeout 8 plasmawindowed <id>`, poi `journalctl --user -u plasma-plasmashell.service --since '2 minutes ago' --no-pager` e screenshot/verifica UI quando disponibile. Il codice di uscita 124 di `timeout` è normale se la finestra resta aperta; non prova che il contenuto sia leggibile. Evita di attribuire errori generici di altri widget al plasmoide corrente.
|
||||
Reference in New Issue
Block a user