react-elements-ai-inspector

一个开箱即用的 React 元素检测插件，可以在开发环境中快速定位任意元素的源码位置，并直接发送修改建议到 CodeBuddy。

特性

• 🔍 按住 Alt + 悬停即可高亮元素
• 📍 点击元素自动生成包含源码位置的 Prompt
• 💬 支持为元素添加修改建议评论
• 🚀 一键发送到 CodeBuddy CLI
• 🎯 支持查看元素层级关系
• 📦 零配置，开箱即用
• 🔌 支持 Vite / Webpack
• ⚙️ 支持自定义 Prompt 模板，注入项目规范约束

原理

┌─────────────────────────────────────────────┐
│  用户代码 (.jsx)                             │
│  <Button onClick={...}>Click</Button>       │
└─────────────────┬───────────────────────────┘
                  │ Babel 编译
                  ▼
┌─────────────────────────────────────────────┐
│  编译后代码                                  │
│  <button data-source-file="..."             │
│          data-source-line="5" ...>          │
└─────────────────┬───────────────────────────┘
                  │ 浏览器渲染
                  ▼
┌─────────────────────────────────────────────┐
│  Inspector 运行时                            │
│  1. Alt + 悬停 → 读取 data-source-* 属性     │
│  2. 显示高亮 overlay                         │
│  3. 点击 → 生成包含源码位置的 Prompt         │
└─────────────────────────────────────────────┘

1. Babel 插件：编译时为每个 JSX 元素注入 data-source-file、data-source-line、data-source-column 属性
2. Inspector 组件：运行时监听热键和鼠标事件，读取元素的源码位置信息并高亮显示

安装

npm install react-elements-ai-inspector

安装 CodeBuddy CLI（可选）

如需使用「发送到 CodeBuddy」功能，需要先安装 CodeBuddy CLI：

npm install -g @tencent-ai/codebuddy-code

环境要求：

• Node.js 22+
• Git

📖 官方文档：https://copilot.tencent.com/cli/

使用方式

1. 配置 Vite

// vite.config.js
import react from '@vitejs/plugin-react';
import { babelPlugin } from 'react-elements-ai-inspector/vite';

export default {
  plugins: [
    react({
      babel: {
        plugins: [babelPlugin]  // 注入源码位置信息
      }
    })
  ]
};

2. 添加 Inspector 组件

方式 A：直接使用组件

// main.jsx 或 App.jsx
import { Inspector } from 'react-elements-ai-inspector';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && <Inspector />}
    </>
  );
}

方式 B：使用 Provider

import { InspectorProvider } from 'react-elements-ai-inspector';

function App() {
  return (
    <InspectorProvider>
      <YourApp />
    </InspectorProvider>
  );
}

// 在子组件中使用 hook
import { useInspector } from 'react-elements-ai-inspector';

function ChildComponent() {
  const { disable, enable, toggle, lastPrompt } = useInspector();
  // ...
}

方式 C：使用 HOC

import { withInspector } from 'react-elements-ai-inspector';

function App() {
  return <div>My App</div>;
}

export default withInspector(App);

API

Inspector Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | hotkey | 'Alt' \| 'Control' \| 'Meta' \| 'Shift' | 'Alt' | 激活检测的热键 | | disabled | boolean | false | 是否禁用 Inspector | | onPromptGenerate | (prompt: string) => void | - | 生成 Prompt 时的回调 | | bridgeUrl | string | 'http://localhost:9527' | CodeBuddy Bridge 服务地址 | | promptConfig | PromptConfig | - | 自定义 Prompt 配置 |

PromptConfig

用于注入项目特定的规范、约束和上下文：

| 属性 | 类型 | 说明 | |------|------|------| | systemPrompt | string | 系统级提示词，放在 Prompt 最前面，设置 AI 角色和总体约束 | | projectContext | string | 项目上下文说明，描述技术栈、项目背景 | | rules | string[] | 代码规范/约束规则列表 | | footer | string | 结尾提示词，替换默认的结束语 | | customTemplate | (comments: CommentItem[]) => string | 完全自定义模板函数，忽略其他配置 |

