产品 RFC: Aevatar 作为多 agent 编排层，承接 Codex/Cursor（Responses API）与 Lark/TG/WeChat channel 客户端

[eanzhao]

产品 RFC: Aevatar 作为多 agent 编排层，承接 Codex/Cursor（Responses API）与 Lark/TG/WeChat channel 客户端

Block 项: #608（ChatRuntime refactor）

1. 目标用户场景

用户在自己已经在用的 AI agent 客户端里（Codex / Cursor / Opencode 等说 OpenAI Responses API 的）配置一个第三方 base URL + API key，背后接的不是直连 OpenAI/Anthropic，而是 NyxID（前置网关）+ Aevatar（多 agent 编排） 的运行时。

用户感觉上还是在跟"AI 模型"对话，实际上：

• 任务由 Aevatar 内部多 agent topology 编排（workflow / scripting / sub-agent / RAG）
• LLM credential 由用户在 NyxID 配置；Aevatar 全程不持有 credential
• 同一 user 在不同客户端、不同 channel（Lark / Telegram / WeChat）下复用同一份 agent 状态

第二条入口：用户绑 Lark / Telegram / WeChat 账户，channel 消息走 NyxID channel-relay 进 Aevatar，输出原路回 channel。和 API key 入口走同一套 agent backend。

2. 协议选定：/v1/responses only（v1）

理由：

• previous_response_id 原生支持跨 HTTP 请求会话续传，适合 long-running tool / 多步编排。
• stream SSE 已是 Responses 标准形态。
• Anthropic /v1/messages 无等价 resume 语义；强行支持要塞自定义 session id 进 metadata，客户端不一定认。

客户端覆盖代价：

• Codex / Cursor / Opencode — 原生说 OpenAI Responses。✅
• Claude Code — 原生只说 Anthropic Messages。⚠️ v1 不支持；v2 通过本地 adapter（Messages → Responses 翻译）接入。

v1 首发覆盖 OpenAI-Responses-native 客户端。

3. NyxID 接入模型：和 ornn 一样走通用 proxy plane

aevatar 在 NyxID 上注册为一个普通 DownstreamService row，路径 /api/v1/proxy/s/aevatar/v1/responses——与 ornn / chrono-ornn 同模式，NyxID 侧 v1 无新 Rust 代码。

• NyxID 注入 identity headers（X-NyxID-Identity-Token JWT + 可选 X-NyxID-Delegation-Token）
• aevatar 不验签（信任 proxy，per §14），部署上必须保证 aevatar 只通过 NyxID 入流

