lijianfei.com

在探索大语言模型（LLM）与移动设备自动化结合的道路上，开发者常常陷入两难的技术困局：要么选择传统的软件驱动路线（如 Appium、WebDriverAgent、XCUITest 或私有 CoreDevice 调试通道），这意味着你必须常备一台开机的 Mac 电脑、配置复杂的 Xcode 环境、购买每年 99 美元的 Apple 开发者账号，并时刻面临证书过期与企业级反作弊/风控检测的阻断；要么走深度越狱与进程注入路线，但这在现代 iOS 系统中不仅门槛极高，更会彻底破坏设备的安全基线。智能体（AI Agent）似乎始终被困在虚拟沙箱或模拟器中，无法像真人一样轻盈、无侵入地操控身边的真实 iPhone。

最近，我深度研读并实测了开发者 Henry Yuan 开源的爆款项目 ESP32 iPhone Agent（商业代号 Handsy，GitHub 斩获近 5000 Star），尤其是其最新发布的 DeepSeek Harness (DSH) 官方集成插件。该方案凭借一块仅售价 7 美元的 Seeed Studio XIAO ESP32-S3 微型开发板，彻底撕开了 iOS 的生态围墙——无需 Mac、无需开发者账号、无需越狱，仅凭硬件级模拟的“AirPlay 屏幕镜像之眼”与“USB HID 键鼠之手”，就让运行在云端或本地的 DeepSeek 模型获得了接管真实 iPhone 的物理实体。在本文中，我将以第一视角深入拆解该方案的底层硬件通信原理、DeepSeek Harness 的 Cordis 微内核与 MCP 桥接架构，以及其关键的“看-动闭环”与人机协同安全边界。

一、 核心困境：传统移动端 Agent 为何走不通？

在深入技术架构之前，先梳理一下过往自动化操控 iOS 设备的各种流派及其致命缺陷：

通过纯硬件外设层面的模拟，Handsy 实现了一种“带外控制（Out-of-Band Control）”哲学：从操作系统内核的角度看，既没有注入的动态库，也没有开启的调试开关，甚至没有可疑的后台无障碍服务。设备只是单纯地把画面无线镜像给了屏幕，并接收到了来自 USB 接口的物理电气信号。

二、 物理双桥：AirPlay 之眼与 USB HID 之手

这套系统能够以极低成本落地的核心，在于对两个 iOS 原生原生开放特性的极致复用：

flowchart LR
    subgraph iOSDevice ["iPhone 实体真机 (iOS 18+)"]
        Screen["屏幕图像 (Screen)"]
        TouchOS["辅助触控 (AssistiveTouch)<br/>系统级鼠标指针与物理键盘"]
    end

    subgraph ESP32Board ["7 美元 ESP32-S3 开发板"]
        direction TB
        AirPlayRecv["AirPlay 镜像接收端<br/>(从 UxPlay 裁剪移植)"]
        USBHIDChip["USB OTG 复合设备<br/>(HID 鼠标 + 键盘)"]
        CommBridge["应用层加密通信总线<br/>(BLE 握手 / Wi-Fi TCP:7202)"]
    end

    subgraph HostSystem ["宿主工作站 / DeepSeek Harness"]
        direction TB
        DSHCore["DeepSeek Harness (Cordis 内核)"]
        MCPServer["esp32agent CLI / MCP Server"]
        VLM["DeepSeek 视觉推理大模型"]
    end

    Screen -- "Wi-Fi H.264 镜像流" --> AirPlayRecv
    USBHIDChip -- "物理 USB 信号 (点击/按键)" --> TouchOS
    AirPlayRecv --> CommBridge
    CommBridge --> USBHIDChip

    CommBridge <== "AES-128-GCM 加密通道" ==> MCPServer
    MCPServer <== "JSON-RPC (stdio)" ==> DSHCore
    DSHCore <== "Prompt & Tool Calls" ==> VLM

1. 眼睛：轻量级 AirPlay 接收端

ESP32-S3 板载了 8MB PSRAM 与 8MB 闪存，具备硬件 Wi-Fi 与蓝牙。作者 Henry Yuan 将著名的开源 AirPlay 接收器 UxPlay 裁剪并重构移植到了 ESP32 固件中：

• 板子启动自身热点（SoftAP）或接入局域网 Wi-Fi，广播名为 ESP32 Agent 的 AirPlay 投屏服务；
• iPhone 打开控制中心，点击“屏幕镜像”，选择该设备；
• iPhone 将当前的屏幕画面实时编码为 H.264 视频流（默认分辨率为 $480 \times 1040$，帧率上限为 5 fps），推送到 ESP32；
• ESP32 收到 H.264 访问单元（Access Unit）后，通过板载缓存处理，将视频流封装并直接中继透传至宿主机或本机 App 进行硬解或 ffmpeg 快照提取。

