• 一个组件，零配置 —— 只需添加一次 <FloatingDevTools />；安装任意工具包后，它会自行出现在菜单中
• 22 个工具，覆盖所有环境 —— 网络、状态、存储、渲染、性能等，适用于开发、预发布以及生产构建
• 你的 Agent 可以驱动它 —— Claude 或 Cursor 可读取实时状态、点击真实按钮，并通过 MCP 在真机上进行基准测试。

---

⚡ 快速开始

npm install @buoy-gg/core

import { FloatingDevTools } from "@buoy-gg/core";

export default function App() {
  return (
    <>
      {/* Your app */}
      <FloatingDevTools />
    </>
  );
}

配置到此为止。应用内会出现一个悬浮开发菜单。

---

🛟 一个实时会话，三种接入方式

所有工具都运行在应用进程内。手机、桌面和你的 agent 都能实时看到同一个会话。

• 📱 在手机上 — 点按悬浮菜单。适用于任意设备，无需数据线、桌面应用或 Metro。
• 🖥️ 在桌面上 — Buoy Desktop 将设备端工具镜像到 macOS、Windows 和 Linux 上的全屏面板，并提供实时 UI/JS FPS · CPU · 内存 HUD 以及设备远程控制。
• 🤖 通过你的 agent — Buoy MCP server 为 Claude Code、Cursor 或任意 MCP 编辑器提供对运行中应用的结构化工具调用。

---

🧰 22 个工具

工具	包	功能
Network	@buoy-gg/network	每个请求、响应、耗时与错误——GraphQL 操作会被提取并显示为 GetUser › 123
Storage	@buoy-gg/storage	浏览并编辑 AsyncStorage、MMKV 与 SecureStore，附带变更历史——生物识别密钥仅列出，不会自动读取
Time Machine	@buoy-gg/time-machine	将存储、Redux、Zustand、Jotai 与查询缓存快照为恢复点——一键回退，或清空至全新安装
Scenarios (即将推出)	@buoy-gg/scenarios	为 QA 和支持提供一键保存的应用状态——覆盖响应、写入存储、模拟身份并导航均可一步完成，并带有醒目的 SIMULATED 横幅和一键撤销
Env	@buoy-gg/env	自动发现 EXPO_PUBLIC_ 变量，校验类型，并以 0–100% 为配置健康度打分
Query	@buoy-gg/react-query	TanStack Query 缓存——重新获取、使缓存失效、模拟加载与错误状态，一键离线
Routes	@buoy-gg/route-events	导航事件、实时栈与完整站点地图——可跳转到任意屏幕
Debug Borders	@buoy-gg/debug-borders	按深度着色的布局边框（触摸穿透）——点按任意标签查看 testID、a11y 属性与计算样式
Highlight Updates	@buoy-gg/highlight-updates	每次渲染及其原因：挂载、状态、props 或父组件——精确到具体 useState 的前后变化
Bench	@buoy-gg/perf-monitor	真机上的 UI/JS FPS、CPU、内存与卡顿——批量基准测试会返回排名报告
JS Top	@buoy-gg/js-top	JS 线程的任务管理器——实时排名表，显示哪些定时器、Promise 链和回调在消耗你的 JS FPS
Images	@buoy-gg/images	每次图片加载的缓存判定（内存/磁盘/网络）、耗时、超大图与内存浪费审计，以及失败诊断
Assets	@buoy-gg/assets	你发布的所有内容——打包图片、字体、视频与音频，附带大小、重复项以及从未加载检测
Events	@buoy-gg/events	跨所有工具的统一时间线，并提供 LLM 导出预设：供 agent 使用的 Markdown、Bug Report、Errors Only
Console	@buoy-gg/console	设备上的 Chrome-DevTools 控制台——无需数据线、无需 Metro，即可读取发布构建的日志
Redux	@buoy-gg/redux	检查、dispatch 与时间旅行——标记超出 16ms 帧预算的 actions
Zustand	@buoy-gg/zustand	状态、差异、跳转至指定状态、一键重置——无需中间件
Jotai	@buoy-gg/jotai	一次 watchAtoms() 调用，无需任何包装——每个事件都会显示 prev → next，即使是没有变化的写入
Impersonate	@buoy-gg/impersonate	无需重新构建即可切换用户、角色与特性开关——向每个请求注入 x-impersonate-user-id
TV Remote	@buoy-gg/tv-remote	从桌面操控 Apple TV 与 Android TV 上的 D-pad——将导航路径录制为宏，并在所有设备上回放
Focus Inspector	@buoy-gg/focus-inspector	查看 Apple TV 与 Android TV 上 D-pad 的焦点所在——每次移动都带方向，并标记卡住、消失或始终无法到达的焦点
Camera	(无包 — 桌面应用)	为 iOS Simulator 提供真实相机——可指向 Mac 屏幕、摄像头、图片或视频，无需设备即可扫描二维码或驾照
Overlay	@buoy-gg/image-overlay	将 Figma 设计稿像素级精准地覆盖在应用上——Component Mode 可跟踪已标记组件在滚动与动画中的表现

一行即可获取全部：

npm i @buoy-gg/{core,network,storage,env,react-query,route-events,debug-borders,highlight-updates,perf-monitor,js-top,images,assets,events,console,redux,zustand,jotai,impersonate,image-overlay,tv-remote,focus-inspector}

