# API Hooks (V2)

Rich Browser 扩展 V2 在所有支持的电商站点 `document_start` 阶段注入一个**通用** hook，
把页面发出的所有 JSON 响应缓存到 `window.__capturedResponses`。

## 文件

- **`loader.js`** — 唯一的 hook 实现，content_script 在 MAIN world 注入。
  挂 `fetch` 和 `XMLHttpRequest` 两条路径，记录所有 JSON 响应。
  失败永远静默降级（不影响页面正常运行）。

## 已支持站点（manifest.json `matches` 列表）

- Ozon: `*.ozon.ru`
- Alibaba / 1688: `*.alibaba.com`, `*.1688.com`
- Taobao / Tmall: `*.taobao.com`, `*.tmall.com`
- Amazon: `*.amazon.{com,de,co.uk,fr,it,es,co.jp}`
- Shein: `*.shein.com`, `*.us.shein.com`
- Temu: `*.temu.com`

新增站点：在 `manifest.json` 的 `content_scripts[1].matches` 加新模式即可，loader.js 不用改。

## 加新站点的步骤

1. 编辑 `manifest.json`，在第二个 `content_scripts` 条目的 `matches` 数组里加新 URL 模式
2. 提升 `version`（语义化：加站点 → minor，bug 修复 → patch，破坏性变更 → major）
3. 在 `chrome://extensions` 里 Reload 扩展（开发期）或推 Web Store 新版（生产）
4. 验证：访问目标站点，`window.__hookSource` 应该是 `extension-v2-bundled`

## 为什么没有 per-site 文件

最初设计是 `api-hooks/seller-ozon-ru.js`、`alibaba-com.js` 等每站一个文件。
实际写完 loader.js 发现 hook 逻辑对所有站点完全通用：
**捕获所有 JSON 响应 → 由技能侧决定怎么解析**。

把 site-specific 解析放在扩展里会让扩展频繁更新（违反 Web Store 政策的代码热更）；
放在技能里则技能是热加载的（沙盒），改完立即生效。所以选择**通用 hook + 技能侧解析**。

如果未来出现某个站点需要扩展级特殊处理（比如内容是 protobuf 而不是 JSON、或需要解密响应），
再单独建 `{site}.js` 文件，loader 按 hostname 分发即可。

## 技能侧消费方式

```javascript
// 在技能 handler.js 里
var hookCheck = await execJs('return { source: window.__hookSource, count: Object.keys(window.__capturedResponses || {}).length };');
if (hookCheck && hookCheck.source) {
  // 新版扩展，可以读 hook 数据
  var data = await execJs('return window.__capturedResponses;');
  // 自己挑感兴趣的 URL，解析 data[url].data
} else {
  // 老版扩展，降级到 DOM 抓取
}
```

## Web Store 政策合规

- ✅ Hook 代码完全打包在扩展内
- ✅ 不远程加载或 eval 代码
- ✅ 透明可审计（loader.js 100 行左右）
- ✅ 不读取 cookie / localStorage / 用户输入，只读 fetch/XHR 响应
