# Coding Agent 多实现架构对比

> **本文档定位**：横向对比业界主流 coding agent 的架构选型（接入层 / 多 provider / 工具系统 / 扩展机制 / 状态管理 / 信任模型），为 FFAI Agent 内核（[`00-architecture.md`](./00-architecture.md)）的架构演进提供决策依据。
>
> **生长方式**：本文档**持续累积**——每分析完一个新的 agent 实现，就在下方加一栏，并更新对比矩阵。当前已收录 3 个，待收录占位若干。
>
> **不做什么**：不做"哪个最好"的排名，只做"在 X 维度上 A 选了 B 路线、为什么、代价是什么"的事实记录。

---

## 已收录实现

| 简称 | 全名 | 版本 | 类型 | 详细分析 |
|---|---|---|---|---|
| **CC** | Claude Code | 2.1.88 | 闭源商业 CLI（TypeScript） | [`claude-code-reference.md`](./claude-code-reference.md) |
| **OC** | OpenClaude (Gitlawb) | 0.11.0 | 开源 fork（TypeScript / 多 provider） | [`openclaude-reference.md`](./openclaude-reference.md) |
| **CDX** | Codex CLI (OpenAI) | 0.130.0 | 开源 Apache 2.0（Rust / 多端 daemon-client / Cargo workspace ~98 crate） | [`codex-reference.md`](./codex-reference.md) |
| **FFAI** | FFAI Agent (本项目) | v0.1 草案 | 自研 Web/多租户 | [`00-architecture.md`](./00-architecture.md) |

## 待收录占位

| 简称 | 全名 | 类型 | 优先级 | 备注 |
|---|---|---|---|---|
| **OPC** | OpenCode (SST) | MIT 开源 CLI | 高 | 75+ provider，120k+ stars，最大开源对手 |
| **CLN** | Cline | 开源 IDE 扩展 | 高 | 5M+ 安装，VSCode/JetBrains/Zed/Neovim 多端 |
| **AID** | Aider | 开源 CLI | 中 | 老牌，git 集成深，pair-programming 范式 |
| **CSR** | Cursor | 闭源 IDE | 中 | fork 自 VSCode，agent + IDE 一体化 |
| **GMI** | Gemini CLI (Google) | 半开源 | 低 | Google 官方 |
| **CRS** | Cursor / Composer | 闭源 | 低 | Cursor 内嵌 agent |
| **WND** | Windsurf (Codeium) | 闭源 IDE | 低 | 类 Cursor |

> 优先级按"对 FFAI 架构决策的参考价值"排，不是按市场份额。

---

## 一、对比矩阵（速查）

