ZSeven-W/dsh-ios · 上手攻略

仓库：ZSeven-W/dsh-ios
链接：https://github.com/ZSeven-W/dsh-ios
分类：开发者工具 · iOS 开发 · AI Agent
作者：Jay
更新：2026-08-25

这是什么

dsh-ios（DeepSeek Harness iOS）是 DeepSeek Harness（DSH）的插件，将一个可交互的 iOS Simulator 实时画面和一台通过 USB 连接的 iPhone 整体嵌入 DSH 对话中。AI Agent 获得了 22 个工具来控制 iOS 模拟器或真机——启动/关闭设备、截图、UI 自动化（通过无障碍树或 OCR 定位元素）、构建并运行 Xcode 项目、查看统一日志、检查进程和内存泄漏等。实时画面以 MJPEG 流形式呈现在对话侧边栏中，用户可以直接在画面上点击、拖动、旋转、截图。

本质上，这是一个让 AI Agent 用"真实 iOS 设备"作为工具的 DSH 插件，适合需要在对话中自动化 iOS UI 测试、Swift 开发、越狱研究等场景。

解决什么问题

传统 iOS 开发中，AI 写好代码后需要手动构建、手动运行、手动观察模拟器。AI 看不到模拟器的画面，也无法直接触发 UI 操作。即使使用 Siri Shortcuts 或 xcrun simctl 等命令行工具，也只能做非常有限的操作。

dsh-ios 把这个链条完全自动化：Agent 可以用 ios_sim_build_run 构建 Xcode 项目并立即启动到模拟器，用 ios_sim_ui_tree 获取完整无障碍树，用 ios_sim_tap_element 按标签或标识符点击 UI 元素，用 ios_sim_ui_rows 将列表转换为索引行后按行号操作。AI 在整个过程中同时看到实时画面——真正实现了"AI 在控制真实 iOS 设备"的闭环。

快速安装

前置要求

macOS（模拟器和真机控制均依赖 macOS 工具链）
DeepSeek Harness（DSH） 已安装（需要 0.1.1-rc.1 或更高版本）
真机模式需要 WebDriverAgent（Xcode 内置）或通过 Xcode 构建

安装插件

# 通过 DSH 插件命令安装
dsh plugin --profile web add @zseven-w/dsh-ios@latest

# 启动 DSH web 界面
dsh web

当前最新版本：0.1.0-rc.5（2026-08-25），需要 DSH 0.1.1-rc.1+。

核心用法

设备列表与启动

// 工具：ios_sim_devices（无需参数）
// 返回：所有可用模拟器 + USB 连接的真机
{
  "simulators": [
    { "udid": "XXX", "name": "iPhone 16 Pro", "runtime": "iOS 18.0", "state": "booted" }
  ],
  "realDevices": [
    { "udid": "YYY", "name": "iPhone 15", "osVersion": "17.5", "model": "iPhone15,2", "state": "connected" }
  ]
}

// 工具：ios_sim_boot
{ "udid": "XXX" }

UI 自动化

// 获取无障碍树（AXe）
// 工具：ios_sim_ui_tree
{ "udid": "XXX" }

// 按标签点击元素
// 工具：ios_sim_tap_element
{ "udid": "XXX", "name": "Settings" }

// 按 OCR 文字点击（无障碍树为空时）
// 工具：ios_sim_find_text → ios_sim_tap_text

// 操作列表行（点击某行并验证计数器变化）
// 工具：ios_sim_ui_rows → ios_sim_tap_row
{ "udid": "XXX", "rowIndex": 3 }

构建与运行

// 构建并运行 Xcode 项目
// 工具：ios_sim_build_run
{ "udid": "XXX", "projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp" }

// 启动已安装的应用
// 工具：ios_sim_launch_app
{ "udid": "XXX", "bundleId": "com.example.MyApp" }

// 列出已安装应用
// 工具：ios_sim_list_apps
{ "udid": "XXX", "query": "Safari" }

交互与截图

// 工具：ios_sim_interact
{ "udid": "XXX", "action": "tap", "x": 0.5, "y": 0.3 }
// action 可选：tap / type / button(home/lock/volumeUp) / scroll / gesture

