ShipBest → 领星OMS 订单同步（Chrome 扩展）· 安装与使用手册

把 ShipBest（https://oms.shipbest.com/orders/list）里已打单的订单，同步到领星 OMS（https://oms.xlwms.com）的「一件代发 · 新建出库单」页面（https://oms.xlwms.com/warehouse/packet/create），自动填表并上传面单文件。

插件只填不提交：填完后由你人工核对，再自己点领星的保存/提交。

项目	内容
扩展名	ShipBest → 领星OMS 订单同步
当前版本	0.1.11
适用浏览器	Chrome / Edge 111 及以上（其他新版 Chromium 内核浏览器同样可用）
安装方式	开发者模式「加载已解压的扩展程序」

一、它做了什么

① ShipBest 订单列表页 /orders/list
     页内弹框自动采集：收件人 / 运单号 / 承运商 / 面单 / SKU
        │
        ├─ 勾选订单 →「同步到领星OMS (n)」
        │       ├─ 订单写入待填充队列
        │       └─ 自动打开领星「新建出库单」页
        │
② 领星建单页 /warehouse/packet/create
     右下角面板列出待填充订单
        ├─ 进页自动预设：仓库、物流渠道
        └─ 点某单的「填充」→ 填字段 + 自动上传面单 → 行状态变「已填充」
                │
③ 人工核对（收件人 / 承运商 / 渠道 / SKU / 面单是否本单）
        └─ 你自己点领星的保存 / 提交建单

整条链路上，插件不会点任何「保存」「提交」「确认下单」按钮。

下载插件

ShipBest → 领星OMS 订单同步 Chrome插件下载

二、安装

1. 准备扩展目录

以下任一目录都可用（内容一致）：

仓库内：browser-extension/shipbest-lingxing
桌面副本：~/Desktop/shipbest-lingxing

扩展目录里必须直接有 manifest.json 这一层。不要双击 manifest.json，也不要打包成 zip 安装——必须用下面的「加载已解压」方式。

2. 在 Chrome 里加载

地址栏打开 chrome://extensions
右上角打开 开发者模式
点 加载已解压的扩展程序
选择扩展目录（例如 ~/Desktop/shipbest-lingxing）
点浏览器工具栏的拼图图标，把「ShipBest → 领星OMS」固定到工具栏（图标上的数字 = 待填充单数）

Edge 同理：edge://extensions → 打开「开发人员模式」→「加载解压缩的扩展」。

3. 登录两个站点

插件不做登录、不保存账号密码，只复用你浏览器里已有的登录状态：

打开并登录 ShipBest 订单列表 https://oms.shipbest.com/orders/list
打开并登录领星 OMS https://oms.xlwms.com

插件会在你正常使用 ShipBest 时，从页面自身的请求里读取登录令牌（JWT），仅存本机浏览器，用于后续同源取单。

4. 升级 / 重装

用新版本文件覆盖扩展目录
chrome://extensions → 本扩展卡片 → 重新加载
刷新已经打开的 ShipBest / 领星页面

第 3 步很关键：扩展重载前打开的标签页里没有新脚本，表现为「采集不到」「面板不更新」「Receiving end does not exist」。

5. 权限说明

权限	用途
`storage`	存订单队列、设置、最近一次订单缓存（全部仅本机浏览器）
`tabs`	找到 / 打开 ShipBest 与领星标签页，同步后自动打开建单页
`clipboardWrite`	「复制诊断」「复制面单链接」
`https://.shipbest.com/`	读取 ShipBest 订单接口（同源，带你自己的登录态）
`https://oms.xlwms.com/*`	在领星建单页注入填充面板
可选：任意域名（默认不申请）	仅用于下载面单文件（面单常放在对象存储域名上）。需要时在设置页点「授权面单下载域名」，或点面板上的「授权并重试」

三、首次配置

入口：右键工具栏上的扩展图标 → 选项；或 chrome://extensions → 本扩展「扩展程序选项」。（工具栏弹窗里不再放「设置」按钮。）

建议只确认这几项，其余保持默认：

