自动化接口快速开始

CodexProviderSync.Automation.exe 是供脚本、持续集成（CI）和 AI Agent 调用的实验性 Windows 接口。普通桌面用户不需要它，直接使用 CodexProviderSync.exe 即可。

自动化接口包包含：

• CodexProviderSync.Automation.exe
• automation-protocol-v0.4.schema.json
• 本说明文件

接口每次运行只向标准输出写入一份协议 0.4 JSON；诊断信息写入标准错误。所有路径都必须是绝对路径。

只读命令

# 查看协议能力和安全要求
.\CodexProviderSync.Automation.exe describe

# 查看当前 Provider、rollout 和 SQLite 状态
.\CodexProviderSync.Automation.exe status `
  --codex-home C:\Users\you\.codex

先生成计划

写命令默认不会修改数据。以下示例生成一份同步计划：

$planResponse = .\CodexProviderSync.Automation.exe plan `
  --operation sync `
  --codex-home C:\Users\you\.codex `
  --provider openai | ConvertFrom-Json

$planPath = 'C:\Temp\codex-provider-sync-plan.json'
$planJson = $planResponse.data | ConvertTo-Json -Depth 100 -Compress
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($planPath, $planJson, $utf8NoBom)
$planDigest = $planResponse.data.digest

请先检查返回的计划、警告和目标列表。计划会绑定当前输入与目标状态，具有有效期，并且只能使用一次。

明确执行计划

确认计划无误后，使用同一组操作参数，并同时提供 --apply、计划文件和计划摘要：

.\CodexProviderSync.Automation.exe sync `
  --codex-home C:\Users\you\.codex `
  --provider openai `
  --apply `
  --plan $planPath `
  --plan-digest $planDigest

如果目标状态在计划生成后发生变化，执行会被拒绝，需要重新生成计划。同步和切换仍遵循 Core 的备份、事务、回滚、锁和 WSL UNC 安全规则。

支持的命令

命令	用途
describe	查看协议能力和安全要求
status	只读检查当前状态
plan	为写操作生成计划
sync	同步历史会话元数据
switch	切换 Provider/model 后同步
restore	恢复托管备份
prune	清理旧的托管备份

完整参数和返回结构见 automation-protocol-v0.4.schema.json；架构、安全限制和兼容边界见 Automation Design Notes。协议 0.4 仍处于 1.0 之前的实验阶段，未来可能发生不兼容变更。