使用示例：

<Inspector
  promptConfig={{
    systemPrompt: "你是一个专业的前端开发专家，擅长 React 和 TypeScript。",
    projectContext: "这是一个使用 React 18 + TypeScript + TailwindCSS 的电商项目。",
    rules: [
      "使用 TypeScript 严格模式",
      "组件使用函数式组件 + Hooks",
      "样式使用 TailwindCSS",
      "遵循 ESLint 和 Prettier 规范"
    ],
    footer: "请按照上述需求修改代码，并确保符合项目的代码规范。修改后请简要说明改动点。"
  }}
/>

生成的 Prompt 结构：

[systemPrompt]

## 项目背景
[projectContext]

## 代码规范要求
1. [rule1]
2. [rule2]
...

## UI 修改需求
[用户评论内容]

---
[footer]

完全自定义模板：

<Inspector
  promptConfig={{
    customTemplate: (comments) => {
      return `# 自定义 Prompt\n\n${comments.map(c => 
        `- ${c.comment} (${c.element.source?.file}:${c.element.source?.line})`
      ).join('\n')}`;
    }
  }}
/>

useInspector Hook

interface UseInspectorReturn {
  disabled: boolean;      // 当前是否禁用
  enable: () => void;     // 启用 Inspector
  disable: () => void;    // 禁用 Inspector
  toggle: () => void;     // 切换状态
  lastPrompt: string;     // 最后生成的 Prompt
}

发送到 CodeBuddy

Inspector 支持将生成的 Prompt 直接发送到 CodeBuddy CLI，让 AI 自动修改代码。

前置条件

1. 安装 CodeBuddy CLI（如未安装）：

npm install -g @tencent-ai/codebuddy-code

2. 验证安装：

codebuddy --version

启动 Bridge 服务

在项目目录下运行：

npx react-elements-ai-inspector-bridge

服务启动后会显示 CLI 安装状态：

╔════════════════════════════════════════════════════════╗
║     React Elements AI Inspector - CodeBuddy Bridge     ║
╠════════════════════════════════════════════════════════╣
║  Server running at http://localhost:9527               ║
║                                                        ║
║  ✅ CodeBuddy CLI detected                              ║
║                                                        ║
║  Endpoints:                                            ║
║    POST /send-prompt  - Send prompt to CodeBuddy       ║
║    GET  /health       - Health check                   ║
╚════════════════════════════════════════════════════════╝

如果显示 ❌ CodeBuddy CLI not found，请先安装 CLI。

使用流程

1. 按住 Alt 键点击页面元素
2. 在弹出的评论框中输入修改建议
3. 按 Enter 或点击 添加评论 按钮
4. 点击 发送到 CodeBuddy 按钮
5. CodeBuddy CLI 会在后台自动处理请求并修改代码

状态指示器：

• 🟢 绿色：Bridge 服务已连接
• 🔴 红色：Bridge 服务未启动

Webpack 配置

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        use: {
          loader: 'babel-loader',
          options: {
            plugins: [
              'react-elements-ai-inspector/babel-plugin'
            ]
          }
        }
      }
    ]
  }
};

使用说明

1. 按住 Alt 键（可配置）
2. 将鼠标悬停在任意元素上，元素会被高亮
3. 点击元素，弹出评论输入框
4. 输入修改建议，按 Enter 添加评论
5. 点击 发送到 CodeBuddy 将请求发送给 AI

常见问题

Bridge 服务报错 "CodeBuddy CLI not installed"

请先安装 CodeBuddy CLI：

npm install -g @tencent-ai/codebuddy-code

发送后 CodeBuddy 没有响应

1. 确认 CodeBuddy CLI 已正确安装并登录
2. 检查终端中 Bridge 服务的输出日志
3. 使用 codebuddy /doctor 命令诊断问题

License

MIT