pranshuchittora/simvynUniversal mobile devtool for Agents & Humans - control iOS Simulators, Android Emulators, and real devices from a single dashboard and CLI 面向代理与人类的通用移动开发工具 - 从单一仪表盘和命令行界面控制 iOS 模拟器、Android 模拟器以及真实设备
<p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/12264/e081fb1d4bcaa6556ff10e722d1ff25449288b68ce1aad9ac3b5ecc047ccf5fb.png" width="180" alt="simvyn" /> </p> <h1 align="center">simvyn</h1> <p align="center"> 通用移动开发工具 — 通过单一仪表板和 CLI 控制 iOS 模拟器、Android 模拟器和真实设备 </p> <p align="center"> <a href="https://www.npmjs.com/package/simvyn"><img src="https://img.shields.io/npm/v/simvyn?color=cb3837&logo=npm" alt="npm version" /></a> <a href="https://www.npmjs.com/package/simvyn"><img src="https://img.shields.io/npm/dm/simvyn?color=cb3837&logo=npm" alt="npm downloads" /></a> <a href="https://github.com/pranshuchittora/simvyn/actions/workflows/ci.yml"><img src="https://github.com/pranshuchittora/simvyn/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a> <a href="https://github.com/pranshuchittora/simvyn/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/simvyn?color=blue" alt="MIT License" /></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/simvyn?color=5FA04E&logo=node.js&logoColor=white" alt="Node version" /></a> </p> <p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/12264/bff45a80ced8a6cba77f5bab23f21607fb310862cbc838179d9ce714a1d4d6b6.png" alt="simvyn dashboard" /> </p> <p align="center"> <img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/assets/demo.gif" alt="simvyn demo" /> </p> ## 目录 - [快速开始](#quick-start) - [安装](#installation) - [AI 编码代理](#ai-coding-agents) - [功能特性](#features) - [模块展示](#module-showcases) - [集合指南](#collections-guide) - [CLI 参考](#cli-reference) - [工作原理](#how-it-works) - [支持的平台](#supported-platforms) - [贡献](#contributing) - [安全](#security) - [许可证](#license) ## 快速开始```bash npx simvyn ``` 启动本地服务器，在浏览器中打开 Web 仪表板，并自动发现所有已连接的模拟器、仿真器和通过 USB 连接的物理设备。 ## 安装 **全局安装：**```bash npm install -g simvyn ``` **一次性使用（无需安装）：**```bash npx simvyn ``` **环境要求：** - Node.js 22（22.14.0+）或 24+ - macOS（完整支持 iOS + Android）或 Linux（仅支持 Android） ## AI 编码代理 simvyn 包含一个可移植的 [Agent Skill](https://github.com/pranshuchittora/simvyn/blob/main/skills/simvyn/SKILL.md)，用于发现设备、运行支持的 CLI 命令、捕获屏幕截图、检查应用数据以及收集有界日志。它指导代理使用带有明确设备 ID 和平台限制的 CLI。该技能使用代理现有的终端工具；它不会注册 MCP 服务器或新的代理工具。 **Pi：** 该 npm 包是一个 [Pi 包](https://pi.dev/packages/simvyn)。除了该技能外，它还添加了 `simvyn`、`simvyn_screenshot`、`simvyn_logs` 和 `simvyn_record` 工具，一个运行仪表板的 `/simvyn` 命令，以及 `/simvyn-repro`、`/simvyn-screen` 和 `/simvyn-logs` 提示模板。它需要 Pi 0.74 或更高版本：```bash pi install npm:simvyn ``` **其他兼容代理：** 从 GitHub 安装便携式技能，选择你的代理，并单独安装 simvyn CLI：```bash npm install -g simvyn npx skills add pranshuchittora/simvyn --skill simvyn --agent codex --yes ``` GitHub 命令要求这些技能文件存在于默认分支上；Pi 命令要求已发布的 npm 版本中包含 Pi 资源。对于未发布的更改，请使用[本地检出说明](https://github.com/pranshuchittora/simvyn/blob/main/docs/agents.md#test-an-unreleased-checkout)。 有关捆绑启动器、支持的输出、非交互式操作和当前限制，请参阅[代理设置和工作流指南](https://github.com/pranshuchittora/simvyn/blob/main/docs/agents.md)。对于接受文档 URL 的工具，还提供了一个紧凑的[文档索引](https://github.com/pranshuchittora/simvyn/blob/main/llms.txt)。 ## 功能 - **设备管理** — 发现、启动、关闭、擦除、创建和克隆模拟器、仿真器和物理设备，支持收藏置顶 - **应用管理** — 通过拖放或 CLI 安装、启动、终止、卸载应用 - **日志查看器** — 实时流式传输，支持级别过滤、页面内查找（Cmd+F）、正则搜索、分页和导出 - **位置模拟** — 设置 GPS 坐标，播放 GPX/KML 路线并控制速度，保存收藏 - **设备设置** — 深色模式、区域设置、方向、权限、状态栏覆盖、辅助功能预设 - **截图和录制** — 捕获截图并录制屏幕视频，带历史记录 - **深度链接** — 打开 URL 和自定义 scheme，按应用保存收藏 - **数据库检查器** — 浏览 SQLite 表，运行 SQL 查询，查看 SharedPreferences 和 NSUserDefaults - **文件浏览器** — 浏览应用沙盒，上传/下载文件，内联编辑文本 - **推送通知** — 编写 JSON 负载，发送到 iOS 模拟器，模板库 - **集合** — 将设备操作打包为可重用序列，一次应用到多个设备 - **崩溃日志** — iOS 诊断报告和 Android logcat/tombstone 崩溃 - **剪贴板** — 读取和写入设备剪贴板内容 - **媒体** — 将照片和视频推送到设备相机胶卷和相册 - **工具设置** — 服务器配置、存储管理、诊断和调试报告 - **真机支持** — 通过 USB 连接物理 Android 和 iOS 设备，自动发现 - **Web 仪表板** — Apple Liquid Glass 设计，带命令面板、键盘导航 - **完整 CLI** — 每个功能都可通过 `simvyn <command>` 无头运行 ## 模块展示 ### 设备管理 在一个统一列表中查看所有连接的 iOS 模拟器、Android 仿真器和 USB 连接的物理设备。无需打开 Xcode 或 Android Studio 即可启动、关闭和擦除设备。通过选择设备类型和运行时创建新的 iOS 模拟器，或克隆现有模拟器以快速创建副本。物理设备插入后自动显示，并在设备选择器中单独分组。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/2b85641878f6015c248311700a1a87a20476ade6c930273a3e47f288a82d6d2e.png" alt="Device Management" width="700" /></p> - 列出所有可用的模拟器、仿真器和跨平台物理设备 - 一键或通过 CLI 命令启动、关闭和擦除设备 - 通过选择设备类型和运行时创建新的 iOS 模拟器 - 克隆和重命名现有模拟器 - 将收藏设备置顶到设备选择器 - 通过 WebSocket 实时更新设备状态 ### 应用管理 在任何连接的设备上安装、启动、终止和卸载应用。将 IPA、APK 或 iOS 模拟器 .app 包直接拖放到仪表板上。查看详细的应用信息并清除应用数据，无需手动执行 adb 或 simctl 命令。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/17757b1ca8ddd41d43ac3a159260598308da6c3f759e1c9d730f61498e18ce8a.png" alt="App Management" width="700" /></p> - 拖放安装 IPA、APK 和 iOS 模拟器 .app - 按 bundle ID 启动、终止和卸载应用 - 查看应用详情，包括版本、大小和权限 - 在 Android 设备上清除应用数据 - 列出所有已安装应用并支持搜索过滤 ### 日志查看器 实时流式传输设备日志，支持强大的过滤功能。按日志级别过滤，使用正则模式搜索，按进程名过滤。使用页面内查找（Cmd+F）高亮特定条目而不隐藏周围上下文。导出过滤后的日志以供分享或归档。分页历史记录让您可以回滚浏览数千条条目而不会出现性能问题。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/b909b3515637b4059ebf210c56599f2f022506f09ee35a11e812bd8368d3750e.png" alt="Log Viewer" width="700" /></p> - 通过 WebSocket 实时流式传输日志 - 按级别过滤：debug、info、warning、error、fatal - 页面内查找（Cmd+F），支持匹配高亮、导航和计数器 - 正则搜索和进程名过滤 - 分页历史记录，带虚拟滚动 - 将过滤后的日志导出到文件 - 暂停/恢复日志流式传输，并在清除后保留状态 ### 位置 使用交互式地图或手动输入在任何设备上设置精确的 GPS 坐标。播放 GPX 和 KML 路线文件，支持可调节的速度控制。将常用位置保存为收藏以便快速访问。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/47842dfa878ffbc80bd5bb32d83e820e7ed7dd56a4d63368ca6e823ef72889d4.png" alt="Location" width="700" /></p> - 交互式地图，点击设置坐标 - GPX 和 KML 路线文件播放，带速度控制 - 按设备保存收藏位置 - 多设备位置广播 - 反向地理编码以获取人类可读的地址 ### 设备设置 切换深色模式、更改区域设置、旋转设备方向（Android）、管理应用权限，并覆盖状态栏外观。应用辅助功能预设以在不同条件下测试您的应用。所有设置更改会立即在目标设备上生效。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/d3f6a33c17b773560072f7b94b71abd5ebc82786c073bdeb6d25f828c3f214fa.png" alt="Device Settings" width="700" /></p> - 切换深色/浅色模式 - 更改设备区域设置 - 管理应用权限 - 覆盖状态栏（时间、电池、信号） - 辅助功能预设（粗体文本、增加对比度、内容大小） ### 截图和录制 在任何设备上捕获截图并录制屏幕视频。所有捕获内容都带有时间戳保存，并组织在可浏览的历史记录中。直接从仪表板下载或删除捕获内容。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/58ed8f25d148ed53f39066e42be730f255235dbec47539bbec826c455cba7936.png" alt="Screenshots and Recording" width="700" /></p> - 一键截图捕获 - 屏幕录制，带开始/停止控制 - 带时间戳的捕获历史记录 - 从仪表板下载和删除捕获内容 ### 深度链接 在任何设备上打开 URL 和自定义 URI scheme。将常用深度链接按应用保存为收藏。无需手动在终端中输入 URL 即可测试应用的深度链接处理。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/3a990ef7c74f83c93b63c1654f74b3fa952b0b41abd31fe688cdaf2e29570f62.png" alt="Deep Links" width="700" /></p> - 在设备上打开任何 URL 或自定义 scheme - 按应用保存收藏深度链接 - 链接历史记录，按最近优先排序 - 适用于 iOS 和 Android ### 数据库检查器 浏览任何应用沙盒内的 SQLite 数据库。查看表结构，运行任意 SQL 查询，并检查 SharedPreferences（Android）或 NSUserDefaults（iOS）。无需编写脚本即可内联编辑值。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/4884b688dbbee5f1a34b0454950f4d6562e74efdbbb3b84ca5c626835b4b7d37.png" alt="Database Inspector" width="700" /></p> - 浏览 SQLite 表，支持可排序列 - 运行任意 SQL 查询 - 查看和编辑 SharedPreferences 和 NSUserDefaults - 内联单元格编辑，带类型检测 ### 文件浏览器 浏览任何已安装应用的沙盒文件系统。导航目录，上传和下载文件，并内联编辑文本文件。无需手动执行 adb pull/push 命令即可在您的机器和设备之间传输文件。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/7b7ba540ad5de8b575da4f9bb28694dc68f5ffce51225a388788b8ef2f4767a0.png" alt="File Browser" width="700" /></p> - 浏览应用沙盒目录 - 上传和下载文件 - 内联编辑文本文件 - 适用于 iOS 和 Android 应用容器 ### 推送通知 编写 JSON 推送通知负载并发送到 iOS 模拟器。使用内置模板库作为起点，或从头编写负载。实时 JSON 验证在发送前高亮错误。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/f640654be67c24c7248806987e62908316407c18648fc145109118f260443f7d.png" alt="Push Notifications" width="700" /></p> - 编写并发送推送负载到 iOS 模拟器 - 内置负载模板库 - 实时 JSON 验证 - 按 bundle ID 定位特定应用 ### 集合 创建可重用的设备操作集合并一次应用到多个设备。集合将设置位置、切换深色模式和安装应用等步骤打包为单个可重复的工作流。simvyn 附带三个入门预设供您开始使用。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/fbf2ddbba1d3725321c80a914bf5b71ea6a2fc605fddbb73abd0b28385488af6.png" alt="Collections" width="700" /></p> - 创建、复制和管理命名集合 - 浏览所有模块的分类操作目录 - 拖放重新排序步骤 - 应用到多个设备，带兼容性检查 - 三个内置入门预设 ### 崩溃日志 查看 iOS 诊断报告（.ips 文件）以及来自 logcat 和 tombstone 转储的 Android 崩溃日志。浏览带时间戳和进程信息的崩溃条目。无需深入设备文件系统即可检查完整的崩溃详情。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/8f74a799448050bc37eace1d43865b13f3f47a0997c01dba650fd21e94f09ebf.png" alt="Crash Logs" width="700" /></p> - iOS 诊断报告（.ips）解析 - Android logcat 崩溃按 PID 和标签分组 - Android tombstone 转储检索 - 带时间戳的崩溃列表，带详情视图 ### 剪贴板 从仪表板或 CLI 读取和写入设备剪贴板。适用于快速将测试数据粘贴到应用中或检查应用复制了什么内容。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/db889032abeb5f1d511dcfeb8c06c215bda851436f198a63db97f595b50853d6.png" alt="Clipboard" width="700" /></p> - 读取当前剪贴板内容 - 将文本写入设备剪贴板 - 适用于 iOS 模拟器和 Android 仿真器 ### 媒体 将照片和视频直接推送到设备的相机胶卷或相册。将文件拖放到仪表板上即可注入，无需数据线、电子邮件或云传输。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/c63ce5411dc17b5d329c2af381c035d86164f5544928b0c76fe7d05346473561.png" alt="Media" width="700" /></p> - 通过拖放将照片和视频添加到设备相册 - 支持最大 500 MB 的大文件 - 适用于 iOS 模拟器和 Android 仿真器 ### 工具设置 配置 simvyn 服务器、管理存储并查看诊断信息。包含用于提交问题的调试报告生成器。 <p align="center"><img src="https://assets.kitploit.com/production/public/readmes/12264/7ba043d473d21d4bb5477582539ffd9a4c57600ec20c22ee9d7e63146cbbfbb2.png" alt="Tool Settings" width="700" /></p> - 服务器端口、自动打开和轮询间隔配置 - 存储使用概览，带数据清除选项 - 诊断：Xcode 版本、devicectl 可用性、adb 版本 - 一键调试报告用于提交 bug ## 集合指南 集合让您将多个设备操作打包为可重用的序列，并一键应用到任意设备组合。 ### 创建集合 从侧边栏打开集合面板。点击 **New Collection** 并为其命名。集合初始为空——您将从操作目录中添加步骤。 ### 添加步骤 点击 **Add Step** 浏览分类操作目录。操作按模块组织——设备设置、位置、应用管理等。选择一个操作，内联配置其参数（坐标、bundle ID、切换值），它就会出现在您的集合中。拖动步骤以重新排序。 ### 应用集合 点击 **Apply** 打开应用模态框。从设备列表中选择一个或多个目标设备。兼容性摘要显示哪些步骤将在不兼容的平台上被跳过（例如，在 Android 设备上的 iOS 专属操作）。按 **Cmd+Enter** 执行。实时状态矩阵显示每个步骤、每个设备的实时进度。 ### 命令面板集成 已保存的集合会出现在命令面板（**Cmd+K**）中。按名称搜索集合，并使用设备选择器直接应用——无需导航到集合面板。 ### 入门集合 simvyn 附带三个内置预设： - **深色模式 + 日语区域** — 启用深色模式并将区域设置为日语 - **截图设置** — 配置状态栏覆盖以获得干净的 App Store 截图 - **重置设备状态** — 清除位置、重置设置并擦除应用数据 ### CLI 用法```bash simvyn collections list # List all collections simvyn collections apply <name> <devices...> # Apply a collection to devices ``` ## CLI 参考 每个功能都可以通过命令行访问。不带参数运行 `simvyn` 即可启动仪表板，或使用以下任意命令进行无头操作。 | 命令 | 描述 | | ------------------------------------------------- | ------------------------------------------ | | `simvyn` | 启动仪表板（默认） | | `simvyn device list` | 列出所有设备 | | `simvyn device boot <device>` | 启动设备 | | `simvyn device shutdown <device>` | 关闭设备 | | `simvyn device erase <device>` | 抹掉设备内容和设置 | | `simvyn device create <name> <type> <runtime>` | 创建新的 iOS 模拟器 | | `simvyn device clone <device> <name>` | 克隆 iOS 模拟器 | | `simvyn device rename <device> <name>` | 重命名 iOS 模拟器 | | `simvyn device delete <device>` | 删除 iOS 模拟器 | | `simvyn location set <device> <lat> <lng>` | 设置 GPS 坐标 | | `simvyn location route <device> <file>` | 播放 GPX/KML 路线 | | `simvyn location clear <device>` | 清除模拟位置 | | `simvyn app list <device>` | 列出已安装的应用 | | `simvyn app install <device> <path>` | 安装 IPA、APK 或 iOS 模拟器 .app | | `simvyn app uninstall <device> <bundle-id>` | 卸载应用 | | `simvyn app launch <device> <bundle-id>` | 启动应用 | | `simvyn app terminate <device> <bundle-id>` | 终止应用 | | `simvyn app info <device> <bundle-id>` | 显示应用详情 | | `simvyn app clear-data <device> <bundle-id>` | 清除应用数据（Android） | | `simvyn logs <device>` | 流式传输设备日志 | | `simvyn screenshot <device>` | 截取屏幕截图 | | `simvyn record <device>` | 录制屏幕 | | `simvyn link <device> <url>` | 打开深度链接 | | `simvyn push <device>` | 发送推送通知 | | `simvyn fs ls <device> <bundle-id> [path]` | 列出应用沙盒中的文件 | | `simvyn fs pull <device> <bundle-id> <path>` | 下载文件 | | `simvyn fs push <device> <bundle-id> <src> <dst>` | 上传文件 | | `simvyn db list <device> <bundle-id>` | 列出数据库 | | `simvyn db query <device> <bundle-id> <db> <sql>` | 运行 SQL 查询 | | `simvyn db prefs <device> <bundle-id>` | 查看 SharedPreferences / NSUserDefaults | | `simvyn keychain add <device> <cert>` | 添加根证书 | | `simvyn keychain reset <device>` | 重置钥匙串 | | `simvyn collections list` | 列出所有集合 | | `simvyn collections show <id>` | 显示集合详情 | | `simvyn collections create <name>` | 创建新集合 | | `simvyn collections delete <id>` | 删除集合 | | `simvyn collections duplicate <id>` | 复制集合 | | `simvyn collections apply <name> <devices...>` | 将集合应用到设备 | | `simvyn settings orientation <device> <orient>` | 设置设备方向（Android） | ## 工作原理 simvyn 将 `xcrun simctl`（iOS 模拟器）、`xcrun devicectl`（iOS 物理设备）和 `adb`（Android）封装在统一接口之后。无需 SDK —— 适用于任何应用，无需修改代码。 该架构围绕模块系统构建，每个功能（位置、日志、应用管理等）都是一个自包含的插件，注册自己的 API 路由、CLI 命令和 WebSocket 处理器。Web 仪表板通过单个多路复用 WebSocket 连接与本地 Fastify 服务器通信，以实现实时设备状态和日志流式传输。特定设备类型上不可用的功能会自动禁用，并在 UI 中显示清晰的指示。 ## 支持的平台 | 平台 | iOS 模拟器 | iOS 设备 | Android 模拟器 | Android 设备 | | ------- | ---------- | -------- | -------------- | ------------ | | macOS | 是 | 有限 | 是 | 是 | | Linux | 否 | 否 | 是 | 是 | ### 真实设备支持 通过 USB 连接的物理设备会与模拟器和仿真器一起被自动发现。仪表板将它们分组到不同的部分（物理设备 / 模拟器 / 仿真器），并在设备断开连接时显示提示。 **Android 物理设备**支持几乎所有功能 —— 应用管理、深度链接、日志、屏幕截图、数据库检查器、文件浏览器等。少数仅限仿真器的功能（通过 `adb emu geo` 进行位置模拟、电池模拟）不可用，并在 UI 中明确标记。 **iOS 物理设备**需要 Xcode 15+，并在底层使用 `xcrun devicectl`。支持的功能包括设备发现、应用安装/卸载/启动/终止、应用列表、深度链接和文件复制。许多依赖 `simctl` 的功能（屏幕截图、屏幕录制、位置模拟、剪贴板、外观、状态栏、推送通知）在物理 iOS 设备上不可用。不支持的控件会被禁用，并显示解释原因的提示。集合会自动跳过不适用于物理设备的步骤。 ## 贡献 欢迎贡献 —— 无论是错误修复、新模块、平台覆盖还是文档。 请从 **[贡献指南](https://github.com/pranshuchittora/simvyn/blob/main/CONTRIBUTING.md)** 开始，其中涵盖了开发环境设置、项目布局、如何添加模块以及 CI 运行的检查。 - [报告错误](https://github.com/pranshuchittora/simvyn/issues/new?template=bug_report.yml) - [请求功能](https://github.com/pranshuchittora/simvyn/issues/new?template=feature_request.yml) - [行为准则](https://github.com/pranshuchittora/simvyn/blob/main/CODE_OF_CONDUCT.md) - [更新日志](https://github.com/pranshuchittora/simvyn/blob/main/CHANGELOG.md)```bash git clone https://github.com/pranshuchittora/simvyn.git cd simvyn npm install npm run dev ``` ## 安全 simvyn 是一个本地开发者工具，并非设计用于暴露在不受信任的网络中。 请通过 [GitHub Security Advisories](https://github.com/pranshuchittora/simvyn/security/advisories/new) 私下报告漏洞，而不是作为公开 issue 提交。有关范围以及应包含的内容，请参阅[安全策略](https://github.com/pranshuchittora/simvyn/blob/main/SECURITY.md)。 每个版本都通过可信发布以[来源证明](https://docs.npmjs.com/generating-provenance-statements)发布到 npm，因此你可以将 tarball 追溯验证到构建它的提交：```bash npm audit signatures ``` ## 许可证 [MIT](https://github.com/pranshuchittora/simvyn/blob/main/LICENSE) © [Pranshu Chittora](https://github.com/pranshuchittora)
