油猴脚本工程脚手架

要解决的工程问题

写一个 Tampermonkey 用户脚本，远不止在页面里插一段代码。首先要判断这件事该不该由 userscript 来做：浏览器工具栏、新标签页、右键菜单属于扩展的领地；拦截或改写页面自身的网络请求，userscript 做不到，只能发送请求；纯粹改样式用 Stylus 更合适。其次，脚本运行在宿主页面的上下文里，宿主可能是 Vue 2、Vue 3 或 React，直接挂载会冲突；跨域调用要绕过 CORS，得用 GM_xmlhttpRequest 并预先声明 connect；要从宿主页面拿当前会话、商品 ID 这类内部状态，只能靠运行时探测，没有稳定 API。这个技能把这些杂事整理成一套可重复的流程。

核心能力与执行流程

决策门（Decision Gate）：脚手架生成前先问四个问题——作用域是否限定在特定站点、是否需要拦截网络请求、是否要改浏览器原生 UI、是否只是纯 CSS 改动。任一答案指向 Chrome 扩展，就立即转向，不再生成 userscript。

工程化脚手架：以 vite-plugin-monkey 为基础生成最小项目结构。vite.config.ts 中按用户给出的 URL 模式填好 include（宽松匹配，支持通配符与正则）与 match（严格匹配），并把脚本通过 GM_xmlhttpRequest 访问的所有域名列入 connect，否则请求会被 Tampermonkey 拦截。

隔离式挂载：入口 src/main.ts 自建 DOM 容器再挂载独立的 Vue 3 应用，绝不挂到宿主已有的根节点上，保证脚本在宿主框架之外独立运行。

悬浮面板：App.vue 提供 position: fixed 的可拖拽悬浮按钮，包含拖拽阈值判断、视口边界检查、菜单面板的避让定位，以及 z-index 分层（按钮 9999、菜单 10000+、模态 10001+）；使用 Ant Design Vue 时用 :getPopupContainer 或全局 z-index 覆盖处理弹层。

三模式 API 层：src/utils/client.ts 区分三种请求路径——tp_* 走 GM_xmlhttpRequest 调用脚本专属后端，不自动携带页面 Cookie，需显式传 token；cr_* 用同源 XHR 冒充页面自身请求，自动带上会话 Cookie，适合登录态接口；standard 通过 GM_xmlhttpRequest 直连任意外部服务。底层 ajax.js 按 _mode 切换引擎，业务代码无需关心。

宿主状态提取：可选的 pageContext.ts 收集带 __vue__、__vue_app__ 等标记的 DOM 节点，从 _context.provides.pinia 或 $store 入手遍历内部 store，按字段名（如 conversationId、messages）打分筛选，并递归解开 Vue 3 响应式引用（限制深度约 6 层），同时兼容 Vue 2 的 __vue__.$store.state。

适用边界与注意点

这套方案只适用于「在特定页面内增强功能」的场景。以下几点被明确列为反模式：

• 绝不挂载到宿主页面的根元素，始终自建容器；
• 绝不假设宿主是 Vue 3，pageContext.ts 必须保留 Vue 2 与 Pinia 的回退路径；
• 跨域请求绝不用原生 fetch，一律走 GM_xmlhttpRequest 抽象层，并保证域名在 connect 中；
• 不要为浏览器全局功能、网络拦截、原生 UI 修改或纯样式定制推荐 Tampermonkey。

另外，宿主页面状态提取是启发式的——宿主内部结构一旦变化就可能失效，应当视为 best-effort，并为用户提供手动输入的兜底入口。构建产物是 dist/.user.js，分发靠手动粘贴、GreasyFork 上传或内部服务器托管原始 URL。