Communitygithub.com

Environment Manager (Check for Updates)

The sole manager of the video editing environment: readiness check (skills up-to-date → runtime compatible), skill update activation, runtime installation and health check. Used when users say "check for updates," "install editing environment," "install player," "check editing environment," "is the editing environment ready?", "configure transcription credentials." Also referenced as step 0 by business skills (cut/podcast/captions/scenes/export). Not used for editing, captions, scenes, export itself, or project data migration.

What is Environment Manager (Check for Updates)?

This skill acts as the single, authoritative controller for the entire video editing environment within a Codex-powered AI agent. Its primary purpose is to ensure the agent's skills are the latest version and that the required runtime dependencies (like Bun, FFmpeg, and the agent's runtime) are correctly installed and healthy before any editing task begins. It is designed to be referenced as the mandatory first step (step 0) by any business skill that needs to perform editing operations, consolidating all environment management logic into one place. The skill performs a three-step readiness check: it verifies its own plugin cache identity, checks for updates via a Marketplace script, and then runs a runtime health check. If an update is available, it presents the details to the user for confirmation before activating it in a way that requires a new session. If the runtime is missing or unhealthy, it provides a structured diagnostic report and stops the process, preventing the agent from proceeding with alternative workflows that could produce incompatible or untrustworthy results. It supports macOS and Windows, with separate installation paths for a desktop app (recommended) or pure CLI. The skill strictly avoids any user-invoked `codex` commands, project creation, media access, or any other form of actual editing work.

Works with~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

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Check for Updates (Environment Manager)

All environment logic is written only in this Skill: skills version, runtime installation and health check. Business Skills at step 0 reference the "Readiness Check" below with a single line, and do not carry any environment logic themselves—if the environment strategy changes, only this file needs to be modified. This Skill does not create projects, open Studio, or transcribe any media.