2. 双手：USB 原生 HID 复合外设

ESP32-S3 拥有原生 USB OTG 接口。通过一根 USB-C 短线（或 Lightning 相机转换套件）插入 iPhone：

• 在 iPhone 上开启 设置 → 辅助功能 → 触控 → 辅助触控（AssistiveTouch）。这一选项是 iOS 为残障人士提供的无障碍功能，允许通过外接硬件鼠标在屏幕上产生悬浮光标并触发触控；
• ESP32 在 USB 枚举阶段将自身描述为一个 标准的复合 HID 设备（USB Mouse + USB Keyboard）；
• 当 Agent 需要点击某个坐标时，ESP32 向 USB 差分数据线发送标准 HID 相对位移与左键单击报告，驱动辅助触控光标移动并完成点击；
• 当 Agent 需要输入文本时，ESP32 模拟硬件键盘敲击。按压 HOME 键时，则发送键盘预设的多媒体或快捷键触发系统返回桌面。

三、 DeepSeek Harness 架构集成：Cordis 微内核与 MCP 桥接

官方在 integrations/dsh 目录下的实现，堪称现代智能体架构工程的典范。它并没有编写任何冗余的私有胶水层，而是精准对接了 DeepSeek Harness 基于 Cordis 响应式微内核与标准模型上下文协议（Model Context Protocol, MCP）。

1. cordis.patch.yml：声明式 MCP 客户端注入

DeepSeek Harness 采用基于配置的插件扩展机制。在 integrations/dsh/cordis.patch.yml 中，Handsy 通过 @deepseek-ai/dsh-mcp-client 将 CLI 包装为 stdio MCP 服务器挂载到系统总线：

- insert:
    # 注入 stdio MCP 客户端，将底层工具映射为 mcp__esp32agent__<tool>
    - id: esp32agent-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: esp32agent
        transport: stdio
        command: npx
        args: [-y, [email protected], mcp]
        # DSH 在 fork 子进程时会清理环境变量，必须显式穿透指定的硬件板卡 ID
        env: !!js "process.env.ESP32AGENT_DEVICE ? { ESP32AGENT_DEVICE: process.env.ESP32AGENT_DEVICE } : {}"
        # 首次启动涉及下载二进制与 H.264 AirPlay 关键帧对齐，放宽超时阈值
        startupTimeoutMs: 120000
        toolCallTimeoutMs: 120000
        # 关键容错：若未插硬件板子，不阻塞 DSH 正常启动，仅在工具调用时原子报错
        failOnStartupError: false
    # 注入认知技能定义（看-动闭环与安全规范）
    - id: esp32agent-skill
      name: dsh-esp32agent

这里的工程细节极具参考价值：

• 环境变量显式穿透：DSH 为了环境纯净，默认会剥离继承的父进程环境变量。Handsy 通过 !!js 动态表达式，精准将 ESP32AGENT_DEVICE 透传给子进程，保证多板卡并存时能够精准寻址；
• 优雅降级与防御性容错：failOnStartupError: false 保证即使开发者手头未连接实体 ESP32 板子，DSH 工作区依然能平稳拉起，不会因外设脱机而导致整个智能体工作台崩溃；
• 充裕的启动宽限：设定 120 秒超时，完美覆盖了 npx 首次拉取 Go 编译二进制以及 AirPlay 视频建立链路的时间开销。

2. index.js：Cordis 插件与认知注入

单纯暴露 API 工具往往无法让大模型稳定工作，因为 LLM 经常会产生“链式幻觉”（连续猜想并连续点击多次）。integrations/dsh/index.js 通过 Cordis 的服务注入机制注册了名为 handsy 的专属技能：

import { readFile } from 'node:fs/promises'
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'

export const name = 'dsh-esp32agent'
export const inject = ['skills']

const SKILL_DIR = fileURLToPath(new URL('./skills/handsy/', import.meta.url))
const SKILL_PATH = `${SKILL_DIR}SKILL.md`
// 设定与 DSH 内置技能完全相同的优先级（600），便于用户工作区本地配置覆盖
const RANK = 600

export function apply(ctx) {
  const { description } = parse(readFileSync(SKILL_PATH, 'utf8'))
  const candidate = {
    name: 'handsy', 
    description,
    invocation: { modelInvocable: true, userInvocable: true },
    provider: name, 
    source: 'bundled', 
    rank: RANK,
    resourceBase: { kind: 'directory', path: SKILL_DIR },
    locator: SKILL_PATH,
  }
  ctx.skills.registerProvider(() => ({
    name,
    list: () => Promise.resolve([candidate]),
    async get(c, options) {
      const { rank: _rank, locator, ...summary } = c
      const raw = await readFile(locator, { encoding: 'utf8', signal: options?.signal })
      return { ...summary, content: parse(raw).content }
    },
  }))
}

