@tntd/code-inspector-plugin

code-inspector-plugin 的封装。就做两件事：

1. 弹窗：按住 Option + Shift（默认快捷键）点击页面元素，弹出输入框写补充说明；
2. 打开 Codex：确认后打开 Codex 新会话，提示词里带上「代码位置 + 说明 + 工作目录」。

它复用 code-inspector-plugin 的编译期源码定位能力，只把它内置的“跳转 IDE”（Locate Code）默认关掉。

安装

npm i -D @tntd/code-inspector-plugin

使用

只需要在开发构建配置里注册插件，业务代码一行都不用改。

// webpack 开发配置，例如 build/webpack.dev.conf.js
const { tntdCodeInspectorPlugin } = require('@tntd/code-inspector-plugin');

plugins: [
  tntdCodeInspectorPlugin({
    bundler: 'webpack',
    codex: { root: process.cwd() }, // Codex 新会话的工作目录
  }),
];

// vite 配置
import { tntdCodeInspectorPlugin } from '@tntd/code-inspector-plugin';

plugins: [tntdCodeInspectorPlugin({ bundler: 'vite' })];

两点说明：

• 开发/生产由构建配置决定：插件只写在开发配置里，生产配置不引入就不生效，业务代码不需要写 if (process.env.SYS_ENV === 'development') 这类判断；
• webpack / rspack 下浏览器侧脚本由插件自动挂到入口文件，业务入口不需要 require。vite 没有同等的入口注入点，需要在入口 import '@tntd/code-inspector-plugin/client'。

配置项

除 codex 外的选项（bundler、hotKeys、showSwitch、port 等）全部透传给 code-inspector-plugin。

| 选项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | codex.root | string | process.cwd() | Codex 新会话的工作目录，会注入产物作为深链接的 path 参数 | | codex.injectClient | boolean | true | 是否把浏览器侧脚本挂到入口文件；设为 false 后自行 import '@tntd/code-inspector-plugin/client' | | codex.clientEntry | string \| string[] | 构建配置的 entry | 显式指定要注入的入口文件，仅入口是函数等无法静态解析时需要 |

工作目录的注入方式：webpack/rspack 用 DefinePlugin 把 __TNTD_CODEX_INSPECTOR_PROJECT_PATH__ 内联进产物； vite 用 config 钩子写 define。浏览器侧取不到时会省略 path 参数，不会生成 path=undefined。

插件默认关闭 behavior.locate 和底层 behavior.copy；路径复制由浏览器侧脚本自动完成，设置面板不再显示 Copy Path。 editor、server 等选项都不覆盖，手动打开 Locate Code 后，点击元素走的仍是它原本的跳转 IDE 链路 （IDE 由它自动探测，也可以在项目 .env.local 里用 CODE_EDITOR=code 指定）。

页面上的 Locate Code 开关决定点击元素走哪条路：

| Locate Code | 点击元素的结果 | | --- | --- | | 关闭（默认） | 弹出 Codex 说明框 | | 手动打开 | 跳转 IDE 并定位到源码，不再弹 Codex 说明框 |

指定跳转的编辑器

mac 上 launch-ide 靠 ps ax -o comm= 找正在运行的 IDE 来识别编辑器，识别不到就什么也不打开 （只会在终端打印 Failed to recognize IDE automatically）。它自己的 editor 选项只用于在探测到的编辑器里挑选， 兜底读的是 EDITOR / VISUAL，所以插件会把显式指定的 editor 同步到 EDITOR：

tntdCodeInspectorPlugin({
  bundler: 'webpack',
  editor: 'code', // 点击 Locate Code 时用 VS Code 打开并定位
});

这样即使 VS Code 没在运行也能被拉起来。如果使用者自己已经设置了 EDITOR，插件不会覆盖。

行为

1. code-inspector-plugin 在编译期给 DOM 打上 data-insp-path（源码文件:行:列）；
2. 按住 Option + Shift 点击元素 → 浏览器侧弹窗显示该位置，等你输入说明；
3. 确认后拼出 codex://threads/new?prompt=...&path=... 并在浏览器里打开。

手动打开页面上 Locate Code 后，第 2、3 步让位给 code-inspector-plugin 自己的跳转 IDE。

注意

• 深链接只预填、不发送：Codex 打开新会话后提示词停在输入框，需要你自己回车发送。
• 不支持在深链接里指定分支：Codex 深链接只认 prompt / path / originUrl。需要固定分支时，先用 git worktree add 准备该分支目录，再让 codex.root 指向它。