Auf Updates prüfen (Umgebungsverwaltung)
Die gesamte Logik der Umgebung wird nur in dieser Skill beschrieben: Skills-Versionen, Runtime-Installation und -Diagnose. Geschäfts-Skills referenzieren in Schritt 0 die folgende „Bereitschaftsprüfung“ und enthalten selbst keine Umgebungslogik – soll sich die Umgebungsstrategie ändern, wird nur diese eine Datei geändert. Diese Skill erstellt keine Projekte, öffnet kein Studio und transkribiert keine Medien.
Bereitschaftsprüfung (Schritt 0 der Geschäfts-Skills)
Drei Schritte, die zu einem von drei Zuständen führen: Bereit / Neue Sitzung erforderlich / Stopp.
1. Lokalisierung des aktuellen Plugin-Cache (schreibgeschützt)
Ausgehend vom tatsächlichen Quellpfad dieser Skill, der vom Host bereitgestellt wird: Das Verzeichnis, in dem sich diese Datei befindet, zwei Ebenen nach oben ist <Plugin-Stamm>. Mit einem Dateilesetool wird bestätigt, dass <Plugin-Stamm>/.codex-plugin/plugin.json und <Plugin-Stamm>/scripts/check-plugin-update.cjs existieren. Wenn der Pfad nicht ermittelbar ist, die Verzeichnisebene nicht stimmt oder die Dateien nicht existieren, wird der Update-Vergleich mit installed_identity_missing gestoppt; es ist nicht erlaubt, unter dem Benutzer-CODEX_HOME codex plugin list zur Ergänzung aufzurufen oder die gesamte Festplatte zu durchsuchen.
In allen folgenden Befehlen wird <Plugin-Stamm> durch diesen wörtlichen Pfad ersetzt (bei Leerzeichen wird der gesamte Abschnitt in Anführungszeichen gesetzt). Befehlblöcke verwenden keine Shell-Variablen oder Befehlsersetzung – die Zuweisungssyntax von Bash und PowerShell ist nicht kompatibel. Das Prüfskript liest das installierte Manifest, die Herkunft, die exakte Marketplace-Revision und den Bundle-Digest direkt aus dem eigenen Cache; die Prüfphase ist nicht von der Marketplace-CLI des Benutzers abhängig.
2. Sind die Skills aktuell?
node "<Plugin-Stamm>/scripts/check-plugin-update.cjs" --marketplace chengfeng-videocut --json
(Der Marketplace-Name ist standardmäßig chengfeng-videocut; wenn der Benutzer einen anderen Namen konfiguriert hat, wird dieser verwendet.)
current→ Fahre mit Schritt 3 fortupdate_available_confirmation_required→ Zeigeinstalled,candidateund die vier Kandidatenwerte an: Version, 40-hexsnapshotRevision(B), 40-hexcontentRevision(A),publisherChecksum(SHA-256), warte auf Benutzerbestätigung; nach Bestätigung folge dem Abschnitt „Aktivierung“ unten. Aktivierung erfolgreich = Neue Sitzung erforderlich: Der Skill-Text ist bereits zu Sitzungsbeginn geladen, eine Aktualisierung während der Sitzung ist nicht wirksam. Bitte den Benutzer, eine neue Sitzung zu öffnen, bevor die Aufgabe fortgesetzt wird.- Wenn gleichzeitig
legacyInstalledIdentity=trueist, handelt es sich um eine einmalige Kompatibilitätsmigration von historischer Version 0.10.5 zum neuen Beweisformat; es wird derselbe Bestätigungsdialog verwendet, ohne dass der Benutzer vorab die Marketplace-Referenz ändern muss.
- Wenn gleichzeitig
marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe→ Der aktuelle Benutzer-Marketplace fehlt, die Quelle ist nicht vertrauenswürdig oder es ist keine exakte 40-hex-Pin; rufe keine Codex-CLI des Benutzers zur Reparatur auf, melde und fahre mit Schritt 3 fort.installed_identity_missing/installed_identity_untrusted→ Die Identität des aktuellen Caches kann nicht sicher gelesen oder bewiesen werden; rate keine Version, aktiviere nicht; melde und fahre mit Schritt 3 fort.installed_context_mismatch→ Der tatsächliche Cache-Pfad der aktuellen Skill, der Marketplace-Name oder das expliziteCODEX_HOMEstimmen nicht überein; suche nicht in anderen Caches, aktiviere nicht.isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed→ Der temporäre Kandidaten-Stage, das CLI-Schema oder die Bereinigung des temporären Verzeichnisses sind fehlgeschlagen; kein Schreibzugriff auf das Benutzer-HOME, melde und fahre mit Schritt 3 fort.update_metadata_untrusted→ Der Beweis aus version + B + A + SHA-256 ist nicht gültig, aktiviere nicht; melde und fahre mit Schritt 3 fort.candidate_older_than_installed→ Downgrade ist verboten, melde und fahre mit Schritt 3 fort.- Netzwerk nicht erreichbar oder anderer Prüffehler → Erkläre dem Benutzer kurz, fahre mit der aktuellen Runtime-Prüfung fort – Ein Fehler bei der Update-Prüfung blockiert nicht die Arbeit.
Die normale Prüfung darf nur in einem temporären CODEX_HOME mit dem offiziellen stable-Tag nach Kandidaten suchen; es werden keine codex-Befehle im Benutzer-CODEX_HOME aufgerufen und keine Konfiguration, kein Marketplace und kein Cache geschrieben. Die Versionsverzeichnisse des aktuellen Caches müssen alle striktes semver sein; niedrigere Versionen dürfen vorhanden sein, aber nur die eindeutig höchste semver-Priorität wird als aktiv betrachtet. Wenn auf der höchsten Ebene mehrere Verzeichnisse mit derselben Priorität existieren, wird installed_identity_untrusted zurückgegeben; es darf nicht nach lexikografischer Reihenfolge der Verzeichnisnamen ausgewählt werden.
3. Ist die Runtime kompatibel?
node "<Plugin-Stamm>/scripts/ensure-runtime.cjs" --install-if-missing --json
ready→ Bereit, Geschäfts-Skill fährt fortruntime.kind=desktop-managedbedeutet, dass die Desktop-App die mitgelieferte Runtime, Bun, FFmpeg und FFprobe in das einheitlich verwaltete Produktverzeichnis installiert hat; Skills nutzen diese direkt, ohne weitere Abhängigkeiten zu installieren oder Dienste zu starten.runtime.kind=managed/path/sourcesind weiterhin kompatible CLI-Installationsquellen; die späteren Geschäftsvereinbarungen sind identisch.
- missing: Das Skript gibt nur einen Hinweis „Wird gerade von GitHub Release installiert“, nach Abschluss der SHA-256-Prüfung wird automatisch fortgesetzt.
runtime_unhealthy, Installationsfehler oder Fehler nach der Installation (doctor) → Stopp, melde strukturierte Diagnose. Stopp bedeutet Stopp: Es ist verboten, mit selbst erstellten Prüfseiten, Playern, Timeline oder anderen Ersatzoberflächen fortzufahren. Jede Ausgabe, die bei nicht verfügbarem Produkt erzeugt wird, ist nicht vertrauenswürdig (reales Beispiel: Bei fehlender Runtime hat ein Agent eine „Prüfseite“-Webseite selbst gebaut, deren Prüfentscheidungen mit dem Buchhaltungsformat des Produkts völlig inkompatibel waren – der Benutzer hat alles umsonst gemacht). Die einzig korrekte Aktion ist: Die strukturierte Diagnose an den Benutzer geben und zur Installation oder zum Melden eines Issues anleiten.runtime_capability_missing→ Stopp: Runtime ist gesund, erfüllt aber nicht die vertraglichen Anforderungen. Melde zwei Versionsnummern und die Unterschiede, leite den Benutzer zur Bestätigung und zum Upgrade an (Upgrade ersetzt~/.chengfeng-videocut/app, Projektdaten bleiben unberührt); solange der Benutzer nicht bestätigt hat, wird die bestehende Installation nicht angetastet; Downgrade von alten Schnittketten ist verboten.- In der Bereitschaftsprüfungsphase ist es verboten, Dienste zu starten, Studio zu öffnen oder Projekte zu erstellen.
Voraussetzungen der Maschine
Unterstützt macOS und Windows 10/11, zwei Installationspfade:
Desktop-Version (empfohlen)
Chengfeng VideoCut installieren und mindestens einmal starten
-> Die App installiert Bun, FFmpeg, FFprobe und Runtime mit
-> Der Benutzer muss diese Tools nicht zum System-PATH hinzufügen
-> Skills nutzen denselben Dienst über den stabilen Einstiegspunkt ~/.chengfeng-videocut/bin
Reine CLI-Installation
macOS brew install bun ffmpeg
Windows winget install Oven-sh.Bun Gyan.FFmpeg
Nach der Installation ein neues Terminal/eine neue Sitzung öffnen, damit PATH wirksam wird
Beide Pfade benötigen weiterhin Node.js ≥ 20 zur Ausführung der Plugin-Skripte; für den Export von Untertiteln/Animationen wird weiterhin Google Chrome benötigt. Reine CLI-Benutzer installieren selbst, unter Windows kann winget install OpenJS.NodeJS.LTS Google.Chrome verwendet werden. Wenn etwas fehlt, muss klar gestoppt werden, kein stillschweigendes Überspringen.
Für den Identitätsnachweis der Skills-Updates wird außerdem Git benötigt; unter Windows kann winget install Git.Git verwendet werden. Wenn Git nicht ausführbar ist oder die Origin/HEAD/Commit-Beziehung des offiziellen Snapshots nicht gelesen werden kann, schlägt die Update-Prüfung mit „fail-closed“ fehl, fährt aber dennoch gemäß den obigen Regeln mit der Runtime-Prüfung fort.
Für die Cloud-Transkription werden außerdem Anmeldedaten von Volcengine benötigt: node "<Plugin-Stamm>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>.
Ausführliche Vereinbarungen finden Sie unter Runtime- und Produktvertrag.
Skills-Update: Inspect und Aktivierung
Reine Ansicht des aktuellen Plugin-Cache (schreibgeschützt): Keine Netzwerkverbindung, kein Aufruf von codex, kein Schreiben in das Benutzer-CODEX_HOME:
node "<Plugin-Stamm>/scripts/check-plugin-update.cjs" --marketplace "<Marktname>" --inspect --json
Bei Erfolg wird inspected_no_refresh zurückgegeben, das nur die aktuell gepinnte Marketplace- und Cache-Identität enthält, keine Remote-Kandidaten generiert.
Isolierte Netzwerkprüfung (wenn der Benutzer explizit „Auf Updates prüfen“ sagt, oder Schritt 2 der Bereitschaftsprüfung):
node "<Plugin-Stamm>/scripts/check-plugin-update.cjs" --marketplace "<Marktname>" --json
current: Meldet die neueste veröffentlichte Identität der installierten und der temporären Umgebung.update_available_confirmation_required: Zeigt die installierte und die vier Kandidatenwerte version,snapshotRevision(B),contentRevision(A),publisherChecksuman; stoppt und wartet auf Benutzerbestätigung.legacyInstalledIdentity=true: Der aktuelle Cache ist ein kompatibler historischer Cache der Version 0.10.5. Er kann in den normalen Bestätigungsprozess des vorherigen Punkts eintreten; die alte Identität wird gemeinsam durch die exakte Marketplace-Revision, die Cache-Verzeichnisversion, die Manifest-Version und den Inventory-Digest gebunden. Der Benutzer sollte nicht aufgefordert werden, die Referenz zu ändern, und es sollte kein separater „Migrationserfolg“-Status erstellt werden.marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe: Der aktuelle Benutzer-Marketplace fehlt, ist nicht vertrauenswürdig oder ist nicht auf seine eigene exakte 40-hex-Revision gepinnt; die Referenz wird nicht automatisch geändert.installed_identity_missing/installed_identity_untrusted: Der aktuelle Cache ist nicht erkennbar oder nicht vertrauenswürdig; die installierte Version wird nicht geraten.installed_context_mismatch: Die Ausführungsposition des Skripts ist nicht der eindeutig höchste aktive Cache des aktuellen Marketplace, oder das expliziteCODEX_HOMEstimmt nicht mit dem HOME des Caches überein; es wird nicht in anderen Verzeichnissen nachgeraten.isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed: Es wird nur erklärt, dass der temporäre Stage, das CLI-JSON-Schema oder die Bereinigung fehlgeschlagen sind; es wird nicht angedeutet, dass die Benutzerinstallation aktualisiert wurde.update_metadata_untrusted: Dem temporären Snapshot fehlen B, A, der SHA-256/Inventar-Nachweis, oder die Identitäten von Manifest, Marketplace-Revision und Provenance widersprechen sich gegenseitig.candidate_older_than_installed: Downgrade von einer neueren lokalen Version ist verboten.- Jeder Snapshot/Parse/Version-Fehler: Strukturiertes JSON wird beibehalten;
userMutationPerformed=falseim Benutzer-HOME.
Das Skript führt die offizielle Marketplace-CLI nur in einem neu erstellten temporären CODEX_HOME aus: Zuerst wird mit marketplace add Agentchengfeng/chengfeng-videocut-skills --ref stable die Entdeckungsquelle eingerichtet, dann mit marketplace upgrade im selben temporären HOME ein Snapshot materialisiert und mit plugin list die Kandidaten ermittelt. Der aus stable aufgelöste 40-hex B, der 40-hex A aus der Provenance, die Manifest-Version und der neu berechnete SHA-256 bilden gemeinsam den Kandidaten. Git muss außerdem nachweisen, dass der temporäre Marketplace-Origin das offizielle Repository ist, HEAD = B ist, A ein Vorfahre von B ist, der Plugin-Arbeitsbaum sauber ist und der Plugin-Unterbaum von A nach B nur die Provenance ändert. Das temporäre Verzeichnis wird nach der Verwendung gelöscht. Der Marketplace des Benutzers muss auf dem zuvor bestätigten exakten B bleiben; während der Prüfphase wird nicht einmal ein schreibgeschützter codex-Befehl aufgerufen.
Unter Windows wird bei der Auflösung von codex / git zuerst nach PATHEXT nach ausführbaren Erweiterungen gesucht, dann nach Dateien ohne Erweiterung; .cmd / .bat werden über ComSpec verpackt. Daher verdeckt der Unix-codex-Shim im selben Verzeichnis wie pnpm nicht codex.cmd.
Aktivierung nur nach expliziter Benutzerbestätigung
Die Bestätigung muss erfolgen, nachdem der Benutzer die exakte Kandidatenversion, B, A und den Checksum gesehen hat:
node "<Plugin-Stamm>/scripts/check-plugin-update.cjs" --marketplace "<Marktname>" --activate --confirmed --expected-version "<angezeigte Version>" --expected-snapshot-revision "<angezeigtes B>" --expected-content-revision "<angezeigtes A>" --expected-sha256 "<angezeigter Paket-SHA256>" --json
Das Skript muss ein neues temporäres CODEX_HOME erstellen, erneut von stable aus den Kandidaten staggen und alle vier Werte mit --expected-* vergleichen. Wenn der Kandidat vor oder nach dem Stage abweicht oder die Parameter nicht übereinstimmen, wird confirmation_mismatch zurückgegeben, und in das Benutzer-HOME wird nichts geschrieben. Nach erfolgreicher Prüfung wird die exakte Snapshot-Revision und Cache-Identität vor der Aktualisierung aufgezeichnet, und dann werden nur offizielle Befehle im Benutzer-HOME ausgeführt:
plugin marketplace remove <Marktname>
plugin marketplace add Agentchengfeng/chengfeng-videocut-skills --ref <B>
plugin marketplace upgrade <Marktname>
<B> muss der gerade neu gestagte und vom Benutzer bestätigte 40-hex snapshotRevision sein; stable, andere Branches, Tags, kurze SHA oder beliebig andere Referenzen geben marketplace_ref_unsafe zurück. Nach dem Upgrade liest das Skript direkt aus dem Cache erneut und überprüft version + B + A + SHA-256; nur bei vollständiger Übereinstimmung wird activated zurückgegeben. Nach erfolgreicher Aktivierung wird der Benutzer aufgefordert, Codex neu zu starten oder eine neue Sitzung zu öffnen. Wenn --confirmed fehlt, wird confirmation_required zurückgegeben; wenn eines der erwarteten Felder fehlt, unterschiedlich ist oder nach dem erneuten Stage abweicht, wird confirmation_mismatch zurückgegeben; beide Fälle schreiben nichts in das Benutzer-HOME.
Vor dem ersten Schreibbefehl überprüft das Skript mit CAS den Benutzer-Marketplace und den aktiven Cache erneut. Wenn diese sich von der vor dem Stage gespeicherten alten Identität unterscheiden, wird activation_state_changed zurückgegeben, die Aktivierung beginnt nicht, und es wird nichts in das Benutzer-HOME geschrieben. Wenn ein Schritt des Schreibtransaktions fehlschlägt, überprüft das Skript zunächst den Nachzustand von Marketplace und Cache:
activation_failed_no_change: Nach dem Fehler ist der Zustand immer noch vollständig gleich der alten Identität; kein Rollback erforderlich,userMutationPerformed=falseactivation_failed_rolled_back: Die Kandidatenaktivierung ist fehlgeschlagen, aber die alte exakte Revision und der alte Cache wurden vollständig wiederhergestelltactivation_cache_locked_rolled_back: Der Fehler wurde als Cache/Datei-Handle-Belegung identifiziert, und der alte Zustand wurde vollständig wiederhergestelltactivation_failed_rollback_incomplete: Das Rollback ist fehlgeschlagen, oder es kann nicht nachgewiesen werden, dass sowohl Marketplace als auch Cache zum alten Zustand zurückgekehrt sind; der tatsächliche Nachzustand wird gemeldet, und es wird gestoppt
Nur wenn sich der Nachzustand geändert hat, wird mit der gespeicherten alten exakten Revision ein offizielles remove → add --ref <old B> → upgrade rollback ausgeführt und der Cache erneut direkt ausgelesen. Keiner dieser Fehlerzustände darf als „bereits aktualisiert“ bezeichnet werden. Es ist nicht erlaubt, Cache manuell zu kopieren oder zu löschen, um einen Erfolg vorzutäuschen; Runtime, Projekte, Medien, EDL oder Studio-Status dürfen nicht berührt werden.
Benutzer sagt „Schnittumgebung installieren / Player installieren / Umgebung prüfen“
Direkt die vollständige Bereitschaftsprüfung ausführen; nach Erhalt von „Bereit“ die vollständige Selbstprüfung ausführen und unverändert berichten:
node "<Plugin-Stamm>/scripts/videocut-cli.cjs" doctor --json
Bericht: Runtime-Version und -Ort, Ergebnis jeder einzelnen Prüfung des Doctors, Reparaturmethoden für fehlende Teile (Maschinenabhängigkeiten: Installationsanleitung; Transkriptionsanmeldedaten: Anleitung zu node "<Plugin-Stamm>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>).
Wenn runtime.kind=desktop-managed ist, wird klar erklärt, dass Bun/FFmpeg/FFprobe aus dem Desktop-Paket stammen und keine Änderung des System-PATH erforderlich ist. Nach der Installation dem Benutzer mitteilen: Einfach „Sprachaufnahme schneiden“ sagen, um zu beginnen.
Grenzen
- Plugin-Version und Runtime-Version sind voneinander unabhängig; die minimale Kompatibilität und das Release-Ziel der Runtime werden durch den Vertrag in
runtime-requirements.jsongesteuert, in diesem Dokument werden keine Versionsnummern hartcodiert. stablewird nur für die temporäre Erkennung verwendet; es wird nicht als dauerhafte Referenz des Benutzers installiert, und temporäres Staging, Legacy-Cache oder lokale Verzeichnisse werden nicht als aktivierte Version bezeichnet.- In der Update-Prüfphase werden keine Codex-Aufrufe und keine Schreibvorgänge im Benutzer-HOME durchgeführt; erst nachdem version + B + A + SHA-256 gesehen und bestätigt wurden, kann die rückrollbare Aktivierung beginnen.
- Es werden keine Projektdaten oder Medien veröffentlicht oder geändert; die offizielle Codex-Aktivierung nach Benutzerbestätigung und die Runtime-Installation sind die einzigen Ausnahmen für Schreibvorgänge.
- Es werden keine Electron-
.app-, NSIS-Installationsverzeichnisse durchsucht oder Electron-Ressourcenpfade an Geschäfts-Skills übergeben; die Desktop-App ist für das Schreiben eines stabilen Produkteinstiegspunkts verantwortlich, Skills erkennen nur diesen Einstiegspunkt.