实战演示

---

🤖 为你的 Agent 装上双手

npx -y @buoy-gg/mcp@latest init

一条命令即可将 Buoy MCP 服务器接入 Claude Code、Cursor 和 VS Code——且不会破坏现有配置。

你的 AI 智能体直接在 JS 中触发真实 UI 处理函数，读取实时应用状态，并在真机上进行基准测试——无需截图、无需像素坐标、无需合成触摸。

• 读取运行时 — get_events 和 get_console 以节省 token 的摘要形式，流式输出应用实际正在执行的内容
• 操控 UI — describe_screen 遍历实时 React 树，生成带可点击点的无障碍式元素列表；tap_element 在 JS 中触发真实处理函数。支持真机。
• 变更状态 — get_redux_state / redux_dispatch、get_zustand_state、get_jotai_state、get_react_query / react_query_action、get_storage / storage_action、get_routes / navigate
• 度量 — run_benchmark_batch 在真机上运行 Bench 用例，并返回排名对比结果；screenshot_component 通过 testID 返回任意组件的紧凑截图（iOS 模拟器）；list_devices 选择目标设备

init 还会安装 buoy-optimize 技能：一个向导式流程，会在真机上对多个变体进行基准测试，应用优胜方案，并重复执行，直到指标趋于平稳。一次真实运行，将 Skia LED 显示从 28 个卡顿的灯提升到 12,000 多——毫无延迟。

📚 AI / MCP 文档 · Pro 功能

---

🖥️ Buoy Desktop

所有工具，全屏体验。Buoy Desktop 在 macOS、Windows & Linux 上免费使用：

• 零配置连接 — 设备会自动发现你的电脑，包括真机
• Network、Console、Storage 以及所有状态工具的全屏面板
• 实时 UI/JS FPS · CPU · 内存 HUD
• 远程操作 — 通过键盘执行 dispatch、navigate、invalidate
• 多设备切换与组件截图工具
• 带动态光效的主题，因为你可能会盯着它一整天

📚 桌面文档

---

为什么选择 Buoy？

Flipper 已弃用。剩下的，不过是摇一摇设备打开开发者菜单、通过数据线进行 console.log 考古，以及一旦发布 staging 或生产构建就会失效的桌面调试器。而当 AI 智能体参与你的应用开发时，它只能盲调——它能修改代码，却看不到正在运行的应用究竟在做什么。

Buoy 反转了这一模型：工具内置在应用自身，因此应用到哪里，工具就跟随到哪里——模拟器、测试人员的手机、生产环境。一个极小的 localhost broker 会将同一会话镜像到你的桌面和你的智能体。

	Buoy	Flipper	Reactotron	RN Debugger
设备端运行，无需桌面应用	✅	❌	❌	❌
适用于生产构建	✅	❌	❌	❌
AI 智能体控制（MCP）	✅	❌	❌	❌
QA 与支持团队可用	✅	❌	❌	❌
零配置接入	✅	❌	❌	❌

生产环境安全

<>
  {/* Your app */}
  {isInternalUser && <FloatingDevTools />}
</>

那一行就是完整的生产策略：内部构建和开启标志的用户获得完整工具集；其他人则完全不启用。

想要完全没有设备端 UI 的会话吗——现场构建、自助终端设备，或交给非开发者的应用？无头模式可让每个工具持续与 Buoy Desktop 和 MCP 保持同步，同时在设备端不渲染任何内容：

<FloatingDevTools headless />

---

💳 每款工具都免费。一把免费密钥解锁其余能力。

每款工具在所有套餐中均永久免费——唯一变化的是每款工具保留多少历史记录。

	获取方式	你将获得
无密钥	无需任何操作	全部工具，附带短暂捕获窗口——足以了解每个工具的作用。
免费	npx buoy login —— 无需信用卡，约 30 秒	完整免费套餐：覆盖所有工具的真实历史记录，以及每周末免费使用 Pro。
Pro	buoy.gg/pricing	全部功能：生产构建、MCP server、无限捕获。

付费方案可解锁生产构建、MCP server 和无限捕获——Solo 为 $9/月（$89/年），面向个人；Business 为 $45/席位/月，面向企业，并提供优先支持与批量定价。两者均附带 14 天试用。

领取你的密钥——无论免费还是付费，都是同一条命令：

npx buoy login

请在已安装 @buoy-gg/core 的项目中运行 —— npx 会从你本地的 node_modules 中解析该命令。如果它转而尝试下载内容，请显式指定包名：npx --package=@buoy-gg/core buoy login。

它会完成登录，将 key 写入 .env.local，并加入 .gitignore。然后：

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

也可以直接传入：<FloatingDevTools licenseKey="YOUR_LICENSE_KEY" />

Weekend Pass： 每周六和周日，工具内的所有 Pro 功能都会免费解锁，所有持有 key 的用户均可使用——包括免费 key。这不是促销活动，而是产品内置机制。运行 npx buoy login，亲自体验一下，周一再决定。

➡️ buoy.gg/pricing

---

反馈

发现了 bug，或者需要一个还不存在的工具？提交 Issue ——功能请求将驱动产品路线图。

许可证

专有软件。© Buoy LLC。保留所有权利。请参阅 服务条款。

---

_{你读完了整个 README。Pro 每周末免费解锁——周六见。🛟}