packServer/extension/README.md
liufumingren 9b37101a7b docs(extension): Edge 商店上架材料 + 扩展隐私政策页
国内实测 Chrome 商店不可达(chromewebstore.google.com / clients2.google.com 均超时),
Edge 加载项商店 200/0.43s 可达,所以官方分发走 Edge 商店。

- extension/STORE-SUBMISSION.md(新):上架检查清单、中英文 listing 文案、逐条权限用途说明、
  数据使用声明、截图清单、审核退回应对、上架后 ID 变化与升级流程、现场操作对照;
- frontend/public/extension-privacy.html(新):隐私政策页,随前端构建发布到
  https://pack.wms.gztbyc.com/extension-privacy.html(npm run deploy 会自动带上);
- extension/README.md:分发章节补上「国内走 Edge 商店」与上面两份文档的入口。

扩展 1.1.2(压缩产物 + 跳转默认值修复)已发布到线上:
updates.xml -> YuncangTraceExtension-1.1.2.crx(27766 字节,200)。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-01 04:03:58 +08:00

20 KiB
Raw Blame History

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

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, 换了私钥 = 换了 ID = 已经下发到客户机的策略全部失效;

  • 服务器上:/download/extension/updates.xml(不缓存,浏览器靠它自动升级)、 /download/extension/YuncangTraceExtension-<version>.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;隐私政策页已上线: https://pack.wms.gztbyc.com/extension-privacy.html(源码 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 各自 用 <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&amp;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)两道保险, 实测连续 applyMarks 5 次仍然是 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 那个展开按钮)目前只取折叠时显示的第一个编号。