设置项	默认值	说明
新建出库单地址	`https://oms.xlwms.com/warehouse/packet/create`	同步完成后自动打开的页面（一件代发建单页）。旧版本默认的 `/warehouse/create` 会在升级后首次读取设置时自动换成新地址（自己填过的地址不动）
物流渠道	`上传物流面单`	建单页「物流渠道」固定选这一项（卖家使用 ShipBest 面单）
固定仓库名	留空	留空 = 自动：优先用你上次选过的仓库，否则选第一个
填物流承运商	开启	关闭后承运商留空，由你手选

设置页底部工具按钮：授权面单下载域名 / 清空待填充队列 / 清空订单缓存 / 恢复默认（只重置设置，不动队列和登录态）。

完整设置项见第六节设置项全表。

四、使用

第 1 步：在 ShipBest 采集订单

打开 https://oms.shipbest.com/orders/list
页面右下角自动弹出「ShipBest → 领星OMS」面板，并自动采集一次
面板副标题显示采集概况，例如 38/1200 单 · 面单 36 · 已同步 12 · 缺 2
- 面单 = 有面单地址的单数
- 已同步 = 已推送进领星队列的单数
- 缺 = 缺收件人 / 承运商 / SKU / 运单号中任意一项的单数
面板为空或列表有单但采不到：
- 点底栏 「采集本页」 再试
- 点工具条 「复制诊断」，把内容发我，可据此校准字段
出现「缺 N」时点工具条 「补齐详情」：插件逐单调详情接口补全字段（承运商、收件人、SKU、面单多在详情里）；失败原因会直接写在面板上（详情失败：…）

面板工具条：全选复选框、已选 n 单、补齐详情、（有缺字段时）复制诊断。

面板底栏只有两个按钮：采集本页、同步到领星OMS (n)。

第 2 步：勾选并同步到领星

勾选要处理的订单（点整行即勾选；工具条复选框是全选）
点底栏 「同步到领星OMS (n)」
插件把订单写入待填充队列，并自动打开领星「新建出库单」页（地址取设置里的「新建出库单地址」）

同一单重复同步不会产生重复条目，只会更新数据；已填充过的单保持「已填充」状态，避免重复填。

第 3 步：在领星逐单填充

进入建单页后，右下角出现面板「打单同步 · 领星OMS」，副标题是 队列 N 单 · 待填充 M。

进页会自动预设（可在设置里关）：仓库（上次选过的仓库，否则第一个）、物流渠道（上传物流面单）。承运商不预选，跟着字段填充走。

对每一单：

点该行的 「填充」（已填过的显示「重新填充」）
插件按顺序执行：
- 清掉上一单留下的面单文件（防止旧面单跟着新单提交）
- 预设仓库、物流渠道
- 逐字段填充：收件人、地址、电话、州/市/邮编、重量尺寸、SKU、客户订单号、运单号、物流承运商、备注等
- 填充后自动上传面单（可在设置里关）
行状态变化：待填充 → 填充中 → 已填充，并留在列表原位
行上出现结果摘要：上次结果：填充 18 · 无值 0 · 未找到控件 0 · 失败 1

有失败字段时，行内直接显示红字原因，例如：

· 物流承运商：下拉里没有匹配的选项，页面可选：GOFO / GOFO Ground（订单值：GOFO Express）

面板「填充中」时不要切单

行内按钮与标签

元素	含义
填充 / 重新填充	填这一单；已填过的可重填（换单前会清空上一单面单）
传面单 / 重传面单	只重传这一单的面单，不重填字段
`待填充`	还在队列里，没填过
`填充中`	正在填（此时不要切单）
`已填充`	填过了，可核对提交
`面单已传`	面单文件已写入领星上传控件
`有面单`	订单有面单地址，但还没上传
`无SKU`	这一单没有商品明细，需先回 ShipBest 补齐
`GOFO Express` 这类紫底标签	订单的物流承运商

面单上传失败时

面板顶部出现红色提示块，写明具体原因（未授权 / 存储异常 / 签名过期等），并给出按钮：

授权并重试（域名未授权时）：授予该面单域名权限后自动重试上传
复制面单链接：手工下载面单
关闭提示：收起提示块

第 4 步：人工核对并提交

插件只填表单字段与面单文件，最终提交由你完成。建议核对：收件人 / 电话 / 邮编、承运商、物流渠道、SKU 与数量、面单是否为本单。

