Skill de configuration d'environnement (unique)

Objectif : déterminer exactement où se trouvent les outils sur cette machine, rédiger un contrat de chemins, puis disparaître.

Le cycle de vie de cette skill est "utiliser et jeter". Ne la laissez pas résidente – à la fin, suivez impérativement la procédure de confirmation §7.

0. Trois règles strictes (à lire d'abord)

Phase de détection en lecture seule. scripts/detect.py ne crée/modifie/supprime jamais de fichiers système. Il utilise uniquement which / stat / requêtes de version / listage de répertoires. Toute écriture doit se produire dans install.sh en §4, et être enregistrée ligne par ligne dans un manifeste.
N'écrivez jamais sur le disque utilisateur. Ne touchez pas à /mnt/c, /mnt/d, ni aux disques Windows. Tous les fichiers de sortie et temporaires se situent dans l'espace de travail actuel ou ~/.config/ideaform/.
N'essayez pas sudo. Les processus dans le bac à sable n'auront jamais les droits root (NoNewPrivs=1 du noyau), c'est une perte de temps. Les tâches nécessitant root sont confiées à l'utilisateur qui les exécutera dans son propre terminal, avec des commandes précises fournies. Tous les outils de ce projet sont conçus pour une installation au niveau utilisateur (extraction AppImage, installation dans venv, polices locales), sans root.

1. Fichier de contrat (la seule sortie externe de cette skill)

Emplacement (fixe, tiers, en dehors des deux skills) :

$VW_CONFIG_ROOT/toolchain.json          # par défaut ~/.config/ideaform/
$VW_CONFIG_ROOT/env.sh                  # script exportable directement sourceable par le shell
$VW_CONFIG_ROOT/install-manifest.jsonl   # ce qui a été installé, pour rollback
$VW_CONFIG_ROOT/logs/
$VW_CONFIG_ROOT/backup/                 # sauvegardes des fichiers originaux avant toute conservation

$VW_CONFIG_ROOT par défaut ~/.config/ideaform, peut être écrasé par une variable d'environnement. Le fichier de contrat est placé en dehors du répertoire de la skill par conception – ainsi, même après suppression de cette skill, les skills de workflow peuvent toujours le lire.

Champs de schema_version 1 (les skills de workflow lisent ces clés) :

{
  "schema_version": 1,
  "generated_at": "ISO8601",
  "generated_by": "[email protected]",
  "verified_at": "ISO8601 | null",       // tamponné après succès du test de fumée
  "host": { "os": "linux", "distro": "...", "arch": "x86_64", "in_wsl": true },
  "config_root": "/abs/path",
  "tmpdir": "/abs/path/to/big/disk/tmp", // ★ doit pointer vers un grand disque, pas /tmp de 10 Mo
  "tools": {
    "node":     { "path": "/abs", "version": "22.x", "status": "ok|missing|degraded" },
    "python":   { "path": "/abs", "version": "3.13.x", "status": "..." },
    "venv":     { "path": "/abs", "python": "/abs/bin/python", "pip": "/abs/bin/pip" },
    "ffmpeg":   { "path": "/abs", "version": "...", "flavor": "full|remotion-minimal", "status": "..." },
    "ffprobe":  { "path": "/abs", "status": "..." },
    "remotion": { "project": "/abs", "version": "4.x", "status": "..." },
    "lmms":     { "apprun": "/abs", "root": "/abs", "version": "1.2.2",
                  "stkdir": "/abs", "status": "..." },
    "fonts":    { "cjk_families": ["Noto Sans CJK SC"], "status": "..." }
  },
  "env_file": "/abs/env.sh",
  "manifest": "/abs/install-manifest.jsonl"
}

Au démarrage, la skill de workflow vérifie schema_version et verified_at : version non conforme → demande de relancer cette skill ; verified_at null → avertissement "Non validé par le test de fumée".

2. Ordre d'exécution (à suivre, ne pas sauter)

Étape 1 · Détection en lecture seule

python3 skills/ideaform-setup/scripts/detect.py            # rapport lisible par un humain
python3 skills/ideaform-setup/scripts/detect.py --json     # lisible par une machine

Vérifiez chaque entrée par rapport à references/toolchain-matrix.md. Chaque élément a un état : ok / missing / degraded (présent mais incomplet, par ex. ffmpeg version Remotion minimal).

Étape 2 · Présenter le plan, demander à l'utilisateur

Organisez les résultats de la détection en un tableau à montrer à l'utilisateur : ce qui est ok, ce qui manque, ce qui est dégradé, et pour chaque élément manquant, comment on compte l'installer, où, et l'espace disque requis. Attendez la confirmation de l'utilisateur avant d'agir. N'installez rien de votre propre chef.

Étape 3 · Installation (seulement après confirmation utilisateur)

bash skills/ideaform-setup/scripts/install.sh --only <tool1,tool2>

Sans --only, installe tous les éléments manquants. Le script :

Sauvegarde les fichiers existants qui seront écrasés dans $VW_CONFIG_ROOT/backup/<timestamp>/
Ajoute une entrée dans install-manifest.jsonl après chaque étape
Installe tout dans des chemins utilisateur, sans besoin de root

Si un élément nécessite root (très rare), le script s'arrête et imprime la commande à transmettre à l'utilisateur pour exécution dans son terminal.

Étape 4 · Écrire le contrat

python3 skills/ideaform-setup/scripts/detect.py --write

Résultat dans toolchain.json + env.sh. À ce stade, verified_at est toujours null.

Étape 5 · Moissonnage des skills communautaires (récupération)

Une fois le contrat écrit, les outils présents dans la chaîne sont déterminés. Ne vous précipitez pas à utiliser vos propres connaissances limitées, récupérez d'abord les skills matures de la communauté qui ont déjà rencontré les problèmes :

python3 skills/ideaform-setup/scripts/harvest-skills.py --from-contract            # moissonne outil par outil
python3 skills/ideaform-setup/scripts/harvest-skills.py --from-contract --dry-run  # prévisualisation des candidats

Pour chaque outil, le script : recherche GitHub filename:SKILL.md → note selon stars/licence/actualité → scan de sécurité (les correspondances de motifs dangereux vont dans _quarantine/ et on passe au candidat suivant) → écrit dans ~/.workbuddy/skills/<name>/ (avec _PROVENANCE.md de provenance) → enregistre dans le manifeste.

Aucun candidat valable = ce tool nécessite vraiment d'écrire sa propre skill – c'est la raison d'être de ce dépôt skills/ideaform*.
Les skills déposées vous appartiennent pour évolution. Le script a une protection de fork (_harvest.json avec hash par fichier) : les modifications locales ne sont pas écrasées par défaut, --force ne met à jour que ce qui n'a pas été modifié, les nouvelles versions forkées vont dans _upstream/ pour fusion manuelle. Voir references/skill-harvest.md §4.1.
Protocole complet (critères de notation / motifs de sécurité / limites) voir references/skill-harvest.md.

Cette étape n'appartient pas seulement à la configuration initiale. Lors de l'introduction future de tout nouvel outil open source en production (par exemple pour dessiner des structures chimiques, penser à RDKit), la première chose à faire est harvest-skills.py rdkit – moissonner d'abord, agir ensuite.

Étape 6 · Test de fumée de bout en bout (obligatoire, ne pas sauter)

python3 skills/ideaform-setup/scripts/verify.py

Exécute vraiment le cycle minimal complet, les quatre éléments doivent réussir pour tamponner :

★ Critère d'acceptation : après cette étape, relancez une fois sans aucune variable d'environnement : env -u TMPDIR -u VW_TMPDIR -u VW_CHROME python3 scripts/verify.py Si tout passe encore, le contrat est vraiment autonome (chemins des outils, TMPDIR, chrome lus depuis le contrat). Un succès uniquement grâce à un export manuel = contrat incomplet, la skill de workflow échouera sur une autre machine.

Vérification	Fait	Critère de réussite
① TTS	Synthétiser une phrase en chinois	Audio produit > 2 Ko et RMS > seuil
② Image	Remotion rend 1 frame still	PNG de taille correcte, fichier > 20 Ko
③ Audio	LMMS rend un projet de 1 seconde	Pic WAV > 1000 et non silencieux
④ Montage	ffmpeg fusionne vidéo silencieuse + piste audio	Débit audio de sortie > 64000 bps

Tout réussi → verified_at est tamponné dans toolchain.json. Un échec → arrêtez-vous et rapportez quel élément et pourquoi, corrigez puis relancez. Ne tamponnez pas.

Étape 7 · Confirmation de fin + nettoyage

Voir §7.

3. Comment trouver chaque outil (résumé)

Tableau complet dans references/toolchain-matrix.md. Points clés :

Node / Python : privilégier les chemins des versions hébergées localement (~/.workbuddy/binaries/...), puis PATH.
ffmpeg / ffprobe : généralement absent du système. Remotion embarque une version réduite (node_modules/@remotion/compositor-linux-x64-gnu/ffmpeg) – suffisante, mais moins de filtres (pas de volumedetect / acompressor, loudnorm avec latence). Si trouvé, marquer degraded plutôt que missing, et préciser flavor dans le contrat.
Projet Remotion : privilégier $VW_REMOTION_PROJECT, puis chercher ~/tools/remotion-app, puis scanner l'espace de travail pour remotion.config.ts, sinon utiliser le modèle fourni par cette skill assets/templates/remotion-starter/.
LMMS : chercher squashfs-root/AppRun (point d'entrée après extraction AppImage). Note : stkdir dans ~/.lmmsrc.xml doit pointer vers rawwaves/ du répertoire extrait, sinon silence total sans message d'erreur – c'est le piège le plus coûteux de ce workflow, verify.py ③ est là pour ça.
Polices chinoises : fc-list chercher Noto Sans CJK SC etc. Si manquantes, installer au niveau utilisateur dans ~/.local/share/fonts/.

4. Emplacements d'installation

Outil	Emplacement	Moyen
Node / Python	Uniquement si manquant	Utiliser d'abord les versions hébergées de la machine ; sinon inviter l'utilisateur
`edge-tts` / `soundfile` / `numpy`	venv	`<venv>/bin/pip install`, doit `export TMPDIR=<grand disque>`
ffmpeg complet	`~/.local/bin/`	Télécharger archive statique depuis un miroir, extraire, aucun root nécessaire (optionnel, version réduite suffisante pas besoin d'installer)
LMMS	`$VW_CONFIG_ROOT/lmms/`	Télécharger AppImage via proxy → `--appimage-extract` extraire
Dépendances Remotion	Répertoire du projet	`npm install`, `TMPDIR` pointé vers grand disque
Polices chinoises	`~/.local/share/fonts/`	Extraire `.ttc` → `fc-cache -f`

⚠️ Chaque téléchargement doit être vérifié : taille / SHA256 / possibilité d'exécution après extraction. En cas d'échec, réessayer plutôt que de laisser un fichier incomplet.

5. Retour arrière

install-manifest.jsonl est la seule source de vérité, format :

{ "entries": [
  { "ts": "...", "kind": "pip-install", "target": "<venv>", "detail": "edge-tts==7.3.1",
    "undo": "<venv>/bin/pip uninstall -y edge-tts" },
  { "ts": "...", "kind": "mkdir", "target": "$VW_CONFIG_ROOT/lmms", "undo": "rm -rf ..." },
  { "ts": "...", "kind": "backup-file", "target": "~/.lmmsrc.xml",
    "backup": "$VW_CONFIG_ROOT/backup/<ts>/lmmsrc.xml", "undo": "cp backup à l'emplacement d'origine" }
] }

bash skills/ideaform-setup/scripts/rollback.sh --list      # voir ce qui sera annulé
bash skills/ideaform-setup/scripts/rollback.sh --dry-run   # simulation, ne touche pas
bash skills/ideaform-setup/scripts/rollback.sh --yes       # vrai rollback (ordre inverse)

Sauvegarder avant d'écraser un fichier existant de l'utilisateur – surtout ~/.lmmsrc.xml. Par défaut, le rollback ne supprime pas le fichier de contrat (utilisé par la skill de workflow), sauf demande explicite --purge-contract.

7. ★ Fin : désactiver / archiver / supprimer (l'utilisateur doit choisir)

Après succès du test de fumée, ne vous supprimez pas automatiquement. Suivez cette procédure :

① Rapportez d'abord

Dites à l'utilisateur :

L'environnement est configuré, toolchain.json est prêt (donner le chemin)
Résultats des quatre tests de fumée
La skill de workflow n'a pas besoin de cette skill pour fonctionner (car le contrat est en dehors de la skill)

② Présentez trois options, laissez l'utilisateur choisir

Option	Fait	Réversibilité	Applicable
A. Désactiver (recommandé)	Mettre `disable: false` à `true` dans le frontmatter de ce SKILL.md	Remettre à `false` pour restaurer	Pour garder la possibilité de relancer sur une autre machine/environnement
B. Archiver	Déplacer tout le répertoire skill dans `$VW_CONFIG_ROOT/archive/ideaform-setup-<ts>/`	Remettre en place pour restaurer	Ne pas vouloir qu'il apparaisse dans la liste des skills, mais le garder en réserve
C. Supprimer	Supprimer vraiment le répertoire	Restaurer via la sauvegarde automatique	Certain de ne plus en avoir besoin

Recommandation A : Désactiver est le plus sûr, le moins coûteux, et garde la capacité de "relancer si l'environnement change".

③ Règle absolue avant d'agir

Quelle que soit l'option, sauvegarder d'abord, agir ensuite, puis confirmer :

Sauvegarde : cp -r <répertoire skill> $VW_CONFIG_ROOT/backup/skill-ideaform-setup-<ts>/
Liste : listez chaque chemin qui sera supprimé/modifié pour l'utilisateur
Double confirmation : attendez que l'utilisateur dise explicitement "supprime" ou équivalent, n'utilisez pas de valeur par défaut ou d'inférence
Exécution : supprimez avec mv vers la sauvegarde, pas directement rm -rf
Vérification : confirmez que la skill de workflow peut toujours lire toolchain.json et démarrer correctement

④ Auto-test après suppression

test -f "$VW_CONFIG_ROOT/toolchain.json" && echo "Contrat toujours présent ✓"

Contrat présent → le workflow n'est pas affecté. Contrat perdu → suppression erronée, restaurer avec la sauvegarde.

Quand l'utilisateur demande "je peux supprimer directement ?", répondez en présentant les trois options et expliquez les compromis, ne répondez pas juste "oui".

8. Erreurs courantes

Phénomène	Cause réelle	Traitement
Rendu LMMS silencieux, aucun message d'erreur dans les logs	`stkdir` dans `~/.lmmsrc.xml` ne pointe pas vers `rawwaves/` du répertoire extrait	Modifier `stkdir`, puis relancer `verify.py` ③ pour revérifier
`npm install` / `pip install` renvoie `ENOSPC`	`TMPDIR` pointé vers `/tmp` tmpfs de 10 Mo	`export TMPDIR=<grand disque>`, le `tmpdir` du contrat sert à cela
Rendu Remotion timeout / blocage en cours de route	Concurrence trop élevée faisant exploser la mémoire (4 pages 1080p)	Réduire `--concurrency`, segmenter les longues vidéos
AppImage ne se lance pas	Bac à sable sans `/dev/fuse`	Extraire avec `--appimage-extract` puis utiliser `AppRun`
LMMS refuse de démarrer	`id` dans le bac à sable affiche root	Ajouter `--allowroot`
edge-tts renvoie `WSServerHandshakeError 403`	Version trop ancienne (pas un problème réseau)	`pip install --upgrade edge-tts`, puis recalibrer l'horloge système

Plus dans docs/05-故障排查.md (en chinois).

9. Transmission à qui

Une fois la configuration terminée, la prochaine étape est la skill de workflow :

skills/ideaform/SKILL.md

Elle lira d'abord le toolchain.json produit par cette skill. Message de transmission :

L'environnement est configuré et validé, le contrat se trouve à <chemin>. Passez maintenant à la skill de workflow pour la production.

Orinkle/ideaform

Qu'est-ce que ideaform ?

Demander à votre IA préférée

Documentation