# Codex exec 教程：用 JSON Schema 输出 Zod 3 升级影响清单

## 身份和范围

本站原创 fixture 与人工参考；实际运行：人工参考结构校验及四行源码映射。目标代理模型、账号会话、付费 API、第三方 PR、推送和发布均未执行。公开包不含 .env；需要时仅在自己的临时练习目录从文本模板创建。

## 本地命令

```sh
python3 -m pip install -r requirements.txt
python3 verify.py
```

## 七步原生操作

### 1. 保留原始调用点与版本

src/schema.ts 中有 default、required_error、trim/min 和 custom 四类真实调用，package.json 固定 Zod 3.25.76。先保留源文件，不升级依赖；本题先做影响审计而不是直接迁移代码。

### 2. 为最终报告定义 JSON Schema

打开 impact.schema.json，固定 items 每项的 file、line、snippet、status、basis，status 只允许 review/unchanged/unknown，additionalProperties 为 false。Schema 限制输出形状，不验证技术判断是否正确。

### 3. 用只读 exec 分离最终 JSON 与事件

先运行 codex exec --help 确认本机支持 --output-schema、--json 和 -o，再按 run-codex.txt 执行。-o 保存最终结构化报告，标准输出的 --json 是 JSONL 事件日志，不能把两者当同一个 JSON 文件解析。 包内 local-codex-help.txt 是本机 CLI 的真实 help 输出，仅证明参数存在，没有发起模型任务。

### 4. 让每项判断引用源码和官方变化

提示中要求逐行读取源文件，对照官方 Zod 4 migration guide。default 的短路行为、required_error 的统一 error 参数要分别说明；custom 的业务策略缺证据时必须写 unknown，不能臆造兼容结论。

### 5. 运行结构与行号映射检查

安装 requirements.txt 后运行 python3 verify.py；检查器验证人工参考符合 schema、四项 snippet 与真实源码行号一致，并故意把 line 改成字符串验证会失败。本站没有运行 Codex exec 模型。

### 6. 检查 unknown 和未变化判断

人工回读每一项官方依据，确认 unchanged 仅表示本题未断言影响，不代表整个 API 永远不变。至少保留 custom 的 unknown，避免结构化输出给人“机器已证明安全升级”的错觉。

### 7. 冻结报告后再另开实施任务

保存实际 actual-impact.json、事件 JSONL、输入 SHA 和审校结论。批准升级是下一步；本题不更新真正依赖，不把人工参考报告冒充模型输出。

## 验收产物

符合给定 schema 的 migration-impact.json；每项包含文件、原代码、官方变化依据、风险、建议与 unknown 项；保存独立 JSONL 运行事件日志

## 门槛

- 本地已核实 codex-cli 0.162.0-alpha.17.2 支持 exec --output-schema、--json、-o；教程需记录实际版本。
- 订阅额度与 API key 计费分开；本任务可保持 read-only，禁止自动安装或升级依赖。
- 结构正确不等于内容正确；需复核每项源码与官方依据。

## 官方来源

- https://learn.chatgpt.com/docs/non-interactive-mode
- https://zod.dev/v4/changelog

静态配图冻结于本次输入。修改输入需重新运行并自行重渲染；不把旧截图当新结果。