（早期版本曾写"NyxID 必须新增 InternalServiceProvider 类"——已纠正。那是 v2 nice-to-have（让 aevatar 出现在 /api/v1/llm/aevatar/* namespace 蹭翻译 pipeline）。v1 通用 proxy 就够。）

4. Aevatar 内部编排（愿景，部分已实现）

LLM 协议层的 "function call" / "tool" 是 JSON Schema + 调用结果的形态；Aevatar 内部 tool 可以是 GAgent / workflow / script / 子 agent / RAG / MCP，只要被 LLM 选中后能产出可序列化结果。所有 Aevatar tool 暴露给 LLM 时被适配成 function-call schema，但反过来不成立——LLM 视角的 function call 不能反推它在 Aevatar 里是哪种实体。这是本 pipeline 真正的耦合点。

具体能力：

• Workflow：YAML 定义，存储在 Ornn 平台作为 skill 资产。
• Scripting：ScriptDefinitionGAgent / ScriptRuntimeGAgent 注册为 agent 内部 tool。
• Sub-agent：GAgent parent-child link 拓扑下的多 agent 协作（per [Aevatar Harness] 核心能力边界讨论 #568）。
• RAG / memory：通过 ProjectionPipeline 物化的 readmodel 查询。

5. 客户端 declared tool 处置策略

默认：forward——客户端 declared 的 tool 原样保留在发给内层 LLM 的 list 里；LLM emit tool_use 透传给客户端；客户端执行回 tool_result；继续。

v1 不做 refuse：任何 tool aevatar 处理不了就让客户端处理，不让 aevatar 的能力缺口卡用户的事。

必须 substitute（同名 tool 在两个世界里语义不同）

Tool	为什么必须 substitute
TodoWrite / Todo* 系列	客户端版本是 client session 内存态；aevatar 版本要 agent-scoped、event-sourced、跨会话可查询、其他 agent 可引用。不 substitute = 违背"aevatar 是跨会话编排层"产品定位。
Task / 客户端 sub-agent dispatch	客户端版本调度 client 内置 subagent runner；aevatar 必须走 GAgent parent-child link 拓扑，否则 subagent 状态不入 ProjectionPipeline、不在 aevatar 视野里、不能被其他 agent 协作。

应该 substitute（aevatar 接管能带来 trace 价值）

Tool	为什么
WebFetch	aevatar 出口 fetch，结果进 RAG / memory；同 URL 跨会话 / 跨 agent 可复用，可缓存。
WebSearch	同理，search trace 进 RAG。

Additive（aevatar 在客户端 declared list 之外加的，aevatar_ 前缀避免命名冲突）

Tool	说明
aevatar_workflow	调用 Ornn 上存储的 workflow YAML。
aevatar_script	调用 ScriptDefinitionGAgent 注册的 script。
aevatar_delegate	派发任务给 sub-agent（GAgent parent-child link）。
aevatar_memory_query	查询 agent 自己的 readmodel。

典型 forward 列表（明说 aevatar 不接管）

Bash / Read / Write / Edit / Glob / Grep / NotebookEdit / Skill（客户端本地 ~/.claude/skills）/ stdio-class MCP — 全部 client 文件系统 / 进程资源，aevatar 没访问权。Remote/HTTP MCP 是潜在 substitute 候选，v1 不做。

实现位置

在 aevatar 的 protocol boundary（/v1/responses ingress）层做分类：

1. 拿到客户端 declared tools 后按表分类
2. Forward 类：原样发给内层 LLM
3. Substitute 类：从 list 删掉客户端版本，注册 aevatar 同名（同 schema）实现给内层 LLM
4. Additive 类：合并进 list 给内层 LLM
5. 不走 "让 LLM 选了再 runtime 拦截" —— 那个会浪费 token 在被吞掉的工具上、且 traces 不一致
6. Forward 类 pending call 必须事件化持久化 —— tool_use 出口前在 run/session actor emit ToolCallEmitted(response_id, call_id, tool_name, schema_hash, arguments, expiry)；客户端回 tool_result 时按 call_id 幂等对账。完整契约见 §13。否则 forward 链路依赖 HTTP stream / in-process 状态，违反 Refactor ChatRuntime to match Harness boundary (#568) — blocks NyxID-fronted Responses API gateway #608 要解决的问题

Trade-off 明说

Substitute 后客户端有些任务可能比 vanilla Codex / Cursor 弱（丢了客户端独有的工具优化）。换来 aevatar 的多会话编排、跨 agent 协作、RAG。把这个 trade-off 写入 product 定位，不假装无损。

6. Long-running tool 续传

previous_response_id 是这条 pipeline 的核心机制。完整契约见 §13。要点：

• 会话状态归 GAgent / run/session actor 拥有，event-sourced（per CLAUDE.md "权威状态 / 单一权威拥有者"）。
• response.id 是不透明 handle（opaque），不从 GAgent id / checkpoint 派生。aevatar 内部维护映射到对应 run/session actor，持久化 ownership facts + lifecycle + pending forwarded calls。
• TTL + 主动 cancel：handle 默认 24h TTL；必须实现 POST /v1/responses/{id}/cancel（OpenAI Responses 标准端点）；过期或 cancel 后即便 token 对也拒绝 resume。
• 每次 resume 重走 scope resolution port（§8）：不是验证 token 有效，是验证 "当前 NyxID delegation token resolve 出的 scope == mapping 里持久化的 scope"。防 token rotation / 跨 scope 越权。
• 跨 origin resume 默认禁止：api_key 起的 response 不能被 channel webhook 续，反之亦然；要跨需要显式 feature gate。
• Tool 跑几分钟 / 几小时都行；run/session actor 的 self-continuation 推进，event 流推回客户端做 keepalive。

这是 #608（ChatRuntime refactor）必须先关掉的关键理由之一 —— 现在的 in-process ChatRuntime 不能跨 HTTP 请求续会话。

7. LLM credential brokering

Aevatar 在所有路径上都不持有 LLM credential（per CLAUDE.md "Aevatar 不保存任何 credential"）。

• 客户端用 NyxID issued API key 进来。
• NyxID 把用户在 NyxID 配置的 provider credential / 订阅额度 inject 给 Aevatar 出 LLM call 时用。
• Aevatar 走 NyxIdLLMProvider（已有），通过 AgentToolRequestContext 拿 access token。

NyxID 已有的 inject_delegation_token flag + X-NyxID-Delegation-Token header 满足这条。

8. 多租户 scope

Aevatar 当前 scope 走 URL /api/scopes/{scopeId}/*。新 inbound（/v1/responses + channel webhook）从 NyxID 进来时，scope 要从 NyxID delegation token 反解。

新加一个 scope resolution port："NyxID user_id → aevatar scope"。两条 inbound（Responses API、channel）复用同一套。

9. NyxID 侧改造清单

v1 几乎零 Rust 代码改动——aevatar 走通用 proxy plane，复用 ornn 已有的全部基础设施。

项	描述	类型
Aevatar 注册为 DownstreamService row	NyxID dashboard 加一条：slug=aevatar, base_url=https://aevatar.example.com, forward_identity_mode=jwt, inject_delegation_token=true。	admin，零代码
aevatar:* permission scopes 加进 role mapping	aevatar:run:invoke 等 scope 进 NyxID RBAC 配置。	admin，零代码
SSE 透传验证（无新代码）	handlers/proxy.rs:2142-2233 已对通用 proxy 做 bytes_stream() 透传 + content-length 剥离 + idle-timeout 看门狗。验证 proxy_stream_idle_timeout_secs 对 long-running 场景配够大。	配置验证
Delegation token rotate / revoke 通知（§13 依赖）	NyxID delegation token 默认 5-min TTL；aevatar response handle TTL 24h。两条路：(a) aevatar 用 POST /api/v1/delegation/refresh 自续；(b) NyxID 加 API key revoke 时 push 通知给 aevatar。待决，可能要小代码。	可选小改

已删：v1 不需要 InternalServiceProvider 类 + /api/v1/llm/aevatar/v1/* 路由（推 v2 nice-to-have）。

部署 gotcha（per #417 根因）：end-user API key 默认 allow_all_services=false，必须把 aevatar 的 service_id 加进 user 的 allowed_service_ids，或用 allow_all_services=true 的 key，否则 handlers/proxy.rs:1045-1066 直接 403。写进 ops README。

10. Aevatar 侧改造清单

改造	描述
#608 — ChatRuntime refactor（block 项）	必须先做。把 ChatRuntime 解构为 GAgent 内的 tool loop + StreamProxy boundary。
/v1/responses ingress（StreamProxy 实现形态）	协议适配：Responses 入 → GAgent message；GAgent event → Responses SSE。不叫 Runtime / Gateway，per #568。
Inbound auth middleware	per §14 Inbound Auth Contract：base64url decode X-NyxID-Identity-Token（不验签）、scalar header fallback、permission gating、outbound SA-mode token cache。复用 ornn nyxidAuth.ts 模式。
Channel webhook inbound endpoint	NyxID channel-relay 来件接收 + HMAC/JWT 验证；和 /v1/responses 复用 scope resolution。
Tool 处置层	实现客户端 declared tools 的 forward / substitute / additive 分类，per §5。
Aevatar additive tools 注册	aevatar_workflow / aevatar_script / aevatar_delegate / aevatar_memory_query。
Scope resolution port	"NyxID user_id → aevatar scope"，两条 inbound 共用。
Substitute 类 tool 实现	TodoWrite（agent-scoped 持久化）、Task（GAgent topology）、WebFetch / WebSearch（出 trace 入 RAG）。
previous_response_id 续传 + opaque handle	per §13 Session Continuation Contract：opaque response.id → run/session actor 持久化 ownership + lifecycle + pending forwarded calls；resume 每次重走 scope resolution，跨 origin 默认禁止。
Forwarded tool continuation contract	per §5 + §13：forwarded tool_use 在 run/session actor 事件化持久化 (call_id, tool_name, schema_hash, arguments, status, expiry)；客户端 tool_result 按 call_id 幂等对账 + self-message 继续 LLM run。
POST /v1/responses/{id}/cancel 端点	per §13：用户主动取消，标 response 所有 pending forwarded calls 为 cancelled。

11. v1 范围 / 非目标

• In scope：v1 inbound 只 /v1/responses；Anthropic Messages 不支持。
• In scope：v1 仅 substitute 表中"必须"和"应该"项。
• In scope：v1 LLM provider 走 NyxID broker。
• In scope：§13 Session Continuation Contract 所有"必须实现"不变式（opaque handle、TTL、cancel 端点、re-auth、forwarded tool 持久化、schema_hash drift 检测、idempotency 等）。
• Out of scope：Aevatar 直连 LLM（永久 out）。
• Out of scope：MCP brokered substitution（v2）。
• Out of scope：Workflow / Script / Sub-agent 各自的内部设计（走各自 issue）。

12. 公开问题

1. 客户端 tool 命名空间冲突：v1 简单策略——additive tools aevatar_ 前缀 hard-coded 避开冲突。是否够？需不需要更动态的命名空间约定？
2. Substitute schema 不兼容：客户端 TodoWrite schema 和 aevatar 版本 schema 不一致时？默认 aevatar 版本 schema 覆盖；记录 schema diff 警告。需要 review。
3. Streaming keepalive 粒度：Long-running tool 期间 SSE 上发什么 event 类型保持连接？OpenAI Responses 已有 response.in_progress 等；v1 follow 已定义 event，不发明新类型。
4. NyxID InternalServiceProvider 谁来实现：跨仓库改动，需要 NyxID 那边对应排期。

13. Session Continuation Contract

源自 comment 16877401（opaque response.id + re-auth）与 16877407（forwarded tool 持久化）；两条其实是同一 contract 的两个侧面。本节为 §5（forward）/ §6（previous_response_id）/ §8（scope resolution）的共同规范基础。

Contract shape

opaque response_id（例 resp_<random>） → run/session actor（event-sourced）
    ├── ownership facts
    │     ├── scope_id
    │     ├── owner_subject              -- 主体身份（NyxID user 或 channel sender，按 origin 解）
    │     ├── origin_kind                -- api_key | channel
    │     └── channel (optional)         -- channel id（仅 channel origin）
    ├── lifecycle
    │     ├── created_at
    │     ├── ttl                        -- 默认 24h
    │     └── cancelled_at (nullable)
    └── pending forwarded calls (N parallel)
          { call_id, tool_name, schema_hash, arguments, status, expiry }
              status: pending → received → resolved | expired | cancelled

Resume 流程（每次 previous_response_id 请求）

1. opaque response_id lookup → 对应 run/session actor
2. re-resolve current scope via §8 scope resolution port → 必须 == actor.scope_id（不是验证 token 有效，是验证 resolve 出的 scope 匹配）
3. 验证 origin_kind 与本次请求 ingress 一致；跨 origin 默认拒绝
4. for each tool_result：match call_id → schema_hash check → 状态机推进 pending → received
5. self-message 触发 LLM run 继续，处理已 received 的 tool results（支持 partial / out-of-order）
6. 发新 event stream（response_id 复用同一个直到 TTL 到期）

不变式（v1 必须实现）

• opaque handle：纯随机（base32 / UUID），禁止从 GAgent id / checkpoint 派生
• TTL + 主动 cancel：handle TTL 默认 24h；POST /v1/responses/{id}/cancel 必须实现
• 每次 resume 重走 scope resolution：防 token rotation 越权
• 跨 origin resume 默认禁止：除非显式 feature gate 开启
• forwarded tool 持久化：所有 forward 类 tool_use 出口前必须在 actor 状态里 emit ToolCallEmitted 事件
• schema_hash 检测 drift：客户端回的 tool_result schema 不匹配当时 emit → reject，不静默接受
• partial / out-of-order resolution：parallel tool calls 允许乱序部分返回；actor 收到一个就推进
• TTL 到期合成 error tool_result：actor 合成 {"error":"tool_call_expired","call_id":...} 喂回 LLM graceful 收尾
• Idempotency：同 call_id 二次 tool_result 返回已 resolved 结果，不重走 LLM
• 客户端 cancel：触发 cancel 端点时 actor 标所有 pending 为 cancelled

与 #608 的关系

#608 把 ChatRuntime 抽掉之后，跨 HTTP 请求的 continuation 事实必须 actor-owned + event-sourced。本 contract 是 #608 在协议入口的具象化——forwarded tool 链路如果不实现本 contract，等于 ChatRuntime 影子复活。本 contract 与 #608 priority 等同。

NyxID 侧依赖

• delegation token TTL + revoke notification（§9 一项）：NyxID 应在用户 delegation token 撤销时主动通知 aevatar；aevatar 收到后 cancel 受影响的 active response handles。
• scope resolution port 双输入：channel callback JWT（aud=channel-relay/reply，单次性）与 delegation token（长期）形态不同；§8 scope resolution port 必须吃两种输入，且 resolve 出的 owner_subject 语义明确（channel sender ≠ channel bot owner）。

14. Aevatar Inbound Auth Contract（per ornn 模式）

NyxID 接入身份契约——aevatar 必须按 ornn 的 nyxidAuth.ts 模式实现：

1. 主：X-NyxID-Identity-Token (JWT)，base64url-decode middle segment，不验签（信任 NyxID proxy，proxy 已 verify），抽 sub / email / name / roles[] / permissions[]
2. fallback：JWT 缺时读 X-NyxID-User-Id / X-NyxID-User-Email / X-NyxID-User-Name scalar headers；此时 permissions 空，所有 requirePermission 都 403
3. bearer 旁路：Authorization: Bearer <user_nyxid_token> 用于 aevatar 反向调 NyxID as the user；NyxID 默认不转发，需 binding 开 forward_access_token=true
4. permission gating：纯字符串数组 claim 检查，不查 DB，不回调 NyxID
5. outbound SA-mode：aevatar 反向调 NyxID as itself 用 OAuth2 client_credentials + token 缓存（到 expires_in - 60s）。credentials cluster-wide 持久化（不能 node-local，per feedback_aevatar_secrets_store_node_local）
6. SSE headers：Content-Type: text/event-stream + Cache-Control: no-cache, no-transform + X-Accel-Buffering: no + 每 ~15s : keepalive\n\n 心跳
7. 登记：aevatar 不自动 register 进 NyxID；暴露 AEVATAR_PUBLIC_ORIGIN env 给 ops。启动时 log warning if 请求带 non-empty roles[] 但 permissions[] 空（NyxID side forward_identity_mode=headers 而非 jwt 的 smell）

部署约束：信任不验签的前提是 aevatar 只通过 NyxID proxy 入流，直接外部访问被网络层隔离。

15. Aevatar 自验证计划（不依赖 NyxID 完成的递进验证）

Phase A — 完全不依赖 NyxID（最关键，先做）

目标：验证 /v1/responses ingress + §13 contract + tool 处理 + LLM 出口都自洽。

• deploy：本地 aevatar localhost:5000
• inbound 模拟：curl 直接打，手 craft X-NyxID-Identity-Token（任意合法 JWT 形状，middle segment base64url 含 {"sub":"test_user_1","permissions":["aevatar:run:invoke"]}，header / signature 可乱填——aevatar 不验签所以能用）
• LLM 出口：临时 swap NyxIdLLMProvider → MEAILLMProvider（已有，直连 OpenAI），dev 自己的 OpenAI key

必跑用例：

• POST /v1/responses 基础推理 + SSE 返回
• Tool forward：aevatar emit tool_use，client 模拟回 tool_result，run 继续
• §13 跨请求 continuation：T1 起 response → 收 tool_use → HTTP 断 → T2 用 previous_response_id + tool_result 续，验证 actor 从 event store 重建 pending call
• POST /v1/responses/{id}/cancel 端点
• TTL 过期：actor 合成 tool_call_expired 错误喂回 LLM
• Idempotency：同 call_id 二次 tool_result 返回已 resolved 结果
• schema_hash drift：改 schema 的 tool_result 被 reject
• 并行 + 乱序 + 部分 tool_result resolution

Phase A 过 = #608 commit criterion 满足——跨 HTTP 边界事实归 actor、不靠 in-process state。这步过了 #609 核心架构立住。

Phase B — 假 NyxID 前置

目标：验证 identity propagation 契约 + scope resolution port 双输入。

• stub HTTP service 模拟 NyxID /api/v1/proxy/s/aevatar/*：接 raw → 注入 X-NyxID-Identity-Token + X-NyxID-Delegation-Token → 转发 aevatar
• Codex CLI 配 OPENAI_BASE_URL=http://stub-nyxid/api/v1/proxy/s/aevatar/v1
• 验证：identity 解析、scope resolution（§8 port）、resume re-auth 拒绝跨身份、channel webhook 通过同 port 复用
• aevatar 不验签所以 stub 不需要 JWKS

Phase C — 真 NyxID dev 实例（端到端）

• 起 NyxID dev，dashboard 注册 aevatar DownstreamService（slug aevatar-staging）
• 测试 API key 配 allowed_service_ids 含 aevatar
• Codex CLI 直接接 NyxID base URL
• 跑 Phase A 全部用例 + 加：
  • delegation token rotate → aevatar 受影响 response handle 行为
  • LLM 出口走 NyxID broker（NyxIdLLMProvider 拿 inject 的 token 反向调 /api/v1/llm/gateway/v1/*）
  • SSE long-running 实测 NyxID proxy_stream_idle_timeout_secs 够大

Phase A 是真正卡 #608 + #609 自洽性的关卡。B 和 C 是工程胶水验证。

相关

• discussion [Aevatar Harness] 核心能力边界讨论 #568 — Aevatar Harness boundary（platform 原语、StreamProxy、LLM 降级为 connector）
• issue Refactor ChatRuntime to match Harness boundary (#568) — blocks NyxID-fronted Responses API gateway #608 — ChatRuntime refactor（本产品 block 项）
• issue 将 ChatRuntime / ChannelLlmReplyInboxRuntime 收敛为 actor-owned Agent Continuation #596 — Run-actor continuation（continuation 模型有可复用部分）
• issue RFC: 统一外部长连接流为 actor 一等抽象（SessionStreamGAgent 方向）— 求团队讨论与互评 #560 — StreamSessionGAgent RFC（StreamProxy 候选实现）

[eanzhao]

补一条对 §2 "Claude Code v2 通过本地 adapter（Messages → Responses 翻译）接入" 这条措辞的调研——晚 2025 / 早 2026 工业现状对我们的判断有几个反馈点。

现状

没有大牌网关把 Messages-ingress → Responses-upstream 这条链路做成熟。 最常推荐的 musistudio/claude-code-router（34k★）issue #1061 明确不支持 Responses upstream。LiteLLM 是唯一公布参数映射表（/docs/anthropic_unified/messages_to_responses_mapping）的网关，但 SSE 事件映射 + previous_response_id 续传都没文档。

公开最干净的两个完整实现是小项目：

项目	关键
raine/claude-code-proxy（87★，v0.0.10 May 2026）	唯一公开的 Messages → Responses 完整翻译器；"reducer: typed events" SSE 重组层；动机是 Claude Code 借用 ChatGPT 订阅过 Codex 后端
CaddyGlow/ccproxy-api（239★，v0.2.10 May 2026）	唯一把 Responses 当一等 surface 暴露的 proxy，同一服务多协议 ingress（ChatComp / Responses / Messages）

所有公共桥都不用 previous_response_id，每轮重发整段对话。 物理硬限——Claude Code 自己 stateless 重发 history，桥层无语义来源可以伪造 previous_response_id。

Anthropic 没有官方多 provider 计划。 唯一官方 OpenAI 集成是反向的——openai/codex-plugin-cc MCP plugin，让 Claude Code 把 Codex 当 tool 调，不是当后端。

对本 RFC 的 4 个实际含义

1. §2 "本地 adapter" 措辞低估了工程量。 最接近可复用的轮子是 raine 的 reducer 代码（MIT，活跃）+ LiteLLM 的参数映射表（已公开），两个合起来才覆盖一个完整桥。建议把 v2 那条改成："v2 通过本地 adapter（Messages → Responses 翻译）接入；工程量参考 raine/claude-code-proxy 量级，重点是 SSE 事件状态机 + tool content 翻译"。

2. §6 long-running tool 续传对 Claude Code 路径物理上不可用。 Claude Code 是 stateless 重发整段历史，没有 client-side 的"我还要继续上次的 response"语义可以传到桥。意味着：

• v1（Codex / Cursor / Opencode）享有 previous_response_id 续传
• v2（Claude Code）只能跑短任务；long-running tool 在 Claude Code 路径下不可用

建议在 §6 末尾加一句："Claude Code 路径（v2）由于客户端 stateless 重发 history，无续传语义来源；long-running tool 仅对 Codex / Cursor / Opencode 可用。"

3. v2 备选路径：aevatar 直接吃 /v1/messages（不是用户本机装 adapter）。ccproxy-api 已证明同一服务可以多协议 ingress。代价：aevatar 自己背 SSE 翻译 + tool content 翻译。收益：Claude Code 用户最干净的 setup（一行 ANTHROPIC_BASE_URL，不装本机进程）。建议加进 §12 公开问题——"v2 Claude Code 接入方式：本地 adapter vs aevatar 自己暴露 /v1/messages ingress"。

4. MCP plugin 是完全不同的接入形态。 codex-plugin-cc 模式下 Claude Code 主体不变，aevatar 注册为 MCP server 当 tool 用。绕开协议翻译，但放弃"aevatar 是模型"的产品定位——变成"aevatar 是 Claude Code 的子工具"。和本 RFC 主线冲突，作为 sidecar 形态心里备份就行，不进 v1 / v2 范围。

一条 honest caveat（值得抄进 v2 范围）

"Claude Code's harness — system prompts, tool-use patterns, agent loops — is built for Claude models. Agentic workflows, multi-step tool calls, and complex reasoning chains may behave differently. It works, but don't expect parity." — prabal.ca, 2026-04-01

即便协议翻译 100% 对，Claude Code 的 harness（系统 prompt / loop 时序 / tool 使用模式）是为 Claude 模型调出来的。aevatar 当"模型"接进去时 semantic layer 未必匹配。v2 spec 应明确："v2 Claude Code 支持 = 可用，不承诺 parity。"

调研来源

• musistudio/claude-code-router#1061
• raine/claude-code-proxy
• CaddyGlow/ccproxy-api
• docs.litellm.ai/docs/anthropic_unified/messages_to_responses_mapping
• prabal.ca/posts/claude-code-chatgpt-subscription/
• community.openai.com/t/introducing-codex-plugin-for-claude-code/1378186

[eanzhao]

response.id 和 previous_response_id 建议不要直接暴露可推导的 GAgent id + checkpoint。client-visible id 最好是 opaque handle；Aevatar 内部再维护 response_id -> scope_id / actor_id / checkpoint / state_version / owner_subject / channel 的映射。

resume 时也要用当前 NyxID delegation token 重新校验同 scope / 同主体是否有权恢复。否则只要猜到或泄露了 response id，就可能跨 scope 续会话。这里和 §8 的 scope resolution 是同一个问题：NyxID user、channel sender、bot owner、Aevatar scope、target actor 需要明确绑定规则，不能默认混成同一个身份语义。

[loning]

Messages-ingress → Responses-upstream, 我们不做这个.

上游Responses, 我们就输出 Responses

上游Messages-ingress, 我们就输出 Messages-ingress

[eanzhao]

§5 的 default forward 还需要一个正式的 external-tool continuation contract。LLM 选择 forwarded tool 后，Aevatar 不能只把 tool_use 透传给客户端再等下个 HTTP 请求；至少要在 run/session actor 里记录 pending call 的非 secret 事实：response_id / call_id / tool_name / schema_hash / arguments / status / expiry。

客户端回 tool_result 时按 call_id 做幂等对账，然后由 self-message 继续推进。否则 forwarded tool 这条链路仍然依赖 HTTP stream / in-process 状态承载事实，和 #608 要解决的跨请求 continuation 问题会撞上。