# 云仓视频溯源 · 单号注入扩展 Chrome / Edge 扩展(**Manifest V3 + 原生 JS,零构建**)。 它注入到**第三方 WMS / 后台页面**里,按规则找到「运单号」这类字段,在它**旁边**渲染一个 「▶ 查看打包视频」按钮(宿主元素一个字都不改);点击按钮打开溯源页面,把编号作为关键词带过去。 > 首个取样站点:`https://wms.wms.gztbyc.com/order/orderManagement` > 运单号长这样: > ```html > title="点击复制并查看快递单号二维码">321408064481776 > ``` > 扩展会在它后面插一个按钮(插在 `+1` 展开按钮之前): > ```html > 321408064481776 > > ``` > 点按钮 → 小窗打开 `https://www.baidu.com/?keyword=321408064481776`。 > 原来的运单号仍保留 WMS 自带的「点击复制二维码」行为。 --- ## 0. 配置从哪来(1.1.0 起) **插件只拉取并执行,不提供本地配置**: - 后台(`平台管理 → 插件配置`)维护**单号前缀**(`YT` / `SF` / `32`…)、**生效站点**、跳转模板、安装包地址; 单号正则由服务端拼好(`\b(?:YT|SF|…)\d{10,16}\b`)一起下发,插件端**不展示、不可改**; - 插件每 **5 分钟**自动拉一次 `GET https://pack.wms.gztbyc.com/api/web/extension/config` (`chrome.alarms`;浏览器启动/扩展安装时也会立刻拉一次),选项页/弹窗里还有「立即同步」; - **版本没变就不写存储**(避免整页重扫);**拉取失败保留旧配置**(断网照常工作),错误显示在选项页; - 插件里不再有:规则编辑、正则输入、试跑、导入导出、使用说明 —— 这些都在后台维护。 --- ## 0.1 打包与分发(企业策略安装) 浏览器**不认「加载已解压」之外的本地目录**,所以正式分发必须打包成签名好的 `.crx`: ```powershell cd backend npm run extension:bundle # 只压缩源码 → extension/dist(esbuild minify,去注释压空白,约 1/3 体积) npm run extension:build # 压缩 + 打包(extension/out/ 下产出 .crx / updates.xml / extension-id.txt) npm run extension:publish # 压缩 + 打包 + 上传到服务器 /download/extension/ + 刷新 nginx npm run extension:zip # 压缩 + 出商店上传包(extension/out/*.zip,条目名是标准 `/`) ``` **分发用的都是 `extension/dist`(压缩产物),开发调试仍用源码目录**: - `extension/` = 源码(带完整注释),`chrome://extensions`「加载已解压」时选这个目录; - `extension/dist/` = 压缩产物(`dist/` 已 gitignore,随时可重新生成),桌面端安装包和 `.crx` 都只用它; - 只做 minify、**不做混淆**:MV3 的 CSP 禁止 `eval`/`new Function`(`debugProtection` 之类直接报错), 而且 Chrome/Edge 商店要求提交的代码可读;压缩后已经去掉全部注释、缩短了标识符, 真正需要保密的东西也不在插件里(前缀/正则/站点全部由服务端下发,私钥从不进包)。 - 私钥 `extension/keys/key.pem`(首次运行自动生成,**务必单独备份**):它决定**扩展 ID**, 换了私钥 = 换了 ID = 已经下发到客户机的策略全部失效; - 服务器上:`/download/extension/updates.xml`(**不缓存**,浏览器靠它自动升级)、 `/download/extension/YuncangTraceExtension-.crx`(文件名带版本号,长缓存); - 客户机:桌面端「工具 → **安装谷歌插件**」→ 允许一次 UAC → 写 HKLM 策略: ``` Chrome/Edge ExtensionInstallForcelist = <扩展ID>;https://<域名>/download/extension/updates.xml Chrome/Edge ExtensionInstallSources = https://<域名>/download/extension/* ``` 重启浏览器即自动装好(`chrome://extensions` 里显示「由你的组织管理」)。 「工具 → 卸载谷歌插件」只会删掉值里带 `/download/extension/` 的那几条,不动别的策略。 没有管理员权限的机器仍可用「工具 → 复制插件路径(开发者模式)」手动加载(拿到的是安装目录里的压缩版)。 > 国内环境下 **Chrome 应用商店连不上**(实测 `chromewebstore.google.com`、`clients2.google.com` 均超时), > 官方分发走 **Edge 加载项商店**(可达、免费)。上架文案、权限说明、截图清单、审核应对 > 见 [STORE-SUBMISSION.md](./STORE-SUBMISSION.md);隐私政策页已上线: > (源码 `frontend/public/extension-privacy.html`)。 ## 1. 安装 ### 客户机:从桌面端安装包直接加载(推荐) 桌面端安装包(MSI / EXE)已经把插件的**压缩产物**装到固定路径 `%LOCALAPPDATA%\Programs\YuncangTrace\extension`(源码、私钥都不进包): 1. 桌面端软件菜单「**工具 → 复制插件路径(开发者模式)**」(复制的是 Windows 路径,可直接粘进选择框)。 2. 打开 `chrome://extensions`(Edge 是 `edge://extensions`)→ 右上角打开 **开发者模式**。 3. 点 **加载已解压的扩展程序**,把刚复制的路径粘进去。 4. 刷新一下已经打开的 WMS 页面(扩展只对**安装之后**加载的页面生效)。 ### 开发:直接加载仓库目录 1. 打开 `chrome://extensions`(Edge 是 `edge://extensions`)。 2. 右上角打开 **开发者模式**。 3. 点 **加载已解压的扩展程序**,选择本目录 `extension/`。 4. 刷新一下已经打开的 WMS 页面(扩展只对**安装之后**加载的页面生效)。 图标缺失时重新生成:`powershell -ExecutionPolicy Bypass -File tools\make-icons.ps1` ## 2. 目录结构 ``` extension/ ├── manifest.json # MV3 声明;permissions = storage + alarms,host_permissions 含后端域名 ├── icons/ # 16/32/48/128,由 tools/make-icons.ps1 生成 ├── src/ │ ├── lib/rules.js # ★ 规则引擎(配置归一化 / 服务器配置合并 / DOM 加工 / 地址拼接) │ ├── content.js # 注入脚本:扫描 + 加工 + 点击拦截 + MutationObserver 补标 │ ├── content.css # 注入样式(全部 .pst- 前缀 + !important) │ ├── background.js # service worker:打开目标地址 + **每 5 分钟拉取服务器配置** │ ├── popup.html/.css/.js # 工具栏弹窗:配置版本、本页命中清单、重新扫描、立即同步 │ └── options.html/.js # ★ 只读状态页:同步状态 / 生效站点 / 前缀(不可编辑) ├── dist/ # 压缩产物(npm run extension:bundle 生成,不进仓库) ├── test/wms-mock.html # 自测页:按真实结构复刻的表格 └── tools/make-icons.ps1 # 生成图标(纯 ASCII,见文件头说明) ``` **开发没有构建步骤**:`rules.js` 挂在 `globalThis.PSTRules` 上,content script / popup / options 各自 用 `