HomeDash/extension/README.md

JianF Nav Sync — 浏览器扩展

将浏览历史同步到自建导航门户，按总访问频次自动排序「常用服务」与「历史访问」。

安装

Chrome / Edge（MV3）

1. 打开 chrome://extensions/
2. 开启右上角「开发者模式」
3. 点「加载已解压的扩展程序」，选择本目录的 chrome/ 文件夹
4. Edge 同理：edge://extensions/

Firefox（MV2）

1. 打开 about:debugging#/runtime/this-firefox
2. 点「临时加载附加组件」，选择本目录 firefox/ 下的 manifest.json
3. 长期使用：web-ext build 打包后到 about:addons 安装

iOS / 手机浏览器

系统浏览器扩展 API 不适用于 iOS Safari 普通网页。可用备选：

• iOS Safari Web Extension（需 Xcode 工程封装）
• Android 上使用 Kiwi / Yandex 等支持 MV3 的浏览器加载 chrome/

配置（点击扩展图标）

字段	说明
导航服务地址	你的门户根地址，如 https://nav.example.com（不要带 /search 等路径）
同步令牌	服务端环境变量 NAVI_SYNC_TOKEN 的值（服务端开启鉴权时必填）
设备名称	可选，留空则自动检测。Firefox 版按 UA 识别（desktop-firefox / mobile-* / desktop-edge 等）；Chrome 版的 MV3 service worker 里没有 navigator，只能回退为 desktop-browser（需要区分设备时请手填）

行为

• 每 30 秒用 chrome.history.search 拉取最近 2 小时新记录（不依赖 onVisited 事件，MV3 休眠也可靠）
• 本地过滤：搜索引擎域名、/search?q= 结果页、chrome://、about: 等一律不上传
• 同一网址 10 分钟内去重、同批 URL 去重
• 仅在有待同步数据时发 POST（无空轮询）
• 同步失败自动保留队列，下轮重试
• 上报带 Authorization: Bearer <token>；门户「常用服务/历史访问」按 total_visits 自动更新

技术细节

• Chrome/Edge: Manifest V3，service worker + chrome.alarms(最小周期 30s)
• Firefox: Manifest V2，event page（persistent: true）+ browser.alarms
• 存储: storage.local（pending 队列 + 配置）
• API: history.search + alarms + runtime.onMessage
• visit_count 上报的是 Chrome/Firefox history API 的绝对累计值，不是增量。 服务端（history-server）按设备取绝对值再求和，所以重复上报不会把计数放大。
• 两个目录的 background.js 不是同一份文件：Firefox 额外做设备名识别 （MV2 常驻后台，navigator 可用），并过滤 moz-extension://。 改动时两边都要改，但不要直接整份覆盖。