vite-plugin-ai-dev

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

中文 · English

这是什么

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

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

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

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

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

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

• 当前路由、加载了哪些组件、依赖关系实时推给当前 Agent
• 8 个 MCP 工具把项目状态结构化暴露（get_page_context / get_errors / get_module_graph / ...），无需读完整个 node_modules 就能理解项目，省大量 token
• Claude 模式额外维护项目级 CLAUDE.md；Codex 模式通过 MCP instructions + 工具获得同一套运行时上下文

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

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

• 运行时错误、Vue 警告、TypeScript 失败 —— 全自动捕获 + 分级 + 指纹去重
• 可选开启 autoFix: { enabled: true }：错误出现 → 当前 Agent 自动读源码 → 改好 → 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 里至少有一个受支持的 CLI：Claude Code 或 OpenAI Codex。配置的 Provider 未安装时会自动使用另一个已安装的 CLI；两个都未安装时插件直接禁用，本次 dev server 不再启动 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()],
});

默认仍使用 Claude Code。启动 vite dev，你会看到：

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

要改用 Codex：

aiDev({
  agent: 'codex',
  codex: {
    sandbox: 'workspace-write',
    approval: 'never',
  },
});

配置

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

aiDev({
  // --- Agent ---
  agent: 'claude',        // 'claude' | 'codex' | 'auto'，默认 claude
  autoLaunch: true,       // 随 dev server 拉起所选 Agent。默认: true

  // Claude Code
  claudeMode: 'terminal', // 'terminal' | 'split' | 'none'
  claudeArgs: [],         // 额外传给 claude 的参数

  // OpenAI Codex
  codex: {
    mode: 'terminal',     // 'terminal' | 'split' | 'none'
    args: [],
    sandbox: 'workspace-write',
    approval: 'never',
    projectMcpConfig: false, // 实验选项；默认通过每次进程的 -c 注入 MCP
  },

  // --- 页面内开发工作台（侧栏） ---
  selector: {
    enabled: true,        // 视觉选择器 + Alt+Click
    hotkey: 'alt',        // 'alt' | 'ctrl+shift' | 'ctrl+alt'
    ttlMs: 300_000,       // 选中信息保鲜时长
    showToast: true,
    devPanel: {
      enabled: true,      // 侧栏工作台
      timeoutMs: 14_400_000, // 单轮 Agent 对话超时（默认 4 小时）
      model: 'opus',      // Claude 默认 opus；Codex 默认留空走 CLI 配置
      theme: 'dark',    // 侧栏主题：'light' | 'dark'
                          // 团队默认值；每个开发者可在 header 右侧的
                          // 切换按钮里选自己喜欢的，写入 localStorage 覆盖。
    },
  },

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

  // --- Claude Code statusLine 回显（Claude-only） ---
  statusLine: {
    enabled: undefined,   // 默认跟随 autoLaunch
    refreshInterval: 1,
  },

  // --- 出错自动修复 ---
  autoFix: {
    enabled: false,
    severities: ['fatal', 'error'],
    maxAttempts: 3,
    timeoutMs: 14_400_000,
    debounceMs: 2_000,
    model: 'haiku',       // Claude 默认 haiku；Codex 默认走 CLI 配置
  },

  // --- 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 自动修好。

默认走 model: 'haiku'（小问题用小模型，快又便宜），修不动可以升 'sonnet' / 'opus'。详见 autoFix.model。

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

视觉锚点 Visual Picker

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

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

终端 statusLine 回显

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

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

Agent 搬进网页

页面右侧常驻一个简洁的 Vite 品牌侧栏，多 tab 多轮对话、流式 markdown 渲染、每个 tab 独立 session。

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

/ 斜杠命令

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

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

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

切换主题

侧栏只保留两套 Vite 品牌主题，header 右上角的按钮可在两者之间切换：

• light — 明亮背景、白色卡片和 Vite 紫蓝强调。
• dark — 深海军蓝背景、紫色卡片和青蓝语法强调（默认）。

两套主题共用同一套布局和 Vite 图标，旧版的 claude、vscode、terminal 值作为兼容别名自动映射。

多元素选择

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

更多可插拔 Agent

当前已支持 Claude Code 与 OpenAI Codex。后续继续复用同一套视觉锚点 + 工作台 + MCP 工具接入：

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

当前配置为 agent: 'claude' | 'codex' | 'auto'；新 Provider 会继续扩展这个联合类型。

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