09 — App-Server、JSON-RPC v2 与背压 ​

角色 ​

codex app-server 为 VS Code 扩展等富客户端 提供 JSON-RPC 接口（见 codex-rs/app-server/README.md）。与 MCP 的「工具协议」不同，这里是 一等会话/线程 API。

传输与初始化 ​

• 默认 stdio JSONL；实验性 WebSocket（文档明确 unsupported for production）。
• 连接后必须先 initialize 再 initialized，否则拒绝请求；可重复 initialize 报错 Already initialized。
• initialize.params.capabilities.optOutNotificationMethods：精确方法名 级别的通知过滤，减少弱客户端负担。

背压与过载 ​

README 说明：传输 ingress、请求处理、出站写之间使用 有界队列；饱和时返回 JSON-RPC -32001 Server overloaded; retry later.，客户端应 指数退避 + 抖动。

设计原因：agent 事件流可能突发；无界队列会 OOM 或拖垮 IDE；显式错误码比挂死更可运维。

安全：WebSocket 在非 loopback ​

文档警告：非 127.0.0.1 监听时默认可能 无鉴权；需 --ws-auth capability-token 或 signed-bearer-token 等。

要点：本地 IPC（stdio）与网络监听 威胁模型完全不同，不能复用同一默认安全策略。

v2 方法全景（节选） ​

codex-rs/docs/codex_mcp_interface.md 与 app-server README 列出：

• thread/start|resume|fork|read|list
• turn/start|steer|interrupt
• config/read|value/write|batchWrite
• model/list（分页 cursor / limit）
• 通知：thread/started、turn/completed、codex/event/* 等

事件 payload 与 core/src/protocol.rs 的 Event / EventMsg 对齐，保证 CLI / IDE / MCP 消费者语义一致。

类型与 Schema 生成 ​

codex app-server generate-ts / generate-json-schema：生成物与当前二进制版本绑定，避免「文档与实现漂移」。前端可类比 orval / openapi-typescript 的 lockstep 生成。

延伸阅读 ​

• 02 分层
• 13 思考题