# 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://`。
  改动时两边都要改，但不要直接整份覆盖。