liufumingren bd2363bf00 chore: 初始化仓库(backend / frontend / extension 三块)
- 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 密码,绝不入库)。
2026-10-17 08:50:32 +08:00
..

云仓视频溯源 · 单号注入扩展

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. 安装

  1. 打开 chrome://extensions(Edge 是 edge://extensions)。
  2. 右上角打开 开发者模式。
  3. 点 加载已解压的扩展程序,选择本目录 extension/。
  4. 刷新一下已经打开的 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 那个展开按钮)目前只取折叠时显示的第一个编号。