vite-plugin-spm-bridge

⚠️ 本项目已废弃（Archived）

经评估，本项目存在重复造轮子的嫌疑：对于人类前端开发者，已有 Vue DevTools 等更成熟的调试工具；对于 AI/自动化场景，其核心价值与现有方案重叠，且缺乏足够的差异化竞争力。因此决定停止维护，代码仅作存档参考，请勿在生产环境中使用。

🚧 本项目处于测试阶段，API 和实现细节可能随时调整，请勿在生产环境或关键项目中使用。

一个 Vite 开发服务器插件，帮助非视觉类 AI（或自动化脚本）通过页面上的 data-spm 标记精确定位元素及其对应的 Vue/TSX 源码位置。它会在开发页面注入一个客户端 SDK，并在本地暴露 REST API，支持查询、定位以及（可选的）自动修改源码。

提示：本插件仅在 vite dev（serve 模式）下生效，不会影响生产构建。

---

核心特性

• 🔍 基于 data-spm 定位：复用项目中已有的 SPM 埋点标识，无需额外添加属性。
• 🌐 暴露本地 REST API：AI Agent 可以通过 HTTP 接口批量查询元素对应的源码路径与行号。
• ✏️ 可选的源码自动修改：开启 allowModify 后，支持通过 API 安全地替换或插入代码行。
• 🖱️ 浏览器端可视化辅助：提供元素拾取模式（高亮、点击选择、底部面板），方便人工复核。
• 🛡️ 安全限制：默认关闭写操作，且所有写路径都受限于项目根目录，每次修改前自动创建 .bak 备份。

---

安装

本项目暂未发布到 npm，需要先本地克隆并构建，再引入到你的项目中使用。

git clone git@github.com:conglinyizhi/vite-plugin-spm-bridge.git
cd vite-plugin-spm-bridge
pnpm install
npm run build

构建完成后，产物会输出到 dist/ 目录。你可以通过相对路径或 file: 协议将其引入主项目（详见下方的「本地开发」章节）。

本插件将 vite >= 5.0.0 作为 peerDependency。

---

快速使用

在 vite.config.ts 中引入并配置：

import { defineConfig } from 'vite'
import spmBridge from 'vite-plugin-spm-bridge'

export default defineConfig({
  plugins: [
    spmBridge({
      // 扫描哪些文件（默认仅 .vue）
      include: ['**/*.vue', '**/*.tsx'],
      // 允许通过 API 修改源码（默认 false）
      allowModify: true,
    })
  ]
})

启动开发服务器后，插件会自动在页面注入客户端脚本。打开浏览器，按 Alt + P 即可进入元素拾取模式。

---

工作原理

服务端（Vite Dev Server）

插件注册了一组开发服务器中间件（默认前缀 /__spm__）：

方法	路径	说明
GET	/{prefix}/client	提供浏览器端 SDK 脚本
GET	/{prefix}/settings	读取项目根目录下的 .spm-bridge.json
POST	/{prefix}/list	返回所有扫描到的 data-spm 标记
POST	/{prefix}/locate	根据单个 SPM 值返回文件路径、行号与上下文
POST	/{prefix}/locate-batch	批量定位
POST	/{prefix}/pick-result	接收浏览器端手动选中的元素并补充源码上下文
POST	/{prefix}/modify	需开启 allowModify。替换指定文件的某一行
POST	/{prefix}/insert-after	需开启 allowModify。在指定行后插入内容
POST	/{prefix}/settings	保存设置到 .spm-bridge.json

客户端（浏览器）

页面加载后，全局暴露 window.__SPM__ SDK。默认快捷键：

• Alt + P：进入/退出元素拾取模式
• Esc：退出拾取模式
• 按住 Alt：临时隐藏底部面板

---

配置项

interface SpmBridgeOptions {
  /** 是否启用插件（默认 true） */
  enabled?: boolean
  /** API 路由前缀（默认 '/__spm__'） */
  prefix?: string
  /** 扫描文件匹配规则（默认 ['**/*.vue']） */
  include?: string[]
  /** 排除规则（默认 ['node_modules', 'dist', '.git']） */
  exclude?: string[]
  /** 返回上下文行数（默认 5） */
  contextLines?: number
  /** 是否允许通过 API 修改源码（默认 false） */
  allowModify?: boolean
}

---

本地开发（不发布 npm）

如果你希望直接把源码放在主项目里使用，可以先构建出 dist/，再通过相对路径或 file: 协议引入：

# 在插件目录中
pnpm install
npm run build

然后在主项目的 vite.config.ts 中：

// 方式一：直接引用构建产物
import spmBridge from '../packages/vite-plugin-spm-bridge/dist/index.js'

// 方式二：使用 file: 本地安装
// pnpm add file:../packages/vite-plugin-spm-bridge
// import spmBridge from 'vite-plugin-spm-bridge'

注意：修改 src/ 源码后需要重新执行 npm run build。

---

开发命令

pnpm install       # 安装依赖
pnpm run dev       # 本地自托管开发（插件作用在自己身上）
pnpm run build     # 完整构建：client.js + ESM 服务端 + 类型声明

---

安全提示

• 源码修改默认关闭，请仅在受信任的本地开发环境中开启 allowModify: true。
• 所有写文件操作都会校验目标路径，禁止跳出项目根目录。
• 每次修改前会自动生成 .bak 备份文件。

---

许可证

MIT