Umgebungs-Setup-Skill (Einmalig)
Ziel: Klären, wo sich diese Tools auf diesem Rechner befinden, in einer Pfad-Vereinbarung festhalten und sich dann zurückziehen.
Dieses Skill ist dazu gedacht, nach einmaliger Nutzung entsorgt zu werden. Lassen Sie es nicht dauerhaft aktiv – befolgen Sie am Ende zwingend den Bestätigungsprozess aus §7.
0. Drei harte Regeln (zuerst lesen)
- Erkennungsphase ist read-only.
scripts/detect.pyerstellt/ändert/löscht niemals Systemdateien. Es führt nurwhich/stat/ Versionsabfragen / Verzeichnislisten aus. Jegliche Schreibvorgänge müssen in§4(install.sh) erfolgen und einzeln im Manifest protokolliert werden. - Niemals auf Benutzerlaufwerke schreiben. Keine Änderungen auf
/mnt/c,/mnt/doder Windows-Laufwerken. Alle Ausgaben und temporären Dateien landen im aktuellen Arbeitsbereich oder in~/.config/ideaform/. - Versuchen Sie kein sudo. Prozesse in der Sandbox haben niemals root-Rechte (Kernel
NoNewPrivs=1). Dies zu versuchen, ist reine Zeitverschwendung. Aufgaben, die root erfordern, übergeben Sie an den Benutzer zur Ausführung in seinem eigenen Terminal, zusammen mit den genauen Befehlen. Alle Tools dieses Projekts sind für eine Installation auf Benutzerebene ausgelegt (Entpacken von AppImages, venv-Installation, lokale Schriftarten), root wird nicht benötigt.
1. Vertragsdatei (Die einzige externe Ausgabe dieses Skills)
Speicherorte (festgelegt, Drittanbieter-Speicherorte außerhalb der beiden Skills):
$VW_CONFIG_ROOT/toolchain.json # Standard: ~/.config/ideaform/
$VW_CONFIG_ROOT/env.sh # Shell-Skript, das direkt gesourced werden kann
$VW_CONFIG_ROOT/install-manifest.jsonl # Installationsprotokoll für Rollbacks
$VW_CONFIG_ROOT/logs/
$VW_CONFIG_ROOT/backup/ # Backups aller vor dem Überschreiben vorhandenen Dateien
$VW_CONFIG_ROOT ist standardmäßig ~/.config/ideaform und kann mit einer Umgebungsvariable überschrieben werden.
Die Vertragsdatei wird absichtlich außerhalb des Skill-Verzeichnisses abgelegt – so können Workflow-Skills darauf zugreifen, selbst wenn dieses Skill gelöscht wird.
Schema-Version 1 Felder (Workflow-Skills lesen diese Schlüssel):
{
"schema_version": 1,
"generated_at": "ISO8601",
"generated_by": "[email protected]",
"verified_at": "ISO8601 | null", // Wird erst nach bestandenem Smoke-Test gesetzt
"host": { "os": "linux", "distro": "...", "arch": "x86_64", "in_wsl": true },
"config_root": "/abs/path",
"tmpdir": "/abs/path/to/big/disk/tmp", // ★ Muss auf eine große Platte zeigen, nicht auf das 10 MB /tmp
"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"
}
Workflow-Skills prüfen beim Start schema_version und verified_at:
- Version stimmt nicht überein → Aufforderung, dieses Skill erneut auszuführen.
verified_atist null → Warnung „Smoke-Test nicht bestanden“.
2. Ausführungsreihenfolge (genau so, nichts überspringen)
Schritt 1 · Read-Only-Erkennung
python3 skills/ideaform-setup/scripts/detect.py # Für Menschen lesbarer Bericht
python3 skills/ideaform-setup/scripts/detect.py --json # Maschinenlesbar
Prüfen Sie jeden Eintrag anhand der references/toolchain-matrix.md.
Jeder Eintrag hat den Status ok / missing / degraded (vorhanden, aber nicht voll funktionsfähig, z. B. ffmpeg in der Remotion-Minimalversion).
Schritt 2 · Plan erstellen, Benutzer fragen
Fassen Sie das Erkennungsergebnis in einer Tabelle für den Benutzer zusammen: welche ok, welche missing, welche degraded,
sowie für jedes fehlende Tool: wie es installiert werden soll, wohin und wie viel Speicherplatz benötigt wird.
Warten Sie auf die Bestätigung des Benutzers, bevor Sie handeln. Installieren Sie nichts eigenmächtig.
Schritt 3 · Nachinstallation (nur nach Benutzerbestätigung)
bash skills/ideaform-setup/scripts/install.sh --only <tool1,tool2>
Ohne --only werden alle fehlenden Elemente installiert. Das Skript:
- Sichert vorhandene Dateien, die überschrieben werden sollen, in
$VW_CONFIG_ROOT/backup/<Zeitstempel>/ - Fügt nach jedem abgeschlossenen Schritt einen Eintrag zu
install-manifest.jsonlhinzu - Installiert alles in Benutzerpfaden, benötigt kein root
Falls etwas doch root benötigt (sehr selten), stoppt das Skript und gibt den Befehl aus, damit Sie ihn dem Benutzer zur Ausführung in seinem eigenen Terminal übergeben können.
Schritt 4 · Vertrag schreiben
python3 skills/ideaform-setup/scripts/detect.py --write
Schreibt die Ergebnisse als toolchain.json + env.sh. Zu diesem Zeitpunkt ist verified_at noch null.
Schritt 5 · Community-Skills ernten (Übernahme)
Sobald der Vertrag geschrieben ist, steht fest, welche Tools in der Kette sind. Versuchen Sie nicht, sich nur auf Ihr vorhandenes Wissen zu verlassen, sondern holen Sie sich zuerst die ausgereiften Skills aus der Community, die bereits ihre Fehler hatten:
python3 skills/ideaform-setup/scripts/harvest-skills.py --from-contract # Erntet für jedes Tool in der Kette
python3 skills/ideaform-setup/scripts/harvest-skills.py --from-contract --dry-run # Erst die Kandidatenliste prüfen, dann entscheiden
Das Skript sucht für jedes Tool: GitHub-Suche nach filename:SKILL.md → Bewertung nach Stars/Lizenz/Aktualität →
Sicherheitsscan (bei Treffern mit gefährlichen Mustern in die Quarantäne _quarantine/ verschieben und nächsten Kandidaten nehmen) →
speichern unter ~/.workbuddy/skills/<name>/ (mit _PROVENANCE.md als Herkunftsnachweis) → im Manifest protokollieren.
- Kein geeigneter Kandidat gefunden = dieses Tool muss wirklich selbst ein Skill schreiben – genau dafür gibt es die
skills/ideaform*in diesem Repository. - Die gespeicherten Skills können Sie weiterentwickeln. Das Skript hat einen Fork-Schutz (
_harvest.jsonmit Hash pro Datei): Lokal geänderte Dateien werden standardmäßig nicht überschrieben,--forceaktualisiert nur unveränderte, von gegabelten Upstream-Versionen landen neue in_upstream/zur manuellen Zusammenführung. Siehereferences/skill-harvest.md§4.1. - Vollständiges Protokoll (Bewertungsdetails / Sicherheitsmodi / Limits) in
references/skill-harvest.md.
Dieser Schritt gehört nicht nur zur Ersteinrichtung. Wenn Sie später in der Produktion ein neues Open-Source-Tool einführen (z. B. für chemische Strukturformeln an RDKit denken), ist das Erste
harvest-skills.py rdkit– erst ernten, dann loslegen.
Schritt 6 · End-to-End-Smoke-Test (Pflicht, nicht überspringen)
python3 skills/ideaform-setup/scripts/verify.py
Führt wirklich den minimalen geschlossenen Kreislauf aus. Alle vier Prüfungen müssen bestanden sein, bevor der Stempel gesetzt wird:
★ Abnahmekriterium: Nach diesem Schritt erneut unter Null-Umgebungsvariablen ausführen –
env -u TMPDIR -u VW_TMPDIR -u VW_CHROME python3 scripts/verify.pymuss immer noch alles bestehen, dann erst ist der Vertrag wirklich konsistent (Toolchain, TMPDIR, Chrome-Pfad werden alle aus dem Vertrag gelesen). Wenn es nur mit manuellemexportfunktioniert, hat der Vertrag Lücken, und das Workflow-Skill wird auf einem anderen Rechner scheitern.
| Prüfung | Was wird gemacht | Bestehenskriterium |
|---|---|---|
| ① TTS | Synthetisiere einen chinesischen Satz | Ausgabe-Audio > 2 KB und RMS > Schwellwert |
| ② Bild | Remotion rendert 1 Standbild | PNG-Größe korrekt, Datei > 20 KB |
| ③ Audio-Rendering | LMMS rendert ein 1-Sekunden-Projekt | WAV-Spitzenwert > 1000 und nicht stumm |
| ④ Audio-Video-Mux | ffmpeg kombiniert stummes Video + Audiospur | Ausgabe-Audiobitrate > 64000 bps |
Alles bestanden → verified_at wird in toolchain.json gesetzt.
Nicht bestanden → Stoppen und melden, welcher Punkt warum durchgefallen ist, reparieren und erneut ausführen. Keinen Stempel setzen.
Schritt 7 · Übergabebestätigung + Abschluss
Siehe §7.
3. Wie die einzelnen Tools gefunden werden (Zusammenfassung)
Die vollständige Tabelle finden Sie in references/toolchain-matrix.md. Wichtige Punkte:
- Node / Python: Bevorzugt Pfade zu gehosteten Versionen auf dem Rechner (
~/.workbuddy/binaries/...), dann Rückfall aufPATH. - ffmpeg / ffprobe: Das System hat sie normalerweise nicht. Im Remotion-Paket ist eine Minimalversion enthalten
(
node_modules/@remotion/compositor-linux-x64-gnu/ffmpeg) – ausreichend, aber mit weniger Filtern (keinvolumedetect/acompressor,loudnormhat Verzögerung). Wird sie gefunden, wird sie alsdegradedmarkiert, nicht alsmissing, und derflavorwird im Vertrag vermerkt. - Remotion-Projekt: Bevorzugt
$VW_REMOTION_PROJECT, dann~/tools/remotion-app, dann Suche im Arbeitsbereich nachremotion.config.ts. Wenn nichts gefunden wird, wird mit dem im Skill enthaltenenassets/templates/remotion-starter/ein neues erstellt. - LMMS: Suche nach
squashfs-root/AppRun(Einstiegspunkt nach dem Entpacken des AppImage). Beachten Sie:stkdirin~/.lmmsrc.xmlmuss aufrawwaves/im entpackten Verzeichnis zeigen, sonst ist durchgängig Stille ohne Fehlermeldung – das ist der teuerste Fehler dieses Workflows,verify.py③ wurde dafür eingerichtet. - Chinesische Schriftarten:
fc-listsucht nachNoto Sans CJK SCoder Ähnlichem. Fehlende Schriftarten werden als Benutzer-Schriftarten in~/.local/share/fonts/installiert.
4. Installationsziele
| Tool | Wohin installieren | Methode |
|---|---|---|
| Node / Python | Nur installieren, wenn fehlend | Bevorzugt vorhandene gehostete Versionen des Rechners verwenden; sonst Benutzer auffordern |
edge-tts / soundfile / numpy | venv | <venv>/bin/pip install, TMPDIR=<große_Platte> muss gesetzt sein |
| ffmpeg (vollständig) | ~/.local/bin/ | Statisches Paket von einem Mirror herunterladen und entpacken, kein root nötig (optional, nur wenn die Minimalversion nicht ausreicht) |
| LMMS | $VW_CONFIG_ROOT/lmms/ | AppImage über Proxy herunterladen → --appimage-extract entpacken |
| Remotion-Abhängigkeiten | Projektverzeichnis | npm install, TMPDIR auf große Platte setzen |
| Chinesische Schriftarten | ~/.local/share/fonts/ | .ttc entpacken → fc-cache -f |
⚠️ Jeder Download muss verifiziert werden: Byteanzahl / SHA256 / ob das Entpackte ausführbar ist. Bei einem Fehlschlag lieber wiederholen, als eine halbe Datei zurücklassen.
5. Rollback
install-manifest.jsonl ist die einzige Quelle der Wahrheit, z. B.:
{ "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 an ursprünglichen Ort" }
] }
bash skills/ideaform-setup/scripts/rollback.sh --list # Zeigt, was rückgängig gemacht wird
bash skills/ideaform-setup/scripts/rollback.sh --dry-run # Simulation, keine Aktion
bash skills/ideaform-setup/scripts/rollback.sh --yes # Echtes Rollback (in umgekehrter Reihenfolge)
Vor dem Überschreiben vorhandener Benutzerdateien muss ein Backup erstellt werden – insbesondere ~/.lmmsrc.xml.
Das Rollback löscht standardmäßig nicht die Vertragsdatei (die wird vom Workflow-Skill benötigt), es sei denn, der Benutzer fordert explizit --purge-contract.
7. ★ Abschluss: Deaktivieren / Archivieren / Löschen (Benutzer muss wählen)
Nach bestandenem Smoke-Test nicht automatisch selbst löschen. Gehen Sie wie folgt vor:
① Zuerst berichten
Dem Benutzer mitteilen:
- Die Umgebung ist eingerichtet,
toolchain.jsonist bereit (Pfad angeben) - Ergebnisse der vier Smoke-Tests
- Das Workflow-Skill benötigt dieses Skill nicht, um zu funktionieren (weil die Vertragsdatei außerhalb des Skills liegt).
② Drei Optionen anbieten, Benutzer wählen lassen
| Option | Was wird gemacht | Umkehrbarkeit | Anwendung |
|---|---|---|---|
| A. Deaktivieren (empfohlen) | disable: false in den Frontmatter dieser SKILL.md auf true setzen | Wieder auf false setzen reaktiviert | Für zukünftige Ausführungen auf anderem Rechner / in anderer Umgebung behalten |
| B. Archivieren | Komplettes Skill-Verzeichnis nach $VW_CONFIG_ROOT/archive/ideaform-setup-<ts>/ verschieben | Zurück verschieben reaktiviert | Soll nicht in der Skill-Liste erscheinen, aber als Reserve bleiben |
| C. Löschen | Verzeichnis wirklich löschen | Über automatisches Backup wiederherstellbar | Sicher, dass es nicht mehr benötigt wird |
Empfehlung A: Deaktivieren ist am sichersten, mit geringsten Kosten und behält die Fähigkeit, bei geänderter Umgebung erneut ausgeführt zu werden.
③ Eherne Regel vor der Aktion
Unabhängig von der gewählten Option: Erst backup, dann handeln, dann bestätigen:
- Backup:
cp -r <Skill-Verzeichnis> $VW_CONFIG_ROOT/backup/skill-ideaform-setup-<ts>/ - Liste erstellen: Jeden Pfad, der gelöscht/geändert wird, dem Benutzer anzeigen
- Zweite Bestätigung: Warten, bis der Benutzer explizit „Löschen“ oder Ähnliches sagt. Nicht mit Standardwerten oder Annahmen arbeiten
- Ausführen: Zum Löschen mit
mvins Backup verschieben, nicht direktrm -rf - Verifizieren: Sicherstellen, dass das Workflow-Skill
toolchain.jsonnoch lesen und normal starten kann
④ Selbstprüfung nach dem Löschen
test -f "$VW_CONFIG_ROOT/toolchain.json" && echo "Vertrag noch vorhanden ✓"
Vertrag vorhanden → Workflow bleibt unbeeinflusst. Vertrag weg → versehentlich gelöscht, mit Backup wiederherstellen.
Wenn der Benutzer fragt „Kann ich es einfach löschen?“, antworten Sie mit den drei Optionen und erklären Sie die Vor- und Nachteile, antworten Sie nicht nur mit „Ja“.
8. Häufige Fehler
| Phänomen | Wahre Ursache | Behandlung |
|---|---|---|
| LMMS rendert durchgängig stumm, Log ohne Fehler | stkdir in ~/.lmmsrc.xml zeigt nicht auf rawwaves/ im entpackten Verzeichnis | stkdir korrigieren und verify.py ③ erneut ausführen |
npm install / pip install meldet ENOSPC | TMPDIR liegt im 10 MB /tmp tmpfs | export TMPDIR=<große_Platte>, der tmpdir-Eintrag im Vertrag dient diesem Zweck |
| Remotion-Rendering bricht währenddessen ab / Seite bleibt hängen | Zu hohe Parallelität verbraucht den gesamten Arbeitsspeicher (4×1080p-Seiten) | --concurrency reduzieren, lange Filme segmentiert rendern |
| AppImage startet nicht | Sandbox hat kein /dev/fuse | --appimage-extract entpacken und mit AppRun ausführen |
| LMMS verweigert Start | id zeigt root in der Sandbox | --allowroot hinzufügen |
edge-tts meldet WSServerHandshakeError 403 | Version zu alt (kein Netzwerkproblem) | pip install --upgrade edge-tts, dann Systemuhr synchronisieren |
Mehr in docs/05-故障排查.md.
9. Übergabe an wen
Nach der Einrichtung ist der nächste Schritt das Workflow-Skill:
skills/ideaform/SKILL.md
Es wird als erstes die von diesem Skill geschriebene toolchain.json lesen. Übergabetext:
Umgebung eingerichtet und bestätigt, Vertrag unter
<Pfad>. Als nächstes mit dem Workflow-Skill in die Produktion gehen.