Communitygithub.com

检查更新(環境総合管理)

剪辑环境的唯一管理者:检查技能是否为最新、运行时是否匹配、更新技能、安装并验证运行时环境。

检查更新(環境総合管理) とは?

このスキルは、動画編集環境の状態を統合的に管理するための「環境管理スキル」です。具体的には、スキル自身のバージョン管理(Marketplaceからの更新確認とアクティベーション)、ランタイム(Node.js, Bun, FFmpeg など)のインストール状態と健全性チェック、そしてこれらを統合した「準備完了チェック」をワンストップで提供します。開発者は「環境をチェックして」「更新を確認して」「ランタイムをインストールして」といった自然言語の指示からこのスキルを呼び出せます。また、他の業務スキル(カット編集・字幕・画面出力など)は、その処理の第0ステップとしてこのスキルの準備完了チェックを呼び出すことが推奨されており、環境に関するロジックを一元化することで、変更が発生した場合のメンテナンスコストを大幅に削減します。対応プラットフォームはmacOSとWindowsで、デスクトップ版アプリ(Chengfeng VideoCut)と純粋なCLIの二つのインストールパスをサポートし、トラブル発生時には構造化された診断情報を提供して、誤ったワークフローの継続を防止します。

対応~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/2789927464king-jpg/video-skill-ku/tree/HEAD/chengfeng-videocut-skills/plugins/chengfeng-videocut/skills/chengfeng-check-updates

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

检查更新(環境総合管理) は何をしますか?

環境に関するすべてのロジックは本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-hex snapshotRevision(B)、40-hex contentRevision(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=false
  • activation_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はそのエントリポイントのみを認識します。

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

2789927464king-jpg/video-skill-ku

剪辑中文口播原素材:逐词转录、词典修字出修字表、五轮扫描找口误与重复、汇总表与重复句子表、打开 Studio 让用户复核、复盘沉淀用户偏好与词典。只产出一份已复核的删词账本,不切媒体、不做字幕、不做分镜动画。用户说剪口播、处理口误、生成口播基础素材、继续剪口播,或确认卡回传 action=return_cut_review 时使用。不要用于执行物理剪切、导出剪后视频、单独安装、单独打开工作台或口播分镜成片。

2789927464king-jpg/video-skill-ku

把剪好的口播烧成一个成片文件:账本切片段、推近、字幕、HTML 画面层,一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。

2789927464king-jpg/video-skill-ku

整理、脱敏并上报 chengfeng-videocut 的 GitHub Bug。用户说上报 Bug、反馈剪口播问题、提交 GitHub Issue、这个问题告诉开发者,或要求继续提交已预览的 Bug 草稿时使用。不要用于功能建议、普通排错、代码提交或未获用户确认的自动上报。

2789927464king-jpg/video-skill-ku

给剪好的口播做字幕:直接用已有的逐词稿加账本算出剪后时间(不必导出、不必重新转录)、用词典和作者文稿改写听错的专名、按句子分屏、在 Studio 里逐屏复核。用户说做字幕、加字幕、改字幕、重新分屏、字幕不对时使用。不要用于删词剪辑、物理剪切、分镜动画或成片渲染。

2789927464king-jpg/video-skill-ku

操作 chengfeng-videocut 剪辑工作台的已有工程,通过 Runtime CLI 查工程与词句位置、添加或替换画面覆盖层、移除画面、删除明确指定的词句或片段、拆分裁剪移动已有片段、调整画布比例并回读核验。用户说插入片段、删掉这句、移除动画、换个画面、调整顺序或管理时间线时使用;先区分画面覆盖与主轨顺延插入,不负责自动判断口误、创作动画、制作字幕、导出或排查安装故障。

2789927464king-jpg/video-skill-ku

Create Ian Xiaohei-style HTML/SVG motion illustrations for Chinese articles, scripts, storyboard scenes, workflow explanations, concept metaphors, and short video visual aids. Use when the user asks for 小黑 SVG、漫画感 HTML、分层 SVG 动效、把小黑生图做成 HTML/SVG、可编辑矢量动效、口播流程动画、手绘漫画动效、正文配图动画, or wants a Xiaohei illustration style adapted into controllable HTML/SVG/GSAP output instead of raster image generation.

2789927464king-jpg/video-skill-ku

给剪好的口播配画面:在录屏上盖 HTML 层(圈重点标注 / 小黑整屏动画 / 推近),层绑字幕屏、由播放器逐帧驱动、直接在预览里看。用户说做分镜、配画面、加动画、圈重点、B-roll、做 storyboard 时使用。不要用于删词剪辑、字幕、物理剪切或成片渲染。

2789927464king-jpg/video-skill-ku

剪映 (JianYing) AI自动化剪辑的高级封装 API (JyWrapper),提供开箱即用的 Python 接口,支持录屏、素材导入、字幕生成、Web 动效合成及项目导出。全面适配 MacOS (Apple Silicon/Intel) 与 Windows,支持 v5.9+ (draft_info.json) 架构、工程自修复、智能配音字幕及录屏变焦。

関連スキル