五、三处界面说明

1. 工具栏弹窗（点扩展图标）

显示 ShipBest 登录态与队列概况（队列 N 单：待填充 M，已填充 K。），只保留三个按钮：

打开 ShipBest 订单列表
打开领星新建一件代发页面
清空队列（二次确认：只清待填充项，已填充记录保留，避免同一单被重复填）

设置入口不在弹窗里：右键工具栏图标选「选项」，或 chrome://extensions → 本扩展「扩展程序选项」。

2. ShipBest 页内弹框（右下角，宽 470）

底栏：采集本页、同步到领星OMS (n)
工具条：全选、已选计数、补齐详情、（有缺字段时）复制诊断
每行显示：订单号、运单号、承运商、收件人摘要，以及标签 有面单 / 无面单、SKU n、已同步
头部：− 折叠、× 隐藏（隐藏后刷新页面恢复）；面板可拖动，位置会记住
空态会给出 复制诊断 与 重新采集 按钮

3. 领星页内面板（右下角，宽 400）

没有底栏按钮，所有操作都在订单行上（填充 / 传面单）
面单下载失败时的红色提示块见上文
队列为空时显示提示与 打开订单中心 按钮
同样支持拖动、折叠、隐藏

4. 订单中心（全页）

扩展内的完整订单页，适合批量处理。弹窗里不再放入口，需要时直接访问：

chrome-extension://<扩展ID>/app/index.html

扩展 ID 在 chrome://extensions 的本扩展卡片上可以看到。页面内提供：打开 ShipBest、设置、拉取订单、推送到领星队列、打开领星出库单、原始报文；点行可看详情抽屉（推送到队列 / 复制面单链接）。

注意：「每页条数」「最多拉取页数」「拉列表同时拉详情」这三项只对订单中心页生效。页内弹框的「采集本页」只采当前页，缺字段用「补齐详情」。

六、设置项全表

领星 OMS

设置项	默认	说明
新建出库单地址	`https://oms.xlwms.com/warehouse/packet/create`	同步完成后自动打开；留空则用内置地址。旧版本默认的 `/warehouse/create` 会在升级后首次读取设置时自动改成新地址（自己改过的地址不动）

拉取

设置项	默认	说明
订单状态	`4`	4 = 已打单。多个用逗号分隔，如 `4,5`
每页条数	`50`	10–100；页内弹框也用这个值
最多拉取页数	`20`	1–100；仅订单中心页批量拉取时生效
拉列表同时拉详情	是	仅订单中心页生效；字段更全但更慢

填充

设置项	默认	说明
固定仓库名	空	空 = 自动：上次选过的仓库，否则第一个。你在页面上手动换仓也会被记住（记录在 `lastWarehouse`，无独立开关）
物流渠道	`上传物流面单`	建单页「物流渠道」选这一项
填物流承运商	开启	建单时拿订单承运商去「物流承运商」下拉匹配填进去（详见第七节）。关闭则留空由你手选
进入建单页自动预设	开启	进页 / 切路由时先选好仓库与物流渠道（承运商不预选）
填充后自动上传面单	开启	填完自动把面单文件写入上传控件
重量目标单位	不换算	可选 `lb / oz / g / kg`
尺寸目标单位	不换算	可选 `in / cm`
数值小数位	`3`	0–4
字段填充间隔(ms)	`120`	页面控件多、填充不稳时调大（如 200–300）

高级

设置项	默认	说明
字段映射覆盖(JSON)	空	数组格式，元素含 `id/label/path/include/exclude` 等。只有领星页面结构与内置映射差太多时才需要改

设置页工具按钮

按钮	作用
保存设置	写入 `sblxSettings`（表单里没有的键如 `lastWarehouse` 会原样保留）
授权面单下载域名	申请任意域名下载权限，用于面单在对象存储域名时
清空待填充队列	只删待填充项，已填充记录保留（与弹窗一致，避免重复填）
清空订单缓存	清空上次拉到的订单，下次重新拉
恢复默认	只重置设置，不动队列和登录态

七、会填哪些字段 / 承运商怎么匹配

