Buoy：把开发者工具装进 App 里，让 AI 代理也能操控你的应用

场景切入：当调试工具只能"看"不能"动"

你正在开发一个复杂的 React Native 应用，遇到一个玄学 bug——某用户在特定网络条件下登录失败，但本地模拟器怎么都复现不了。传统的解决方案是：让测试人员打开手机设置、复现步骤、截图发给你，你再在电脑前对着 Flipper 翻日志，一来一回耗时数小时。

Buoy 解决的是同一个问题，但换了一个思路：不把调试工具放在桌面电脑上，而是把它嵌进你的 App 里——每个请求、每次状态变更、每次渲染、每个帧，都实时呈现在手机屏幕上、桌面上，以及你的 AI 代理的操作界面上。

这意味着，无论是真人测试员、AI Coding 助手，还是你自己，都能在任何环境下（开发、预发、甚至生产环境）看到 App 内部在做什么。更重要的是，AI 代理可以通过 MCP（Model Context Protocol）协议直接"操作"这个工具——读取状态、触发按钮、执行性能基准测试——就像在你身边坐着一个懂行的调试助手。

项目背景：Flipper 停更后的破局者

Buoy 的诞生背景非常清晰：Flipper 宣布废弃。Flipper 是 React Native 生态曾经最流行的桌面调试工具，但 Meta 在 2024 年宣布停止维护，而 React Native 0.73 开始 Flipper 已被移除。这意味着整个社区突然失去了一个重要的调试基础设施。

与此同时，传统调试工具存在三个根本局限：

• 位置限制：调试工具必须跑在电脑上，断开 USB 线就无法使用
• 环境限制：一旦 App 打包为预发/生产版本，console.log、React DevTools 全部失效
• AI 盲区：Claude、Cursor 等 AI Coding 工具能读代码、改代码，但无法"看见"运行中的应用——调试时只能靠猜测

Buoy 正是针对这三个痛点设计：工具运行在 App 进程内部，跟随 App 走遍所有环境；通过 localhost 代理将同一调试会话同时镜像到手机界面、桌面客户端和 AI 代理。

核心功能：零配置的浮动菜单 + 19 把瑞士军刀

Buoy 的使用方式极度简洁——只需在 App 根组件中挂载一个组件：

import { FloatingDevTools } from "@buoy-gg/core";
export default function App() {
  return (
    <>
      {/* 你的 App */}
      <FloatingDevTools />
    </>
  );
}

就这么一行代码，一个浮动调试菜单就出现在屏幕边缘，点开即有 19 个工具可用。以下是主要工具的功能解析：

Network（网络）：记录 App 中所有 HTTP 请求和响应，包括 GraphQL 操作，自动提取为 "GetUser › 123" 这样的可读格式，附带耗时和错误信息。这是日常开发中使用频率最高的工具之一。

Storage（存储）：支持 AsyncStorage、MMKV、SecureStore 的浏览和编辑，提供变更历史记录。生物识别密钥会列在列表中，但不会自动读取，保护用户隐私。

Time Machine（时光机）：对 Redux、Zustand、Jotai 和 React Query 缓存打快照作为还原点，一键回滚到任意历史状态，或直接清除到全新安装状态。对状态管理密集型应用极为有用。

Env（环境变量）：自动扫描 Expo 环境变量，验证类型是否正确，并给出 0-100% 的配置健康度评分。

React Query 工具：直接操作 TanStack Query 缓存，支持手动刷新、失效指定查询、模拟加载/错误状态，以及一键离线模式。

Debug Borders / Highlight Updates：用深度着色的边框标注布局层级（可穿透触控），点击任意标签查看 testID、无障碍属性和计算后的样式；高亮每次重新渲染，标注原因是 mount、state、props 还是父组件。

Perf Monitor（Bench）：实时显示 UI/JS FPS、CPU、内存和卡顿情况；批量基准测试返回排名报告，清晰展示哪些操作拖慢了帧率。

JS Top：JS 线程的任务管理器，以实时排名表格展示哪个定时器、Promise 链或回调占用了最多 JS 帧时间。

Events（事件时间线）：将所有工具的事件汇聚到一条统一时间轴上，支持导出为 Markdown（供 AI 代理使用）、Bug Report 模板，或仅显示错误。

Console：在设备上查看 Chrome DevTools 风格的 Console 输出，支持从 release 构建版本中读取，无需 USB 线也不需要 Metro。

Redux / Zustand / Jotai：三大状态管理库的专项检查器，支持状态读取、历史 diff、跳转和重置。Zustand 和 Jotai 工具无需任何中间件，一行调用即可启用。

Impersonate（模拟用户）：切换用户身份、角色和开关，无需重新构建，直接在请求头中注入 x-impersonate-user-id。

Image Overlay（图层叠加）：将 Figma 标注稿像素级对齐叠加在 App 界面上，Component Mode 可追踪特定组件在滚动和动画中的位置。

