codex-app-server/docs/upstream-166-alignment.md

# 上游对齐：openai/codex 稳定版 0.166.0（核查日 2026-11-05）

结论先说：**已用 0.166.0 官方二进制重导 schema 并验证通过；本批只改
宿主侧 pin、文档、schema 与映射测试，不动任何生产二进制。**

生产二进制更换（/usr/local/bin/codex、172、170、Docker 镜像内
二进制）是部署动作，需要用户另外点头 + 窗口，不在本批；本批的
验证边界是本地 scratch 验证（见下文“验证”），不是生产换装实证。

## 基线与上游位置

- 本项目此前锚定：`codex-cli 0.164.0-alpha.9`（2026-10-25 实测，
  `protocol/` 的 schema 就是从它用
  `codex app-server generate-json-schema` 导出的；见
  `docs/upstream-164-alignment.md`）。
- 上游稳定版：`0.165.0`（2026-10-27）、`0.166.0`（2026-10-29，
  当前最新稳定版）。本批一次跨两个稳定版锚定到 0.166.0，不
  在 0.165.0 停留（0.165.0 的内容已全含在 0.166.0 里）。
- 上游 alpha 线（不作为目标）：0.167.0-alpha.5 与 0.168.0-alpha.1
  （均 2026-11-03），无 0.167/0.168 稳定版。按 164 文档立过的
  原则只记录、不跟进；alpha 跟踪办法见批总结，不进本文档。
- 上游来源：https://github.com/openai/codex/releases（npm 官方包
  `@openai/codex@0.166.0` + 平台包 `@openai/codex@0.166.0-linux-x64`，
  npm integrity sha512 已验）。

## 稳定版 0.166.0 改动 → 本项目状态

| 上游改动 | 对宿主层的影响 | 结论 |
|---|---|---|
| app-server 线程启动/关闭竞态修复、已完成 runtime 及时释放（#57787、#57788） | 宿主 host.py 是长循环、一个 app-server 进程托管多 thread，直接受益 | 升级收益，无需改代码；重测 thread 生命周期一项（已做，见验证） |
| resume/fork 时保留已确认的 approval 与权限设置（#57227） | 宿主 resume/fork 流程不再被重置坑绊 | 升级收益，无需改代码 |
| 独立 executor 随规范 CLI 与 app-server 发布包一起发（#57837） | 实查：不是新文件，是二进制内 `exec-server` 子命令；三件套文件形态不变，宿主只驱动 `app-server` | 不影响安装形态，无需改代码 |
| GPT-6.1 Terra 进入 bundled、Vertex AI、Bedrock 三个目录（#57293）；Vertex AI provider（0.165.0 #56265） | 宿主模型走中转路由，引擎版本不卡 Terra 可用性；内置列表回退路径 0.165+ 才含 Terra | 不相关，无需改代码 |
| `codex queue --resume`（0.165.0 #57232） | 宿主任务队列自建（host.py 循环 + worker_sweep admin CLI），不依赖上游 queue | 不相关，功能等价但实现无关 |
| `codex doctor --network-only`（#57606） | 运维诊断工具，不是宿主运行路径 | 观察项，不接 |
| 键盘 transcript 选择、Markdown 渲染一致化、安全拦截说明 | 都是 TUI 交互面，app-server 协议与宿主层不依赖它们 | 不相关，无需改代码 |
| memory v2 对新 profile 默认开启 + 外部记忆导入（0.165.0） | 宿主 auto_memory 为自建租户记忆，未对齐上游 memory v2 格式/导入 | 不对齐，见对齐表 A10；本批不动 |
| 实验性 attached thread forks（0.165.0 #56351） | 只在 `--experimental` schema 里出现（`ThreadForkParams.attachToSource`），默认 schema 无；且 attached fork 在普通 thread/list 里不可见，与宿主“fork 即新建 worktree 的可见线程”模型冲突 | 不接，评估见批总结；本批不写代码 |
| 构建基线 Node.js 24.22.1、Rust 1.95.0 | 与本机 Node 24.22.1 一致；宿主是 Python，不编译 Rust | 不相关 |

## schema 重导结果（0.166.0 二进制实导，非树对比）

导出方式：`codex app-server generate-json-schema --out <dir>`，
原样取其中两 bundle 替换 `protocol/`（v1 + v2，与旧形态一致，
不引入 per-type 散文件）。

| 对比项 | alpha.9 时代 bundle | 0.166.0 重导 bundle | 结论 |
|---|---|---|---|
| v1 bundle 定义数 | 83 | 83 | 仅 ClientRequest 变（新增 feedback/save 一个方法） |
| v2 bundle 定义数 | 665 | 677 | +12 定义、0 删除、16 个定义有改动 |
| v2 新增定义 | — | AccountSession、AccountSessionWorkspace（Kind）、ApplicationStorageRequirements、FeedbackSaveParams/Response、ModelProviderError、OtelExporter、OtelHttpProtocol、OtelRequirements、OtelTlsConfig、OtelToolResultLogConfig | 均为新能力/新遥测，无 host 用项 |
| v2 改动定义 | — | Account、AdditionalContextEntry、ApplicationRequirements、ClientRequest、CodexErrorInfo、ConfigRequirements、HookMetadata、HookRunSummary、HooksListParams、NetworkRequirements、ProcessExitedNotification、ReviewDelivery、ReviewStartParams、ReviewStartResponse、ThreadItem、ThreadUsage | 除 ReviewDelivery 外全是新增可选字段或描述改动（见下） |
| 方法集 | ClientRequest 105 | ClientRequest 106（+feedback/save） | 0 删除；ServerRequest 10→10、通知 85→85 全不变 |
| host 方法 params 引用 | — | 21 个 host 方法的 params 引用全部未变 | 零漂移 |