字段映射表在 content/fieldmap.js，定位方式是「标签 + placeholder + name + id + 邻近文案」打分，兼容原生 input/select 与 Element UI / Ant Design / iView 等组件库（含自研组件下拉）。

1. 字段清单

分组	字段
收件人	姓名、公司、电话、邮箱、国家、州/省、城市、邮编、地址1、地址2、完整地址
寄件人	姓名、公司、电话、国家、州/省、城市、邮编、地址1（页面没有则记为「未找到控件」，属正常）
包裹	重量、长、宽、高、尺寸（合并文本）
商品	首条明细的 SKU、中文品名、英文品名、数量、申报单价、申报币种、海关编码
单据	客户订单号、运单号、面单链接、备注
预设	仓库、物流渠道（进页自动选）

2. 承运商匹配规则

候选值顺序 = 订单承运商原值 → 产品名 → 各自首段短名（GOFO Express 会额外试 GOFO）。下拉选项按四档打分：完全相同 > 以候选开头 > 包含候选 > 被候选包含。

同分时按两级收敛，不是一上来就报歧义：

候选权威性：优先命中更靠前的候选。订单 SpeedX、产品名 SPX，下拉里两者都有时选 SpeedX（订单原值才是客户下的那个），不会报「候选项有歧义」。
互为包含取最短：GOFO 与 GOFO Ground 都能吃 GOFO 候选时取 GOFO。

两级都收敛不了（两个互不相干的品牌/线路）才放弃，并把页面实际可选值写进行内红字，由你手选——宁可不选，也不把单入错渠道。

3. 不会做的事

不点保存 / 提交 / 确认下单
不登录、不填账号密码
不伪造面单：ShipBest 侧还没打印面单的单，插件只会显示「无面单」

八、常见问题

先按症状查表，再看下面展开的几条。

症状	处理
弹框一直空 / 采集不到	确认在 `/orders/list`；刷新页面；点「采集本页」；仍为空点「复制诊断」发我
`Receiving end does not exist`	该 ShipBest 标签页是扩展重载之前打开的：刷新它，或直接重试（插件会自愈开新标签页）
补齐后仍显示「无面单」	该单在 ShipBest 侧未获取 ScanForm / 未打印面单，属数据状态
承运商没自动选上	看行内红字里的「页面可选」；两个品牌/线路确实冲突时需手选
面单上传失败	面板顶部红块看原因；域名未授权点「授权并重试」，或「复制面单链接」手工下载
仓库 / 物流渠道选错	确认「进入建单页自动预设」开启；页面手动换一次仓库会被记住
图标角标数字对不上	角标 = 待填充数；已填充的单不再计数
想全部重来	设置页「清空待填充队列」，再回 ShipBest 重新同步

1. 为什么面板采集不到订单？

按顺序排查：

是否在 https://oms.shipbest.com/orders/list（/orders 也认）
该标签页是否在扩展重载前打开的 → 刷新
页面本身能看到订单表格吗（登录态是否失效）
点「复制诊断」，看是接口没通、还是报文解析不出订单（面板会把原因直接写出来）

2. 「候选项有歧义」到底算不算错误？

同一家承运商的两种写法（SpeedX / SPX）不算歧义，会按订单原值选。真正会报歧义的是两个互不相干的选项（两个不同品牌或线路），此时插件不猜，等你手选，避免入错物流渠道。

3. 为什么「面单上传」会失败？

面单文件在对象存储域名上（如 download.shipbest.com），扩展需要该域名的下载权限：

默认已覆盖 *.shipbest.com
面单在其它域名 → 面板红块点 授权并重试，或设置页点 授权面单下载域名

其它失败原因（签名过期、网络异常）会原样显示在红块里，可直接「复制面单链接」手工下载。

4. 升级后要做什么？

chrome://extensions → 重新加载扩展 → 刷新已打开的 ShipBest 和领星页面。建单页地址会自动迁移成 packet/create，你自定义过的地址不会被覆盖。

九、数据与隐私