| 维度 | CC (Claude Code) | OC (OpenClaude) | **CDX (Codex CLI)** | FFAI 当前/计划 |
|---|---|---|---|---|
| **核心定位** | Anthropic 垂直整合产品 | 多 provider 平台 | **OpenAI 多端 daemon-client** | 多租户 Web 内置 agent |
| **目标用户** | 单租 / 个人开发者 | 单租 / 自托管 | 单租 + 企业 cloud tasks | 多租 / 企业团队 |
| **运行形态** | 本地 Node 进程 | 本地 Node 进程 | **本地 Rust daemon + 多 client** | Web 后端常驻 |
| **接入面** | CLI（Ink TUI）+ VSCode + 远程 WS | + gRPC + 独立 Web + Python | **TUI(ratatui) + CLI + IDE + Python SDK + TS SDK 自动生成 + cloud tasks** | Web UI（主） + 未来 IDE 扩展 |
| **语言/包模型** | TypeScript / npm 单包 | 同 | **Rust 96.2% / Cargo workspace ~98 crate / npm shim 分发** | TypeScript / npm |
| **架构纪律** | 隐式 | 隐式 | **AGENTS.md 写明"resist adding to core"** | 待定 |
| **provider 模型** | Anthropic 直连（+ Bedrock + Vertex） | 11 vendors × 18 gateways × 200+ 模型 | OpenAI Responses API + Bedrock + Ollama + LM Studio + 自定义 | 多 provider（自研路由层） |
| **协议层** | Anthropic 一种 | 三协议归一（OAI / Anthropic / Gemini） | **JSON-RPC 2.0 v1+v2（v2 = 12K LoC）+ TS SDK 通过 ts-rs 派生** | 待定 |
| **工具系统** | 43+ 内置工具，统一 Tool.ts 接口（isReadOnly + isEnabled 双布尔） | 49 个（继承 + 新增），同接口 | **`ToolExecutor<Invocation>` 异步泛型 trait + `ToolExposure` 三态（Direct/Deferred/DirectModelOnly）** | 待设计 |
| **patch 协议** | Edit tool 字符串替换 | 同 | **自定义 DSL**（`*** Begin Patch` envelope，4 操作 + `@@` hunk + 流式 parser） | 待定 |
| **Shell 解析** | 字符串 / 正则匹配 | 同 | **tree-sitter-bash 真 parser** | 待定 |
| **执行策略** | 三态（allow/deny/ask） | 同 | **execpolicy v2 声明式 + v1 Starlark 双引擎 + 网络规则** | 待设计 |
| **扩展机制** | skills + plugins + hooks 三层 | 同上（继承） | 同 + **ext/Contributor 模式（4 种 trait）+ Plugin Marketplace（9 大 SaaS 出厂内置）** | 待设计 |
| **Hook 事件** | ~6 | ~6 | **8（含 PostCompact / UserPromptSubmit）** | 待设计 |
| **MCP 角色** | client | client | **client + server 双向**（rmcp-client + codex-mcp + mcp-server 三件套） | 待定 |
| **状态持久化** | `~/.claude/` 文件 + memdir | `~/.openclaude/` 同上 | **三层**：message-history(JSONL) + rollout(snapshot) + rollout-trace(reducer) | DB（多租户必需） |
| **多 agent 持久化** | 隐式（fork） | 同 | **agent-graph-store 显式 parent-child 边 + agent-identity（JWT/JWKS）** | 待设计 |
| **沙盒** | macOS sandbox-exec / Linux landlock / Docker | 同上 + Termux/proot（Android） | **Linux: bwrap+landlock+seccomp；Win: AppContainer+JobObj+ACL+ConPTY 15K LoC；macOS: Seatbelt** | Docker 容器（多租户必需） |
| **Network 控制** | 无 | 无 | **MITM TLS proxy + allowlist**（9.3K LoC） | 待定 |
| **进程加固** | 无 | 无 | **#[ctor] pre-main**（禁 ptrace / coredump / 剥离 LD_PRELOAD） | 无（Docker 内运行） |
| **会话历史** | JSONL 本地文件 | 同上 + SQLite Phase 2 | TOML + JSON 混合（rollout） | DB（多租户必需） |
| **远程协作** | remote/ WebSocket | 同 + Web | **cloud-tasks 三件套接 chatgpt.com 后端** | 待定 |
| **多 agent 协调** | coordinator/（同进程 fork+resume） | 同上 | 同 + agent-graph-store + identity | 待设计（应跨进程） |
| **OSS 模型默认** | N/A | N/A | **gpt-oss-20b（LM Studio + Ollama）** | 待定 |
| **凭据** | OS keyring / env | profile 文件 | **login + keyring-store（4 平台）+ aws-auth + secrets（age 加密）四件套** | vault / KMS |
| **Telemetry** | Anthropic 后台 | `verify-no-phone-home.ts` 强制审计 | **OTEL → Statsig (ab.chatgpt.com/otlp) + Sentry SaaS feedback** | 自托管 OTel |
| **协作模式** | N/A | N/A | **PLAN / DEFAULT / EXECUTE / PAIR_PROGRAMMING** first-class | 待定 |
| **语音 agent** | N/A | N/A | realtime-webrtc（macOS only） | 待定 |
| **竞品迁移** | N/A | N/A | **external-agent-migration / sessions（from CC）** | 待定 |
| **构建系统** | npm | npm | **Bazel + Cargo + Just + pnpm + Nix flake**（5 套并存） | npm |
| **代码量** | ~unknown (闭源 sourcemap 还原 1332 .ts) | ~2451 源文件 | **~98 crate，主要 crate 加起来 600K+ Rust LoC**（tui 188K · core 152K · app-server 38K · windows-sandbox 15K） | 早期 |
| **开源协议** | 闭源（npm 包可用） | MIT | **Apache 2.0** | 内部 |

