Vérification des mises à jour (Gestionnaire d'environnement)
Toute la logique de l'environnement réside uniquement dans ce Skill : version des skills, installation et diagnostic du Runtime. Les Skills métier l'appellent à l'étape 0 en une seule ligne via la « vérification de disponibilité » ci-dessous, sans inclure aucune logique d'environnement propre – pour modifier la stratégie d'environnement, ne modifier que ce fichier. Ce Skill ne crée pas de projet, n'ouvre pas Studio et ne transcrit aucun média.
Vérification de disponibilité (Étape 0 des Skills métier depuis ici)
Trois étapes, trois états possibles : Prêt / Nouvelle session nécessaire / Arrêt.
1. Localiser le cache actuel du Plugin (lecture seule)
À partir du chemin du fichier source réel de ce Skill fourni par l'hôte : remonter de deux niveaux depuis le répertoire de ce fichier permet d'obtenir <racine du plugin>. Utiliser un outil de lecture de fichier pour confirmer que <racine du plugin>/.codex-plugin/plugin.json et <racine du plugin>/scripts/check-plugin-update.cjs existent tous les deux. Si le chemin est inaccessible, la structure de répertoires ne correspond pas, ou les fichiers sont absents, interrompre la comparaison des mises à jour avec installed_identity_missing ; il ne faut pas appeler codex plugin list de l'utilisateur sous CODEX_HOME pour le deviner, ni chercher sur tout le disque.
Dans toutes les commandes suivantes, <racine du plugin> est remplacé par ce chemin littéral (mettre entre guillemets s'il contient des espaces).
Les blocs de commandes n'utilisent pas de variables shell ni de substitutions – la syntaxe d'affectation de bash et PowerShell est incompatible.
Le script de vérification lit directement le manifeste installé, la provenance, la révision exacte du Marketplace et le digest du bundle depuis son propre cache ; la phase de vérification ne dépend pas de la sortie CLI du Marketplace utilisateur.
2. Les skills sont-ils à jour ?
node "<racine du plugin>/scripts/check-plugin-update.cjs" --marketplace chengfeng-videocut --json
(Le nom du Marketplace est chengfeng-videocut par défaut ; si l'utilisateur en a configuré un autre, utiliser le sien.)
current→ passer à l'étape 3update_available_confirmation_required→ afficherinstalled,candidateet les quatre éléments du candidat : version,snapshotRevision(B) en hexa 40,contentRevision(A) en hexa 40,publisherChecksum(SHA-256), s'arrêter et attendre la confirmation de l'utilisateur ; après confirmation, suivre la section « Activation » ci-dessous. Activation réussie = Nouvelle session nécessaire : le texte du skill est chargé au début de la session, une mise à jour en cours de session ne prend pas effet. Demander à l'utilisateur d'ouvrir une nouvelle session avant de continuer la tâche.- Si
legacyInstalledIdentity=trueest présent, il s'agit d'une migration de compatibilité unique de la version historique 0.10.5 vers le nouveau format de preuve ; utiliser la même porte de confirmation, sans exiger de l'utilisateur de modifier au préalable la référence du Marketplace.
- Si
marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe→ le Marketplace de l'utilisateur actuel est manquant, sa source n'est pas fiable ou n'est pas un pin exact en hexa 40 ; ne pas appeler la CLI Codex de l'utilisateur pour le réparer, signaler et passer à l'étape 3.installed_identity_missing/installed_identity_untrusted→ l'identité du cache actuel ne peut pas être lue ou prouvée de manière sécurisée ; ne pas deviner de version, ne pas activer ; signaler et passer à l'étape 3.installed_context_mismatch→ le chemin réel du cache de ce Skill, le nom du Marketplace ou leCODEX_HOMEexplicite ne correspondent pas ; ne pas chercher dans d'autres caches, ne pas activer.isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed→ le stage temporaire du candidat, le schéma CLI ou le nettoyage du répertoire temporaire a échoué ; zéro écriture sur le HOME de l'utilisateur, signaler et passer à l'étape 3.update_metadata_untrusted→ la preuve avec version + B + A + SHA-256 n'est pas valide, ne pas activer ; signaler et passer à l'étape 3.candidate_older_than_installed→ interdiction de rétrograder, signaler et passer à l'étape 3.- Erreur réseau ou autre erreur de vérification → expliquer brièvement à l'utilisateur, vérifier le Runtime actuel et passer à l'étape 3 – un échec de vérification des mises à jour ne bloque pas le travail.
La vérification normale n'est autorisée qu'à utiliser le stable officiel dans un CODEX_HOME temporaire pour découvrir un candidat ; aucune commande codex n'est appelée sur le CODEX_HOME de l'utilisateur, et aucune configuration, Marketplace ou cache n'est écrit.
Le répertoire de version du cache actuel doit être strictement semver ; les versions inférieures résiduelles sont autorisées, mais seule la version semver la plus élevée est considérée comme active. Si plusieurs répertoires de même priorité existent dans la position la plus élevée, retourner installed_identity_untrusted, sans choisir par ordre alphabétique des noms de répertoire.
3. Le Runtime est-il compatible ?
node "<racine du plugin>/scripts/ensure-runtime.cjs" --install-if-missing --json
ready→ Prêt, le Skill métier continue.runtime.kind=desktop-managedindique que l'application de bureau a installé le Runtime, Bun, FFmpeg et FFprobe dans un répertoire géré unifié du Produit ; les Skills les réutilisent directement, sans installer de dépendances supplémentaires ni démarrer de nouveaux services.runtime.kind=managed/path/sourcereste une source d'installation CLI compatible ; le contrat métier ultérieur est identique.
- missing : le script n'affiche qu'une seule fois « Installation en cours depuis GitHub Release », après vérification du SHA-256, il se relance automatiquement.
runtime_unhealthy, échec d'installation ou échec du diagnostic après installation → Arrêt, rapporter un diagnostic structuré. Arrêt signifie arrêt : interdiction d'utiliser une page de révision maison, un lecteur, une timeline ou toute interface alternative pour continuer le processus. Toute sortie produite lorsque le produit est indisponible est non fiable (cas réel : lorsque le Runtime manquait, l'Agent a bricolé une page web de « table de montage », dont les décisions de révision étaient totalement incompatibles avec le format de registre du produit, forçant l'utilisateur à tout refaire). La seule action correcte : fournir le diagnostic structuré à l'utilisateur, l'orienter vers l'installation ou la soumission d'un Issue.runtime_capability_missing→ Arrêt : le Runtime est sain mais inférieur aux exigences du contrat. Rapporter les deux numéros de version et la différence, orienter l'utilisateur vers une mise à jour après confirmation (la mise à jour remplace~/.chengfeng-videocut/app, les données de projet sont inchangées) ; ne pas toucher à l'installation existante avant confirmation de l'utilisateur, interdire le retour à une ancienne chaîne de montage.- Pendant la phase de vérification de disponibilité, il est interdit de démarrer des services, d'ouvrir Studio ou de créer des projets.
Dépendances préalables de la machine
Supporte macOS et Windows 10/11, deux voies d'installation :
Application de bureau (recommandée)
Installer et lancer Chengfeng VideoCut au moins une fois
-> L'App installe Bun, FFmpeg, FFprobe et le Runtime
-> L'utilisateur n'a pas besoin d'ajouter ces outils au PATH système
-> Les Skills réutilisent le même service via l'entrée stable ~/.chengfeng-videocut/bin
Installation CLI pure
macOS brew install bun ffmpeg
Windows winget install Oven-sh.Bun Gyan.FFmpeg
Ouvrir un nouveau terminal/session après installation pour que le PATH prenne effet
Les deux voies nécessitent toujours Node.js ≥ 20 pour exécuter les scripts Plugin ; l'export de sous-titres/animations nécessite toujours Google Chrome. Les utilisateurs CLI pure doivent les installer eux-mêmes ; sur Windows, utiliser winget install OpenJS.NodeJS.LTS Google.Chrome. En cas d'absence, l'arrêt doit être explicite, sans silence.
La preuve d'identité de mise à jour des Skills nécessite également Git ; sur Windows, utiliser winget install Git.Git. Si Git n'est pas exécutable ou ne peut pas lire la relation origin/HEAD/commit du snapshot officiel, la vérification de mise à jour échoue fermée, mais suit toujours les règles ci-dessus pour la vérification du Runtime.
La transcription cloud nécessite en outre des identifiants Volcano Engine : node "<racine du plugin>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>.
Voir le contrat détaillé dans Runtime et contrat produit.
Mise à jour des Skills : inspection et activation
La simple inspection en lecture seule du cache actuel du Plugin : pas de connexion réseau, pas d'appel à codex, pas d'écriture sur le CODEX_HOME de l'utilisateur :
node "<racine du plugin>/scripts/check-plugin-update.cjs" --marketplace "<nom du marché>" --inspect --json
Retourne inspected_no_refresh en cas de succès, contenant uniquement la référence actuelle du Marketplace épinglé et l'identité du cache, sans générer de candidat distant.
Vérification isolée en ligne (l'utilisateur dit explicitement « vérifier les mises à jour », ou à l'étape 2 de la vérification de disponibilité) :
node "<racine du plugin>/scripts/check-plugin-update.cjs" --marketplace "<nom du marché>" --json
current: rapporter l'identité installée et la plus récente version publiée découverte dans l'environnement temporaire.update_available_confirmation_required: afficher les quatre éléments de l'installé et du candidat : version,snapshotRevision(B),contentRevision(A),publisherChecksum; s'arrêter et attendre la confirmation de l'utilisateur.legacyInstalledIdentity=true: le cache actuel est un cache historique compatible 0.10.5. Il peut entrer dans le processus de confirmation normal ci-dessus ; l'ancienne identité est liée conjointement par la révision exacte du Marketplace, la version du répertoire du cache, la version du manifeste et le digest de l'inventaire. Ne pas demander à l'utilisateur de modifier d'abord la ref, ni créer un état « migration réussie » distinct.marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe: le Marketplace actuel de l'utilisateur est manquant, non fiable ou n'est pas épinglé à sa propre révision exacte en hexa 40 ; ne pas modifier automatiquement la ref.installed_identity_missing/installed_identity_untrusted: le cache actuel est non identifiable ou non fiable, ne pas deviner la version installée.installed_context_mismatch: l'emplacement d'exécution du script n'est pas le seul cache actif le plus élevé du Marketplace actuel, ou leCODEX_HOMEexplicite ne correspond pas au HOME de ce cache ; ne pas deviner dans d'autres répertoires.isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed: indique uniquement un échec du stage temporaire, du schéma JSON CLI ou du nettoyage, sans suggérer que l'installation de l'utilisateur a été actualisée.update_metadata_untrusted: le snapshot temporaire manque de preuve B, A, SHA-256/recalcul de l'inventaire, ou l'identité du manifeste, de la révision du Marketplace et de la provenance se contredisent.candidate_older_than_installed: interdiction de rétrograder depuis une version locale plus récente.- Toute erreur de snapshot/parse/version : conserver le JSON structuré ;
userMutationPerformed=false.
Le script n'exécute la CLI officielle du Marketplace que dans un nouveau CODEX_HOME temporaire : d'abord marketplace add Agentchengfeng/chengfeng-videocut-skills --ref stable pour établir la source de découverte, puis marketplace upgrade dans le même HOME temporaire pour matérialiser le snapshot, et plugin list pour obtenir le candidat. Le B en hexa 40 résolu à partir de stable, le A en hexa 40 de la provenance, la version du manifeste et le SHA-256 recalculable constituent ensemble le candidat. Git doit également prouver que l'origine temporaire du Marketplace est le dépôt officiel, que HEAD=B, que A est un ancêtre de B, que l'arbre de travail du Plugin est propre, et que la sous-arborescence Plugin de A→B ne modifie que la provenance. Le répertoire temporaire est supprimé après utilisation. Le Marketplace du HOME de l'utilisateur doit rester sur le B exact précédemment confirmé ; pendant la phase de vérification, aucune commande codex, même en lecture seule, n'est appelée dessus.
Sur Windows, pour résoudre codex / git, chercher d'abord les extensions exécutables selon PATHEXT, puis tenter un fichier sans extension ; .cmd / .bat sont encapsulés via ComSpec. Ainsi, le shim Unix codex du même répertoire que pnpm ne masquera pas codex.cmd.
Activation seulement après confirmation explicite de l'utilisateur
La confirmation doit avoir lieu après que l'utilisateur a vu la version exacte du candidat, B, A et le checksum :
node "<racine du plugin>/scripts/check-plugin-update.cjs" --marketplace "<nom du marché>" --activate --confirmed --expected-version "<version affichée>" --expected-snapshot-revision "<B affiché>" --expected-content-revision "<A affiché>" --expected-sha256 "<SHA256 du paquet affiché>" --json
Le script doit recréer un CODEX_HOME temporaire, re-stager le candidat depuis stable, et comparer les quatre éléments avec tous les --expected-*. Si le candidat dérive avant/après le stage ou si les paramètres ne correspondent pas, retourner confirmation_mismatch, zéro écriture sur le HOME de l'utilisateur. En cas de succès, enregistrer la révision exacte du snapshot avant la mise à jour et l'identité du cache, puis exécuter uniquement des commandes officielles sur le HOME de l'utilisateur :
plugin marketplace remove <nom du marché>
plugin marketplace add Agentchengfeng/chengfeng-videocut-skills --ref <B>
plugin marketplace upgrade <nom du marché>
<B> doit être le snapshotRevision en hexa 40 qui vient d'être re-stagé et confirmé avec l'utilisateur ; stable, d'autres branches, tags, SHA court ou toute autre référence différente retournent marketplace_ref_unsafe. Après la mise à niveau, le script relit directement le cache et vérifie version + B + A + SHA-256 ; il ne retourne activated que si tout correspond parfaitement. Après activation réussie, informer l'utilisateur de redémarrer Codex ou d'ouvrir une nouvelle session. En l'absence de --confirmed, retourner confirmation_required ; si l'un des champs --expected manque, est différent ou dérive après le re-stage, retourner confirmation_mismatch, tous deux avec zéro écriture sur le HOME de l'utilisateur.
Avant la première commande d'écriture, le script relit le Marketplace de l'utilisateur et le cache actif avec CAS. Si l'ancienne identité est différente de celle enregistrée avant le stage, retourner activation_state_changed, l'activation ne commence pas et zéro écriture sur le HOME de l'utilisateur. En cas d'échec de l'une des étapes de la transaction d'écriture, le script vérifie d'abord l'état postérieur du Marketplace et du cache :
activation_failed_no_change: après échec, toujours égal à l'ancienne identité ; aucune restauration nécessaire,userMutationPerformed=falseactivation_failed_rolled_back: l'activation du candidat a échoué, mais l'ancienne révision exacte et l'ancien cache ont été complètement restaurésactivation_cache_locked_rolled_back: l'échec a été identifié comme une occupation du cache/des descripteurs de fichier, et l'ancien état a été complètement restauréactivation_failed_rollback_incomplete: la restauration a échoué, ou il n'est pas possible de prouver que le Marketplace et le cache sont tous deux revenus à l'ancienne identité ; rapporter l'état postérieur réel et s'arrêter
Ce n'est que si l'état postérieur a changé qu'il faut utiliser l'ancienne révision exacte enregistrée pour exécuter la restauration officielle remove → add --ref <old B> → upgrade, et relire directement le cache. Aucun de ces états d'échec ne peut être qualifié de « mis à jour ». Il est interdit de copier ou supprimer manuellement le cache pour simuler un succès ; il est interdit de toucher au Runtime, aux projets, aux médias, à l'EDL ou à l'état de Studio.
L'utilisateur dit « installer l'environnement de montage / installer un lecteur / vérifier l'environnement »
Exécuter directement la vérification de disponibilité complète ; une fois « Prêt » obtenu, exécuter un auto-diagnostic complet et le rapporter tel quel :
node "<racine du plugin>/scripts/videocut-cli.cjs" doctor --json
Rapporter : version et emplacement du Runtime, résultat de chaque vérification du diagnostic, méthode de correction pour les éléments manquants (guider l'installation des dépendances machine ; pour les identifiants de transcription, guider node "<racine du plugin>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>). Si runtime.kind=desktop-managed, préciser clairement que Bun/FFmpeg/FFprobe proviennent du paquet de bureau et qu'il n'est pas nécessaire de modifier le PATH système. Une fois installé, dire à l'utilisateur : dites simplement « monter la voix-off » pour commencer.
Limites
- La version du Plugin et la version du Runtime sont indépendantes ; la compatibilité minimale du Runtime et l'objectif de Release sont contrôlés par le contrat
runtime-requirements.json, aucun numéro de version n'est codé en dur dans ce document. stableest uniquement utilisé pour la découverte temporaire ; ne pas l'écrire comme référence persistante de l'installation de l'utilisateur, ne pas qualifier le staging temporaire, le cache legacy ou le répertoire local de version activée.- Pendant la phase de vérification des mises à jour, zéro appel Codex et zéro écriture sur le HOME de l'utilisateur ; l'activation réversible ne peut commencer qu'après avoir vu et confirmé version + B + A + SHA-256.
- Ne pas publier, ne pas modifier les données de projet ou les médias ; l'activation Codex officielle après confirmation de l'utilisateur et l'installation du Runtime sont les seules exceptions d'écriture.
- Ne pas chercher de
.appElectron, de répertoire d'installation NSIS, ni passer de chemin de ressource Electron à un Skill métier ; l'App de bureau écrit l'entrée stable du Produit, les Skills ne reconnaissent que cette entrée.