AI Agent 也能操作 Codex 同步：Codex Provider Sync v0.4 自动化协议 plan-apply 详解

AI Agent 也能操作 Codex 同步Codex Provider Sync v0.4 自动化协议 plan-apply 详解【免费下载链接】codex-provider-syncSynchronize Codex session provider metadata across rollout files and SQLite state.项目地址: https://gitcode.com/gh_mirrors/co/codex-provider-syncCodex Provider Sync 是一个用于在 rollout 会话文件与 SQLite 状态之间同步 Codex Provider 元数据的本地工具。从 v0.4 开始它新增了一个面向脚本、CI 和 AI Agent 的实验性自动化接口不再需要人工点击界面AI Agent 也能安全地执行同步、切换、恢复等操作。核心思想只有一句话——plan-apply先生成计划再明确执行任何写操作默认只是演练必须凭一份带摘要签名的计划才能真正落盘。为什么 AI Agent 需要同步接口手动点界面对 Agent 来说既慢又不可靠。v0.4 的自动化接口CodexProviderSync.Automation.exe为机器调用提供了三个关键能力机器可读输出每次运行只向标准输出写一份固定结构的协议 JSON诊断信息走标准错误方便 Agent 直接解析明确的退出码成功、参数错误、计划失效、忙碌、回滚失败、需要恢复等状态各自对应独立退出码无需猜结果与 GUI 同源桌面界面和自动化接口共用同一套校验、备份、恢复、锁和 WSL 安全规则行为一致。相关源码与协议定义AutomationProtocol.cs、automation-protocol-v0.4.schema.json支持的 7 个命令从只读到写入命令用途是否写入describe查看协议能力和安全要求否status只读检查当前 Provider、rollout 与 SQLite 状态否plan为写操作生成一份计划否只产出计划sync同步历史会话元数据需--applyswitch切换 Provider/model 后同步需--applyrestore恢复托管备份需--applyprune清理旧的托管备份需--apply所有写命令默认都是dry-run不带--apply时只返回影响预览一个字节都不会改。完整的命令行参数见 AutomationCommandLine.cs。plan-apply 两阶段流程AI Agent 的安全阀这是整个协议最核心的设计。分三步走第 1 步生成计划plan.\CodexProviderSync.Automation.exe plan --operation sync --codex-home C:\Users\you\.codex --provider openai返回的计划包含planId、stateFingerprint目标状态指纹、expiresAtUtc过期时间、executionToken一次性执行凭证和 64 位小写的digest计划内容 SHA-256 摘要。第 2 步Agent 审查计划Agent 检查计划中的目标列表、警告和意图是否与预期一致——这一步正是让 AI 先想清楚再动手的环节。第 3 步明确执行apply.\CodexProviderSync.Automation.exe sync --codex-home C:\Users\you\.codex --provider openai --apply --plan C:\Temp\plan.json --plan-digest digest执行必须同时提供--apply、计划文件和精确的--plan-digest三要素缺一不可。计划为什么不能作弊计划有三重约束Agent 无法绕过绑定状态指纹如果计划生成后目标状态变了比如有新会话写入执行直接被拒绝要求重新生成计划有过期时间计划只在expiresAtUtc之前有效防止拿旧计划无限期重试单次使用执行凭证通过持久化台账记录用过即失效杜绝重复执行。这套模型与桌面端的交互设计完全同构详见 ADR-0009写操作采用 Plan / Confirm / Apply。机器可读的结果Agent 如何判断成败每次运行的 JSON 响应都带有lifecycle生命周期字段如accepted、planning、readyToApply、applying、succeeded、failed、recoveryRequired和可区分的退出码退出码含义Agent 建议动作0成功继续后续步骤2参数或用法错误修正命令3计划无效/过期重新生成计划4忙碌有未完成操作稍后重试5已回滚的失败检查备份与错误信息6需要恢复走restore流程7已取消或超时重新规划10协议内部错误报告上游这种退出码 lifecycle timeline的组合让 Agent 能像读 API 文档一样理解每一次操作而不需要解析人类可读的日志。安全边界Agent 能做什么、不能做什么自动化接口在设计上刻意收窄了权限这些不变式来自 ADR-0001绝不触碰凭证任何自动化路径都不读取、不复制、不记录、不修改auth.json备份优先写入前自动创建托管备份失败时尝试回滚无法确认完整性时明确报需要恢复而不是假报成功拒绝危险路径绝对路径校验会拒绝符号链接与 reparse pointWindows 进程也不会通过 WSL UNC 路径直接修改 SQLite不承诺 1.0 稳定协议0.4处于实验阶段未来可能发生不兼容变更Agent 集成时建议先用describe探测能力。快速上手3 步跑通第一次 Agent 同步看能力.\CodexProviderSync.Automation.exe describe确认协议版本与支持命令查状态.\CodexProviderSync.Automation.exe status --codex-home C:\Users\you\.codex拿到当前 Provider 与文件数计划 执行按上文第 1、3 步生成计划并执行sync。更完整的示例含将计划写入临时文件、提取 digest 的 PowerShell 写法请参考官方快速开始文档AUTOMATION_QUICKSTART_ZH.md。若想了解 GUI 自动化与发布验证的完整设计可阅读 AUTOMATION_DESIGN_NOTES.mdv0.4 的发布背景见 v0.4.0 发布说明。小结Codex Provider Sync v0.4 的自动化协议把AI Agent 操作本地数据这件事做成了工程化的标准答案plan-apply 两阶段流程保证 Agent 先看影响再动手状态指纹 过期 单次使用保证计划不可滥用机器可读 JSON 区分退出码保证 Agent 能可靠判断结果。对于想让 AI 参与日常 Codex 会话维护的用户这套协议是目前最稳妥的入口。【免费下载链接】codex-provider-syncSynchronize Codex session provider metadata across rollout files and SQLite state.项目地址: https://gitcode.com/gh_mirrors/co/codex-provider-sync创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考