annotai

ANNOTAI

让 AI 看见你
在说哪个元素

在浏览器里框选元素，复制带 file:line:col 的 Markdown 交给 AI，或按住 Alt+Shift 点击跳转到编辑器中的源码

快速开始
npm install -D annotai

为什么用 annotai

把「那个蓝色的按钮」翻译成 AI 和编辑器都能精确定位的源码坐标

框选标注

拖拽即选，自动解析到组件源码位置，不用手写选择器

明文位置

每个元素带 data-annotai-path，DevTools 里直接可读

复制 Markdown

把标注整理成结构化问题清单，粘贴给任何 AI 工具即可

编辑器跳转

Alt+Shift 点击直达编辑器中的源码行列

快速开始

三步接入，dev 服务即开即用

1

安装

npm install -D annotai
2

接入 Vite

// pnpm add -D @vitejs/plugin-react
import react from '@vitejs/plugin-react'
import { annotate } from 'annotai/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [annotate(), react()],
})
3

框选、复制、跳转

pnpm dev

# 页面右下角打开面板 → 框选元素 → 备注问题
# 复制 Markdown 交给 AI，或 Alt+Shift 点击跳转到编辑器

全部配置

均可省略，默认值开箱即用；按需覆盖即可

配置默认说明
editor自动发现跳转编辑器：默认自动发现 Neovim，无实例时回退运行中的 IDE；open 钩子可接任意编辑器
hotKeys['altKey', 'shiftKey']打开编辑器的修饰键组合，可选 altKey / shiftKey / ctrlKey / metaKey；空数组关闭
hoverPreviewtrue悬停源码预览；对象形式可调卡片宽度与行数
locale'en'界面与 Markdown 导出语言
surroundingLines4源码片段上下各附带的行数（0–100）
context4 开 1 关Markdown 字段开关：位置、片段、类名、文本默认开启，DOM 路径关闭
animationtrue面板与高亮交互动画；系统减少动态效果偏好优先
theme内置面板淡出透明度与任意 --sn-* CSS 变量覆盖
formatCopy内置浏览器端自定义剪贴板内容；函数以源码内联，须自包含
onCopy—Node 侧复制钩子：收到最终 Markdown 与全部标注，可派发给 agent 改代码；异步执行不阻塞浏览器
maxBodyBytes2 MB源码服务单个请求体上限（字节）
projectRootworkspace rootMarkdown 相对路径基准，不扩大可读取目录
allowedRoots[vite.root]可处理源码的目录，符号链接按真实路径校验
transforms[reactTransform]语法适配器，按顺序取第一个支持当前文件的；Vue / Solid 换内置对应转换器
clienttrue是否注入浏览器工具栏

两个复制钩子

浏览器端改写剪贴板内容，Node 端接住每次复制

annotate({
  // 浏览器端：自定义剪贴板内容（函数以源码内联，须自包含）
  formatCopy: ({ annotations, fields }) => annotations.map((a) => a.question).join('\n'),

  // Node 端：复制后把上下文派发给 agent 改代码
  onCopy: ({ markdown }) => {
    spawn('pi', ['-p', markdown], { stdio: 'inherit' })
  },
})

常见问题

支持哪些前端框架？

React、Vue 3、Solid

生产构建会注入标注属性吗？

不会。属性注入与源码服务仅在 dev / preview 启用，build 产物零残留

HMR 之后旧标注还能用吗？

文件变动后，旧标注会提示重新框选，不会指向错误的源码