跳转至

安装、验证与事务恢复

适用范围

  • 产品目标:Codex Desktop;管理组件与桌面任务运行能力分别核验。
  • 基础安装无需本包 Python runtime;仅增强运行时需 Python 3.11 或更高版本。
  • 推荐形态:账户级 Plugin。
  • 可升级版本:7.17.2, 7.17.1, 7.17.0, 7.16.2, 7.16.1, 7.16.0, 7.15.3, 7.15.2, 7.15.1, 7.15.0, 7.14.6, 7.14.5, 7.14.4, 7.14.3, 7.14.2, 7.14.1, 7.14.0, 7.13.6, 7.13.5, 7.13.4, 7.13.3, 7.13.2, 7.13.1, 7.13.0, 7.12.0, 7.11.2, 7.11.1, 7.11.0, 7.10.0, 7.9.2, 7.9.1, 7.9.0, 7.8.1, 7.8.0, 7.7.1, 7.7.0, 7.6.2, 7.6.1, 7.6.0, 7.5.1, 7.5.0, 7.4.6, 7.4.5, 7.4.4, 7.4.3, 7.4.2, 7.4.1, 7.4.0, 7.3.0, 7.2.0, 7.1.0, 7.0.0, 6.6.1, 6.6.0, 6.5.0, 6.4.0, 6.3.0, 6.2.0, 6.1.0, 6.0.0, 5.1.0, 5.0.0, 4.2.0, 4.1.0, 4.0.0。
  • 受管对象:本包 Marketplace payload、manifest 条目、Plugin cache、Reviewer、全局规则和安装状态。

安装器不改写 config.toml,不删除未知 Skill、Agent、Hook、MCP、项目上下文、Event、Snapshot、Assessment、Proposal 或历史备份。

最短可用路径

安装后可直接使用;首次全扫可以跳过。未回答、拒绝或辅助状态不可写时,普通任务仍使用当前源码和 BASIC 能力,不会为了获得修改资格强制全扫。排障顺序:doctor 查看分功能结论,inventory 只读列出受管、缺失、漂移和未知资产,存在持久事务时再运行规范 recover。doctor --recover 只是同一恢复函数的兼容别名。

日常入口固定为 scripts/cp-assistant.ps1、scripts/cp-assistant.sh 和 scripts/cp-assistant.py。入口使用白名单转发,不改变全局 PATH;help 和 install-base 不依赖本包 Python。status、doctor、inventory、verify、resume 是查询/验证动作,install-base、install-enhancement、recover 是写操作。

python scripts\package_manager.py doctor
python scripts\package_manager.py inventory --scope user --mode plugin --json
python scripts\package_manager.py recover --scope user

等价的统一入口:

.\scripts\cp-assistant.ps1 status
.\scripts\cp-assistant.ps1 doctor --json
.\scripts\cp-assistant.ps1 inventory --scope user --mode plugin --json
.\scripts\cp-assistant.ps1 resume --repo-path E:\\work\\repo --profile C:\\safe-state\\project-profile.json --state C:\\safe-state\\project-state.json --checkpoint-dir C:\\safe-state\\task --json
.\scripts\cp-assistant.ps1 recover --scope user

resume 只读现有 Project Profile/State、明确的 Markdown 检查点和显式 Evidence。它不会扫描默认账户目录、创建绑定、修复账本、修改检查点或调用安装 recover。没有 Profile 时可以只提供明确的 --checkpoint-dir;未知 schema、完整性失败、任务/仓库冲突和越界路径返回结构化失败。仓库变化、Evidence 过期、读取预算耗尽或检查点缺失保留 UNKNOWN、PARTIAL 或 STALE,不投影为 PASS。resume --json 的 schema 为 resume-view/1,完整查询为退出码 0,部分/未知为 1,非法参数或完整性/身份失败为 2。

无 state 时,uninstall --dry-run 只给出零删除预览;真实卸载仍拒绝。非 Git 文件夹可使用基础说明和文件能力,不会被自动初始化为仓库。

