Communitygithub.com

檢查更新(環境總管)

管理剪輯環境的唯一管理者:檢查就緒狀態(Skills 是否最新 → Runtime 是否配套)、Skills 更新與激活、Runtime 安裝與體檢。

檢查更新(環境總管) 是什麼?

此技能是剪輯環境的集中化管理工具,負責檢查 Skills 版本、Runtime 安裝與健康狀態。它提供「就緒檢查」作為其他業務技能(如剪口播、字幕、畫面、導出)的第 0 步,確保環境一致且可靠。支援 macOS 與 Windows,並提供桌面版與純 CLI 兩種安裝路徑。技能使用 Node.js 腳本(如 `check-plugin-update.cjs` 與 `ensure-runtime.cjs`)來執行檢查,並透過 Marketplace 驗證 Skills 更新。它嚴守邊界:不創建項目、不打開 Studio、不轉錄媒體。用戶可透過「檢查更新」、「安裝剪輯環境」等指令觸發完整就緒檢查與自檢(`doctor`),並在出現問題時提供結構化診斷與修復指引。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/Agentchengfeng/chengfeng-videocut-skills/tree/HEAD/plugins/chengfeng-videocut/skills/chengfeng-check-updates

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

檢查更新(環境總管) 是做什麼的?

環境的一切邏輯只寫在本 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-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 修復,報告後繼續第三步
  • 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 手搓了一個 「審片台」網頁,其審核決定與產品的帳本格式完全不相容,用戶白做一遍)。 正確動作只有一個:把結構化診斷給用戶,指引安裝或上報 Issue
  • runtime_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=false
  • activation_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 只認該入口

Individual skills in this repo

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

Agentchengfeng/chengfeng-videocut-skills

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

Agentchengfeng/chengfeng-videocut-skills

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

Agentchengfeng/chengfeng-videocut-skills

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

Agentchengfeng/chengfeng-videocut-skills

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

Agentchengfeng/chengfeng-videocut-skills

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

Agentchengfeng/chengfeng-videocut-skills

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.

Agentchengfeng/chengfeng-videocut-skills

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

相關技能