评估 AGC 与独立 Codex 替换边界

对比 AGC 0.147.0、独立适配器 0.152.1 与本机 Codex 0.153.4

记录协议、隔离、工具桥与 Runtime 职责差异

明确先做 0.153.4 typed adapter 和可切换接线，不直接替换生产路径

docs/technical/【技术评估】AGC与独立Agent Codex替换对比-2026-09-09.md

@@ -0,0 +1,66 @@
+# AGC 与独立 Agent Codex 替换对比
+
+## 结论
+
+当前不能直接把 AGC 的 Codex 实现替换成 `rust/` workspace 的
+`agent-codex`，也不能只替换可执行文件后宣称兼容。三处版本和职责并不一致：
+
+| 位置 | 当前版本/协议 | 实际范围 |
+| --- | --- | --- |
+| AGC npm/Windows sidecar | `@openai/codex` / `codex-cli 0.147.0` | 自建 Tokio app-server 连接池、隔离 `CODEX_HOME`、workspace sandbox、MCP/Skill、项目工具桥、Runtime 事件和取消/审计 |
+| 独立 `rust/agent-codex` | 通用 JSONL/V2 + 窄 `codex_0_152_1` | 进程与 JSON-RPC transport、有限生命周期、有限 server-request/notification DTO；不嵌入 `codex-core`，不持有项目 Runtime 真相 |
+| 本机 Codex | `codex-cli 0.153.4` | 可验证 initialize/thread-start；schema 已扩展，不能作为 0.152.1 的兼容证明 |
+
+## 接线差异
+
+AGC 的 `codex_app_server.rs` 还负责凭据桥接、敏感环境变量排除、临时目录、只读/可写
+workspace 模式、`agc_tools` MCP、Skill roots、连接池和项目级安全策略。独立适配器的
+`CodexAppServerProcess` 只负责进程/协议边界，默认不会清空环境、注入 `CODEX_HOME` 或
+设置工作目录；Host 的 handler 也只覆盖工具调用桥接。因此直接替换会丢失 AGC 的安全和
+业务运行时语义。
+
+协议上，AGC 当前使用 initialize → thread/start → turn/start，并处理项目工具请求、MCP/
+Skill 初始化、turn/agent-message 通知和 `turn/interrupt`。独立适配器的通用层可承接
+JSON-RPC transport，0.152.1 typed 层只覆盖有限的 initialize/thread/start/turn/start/
+interrupt、8 类 server request 和 6 类通知；它不是完整生成 schema。
+
+## 与 Codex 版本对比
+
+本机 0.153.4 的实验 schema 已明显扩展：v2 bundle 约 706653 bytes，包含约 155 个
+client methods、11 个 server requests 和 81 个 server notifications；新增/扩展了
+thread queue、resume/steer、settings、goals、realtime、plugins、skills、MCP、文件与
+进程等边界。独立仓库当前 fixture 固定 0.152.1，不能把相同的 `v2` 标签当作发行版兼容。
+
+上游 `openai/codex` 还把 `app-server-protocol`、`app-server-client`、`app-server-transport`
+和 `app-server` 拆成多个 crate，并提供异步 typed/raw API、server-request resolution、
+有序事件队列和多种 transport；这不等于应把 `codex-core` 搬进 AGC。AGC 的项目 Runtime、
+工具权限、持久化和预览完成门仍应由 AGC 掌控。
+
+## 分阶段替换路线
+
+1. 先在独立 workspace 新增明确命名的 `codex_0_153_4` typed adapter，基于该版本生成的
+   provenance/schema fixture，覆盖 initialize、thread/start、turn/start、interrupt、
+   核心通知和 dynamic-tool request；未覆盖方法默认拒绝或保留 raw，不静默猜测。
+2. 给通用 process facade 增加显式的工作目录和环境策略接口，或由 AGC 外层继续负责
+   `CODEX_HOME`、凭据桥和敏感环境排除；不能因接入 Rust adapter 而削弱隔离。
+3. 在 AGC 内增加版本无关的窄 adapter trait，让现有 `codex_app_server.rs` 与 Rust
+   adapter 可切换；保留 0.147.0 路径作为回滚实现，先做离线握手、通知、server-request、
+   cancel/timeout 和 Runtime 事件回归。
+4. 通过隔离 `CODEX_HOME` 的真实 0.153.4 initialize/thread/turn/tool smoke 后，才考虑
+   更新 npm lock、Windows sidecar、NOTICE、build manifest 和默认版本；真实 turn 必须
+   使用授权环境，不能用 fixture 代替。
+
+## 当前不做
+
+- 不直接修改 AGC 的生产 Codex 接线或删除 0.147.0 fallback。
+- 不复制 `codex-core`、ThreadStore、sandbox、认证、MCP/Skill/plugin 子系统到独立内核。
+- 不把本机 0.153.4 的握手通过写成完整 session、工具或版本兼容已验收。
+
+## 证据
+
+- AGC：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs`、
+  `codex_cli.rs`、`runtime_protocol/provider_retry.rs`。
+- 独立适配器：`rust/crates/agent-codex/src/lib.rs`、
+  `rust/crates/agent-codex/src/codex_0_152_1.rs` 及其审计文档。
+- 版本来源：AGC `package.json`/`package-lock.json`、`src-tauri/build.rs`；本机
+  `codex --version` 为 `codex-cli 0.153.4`。