全部数据只存在本机浏览器的 chrome.storage.local，不上传任何服务器：
- sblxShipbestAuth：从页面请求里读到的 ShipBest 登录令牌（含时间戳）
- sblxQueue：待填充队列
- sblxOrders：最近一次拉到的订单
- sblxSynced：已推送标记
- sblxSettings：设置
- sblxRawSample / sblxDebug：最近一次原始报文样本与接口摘要（仅用于排查）
插件不外发任何数据；面单文件由后台代下载后直接写入页面控件，不落第三方
队列与缓存都可在设置页清空；卸载扩展会一并清掉

十、已知限制

只填不提交：提交动作始终由人完成
领星「商品」是选择器时，可能只填上 SKU 文本，需要你在商品行里补选具体商品
建单页按页面特征判定（可填控件 ≥ 6 且出现「收件人」字样），不看 URL；页面大改版可能需要更新字段映射
单条填充是串行的：队列里一次只填一单，填充中切换页面会中断该次填充
面单必须先在 ShipBest 侧打印出来才有地址
极少数自研组件下拉需要更长的等待，可把「字段填充间隔」调到 200–300ms

十一、给维护者

目录结构

shipbest-lingxing/
├── manifest.json
├── background.js            # 消息路由、面单下载、角标、开页、地址迁移
├── content/
│   ├── common.js            # 存储 / 设置 / 面板 UI 公共层（SBLX.LX_CREATE_URL 在此单源声明）
│   ├── dict.js              # 单位换算、国家州省份字典
│   ├── normalize.js         # ShipBest 报文归一化（含未知包法兜底）
│   ├── fieldmap.js          # 领星字段映射表
│   ├── fill.js              # 填充引擎（控件定位 / 下拉匹配 / 面单上传）
│   ├── shipbest.js          # ShipBest 侧同源取数 + 登录态捕获
│   ├── sb-hook.js           # MAIN world 钩子（抓 authorization 头）
│   ├── sb-panel.js          # ShipBest 页内弹框
│   └── lingxing.js          # 领星页内面板
├── app/                     # 订单中心（全页）
├── popup/                   # 工具栏弹窗（3 个按钮）
├── options/                 # 设置页
└── dev/verify.mjs           # 静态一致性 + 纯函数行为断言

本地验证

# 1) 静态一致性 + matchOptions/设置迁移等行为断言（无需浏览器）
node browser-extension/shipbest-lingxing/dev/verify.mjs

# 2) 后台 service worker（chrome.* 桩驱动真实 background.js）
cd .tmp-smoke && node sblx-bg-test.mjs

# 3) 端到端：真实 Chrome + 静态托管扩展 + 假 ShipBest / 假领星页面（场景 A–O）
cd .tmp-smoke && node sblx-e2e.mjs

# 4) 弹窗渲染与按钮宽度检查（可选，出图 .tmp-smoke/sblx-popup.png）
cd .tmp-smoke && node sblx-popup-shots.mjs

.tmp-smoke/ 是本地临时验证目录（不在扩展内），依赖根目录的 playwright-core。

发布流程

改代码
manifest.json 与本文「当前版本」同步递增
上述 1–3 全部通过
同步桌面副本并校验：

rsync -a --delete browser-extension/shipbest-lingxing/ ~/Desktop/shipbest-lingxing/
diff -r browser-extension/shipbest-lingxing ~/Desktop/shipbest-lingxing && echo SYNC_OK

提示使用者到 chrome://extensions 重新加载并刷新已打开页面

十二、版本变更（近期）

版本	变更
0.1.11	修正「清空队列」行为：只删待填充项，已填充记录保留（此前会把整条队列含已填充记录一起清掉，与确认文案不符）；重写安装与使用文档
0.1.10	工具栏弹窗收敛为三个按钮（打开 ShipBest 订单列表 / 打开领星新建一件代发页面 / 清空队列），移除「订单中心」「设置」入口
0.1.9	领星面板删除「当前页面看起来不是建单页」提示块与「打开新建出库单」按钮，不再占用队列版面
0.1.8	承运商同分按候选权威性收敛：`SpeedX` / `SPX` 并存时取订单原值，不再误报歧义；修复下拉选中时元素引用错误（下拉展开但不选值）
0.1.7	建单页默认地址改为「一件代发」`/warehouse/packet/create`，老用户旧默认值自动迁移（自定义地址不覆盖）
0.1.6	承运商改走字段填充（不再进页预选）；失败原因直接写在队列行上