检查更新(環境総合管理) は何をしますか?
環境に関するすべてのロジックは本Skillにのみ記述します:skillsのバージョン、Runtimeのインストールとヘルスチェック。 業務Skillの第0ステップは、以下の「準備完了チェック」を一行で参照するだけで、自ら環境ロジックを持ちません。環境戦略を変更する場合、このファイルだけを修正すれば済みます。 本Skillはプロジェクトを作成せず、Studioを起動せず、あらゆるメディアをトランスコードしません。
準備完了チェック(業務Skillの第0ステップはここから実行)
3ステップを完了し、次の3状態のいずれかを出力します:準備完了 / 新規セッションが必要 / 停止。
一、現在のPlugin cacheの特定(読み取り専用)
hostから提供される本Skillの実際のソースファイルパスを使用して特定します:本ファイルが存在するディレクトリから2階層上が <プラグインルート> です。ファイル読み取りツールを使用して <プラグインルート>/.codex-plugin/plugin.json と <プラグインルート>/scripts/check-plugin-update.cjs の両方が存在することを確認します。パスが取得できない、ディレクトリ階層が合わない、ファイルが存在しない場合は、installed_identity_missing として更新比較を停止します。ユーザーの CODEX_HOME 下の codex plugin list を呼び出して補完推測したり、ディスク全体を検索してはいけません。
以降のすべてのコマンド内の <プラグインルート> はこのリテラルパスに置き換えます(スペースを含む場合は全体を引用符で囲みます)。
コマンドブロックではシェル変数とコマンド置換を使用しません。bash と PowerShell の代入構文には互換性がないためです。
チェックスクリプトは自身が配置されているcacheから直接、installed manifest、provenance、Marketplace exact revision、bundle digest を読み取ります。チェックフェーズではユーザーのMarketplace CLI出力に依存しません。
二、skillsは最新か
node "<プラグインルート>/scripts/check-plugin-update.cjs" --marketplace chengfeng-videocut --json
(Marketplace名はデフォルトで chengfeng-videocut です。ユーザーが別の名前を設定している場合はその名前を使用します。)
current→ ステップ3へ進むupdate_available_confirmation_required→installed、candidateと候補の4項目(version、40-hexsnapshotRevision(B)、40-hexcontentRevision(A)、publisherChecksum(SHA-256))を表示し、ユーザーの確認を待ちます。確認後は以下の「アクティベーション」節に進みます。 アクティベーション成功 = 新規セッションが必要:セッション開始時にskillテキストはすでに読み込まれているため、途中での更新は現在のセッションに反映されません。ユーザーに新しいセッションを開いてからタスクを続行するよう依頼してください。- 同時に
legacyInstalledIdentity=trueがある場合、これは履歴上の0.10.5から新しい証明形式への一回限りの互換性マイグレーションです。同じ確認プロセスを使用し、ユーザーにMarketplace refの事前変更を要求しません。
- 同時に
marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe→ 現在のユーザーMarketplaceが欠落している、ソースが信頼できない、またはexactな40-hex pinではありません。ユーザーのCodex CLIを呼び出して修復せず、報告してステップ3へ進みます。installed_identity_missing/installed_identity_untrusted→ 現在のcache IDを安全に読み取ったり証明できません。バージョンを推測せず、アクティベーションも行いません。報告してステップ3へ進みます。installed_context_mismatch→ 現在のSkillの実際のcacheパス、Marketplace名、または明示的なCODEX_HOMEが一致しません。他のcacheを検索せず、アクティベーションも行いません。isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed→ 一時的な候補ステージ、CLIスキーマ、または一時ディレクトリのクリーンアップに失敗しました。ユーザーのHOMEには書き込みを行わず、報告してステップ3へ進みます。update_metadata_untrusted→ version + B + A + SHA-256 の証明が成立しません。アクティベーションは行わず、報告してステップ3へ進みます。candidate_older_than_installed→ ダウングレードは禁止です。報告してステップ3へ進みます。- ネットワーク到達不可、またはその他のチェックエラー → ユーザーに一言説明し、現在のRuntimeチェックを付けてステップ3へ進みます。更新チェックの失敗は作業をブロックしません
通常のチェックでは、一時的な CODEX_HOME 内でのみ公式の stable を使用して候補を発見できます。ユーザーの CODEX_HOME に対しては、いかなる codex コマンドも呼び出さず、設定やMarketplace、cacheにも書き込みません。
現在のcacheのバージョンディレクトリはすべてstrict semverである必要があります。低いバージョンの残骸は許可されますが、最も高いsemver優先度を持つものだけがactiveと見なされます。最も高い位置に同じ優先度のディレクトリが存在する場合は installed_identity_untrusted を返し、ディレクトリ名の字句順で選択してはいけません。
三、Runtimeは適合しているか
node "<プラグインルート>/scripts/ensure-runtime.cjs" --install-if-missing --json
ready→ 準備完了。業務Skillは続行します。runtime.kind=desktop-managedは、デスクトップAppがバンドルされたRuntime、Bun、FFmpeg、FFprobeをProductの統一管理ディレクトリにインストール済みであることを示します。Skillsはこれを直接再利用し、追加で依存関係をインストールしたり、別のサービスを起動したりしません。runtime.kind=managed/path/sourceは依然として互換性のあるCLIインストール元です。後続の業務契約は同じです。
- missing:スクリプトは一度だけ「GitHub Releaseからインストール中です」とプロンプトを表示し、SHA-256検証完了後に自動的に再実行します。
runtime_unhealthy、インストール失敗、またはインストール後のdoctor失敗 → 停止。構造化された診断情報を報告します。 停止は停止です。自作のレビューページ、プレーヤー、タイムライン、またはその他の代替インターフェースを使用して処理を続行することは禁止されています。 製品が利用できない状態で生成された成果物はすべて信頼できません(実際の事例:Runtime欠落時にAgentが自作の「レビューページ」Webページを作成し、そのレビュー判断が製品の台帳フォーマットと完全に互換性がなく、ユーザーは無駄な作業を強いられました)。 正しいアクションはただ一つ:構造化診断情報をユーザーに提供し、インストール手順を案内するか、Issueを報告するよう促すことです。runtime_capability_missing→ 停止:Runtimeは健全ですが、契約要件を下回っています。二つのバージョン番号と差異を報告し、ユーザーに確認の上でアップグレードを案内します(アップグレードは~/.chengfeng-videocut/appを置き換え、プロジェクトデータは変更しません)。ユーザーが確認するまでは既存のインストールに触れず、古い編集チェーンにロールバックすることも禁止します。- 準備完了チェックフェーズでは、サービスの起動、Studioのオープン、プロジェクトの作成を禁止します。
マシンの前提依存関係
macOS および Windows 10/11 をサポートし、2つのインストールパスがあります:
デスクトップ版(推奨)
Chengfeng VideoCutをインストールし、少なくとも一度起動する
-> AppがBun、FFmpeg、FFprobe、Runtimeをバンドルインストール
-> ユーザーはこれらのツールをシステムPATHに追加する必要はありません
-> Skillsは ~/.chengfeng-videocut/bin の安定したエントリポイントを通じて同じサービスを再利用
純粋なCLIインストール
macOS brew install bun ffmpeg
Windows winget install Oven-sh.Bun Gyan.FFmpeg
インストール後、新しいターミナル/セッションを開いてPATHを有効にする
どちらのパスでも、Pluginスクリプトを実行するためにNode.js ≥ 20が必要です。字幕/アニメーションのエクスポートにはGoogle Chromeが必要です。純粋なCLIユーザーは自分でインストールします。Windowsでは winget install OpenJS.NodeJS.LTS Google.Chrome が使用できます。不足している場合は明確に停止し、黙ってスキップしてはいけません。
Skills更新IDの自己証明にはさらにGitが必要です。Windowsでは winget install Git.Git が使用できます。Gitが実行不可能、または公式snapshotのorigin/HEAD/コミット関係を読み取れない場合、更新チェックはfail-closedとなりますが、上記のルールに従ってRuntimeチェックは続行されます。
クラウド文字起こしにはさらにボルケノエンジンの認証情報が必要です:node "<プラグインルート>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>。
詳細なプロトコルについては Runtimeと製品契約 を参照してください。
Skills 更新:inspect と アクティベーション
純粋な参照は現在のPlugin cacheを読み取り専用で行います。ネットワーク接続せず、codex を呼び出さず、ユーザーの CODEX_HOME にも書き込みません:
node "<プラグインルート>/scripts/check-plugin-update.cjs" --marketplace "<マーケット名>" --inspect --json
成功すると inspected_no_refresh を返し、現在のpinned Marketplaceとcache IDのみを含み、リモート候補は生成しません。
ネットワーク接続分離チェック(ユーザーが明示的に「更新を確認」と指示した場合、または準備完了チェックのステップ2):
node "<プラグインルート>/scripts/check-plugin-update.cjs" --marketplace "<マーケット名>" --json
current:installedと一時環境で見つかった最新の公開IDを報告します。update_available_confirmation_required:installedと候補の4項目(version、snapshotRevision(B)、contentRevision(A)、publisherChecksum)を表示します。ユーザーの確認を待って停止します。legacyInstalledIdentity=true:現在は互換性のある履歴上の0.10.5 cacheです。これは上記の通常の確認フローに入ることができます。古いIDはMarketplace exact revision、cacheディレクトリバージョン、manifest version、inventory digestによって共同でバインドされています。ユーザーに先にrefを変更させたり、「移行成功」という別の状態を作り出したりしないでください。marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe:現在のユーザーMarketplaceが欠落している、信頼できない、または自身のexact 40-hex revisionに固定されていません。自動的にrefを変更しません。installed_identity_missing/installed_identity_untrusted:現在のcacheが認識できない、または信頼できません。installedバージョンを推測しません。installed_context_mismatch:スクリプトの実行位置が、現在のMarketplaceの唯一の最高active cacheではない、または明示的なCODEX_HOMEがそのcacheが属するHOMEと一致しません。ディレクトリを横断して補完推測しません。isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed:一時ステージ、CLI JSONスキーマ、またはクリーンアップの失敗のみを説明し、ユーザーのインストールが更新されたことを示唆しません。update_metadata_untrusted:一時スナップショットにB、A、SHA-256/マニフェスト再計算証明が欠けているか、マニフェスト、Marketplace revision、provenanceの間でIDが矛盾しています。candidate_older_than_installed:より新しいローカルバージョンからのダウングレードは禁止されています。- 何らかのsnapshot/parse/versionエラー:構造化JSONを保持します。ユーザーHOMEは
userMutationPerformed=falseです。
スクリプトは新しく作成された一時的な CODEX_HOME 内でのみ公式のMarketplace CLIを実行します:最初に marketplace add Agentchengfeng/chengfeng-videocut-skills --ref stable でディスカバリソースを確立し、同じ一時HOME内で marketplace upgrade でスナップショットを具体化し、plugin list で候補を取得します。stable から解決された40-hex B、provenance内の40-hex A、manifest version、再計算可能なSHA-256が共同で候補を構成します。Gitはさらに、一時Marketplaceのoriginが公式リポジトリであること、HEAD=B、AがBの祖先であること、Plugin作業ツリーがクリーンであること、A→BのPluginサブツリーがprovenanceのみを変更することを証明する必要があります。一時ディレクトリは使用後に削除されます。ユーザーHOMEのMarketplaceは以前に確認されたexact Bに維持されなければなりません。チェックフェーズでは、それに対して読み取り専用の codex コマンドさえ呼び出しません。
Windows上で codex / git を解決する際は、最初に PATHEXT に従って実行可能拡張子を検索し、次に拡張子なしのファイルを試みます。.cmd / .bat は ComSpec を介してラップされます。これにより、pnpm同ディレクトリのUnix codex shimが codex.cmd を覆い隠すことはありません。
ユーザーが明示的に確認した後にのみアクティベート
確認は、ユーザーがexact candidate version、B、A、checksumを確認した後でのみ行われなければなりません:
node "<プラグインルート>/scripts/check-plugin-update.cjs" --marketplace "<マーケット名>" --activate --confirmed --expected-version "<表示されたバージョン>" --expected-snapshot-revision "<表示されたB>" --expected-content-revision "<表示されたA>" --expected-sha256 "<表示されたパッケージSHA256>" --json
スクリプトは一時的な CODEX_HOME を再作成し、再度 stable から候補をステージングし、4項目すべてを --expected-* と比較しなければなりません。ステージング前後で候補がずれたり、パラメータが一致しない場合は confirmation_mismatch を返し、ユーザーHOMEにはゼロ書き込みです。合格後は、更新前のexact snapshot revisionとcache IDを記録し、公式コマンドのみを使用してユーザーHOMEに対して以下の操作を実行します:
plugin marketplace remove <マーケット名>
plugin marketplace add Agentchengfeng/chengfeng-videocut-skills --ref <B>
plugin marketplace upgrade <マーケット名>
<B> は、直前に再ステージングされ、ユーザーが確認したものと一致する40-hex snapshotRevision でなければなりません。stable、他のブランチ、タグ、短縮SHA、または任意の異なるrefは marketplace_ref_unsafe を返します。upgrade後、スクリプトはcacheから直接version + B + A + SHA-256を再読み取りして検証し、完全に一致した場合のみ activated を返します。アクティベーション成功後は、ユーザーにCodexを再起動するか、新しいセッションを開くよう通知します。--confirmed がない場合は confirmation_required を返します。いずれかのexpectedフィールドが欠けている、異なる、または再ステージング後にずれている場合は confirmation_mismatch を返します。どちらの場合もユーザーHOMEへの書き込みはゼロです。
最初の書き込みコマンドに入る前に、スクリプトはCASでユーザーのMarketplaceとactive cacheを再読み取りします。ステージング前に保存された古いIDと異なる場合は activation_state_changed を返し、アクティベーションは開始されず、ユーザーHOMEへの書き込みはゼロです。書き込みトランザクションのいずれかのステップが失敗した場合、スクリプトはまずMarketplaceとcacheの事後状態を確認します:
activation_failed_no_change:失敗後も古いIDと完全に等しい。ロールバックの必要はなく、userMutationPerformed=falseactivation_failed_rolled_back:候補のアクティベーションに失敗したが、古いexact revisionと古いcacheは完全に復元されたactivation_cache_locked_rolled_back:失敗がcache/ファイルハンドルの占有と認識され、古い状態が完全に復元されたactivation_failed_rollback_incomplete:ロールバックに失敗したか、Marketplaceとcacheの両方が古いIDに戻ったことを証明できない。実際の事後状態を報告して停止します
事後状態が変化している場合のみ、保存されたold exact revisionを使用して、公式のremove → add --ref <old B> → upgradeロールバックを実行し、再度直接cacheを読み取ります。上記の失敗状態はいずれも「更新済み」とは言えません。成功を偽装するためにcacheを手動でコピーまたは削除してはいけません。Runtime、プロジェクト、メディア、EDL、Studioの状態に触れてはいけません。
ユーザーが「編集環境をインストールして / プレーヤーをインストールして / 環境をチェックして」と言った場合
完全な準備完了チェックを直接実行します。結果が「準備完了」になったら、完全なセルフチェックを実行し、そのまま報告します:
node "<プラグインルート>/scripts/videocut-cli.cjs" doctor --json
報告内容:Runtimeのバージョンと場所、doctorの各チェック結果、不足項目の修正方法(マシン依存関係のインストール手順、文字起こし認証情報の設定手順 node "<プラグインルート>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>)。runtime.kind=desktop-managed の場合は、Bun/FFmpeg/FFprobeがデスクトップパッケージ由来であり、システムPATHを変更する必要がないことを明確に説明します。インストール完了後は、「カット原稿編集(剪口播)」と言えば開始できると伝えます。
境界
- PluginのバージョンとRuntimeのバージョンは互いに独立しています。Runtimeの最小互換性とリリースターゲットは
runtime-requirements.jsonコントラクトによって制御され、本文にバージョン番号をハードコードしません。 stableは一時的なディスカバリにのみ使用されます。ユーザーインストールの永続的なrefとして書き込んだり、一時ステージング、レガシーcache、ローカルディレクトリをアクティブなバージョンとして説明したりしません。- 更新チェックフェーズでは、ユーザーのHOMEに対してCodexの呼び出しも書き込みも行いません。version + B + A + SHA-256の確認と承諾があった後にのみ、ロールバック可能なアクティベーションを開始できます。
- 公開、プロジェクトデータやメディアの変更は行いません。ユーザー確認後の公式CodexアクティベーションとRuntimeインストールが唯一の書き込み例外です。
- Electron
.app、NSISインストールディレクトリを検索したり、Electronリソースパスを業務Skillに渡したりしません。デスクトップAppは安定したProductエントリポイントを書き込む責任があり、Skillsはそのエントリポイントのみを認識します。