jo-duchan/tapflow

项目介绍

tapflow 让移动 QA 团队直接在浏览器里操作 iOS Simulator 和 Android 模拟器，不必每人都装 Xcode、Android Studio，也不用轮流借用真机。它由三部分组成：自托管中继（Linux 或 macOS，同时在同一端口提供控制台）、运行在 Mac 上并主动向外连接中继的代理（直接注入 iOS 触摸，不依赖 WebDriverAgent），以及团队其他人使用的浏览器界面（架构说明）。

画面采用 H.264 编码和两级解码（HTTPS 下用 WebCodecs，普通 HTTP 下用 WASM/tinyh264），绕开媒体元素缓冲，并提供 JPEG 回退。围绕串流，控制台还提供 App Center（上传 .app.zip/.apk 并按状态跟踪构建）、约 72 小时后自动清理的会话录制、截图 REST 接口、每台代理的 CPU/内存监控、团队角色以及个人访问令牌（功能列表）。

适合需要验证构建、查看布局或演示行为的产品、设计和 QA 同学；它不替代原生开发工具，不是设备农场，也不接入 Appium、WebDriverAgent 等外部自动化框架（边界说明）。仓库还包含实验性的 YAML 流程回放器和给 LLM 代理用的 MCP Server。

快速使用

前提：Node.js ≥ 22；运行代理需要 macOS 26 或 27，并装有 Xcode 26 或 27 与 iOS Simulator 运行时，或者装有 Java 和带 AVD 的 Android SDK（环境要求）。

1. 安装命令行工具：npm install -g tapflow。
2. 在要跑模拟器的 Mac 上准备环境：tapflow setup。仅做中继的 Linux 机器可跳过。
3. 本地模式同时启动中继和代理：tapflow start。输出会显示中继运行在 http://localhost:4000，代理已连接并列出可用模拟器。
4. 打开 http://localhost:4000，页面会跳转到 /setup 创建管理员账号。无图形界面的服务器可改用 tapflow admin init。
5. 登录后进入控制台。环境检查失败时运行 tapflow doctor 重新检查 Node、iOS 和 Android 配置。

团队使用时，在单独的 Linux 主机或 Mac 上运行 tapflow relay start（文档给出 PM2 和带持久卷的 tapflow/tapflow Docker 镜像两种方式），然后在每台 Mac 上执行 tapflow agent start --relay wss://your-relay-url --token <agent-token> 接入（自托管说明）。

使用约束

代理必须运行在 macOS 上，因为它要驱动 Simulator 和模拟器；只有中继可以随意部署。中继承载账号、构建和实时设备控制，是信任边界：非本机访问需要登录，远程代理需要 agent 作用域的令牌；即使隧道客户端跑在中继本机，经隧道进入的流量也按非本机处理（安全模型）。

Docker 镜像只包含中继，必须挂载卷保存登录密钥；邀请链接还需要设置 TAPFLOW_RELAY_URL。从设备复制内容到浏览器剪贴板需要 HTTPS 或 localhost。会话录制约 72 小时后自动清除。流程回放器和 MCP Server 标注为实验性功能。项目采用 MIT 许可证，Android 串流捆绑了 scrcpy-server。

HotRepo 点评

在 2026-11-04 的 TypeScript 日榜中，tapflow 单日新增 26 Star，当天最高排到第 10 位；仓库累计 1,585 Star、169 Fork。2026-06-10 的 Show HN 帖只有 4 分、没有评论；更活跃的讨论来自 2026-06-22 一篇排查 0.5 秒周期卡顿的文章，最终定位到 macOS AWDL，评论者提到云游戏串流服务也曾针对 Mac 发出类似提醒。README 自己给出的延迟数据是局域网内 WASM 软解下解码到呈现 p50 约 11–17 ms，这说明端到端流畅度还取决于宿主机的网络行为，而不只是串流链路本身。