Assets / Images：审计所有打包图片的大小、重复项和未加载资源；图片加载显示缓存判定（内存/磁盘/网络）、耗时、超大警告和失败诊断。

MCP 集成：让 AI 代理真正"动手"调试

Buoy 最具前瞻性的功能是 MCP 服务器集成。一行命令即可接入 Claude Code、Cursor 或任意支持 MCP 的编辑器：

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

接入后，AI 代理获得了普通情况下不可能具备的能力：读取运行中的 App 状态（Redux/Zustand 状态、存储内容、路由栈），在 JS 层面真实触发按钮点击和表单提交，对物理设备或模拟器进行性能基准测试，并返回结构化的对比报告——而不再依赖截图、像素坐标或模拟触摸。

官方还提供了一个 buoy-optimize skill：用真实设备对 UI 变体做循环基准测试，每次应用最优方案，直到指标不再提升。官方声称曾用此方法将一个 Skia LED 动画从 28 帧卡顿优化到超过 12,000 帧流畅。

部署方式：零门槛的 npm 安装

Buoy 是一款纯 npm 包，不提供 Docker 容器化方案，部署门槛极低。所有工具都运行在 App 进程内部，镜像到桌面的通信通过 localhost 代理完成——不会将任何数据发送至外部服务器。

基础包安装：

npm install @buoy-gg/core

全套工具一键安装（按需选择）：

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}

核心 @buoy-gg/core 仅需约 50MB 磁盘空间，内存占用约 512MB，无 GPU 依赖，可在任意开发机上运行。生产环境只需一行条件渲染即可开启或关闭全部工具：

<FloatingDevTools headless />  {/* 无界面模式，仅同步到桌面和 MCP */}

无头模式适合字段测试、KIOSK 设备或交给非开发人员的构建版本。

代码架构：Monorepo + TypeScript 优先

Buoy 采用 monorepo 结构，主仓库包含 21 个子包，全部位于 packages/ 目录下：

• devtools-floating-menu（即 @buoy-gg/core）：浮动菜单核心 UI
• bottom-sheet：通用底部抽屉组件
• network、storage、env-tools 等 19 个工具子包

所有包均以 TypeScript 编写，类型覆盖率达到 100%。核心包 @buoy-gg/core 版本为 7.0.17（截至分析时），支持 React Native 和 Expo（含 Expo Go）。由于是专有软件，源码不公开，代码质量评估依赖 README 中的公开信息推断：TypeScript 100% 覆盖、monorepo 结构清晰、包粒度合理，推测代码质量较高。

许可模式：免费基础版 + 付费解锁高级功能

重要声明：Buoy 采用专有软件许可（Proprietary Software License），不是开源项目。LICENSE 文件明确标注 "NOT open source software"。

免费功能包括所有 19 个调试工具的开发版本使用，无时间限制，无需注册。付费解锁内容：生产环境构建（Production Builds）、MCP 服务器接入、无限数据捕获。定价：Solo 个人版 $9/月（或 $89/年），Business 企业版 $45/座位/月，均提供 14 天试用。

周末通行证（Weekend Pass）：每个周六和周日，所有付费功能对所有人免费开放，无需任何操作。这是一种独特的商业模式，让潜在用户在实际项目中完整体验 Pro 功能后再决定是否付费。

竞品对比：没有真正的竞争对手

在 React Native 调试工具领域，Flipper 已停更，Reactotron 功能有限，RN Debugger 能力有限。Buoy 的核心差异化在于三点：设备端调试（其他工具均需桌面）、生产环境可用性（其他工具仅限开发构建）、AI 代理控制（MCP 接入，无竞品具备）。如果将范围扩展到 Flutter，Buoy 已在 2024 年底推出 Flutter 版本（flutter pub add buoy），同样提供完整工具集。

行业意义：调试工具的范式转移

Buoy 代表了一种趋势：工具应该跟着应用走，而不是应用必须围绕工具转。传统开发流程中，开发者需要打开特定的桌面软件、连接设备、复现步骤，这个过程本身就成了效率瓶颈。Buoy 将这个关系倒置——工具嵌在应用里，无论应用跑在什么设备上、什么网络环境下、谁在使用，工具始终可用。

对于 AI Coding 时代而言，这个意义更为深远：AI 代理调试能力的缺失是当前 AI Coding 最大的瓶颈之一。当 AI 能直接读取运行中的应用状态、触发交互操作、执行性能基准测试，"AI 帮我修 bug"才从一句口号变成现实。

总结

Buoy 是一个设计精良的 React Native 应用内调试工具包，以极简的集成方式和丰富的工具集填补了 Flipper 停更后的生态空白。其 MCP 集成让 AI 代理第一次具备了真实调试移动应用的能力，方向具有开创性。免费版覆盖日常开发需求，付费模式合理，周末通行证是值得称赞的营销创新。

需要注意的局限：这是专有软件（非开源），源码不可获取，依赖官方维护；目前仅支持 React Native 和 Flutter，Web 版尚不在路线图中；对于已深度定制化调试工具链的团队，迁移成本不可忽视。