react-grab

react-grab — 为 AI Agent 提供浏览器元素上下文

关键词： react-grab · grab · element context

指向实时 React UI 元素，捕获精确的组件、文件和 HTML 上下文，然后直接将其提供给 Claude Code、Cursor、Copilot、Codex、Gemini 或 MCP 工作流。

何时使用此技能

• 在 React 项目中安装 react-grab，让 Agent 可以从浏览器复制准确的组件上下文
• 为 React 元素捕获选择剪贴板流程、MCP 流程或插件/API 流程
• 修复 react-grab 设置问题，例如加载位置错误、缺少文件路径或 MCP 响应为空
• 添加或移除 Agent 集成（claude-code、cursor、codex、gemini、mcp 等）
• 为项目特定的工作流构建自定义插件或使用原语 API

不要将此技能用于：

• 新会话的浏览器自动化、身份验证流程或一次性浏览器验证 → browser-harness
• 复用已有 Cookie、扩展程序或登录状态的运行中浏览器 → playwriter
• 针对已渲染 UI 的人工反馈/标注数据包 → agentation
• React 性能诊断、重复渲染、Hydration、打包体积或 RSC/客户端边界相关工作 → react-best-practices
• 通用 UI 系统、设计令牌或组件库设计工作 → design-system

说明

步骤 1：判断请求类型

在提供命令前，选择一种主要模式：

1. 剪贴板安装/使用 — 用户希望将鼠标悬停在元素上，按 Cmd/Ctrl+C，然后将上下文粘贴到 AI Agent 中。
2. MCP 工作流 — 用户希望浏览器中选中元素后，Agent 调用 get_element_context 等工具。
3. 插件/API 工作流 — 用户希望使用自定义操作、生命周期钩子、格式化功能或 freeze() 等原语。
4. 故障排除/移除 — 用户希望解决设置问题或彻底移除集成。

步骤 2：如实确认前置条件

以上游项目为准：

• npx grab@latest init 是默认安装方式。
• 上游 package.json 目前要求 Node.js >=22。
• 浏览器叠加层是仅限开发环境的工具；切勿将其描述为生产功能。

如果用户的环境低于 Node 22，请在提供安装方式前明确说明。

步骤 3：提供最简正确方案

模式 A — 剪贴板安装/使用

除非用户明确要求使用 MCP 或插件，否则默认采用此方式：

# At the project root
npx -y grab@latest init

然后说明运行流程：

1. 启动开发服务器。
2. 在浏览器中打开应用。
3. 将鼠标悬停在目标元素上。
4. 按 Cmd+C（Mac）或 Ctrl+C（Windows/Linux）。
5. 将捕获的上下文粘贴到 AI Agent 中。

剪贴板输出应包含：

• 组件名称
• 源文件路径
• 行号/列号（如果可用）
• HTML 片段

如果用户需要特定框架的设置说明，请参阅 references/install-and-routing.md。

模式 B — MCP 工作流

当用户希望 Agent 以编程方式访问，而不是手动粘贴时：

npx -y grab@latest add mcp

清楚说明实际流程：

1. 用户在浏览器叠加层中选中元素或将鼠标悬停在元素上。
2. MCP 服务提供最新的选中项。
3. AI Agent 调用 get_element_context。
4. 工具返回文件路径、组件、堆栈和 HTML 上下文。

如果用户询问这与剪贴板流程有何不同：

• 剪贴板是手动粘贴到聊天中。
• MCP是在选中元素后通过工具检索。

有关特定 Agent 的安装和路由指南，请参阅 references/agent-workflows.md。

模式 C — 插件/API 工作流

当用户希望实现自定义行为、自动化或更深入的集成时：

• 先确定安装方式和工作流选择。
• 然后参考：
  • references/api.md，了解完整 API
  • references/agent-workflows.md，了解实用的插件/MCP 模式

可提及的常用原语：

• getElementContext(element)
• freeze() / unfreeze()
• openFile(filePath, lineNumber?)
• registerPlugin(...)

除非用户要求深入了解，否则不要列出完整 API。

模式 D — 故障排除／移除

如果用户需要修复问题或彻底移除：

• 使用 references/troubleshooting.md，按症状优先进行排查。
• 如需移除，请使用上游 CLI 移除命令：

npx -y grab@latest remove <agent>

第 4 步：明确划分边界

将 react-grab 的用途限定为从浏览器捕获 React 元素上下文。

如果用户实际提出的是以下需求，请转交给其他工具：

• 通用浏览器自动化 → browser-harness 或 playwriter
• UI 审查／视觉标注 → agentation
• 性能／性能分析／水合／包体积／RSC 问题 → react-best-practices
• 可复用组件系统设计 → design-system 或 design-system

第 5 步：优先使用参考文档，避免主入口内容臃肿

确定模式后，仅加载相应的支持文档：

• references/install-and-routing.md
• references/agent-workflows.md
• references/troubleshooting.md
• references/api.md

除非用户明确要求详细流程，否则请保持主要答复简短。

示例

示例 1：在 Next.js 应用中安装并使用剪贴板流程

用户：“在我的 Next.js 应用中设置 react-grab，这样我就能把组件复制到 Claude Code 里。”

答复结构：

1. 确认 Node 22+ 是前置要求。
2. 默认使用 npx -y grab@latest init。
3. 说明开发服务器 → 在浏览器中悬停 → Cmd/Ctrl+C → 粘贴到 Claude Code 的流程。
4. 只有在无法自动检测时，才加载框架专属设置。

示例 2：设置 MCP，以便 Agent 使用工具

用户：“安装 react-grab MCP，让 Agent 能获取所选按钮的上下文。”

答复结构：

1. 确认 Node 22+ 是前置要求。
2. 运行 npx -y grab@latest add mcp。
3. 说明先在浏览器中选择元素，然后 Agent 再调用 get_element_context。
4. 如有需要，将通用浏览器控制问题转交给 browser-harness／playwriter。

示例 3：自定义插件工作流

用户：“创建一个 react-grab 插件，在上下文菜单中添加 Jira 操作。”

答复结构：

1. 将 react-grab 限定在插件／API 范围内。
2. 使用 registerPlugin(...)，并添加操作和可选钩子。
3. 指向 references/api.md，了解完整的钩子接口。
4. 示例只围绕用户要求的操作展开，不要重复介绍整个 API。

示例 4：修复设置偏差

用户：“我的电脑上 grab init 一直失败。”

答复结构：

1. 先检查 Node 版本，并指出 Node 22+ 的要求。
2. 确认用户是在项目根目录运行命令。
3. 使用 references/troubleshooting.md 排查覆盖层／加载／MCP／路径故障。
4. 将无关的框架构建问题转交给相应的前端技能。

最佳实践

1. 如实说明 Node.js >=22 的前置要求，然后再推荐安装命令。
2. 默认使用 npx -y grab@latest init，除非用户明确需要手动设置框架。
3. 仅用于开发环境——绝不要暗示它应该包含在生产构建中。
4. 清楚说明剪贴板与 MCP 的区别，避免用户混淆基于粘贴和基于工具的工作流。
5. 尽早转交宽泛的浏览器或 UI 审查任务，不要让 react-grab 包揽相邻技能的职责。
6. 通过支持文档提供深入内容，不要把冗长的安装或 API 手册粘贴到主答复中。

参考资料

• react-grab GitHub
• react-grab.com
• 安装与路由指南
• Agent 工作流
• 故障排除
• 完整 API 参考
• 辅助脚本 — install.sh 和 add-agent.sh