- 工具菜单去掉「安装浏览器插件(企业策略:Chrome / Edge)」「卸载浏览器插件(企业策略)」, 删除 Services/ExtensionInstaller.cs(.reg 生成 + 提权导入 + 注册表校验) - 只保留「安装浏览器插件(Edge 应用商店)」与「复制插件路径(Chrome / 开发者模式)」; 商店弹窗去掉「审核中会 404」的说法,Chrome 用户直接引导到开发者模式 - 文档同步(桌面 README / 后端 README / extension README / STORE-SUBMISSION / keys README): 写清老机器上残留的 HKLM 策略怎么手工清理,避免和商店版同时注入 - extension:publish(.crx + updates.xml)保留,仅给内网/离线分发用 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
20 KiB
云仓视频溯源 · 单号注入扩展
Chrome / Edge 扩展(Manifest V3 + 原生 JS,零构建)。
它注入到第三方 WMS / 后台页面里,按规则找到「运单号」这类字段,在它旁边渲染一个 「▶ 查看打包视频」按钮(宿主元素一个字都不改);点击按钮打开溯源页面,把编号作为关键词带过去。
首个取样站点:
https://wms.wms.gztbyc.com/order/orderManagement运单号长这样:<span class="click-copy-link" role="button" tabindex="0" title="点击复制并查看快递单号二维码">321408064481776</span>扩展会在它后面插一个按钮(插在
+1展开按钮之前):<span class="click-copy-link" …>321408064481776</span> <button class="pst-trace-mark pst-trace-btn" data-pst-code="321408064481776" data-pst-url="https://www.baidu.com/?keyword=321408064481776">查看打包视频</button>点按钮 → 小窗打开
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:
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; -
服务器上:
/download/extension/updates.xml(不缓存)、/download/extension/YuncangTraceExtension-<version>.crx(文件名带版本号,长缓存)—— 这条链路现在只用于内网/离线分发,客户端不再写企业策略; -
正式分发:
- Edge:加载项商店(已上架)https://microsoftedge.microsoft.com/addons/detail/mgdonmkicojkabgalgekobaoohaohfcj, 桌面端「工具 → 安装浏览器插件(Edge 应用商店)」直接打开,点「获取」即可;
- Chrome:桌面端「工具 → 复制插件路径(Chrome / 开发者模式)」,到
chrome://extensions开开发者模式、加载已解压的扩展程序。
⚠️ 早期版本用
ExtensionInstallForcelist写 HKLM 策略装自建 CRX(IDlkei…),该功能已下线。 用过旧版本的机器策略仍在,会和商店版同时注入 —— 手动删掉...\Policies\Google\Chrome\ExtensionInstallForcelist与...\Policies\Microsoft\Edge\ExtensionInstallForcelist里值带/download/extension/的项 及同级ExtensionInstallSources,重启浏览器即可。
没有管理员权限的机器仍可用「工具 → 复制插件路径(Chrome / 开发者模式)」手动加载(拿到的是安装目录里的压缩版)。
国内环境下 Chrome 应用商店连不上(实测
chromewebstore.google.com、clients2.google.com均超时), 官方分发走 Edge 加载项商店(可达、免费)。上架文案、权限说明、截图清单、审核应对 见 STORE-SUBMISSION.md;隐私政策页已上线: https://pack.wms.gztbyc.com/extension-privacy.html(源码frontend/public/extension-privacy.html)。
1. 安装
客户机:从桌面端安装包直接加载(推荐)
桌面端安装包(MSI / EXE)已经把插件的压缩产物装到固定路径
%LOCALAPPDATA%\Programs\YuncangTrace\extension(源码、私钥都不进包):
- 桌面端软件菜单「工具 → 复制插件路径(开发者模式)」(复制的是 Windows 路径,可直接粘进选择框)。
- 打开
chrome://extensions(Edge 是edge://extensions)→ 右上角打开 开发者模式。 - 点 加载已解压的扩展程序,把刚复制的路径粘进去。
- 刷新一下已经打开的 WMS 页面(扩展只对安装之后加载的页面生效)。
开发:直接加载仓库目录
- 打开
chrome://extensions(Edge 是edge://extensions)。 - 右上角打开 开发者模式。
- 点 加载已解压的扩展程序,选择本目录
extension/。 - 刷新一下已经打开的 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 各自
用 <script src> 或 manifest.content_scripts.js 按顺序加载它。改完代码在 chrome://extensions 点一下
刷新即可(改 manifest.json 才需要重装)。
分发才有打包步骤:npm run extension:bundle 用 esbuild 逐文件压缩(不合并文件,
所以 importScripts('lib/rules.js') 和各处路径原样有效)输出到 extension/dist;
桌面端安装包与 .crx 都只打 dist。改了 src/ 之后记得重跑一次(build.ps1 会自动跑)。
3. 匹配方式 × 加工方式
匹配(怎么找)
| 方式 | 适用 | 关键字段 |
|---|---|---|
| CSS 选择器 | 元素本身好定位,或编号在属性里 | selector + attr(空 = 取元素文本)+ 可选 pattern |
| 文本正则 | 页面结构会变、但有稳定的编号格式(YT1234…) |
pattern + flags(必填,可用 exclude 排除) |
pattern的第 1 个捕获组会被当成编号({code}的值);没写捕获组就用整个匹配。- 选择器模式下
pattern是可选的:填了就从「attr取到的值 / 元素文本」里再抽一次编号。 - ⚠️ 属性里的值只能用选择器模式:文本正则只遍历文本节点,拿不到属性值。
例:编号藏在 javascript: 链接里
<a href="javascript:MM_openTrace('../system/view-trace!viewTrace.jspb?postNum=202610101621&wareHouseId=5400')">
202610101621
</a>
这条的编号既在链接文字里、也在 href 的 postNum= 参数里。两种写法都行:
| 写法 | selector | attr | pattern | 说明 |
|---|---|---|---|---|
| 从属性抽(推荐) | a[href*="postNum="] |
href |
postNum=([0-9A-Za-z_-]+) |
不依赖链接文字,文字被改成「查看轨迹」也照样能取到编号 |
| 取链接文字 | a[href*="postNum="] |
(空) | (空) | 简单;引擎会对取到的文本 trim(),那一大串换行/制表符会被去掉 |
内置示例规则不再默认带着这种结构(2026-10-17 已移除)。当前版本只下发一条文本规则(前缀 + 位数),
所以下表这种「按选择器/属性抽编号」的写法暂时用不上 —— 它属于 rules.js 引擎仍然支持、但插件端不再暴露的能力。
因为是 button 加工方式,按钮插在 <a> 之后,<a> 自己那个 javascript:MM_openTrace(...) 照旧能用。
加工(找到之后干什么)
| 方式 | 行为 | 适合 |
|---|---|---|
button(默认) |
命中元素一个字都不改,只在它旁边插一个「查看打包视频」兄弟按钮 | 元素本身有自己的点击行为(比如「点击复制二维码」),不能抢 |
chip |
命中元素自己变成可点(加类名 / 改写 title / 接管点击);可配下划线 / 高亮 / 胶囊 + ▶ 角标 |
命中处本来只是普通文字 |
button方式是零侵入的:- 不加类名、不改
title、不动role/tabindex、不接管它的点击 → 页面原有的行为完全不受影响; - 只往宿主元素上写
data-pst-code/data-pst-rule两个属性当「已处理」记号 (data-*对事件和渲染没有任何影响),撤销时一并摘掉; - 按钮插在命中元素之后;若命中元素在
<a>里,则退到那个<a>之后 ——<button>嵌进<a>是非法嵌套。
- 不加类名、不改
chip方式下点击会被脚本在捕获阶段拦掉(preventDefault + stopImmediatePropagation), 所以原元素自己的点击不会再触发;想用原功能就按住修饰键点(见「行为约定」)。text正则 +button:因为要把按钮放到「命中位置的旁边」,必须包一层纯定位的<span class="pst-trace-anchor">(无任何视觉、不带可点类名、不拦点击);它是原文照抄的, 所以被匹配到的那段文字没变。- 按钮文案是固定的默认值「查看打包视频」(
DEFAULT_BUTTON_TEXT);actionMode由defaultConfig()决定,插件端不提供入口。 - 提醒:按钮是真实 DOM,所以容器元素的
textContent会多出按钮文案 —— 这是插入 UI 的必然结果, 被匹配的那段文字本身没有被改动。
识别规则(服务器下发,唯一一条)
只有一条文本规则,内容由服务器按后台维护的前缀拼出来:
| id | 说明 | 生效站点 | 默认 |
|---|---|---|---|
remote |
\b(?:YT|SF|JD|ZTO|YTO|STO|EMS|DBL|32|77)\d{10,16}\b(flags g) |
后台配的生效站点 | 由后台开关控制 |
- 只维护前缀:后台「平台管理 → 插件配置」里加/删前缀(
YT、SF、32…), 正则由后端buildPattern()拼好一起下发;插件端applyRemote()只把它当成一条text规则,不解析、不展示。 - 前缀后面必须跟 10~16 位数字(后台也可调,默认 10~16):所以
321408064481776(32开头)会被命中, 而同一行的波次号E2026101600069、发货单号JY2026101619599、平台交易单号、17 开头的毫秒时间戳都不会; - ⚠️ 数字前缀(
32/77)最容易被内部 ID、订单号一起点亮 —— 发现误标就在后台把那个前缀删掉。 - 规则是区分大小写的(flags 只有
g):前缀统一存成大写,yt1234…不会被点亮。 src/lib/rules.js里仍保留一条内置的express规则,只作兜底:首次安装还没同步成功时用它, 同步成功后会被服务器那条remote整个替换掉。
4. 目标地址模板
在后台「插件配置」里改(网页模板 / 唤起协议),占位符:
| 占位符 | 含义 |
|---|---|
{code} |
提取到的编号,URL 编码后填入 |
{rawcode} |
同上但不编码 |
{host} |
当前站点 host |
默认:https://www.baidu.com/?keyword={code}
将来:https://video.example.com/trace?keyword={code}&from=wms
点击后按本地偏好呈现:独立小窗或新标签页(openMode,不再由服务器下发,避免每台机器行为不一致)。
5. 配置同步与排障
| 触发 | 频率 |
|---|---|
定时(chrome.alarms) |
每 5 分钟 |
| 扩展安装 / 浏览器启动 | 立刻一次 |
| 选项页 / 弹窗「立即同步」 | 手动 |
- 拉的是
GET https://pack.wms.gztbyc.com/api/web/extension/config(可用chrome.storage.local.pstConfigUrl覆盖,联调环境用); - 安装包地址不用后台配:每次同步还会读一次
GET https://pack.wms.gztbyc.com/download/version.json, 取里面的downloadUrl写进配置(和网页顶栏「下载桌面端」同一份,永远是最新发布版本); 只有 version.json 拉不到时才退回后台配置里那个值、再退回上一次的值; - 返回
{ ok, data: { version, enabled, hosts, prefixes, pattern, flags, urlTemplate, appUrlTemplate, downloadUrl } }; - 版本相同不写存储:
pstConfig.remote.version与服务器一致就跳过,页面不会被无谓重扫; - 失败保留旧配置(断网/后端挂了照常工作),错误写进
chrome.storage.local.pstSyncState,选项页显示; - 写配置后会触发
chrome.storage.onChanged,content script 自己unmark()+ 重扫,不用刷新页面。
排障入口:选项页(同步状态/上次错误/生效站点/前缀)→ 弹窗(本页命中清单)→ chrome://extensions 的
「Service Worker → 检查」里看 syncConfig() 的报错。
6. 自测页
# 任选一种方式打开 test/wms-mock.html
npx --yes http-server extension/test -p 7310 # → http://127.0.0.1:7310/wms-mock.html
(也可以直接双击打开 file://,但要在扩展详情里额外开启「允许访问文件网址」。)
预期:表格里 3 个运单号旁边各多一个「▶ 查看打包视频」按钮(插在运单号和 +1 之间),
其余 9 个蓝色文本不受影响;页面底部那行 SF1234567890123 也会被文本正则命中并插按钮。
7. 行为约定
- 默认(button)模式下完全不碰宿主元素:命中元素的点击、样式、
title全部原样, 只有我们自己新插的那个按钮会响应点击。 - chip 模式下点击拦截在捕获阶段完成(
preventDefault + stopImmediatePropagation), 不会触发宿主页的委托逻辑,也不会让外层<a>跳走;此时可以用修饰键放行 —— 按住 Ctrl / ⌘ / Alt / Shift 点击就不拦,交还给页面原本的行为。 - SPA 友好:
MutationObserver(默认 400ms 防抖)盯着新增节点和文本变化自动补标; 自己也写了 DOM 会触发观察器,用quietUntil时间窗把这类回声挡掉,避免无限重扫。 - 完整可撤销:后台停用插件、配置变更、或当前站点不在生效范围时会
unmark()—— wrap 模式把<span>换回纯文本,selector 模式把类名 /data-pst-*/ 被覆盖的title/ 加过的tabindex全部还原。 - 上限保护:单次扫描最多看
maxNodes(默认 5000)个文本节点、单页最多标maxMarks(默认 400)处, 超了会截断并在弹窗里显示N+。
8. 权限与安全
| 权限 | 用途 |
|---|---|
storage |
存下发下来的配置(优先 storage.sync,超 8KB 自动退到 storage.local) |
alarms |
每 5 分钟定时拉配置(MV3 的 service worker 会被回收,不能用 setInterval) |
host_permissions: https://pack.wms.gztbyc.com/* |
拉 GET /api/web/extension/config |
host_permissions: http(s)://localhost:17300/* |
探测本机软件是否在跑(协议唤起兜底) |
content script matches: http(s)://*/* |
需要注入任意第三方系统,无法预先枚举域名 |
- 不请求
tabs/scripting/cookies,不读页面 cookie;唯一的出站请求就是上面那个配置接口 (以及本机 17300 的探测)。点击只是把算好的 URL 交给chrome.tabs.create/chrome.windows.create。 - 注入走隔离世界(ISOLATED),不注入页面上下文,不受宿主页 CSP 影响。
- 想收窄范围:改
manifest.json里content_scripts[0].matches为具体域名(如https://wms.wms.gztbyc.com/*), 重新加载扩展即可;规则层面的范围由「生效站点」控制。 - 页面上不想要的可加
data-pst-skip属性(能改页面时),引擎会整棵子树跳过。
9. 踩过的坑(都已修,改代码时注意)
border-color不能放进transition:border-bottom-color未指定时计算值是currentColor(宿主页链接色,实测#409eff),一旦参与过渡,标记出来的第一帧是不确定的宿主色 ——每标一处都闪一下蓝。实测0ms = rgb(64,158,255)→150ms = rgb(14,165,164),去掉后立即正确。tools/make-icons.ps1必须保持纯 ASCII:PowerShell 5.1 在中文机器上把无 BOM 的.ps1按 GBK 读,UTF-8 中文变乱码;乱码落进("{0}" -f $x)这类格式串里会直接报Input string was not in a correct format而中断脚本。acceptTextNode的「已处理」判断必须看data-pst-code,不能只看类名:button 模式不给宿主元素加类名, 只看类名会让 text 正则规则把同一个编号再包一遍,插出第二个按钮。- button 模式要能跨重扫去重:
applyMarks只处理「还没标过」的节点,而 button 模式的宿主元素永远不带 markClass, 每轮增量重扫都会重新命中它 → 靠data-pst-code记号 +existingButton()(看nextElementSibling)两道保险, 实测连续applyMarks5 次仍然是 3 个按钮。 - 命中数不能只看
applyMarks的返回值:它只处理「还没标过的」节点,滚动/翻页是增量补标, 返回值只是本轮新增。所以status里的清单是直接数 DOM 上的.pst-trace-mark(collectItems)。 chrome.tabs.sendMessage要指定frameId: 0:页面里多个 iframe 都注入过脚本, 不定帧会拿到不确定的那个回复。unmark的账要记清:tabindex/title可能本来就是页面自己的,只有我们记过账 (data-pst-tab/data-pst-title)的才还原。- nunjucks 无关但同类教训:新加的类名前缀统一用
pst-,避免和宿主页或本项目其它样式撞名。
10. 下一步(还没做)
- 把目标地址换成真实的打包视频页(后端需要提供
GET /api/.../trace?keyword=<运单号>之类的接口)。 - 需要「先查有没有视频、再决定是否标记」时,把
content.js的runScan()前接一次fetch(要加对应域名的host_permissions),或改成点击时才查。 - 一次报多张运单(
+1那个展开按钮)目前只取折叠时显示的第一个编号。