agentic_huge_data_base / wiki
页面 jcode · 13.1 JCodeKit SDK 与 iOS App·DeepWiki 中文全文译文
DeepWiki 中文译文 / jcode / 13.1

13.1 · JCodeKit SDK 与 iOS App（JCodeKit SDK and iOS App）

代理式研究运行时 · 聚焦本章的模块关系、源码依据与实现要点。

项目jcode 章节13.1 状态全文译文 模块界面与交互、接口与服务契约、测试、发布与运维、工作流与编排
项目要点页2.5 参考项目 项目章节目录jcode DeepWiki 原始章节JCodeKit SDK and iOS App 上一章13 下一章13.2
源码线索
  • codemagic.yaml
  • ios/Sources/JCodeKit/Connection.swift
  • ios/Sources/JCodeKit/CredentialStore.swift
  • ios/Sources/JCodeKit/JCodeClient.swift
  • ios/Sources/JCodeKit/Protocol.swift
  • ios/Sources/JCodeMobile/AppModel.swift
  • ios/Sources/JCodeMobile/Assets.xcassets/AppIcon.appiconset/AppIcon.png
  • ios/Sources/JCodeMobile/Assets.xcassets/AppIcon.appiconset/Contents.json
  • ios/Sources/JCodeMobile/Assets.xcassets/Contents.json
  • ios/Sources/JCodeMobile/ContentView.swift
模块标签
  • 界面与交互
  • 接口与服务契约
  • 测试、发布与运维
  • 工作流与编排
  • 认证、权限与安全

章节正文

JCodeKit SDK 与 iOS App

原始 DeepWiki 页面https://deepwiki.com/1jehuang/jcode/13.1-jcodekit-sdk-and-ios-app

JCodeKit SDK 与 iOS 应用

相关源文件

本章引用的主要源码文件：

  • codemagic.yaml
  • ios/Sources/JCodeKit/Connection.swift
  • ios/Sources/JCodeKit/CredentialStore.swift
  • ios/Sources/JCodeKit/JCodeClient.swift
  • ios/Sources/JCodeKit/Protocol.swift
  • ios/Sources/JCodeMobile/AppModel.swift
  • ios/Sources/JCodeMobile/Assets.xcassets/AppIcon.appiconset/AppIcon.png
  • ios/Sources/JCodeMobile/Assets.xcassets/AppIcon.appiconset/Contents.json
  • ios/Sources/JCodeMobile/Assets.xcassets/Contents.json
  • ios/Sources/JCodeMobile/ContentView.swift
  • ios/Sources/JCodeMobile/ImagePickerView.swift
  • ios/Sources/JCodeMobile/Info.plist
  • ios/Sources/JCodeMobile/JCodeMobile.entitlements
  • ios/Sources/JCodeMobile/JCodeMobileApp.swift
  • ios/Sources/JCodeMobile/MarkdownText.swift
  • ios/Sources/JCodeMobile/QRScannerView.swift
  • ios/Sources/JCodeMobile/SpeechRecognizer.swift
  • ios/Sources/JCodeMobile/Theme.swift
  • ios/Tests/JCodeKitTests/ClientTests.swift
  • ios/Tests/JCodeKitTests/ProtocolTests.swift
  • ios/project.yml
  • src/gateway.rs
  • src/gateway/auth.rs
  • src/gateway/registry.rs

JCode iOS 生态系统由 JCodeKit Swift SDK 和一个原生 SwiftUI 应用组成。SDK 提供了一个高级异步接口，用于通过 WebSocket 网关与 jcode 服务器交互，而 iOS 应用则实现了一个针对移动端优化的聊天界面，支持基于二维码的配对、语音听写和图片附件等功能。

JCodeKit Swift SDK

JCodeKit 是面向移动端和 macOS 客户端的基础框架。它将基于换行符分隔的 JSON 协议抽象为 Swift 原生的 async/await 模式和 AsyncStream 事件。

核心组件
  • JCodeConnection：基于 Actor 的 URLSessionWebSocketTask 封装器。它管理底层套接字的生命周期、认证请求头和保活 Ping 包 ios/Sources/JCodeKit/Connection.swift:3-27。它使用 20 秒的保活间隔来维持连接 ios/Sources/JCodeKit/Connection.swift:27。
  • JCodeClient：开发者的主要入口点。它编排连接，并将原始的 ServerEvent 枚举转换为委托回调 ios/Sources/JCodeKit/JCodeClient.swift:119-143。
  • CredentialStore：管理 ServerCredential 对象的安全存储。
  • 协议类型：jcode 请求/事件模式的 Swift 实现，包括 Request 枚举 ios/Sources/JCodeKit/Protocol.swift:5-22 和 ServerEvent 枚举 ios/Sources/JCodeKit/Protocol.swift:121-150。
数据流：SDK 事件处理

SDK 使用分层事件处理模型，原始套接字字符串被解码为 ServerEvent，然后通过 JCodeClientDelegate 进行分发。

