vite-plugin-ai-dev

把 AI 从项目的"外接设备"变成项目的"内置大脑"。 一个 Vite 插件，让AI 不再是项目“外接”的工具，而是项目本身的一部分 —— 感知、思考、执行，都在 dev server 里完成。

中文 · English

这是什么

一个 Vite 插件，让 Claude Code 在前端开发里做三件事：

1. 把交互从编辑器延伸到浏览器

不用装浏览器扩展、不用在编辑器 / 浏览器 / AI 对话三个窗口之间来回切：

• 页面里 Alt+Click 任意元素 → Claude 拿到精确的源码文件 + 行号 + 组件上下文
• 页面右侧常驻开发工作台 —— 多 tab 多轮对话、流式 markdown、每个 tab 独立 session
• 改动源码实时 HMR 回来，编辑器只负责最后 Review diff

2. 让 Claude 自动感知项目状态

Claude 启动即知 —— 不用每次开头说"我在改 Dashboard 页"：

• 当前路由、加载了哪些组件、依赖关系实时推到 Claude 手里
• 项目级 CLAUDE.md 随路由切换自动刷新，包含文件摘要、props、composables
• 8 个 MCP 工具把项目状态结构化暴露（get_page_context / get_errors / get_module_graph / ...），Claude 不用读整个 node_modules 就能理解项目，省大量 token

3. 运行时 / 编译错误自动修复

错误不再需要你手动贴报错、描述上下文：

• 运行时错误、Vue 警告、TypeScript 失败 —— 全自动捕获 + 分级 + 指纹去重
• 可选开启 autoFix: { enabled: true }：错误出现 → Claude 自动读源码 → 改好 → HMR 验证
• 修不好自动重试（up to maxAttempts），一路拿不下才报到你面前

4. 降低前端项目的上手门槛

对非前端开发者或新人来说，最大的成本不是写代码，而是理解项目。

• 不用翻遍源码找组件关系 —— 问 Claude "这个页面用了哪些组件"，MCP 直接返回结构化的依赖图
• 不用猜某个页面元素对应的源码在哪 —— Alt+Click 指一下，Claude 拿到精确的文件和行号
• 不用配环境就能调试 —— 报错自动捕获，Claude 直接告诉你原因和修复方案

一个人能看懂的项目，才是好项目。让 AI 帮你看懂，比写文档更有效。

这可能是未来前端开发的新形态：AI 不再是项目“外接”的工具，而是项目本身的一部分 —— 感知、思考、执行，都在 dev server 里完成。

安装

pnpm add -D vite-plugin-ai-dev
# 或
npm install -D vite-plugin-ai-dev

前置要求 —— PATH 里有 Claude Code CLI。没装也不会报错：插件自动降级（关 MCP / 关终端 / 关自动修复，但上下文采集继续跑）。

快速开始

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import aiDev from 'vite-plugin-ai-dev';

export default defineConfig({
  plugins: [vue(), aiDev()],
});

就这样。启动 vite dev，你会看到：

1. 页面右下角一个 Claude图标 —— 点开就能和 Claude 对话
2. Alt + 点击任意元素 → Claude 拿到精确的源码文件和行号
3. Claude Code 终端会自动拉起（不想要就 autoLaunch: false）
4. MCP 自动配置好，Claude 自己就知道当前路由、模块图、错误，不用你讲

配置

所有字段都是可选的，默认值基本够用。

aiDev({
  // --- Claude Code 终端 ---
  autoLaunch: true,       // 随 dev server 一起拉起 Claude 终端。默认: true
  claudeMode: 'terminal', // 'terminal' | 'split' | 'none'
  claudeArgs: [],         // 额外传给 claude 的参数

  // --- 页面内开发工作台（侧栏） ---
  selector: {
    enabled: true,        // 视觉选择器 + Alt+Click
    hotkey: 'alt',        // 'alt' | 'ctrl+shift' | 'ctrl+alt'
    ttlMs: 300_000,       // 选中信息保鲜时长
    showToast: true,
    devPanel: {
      enabled: true,      // 侧栏工作台
      timeoutMs: 600_000, // 单轮对话的 claude 超时
      model: 'opus',      // 本项目工作台默认模型。别名 (opus/sonnet/haiku) 或
                          // 完整 id 都行。tab 内 /model 会覆盖这里。
      theme: 'claude',    // 侧栏主题：'claude' | 'vscode' | 'terminal'
                          // 团队默认值；每个开发者可在 header 右侧的
                          // 切换按钮里选自己喜欢的，写入 localStorage 覆盖。
    },
  },

  // --- 浏览器控制（Chrome DevTools MCP）, 探索中---
  // chromeDevMcp: {
  //   enabled: false,                 // 需主动开启
  //   browserMode: 'use-current',     // 'use-current' | 'debug-port' | 'isolated'
  //   saveScreenshots: false,
  //   screenshotDir: '.ai-dev/screenshots',
  // },

  // --- 终端状态回显 ---
  statusLine: {
    enabled: undefined,   // 默认跟随 autoLaunch
    refreshInterval: 1,
  },

  // --- 出错自动修复 ---
  autoFix: {
    enabled: false,
    severities: ['fatal', 'error'],
    maxAttempts: 3,
    timeoutMs: 600_000,
    debounceMs: 2_000,
  },

  // --- MCP 服务 ---
  mcpPort: 3396,

  verbose: false,
});