基础安装使用 scripts\install-base.ps1(或 POSIX 的 scripts/install-base.sh)并只注册 Skill。它在任何写入前拒绝符号链接、Junction 或 Reparse Point 祖先;原生 Marketplace/Plugin 注册失败会撤销本次创建的受管路径。若宿主注册本身无法撤销,会保留 cp-assistant-base-state.json 的 RECOVERY_REQUIRED 状态,下一次同一基础安装入口会先尝试受管恢复,绝不覆盖未知 Marketplace。

路径规则

  • Skill:$HOME/.agents/skills
  • Reviewer:${CODEX_HOME:-$HOME/.codex}/agents
  • 全局规则:${CODEX_HOME:-$HOME/.codex}/AGENTS.md
  • Marketplace:$HOME/.agents/plugins/cp-assistant-marketplace
  • state:${CODEX_HOME:-$HOME/.codex}/cp-assistant-v6-state.json

Windows 原生进程若继承 /mnt/c/.../.codex,必须转换为盘符路径。路径目标及其祖先、受管树后代均不得含符号链接、Junction 或 Reparse Point。

标准升级

在解压后的 V7.14.6 语言包根目录依次执行:

python scripts\package_manager.py doctor
python scripts\package_manager.py install --scope user --mode plugin --dry-run
python scripts\package_manager.py install --scope user --mode plugin
python scripts\package_manager.py verify --scope user --mode plugin

dry-run 应明确显示:

  • 当前升级应读回已安装版本与 to_version=7.14.6;V7.9.2 及清单声明的更早升级路径必须被识别;
  • schema 3 保持不变,旧 schema 1/2 迁移到 3 后重新核验宿主;
  • 新升级备份路径;
  • Marketplace payload、manifest 和 Plugin cache 分离目标;
  • 未知条目保留;
  • 完整回滚动作;
  • 无路径越界或链接型路径风险。

Codex 0.160.0 的本地 Marketplace manifest 必须包含顶层 interface.displayName。升级器会在备份后移除旧 owner、生成受控的 interface.displayName,并保留其他未知外部字段;codex plugin list --json 恢复正常后才继续激活。

基础 Plugin payload 不注册 Hook。增强安装才在账户级 hooks.json 注册可选观察与受控写入 Hook;verify 会逐条核验本包拥有的 matcher、命令和事件参数,同时保留第三方 Hook。版本未知、门禁文件缺失或任一受管条目漂移时,受控操作验证失败关闭;基础任务仍可继续,不伪造 Operation v2 宿主支持。

完成条件:基础 Plugin 精确读回 installed=true、enabled=true、version=7.14.6,并且 10 个 Skill 与空 Plugin Hook 清单通过;若安装增强,还必须通过 schema 3 宿主状态、账户级受管 Hook、延迟封印 worker、keyring 和 payload digest 验证。文件复制完成不构成 Plugin 成功状态。

事务与能力探测

安装前 doctor 检查:

  • 桌面自带管理组件存在,命令摘要与插件登记结构符合当前 Desktop 契约;
  • plugin list --json 可执行;
  • Marketplace add/remove 与 Plugin add/remove 命令存在;
  • state schema 可识别;
  • 无活动事务或可恢复残留;
  • 载荷 manifest 与当前源树一致。

首次受管写入前建立互斥锁和 journal。journal 记录旧状态、备份、每个目标的 mutation intent、Plugin 注册阶段、cache 候选路径及新旧 digest。成功提交后活动 journal 被清理,归档记录保留。

崩溃恢复

先读取状态:

python scripts\package_manager.py status --scope user --mode plugin --json
python scripts\package_manager.py doctor

存在未提交事务时执行:

python scripts\package_manager.py doctor --recover

恢复流程按 journal 所有权处理:

  1. 恢复 Marketplace payload 与 manifest;
  2. 恢复原 Plugin cache 或清理本次候选 cache;
  3. 恢复原 Plugin 版本和启用状态;
  4. 恢复 state 与合并型全局规则;
  5. 再次读取 Plugin list 与 payload digest。

未知内容、归属漂移、损坏 journal、不完整备份或恢复后读回不一致时停止并保留日志。不得直接递归删除整个 .codex、.agents 或 plugins 目录。

手动回滚

优先使用安装器恢复,不直接复制整棵账户目录:

python scripts\package_manager.py recover --scope user
python scripts\package_manager.py verify --scope user --mode plugin

