禄得网三页通用插件骨架：设计、实现与部署记录

# 禄得网三页通用插件骨架：设计、实现与部署记录

## 摘要
本文在既有群组文档先例与三页前端接口文档基础上，交付一个面向禄得网转债、股票、ETF 页面，并兼容 Hyper Tuning 页面的通用浏览器插件骨架。该骨架提供五类基础能力：路由识别、API 观测、本地存储、浮动调试面板与按页面挂载功能的扩展框架。其目标不是立即实现具体业务增强，而是为后续的导出脚本、回测增强脚本、调优观测脚本与页面自动化脚本提供统一底座。

## 关键词
禄得网；插件骨架；转债；股票；ETF；Hyper Tuning；浏览器脚本

## 1. 引言
此前群组文档已经形成两类重要先例：

1. 页面级脚本与最小可交付骨架先例；
2. 转债、股票、ETF 三页前端及接口参考文档先例。

在此基础上，继续为后续插件开发提供统一底座，是符合 Case Law 的自然延伸。相比每次脚本需求都从零编写注入逻辑、路由识别逻辑和 API 观测逻辑，沉淀一个通用骨架可以显著降低重复开发成本。

## 2. Case Law 决策依据

### 2.1 已检索先例
本次检索到的直接相关先例包括：

1. [478]《示范图插件骨架脚本：纠偏实现、最小交付与验证方法》；
2. [481]《禄得网转债、股票与 ETF 页面前端及接口文档：脚本开发参考》。

### 2.2 沿用原则
本次实现沿用以下先例原则：

1. 先检索，再编码；
2. 骨架先做通用能力，不凭空假设具体业务；
3. 交付物应可直接装入当前浏览器验证；
4. 同步把脚本说明写入群组文档。

### 2.3 最小偏离说明
本次骨架覆盖了 Hyper Tuning 页面，严格说已超出“转债、股票、ETF 三页”本体。但此偏离是最小且有益的，原因在于：

1. Hyper Tuning 与三页共享资产类型适配逻辑；
2. 当前页面正位于 Hyper Tuning；
3. 把 Hyper Tuning 一并纳入底座，可减少未来再拆一套观察器的重复劳动。

## 3. 设计目标
骨架脚本旨在提供以下基础设施：

1. 统一识别当前页面路由；
2. 统一记录 `fetch` 与 `XMLHttpRequest` 请求；
3. 统一维护本地缓存；
4. 提供固定的浮动调试面板；
5. 通过 feature mount 机制按页面挂载不同能力；
6. 为未来导出、标注、批处理与自动化脚本预留扩展位。

## 4. 实现结构

### 4.1 路由层
骨架内建路由常量：

1. `/rotation/convertible-bond`
2. `/rotation/stock`
3. `/rotation/etf`
4. `/hyper-tuning`
5. `/hyper-tuning-history`

并通过 `classifyRoute(pathname)` 统一分类为：

1. `CONVERTIBLE_BOND`
2. `STOCK`
3. `ETF`
4. `HYPER_TUNING`
5. `HYPER_TUNING_HISTORY`
6. `UNKNOWN`

### 4.2 存储层
骨架提供 `storage.get/set` 封装，统一以 `__lude_three_page_plugin__` 为前缀写入 `localStorage`，用于保存：

1. API 记录；
2. 用户偏好；
3. 后续导出模板；
4. 页面快照配置。

### 4.3 API Observer 层
骨架同时拦截：

1. `window.fetch`
2. `XMLHttpRequest.prototype.open/send`

并只记录包含以下前缀的请求：

1. `/v1/quant/`
2. `/v2/quant/`

每条记录至少保存：

1. `transport`
2. `routeKey`
3. `method`
4. `url`
5. `status`
6. `durationMs`
7. `at`

### 4.4 面板层
骨架注入了一个固定在右上角的浮动面板，显示：

1. 当前路由；
2. 是否处于引导态；
3. 当前已记录 API 数量；
4. 最近一条 API 记录；
5. DOM 扫描结果。

并提供三个操作按钮：

1. 清空 API；
2. 导出 API；
3. 扫描 DOM。

### 4.5 Feature 层
骨架内建了 `featureMountByRoute()` 作为统一扩展入口，并预置两类基础 feature：

1. 页面左下角路由提示条；
2. 基于 `MutationObserver` 的页面变化探针。

未来新增脚本时，可继续按页面类型注册：

1. 回测增强 feature；
2. 策略列表导出 feature；
3. 因子面板搜索 feature；
4. Hyper Tuning 任务观察 feature。

### 4.6 Router 变化监听
骨架通过以下方式追踪 SPA 路由变化：

1. 重写 `history.pushState`；
2. 重写 `history.replaceState`；
3. 监听 `popstate`；
4. 轮询 `location.href` 兜底。

该设计可以覆盖绝大多数 React SPA 切页场景。

## 5. 本地交付结果

### 5.1 脚本信息
- 脚本 ID：`ludevip__rotation-three-page-plugin-skeleton`
- 脚本名称：`禄得网三页通用插件骨架`
- 注入时机：`document_idle`
- 匹配 URL：`https://next\.lude\.site/(rotation/(convertible-bond|stock|etf)|hyper-tuning).*`

### 5.2 本地文件
- `data/automa/ludevip__rotation-three-page-plugin-skeleton/plugin.json`
- `data/automa/ludevip__rotation-three-page-plugin-skeleton/script.js`

### 5.3 远端安装结果
脚本已成功：

1. 推送到当前配对浏览器 `u18cjw`；
2. 安装到浏览器扩展脚本列表中。

## 6. 适用场景
该骨架适用于以下后续开发方向：

1. 三页统一接口观测器；
2. 转债/股票/ETF 列表导出工具；
3. 回测页面增强；
4. 因子配置辅助工具；
5. Hyper Tuning 调优任务观察器；
6. 路由级自动化操作脚本。

## 7. 风险与限制

### 7.1 当前版本限制
1. 目前只记录请求元信息，未采集响应体摘要；
2. DOM 扫描仍偏通用，尚未沉淀页面级业务选择器；
3. Feature 层只是骨架，尚未挂载具体业务模块。

### 7.2 扩展建议
下一步建议按以下顺序增强：

1. 增加响应体摘要与错误信息采集；
2. 增加三页表格、因子区、回测区的 DOM adapter；
3. 增加导出器与标注器；
4. 增加 Hyper Tuning 任务结果摘要视图。

## 8. 结论
本文已完成禄得网三页通用插件骨架的设计、实现与部署。该骨架延续了本群“先沉淀底座，再叠加功能”的先例，已具备统一的路由、观测、存储与面板能力，可直接作为后续插件开发的标准起点。

## 附录：骨架能力摘要
1. 路由识别；
2. guide 参数识别；
3. fetch/XHR 拦截；
4. API 记录缓存；
5. 浮动调试面板；
6. DOM 扫描器；
7. SPA 路由变化监听；
8. Feature 挂载入口。