---

## 二、维度逐项展开

### 2.1 接入面（Surface）

| | CC | OC | **CDX** | 业界趋势 |
|---|---|---|---|---|
| CLI | ✅ Ink TUI（重） | ✅ 同 | ✅ ratatui TUI（188K LoC，比 core 还大）+ exec 子命令 | 仍是开发者主入口 |
| HTTP poll (IDE) | ✅ `bridge/` | ✅ 继承 | ✅ via app-server JSON-RPC over HTTP | IDE 集成首选 |
| WebSocket | ✅ `remote/` | ✅ 同 | ✅ app-server-transport WebSocket | 浏览器/移动必需 |
| gRPC | ❌ | ✅ `grpc/+proto/` | ❌ 用 **JSON-RPC 2.0**（不上 gRPC） | 多语言 SDK 趋势 |
| 远端任务/Web | 部分（共享 remote） | ✅ 独立 `web/` 子项目 | ✅ **cloud-tasks** 接 chatgpt.com 后端 | 远程协作场景 |
| Python SDK | ❌ | ✅ | ✅ **手写 wrapper**（spawn CLI + 解析事件） | 部分 |
| TypeScript SDK | ❌ | 部分 | ✅ **ts-rs 自动生成自 Rust 类型** | 部分 |
| Daemon-client 分离 | ❌ | ❌ | ✅ **app-server-daemon** 独立常驻 + 多 client | 早期 |
| Mobile native | ❌ | ⚠ 仅 Termux+proot 跑 CLI | ❌ | 早期 |
| 语音 | ❌ | ❌ | ⚠ realtime-webrtc（仅 macOS） | 早期 |

**FFAI 决策建议**：Web UI 是必选；IDE 用 HTTP poll；外部 SDK 走 ts-rs 风格的"类型自动派生"路线（不要 gRPC 也不要纯手写）。**不要复刻 OpenClaude 的 4 套并存**——历史包袱；**也不复刻 Codex 的 daemon-client 分离**——FFAI 是 Web 服务自带 daemon 形态，重点在 protocol/transport 解耦（学 Codex），不在另起 daemon 进程。

