vite-plugin-opencode-assistant

vite-plugin-opencode-assistant

在 Vite 开发环境中嵌入 OpenCode AI 助手，实现边聊天边改代码、即时预览的开发体验。

它能做什么

• 悬浮 AI 面板 - 在页面右下角注入悬浮按钮，支持拖拽定位和边缘磁吸
• 自动启动服务 - 自动启动本地 OpenCode Web 服务，无需手动操作
• 智能会话管理 - 自动复用当前项目的会话，支持创建、切换、删除会话
• 实时状态显示 - 会话列表显示思考状态指示器，了解 AI 当前工作状态
• 页面上下文同步 - 自动同步当前页面 URL、标题给 AI，SPA 路由切换时实时更新
• 元素选择器 - 通过快捷键在页面上点选元素，将组件源码位置信息传给 AI
• 主题同步 - 挂件主题与 OpenCode Web 主题实时同步
• 代理服务 - 内置代理服务器解决 iframe 跨域限制，确保 OpenCode Web 功能完整
• Chrome DevTools 预热 - 启动时自动预热浏览器工具链，减少首次使用等待
• 日志查看 - 提供日志接口，方便 Agent 获取开发服务器输出

效果演示

启动 Vite 开发服务器后：

1. 页面右下角出现悬浮按钮
2. 点击按钮展开 OpenCode 对话面板
3. 直接在面板中与 AI 对话，修改代码
4. Vite HMR 即时刷新，立即看到修改效果

安装

npm install -D vite-plugin-opencode-assistant

前置条件

需要本机已安装 OpenCode CLI：

curl -fsSL https://opencode.ai/install | bash

或使用包管理器：

npm i -g opencode-ai@latest
brew install anomalyco/tap/opencode

验证安装：

opencode --version

快速开始

最小配置

import { defineConfig } from "vite";
import opencodeAssistant from "vite-plugin-opencode-assistant";

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

完整配置示例

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import opencodeAssistant from "vite-plugin-opencode-assistant";

export default defineConfig({
  plugins: [
    vue(),
    opencodeAssistant({
      enabled: true, // 是否启用插件
      webPort: 5097, // OpenCode Web 服务端口
      proxyPort: 6097, // 代理服务端口
      hostname: "127.0.0.1", // 服务绑定地址
      theme: "auto", // 主题: light | dark | auto
      open: false, // 是否自动展开面板
      verbose: false, // 是否输出详细日志
      hotkey: "ctrl+k", // 切换面板的快捷键
      warmupChromeMcp: true, // 是否预热 Chrome DevTools MCP

      // OpenCode 界面语言（可选）
      language: "zh",

      // OpenCode 内部设置（可选）
      settings: {
        general: {
          showReasoningSummaries: true,
          followup: "suggest",
        },
        appearance: {
          fontSize: 14,
        },
      },
    }),
  ],
});

启动开发服务器：

npm run dev

配置项

配置项	类型	默认值	说明
enabled	boolean	true	是否启用插件
webPort	number	5097	OpenCode Web 服务端口，被占用时自动向后寻找可用端口
proxyPort	number	6097	代理服务端口，用于解决 iframe 跨域限制
hostname	string	"127.0.0.1"	服务绑定地址
theme	string	"auto"	挂件主题：light | dark | auto（跟随系统）
open	boolean	false	页面加载后是否自动展开面板
verbose	boolean	false	是否输出详细调试日志
hotkey	string	"ctrl+k"	切换面板的快捷键，macOS 支持 cmd+k
warmupChromeMcp	boolean	true	启动后是否预热 Chrome DevTools MCP
language	string	-	OpenCode 界面语言，如 zh、en、ja 等
settings	object	-	OpenCode 内部设置，详见下方说明

OpenCode 设置

settings 配置项用于自定义 OpenCode Web 的内部行为：

{
  general: {
    autoSave?: boolean;              // 自动保存
    releaseNotes?: boolean;          // 显示更新说明
    followup?: "steer" | "suggest" | "none";  // 后续动作模式
    showReasoningSummaries?: boolean; // 显示推理摘要
    shellToolPartsExpanded?: boolean; // 默认展开 shell 工具
    editToolPartsExpanded?: boolean;  // 默认展开编辑工具
  },
  appearance: {
    fontSize?: number;   // 界面字体大小
    mono?: string;       // 代码字体
    sans?: string;       // 界面字体
  },
  permissions: {
    autoApprove?: boolean;  // 自动批准权限请求
  },
  notifications: {
    agent?: boolean;      // 智能体完成时通知
    permissions?: boolean; // 权限请求时通知
    errors?: boolean;     // 错误时通知
  },
  sounds: {
    agentEnabled?: boolean;       // 启用智能体音效
    agent?: string;               // 智能体音效
    permissionsEnabled?: boolean; // 启用权限音效
    permissions?: string;         // 权限音效
    errorsEnabled?: boolean;      // 启用错误音效
    errors?: string;              // 错误音效
  },
}

使用指南

打开对话面板

• 点击页面右下角悬浮按钮
• 或使用快捷键 Ctrl/Cmd + K

会话管理

面板左侧显示当前项目的会话列表，支持：

• 查看已有会话
• 新建会话
• 切换会话
• 删除会话

页面上下文同步

挂件自动同步以下信息：

• 当前页面 URL
• 当前页面标题
• 选中的页面元素

监听的事件包括：

• history.pushState / history.replaceState
• popstate / hashchange
• document.title 变化

元素选择模式

通过快捷键（默认 Ctrl/Cmd + P）进入选择模式：

1. 按下快捷键，鼠标变为选择状态
2. 点击页面上的元素
3. 元素信息（文件路径、行号、文本内容）自动传给 AI

注意：元素选择依赖 Vue Inspector，如果页面中没有可用的 Inspector，会提示无法使用该功能。

内部接口

插件在 Vite 开发服务器上注册以下内部接口：

路径	说明
/__opencode_widget__.js	浏览器端挂件脚本
/__opencode_start__	服务启动状态与会话地址
/__opencode_context__	页面上下文读写
/__opencode_sessions__	会话查询、创建、删除
/__opencode_events__	SSE 事件流（会话就绪、节点清空等）
/__opencode_logs__	日志查询（OpenCode 进程输出、Vite 日志等）

常见问题

OpenCode not installed

确认命令行可以正常执行：

opencode --version

端口冲突

如果默认端口被占用，插件会自动向后寻找可用端口。也可以手动指定：

opencodeAssistant({
  webPort: 5001,
  proxyPort: 5002,
});

元素选择不可用

需要页面中有 Vue Inspector 钩子。插件已内置 unplugin-vue-inspector，无需额外配置。

生产构建不包含挂件

这是预期行为。插件仅在开发模式（vite serve）下工作，不会影响生产构建。

License

MIT

相关链接

• OpenCode
• OpenCode GitHub
• Vite Plugin API