agent-source-locator

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react' // 或 @vitejs/plugin-react-swc
import { agentSourceLocator } from 'agent-source-locator'

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

顺序无所谓——插件是 enforce: 'pre'，永远先于 React 的编译器拿到源码。Babel 版和 SWC 版都能用，因为注入完全不碰你的 JSX 编译链路。

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { agentSourceLocator } from 'agent-source-locator'

export default defineConfig({
  plugins: [agentSourceLocator(), vue()],
})

需要 Vue 3 SFC。@vue/compiler-sfc 是懒加载的，纯 React 项目不会为它付出任何代价。

构建工具报出的路径是相对它自己的 root 的，而 monorepo 里那就是子包目录。所以 apps/web/src/pages/Home.vue 这个文件产出的是：

src/pages/Home.vue:116:13

你的 Agent 从仓库根出发根本找不到它。声明一个前缀即可：

// vite.config.ts
agentSourceLocator({ pathPrefix: '@web' })

// webpack.config.js / rspack.config.js
new AgentSourceLocatorPlugin({ pathPrefix: '@web' })

// next.config.ts
withAgentSourceLocator(nextConfig, { pathPrefix: '@web' })

@web/src/pages/Home.vue:116:13

前缀是自由格式的——写成什么能让你的 Agent 找到文件，就写成什么。

只有当前缀以字母或数字结尾（也就是看起来像个目录名）时才会插入 / 分隔符。这样单独一个 @ 就能直接粘在路径前面——这一点很关键，因为 Agent CLI 会把 @some/path 当作文件引用来解析，而不是普通文本：

端点会拒绝任何含 .. 的路径，所以 ../web 这样的前缀会让每次点击都静默地校验失败。配了这种前缀时插件会给出警告。

配置可以写在文件里而不是构建配置里，这样个人改自己的设置就不会动到团队共享的部分：

// asl.config.json —— 提交进仓库
{ "pathPrefix": "apps/web" }

// asl.config.local.json —— 加进 gitignore
{ "terminal": false }

terminal: false 会保留 overlay 和剪贴板，但永远不往终端写。此时 toast 只显示 copied to clipboard——因为那本来就是预期的全部结果，而不是什么东西失败了。

两个文件都是从项目根目录向上查找的，所以 monorepo 可以在仓库根放一份共享的 asl.config.json，而任意子包——或任意一个开发者——都能在更近的位置覆盖它。

优先级从高到低：

文件层高于构建配置是有意为之：如果写死在代码里的选项优先级更高，那么一个已提交的 vite.config.ts 就会让本地文件什么都覆盖不了——而那正是本地文件存在的全部意义。

可识别的键是 terminal、pathPrefix 和 port。写错的键会给出警告而不是被静默忽略， 文件格式损坏时会回退到默认值，而不是让 dev server 挂掉。

Next 那边，instrumentation.ts 通常只是一行 re-export，没地方传参数，所以请用配置文件 或环境变量——也可以直接调用：

import { register as start } from 'agent-source-locator/next/instrumentation'
export const register = () => start({ terminal: false })

默认两个 transform 都开着，但各自只对认识的文件生效（.jsx/.tsx 与 .vue），所以单框架项目本来就没有额外开销。想显式指定也可以：

agentSourceLocator({ frameworks: ['react'] })  // 完全跳过 .vue

// webpack.config.js（ESM）
import { AgentSourceLocatorPlugin } from 'agent-source-locator/webpack'

export default {
  mode: 'development',
  plugins: [new AgentSourceLocatorPlugin()],
  devServer: { port: 3000 },
}

// webpack.config.cjs（CommonJS）
const { AgentSourceLocatorPlugin } = require('agent-source-locator/webpack')

module.exports = {
  mode: 'development',
  plugins: [new AgentSourceLocatorPlugin()],
}

插件会自己搞定全部三件事：把 loader 注册为 .jsx/.tsx 的 pre 规则、把 overlay 追加到每个 entry、把 /__asl/emit 挂到 devServer 上。

两个需要注意的点：

• mode 不能是 production —— 是的话插件会直接返回。webpack serve 默认是 development，但如果共用配置里写死了 mode: 'production'，插件会静默失效。
• 插件会读 devServer.host。如果你把服务暴露到 localhost 之外，终端注入会自动关闭，只保留剪贴板。

与 webpack 完全一致——rspack 实现了同样的 plugin 和 dev-server 契约，只是引入路径不同：

// rspack.config.js
import { AgentSourceLocatorPlugin } from 'agent-source-locator/rspack'

export default {
  mode: 'development',
  plugins: [new AgentSourceLocatorPlugin()],
  devServer: { port: 3000 },
}

需要安装 @rspack/dev-server，端点才会被挂载。

Turbopack（Next 16 起的默认构建器）不支持 webpack plugin，但支持 webpack loader。插件本来一次做完的另外两件事，只能分别接到 Next 自己的钩子上——所以是三个文件而不是一个。