标题：JCodeKit 事件管线

jcode · 数据流：SDK 事件处理 · 图 1
jcode · 数据流：SDK 事件处理 · 图 1

来源：ios/Sources/JCodeKit/Connection.swift:137-144、ios/Sources/JCodeKit/Connection.swift:196-210、ios/Sources/JCodeKit/JCodeClient.swift:184-201、ios/Sources/JCodeKit/JCodeClient.swift:203-220

iOS 应用架构

iOS 应用使用 SwiftUI 构建，并采用观察者模式，以 AppModel 作为中央状态协调器。

AppModel 状态管理

AppModel 管理连接生命周期、消息历史记录和服务器发现。

  • 配对：通过 pairAndSave() 逻辑处理配对，与 PairingClient 通信，将 6 位数字码交换为永久的 auth_token ios/Sources/JCodeMobile/AppModel.swift:175-209。
  • 连接生命周期：实现指数退避重连策略，并跟踪 connectionGeneration 以防止处理过期事件 ios/Sources/JCodeMobile/AppModel.swift:89-93。
  • 消息处理：维护一个 ChatEntry 对象列表，支持文本和工具调用的增量流式处理 ios/Sources/JCodeMobile/AppModel.swift:17-41。
UI 组件与功能
  • MarkdownText：一个自定义解析器，使用 SwiftUI 的 Text 和 ScrollView 将 AI 响应渲染为块（段落、代码、标题、列表）ios/Sources/JCodeMobile/MarkdownText.swift:3-15, 85-91。
  • QRScannerView：使用 AVFoundation 和 QRScannerController 扫描 CLI 的 jcode pair 命令生成的 jcode://pair URI ios/Sources/JCodeMobile/QRScannerView.swift:7-25, 136-160。
  • 语音和图片支持：集成 SFSpeechRecognizer 实现免提听写，以及 PhotosUI 用于为查询附加上下文 ios/Sources/JCodeMobile/Info.plist:47-54。
实体映射：UI 到 SDK

标题：移动端实体映射

jcode · 实体映射：UI 到 SDK · 图 2
jcode · 实体映射：UI 到 SDK · 图 2

来源：ios/Sources/JCodeMobile/ContentView.swift:10-29、ios/Sources/JCodeMobile/AppModel.swift:10-15、ios/Sources/JCodeKit/JCodeClient.swift:119-124、ios/Sources/JCodeKit/Protocol.swift:5-10

WebSocket 网关（服务端）

服务器通过 WebSocket 网关（默认端口 7643）支持移动端连接。

  • 架构：网关通过 TCP 接受 WebSocket 连接，并将其桥接到虚拟的 UnixStream 对 src/gateway.rs:8-13。
  • 认证：支持 Authorization: Bearer <token> 请求头或 ?token= 查询参数，用于旧版/浏览器客户端 src/gateway.rs:145-160。
  • 设备注册表：根据持久化的 DeviceRegistry 验证令牌 src/gateway.rs:187-195。

标题：服务端网关桥接

jcode · WebSocket 网关（服务端） · 图 3
jcode · WebSocket 网关（服务端） · 图 3

来源：src/gateway.rs:8-13、src/gateway.rs:71-80、src/gateway.rs:139-170

配对与连接流程

配对流程通过二维码将本地桌面环境与移动设备连接起来。

步骤操作代码实体
1在 PC 上运行 jcode pairCLI（服务器网关）
2使用 iPhone 扫描二维码QRScannerView ios/Sources/JCodeMobile/QRScannerView.swift:20-25
3解析 jcode://pair?host=...&code=...parseJCodeURI ios/Sources/JCodeMobile/QRScannerView.swift:94-114
4将代码交换为令牌PairingClient.pair() ios/Sources/JCodeMobile/AppModel.swift:201-202
5持久化凭证CredentialStore.save()
6建立 WebSocket 连接JCodeConnection.connect() ios/Sources/JCodeKit/Connection.swift:45-66

构建与持续集成与持续交付管线

该项目使用 XcodeGen 生成项目文件，并使用 Codemagic 进行持续集成。

Codemagic 工作流（ios-testflight）

该管线自动化了从源代码到 TestFlight 分发的整个过程。

  1. 环境：使用搭载 Xcode 16.2 的 mac_mini_m2 环境 codemagic.yaml:5, 15。
  2. 项目生成：运行 xcodegen generate，根据 project.yml 生成 JCodeMobile.xcodeproj codemagic.yaml:31-33。
  3. 代码签名：初始化钥匙串，并使用 BUNDLE_ID com.jcode.mobile 从 App Store Connect 获取签名配置文件 codemagic.yaml:12, 39-46。
  4. 构建：使用 Release 配置编译用于分发的 .ipa 文件 codemagic.yaml:50-57。
  5. 发布：自动将构建提交到 TestFlight 的“内部测试人员”Beta 组 codemagic.yaml:61-66。

来源：codemagic.yaml:1-67、ios/project.yml:1-43