检查更新（环境总管）
环境的一切逻辑只写在本 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 手搓了一个
「审片台」网页，其审核决定与产品的账本格式完全不兼容，用户白做一遍）。
正确动作只有一个：把结构化诊断给用户，指引安装或上报 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 只认该入口