13.2 · Mobile Simulator 与核心协议（Mobile Simulator and Core Protocol）

Mobile Simulator 与核心协议（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/1jehuang/jcode/13.2-mobile-simulator-and-core-protocol

翻译时间：2026-05-27T08:45:27.839Z

翻译模型：deepseek-chat

原文字符数：8917

项目：jcode (jcode)

---

移动端模拟器与核心协议

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• crates/jcode-desktop/src/desktop_prefs.rs
• crates/jcode-desktop/src/render_helpers.rs
• crates/jcode-desktop/src/workspace_tests.rs
• crates/jcode-mobile-core/Cargo.toml
• crates/jcode-mobile-core/src/lib.rs
• crates/jcode-mobile-core/src/lib_tests.rs
• crates/jcode-mobile-core/src/protocol.rs
• crates/jcode-mobile-core/src/scenario.rs
• crates/jcode-mobile-core/src/visual.rs
• crates/jcode-mobile-core/tests/golden/pairing_ready_chat_send.json
• crates/jcode-mobile-sim/Cargo.toml
• crates/jcode-mobile-sim/src/gpu_preview.rs
• crates/jcode-mobile-sim/src/lib.rs
• crates/jcode-mobile-sim/src/lib_tests.rs
• crates/jcode-mobile-sim/src/main.rs
• docs/MOBILE_SIMULATOR_WORKFLOW.md
• ios/FUTURE_OWNERSHIP_BACKLOG.md
• ios/SIMULATOR_FOUNDATION.md
• scripts/mobile_simulator_smoke.sh
• scripts/mobile_simulator_tester.sh
• src/stdin_detect.rs

jcode 移动端基础设施提供了一个 Linux 原生、"Rust 优先"的模拟环境，以及一个标准化的通信协议，用于 jcode 移动端应用。该架构支持确定性测试、AI 代理驱动的开发，并在核心开发循环中无需 macOS 或物理硬件即可在模拟器和原生 iOS 宿主之间共享逻辑 ios/SIMULATOR_FOUNDATION.md:13-24。

核心架构理念

该系统采用 SIMULATOR_FOUNDATION 方法，其中移动端应用的状态、逻辑和视觉定义由 Rust crate 拥有 ios/SIMULATOR_FOUNDATION.md:19-30。iOS 应用被设计为一个轻量级的平台外壳，负责承载界面并将输入转发给 Rust 核心 ios/SIMULATOR_FOUNDATION.md:106-108。

组件关系图

下图将概念性的"移动端应用"空间与实现它的具体代码实体连接起来。

graph TD
    subgraph "移动端核心（共享逻辑）"
        CORE["jcode-mobile-core"]
        STATE["SimulatorState (lib.rs)"]
        STORE["SimulatorStore (lib.rs)"]
        PROTO["MobileRequest / MobileServerEvent (protocol.rs)"]
    end

    subgraph "Linux 模拟环境"
        SIM["jcode-mobile-sim (守护进程)"]
        GPU["gpu_preview.rs (wgpu/winit)"]
        SOCK["Unix 套接字自动化"]
        CLI["main.rs (CLI 命令)"]
    end

    subgraph "平台宿主"
        IOS["iOS Swift 外壳 (JCodeKit)"]
        TEST["mobile_simulator_tester.sh"]
    end

    CORE --> SIM
    STATE --> STORE
    STORE --> GPU
    PROTO --> IOS
    SIM --> SOCK
    SOCK --> TEST
    CLI --> SIM

来源：ios/SIMULATOR_FOUNDATION.md:34-45，crates/jcode-mobile-core/src/lib.rs:67-82，crates/jcode-mobile-sim/src/lib.rs:79-81

---

jcode-mobile-核心：协议与状态

jcode-mobile-core crate 定义了权威的状态机以及所有移动端客户端使用的通信协议。

移动端网关协议

该协议定义了类型化的请求和事件，与 JCodeKit 中的 Swift 实现相对应 crates/jcode-mobile-core/src/protocol.rs:16-20。

• MobileRequest：枚举类型，包含 Subscribe、Message、Cancel、SoftInterrupt 和 StdinResponse crates/jcode-mobile-core/src/protocol.rs:20-83。
• MobileServerEvent：从网关接收到的事件，例如 TextDelta、ToolStart 和 StateUpdate crates/jcode-mobile-core/src/protocol.rs:244-254。
• MobileGatewayConfig：派生健康检查、配对和 WebSocket 的 URL crates/jcode-mobile-core/src/protocol.rs:129-140。

模拟器状态与场景

