jcode iOS应用纯Swift架构解析薄客户端服务端协议单一事实源【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcodejcode 是目前内存占用最极致的 AI 编程代理the most RAM efficient harness它运行在你自己的机器上驱动 LLM、工具、Git 与文件操作。而 ios/ 目录下的 iOS 应用则是这套系统的遥控器一部纯 Swift 编写的薄客户端扫码配对后就能远程查看对话、发送消息、中途打断。本文将带你解析这套架构的三个核心决策——为什么放弃 Rust 共享核心、薄客户端如何分层、以及服务端协议如何成为单一事实源。一个产品决策为什么是纯 Swift 而不是共享 Rust 核心早期原型曾尝试 Rust-mobile-core 方向但 v2 重建时彻底放弃写进了架构决策文档The app is a thin client over an existing, server-owned protocol.理由很直接值得共享的行为协议、状态机、工具执行已经全部在服务端了。如果再把 Rust 核心编进手机等于把服务端协议第三次重复还要搭 FFI 桥接、自定义渲染器和一套仿真器——成本远大于收益。于是职责被清晰地切开了Swift 拥有客户端SwiftUI 做界面Swift 6 并发actor、Observable管状态️服务端协议是唯一真相Swift 侧的编解码器用真实线上抓取的 JSON 夹具做测试协议漂移会直接让测试失败可测试性靠分层而非设备视图层以下全部能在 macOS 上swift test跑完不需要真机iOS 应用本身从不直接和 LLM 提供商通信——所有重活LLM 调用、工具、Git、文件、MCP都留在服务端。手机只负责渲染对话和驱动会话。上方是 iOS 应用远程驱动的 jcode 服务端 Agent 界面三层架构JCodeKit 内核 JCodeMobile 外壳 测试层整个工程是一个 SPM 包Package.swift在 ios/ 下分成三部分1️⃣ JCodeKit —— 无平台的客户端内核位于 Sources/JCodeKit/禁止 import UIKit/SwiftUI必须在 macOS 上能编译这样才能被无头测试文件职责Gateway.swift网关端点/health、/pair、/ws三个地址Pairing.swift配对码 → 长效 token 的交换Wire.swift请求/事件编解码器WebSocket 上的 NDJSONTransport.swiftWebSocket 抽象协议 URLSession 实现Connection.swiftactor连接、鉴权、指数退避重连SessionReducer.swift纯函数状态机事件 → 对话/应用状态CredentialStore.swiftKeychain 凭证存储其中SessionReducer是最关键的设计它是一个纯函数(State, ServerEvent) - State所有流式输出、工具调用生命周期、会话切换的边界情况都在这里单元测试取代了旧版 Rust 仿真器的角色。2️⃣ JCodeMobile —— SwiftUI 应用外壳位于 Sources/JCodeMobile/包含配对扫码QRScannerView.swift、聊天、工具调用卡片ToolCallCard.swift、会话列表等视图。规则很严格视图里不允许有任何协议或状态迁移逻辑AppModel.swift 只负责转发用户动作、把SessionReducer的输出发布给视图。3️⃣ 测试与构建Tests/JCodeKitTests/在 macOS 上跑swift test——编解码器夹具、Reducer 流式场景、配对客户端、连接 actor 全部无设备可测project.ymlXcodeGen 规范CI 用xcodebuild保持 UI 可编译配对与连接从扫二维码到 WebSocketiOS 应用背后是运行在自有机器上的 jcode 服务端承载全部 Agent 能力配对流程设计得既简单又安全在服务器侧执行jcode pair生成 6 位配对码5 分钟有效和二维码内容为jcode://pair?hostHportPcodeC手机扫二维码或手输 host/port/码Pairing.swift 向POST /pair提交{code, device_id, device_name}服务端返回长效 token服务端只存哈希客户端把它连同服务器信息一起存入KeychainCredentialStore.swift模拟器无 Keychain 权限时自动降级到文件ws://host:7643/ws升级成 WebSocket携带Authorization: Bearer token连接由 Connection.swift 中的 actor 托管细节值得新手学习指数退避重连基础延迟翻倍递增、封顶 30 秒若服务端主动宣告 reload则跳过退避快速重连401 即终止token 被吊销时用同一 token 重试永远不会成功直接提示重新配对而不是无限退避请求 ID 自增分配响应按 ID 对应协议单一事实源Swift 代码与 Rust 服务端如何不漂移这是整篇文章的题眼。服务端的协议定义在 Rust 侧crates/jcode-protocol/src/wire.rsiOS 的 Wire.swift 在注释中直接声明Wire format mirrorscrates/jcode-protocol/src/wire.rs#[serde(tag type)], snake_case tags也就是说Rust 服务端是唯一事实源Swift 只是它的镜像。iOS 只建模了手机用到的请求子集message、cancel、soft_interrupt、get_history、resume_session、set_model等 13 种服务端会忽略不认识的字段。前向兼容有三道保险全部体现在 Wire.swift 里未知事件归.unknown新版服务端发出的新事件旧版 App 直接忽略而不是崩溃宽容的 JSON 访问器JSONObject缺字段给默认值app must never crash on a server that is newer or older than itself夹具测试WireTests.swift 用真实服务端抓取的 JSON 做往返测试任何漂移都会让swift test失败写在最后jcode 的 iOS 应用给给终端工具做移动端提供了一个教科书式的答案别在客户端重复造协议——服务端协议即契约客户端只做镜像️分层换可测试性——内核不碰 UIKitswift test在 macOS 上覆盖全部行为逻辑凭证进 Keychain、token 服务端只存哈希——配对码 5 分钟过期长效 token 可吊销如果你想动手阅读源码建议从 docs/IOS_APP.md 的架构说明开始再到 Wire.swift 和 Connection.swift 看协议与连接的实际实现。薄客户端不薄——薄的是代码厚的是把边界切得足够干净。【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考