Agmente：移动端 Agent 客户端的双协议架构剖析
ACP + Codex app-server | iOS SwiftUI | 断线恢复与多会话管理
导语：Agmente 的定位非常明确：它不是 agent 运行时，而是一个移动端"协议客户端"。核心目标是把 ACP 与 Codex 两套协议统一在 iOS 上，让用户能在手机上看见工具调用、会话历史与断线恢复。
核心要点：它解决了什么问题
多协议统一
通过 ServerViewModelProtocol 抽象 ACP 与 Codex，两套协议在 UI 层共享统一入口，运行期自动识别切换。
移动端断线恢复
X-Client-Id + stdio-to-ws --persist 配合，解决 iOS 后台切换导致的短线断连问题。
会话与工具可视化
流式消息、tool call、审批请求被结构化为 UI 组件，形成"agent 工具执行现场"的可视化日志。
本地缓存兜底
对不支持 session/list 的服务端，通过 Core Data 缓存会话与消息，实现最小可用体验。
架构速览
AppViewModel（过载核心）
负责连接、初始化、缓存、协议切换、日志与状态机；体量大、责任集中，是当前最大的技术债。
ServerViewModel / CodexServerViewModel
分别映射 ACP 的 session/* 与 Codex 的 thread/turn/* 语义，但存在大量重复逻辑。
SessionStorage（Core Data）
保存 server/session/message 与 MRU 工作目录，为无 session/list 的服务端兜底。
AppServerService（Codex RPC）
JSON-RPC 请求管理与 pending continuation 处理，当前缺少超时与指标。
关键数据流（简化版）
- 连接 connect → initialize → 探测 session/list / session/load 能力 → 切换到 ACP/Codex 视图模型。
- 会话 ACP 用 session/new（placeholder 迁移）；Codex 用 thread/start + turn/start。
- 恢复 ACP: session/load/resume；Codex: thread/resume → 重建消息树。
- 缓存 不支持 session/list 时落盘；支持时以服务端为准。
主要风险与技术债
AppViewModel 过度膨胀
职责过多，难以测试与演进，回归风险高。
重复逻辑
ACP/Codex 的 session 管理重复，后续行为可能漂移。
并发安全
@unchecked Sendable 与 delegate 跨线程回调存在隐患。
文档与实现偏差
文档称 capability 默认 on，但代码默认 false。
"这是一个移动端的协议客户端，不是运行时框架。把协议一致性和断线恢复做到极致，就是它的护城河。"
工程建议（精简版）
- 01 引入显式会话状态机（draft/creating/materialized/loading/resuming/ready），统一处理 placeholder 与竞态。
-
02
每服务器独立连接管理器，消除共享
ACPClientManager的串扰。 - 03 拆 AppViewModel：ServerRegistry / ConnectionOrchestrator / SessionRecoveryCoordinator。
- 04 AppServerService 增加请求级 timeout + metrics（pending 数、超时数、平均 RTT）。
- 05 能力矩阵契约测试（session/list/load/resume + Codex thread/resume + 多 cwd 合并）。