SimulatorState 结构体跟踪当前的 Screen（Onboarding、Pairing、Chat）、ConnectionState 和消息历史 crates/jcode-mobile-core/src/lib.rs:67-82。提供了确定性场景来初始化测试状态：

场景	描述
onboarding	初始登录界面 crates/jcode-mobile-core/src/lib.rs:10-14。
pairing_ready	预填配对字段用于模拟 ios/SIMULATOR_FOUNDATION.md:152。
connected_chat	包含模拟历史记录的活跃聊天会话 ios/SIMULATOR_FOUNDATION.md:154。
server_unreachable	表示连接失败的状态 ios/SIMULATOR_FOUNDATION.md:156。

来源：crates/jcode-mobile-core/src/protocol.rs:20-254，crates/jcode-mobile-core/src/lib.rs:8-82，ios/SIMULATOR_FOUNDATION.md:148-164

---

jcode-mobile-sim：模拟器守护进程

jcode-mobile-sim 是一个无头优先的守护进程，负责托管 SimulatorStore 并通过 Unix 套接字暴露它 crates/jcode-mobile-sim/src/lib.rs:66-81。

自动化协议

模拟器使用基于 Unix 套接字的换行符分隔 JSON 协议 crates/jcode-mobile-sim/src/lib.rs:92-106。关键方法包括：

• status：返回包含运行时间和当前界面的 StatusSummary crates/jcode-mobile-sim/src/lib.rs:167-178。
• tree：返回语义 UI 树供代理检查 crates/jcode-mobile-sim/src/lib.rs:186-192。
• scene：返回用于渲染的 VisualScene crates/jcode-mobile-sim/src/lib.rs:193-199。
• tap：向存储分派 SimulatorAction::TapNode crates/jcode-mobile-sim/src/main.rs:235-239。

GPU 预览与渲染

模拟器支持多个渲染后端，这些后端源自共享的 VisualScene 契约 ios/SIMULATOR_FOUNDATION.md:85-96：

1. 文本后端：通过 render_text 为 CLI 检查提供确定性文本表示 crates/jcode-mobile-sim/src/lib.rs:206-210。
2. GPU 预览：一个原生的 winit/wgpu 窗口，使用确定性三角形列表网格绘制场景 ios/SIMULATOR_FOUNDATION.md:110-117。
3. SVG 后端：用于在 CI 中生成确定性截图 ios/SIMULATOR_FOUNDATION.md:94-96。

graph LR
    subgraph "状态更新"
        ACT["SimulatorAction"] --> RED["Reducer"]
        RED --> STATE["SimulatorState"]
    end

    subgraph "视觉管线"
        STATE --> TREE["语义 UI 树"]
        TREE --> SCENE["VisualScene"]
        SCENE --> WGPU["GPU 预览 (wgpu)"]
        SCENE --> SVG["SVG 截图"]
        SCENE --> MESH["预览网格"]
    end

来源：crates/jcode-mobile-sim/src/lib.rs:159-250，ios/SIMULATOR_FOUNDATION.md:97-104，crates/jcode-mobile-sim/src/gpu_preview.rs:1-11

---

开发工作流与测试

模拟器被设计为通过脚本和 AI 代理使用 mobile_simulator_tester.sh 工作流来驱动 ios/SIMULATOR_FOUNDATION.md:193-196。

CLI 用法

jcode-mobile-sim CLI 提供了控制后台守护进程的命令：

• start --scenario <name>：在后台启动守护进程 crates/jcode-mobile-sim/src/main.rs:29-34。
• state / tree：检查当前应用状态 crates/jcode-mobile-sim/src/main.rs:39-46。
• tap <node_id>：模拟用户交互 crates/jcode-mobile-sim/src/main.rs:235-239。
• assert-screen <name>：验证当前 UI 状态 crates/jcode-mobile-sim/src/main.rs:153-157。

黄金测试夹具

系统使用"黄金"夹具来确保确定性行为。ReplayTrace 允许记录一系列操作，并断言重放这些操作会产生相同的最终状态 crates/jcode-mobile-core/src/lib.rs:179-216。

代理工作流示例

一个典型的自动化测试循环遵循以下步骤：

1. 启动：scripts/mobile_simulator_tester.sh start pairing_ready scripts/mobile_simulator_tester.sh:165。
2. 交互：tap pair.submit scripts/mobile_simulator_tester.sh:168。
3. 断言：assert-screen chat scripts/mobile_simulator_tester.sh:169。
4. 日志：log 10 检查转换日志 scripts/mobile_simulator_tester.sh:175。

来源：docs/MOBILE_SIMULATOR_WORKFLOW.md:29-51，scripts/mobile_simulator_tester.sh:162-177，crates/jcode-mobile-sim/src/main.rs:22-249