该插件将 skills/handsy/SKILL.md 的内容挂载进模型上下文，将“工具”升华为“工作流认知”。

四、 核心工作流：看-动闭环与宏录制（See-Act Loop & Macro）

在 handsy 技能的引导下，DeepSeek 模型严格遵循四步闭环执行任务：

flowchart TD
    Start([接收人类自然语言指令]) --> Shot["1. 获取当前屏幕快照 (screenshot)<br/>等待画面完全静止 (Settled)"]
    Shot --> Analyze["2. 视觉多模态分析 (VLM)<br/>解析屏幕 UI 层次，定位目标元素"]
    Analyze --> Decision{"画面是否符合预期？"}
    
    Decision -- 出现敏感页面 / 拦截 --> HITL["触发安全护栏：交由人类接管<br/>(密码、支付、短信验证码)"]
    Decision -- 正常业务流程 --> Act["3. 执行单步物理动作 (One Action)<br/>输入像素坐标 (tap / swipe / type_text)"]
    
    Act --> VerifyShot["4. 再次获取屏幕快照 (Verification)"]
    VerifyShot --> CheckResult{"单步操作是否达成目标？"}
    
    CheckResult -- 未完成 / 需下一动作 --> Shot
    CheckResult -- 出现偏差 / 偏移 --> Recalibrate["启动指针纠偏 (--aim / calibrate)"] --> Shot
    CheckResult -- 任务整体圆满成功 --> SaveMacro["提取成功轨迹并归档为宏意图 (intent_save)<br/>归一化 0~1000 坐标序列与基准屏幕"]
    SaveMacro --> End([任务完成])

1. 严格禁止盲点：看一眼 → 做一步 → 再看

在桌面 GUI Agent 中，大模型一次性规划多个点击步骤（如“点击搜索框，输入文字，点击搜索”）往往成功率极低，因为移动端有大量页面过渡动画、输入法弹出遮挡和网络加载抖动。
Handsy 在协议层面制定了铁律：

• 每次动作前调用 screenshot 工具，该命令会在底层等待 H.264 视频流画面完全静止后才返回完整分辨率的图片；
• 模型必须根据这张实际截图上的绝对像素坐标（例如 $x=240, y=520$）决定且仅决定一个动作；
• 严禁连续下发多个动作。动作执行完毕后，必须再次截图核验结果。

2. 宏意图保存与就地重放（Intent Save & Replay）

大模型的单步调用通常需要消耗数百毫秒至数秒的推理时间。如果每次给手机定闹钟、打开微信扫一扫都要重新经过 10 轮 VLM 视觉推理，效率将大打折扣。
Handsy 的 CLI 与 MCP 巧妙设计了本地意图缓存层（mcp_local.go）：

• 历史记录追踪（history）：自动以 0~1000 归一化坐标记录操作过程中的有效步骤与当时的基准截图；
• 提炼有效路径（intent_save）：开发者或 Agent 本身可以剔除中间的点错、重试步骤，仅将真正成功的动作序列保存为具名意图（如 Alarm 7:00）；
• 重放验证（intent_show）：在下一次收到类似意图时，智能体直接比对当前屏幕与基准参考图。若一致，直接以宏指令毫秒级完成回放；一旦界面改版或不匹配，再优雅回退至全量 VLM 看-动循环。

五、 底层通信协议：应用层握手与硬件仲裁器

在传统的蓝牙或网络通信中，设备重连或缓存冲突经常导致系统假死。Handsy 的底层实现设计了极为硬核的容错与安全机制。

1. 规避系统蓝牙绑定的“无状态”应用层加密

在 macOS 或 Windows 上开发过 BLE 的工程师几乎都遇到过 CBError 14（Peer removed pairing information）——一旦单片机重新烧录，操作系统底层的配对密钥失效，蓝牙堆栈直接卡死，需要用户在系统设置中手动“忽略设备”。

Handsy 在 docs/cli-protocol.md 中彻底摒弃了系统级 BLE 绑定，全部移入应用层处理：

• 动态 MAC 地址轮换：ESP32 每次冷启动，都会生成一个全新的随机静态地址，系统根本无法持久化旧的 Bond 密钥；
• X25519 + HKDF 安全握手：上电 3 分钟内开放配对窗口，客户端与板卡通过椭圆曲线密钥交换（X25519）派生共享对称密钥 $K$；
• AES-128-GCM 全程加密通信：所有传输的控制帧与视频元数据均附带自增计数器（Counter）与 12 字节认证标签，杜绝重放攻击与旁路窃听。

