feat(proxy): 增加可选的 Codex Multi-Agent V2 第三方子 Agent 明文兼容

.env.example

@@ -50,6 +50,16 @@ CODEX_PORT=8080
 # Codex 上游传输：默认 http；可设 ws 强制使用 WebSocket；auto 在 HTTP 入站下仍走 http
 # CODEX_UPSTREAM_TRANSPORT=http
 
+# Codex Multi-Agent v2 第三方子 Agent 明文兼容（实验性，默认关闭）。
+# 仅对官方 Codex 客户端、原生 Codex 账号、且请求含 collaboration 下的
+# spawn_agent / send_message / followup_task 时生效：移除 message 的
+# encrypted 标记并把命名空间临时改名为 collaboration-optimize，响应再还原。
+# 开启后无法区分子 Agent 提供方，匹配的 v2 协作消息都会走明文；上游可能按
+# 非标准 schema 拒绝或触发风控，请先在隔离实例/账号池灰度。不解密历史密文；
+# 冲突、无效 JSON 或工具数量超限时保持原生路径。
+# 详见 docs/CODEX_MULTI_AGENT_V2_COMPAT.md。
+# CODEX_MULTI_AGENT_V2_COMPAT=false
+
 # 旧版 WebSocket 开关（兼容保留；推荐改用 CODEX_UPSTREAM_TRANSPORT=ws）
 # USE_WEBSOCKET=true
 

README.md

@@ -206,6 +206,7 @@ Antigravity accounts are managed as a dedicated Google channel with browser/impo
 | [Usage Guide](docs/USAGE.md) | Client setup, SDK examples, media workflows, and troubleshooting | `docs/USAGE.md` |
 | [API Documentation](docs/API.md) | API endpoints, request and response examples, error codes | `docs/API.md` |
 | [Antigravity Integration](docs/ANTIGRAVITY.md) | Google OAuth and experimental API Key channel, models, risks, and protocol status | `docs/ANTIGRAVITY.md` |
+| [Codex Multi-Agent v2 Compatibility](docs/CODEX_MULTI_AGENT_V2_COMPAT.md) | Opt-in plaintext compatibility for third-party subagents, risks, rollout, rollback | `docs/CODEX_MULTI_AGENT_V2_COMPAT.md` |
 | [Deployment Guide](docs/DEPLOYMENT.md) | Deployment modes, upgrade guide, backup and restore | `docs/DEPLOYMENT.md` |
 | [Configuration Guide](docs/CONFIGURATION.md) | Environment variables, system settings, configuration priority | `docs/CONFIGURATION.md` |
 | [Architecture](docs/ARCHITECTURE.md) | System architecture, scheduling algorithm, storage design | `docs/ARCHITECTURE.md` |

README.zh-CN.md

@@ -257,6 +257,7 @@ Antigravity 作为独立 Google 渠道管理，支持浏览器/导入 OAuth 凭
 | [API 文档](docs/API.md) | 所有 API 端点、请求/响应示例、错误码说明 | `docs/API.md` |
 | [使用指南](docs/USAGE.md) | 客户端接入、SDK 示例、媒体任务与常见错误排查 | `docs/USAGE.md` |
 | [Antigravity 接入](docs/ANTIGRAVITY.md) | Google OAuth、实验性 API Key 渠道、模型、风险与协议验证状态 | `docs/ANTIGRAVITY.md` |
+| [Codex Multi-Agent v2 兼容](docs/CODEX_MULTI_AGENT_V2_COMPAT.md) | 第三方子 Agent 明文字段兼容、风险、灰度与回滚 | `docs/CODEX_MULTI_AGENT_V2_COMPAT.md` |
 | [部署文档](docs/DEPLOYMENT.md) | 各种部署模式、升级指南、备份恢复 | `docs/DEPLOYMENT.md` |
 | [配置文档](docs/CONFIGURATION.md) | 环境变量、系统设置、配置优先级 | `docs/CONFIGURATION.md` |
 | [架构文档](docs/ARCHITECTURE.md) | 系统架构、调度算法、存储设计 | `docs/ARCHITECTURE.md` |

docs/CONFIGURATION.md

@@ -91,6 +91,7 @@ Codex2API 采用三层配置架构：
 | `CODEX_COMPACTION_AFFINITY_TTL` | 否 | `168h` | 加密压缩状态的来源亲和 TTL。缓存仅保存密文的 SHA-256 摘要、来源账号和兼容域；已知状态不会跨 Codex 官方、不同 Responses 中转或 Grok 上游流转 |
 | `CODEX_FINGERPRINT_DEBUG` | 否 | `false` | 输出脱敏指纹策略诊断日志，不记录 token |
 | `CODEX_REQUEST_COMPRESSION` | 否 | 跟随系统设置 | 覆盖系统设置「Codex HTTP 请求体压缩」。`zstd`/`on`/`true`/`1` 强制开启，`off`/`false`/`0` 强制关闭，未设置或取值无法识别时以系统设置为准。作为部署级逃生阀存在：DB 不可达或后台打不开时仍可整机切换 |
+| `CODEX_MULTI_AGENT_V2_COMPAT` | 否 | `false` | 实验性：为官方 Codex 客户端的 Multi-Agent v2 协作工具启用明文参数兼容。仅原生 Codex 账号生效，重启生效；开启后匹配的 v2 子任务正文会以明文发送。详见 `docs/CODEX_MULTI_AGENT_V2_COMPAT.md` |
 | `CODEX_TELEMETRY_ENABLED` | 否 | 跟随系统设置 | 设为 `false` 时无视管理后台「客户端遥测」开关，部署层强制关闭模拟遥测外发 |
 | `CODEX_STATSIG_API_KEY` | 否 | 内置公开 key | 覆盖 Codex Desktop/CLI 共用的公开 Statsig SDK key，仅遥测开启时使用 |
 | `CODEX_SESSION_HEADER_MODE` | 否 | `native` | 出站会话头形态。`native` 发真实客户端的 `session-id` / `thread-id` / `x-client-request-id`；`legacy` 回退到旧的 `Session_id`（WS 另带 `Conversation_id`） |

docs/DEPLOYMENT.md

@@ -335,6 +335,10 @@ REDIS_ADDR=rediss://default:your-redis-password@your-redis-host:6379/0
 ```bash
 # 快速调度器
 FAST_SCHEDULER_ENABLED=true
+
+# 实验性：Codex Multi-Agent v2 第三方子 Agent 明文兼容（默认关闭）
+# CODEX_MULTI_AGENT_V2_COMPAT=false
+# 说明与灰度步骤见 docs/CODEX_MULTI_AGENT_V2_COMPAT.md
 ```
 
 ### 2. 系统设置（通过管理后台）