对外协议是投影

你在给编辑器写插件。调试器里已经能看到内核往外抛事件：turn_started、exec_command_begin，字段是 snake_case。第一包数据过来，对不上。方法名是 turn/started，中间是斜杠。字段是 threadId、startedAt。

命令开始时你等的 exec_command_begin 没出现，来的是 item/started，里面塞着一个 type: "commandExecution" 的 item。审批更怪：服务端反向发来一条 request，你得回 response，否则这一轮卡在那儿。

如果编辑器按 81 种 EventMsg 写 switch，每加一种内部事件都是一次客户端升级。deprecated 别名也会从仓内兼容问题变成对外合同。

调度函数 apply_bespoke_event_handling 吃一条内核 Event，按四条规则收成对外消息。

出处：codex-rs/app-server/src/bespoke_event_handling.rs 第 159 至 188 行；codex-rs/app-server/src/bespoke_event_handling.rs 第 880 至 918 行；codex-rs/app-server/src/bespoke_event_handling.rs 第 996 至 1036 行

item_event_to_server_notification 只覆盖一对一、无状态的投影。函数名像总入口，调用点才知道它是助手。ExecCommandBegin 在助手里还能变成 item/started，在调度里却走进 deprecated 空分支。现场命令卡片来自后面的 ItemStarted。以调度为准。

出处：codex-rs/app-server-protocol/src/protocol/event_mapping.rs 第 25 至 37 行；codex-rs/app-server-protocol/src/protocol/item_builders.rs 第 1 至 11 行

内核按发生了什么命名，对外按用户看见什么命名。内部还可以继续发 deprecated 事件给 rollout，调度写一句注释丢掉即可。换语言重写，这张表还在：左边内部 type，右边写清留下、改名、丢掉还是拆开。

未知行必须失败。空默认等于通配臂，新事件能通过编译，IDE 的 stdout 上什么都没有。

出处：codex-rs/app-server/src/bespoke_event_handling.rs 第 1238 至 1245 行

同事把 turn/start 的响应当成一轮已经开始。响应立刻回来，里面是一份空 items 的 turn。模型还没开口。真正开跑是后面那条 turn/started 通知。

出处：codex-rs/app-server/README.md 第 81 至 81 行

审批做成普通 notification，客户端可以不理。turn 会停在等待上，直到超时或中断。

线上能解出来的对象只有四种：带 id 的 request、不带 id 的 notification、成功 response、错误 response。看起来像 JSON-RPC，结构体里没有 jsonrpc 字段。常量 JSONRPC_VERSION 还在，线上不带这个键。

出处：codex-rs/app-server-protocol/src/rpc.rs 第 1 至 11 行；codex-rs/app-server-protocol/src/rpc.rs 第 34 至 72 行

对外消息是四套，而且不对称。

1. ClientRequest：客户端问，等人回包。initialize、turn/start 是稳定面主干。

2. ServerNotification：服务端推，不等回包。turn/started、item/started 在这里。

3. ServerRequest：服务端问人。第一条稳定方法是 item/commandExecution/requestApproval。

4. ClientNotification：展开之后只有 Initialized。

出处：codex-rs/app-server-protocol/src/protocol/common.rs 第 1663 至 1670 行；codex-rs/app-server-protocol/src/protocol/common.rs 第 1954 至 1956 行

请求要回执，通知是广播，反向请求把人拉进环。这三件事混成一种，编辑器要么空转等开跑，要么漏画审批按钮。id 对得上，过载时还能把 request 失败回给调用方，避免审批悬挂。

实验方法有 57 个方法级标记。如果靠第二端口，稳定客户和冒险客户要连两个地方。TUI 如果因为同进程就改收 EventMsg，现场通知和远端 IDE 会各写一份 item。

实验面靠 initialize 时一个布尔 experimentalApi，缺省 false。再 initialize 会收到 Already initialized。没开开关就打 server/diagnostics，错误码 -32600，句子是固定的 server/diagnostics requires experimentalApi capability。Python SDK 把这个默认改成 True，官方脚本已经站在实验合同上。

出处：codex-rs/app-server/src/message_processor.rs 第 891 至 895 行；sdk/python/src/openai_codex/client.py 第 209 至 209 行

TUI 不直连 core。内嵌只换载体：socket 和 stdio 换成内存通道，MessageProcessor 还在。请求仍是 ClientRequest，响应仍走同一套 envelope。进程内是 transport-local，不是 protocol-free。

出处：codex-rs/app-server/src/in_process.rs 第 1 至 24 行

TypeScript SDK 不走这条路。它拼的是 exec --experimental-json，事件 type 是点号，字段是 snake_case，完整枚举只有 8 个变体。没有 initialize，没有审批 request。能力差在协议面，不差在语言。

出处：sdk/typescript/src/exec.ts 第 89 至 90 行；codex-rs/exec/src/exec_events.rs 第 8 至 37 行

远程和本机的差别应落在网络，不落在语义。实验面用 capability，比文档里写一句实验更硬。一个布尔把稳定面和实验面切开，schema 生成出两份，默认那份不含实验字段。