2. 双传输层自动平滑升级

• BLE 作为初始探活与保活底座：电脑通过 BLE 搜索广播，完成身份认证与初始配置；
• 自动跃迁至 Wi-Fi TCP（端口 7202） ：一旦检测到电脑与 ESP32 处于同一网段（例如电脑连上了板子的热点，或板子加入了家庭 Wi-Fi），控制与视频流立即平滑无缝切换到 TCP 7202。数据吞吐量瞬间从 BLE 的百 Kbps 跃升至几十 Mbps，截图延迟骤降至亚秒级。

3. 多端仲裁器（Hardware Arbiter）

手机可能既连接着电脑端的 DeepSeek Harness，又运行着手机本机的配套 iOS 控制 App。谁拥有手机的控制权？
固件中的 arbiter.h 严格规定了 “手机本机优先” 原则：

• 当 iOS 本机 App 建立链路时，板卡仲裁器立即抢占硬件总线，向电脑端返回 owner: app, busy: 1，并断开电脑的视频流，释放按下的按键；
• 电脑端 DSH 工具收到 busy 状态后自动退避 30 秒，绝不会发生两端同时发送坐标导致光标在屏幕上“打架”的灾难。

六、 实战避坑与工程调优指南

在亲自使用 ESP32-S3 与 DeepSeek 搭建自动化流水线时，我总结了以下几个必须注意的硬核踩坑点：

1. 辅助触控指针漂移与校准

辅助触控的悬浮鼠标指针在长时间移动后可能会产生微小的累积误差。

• 解决方案：在初次连接或重要点击前，必须调用 npx -y esp32agent calibrate（或使用带 --aim 参数的点击命令）。该命令会驱动光标在屏幕中央做基准校正，并通过视觉反馈重新标定像素与 HID 位移的换算比例。

2. 中文输入的“拼音桥接”机制

iOS 的 USB HID 键盘接口严格遵循标准 USB 规范，无法直接向系统总线注入 UTF-8 字符串（如直接发送“你好”）。

• 解决方案：Handsy 实现了纯纯的“外设级拼音输入法映射”。当调用 type_text 输入中文（例如 拿铁）时，CLI 会自动将其转译为拼音 ASCII 字符序列 natie 进行键击，随后通过发送 space 触发系统输入法的候选词上屏；如果第一候选词不对，Agent 则会通过截图识别候选词栏的准确坐标并补发一次点击。

3. 敏感安全场景的人机协同（HITL）红线

由于 Agent 操控的是一部真实的个人主力或测试 iPhone，上面关联着真实的 Apple ID、银行卡与社交关系。
在配置提示词与工作区策略时，必须严格保留 skills/handsy/SKILL.md 的安全护栏：

• 资金转移安全：凡涉及支付、转账、购买内购等操作，必须强制交由人工接管；
• 对外通信安全：凡涉及发送即时消息、发邮件、拨打电话、公开发布推文等操作，严禁私自触发；
• 敏感认证安全：凡涉及锁屏密码、Face ID 刷脸、二次验证码 OTP 输入，必须立刻挂起并交由用户本人操作。

在这些场景下，Agent 必须立即挂起任务，向人类输出警示信息并等待人工手动在手机上操作完毕后，再继续后续流程。

七、 总结与未来展望

esp32-iphone-agent 与 DeepSeek Harness 的结合，为移动端具身智能（Mobile Embodied Agent）打开了一扇全新的大门。它摒弃了与苹果闭源软件生态在调试协议上的长期对抗，另辟蹊径地从物理外设层降维打击：用 7 美元的微控制器充当物理神经元，将视觉与动作彻底解耦并标准化为 MCP 工具流。

无论是在真机回归自动化测试、个人跨端工作流调度，还是在不破坏系统完整性下的 AI 辅助办公场景中，这种“外设级纯物理 Agent”都在成本、稳定性与安全性之间取得了惊艳的平衡。随着端侧多模态模型推理速度的进一步跃升，我们正在见证手机从“人类指尖的延伸”真正进化为“可被大模型自主接管的物理智能体”。

原文链接与参考资料

• 项目开源代码仓：onehumanbeing/esp32-iphone-agent - GitHub
• DeepSeek Harness 集成规范：esp32-iphone-agent Integrations (DSH) - GitHub
• Handsy 官方硬件与安装文档：Handsy Tech Official Documentation
• DeepSeek Harness 官方仓库：deepseek-ai/deepseek-harness - GitHub
• Cordis 微内核架构文档：Cordis Framework Documentation