// 截图
// 工具：ios_sim_screenshot
{ "udid": "XXX" }

调试与检查

// 查看统一日志
// 工具：ios_sim_unified_log
{ "udid": "XXX", "predicate": "process == 'MyApp'" }

// 查看进程列表
// 工具：ios_sim_processes
{ "udid": "XXX" }

// 查看线程回溯
// 工具：ios_sim_backtrace
{ "udid": "XXX", "pid": 1234 }

// 检查内存泄漏
// 工具：ios_sim_leaks
{ "udid": "XXX", "pid": 1234 }

// 检查应用信息
// 工具：ios_sim_app_info
{ "udid": "XXX", "bundleId": "com.example.MyApp" }

// SwiftUI 预览热重载
// 工具：ios_sim_preview
{ "udid": "XXX", "previewPath": "/path/to/MyPreview.swift" }

典型适用场景

AI 驱动的 iOS UI 测试：AI 自动点击列表行、填写表单、验证计数器变化，无需人工操作模拟器
Swift 代码即写即验：用 ios_sim_build_run 让 AI 写完 Swift 代码立即在模拟器中运行并截图反馈
越狱研究：真机模式通过 USB 控制真实 iPhone，AI 可以操作文件管理器、查看沙盒内容、检查进程
iOS 应用自动化探索：对目标应用进行无障碍树遍历，找到隐藏按钮、测试边界条件
跨应用工作流：AI 可以在 Safari 中打开网页、在设置中修改参数、再回到应用验证效果

坑与注意

⚠️ macOS 独占：模拟器相关的所有功能（serve-sim、devicectl）只能在 macOS 上运行。工具在非 macOS 主机上仍会注册，但调用会返回说明性错误。

⚠️ 真机需要 WebDriverAgent：物理 iPhone 需要 Xcode 构建并安装 WebDriverAgent，否则 ios_real_start_wda 会失败。真机必须保持解锁状态。

⚠️ USB 连接稳定性：真机模式依赖 USB 的 usbmuxd 隧道连接，系统休眠后可能需要重新连接。

⚠️ 设备繁忙超时（v0.1.0-rc.5 修复）：早期版本在设备繁忙时 WDA 调用会无限超时，现已修复为 5 秒超时 + 10 秒冷却期。

⚠️ 实时画面冻结自愈（v0.1.0-rc.5 修复）：MJPEG 流在 8 秒无上游数据时会主动断开重连，不会永久定格在最后一帧。

⚠️ 模拟器 UDID 路由：devicectl 升级后在新版中会将模拟器和真机一起列出，rc.4 已修复模拟器被误判为真机的问题，使用 rc.4 以下版本需注意此 bug。

⚠️ identify-before-tap：真机模式下所有涉及真实账户的操作（如点击通讯录、发送消息）都会被规则拦截，需先确认设备状态。

⚠️ 版本 rc.5（2026-08-25）：最新预发布版本，修复了 WDA 超时和 MJPEG 冻结两个关键 bug，建议使用此版本。

与同类对比

工具	平台	AI 集成	实时画面	真机支持	无障碍树
dsh-ios	macOS/iOS	DSH 插件（22 工具）	✅ MJPEG 流	✅ USB WDA	✅ AXe
Appium	跨平台	WebDriver 协议	❌	✅	✅
xcrun simctl	macOS/iOS	纯命令行	❌	❌	❌
Frida	iOS/Android	JS 脚本	❌	✅ 越狱	❌
inspect（苹果官方）	macOS	独立 App	✅（仅 macOS）	❌	✅

核心优势：在 DSH 对话中同时获得 AI 工具 + 实时画面 + 真机控制，无需切换窗口，AI 的每个操作都有视觉反馈。

一句话推荐结论

如果你在用 DeepSeek Harness 做开发或测试，dsh-ios 是目前最完整的 iOS 设备集成方案——模拟器和真机均可对话式控制，实时画面让 AI 的每一步操作都可见可验证，rc.5 两个关键 bug 已修复，值得一试。