Communitygithub.com

2789927464king-jpg/video-skill-ku

剪輯環境的唯一管理者:就緒檢查(Skills 是否最新 → Runtime 是否配套)、Skills 更新激活、Runtime 安裝與體檢。用戶說檢查更新、安裝剪輯環境、裝播放器、檢查剪輯環境、剪輯環境就緒了嗎、設定轉錄憑證時使用;業務 Skill(剪口播/字幕/畫面/匯出)第 0 步也引用本 Skill 的就緒檢查。不適用於剪輯、字幕、畫面、匯出本身或專案資料移轉。

video-skill-ku 是什麼?

此 Skill 名為「檢查更新(環境總管)」,是剪輯環境的單一管理入口。其核心職責包括:執行就緒檢查(依序驗證 Skills 是否為最新、Runtime 是否配套)、觸發 Skills 更新與激活、安裝與體檢 Runtime。所有業務 Skill(如剪口播、字幕、畫面、匯出)的第 0 步都會引用此 Skill 的就緒檢查,確保環境一致後才開始工作。此 Skill 本身不建立專案、不開啟 Studio、也不進行任何媒體轉錄。支援 macOS 與 Windows 10/11,提供桌面版(推薦,透過 Chengfeng VideoCut App 隨包安裝 Bun、FFmpeg、FFprobe 及 Runtime)與純 CLI 安裝(需自行安裝 Node.js ≥ 20、Git、Google Chrome 等依賴)兩種路徑。更新機制遵循嚴格的安全模型:檢查階段僅在臨時 `CODEX_HOME` 中操作,不寫入用戶環境;用戶必須明確確認候選版本後才執行單向且可回滾的激活。任何環境異常都會回傳結構化診斷,禁止自行繞過限制繼續處理流程。

相容平台~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 中提問

開啟一個已預先載入此 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 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) 架构、工程自修复、智能配音字幕及录屏变焦。

相關技能