若正式安装已提交但需回到旧版本,可从保留的升级备份和旧正式包执行明确版本恢复。恢复完成后应确认原版本 installed/enabled、原 cache digest、原 state、主配置哈希和历史项目上下文数量。

卸载

python scripts\package_manager.py uninstall --scope user --mode plugin --dry-run
python scripts\package_manager.py uninstall --scope user --mode plugin

受管资源发生外部修改时默认拒绝覆盖式卸载。--force 只在归属和覆盖影响已经明确时使用。普通卸载不删除项目上下文、自观察数据或历史备份。

正式制品验证

validate-package.py 在完整 Git 源码仓库运行;语言安装包用于安装及制品验证,不包含双语源码快照。以下 verify 命令可核对对应发行制品。

python scripts\validate-package.py
python scripts\build-release.py verify --archive ..\Codex-Skills-V7.14.6-zh-CN.zip --locale zh-CN
python scripts\release-attestation.py verify --attestation ..\release-attestation-v7.14.6.json --artifact ..\Codex-Skills-V7.14.6-zh-CN.zip

validate-package.py 调用当前 validate-v74.py,检查执行前后的 Git index、受管与未跟踪文件内容、删除状态和链接类型;--output 只能写到仓库外。其 routing_host_observation 固定为 NOT_EVALUATED,不能替代真实宿主路由验收。

机器证明应绑定正式 ZIP SHA-256、确定性构建见证、Codex 版本、Plugin list、生命周期报告、已安装 PreToolUse 模型门禁报告、统一验证报告和安装后的 payload digest。任一证据缺失或哈希不一致时,正式发行结论失败关闭。宿主会话 JSONL 只作诊断旁证,不能替代模型门禁报告。

Windows Hook

可选增强在已核验宿主 profile 下登记八类 Hook 事件、九条账户注册项,由安装器绑定当前 Python 解释器;包内 cp_hook.cmd 是兼容启动入口。无需额外创建 python3.exe。SessionEnd timeout 为 3 秒;Hook 只构造有上限且不含正文的净化事件,并以命令参数无等待派发 detached worker,不扫描或写入事件链,也不做同步管道写入。Worker 在 Hook 预算外完成稳定身份校验、语义去重、持久化、DPAPI 解密、v2 签名入列和封印;未封印的 seal_required 链不会被 Evolution 消费。

升级前已打开的任务可能继续使用旧 Plugin 快照;升级后新建任务完成最终发现验证。不自动重启 Codex。

可选项目门禁与实际加载

增强注册包含八个入口,基础 Plugin 本身为空,项目门禁默认关闭。V7.14.6 中 UserPromptSubmit 是异步观察,Stop 是中性观察,Interrupt 完全由宿主控制;规范 apply_patch 仅在显式启用策略下由 PreToolUse/PostToolUse 推进 Operation v2,未配置或停用策略保持中性。

未配置或 disabled ───────────────→ 原生写入保持宿主既有行为
旧策略 enabled + 原生写工具 ───→ 拒绝 LEGACY_WRITE_ORIGIN_UNAVAILABLE
UserPromptSubmit / Stop / Interrupt → 不消费旧 GateTask 控制状态

配置 enabled=true、增强已加载和业务语义适用是不同结论。V7.14.6 只接受 Hook 建立的 Operation v2 起点、不同 B 的许可领取与匹配 PostTool 回执;旧 GateTask 回执不能授权原生写入。已打开会话可能仍使用旧 Plugin 快照,升级后应在新任务中读回实际行为。shell/MCP 等入口不能保证写前拦截。

当前官方 Hook 文档与管理组件探针分别提供接口证据;实际桌面 Hook 加载与调用仍需单独读回。旧稳定版记录仅用于历史恢复。旧门禁启用与停用入口见能力索引与流程入口,但本补丁不把旧任务生命周期恢复为写入授权。

内部路由管理入口:源码包使用 scripts/routing-v4.py,已安装插件使用独立复审 Skill 的 skills/multi-agent-independent-review/scripts/routing_v4.py。严格 V4 根预算需已安装增强运行时及真实桌面绑定;基础模式仅报告策略约束。