详见 [`openclaude-reference.md` 附录 C.3](./openclaude-reference.md#c3-外部客户端接入websocket--http--grpc-怎么选)、[`codex-reference.md` §5 app-server 五件套](./codex-reference.md#5-app-server-五件套)。

### 2.2 多 Provider 路由

| | CC | OC | **CDX** | FFAI |
|---|---|---|---|---|
| 上游数 | 1（Anthropic） | 11 vendors × 18 gateways | OpenAI Responses API + Bedrock + Ollama + LM Studio + 自定义 | 待定 |
| 协议归一 | 不需要 | OAI / Anthropic / Gemini 三种 | 主要是 OpenAI Responses API（其他通过 model-provider trait 适配） | 必需 |
| Provider 配置位置 | env var | profile 文件（per-user） | `~/.codex/config.toml` + env override + ConfigRequirements 约束 | 必须 per-tenant |
| 模型路由 | 直绑 | descriptor + adapter 三层 | **三层**：model-provider trait（工厂）+ model-provider-info（注册表 + 重试策略）+ models-manager（目录 + 协作模式） | 待设计 |
| Cost tracking | Anthropic billing | 多 vendor token 计价表 | OTEL/analytics 含 token usage + Statsig 后端 | 必需（计费） |
| OSS 默认 | 无 | dev:fast profile | **gpt-oss-20b**（LM Studio + Ollama 都默认） | 无（v1） |

**FFAI 决策建议**：直接借鉴 OC 的 `integrations/` 三层模式（vendor descriptor + gateway adapter + routeMetadata），但 profile 必须从 per-user 改为 per-request（带 tenant context）。Codex 的三层（trait + info + manager）跟 OC 三层同构，可二选一参考；**ConfigRequirements 约束系统（哪些 provider 在哪些 plan 下可用）值得借鉴用于多租户 quota**。

详见 [`openclaude-reference.md` Part II](./openclaude-reference.md#part-ii--多-provider-路由系统-openclaude-核心差异化)、[`codex-reference.md` §8 model-provider 三件套](./codex-reference.md#8-model-provider-三件套)。

### 2.3 工具系统（Tool）

| | CC | OC | **CDX** | 设计要点 |
|---|---|---|---|---|
| 接口规范 | `Tool.ts` 8 个生命周期方法 | 同上（fork） | **`ToolExecutor<Invocation>` 异步泛型 trait** + ToolSpec（JSON schema）解耦 | name/desc/inputSchema/call/render×2/isReadOnly/isEnabled |
| 可见性控制 | isReadOnly + isEnabled 双布尔 | 同 | **`ToolExposure` 三态**：Direct / Deferred / DirectModelOnly | 三态表达力强 |
| 内置工具数 | 43+ | 49 | code-mode（exec + wait）+ apply-patch + shell + memories（list/read/search）+ ext + connectors（动态注册） | 文件 / 执行 / 网络 / agent / IDE |
| 权限模型 | 三态（allow/deny/ask）+ 持久化 | 同 + 多租户审计 | **execpolicy v2 声明式 + v1 Starlark 双引擎**（Decision: Allow/Deny/Prompt）+ 网络规则 | 必需可审计 |
| Patch 协议 | Edit tool 字符串替换 | 同 | **自定义 DSL**：`*** Begin Patch` envelope + 4 操作头 + `@@` hunk + 流式 parser | 三种范式之一 |
| Shell 解析 | 字符串/正则 | 同 | **tree-sitter-bash 真 parser**（is_safe_command / is_dangerous_command） | 多租户应用真 parser |
| 异步流式 | ✅ 工具产 token 流 | ✅ | ✅ via app-server-protocol notifications | 长任务必需 |
| 跨进程沙盒 | macOS sandbox-exec / Linux landlock | + Docker / Termux | **Linux: bwrap+landlock+seccomp；Win: AppContainer+JobObj+ACL+ConPTY 15K LoC；macOS: Seatbelt** | 多租户必需 Docker |
| Network 控制 | 无 | 无 | **MITM TLS proxy + allowlist**（9.3K LoC，工具 HTTPS 强制走自家 proxy） | 多租户必需 egress 控制 |
| 进程加固 | 无 | 无 | **#[ctor] pre-main**：禁 ptrace / coredump / 剥离 LD_PRELOAD | Web + Docker 不需要 |

**FFAI 决策建议**：直接照搬 Tool.ts 接口；权限三态保留；**Tool 接口加 `ToolExposure` 三态**（参考 Codex）；执行类工具（Bash / Edit / Write）必须在每租户独立 Docker 容器；**Shell 命令必须用 tree-sitter-bash 真 parser 而不是字符串匹配**（多租户场景字符串匹配易绕过）。

### 2.4 扩展机制（skills / plugins / hooks）

| 维度 | 含义 | CC | OC | **CDX** |
|---|---|---|---|---|
| **skills** | 工作流模板（markdown + frontmatter） | ✅ | ✅ + 更多内置 | ✅ **双层**：skills（内置资产 169 LoC）+ core-skills（运行时框架 7K LoC） |
| **plugins** | 工具集合（可批量启用一组工具） | ✅ | ✅ | ✅ **双层 + Marketplace**：plugin（identity 386 LoC）+ core-plugins（marketplace 20.6K LoC，**内置 9 大 SaaS 允许列表**：GitHub/Notion/Slack/Gmail/Google Calendar/Figma/Linear/Canva/Teams） |
| **hooks** | 生命周期回调（pre-tool / post-tool / on-msg / on-resp / on-error） | ~700K | 944K（90+ 文件） | **8 个事件**（含 PostCompact / UserPromptSubmit），9.8K LoC，regex matcher |
| **MCP** | 通过 MCP 协议接外部 server 的工具/资源 | client | client | **client + server 双向**（rmcp-client + codex-mcp + mcp-server 三件套） |
| **Contributor 模式** | trait-based 贡献接口 | N/A | N/A | ✅ **ext/extension-api**：4 种 trait（ToolContributor / TurnItemContributor / ThreadLifecycleContributor / ApprovalReviewContributor） |
| **三者边界** | skill = "怎么做"模板；plugin = "有什么工具"；hook = "什么时候插一脚" | 边界清晰 | 同 | 同 + ext/Contributor 是 trait-based DI 第四层 |
| **竞品迁移** | 从其他 agent 导入配置/会话 | N/A | N/A | ✅ **external-agent-migration / sessions**（from Claude Code，源码称 CC 为 "predecessor"） |

**FFAI 决策建议**：三层全保留（skills + plugins + hooks）。OC 的 hooks 数量爆炸是因为多 provider 兼容 hook 多——FFAI 如果走多 provider 也会面临同样问题，**hook 系统从一开始就要设计成可注册 + 可热加载**。**Plugin Marketplace 是企业版差异化**（v2 优先级），但内置 SaaS 列表应对齐国内市场（飞书/钉钉/企微/金山/腾讯文档），不直接复刻 Codex 的国际 9 项。**MCP server 角色（让其他 agent 调用 FFAI）值得早做**，跟"FFAI 作为多租户 agent 平台"定位天然匹配。

### 2.5 状态管理与持久化

| | CC | OC | **CDX** | FFAI |
|---|---|---|---|---|
| 配置 | `~/.claude/settings.json` | `~/.openclaude/profile.json` | `~/.codex/config.toml` + profiles + ConfigRequirements 约束 | DB（per-tenant） |
| 会话历史 | JSONL 本地文件 | 同 + SQLite Phase 2 | **三层**：message-history（JSONL append-only `O_APPEND` 原子）+ rollout（TOML+JSON 快照）+ rollout-trace（event sourcing reducer 12K LoC） | DB（必须）|
| 多 agent 拓扑 | 隐式（同进程 fork） | 同 | **agent-graph-store 显式 parent-child 边**（独立 trait + 实现） | 待设计 |
| Agent 身份 | N/A | N/A | **agent-identity（JWT/JWKS）** —— 企业级身份 | 待设计 |
| 持久化记忆 | memdir 分类型（user/feedback/project/reference）+ MEMORY.md 索引 | 同 | **ext/memories**（list/read/search 工具）+ global memdir 类似 | DB + 可能 vector store |
| 项目级 | CLAUDE.md / AGENTS.md | 同 | **AGENTS.md**（Codex 用同名约定，甚至比 CC 更严：写明 Rust 风格/架构纪律 17K 字） | 可能 per-org markdown |

**FFAI 决策建议**：memdir 的"分类型 + 索引"模式可借鉴；底层从文件换 DB；MEMORY.md 索引模式很妙——LLM context 只塞索引，按需展开。**新增**：从 Codex 借鉴**持久化分三层**（append-only audit log + session snapshot + 可选 reducer），v1 至少做前两层但 schema 设计要 reducer-friendly；**agent-graph-store 显式 parent-child 边 + agent-identity（JWT）**对多 agent 长期演进必需。

### 2.6 信任与安全模型

| | CC | OC | **CDX** | FFAI |
|---|---|---|---|---|
| 数据流向 | Anthropic 后端 | 用户自管 | OpenAI 后端（cloud-tasks 走 chatgpt.com）+ Statsig OTLP + Sentry SaaS | 自托管 |
| Telemetry | 默认开（Anthropic） | `verify:privacy` 脚本审计零外发 | **默认开**：OTEL → `https://ab.chatgpt.com/otlp/v1/metrics`（Statsig）+ Sentry feedback DSN 写死 | 自托管 OTel |
| 工具权限 | 三态 + 用户确认 | 同 | **execpolicy v2 声明式**（Allow/Deny/Prompt + 网络规则）+ 提权 Unix socket 通道 | 同 + 审计日志 |
| 凭据管理 | OS keyring / env | profile 文件 | **四件套**：login（OAuth/PKCE 7.3K）+ keyring-store（4 平台原生 226 LoC）+ aws-auth（SigV4 / Bedrock）+ secrets（**age 加密** + redact_secrets） | 必须 vault / KMS |
| 进程加固 | 无 | 无 | **#[ctor] pre-main**：禁 ptrace / coredump / 剥离 LD_PRELOAD/DYLD_* | Docker 内不需要 |
| Network 出站 | 无控制 | 无控制 | **MITM TLS proxy + allowlist**（network-proxy 9.3K LoC，工具 HTTPS 强制走自家 proxy） | 必需 egress 控制 |
| 沙盒（OS 级） | macOS sandbox-exec / Linux landlock | + Docker / Termux | **三平台独立 crate**：Linux bwrap+landlock+seccomp（6.6K）/ Win AppContainer+JobObj+ACL+ConPTY（**15K**）/ macOS Seatbelt | Docker 第一道，OS 沙盒第二道（多租必需） |
| 多租隔离 | N/A（单租） | N/A（单租） | N/A（单租） | **核心需求** |

**FFAI 决策建议**：单租 agent 的安全设计**不能直接套用**到多租。Tool 执行必须在 per-tenant 容器；LLM 调用必须带 tenant id 走中央 quota；所有持久化必须 row-level security。**新增**：从 Codex 借鉴 **secrets crate 的 age 加密 + `redact_secrets()` 工具**——多租户 audit log 必需 secret redaction；**网络 egress 必须控制**——v1 用 Docker 网络层 IP/port allowlist，v2 升 HTTP proxy + URL allowlist（不必上 MITM TLS，URL allowlist 在 client config 即可）；**Statsig/Sentry 写死 endpoint 是反例**——FFAI 必须可配置 + 自托管 OTel collector + GlitchTip。

### 2.7 多 Agent 协调

| | CC | OC | **CDX** |
|---|---|---|---|
| 模型 | 同进程 fork + resume（coordinator/） | 同 | 同进程 + **agent-graph-store 显式 parent-child 边**（独立 trait + 实现） |
| 通信 | 内存共享 + IPC | 同 | 同 + Unix socket（提权通道 / app-server-transport UDS） |
| 极限 | 受限于单机内存 / CPU | 同 | 同（虽然 cloud-tasks 接 chatgpt.com 但那是任务卸载，不是 agent 协调） |
| 身份 | N/A | N/A | **agent-identity（JWT/JWKS）** —— 每 agent 独立身份，可做企业审计 |
| 子 agent 派生 | 内置在 core | 内置在 core | **`ext/guardian` 通过 extension API 注入**（不在 core 硬编码） |

**FFAI 决策建议**：单机协调够用就不动；要扩展到分布式必须加任务队列（Temporal / Redis Streams）+ 分布式 lock。OC 也没解决这个问题。**新增**：从 Codex 借鉴**两点**：① agent-graph-store 把 parent-child 边显式存储——FFAI 多 agent 必需，否则没法追溯/回放/审计；② ext/guardian 把"subagent spawner"做成可选 extension 而不是 core 硬编码——便于不同租户用不同的派生策略（限速 / 配额 / 模型选择）。**agent-identity (JWT)** 在 FFAI 多租户场景几乎是标配，应早做。

---

## 三、待补充对比维度（部分已被 CDX 覆盖）

收录到 OpenCode / Cline / Aider 后再展开。其中部分维度 Codex 已提供数据点，下次刷新时把对应小节并入 §二：

- **IDE 深度集成**：Cursor / Cline / Windsurf 是 IDE 一等公民，CC/OC 是"加在 IDE 上"。**Codex 也是"加在 IDE 上"**（README 提及 VSCode/Cursor/Windsurf 安装），架构差异巨大
- **Pair-programming 范式 vs Agent 范式**：Aider 把人和 LLM 平等当 pair，CC/OC 把 LLM 当主控。**Codex 用 collaboration-mode-templates 把 PAIR_PROGRAMMING 作为 first-class 模式**，介于两种范式之间——这是个新发现
- **本地模型优化**：Aider 对 7B 小模型有大量适配；OC 也有 `dev:fast` profile；CC 不考虑。**Codex 出厂集成 Ollama + LM Studio，默认 gpt-oss-20b（OpenAI 自家 open-weight）**——是开源化最彻底的官方 agent
- **diff 应用策略**：四种范式并存：① Aider 的 SEARCH/REPLACE block；② CC 的 Edit tool（字符串替换）；③ OC 同 CC；④ **Codex 的自定义 DSL**（`*** Begin Patch` envelope + `@@` hunk + 流式 parser）。**LLM 输出准确率和 token 成本**是关键差异，需要专项对比
- **会话回放与审计**：企业场景必需；CC/OC 都偏弱。**Codex 的 rollout-trace（event sourcing reducer 模式 12K LoC）**是工业级实现，但对单租户场景过重
- **Cost optimization**：prompt caching / batch / context truncation 策略对比；**Codex 的 PostCompact hook + analytics 的 CodexCompactionEvent / CompactionPhase / CompactionStatus 是 token 优化可观测性的好范例**
- **AGENTS.md 工程纪律对比**：Codex 的 AGENTS.md 17K 字写明 Rust 风格 / 模块大小约束 / 命名规则 / 测试要求 / API 契约——是"AI-first 团队工程纪律"的范例。CC/OC 的 CLAUDE.md/AGENTS.md 内容偏简
- **MCP 双向（client + server）**：Codex 是少见的"既是 MCP client 也是 MCP server"实现。FFAI 作为多租户 agent 平台，server 角色是天然差异化点

---

## 四、给 FFAI 架构的决策建议（截至当前对比）

> 当前已看了 CC + OC + CDX，建议会随着收录更多实现而修正。
> 1-5 条来自 CC + OC，**6-10 条**是 CDX 收录后**新增**的建议（来自 [`codex-reference.md` §41](./codex-reference.md#41-5-条对-ffai-的新决策建议基于-codex-独有设计)）。

### 4.1 来自 CC + OC 对比的 5 条

1. **接入面收敛**：Web UI（WebSocket）+ IDE（HTTP poll）+ 外部 SDK（gRPC 或 ts-rs 风格自动生成），其他不做。**不要复刻 OC 的 4 套并存**；**也不必复刻 Codex 的 daemon-client 物理分离**——FFAI Web 服务自带 daemon 形态，重点在 protocol/transport 解耦（学 Codex），不在另起 daemon 进程。
2. **多 provider 抽象**：照搬 OC 的 `integrations/` 三层（vendor descriptor + gateway + routeMetadata）或 Codex 的 model-provider 三件套，profile 改为 per-request 带 tenant context。**ConfigRequirements 约束系统**（哪些 provider 在哪些 plan 下可用）值得借鉴用于多租户 quota。
3. **工具系统**：照搬 CC/OC 的 Tool.ts 接口；**加 `ToolExposure` 三态**（Direct/Deferred/DirectModelOnly，参考 Codex）；执行类工具必须 Docker 沙盒；**Shell 命令必须用 tree-sitter-bash 真 parser** 而不是字符串匹配（多租户场景字符串匹配易绕过）。
4. **扩展机制**：skills + plugins + hooks 三层全保留；hook 系统设计为可注册 + 可热加载；**MCP 一开始就做双向**（client + server），FFAI 作为多租户 agent 平台，server 角色是天然差异化。
5. **持久化**：memdir 的"分类型 + 索引"模式 → DB；MEMORY.md "context 只塞索引、按需展开"是关键。**新增**：从 Codex 借鉴**持久化分三层**（append-only audit log + session snapshot + 可选 reducer），v1 至少做前两层但 schema 设计要 reducer-friendly。

### 4.2 来自 CDX 收录后新增的 5 条

6. **接入面用 Daemon-Client 思路（即使是 Web 服务也适用）**：把**协议定义**（事件、命令、payload schema）独立成一层（参考 Codex `app-server-protocol`）；**WebSocket / HTTP / 未来 SSE** 等 transport 实现独立成一层。不要让 WebSocket handler 直接调业务函数——拆开后未来加 IDE HTTP poll / SDK gRPC 都不痛。**TS SDK 通过类似 ts-rs 的方式从后端 schema 自动派生**（Prisma / openapi-typescript-codegen 同模式）。

7. **Tool 接口加 ToolExposure 三态**：CC 的 `isReadOnly + isEnabled` 双布尔表达力不够。Codex 三态对应：Direct（默认）/ Deferred（按 context 触发）/ DirectModelOnly（只让 model 调，不显示在用户工具列表，用于 self-reflection / planning 等内部工具）。FFAI 工具系统应该一开始就有这三态，避免后续改 schema。

8. **Agent identity + agent-graph-store 多 agent 必需**：Codex 把 agent 间的 parent-child 关系显式存储（agent-graph-store），每个 agent 有独立 JWT identity（agent-identity）。多租户 + 多 agent 的 FFAI 没这两个就没法做：跨 agent 审计、quota 追溯、子 agent 派生策略 per-tenant 配置。建议 v1 就把"agent 拓扑表 + agent JWT"列入 schema。

9. **工具网络访问走 egress proxy**：Codex network-proxy 9.3K LoC 用 MITM TLS 拦截工具所有 HTTPS 出站。多租户 FFAI 必须有 egress 控制：v1 用 Docker 网络层 IP/port allowlist；v2 升 HTTP proxy + URL allowlist；v3 才考虑 MITM TLS（如果合规要求看到内容）。**早做**避免数据外泄事故。

10. **Plugin Marketplace 内置国内 SaaS 清单（企业版差异化）**：Codex 出厂 9 大国际 SaaS（GitHub/Notion/Slack/Gmail/Google Calendar/Figma/Linear/Canva/Teams）覆盖国际企业。FFAI 企业版差异化路径——**v1**：plugin 加载机制 + 自家飞书/钉钉/企微；**v2**：marketplace + 国内 SaaS（金山 / 腾讯文档 / 字节内部工具）+ 必备国际 SaaS（GitHub / Slack）。国内"出厂即装"清单跟 Codex 国际 9 项**完全不重叠**——这是真实差异化机会。

---

## 文档元信息

- **创建**：2026-05-14
- **当前版本**：v0.2（CC + OC + CDX 三个实现收录）
- **历史**：
  - v0.1（2026-05-14）：CC + OC 收录
  - v0.2（2026-05-15）：**CDX (Codex CLI 0.130.0) 收录**，对比矩阵新增 25+ 维度（patch 协议 / Shell 解析 / 进程加固 / 网络控制 / OSS 模型 / 协作模式 / 竞品迁移 / 构建系统 / TS SDK 自动生成等），§四决策建议从 5 条扩展到 10 条
- **下次更新触发**：分析 OpenCode / Cline / Aider 后；或 Codex 出现重大架构变更（v0.140+）
- **维护原则**：每收录一个新实现，更新§一表格 + §二每节加列 + §四决策建议同步刷新
- **OpenClaw**：`openclaw-reference.md` 已存在但本文档未收录到 §一对比矩阵——下次刷新一并加入