兼容性

| | 支持范围 | |---|---| | Vite | >= 4.3（4.x / 5.x / 6.x 已测试） | | Node.js | >= 18 | | 操作系统 | Windows / macOS / Linux | | 框架 | Vue 3（完整）、React（运行期源码映射）、Svelte / Solid / Vanilla（仅路由级） |

功能与使用场景

Token 高效的 MCP 工具

一小组为项目状态量身设计的工具：

• get_page_context —— 当前页面加载了什么
• get_selected_element —— 最近一次 Alt+Click 的目标
• get_errors —— 去重 + 分级的错误列表
• get_module_graph —— Vite 依赖图（按路由或全量）
• get_project_overview / find_files / get_context / run_typecheck

什么时候用： 想让 Claude 了解项目又不想它把 node_modules 读五分钟。结构化摘要替代原文读取，省大量 token。

出错自动修复

可选。运行时错误、Vue 警告、TypeScript 失败会被自动捕获 + 分级 + 指纹去重；开启 enabled: true 后由 Claude 自动修好。

什么时候用： 重构过程中同一个红屏错误反复出现，你想要一个"自愈"回路。

视觉锚点 Visual Picker

Alt + 点击任意 DOM 元素 —— Claude 直接拿到精确的源码文件 + 行号 + 组件上下文。

什么时候用： 你说"这个按钮""那张卡片""这里的 hover"的时候。不用再花三句话描述 class 和层级，直接指就行。

终端 statusLine 回显

浏览器里的最新选中，实时（1s 刷新）回显到 Claude Code 终端底部状态栏。

什么时候用： 主要在终端干活，但想随时能看到"当前浏览器选中的是哪个元素"，不用切窗口。

Claude搬进网页

页面右侧常驻一个 Claude-for-Chrome 风格的侧栏，多 tab 多轮对话、流式 markdown 渲染、每个 tab 独立 session。

什么时候用： 不想离开浏览器。调 CSS、重命名变量、重构组件 —— 改完就在同一个窗口看到 HMR 生效。

/ 斜杠命令

工作台 composer 里支持一组和终端 Claude Code 类似的命令：

• /model → 切换本 tab 模型（Opus 做深度活、Haiku 做调色）
• /clear → 清屏，但 Claude 那边的会话记忆保留
• /new → 开全新会话（Claude 这边也从头开始）
• /help → 列出所有可用命令

什么时候用： 想在浏览器里拥有终端级的控制力，又不想真的去开终端。

切换主题

侧栏支持三套调色板，header 右上角的切换按钮可在浏览器里循环切换：

• claude（默认）—— 暖色奶油底 + 深色 chrome header，对齐 Claude for Chrome 扩展。
• vscode —— 整体深色，跟 VSCode + Claude 对话面板风格一致，深色 IDE 用户友好。
• terminal —— macOS 终端美学，GitHub Dark 配色 + 等宽字体 + >_ 提示符标识 + 终端绿光标，header 显示 ~/<项目名> (<框架>)。无 Claude 品牌元素，留作多 agent 接入用。

两层优先级：

• selector.devPanel.theme 是团队默认值，写在 vite.config.ts 里。
• 每个开发者可点 header 右上角的半圆按钮个人切换，选择写入浏览器 localStorage（key: __aiDevSidebarTheme__），覆盖团队默认。
• 想恢复团队默认：浏览器 DevTools 里删掉这个 key，刷新即可。

什么时候用： 团队成员审美不一致 —— 配置只定基线，每个人各自开心。

未来方向

以下是计划中或正在打磨的能力。

多元素选择

连续 Alt+Click 累积一组选区。让 Claude 一次处理"这三张卡片""所有 hover 态"这种复数操作，而不是一个一个改。

可插拔 Agent 接入

除了 Claude Code，接市面上其他成熟的编程 Agent，复用同一套视觉锚点 + 工作台 + MCP 工具：

• OpenAI Codex
• opencode
• 其它遵循 MCP 协议的 Agent

配置层面计划做成 agent: 'claude' | 'codex' | 'opencode'。

Chrome DevTools MCP 完整联动

当前标记"探索中"（配置被注释掉），打磨稳定后转正：

• 样式改动后自动 take_screenshot 验收
• 运行时报错自动读真实 console / network 数据（而不是猜 stack）
• 性能问题触发 performance_start_trace + 让 Claude 读 flame graph
• 一键 lighthouse_audit

更多框架的组件级视觉锚点

Svelte / Solid / Vanilla 目前只能追路由，未来做编译期注入，拿到类似 Vue 的组件级精度。

工作台能力扩展

• /compact —— 手动总结压缩当前会话
• 用户自定义 slash commands（读 .claude/commands/*.md 自动注册）
• MCP resource picker —— 在工作台里直接把资源喂给 Agent
• 历史会话搜索 + 持久化到磁盘（目前只 sessionStorage）

可视化 diff & 回滚

页面侧栏直接预览 Agent 改了哪些文件、哪些行，一键撤销。不用切到 VS Code 看 git diff。

跨 tab 协作

多个浏览器 tab 共享选区和对话上下文 —— "A tab 里试新方案，B tab 里对比旧版"。

联系作者

有 bug、想法、合作或只是想聊聊，都欢迎：

• 邮箱：[email protected]

License

MIT