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-sync
Codex 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 | 同步历史会话元数据 | 需--apply |
switch | 切换 Provider/model 后同步 | 需--apply |
restore | 恢复托管备份 | 需--apply |
prune | 清理旧的托管备份 | 需--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 point，Windows 进程也不会通过 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.md；v0.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），仅供参考