1. next.config.ts —— 通过 turbopack.rules 注册 loader，并把 /__asl/* 重写到 sidecar，使端点保持同源：

import type { NextConfig } from 'next'
import { withAgentSourceLocator } from 'agent-source-locator/next'

const nextConfig: NextConfig = {
  // ...你的配置
}

export default withAgentSourceLocator(nextConfig)

2. instrumentation.ts —— 放在项目根目录，与 next.config.ts 同级；如果项目用了 src 目录，则放在 src/ 下。不要放进 app/。register() 是唯一在 dev server 启动时执行 Node 代码的钩子，sidecar 就在这里启动：

export { register } from 'agent-source-locator/next/instrumentation'

如果你已经有自己的 register，从里面调用我们的：

export async function register() {
  await (await import('agent-source-locator/next/instrumentation')).register()
  // ...你自己的初始化
}

3. app/layout.tsx —— Turbopack 没有注入 script 标签的钩子，所以 overlay 要从组件树里引入。它不渲染任何内容：

import { AgentSourceLocator } from 'agent-source-locator/next/client'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh">
      <body>
        {children}
        <AgentSourceLocator />
      </body>
    </html>
  )
}

补充说明：

• server component 和 client component 都能定位——loader 作用于所有 .tsx，所以服务端渲染出的标签同样带属性。
• sidecar 监听 127.0.0.1:7091。同时跑多个 Next 项目时，用 ASL_PORT 指定一个空闲端口——next.config.ts 和 instrumentation.ts 都会读它，一个变量就够。
• 这一节针对的是 Next 默认的 Turbopack。next dev --webpack 未经测试——那种情况下 loader 需要改从 next.config 的 webpack() 钩子注册，而不是 turbopack.rules。

每个应用各自接入、各自声明前缀，不存在仓库级的统一配置：

// apps/web-vue/vite.config.ts
agentSourceLocator({ pathPrefix: 'apps/web-vue' })

// apps/web-next/next.config.ts
withAgentSourceLocator(nextConfig, { pathPrefix: 'apps/web-next' })

然后在仓库根目录 attach 一次就够：

cd <仓库根目录> && npx agent-source-locator attach

绑定关系的查找会逐级向上冒泡，所以底下每个应用都会命中这一条记录，全部写进同一个终端。在两个应用之间来回点，结果会交替累积在同一行：

❯ apps/web-vue/src/App.vue:13:5 apps/web-next/app/Counter.tsx:10:7 apps/web-vue/src/App.vue:16:5

各应用抵达终端的通道并不相同，这一点只在规划端口时才需要关心：

所以任意多个 Vite/webpack 应用都能共存。但两个及以上的 Next 应用会争抢 7091。 后启动的那个仍会正常启动——它只是打印一条「端口被占用」的日志，然后在没有自己 sidecar 的情况下运行，也就是说它的点击会由第一个应用的 sidecar 处理。如果两个应用继承的是同一条仓库根 attach 记录，结果依然会落到正确的终端；但想让它们彼此独立，就给其中一个换个端口：

ASL_PORT=7092 next dev

next.config.ts 和 instrumentation.ts 读的是同一个变量，设一次就同时管住 rewrite 目标和 sidecar。

同一个仓库的两份 checkout（git worktree，或者直接复制的目录）各跑一套 dev 时也会撞上同样的问题。各 worktree 的 dev 端口通常是按偏移整体平移的，但 7091 不会跟着走，于是第二份会静默借用第一份的 sidecar，点击落进另一份 checkout 对应的终端。现在抢不到端口时，插件会指名道姓：

[agent-source-locator] clicks from /repo-b will be typed into the terminal
attached to /repo-a. Set ASL_PORT to a free port to keep them separate.

给每个 worktree 配一个跟它 dev 端口配套的 ASL_PORT 即可。

残留的 sidecar

sidecar 跑在 Next dev server 进程内部，所以 Ctrl+C 会连它一起带走。但关掉终端窗口、或者杀掉启动器进程时，next-server 会继续存活——Next 不会随父进程退出，而幸存下来的那个进程同时占着 dev 端口和 7091。

这种情况下 sidecar 会察觉自己已被 init 收养，并在约 30 秒内让出端口，好让下一个 dev server 起自己的：

[agent-source-locator] parent process is gone; releasing the sidecar port
so a new dev server can start its own.

dev server 本身是故意不动的——要不要杀掉它不该由这个工具决定。如果某个残留实例挡了路，Next 会直接告诉你它的 pid（Another next dev server is already running… PID: 12345），或者：

lsof -ti:7091   # 看谁占着 sidecar 端口

一个应用以 iframe 嵌入另一个

可以用，除了两个应用各自接入之外不需要任何额外配置：

• iframe 是独立的 document，有自己的 overlay，所以在它内部的悬浮和点击都由它自己处理。父页面的 overlay 看不到 iframe 里的元素，反之亦然——不会出现双重高亮。
• iframe 内发出的请求打到被嵌入应用自己的 origin（localhost:5599/__asl/emit，而不是父页面的），所以同源校验和 Next 的 rewrite 都照常工作。
• 按住 Alt 时，无论焦点在哪个 document 上都能生效——overlay 是从鼠标事件里读这个修饰键的，而不是追踪键盘状态，正是因为没有焦点的 iframe 收不到任何键盘事件。

父页面这边需要加一件事，前提是你希望 iframe 内的剪贴板兜底也能用：

<iframe src="http://localhost:5599" allow="clipboard-write"></iframe>

不加的话，浏览器会拒绝跨域 iframe 的剪贴板写入（端口不同即为不同 origin）。终端注入不受影响——那条链路根本不经过剪贴板。