Readiness Check (Business Skill's Step 0 runs from here)

Process in three steps, output one of three states: Ready / Needs New Session / Stop.

1. Locate Current Plugin Cache (read-only)

Locate from the actual source file path of this Skill provided by the host: go up two levels from this file's directory to get <Plugin Root>. Use a file reading tool to confirm that <Plugin Root>/.codex-plugin/plugin.json and <Plugin Root>/scripts/check-plugin-update.cjs both exist. If the path is unavailable, the directory structure does not match, or the files do not exist, stop the update comparison with installed_identity_missing; do not call the user's CODEX_HOME to run codex plugin list to guess, and do not search the entire disk.

All subsequent commands use this literal path for <Plugin Root> (wrap the entire path in quotes if it contains spaces). Command blocks must not use shell variables or command substitution—bash and PowerShell assignment syntaxes are incompatible. The check script reads the installed manifest, provenance, Marketplace exact revision, and bundle digest directly from its own cache; the check phase does not depend on the user's Marketplace CLI output.

2. Are Skills Up-to-Date?

node "<Plugin Root>/scripts/check-plugin-update.cjs" --marketplace chengfeng-videocut --json

(Marketplace name defaults to chengfeng-videocut; use the user's custom name if they have configured one.)

  • current → proceed to step 3
  • update_available_confirmation_required → display installed, candidate, and four candidate attributes: version, 40-hex snapshotRevision (B), 40-hex contentRevision (A), publisherChecksum (SHA-256), stop and wait for user confirmation; after confirmation, proceed to the "Activation" section below. Activation success = Needs New Session: skill text is loaded at session start, mid-session updates do not take effect for the current session, ask the user to start a new session to continue the task
    • If legacyInstalledIdentity=true is also present, this is a one-time compatibility migration from historical 0.10.5 to the new proof format; still use the same confirmation gate, do not require the user to modify the Marketplace ref in advance
  • marketplace_not_found / marketplace_source_untrusted / marketplace_ref_unsafe → current user Marketplace is missing, source is untrusted, or not an exact 40-hex pin; do not call the user's Codex CLI to fix, report and continue to step 3
  • installed_identity_missing / installed_identity_untrusted → current cache identity cannot be safely read or proven, do not guess version, do not activate; report and continue to step 3
  • installed_context_mismatch → the real cache path, Marketplace name, or explicit CODEX_HOME of the current Skill is inconsistent; do not search other caches, do not activate
  • isolated_stage_failed / isolated_stage_schema_invalid / isolated_cleanup_failed → temporary candidate staging, CLI schema, or temporary directory cleanup failed; user HOME has zero writes, report and continue to step 3
  • update_metadata_untrusted → the proof of version + B + A + SHA-256 is invalid, do not activate; report and continue to step 3
  • candidate_older_than_installed → downgrading is prohibited, report and continue to step 3
  • Network unreachable or other check errors → explain briefly to the user, continue to step 3 with the current runtime check— a failed update check does not block work

Normal checks are only allowed to discover candidates using the official stable ref in a temporary CODEX_HOME; for the user's CODEX_HOME, do not call any codex commands and do not write configurations, Marketplace, or cache. All version directories in the current cache must be strict semver; lower versions may remain but only the single highest semver priority is considered active. If multiple directories with the same priority exist at the highest position, return installed_identity_untrusted, do not select by directory name lexicographic order.

3. Is the Runtime Compatible?

node "<Plugin Root>/scripts/ensure-runtime.cjs" --install-if-missing --json
  • ready → Ready, business skill continues
    • runtime.kind=desktop-managed indicates the desktop app has installed the bundled Runtime, Bun, FFmpeg, and FFprobe into the product's unified managed directory; Skills reuse them directly without installing additional dependencies or starting new services
    • runtime.kind=managed/path/source are still compatible CLI installation sources; subsequent business contracts are the same
  • missing: the script prompts only once "Installing from GitHub Release", auto-resumes after SHA-256 verification completes
  • runtime_unhealthy, installation failure, or post-install doctor failure → Stop, report structured diagnostics. Stop means stop: do not proceed with any alternative interface like custom review pages, players, timelines, or any other substitute workflows. Output produced when the product is unusable is untrustworthy (real case: when Runtime was missing, an Agent handcrafted a "review panel" webpage whose review decisions were completely incompatible with the product's ledger format, causing the user to redo everything). The correct action is only one: provide structured diagnostics to the user, guide them to install or report an Issue
  • runtime_capability_missing → Stop: Runtime is healthy but below the contract requirements. Report both version numbers and the difference, guide the user to upgrade after confirmation (upgrade replaces ~/.chengfeng-videocut/app, project data remains untouched); do not modify the existing installation until user confirms, prohibit falling back to old editing chains
  • During the readiness check, do not start services, open Studio, or create projects

Machine Prerequisites

Supports macOS and Windows 10/11, with two installation paths:

Desktop App (Recommended)
  Install and launch Chengfeng VideoCut at least once
  -> App bundles Bun, FFmpeg, FFprobe, and Runtime
  -> Does not require the user to add these tools to the system PATH
  -> Skills reuse the same service via the stable entry at ~/.chengfeng-videocut/bin

Pure CLI Installation
  macOS     brew install bun ffmpeg
  Windows   winget install Oven-sh.Bun Gyan.FFmpeg
            Open a new terminal/session after installation for PATH to take effect

Both paths still require Node.js ≥ 20 to run Plugin scripts; exporting subtitles/animations still requires Google Chrome. Pure CLI users install manually, Windows users can use winget install OpenJS.NodeJS.LTS Google.Chrome. Must explicitly stop if items are missing, do not silently skip.

Git is also required for Skills update identity self-proof; Windows can use winget install Git.Git. If Git is not executable or cannot read the official snapshot's origin/HEAD/commit relationships, the update check fails closed, but still continues to the Runtime check according to the rules above.

Cloud transcription additionally requires Volcengine credentials: node "<Plugin Root>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>.

See the detailed agreement in Runtime and Product Contract.

Skills Update: Inspect and Activate

Read-only inspection of the current Plugin cache: no network access, no codex calls, no writes to user CODEX_HOME:

node "<Plugin Root>/scripts/check-plugin-update.cjs" --marketplace "<Marketplace Name>" --inspect --json

Success returns inspected_no_refresh, containing only the current pinned Marketplace and cache identity, without generating remote candidates.

Network-isolated check (when user explicitly says "check for updates," or step 2 of the readiness check):

node "<Plugin Root>/scripts/check-plugin-update.cjs" --marketplace "<Marketplace Name>" --json
  • current: reports the installed identity and the latest published identity found in the temporary environment.
  • update_available_confirmation_required: displays installed and candidate four attributes: version, snapshotRevision (B), contentRevision (A), publisherChecksum; stops and waits for user confirmation.
  • legacyInstalledIdentity=true: the current cache is a compatible historical 0.10.5 cache. It can enter the normal confirmation flow above; the old identity is bound together by Marketplace exact revision, cache directory version, manifest version, and inventory digest. Do not ask the user to change the ref first, and do not create a separate "migration succeeded" status.
  • marketplace_not_found / marketplace_source_untrusted / marketplace_ref_unsafe: current user Marketplace is missing, untrusted, or not pinned to its own exact 40-hex revision; do not auto-change the ref.
  • installed_identity_missing / installed_identity_untrusted: current cache is unrecognizable or untrustable, do not guess the installed version.
  • installed_context_mismatch: the script execution location is not the single highest active cache of the current Marketplace, or the explicit CODEX_HOME is inconsistent with the HOME to which the cache belongs; do not cross-directory guess.
  • isolated_stage_failed / isolated_stage_schema_invalid / isolated_cleanup_failed: only states that temporary staging, CLI JSON schema, or cleanup failed; do not imply the user's installation has been refreshed.
  • update_metadata_untrusted: the temporary snapshot lacks proof of B, A, SHA-256/manifest recomputation, or the identities of manifest, Marketplace revision, and provenance contradict each other.
  • candidate_older_than_installed: downgrading from a newer local version is prohibited.
  • Any snapshot/parse/version errors: keep structured JSON; user HOME userMutationPerformed=false.

The script only executes the official Marketplace CLI in a newly created temporary CODEX_HOME: first use marketplace add Agentchengfeng/chengfeng-videocut-skills --ref stable to establish the discovery source, then use marketplace upgrade to materialize the snapshot in the same temporary HOME, and finally plugin list to obtain the candidate. The 40-hex B resolved from stable, the 40-hex A from the provenance, manifest version, and recomputable SHA-256 together constitute the candidate. Git must also prove that the temporary Marketplace origin is the official repository, HEAD=B, A is an ancestor of B, the Plugin working tree is clean, and the A→B Plugin subtree only changes provenance. The temporary directory is deleted after use. The user's HOME Marketplace must remain at the previously confirmed exact B; during the check phase, not even a read-only codex command is called on it.

On Windows, when resolving codex / git, first search for executable extensions according to PATHEXT, then try files without extensions; .cmd / .bat are wrapped via ComSpec. Therefore, a Unix codex shim in the same directory as pnpm will not shadow codex.cmd.

Activate Only After User Explicitly Confirms

Confirmation must occur only after the user has seen the exact candidate version, B, A, and checksum:

node "<Plugin Root>/scripts/check-plugin-update.cjs" --marketplace "<Marketplace Name>" --activate --confirmed --expected-version "<Displayed Version>" --expected-snapshot-revision "<Displayed B>" --expected-content-revision "<Displayed A>" --expected-sha256 "<Displayed Package SHA256>" --json

The script must recreate a temporary CODEX_HOME, stage the candidate from stable again, and compare all four attributes against all --expected-* arguments. If the candidate drifts between staging rounds or the parameters do not match, return confirmation_mismatch, user HOME has zero writes. After passing, record the exact pre-update snapshot revision and cache identity, then use only official commands on the user's HOME:

plugin marketplace remove <Marketplace Name>
plugin marketplace add Agentchengfeng/chengfeng-videocut-skills --ref <B>
plugin marketplace upgrade <Marketplace Name>

<B> must be the 40-hex snapshotRevision just re-staged and confirmed with the user; stable, other branches, tags, short SHAs, or any different ref all return marketplace_ref_unsafe. After upgrade, the script directly re-reads and verifies version + B + A + SHA-256 from the cache; only if all match exactly does it return activated. After successful activation, inform the user to restart Codex or start a new session. If --confirmed is missing, return confirmation_required; if any expected field is missing, different, or drifts after re-staging, return confirmation_mismatch; both keep user HOME zero writes.

Before entering the first write command, the script re-reads the user's Marketplace and active cache with CAS. If they differ from the old identity saved before staging, return activation_state_changed, activation does not start and user HOME has zero writes. If any step of the write transaction fails, the script first checks the post-state of Marketplace and cache:

  • activation_failed_no_change: on failure, still exactly equals old identity; no rollback needed, userMutationPerformed=false
  • activation_failed_rolled_back: candidate activation failed, but the old exact revision and old cache are fully restored
  • activation_cache_locked_rolled_back: failure identified as cache/file handle lock, and old state is fully restored
  • activation_failed_rollback_incomplete: rollback failed, or unable to prove both Marketplace and cache have returned to the old identity; report the actual post-state and stop

Only when the post-state has changed, use the saved old exact revision to perform official remove → add --ref <old B> → upgrade rollback, and again directly re-read the cache. The above failure states cannot say "updated." Do not manually copy or delete cache to fake success; do not touch Runtime, projects, media, EDL, or Studio state.

User Says "Install Editing Environment / Install Player / Check Environment"

Run the full readiness check directly; after getting "Ready," run the full self-check and report as-is:

node "<Plugin Root>/scripts/videocut-cli.cjs" doctor --json

Report: Runtime version and location, each doctor check result, how to fix missing items (machine dependencies guide for installation; transcription credentials guide for node "<Plugin Root>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>). If runtime.kind=desktop-managed, explicitly state that Bun/FFmpeg/FFprobe come from the desktop package and do not require modifying the system PATH. After everything is set up, tell the user: just say "cut a podcast" to start.

Boundaries

  • Plugin version and Runtime version are independent; minimum Runtime compatibility and Release targets are controlled by the runtime-requirements.json contract, no version numbers are hardcoded in this document
  • stable is only used for temporary discovery; do not write it as a persistent ref for user installation, and do not refer to temporary staging, legacy cache, or local directories as activated versions
  • During the update check phase, zero Codex calls and zero writes to user HOME; activation with rollback can only begin after the user sees and confirms version + B + A + SHA-256
  • Do not publish, modify project data, or media; official Codex activation after user confirmation and Runtime installation are the only write exceptions
  • Do not search for Electron .app, NSIS installation directories, or pass Electron resource paths to business Skills; the desktop app is responsible for writing the stable Product entry point, Skills only recognize that entry point

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) 架构、工程自修复、智能配音字幕及录屏变焦。

Related Skills