AndroidStation(原中控改造为纯设备端) - 只做三件事:UDP 48899 被桌面端发现、TCP 8087 推送 USB 扫码结果、离线语音播报 - 扫码不再经过 UI:去掉逐键重绘,50ms 自动提交,同一码重复扫码也一律上报 - 离线语音种子(数字/字母/“开始打包”/欢迎语)随包安装,MediaPlayer 播放,启动把音量拉满 - 启动播报「欢迎使用溯源系统,初始化已经完成,扫码即可开始打包」 - 移除 Device Owner / 设备管理员 / lock task / 网络与 IP 设置等非普通应用能力(仅保留开机自启) - 正式签名 keystore + release 签名配置,versionName/versionCode 可由打包脚本覆盖 发布脚手架 - backend/android_client:Android 正式包构建(build.ps1 + package.config.json) - backend/scripts/deploy/publish-android.cjs + npm run android:build / android:publish - 桌面端安装包改为 download/desktop,Android 为 download/android_client; version.json 仍走 /download/version.json(老客户端写死),新增 /download/android_client/version.json - 谷歌插件随桌面端 MSI 安装到 <安装目录>\extension,工具菜单新增「复制谷歌插件地址」 - git-safety-check 增加仓库级禁区(keystore.properties / *.jks / local.properties) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
15 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 自带的「点击复制二维码」行为。
1. 安装
客户机:从桌面端安装包直接加载(推荐)
桌面端 MSI 已经把这个 extension/ 目录一起装好,路径固定为
%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 声明;权限只有 "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. 匹配方式 × 加工方式
匹配(怎么找)
| 方式 | 适用 | 关键字段 |
|---|---|---|
| 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 已移除);真要处理 旧版 JSP 轨迹链接,在配置页自己加一条规则(下表两种写法都行)。
因为是 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">(无任何视觉、不带可点类名、不拦点击);它是原文照抄的, 所以被匹配到的那段文字没变。- 按钮文案在基本设置里配(默认「查看打包视频」);全局和单条规则都能设
actionMode,规则留空则跟随全局。 - 提醒:按钮是真实 DOM,所以容器元素的
textContent会多出按钮文案 —— 这是插入 UI 的必然结果, 被匹配的那段文字本身没有被改动。
内置规则
只内置一条(实测这一条就能盖住真实页面的单号):
| id | 说明 | 生效站点 | 默认 |
|---|---|---|---|
express |
文本规则 \b(?:YT|SF|JD|ZTO|YTO|STO|EMS|DBL|32|77)\d{10,16}\b(gi) |
全部 | 开 |
- 前缀表就是唯一要维护的地方:在
src/lib/rules.js的EXPRESS_PREFIXES里往数组里追加新前缀即可 (以前没出现过、又确实出现在单号开头的就加进去)—— 正则会跟着拼出来,不用改正则本身:const EXPRESS_PREFIXES = [ 'YT', 'SF', 'JD', 'ZTO', 'YTO', 'STO', 'EMS', 'DBL', '32', '77' ]; const EXPRESS_PATTERN = '\\b(?:' + EXPRESS_PREFIXES.join('|') + ')\\d{10,16}\\b'; - 前缀后面必须跟 10~16 位数字(
\d{10,16}):所以321408064481776(WMS 运单号,32开头)会被命中, 而同一行的波次号E2026101600069、发货单号JY2026101619599、平台交易单号、17 开头的毫秒时间戳都不会; - ⚠️ 数字前缀(
32/77)最容易被内部 ID、订单号一起点亮 —— 发现误标就把那个前缀拿掉,或者给规则加exclude; - 其它匹配方式(CSS 选择器 / 从
href抽编号 / 按data-*取值)不再内置示例,需要时在配置页自己加一条即可,写法见上面的例子; - 升级迁移(config version 1 → 2):扩展升级后第一次打开配置页/页面时,会
① 把已移除的示例规则(
wms-waybill/numeric/legacy-postnum/dom-attr)从你的规则里剔掉, ② 内置的express如果还是老正则(说明你没改过它)就换成带新前缀表的正则 —— 你自己加的规则、以及你改过的express都不动(见upgradeRules())。
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 个运单号旁边各多一个「▶ 查看打包视频」按钮(插在运单号和 +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 并提示) |
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而中断脚本。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那个展开按钮)目前只取折叠时显示的第一个编号。