vue-semantic-id-plugin

vue-semantic-id-plugin 是一个面向 Vue SFC 的 AI 辅助 codemod。它会扫描模板中的关键交互元素，调用 OpenAI-compatible 大模型接口生成语义化测试标识，然后直接把属性写回源码。

默认注入的是 data-testid，而不是 id。这样更适合自动化测试，也更稳。

当前范围

• Vue 3 SFC
• CLI codemod
• Vite 插件
• OpenAI-compatible API
• --dry-run 预览
• --write 写回源码
• 本地 JSON 缓存，避免重复请求模型

安装

npm install

使用

作为 Vite 插件接入

放在 vue() 前面：

import vue from '@vitejs/plugin-vue';
import semanticIdPlugin from 'vue-semantic-id-plugin';

const { createVueSemanticIdVitePlugin } = semanticIdPlugin;

export default {
  plugins: [
    createVueSemanticIdVitePlugin({
      apiKey: process.env.OPENAI_API_KEY,
      baseURL: 'https://api.openai.com/v1',
      model: 'gpt-4.1-mini',
      attributeName: 'data-testid',
      locale: 'zh-CN'
    }),
    vue()
  ]
};

如果你用的是 TypeScript / ESM 风格配置，也可以这样写：

import vue from '@vitejs/plugin-vue';
import semanticIdPlugin from 'vue-semantic-id-plugin';

const { createVueSemanticIdVitePlugin } = semanticIdPlugin;

export default {
  plugins: [
    createVueSemanticIdVitePlugin({
      apiKey: process.env.OPENAI_API_KEY,
      baseURL: 'https://api.openai.com/v1',
      model: 'gpt-4.1-mini'
    }),
    vue()
  ]
};

这个模式下，插件会在 Vite 处理顶层 .vue 文件时直接改写源码内容，不会落盘到你的源文件。

如果你担心模型接口限流，建议显式收紧并发并改成告警模式：

createVueSemanticIdVitePlugin({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.openai.com/v1',
  model: 'gpt-4.1-mini',
  maxConcurrentRequests: 1,
  maxRetries: 2,
  retryDelayMs: 1500,
  errorMode: 'warn'
})

这样即使短时出现 429 Too Many Requests，插件也会先做退避重试；如果最终还是失败，也只会告警并跳过当前文件，不会直接把整个 Vite 启动打崩。

Dry run

OPENAI_API_KEY=your-key \
vue-semantic-id src \
  --base-url=https://api.openai.com/v1 \
  --model=gpt-4.1-mini

Write

OPENAI_API_KEY=your-key \
vue-semantic-id src \
  --base-url=https://api.openai.com/v1 \
  --model=gpt-4.1-mini \
  --write

自定义属性名

OPENAI_API_KEY=your-key \
vue-semantic-id src \
  --base-url=https://api.openai.com/v1 \
  --model=gpt-4.1-mini \
  --attribute=id \
  --write

默认行为

• 只处理 .vue 文件
• 默认只处理关键交互元素：button、a、input、select、textarea
• 内建支持部分 Element UI / Element Plus 组件位点：el-button、el-input、el-select、el-textarea、el-date-picker、el-checkbox、el-radio
• 如果元素已有 data-testid、id 或对应的绑定属性，默认跳过
• 默认会跳过 type="hidden" 的 input
• 模型只负责给出“语义建议”，最终属性值会在本地做规范化、去重、回退兜底

环境变量

| 变量 | 说明 | |---|---| | OPENAI_API_KEY | 默认 API Key | | OPENAI_BASE_URL | 默认 base URL | | OPENAI_MODEL | 默认模型 |

关键参数

| 参数 | 默认值 | 说明 | |---|---:|---| | --write | false | 直接写回源码 | | --attribute | data-testid | 写入的属性名 | | --base-url | env/空 | OpenAI-compatible base URL | | --api-key | env/空 | API Key | | --model | env/空 | 模型名 | | --include | 空 | 只处理匹配路径 | | --exclude | 空 | 跳过匹配路径 | | --cache-path | .semantic-id-cache.json | 本地缓存文件 | | --locale | zh-CN | 让模型理解页面语义时使用的语言背景 | | --debug | false | 输出调试日志 |

Vite 插件配置

| 配置项 | 说明 | |---|---| | apiKey | OpenAI-compatible API Key | | baseURL | OpenAI-compatible base URL | | model | 模型名 | | attributeName | 注入属性名，默认 data-testid | | include / exclude | 路径过滤 | | locale | 语义理解语言提示 | | maxConcurrentRequests | Vite 下同时进行的模型请求数，默认 1 | | maxRetries | 429 重试次数，默认 2 | | retryDelayMs | 429 基础退避时间，默认 1500 毫秒 | | errorMode | warn / throw / silent，默认 warn | | componentRules | 追加或覆盖组件规则 | | provider | 高级用法，可直接传自定义 provider 实例 |

内建组件规则

当前版本内建了一层保守的组件规则，优先覆盖测试价值最高、且通常允许透传属性的 Element 组件：

| 组件 | 默认行为 | |---|---| | el-button | 作为按钮候选节点，支持直接注入 data-testid | | el-input | 作为输入框候选节点，优先利用 placeholder、aria-label 生成语义 | | el-select | 作为下拉选择候选节点 | | el-textarea | 作为多行输入候选节点 | | el-date-picker | 作为日期选择候选节点，带上 type、start-placeholder、end-placeholder 等提示 | | el-checkbox | 作为复选框候选节点，优先利用 slot 文本和 label 属性 | | el-radio | 作为单选项候选节点，优先利用 slot 文本和 label 属性 |

如果后面要扩展更多组件库，可以继续把规则加到 componentRules。

另外，当前版本会读取最近一层 el-form-item 的 label 作为上下文。
这意味着像下面这种结构，模型会同时看到“预约日期”这个表单语义和组件自身的 placeholder/type 提示：

<el-form-item label="预约日期">
  <el-date-picker type="daterange" start-placeholder="开始日期" end-placeholder="结束日期" />
</el-form-item>

输出约定

模型会返回两类信息：

• semanticLabel：中文或指定语言的人类可读语义，便于报告阅读
• semanticKey：推荐的 kebab-case 英文键，作为最终测试标识候选

最终写入值会经过本地校验：

• 统一转为 kebab-case
• 去掉非法字符
• 文件内去重
• 为空时自动回退到稳定兜底值

设计取舍

这个项目故意不做成“每次构建都在线调用模型”的 webpack/vite build 插件。原因很简单：

• 构建时联网不稳定
• 成本不可控
• 模型输出有波动时会让构建结果不确定

所以当前版本定位是“代码改写工具”，适合在开发、测试整理、批量补标识时运行。

开发

npm test