唯一语义变化：`ReviewDelivery` 枚举从 `["inline", "detached"]`
变为 `["inline"]`（detached 已移除），`ReviewStartParams.delivery`
与 `ReviewStartResponse.reviewThreadId` 的描述同步改写。宿主早已
不发 detached（`host.py start_review` 注释“不发 detached（已废弃）”、
`cloud/review.py` 同款说明），故无影响；其余改动如
`ThreadItem` 新增 `completedAtMs`/`startedAtMs`（可空）、
`ThreadUsage` 新增 `nativeUsageUsdMicros`（可空）、
`CodexErrorInfo` 新增 `modelNotFound`/`policyCapacityUnavailable`
均为向后兼容加法。

方法数勘误：2026-11-05 对齐表写“17 个方法/通知”并不准确。
实查 host.py 触及 21 个方法字符串：18 个发出请求（含
initialize 握手）+ 3 个入站通知；对齐表列出的 18 项漏了
initialize、app/list、mcpServerStatus/list 三个。
`tests/test_host_protocol_mapping.py` 以实查 21 项为准钉死。

## 三件套核对（0.166.0 linux-x64 平台包实查）

- `bin/codex`（319,346,888 字节，`codex-cli 0.166.0`）、
  `bin/codex-code-mode-host`（77,997,328 字节）、
  `codex-resources/bwrap`（529,776 字节）三件齐全，成套。
- 包内另有 voice bundle（`codex-voice-host` 及 gstreamer 库，
  语音为刻意不做项，不理会）与 `codex-path/rg`，均不影响三件套。
- 0.166.0 发布包不改变安装形态：宿主的 `bin/codex` 优先、
  `CODEX_BIN` 环境变量、`PATH` 回退三档逻辑（`host.py
  default_codex_bin`、`start.sh`）无需改动。

## 验证（本地 scratch 验证，无模型调用）

- 沙箱 smoke：scratch 三件套布局下 `codex sandbox echo`
  成功返回，exit 0（bwrap 配对工作）。
- app-server smoke：仓库自带 `client.py --list-threads` 对
  scratch 0.166.0 二进制跑通：initialize 成功（codexHome 为
  scratch 目录、platform=linux）、thread/list 返回空数据，exit 0。
- 技能发现复核：0.166.0 下 `<codex-home>/skills/`（我方播种
  位置）与 `$HOME/.agents/skills/`（文档 USER 位置）放的测试
  技能均被 `skills/list` 发现（scope=user、enabled=true），
  故播种机制无需改动；系统技能（skill-creator 等 5 个）照常出现。
- 方法映射重测：`tests/test_host_protocol_mapping.py`（21 项
  钉死）+ 完整三套件（数见批总结）。

## 本批实际改动（只改宿主侧，不动官方二进制）

1. `protocol/`：两 bundle 替换为 0.166.0 二进制原样导出
   （749,825 + 646,070 字节）。
2. `README.md`：实测版本 pin 从 `0.164.0-alpha.9` 改为
   `0.166.0`（验证通过后才改，见批总结；不是提前改 pin 充数）。
3. `start.sh`：三件套注释版本号同步为 0.166.0（仅注释）。
4. `config.example.toml`：补 `[[skills.config]]` 禁用语义的
   注释示例（仅注释，不改任何生效配置）。
5. `tests/test_host_protocol_mapping.py`：新增，21 项钉死。
6. 本文件：作为 0.166.0 的对齐记录，后续每次上游稳定版发布时
   按同一张表复核。

## 明确不做的事（诚实边界）

- **不换任何生产/服务器二进制。** `/usr/local/bin/codex`、
  172、170、Docker 镜像内二进制一律不动；本批二进制只活在
  scratch 目录，批后清理。
- **不追 alpha。** 0.167/0.168 alpha 只记录、不采用。
- **不改播种机制。** 0.166.0 下 `<codex-home>/skills/` 仍被
  发现，无需改 `skill_seed.py`。
- **不接 attached forks。** 实验性、仅 `--experimental`
  schema、与宿主可观测模型冲突；重估触发条件见批总结。
- **不改阈值、不改 #238 auto_apply、不改 #247 语义、不改
  v1.1 契约、不改 SKILL.md 第五项。**
- **不合并、不部署、不推送。** 本批留在隔离 worktree 的
  `codex-opensource-align2` 分支上；live 仍是 aba06d9，不碰。

## 下一步（需要用户定）

1. 是否把生产二进制从 alpha.9 换到 0.166.0（主机部署动作，
   需窗口 + 重跑 resume / goal / 成本实弹）？那一步与控制面
   部署是两件分开的决策，不可悄悄混进一次部署。
2. gapfill2 线是否合并（B1）仍待用户；本批不替用户定。