檢查更新(環境總管) 是做什麼的?
環境的一切邏輯只寫在本 Skill:skills 版本、Runtime 安裝與體檢。業務 Skill 第 0 步 一行引用下面的「就緒檢查」,自己不帶任何環境邏輯——環境策略要變,只改這一個檔案。 本 Skill 不建項目、不打開 Studio、不轉錄任何媒體。
就緒檢查(業務 Skill 的第 0 步從這裡執行)
三步走完,輸出三態之一:就緒 / 需新會話 / 停。
一、定位當前 Plugin cache(唯讀)
從 host 提供的本 Skill 實際源檔案路徑定位:本檔案所在目錄向上兩級就是
<插件根>。用檔案讀取工具確認 <插件根>/.codex-plugin/plugin.json 與
<插件根>/scripts/check-plugin-update.cjs 都存在。路徑不可取得、目錄層級不符或
檔案不存在時,以 installed_identity_missing 停止更新比較;不得調用用戶
CODEX_HOME 下的 codex plugin list 補猜,也不得搜索整個磁碟。
此後所有命令裡的 <插件根> 都帶入這個字面路徑(含空格時整段引號包住)。
命令塊不用 shell 變數與命令替換——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→ 繼續第三步update_available_confirmation_required→ 展示installed、candidate與候選四項: 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 修復,報告後繼續第三步installed_identity_missing/installed_identity_untrusted→ 當前 cache 身分無法 安全讀取或證明,不猜版本、不激活;報告後繼續第三步installed_context_mismatch→ 當前 Skill 的真實 cache 路徑、Marketplace 名或 顯式CODEX_HOME不一致;不搜索其他 cache,也不激活isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed→ 臨時候選 stage、CLI schema 或臨時目錄清理失敗;用戶 HOME 零寫入,報告後繼續第三步update_metadata_untrusted→ version + B + A + SHA-256 證明不成立,不激活; 報告後繼續第三步candidate_older_than_installed→ 禁止降級,報告後繼續第三步- 網路不可達或其他檢查錯誤 → 向用戶說明一句,帶當前 Runtime 檢查繼續第三步—— 更新檢查失敗不阻塞幹活
正常檢查只允許在臨時 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 手搓了一個 「審片台」網頁,其審核決定與產品的帳本格式完全不相容,用戶白做一遍)。 正確動作只有一個:把結構化診斷給用戶,指引安裝或上報 Issueruntime_capability_missing→ 停:Runtime 健康但低於合同要求。報告兩個版本號 與差異,指引用戶確認後升級(升級替換~/.chengfeng-videocut/app,項目資料不動); 用戶未確認前不動現有安裝,禁止回退舊剪輯鏈- 就緒檢查階段禁止啟動服務、打開 Studio 或創建項目
機器前置依賴
支援 macOS 與 Windows 10/11,分兩條安裝路徑:
桌面版(推薦)
安裝並至少啟動一次 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 才生效
兩條路徑都仍需要 Node.js ≥ 20 來執行 Plugin 腳本;導出字幕/動畫仍需要 Google
Chrome。純 CLI 用戶自行安裝,Windows 可用
winget install OpenJS.NodeJS.LTS Google.Chrome。缺項時必須明確停止,不靜默跳過。
Skills 更新身分自證還需要 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 身分,不生成
遠端候選。
聯網隔離檢查(用戶明確說「檢查更新」,或就緒檢查第二步):
node "<插件根>/scripts/check-plugin-update.cjs" --marketplace "<市場名>" --json
current:報告 installed 與臨時環境發現的最新發布身分。update_available_confirmation_required:展示 installed 與候選四項 version、snapshotRevision(B)、contentRevision(A)、publisherChecksum;停止等用戶確認。legacyInstalledIdentity=true:當前是相容的歷史 0.10.5 cache。它可以進入上一條 正常確認流程;舊身分由 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:只說明臨時 stage、CLI JSON schema 或清理失敗,不暗示 用戶安裝已刷新。update_metadata_untrusted:臨時 snapshot 缺 B、A、SHA-256/清單複算證明,或 manifest、Marketplace revision 與 provenance 的身分互相矛盾。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 materialize snapshot,並以
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 stage 候選,並把四項與
--expected-* 全部比較。stage 前後候選漂移或參數不符返回
confirmation_mismatch,用戶 HOME 零寫入。通過後記錄更新前的 exact
snapshot revision 與 cache 身分,再只用官方命令對用戶 HOME 執行:
plugin marketplace remove <市場名>
plugin marketplace add Agentchengfeng/chengfeng-videocut-skills --ref <B>
plugin marketplace upgrade <市場名>
<B> 必須是剛剛重新 stage 並與用戶確認一致的 40-hex
snapshotRevision;stable、其他分支、tag、短 SHA 或任意不同 ref 都返回
marketplace_ref_unsafe。upgrade 後腳本直接從 cache 復讀並驗證 version + B + A +
SHA-256,完全一致才返回 activated。激活成功後告知用戶重啟 Codex 或新開會話。
缺少 --confirmed 時返回 confirmation_required;任一 expected 字段缺失、不同或
重新 stage 後漂移時返回 confirmation_mismatch,兩者都保持用戶 HOME 零寫入。
進入第一條寫命令前,腳本以 CAS 再復讀用戶 Marketplace 與 active cache。若與
stage 前保存的舊身分不同,返回 activation_state_changed,激活不開始且用戶 HOME
零寫入。寫事務任一步失敗時,腳本先檢查 Marketplace 與 cache 的後置狀態:
activation_failed_no_change:失敗後仍完整等於舊身分;無需回滾,userMutationPerformed=falseactivation_failed_rolled_back:候選激活失敗,但舊 exact revision 與舊 cache 已完整恢復activation_cache_locked_rolled_back:失敗被識別為 cache/檔案句柄佔用,且舊狀態 已完整恢復activation_failed_rollback_incomplete:回滾失敗,或無法證明 Marketplace 與 cache 都回到舊身分;報告實際後置狀態並停止
只有後置狀態已變化時,才用儲存的 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 的最低相容與 Release 目標由
runtime-requirements.json合同控制,不在本文硬編碼任何版本號 stable只用於臨時發現;不把它寫成用戶安裝的持久 ref,也不把臨時 staging、 legacy cache 或本地目錄說成已激活版本- 檢查更新階段對用戶 HOME 零 Codex 調用、零寫入;只有看見並確認 version + B + A + SHA-256 後才能開始可回滾激活
- 不發布、不改項目資料或媒體;用戶確認後的官方 Codex activation 與 Runtime 安裝是僅有的寫入例外
- 不搜索 Electron
.app、NSIS 安裝目錄或把 Electron 資源路徑交給業務 Skill; 桌面 App 負責寫入穩定 Product 入口,Skills 只認該入口