- backend/:Egg 3 纯 JSON 接口服务(MySQL 8 + Redis),全部走 header 令牌鉴权; 已彻底去掉服务端渲染(删除 page 控制器 / app/view / nunjucks / session / CSRF), 开发时把页面请求反代到前端 dev server,生产托管 frontend/dist(SPA 回退)。 单测 91 个通过(不需要本机数据库)。 - frontend/:Vite + Vue3 + TypeScript 的 SPA(登录 / 注册 / 找回密码 / 扫码登录与确认 / 首页统计 / 设备管理 / 扫码记录 / 个人中心 / 测试页),vue-tsc 类型检查与构建通过。 - extension/:MV3 浏览器扩展(零构建),注入第三方 WMS 页面识别运单号并打开溯源页。 - 忽略规则统一放根 .gitignore:node_modules、dist、logs / logs-*、run、typings、 .env*、config.local.js(含本机数据库与 Redis 密码,绝不入库)。
9.7 KiB
云仓视频溯源 · 单号注入扩展
Chrome / Edge 扩展(Manifest V3 + 原生 JS,零构建)。
它注入到第三方 WMS / 后台页面里,按规则把「运单号」这类字段就地二次加工成可点击元素;
点击后打开溯源页面(当前先用 https://www.baidu.com/?keyword={code} 占位),把编号作为关键词带过去。
首个取样站点:
https://wms.wms.gztbyc.com/order/orderManagement运单号长这样:<span class="click-copy-link" role="button" tabindex="0" title="点击复制并查看快递单号二维码">321408064481776</span>点击它 → 小窗打开
https://www.baidu.com/?keyword=321408064481776
1. 安装
- 打开
chrome://extensions(Edge 是edge://extensions)。 - 右上角打开 开发者模式。
- 点 加载已解压的扩展程序,选择本目录
extension/。 - 刷新一下已经打开的 WMS 页面(扩展只对安装之后加载的页面生效)。
图标缺失时重新生成:powershell -ExecutionPolicy Bypass -File tools\make-icons.ps1
2. 目录结构
extension/
├── manifest.json # MV3 声明;权限只有 "storage"
├── 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:只负责把算好的地址打开(小窗 / 新标签页)
│ ├── popup.html/.css/.js # 工具栏弹窗:开关、本页命中清单、重新扫描
│ └── options.html/.css/.js # ★ 规则配置页:基本设置 / 规则编辑 / 试跑 / 导入导出
├── 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 才需要重装)。
3. 两种匹配方式
| 方式 | 适用 | 关键字段 |
|---|---|---|
| 文本正则 | 页面结构会变、但有稳定的编号格式(YT1234…) |
pattern + flags(可带 exclude 排除) |
| CSS 选择器 | 元素本身很好定位(Element-Plus 表格里的 [title*="快递单号"]) |
selector + attr(空 = 取元素文本) |
- 文本正则:遍历文本节点,把命中的子串包成
<span class="pst-trace-mark" data-pst-code="…">。 原文原样保留在 span 里,所以宿主页读textContent、复制粘贴、表单校验拿到的内容都不变。 - CSS 选择器:直接给命中元素加类名和
data-pst-*,不包一层(适合本来就是个<span>/<tr>的情况)。 pattern的第 1 个捕获组会被当成编号({code}的值);没写捕获组就用整个匹配。
内置规则
| id | 说明 | 生效站点 | 默认 |
|---|---|---|---|
wms-waybill |
[title*="快递单号"],取文本 —— 取样自 gztbyc WMS |
wms.wms.gztbyc.com / *.gztbyc.com |
开 |
express |
\b(?:YT|SF|JD|ZTO|YTO|STO|EMS|DBL)\d{10,16}\b 通用文本规则 |
全部 | 开 |
numeric |
纯数字 12~20 位 | 全部 | 关(容易把时间戳、内部 ID 点亮,页面上到处下划线反而没人敢用) |
dom-attr |
[data-order-no] 取属性 |
全部 | 关(示例) |
⚠️ gztbyc WMS 一行里有 4 个长得很像的
.click-copy-link: 发货单号JY2026101619599、运单号321408064481776、波次号E2026101600069、平台交易单号6930529169563286869。 只有运单号那个的title含「快递单号」,所以规则用[title*="快递单号"]而不是.click-copy-link。
4. 目标地址模板
在基本设置里改一处即可切到真实打包视频页,占位符:
| 占位符 | 含义 |
|---|---|
{code} |
提取到的编号,URL 编码后填入 |
{rawcode} |
同上但不编码 |
{host} |
当前站点 host |
默认:https://www.baidu.com/?keyword={code}
将来:https://video.example.com/trace?keyword={code}&from=wms
单条规则还可以设专属地址(留空则用全局模板)。点击后按「打开方式」呈现: 独立小窗(默认)或新标签页。
5. 调规则:别刷页面,用「试跑」
配置页里的 规则试跑 用的是当前表单里还没保存的规则,所以可以边调边看:
- 输入类型选
HTML 片段,粘一段真实 DOM,点「试跑」; - 它会模拟一个站点(默认
wms.wms.gztbyc.com,用于校验规则的「生效站点」), 列出命中的编号 + 最终目标地址,并给出二次加工后的 HTML; - 0 命中时会把每条启用规则的「生效站点 / 选择器 / 正则」列出来,方便判断是站点被过滤了还是没匹配上;
- 点「填入 WMS 取样」可以一键载入内置样例。
工具栏弹窗则用来确认线上是否真的生效:显示「本页命中 N」+ 编号清单(点一条可直接打开)。
6. 自测页
# 任选一种方式打开 test/wms-mock.html
npx --yes http-server extension/test -p 7310 # → http://127.0.0.1:7310/wms-mock.html
(也可以直接双击打开 file://,但要在扩展详情里额外开启「允许访问文件网址」。)
预期:表格里 3 个运单号被标记(青色虚线下划线 + ▶ 角标),其余 9 个蓝色文本不受影响。
7. 行为约定
- 点击拦截在捕获阶段完成,
preventDefault + stopImmediatePropagation,不会触发宿主页的委托逻辑, 也不会让外层<a>跳走。 - 修饰键放行:按住 Ctrl / ⌘ / Alt / Shift 点击 = 不拦, 交还给页面原本的行为。 (gztbyc WMS 上那个运单号 span 原本是「点击复制二维码」,想用原功能就按住 Ctrl 点。)
- 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 并提示) |
content script matches: http(s)://*/* |
需要注入任意第三方系统,无法预先枚举域名 |
- 不请求
tabs/scripting/cookies,不读页面 cookie,不发任何请求: 点击只是把算好的 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而中断脚本。- 命中数不能只看
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那个展开按钮)目前只取折叠时显示的第一个编号。