禄得网 Hyper Tuning 页面前端及接口文档：群组脚本开发参考

# 禄得网 Hyper Tuning 页面前端及接口文档：群组脚本开发参考

## 摘要
本文针对禄得网 `Hyper Tuning` 页面建立第一版前端与接口参考文档，用于支持后续页面脚本开发、接口观测脚本编写与自动化增强。本文遵循本群既有 Case Law：先检索历史先例，再以 Wiki 文档形式沉淀结果；在缺乏运行态网络面板导出的条件下，优先采用静态 Bundle 逆向法提取路由、接口命名、状态枚举与对象结构。分析结果表明，Hyper Tuning 页面是禄得网量化三页（转债、股票、ETF）之上的跨品种超参调优能力层，通过 `security_type` 将不同资产路由到统一的调优工作流。

## 关键词
禄得网；Hyper Tuning；超参调优；前端逆向；接口文档；浏览器脚本

## 1. 引言
超参调优页面不同于转债、股票、ETF 三个具体策略页面。三页页面关注策略创建、编辑、回测与筛选，而 Hyper Tuning 页面承担的是跨资产类型的参数搜索、目标函数优化与实验结果追踪。因此，若后续需要开发：

1. 调优任务观测脚本；
2. 调优结果增强脚本；
3. 多轮调优过程记录脚本；
4. 三页通用插件与 Hyper Tuning 的联动工具；

则必须先建立该页面的基础前端与接口文档。

## 2. Case Law 决策依据

### 2.1 已检索先例
本次先检索了群组历史记录与 Wiki 文档，相关先例包括：

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

### 2.2 沿用原则
沿用的先例原则如下：

1. 先检索 `get_conversation_history` 与 `wiki_search`；
2. 输出以学术格式组织；
3. 文档落到群组文集 `collection_id=39`；
4. 页面脚本参考文档先做静态逆向，再逐步补全运行态样本。

### 2.3 最小偏离说明
本次仍未直接使用运行态抓包明细，而是继续使用静态 Bundle 逆向。偏离理由是：

1. 当前任务重点是“存文档并形成开发骨架”；
2. 主 Bundle 已暴露足够多的 Hyper Tuning 枚举、接口路径与类型映射；
3. 第一版脚本开发不必等待完整抓包，即可先建立观察器、面板与数据缓存层。

## 3. 研究方法

### 3.1 数据来源
本文基于如下证据：

1. 当前页面：`https://next.lude.site/hyper-tuning`；
2. 主 Bundle：`/assets/js/main.d30919d5.js`；
3. 先前已下载的相关 chunk 与接口命名集合；
4. 静态提取到的 Hyper Tuning 路由与方法名。

### 3.2 核心识别结果
静态分析已识别：

1. 路由 `/hyper-tuning`；
2. 历史页 `/hyper-tuning-history`；
3. 接口路径族 `/v2/quant/hyper-tunings...`；
4. 资产特化预创建路径 `/v2/quant/{asset}/hyper-tunings/pre-create`；
5. 资产特化创建路径 `/v2/quant/{asset}/hyper-tunings`。

## 4. 页面定位与功能角色

### 4.1 页面路由
可确认的页面相关路由包括：

1. `/hyper-tuning`
2. `/hyper-tuning-history`

这说明至少存在两个界面：

1. 调优任务创建/执行页；
2. 调优历史或结果回看页。

### 4.2 页面功能角色
Hyper Tuning 页面属于跨资产统一层，其功能角色包括：

1. 选择资产类型；
2. 选择目标函数；
3. 配置搜索空间；
4. 发起调优任务；
5. 查询任务列表；
6. 读取任务详情；
7. 拉取增量回答流或日志；
8. 继续运行已暂停任务。

## 5. 核心前端对象模型

### 5.1 资产类型映射
静态代码中存在一段显式映射逻辑，将 `security_type` 转成接口路径中的资产标识：

1. `STOCK -> stock`
2. `ETF -> etf`
3. `CONVERTIBLE_BOND -> convertible-bond`

这意味着 Hyper Tuning 本质上是对三页策略体系的统一封装，而不是第四套独立策略引擎。

### 5.2 状态枚举
已识别调优任务状态枚举 `HyperTuningStudyStatus`：

1. `WAITING = 0`
2. `RUNNING = 1`
3. `FINISHED = 2`
4. `PAUSING = 3`
5. `PAUSED = 4`

### 5.3 配置类型枚举
已识别配置类型 `HyperTuningConfigType`：

1. `Options`
2. `Range`

该枚举说明搜索空间至少支持：

1. 离散可选值搜索；
2. 连续/区间搜索。

### 5.4 方向枚举
已识别优化方向 `HyperTuningDirection`：

1. `maximize`
2. `minimize`

### 5.5 搜索域参数名
已识别 `HyperTuningScopeArgName`：

1. `rank_weight`
2. `rank_factor`
3. `filter_value`
4. `stop_profit_loss`

这些字段表明 Hyper Tuning 至少可以调优：

1. 排名权重；
2. 排名因子；
3. 过滤阈值；
4. 止盈止损参数。

### 5.6 目标函数枚举
已识别 `HyperTuningObjectiveFunction` 包括：

1. `total_return`
2. `annu_return`
3. `daily_win_rate`
4. `daily_profit_loss_rate`
5. `sharpe_ratio`
6. `calmar_ratio`
7. `sortino_ratio`
8. `daily_max_drawdown`
9. `daily_pnl_mean`
10. `daily_pnl_std`
11. `daily_max_profit`
12. `daily_max_loss`
13. `daily_profit_mean`
14. `daily_loss_mean`
15. `daily_loss_std`
16. `daily_turnover`

这说明调优页面不是简单的参数穷举 UI，而是具有较完整的目标函数定义体系。

## 6. 接口文档

### 6.1 通用目标函数接口
- `GET /v2/quant/hyper-tunings/objective-functions`

用途：获取可选目标函数列表。

### 6.2 任务列表接口
- `GET /v2/quant/hyper-tunings?offset={offset}&limit={limit}`

用途：获取调优任务列表。

### 6.3 任务详情接口
- `GET /v2/quant/hyper-tunings/{id}`

用途：获取单个调优任务详情。

### 6.4 任务回答/增量结果接口
- `GET /v2/quant/hyper-tunings/{id}/answers?last_id={lastId}`

用途：读取调优过程中的回答流、结果流或阶段性日志。

### 6.5 任务继续执行接口
- `POST /v2/quant/hyper-tunings/{id}/resume`

请求体中静态可见字段：

- `n_trails`

说明：该接口用于追加运行轮次或继续一个暂停任务。

### 6.6 资产特化预创建接口
- `POST /v2/quant/stock/hyper-tunings/pre-create`
- `POST /v2/quant/etf/hyper-tunings/pre-create`
- `POST /v2/quant/convertible-bond/hyper-tunings/pre-create`

用途：根据资产类型与参数配置，预校验/预生成调优任务输入。

### 6.7 资产特化创建接口
- `POST /v2/quant/stock/hyper-tunings`
- `POST /v2/quant/etf/hyper-tunings`
- `POST /v2/quant/convertible-bond/hyper-tunings`

用途：正式创建并启动调优任务。

## 7. 前端结构推断

### 7.1 页面区域
基于对象模型和接口命名，可推断页面至少包含以下区域：

1. **资产类型选择区**；
2. **目标函数选择区**；
3. **搜索空间配置区**；
4. **任务摘要区**；
5. **执行状态区**；
6. **回答流/结果流展示区**；
7. **历史记录跳转或历史列表入口**。

### 7.2 与三页页面的关系
Hyper Tuning 与转债、股票、ETF 三页并非割裂关系，而是复用它们的策略参数语义。故脚本开发时应优先共享以下基础能力：

1. 路由识别器；
2. 统一接口观测器；
3. 本地缓存层；
4. 日志面板；
5. 资产类型适配器。

## 8. 脚本开发建议

### 8.1 可优先开发的脚本
1. 调优任务实时观测器；
2. 任务列表导出器；
3. 目标函数说明增强脚本；
4. 搜索空间配置快照脚本；
5. 调优结果摘要面板。

### 8.2 注入建议
建议：

1. 使用 `document_idle` 注入；
2. 以 `location.pathname === '/hyper-tuning'` 和 `'/hyper-tuning-history'` 做页面识别；
3. 对回答流区域使用 `MutationObserver`；
4. 对接口层统一拦截 `/v2/quant/hyper-tunings` 与 `/v2/quant/{asset}/hyper-tunings`。

### 8.3 风险点
1. 无运行态请求体样例，字段仍需后续补全；
2. 历史页与详情页的实际 DOM 结构尚未实测；
3. 回答流的增量更新频率与分页机制仍需运行态观察。

## 9. 结论
本文已将当前 `Hyper Tuning` 页面整理为群组文档，形成第一版脚本开发参考。其核心结论为：

1. Hyper Tuning 是跨转债、股票、ETF 的统一调优层；
2. 页面围绕目标函数、搜索空间与任务执行状态组织；
3. 接口体系以 `/v2/quant/hyper-tunings` 为核心，并通过 `security_type` 分流到具体资产路径；
4. 该页面与三页通用插件骨架可共享统一 router、api observer、storage 与面板框架。

## 参考证据附录

### 附录 A：识别出的路由
- `/hyper-tuning`
- `/hyper-tuning-history`

### 附录 B：识别出的核心方法名
- `getHyperTuningList`
- `getHyperTuningDetail`
- `getHyperTuningAnswer`
- `getHyperTuningObjectiveFunctions`
- `preCreateHyperTuning`
- `createHyperTuning`
- `continueHyperTuning`

### 附录 C：后续补充建议
后续可在运行态拦截脚本完成后补充：

1. 请求体示例；
2. 目标函数中文说明；
3. 任务状态转换图；
4. 回答流与结果流字段结构；
5. Hyper Tuning 与三页策略配置的字段映射表。

### 附录 D：自定义参数书签第一版实现与验证记录（2026-05-14）

#### D.1 研究目的
基于 Hyper Tuning「其它参数调优」区域的截图样式，先实现一个独立书签面板，用于配置参数名、最小值、最大值、步长和单位，并生成参数搜索预览。该版本不直接写入站点原生表单，以降低误提交风险。

#### D.2 实现位置
- 本地文件：`/home/horizon/chat--5179204355/lude_custom_param_bookmark.js`
- 构建标识：`lude-custom-param-bookmark-20260514-v001`

#### D.3 实现方法
书签以悬浮面板形式渲染，默认参数为「止盈比例」，输入结构为「参数名、最小值、最大值、步长、单位、删除」。配置写入 `localStorage.lude_custom_param_bookmark_v1`，支持添加参数、删除参数、重置、生成预览和复制 JSON。

#### D.4 运行态验证
在 `https://next.lude.site/rotation/convertible-bond` 页面通过 CDP 执行书签文件完成验证：

1. 默认渲染成功：面板存在，默认行数为 1，默认参数为「止盈比例」。
2. 生成逻辑成功：输入最小值 0、最大值 6、步长 1 后，生成 `[0,1,2,3,4,5,6]`，组合数为 7。
3. 行操作成功：添加参数后行数为 2，删除一行后行数回到 1。
4. 本地恢复成功：重跑书签后可从 localStorage 恢复保存配置。
5. 隔离性验证成功：生成预览只操作书签面板和本地缓存，不修改禄得原生表单。

#### D.5 结论
第一版适合作为用户自定义参数书签骨架。后续若要一键写入 Hyper Tuning 原生表单，应先补充字段映射和原生表单事件验证。

### 附录 E：自定义参数书签 v002 批量自动回测实现与验证记录（2026-05-15）

#### E.1 研究目的
用户在第一版参数书签中完成「止盈比例」范围设置后，需要直接批量执行回测，而不是只生成参数预览。本次增强目标是在保留第一版悬浮面板和 `localStorage.lude_custom_param_bookmark_v1` 配置结构的基础上，增加“捕获原生回测请求模板、确认止盈字段路径、顺序重放参数队列、展示与导出结果”的能力。

#### E.2 实现位置
- 本地文件：`/home/horizon/chat--5179204355/lude_custom_param_bookmark.js`
- 构建标识：`lude-custom-param-bookmark-20260514-v003`

#### E.3 方法
本次没有采用直接写入页面 `#stop_value` 再触发按钮的方案。原因是 React 受控表单可能不会同步 DOM `.value` 到真实请求体。v002 改为网络模板重放：

1. 安装 `fetch` 与 `XMLHttpRequest` hook，匹配 `/advanced-backtest`、`/{asset}/backtest`、`/{asset}/factors/backtest` 三类回测请求。
2. 用户手动回测两次，书签捕获两份请求样本。
3. 对两份请求体做结构化 diff，识别从 `3` 到 `3.1` 或从 `0.03` 到 `0.031` 的候选字段路径。
4. 唯一候选自动确认，多候选由面板下拉框确认。
5. 复用第一版 `generateValues` 生成参数值队列，MVP 只支持单参数队列，默认可生成 `3, 3.1, ..., 6` 共 31 次。
6. 用捕获模板按确认字段路径替换参数值，顺序调用原生 `fetch` 重放回测请求。
7. 解析 JSON/SSE 响应中的 `timelines`，计算总收益率、年化收益率、最大回撤、夏普比和时间序列条数。
8. 面板展示执行进度、成功数、失败数、结果表，并支持复制 JSON 与 CSV。

#### E.4 调试日志
v002 保留运行态业务日志，所有日志通过 `console.info('[LudeCustomParamBookmark]', tag, data)` 输出，同时保存在 `window.__LUDE_CUSTOM_PARAM_BOOKMARK__.logs`。关键语义标签包括：

- `batch.hook.installed`
- `batch.request.matched`
- `batch.template.captured`
- `batch.diff.candidates`
- `batch.stop_path.confirmed`
- `batch.item.request_built`
- `batch.item.response_parsed`
- `batch.item.failed`
- `batch.run.completed`

默认日志只记录 URL path、body 字节数、候选字段摘要、timelines 数量和耗时，不打印 cookie 或 authorization 等敏感头。

#### E.5 运行态验证
在 `https://next.lude.site/rotation/convertible-bond` 页面通过 CDP 执行书签文件完成初始化验证：

1. 书签执行成功，面板存在。
2. 构建标识为 `lude-custom-param-bookmark-20260514-v002`。
3. 默认参数生成结果为 31 个组合。
4. 面板已出现批量自动回测区域。
5. 操作按钮包含 `install-capture`、`test-replay`、`run-batch`、`stop-batch`、`copy-results-json`、`copy-results-csv`。
6. 控制台出现 `panel.rendered`，无书签解析错误。
7. v003 修复事件重绑与跨域重放：重新注入同构建号时旧事件闭包可能仍被沿用，因此构建号升级到 v003 触发重新绑定；跨域 API 重放不再强制 `credentials: include`，避免 CORS 阶段 `TypeError: Failed to fetch`。
8. v003 测试重放验证：字段路径 `strategy.stop_method.stop_value`，scale `0.01`；止盈 `3` 单次重放成功，解析 `timelines` 915 条，得到总收益率 `236.61%`、年化收益率 `37.82%`、最大回撤 `-10.85%`、夏普比 `2.163`。

#### E.6 使用流程

1. 打开禄得回测页面并运行书签。
2. 设置参数为「止盈比例」，最小值 `3`，最大值 `6`，步长 `0.1`，单位 `%`。
3. 点击“安装监听/捕获模板”。
4. 在禄得原生页面分别以止盈 `3` 和 `3.1` 手动回测两次。
5. 面板确认止盈字段路径。
6. 点击“测试重放一次”验证模板可用。
7. 点击“开始批量回测”顺序执行 31 次。
8. 完成后复制 JSON 或 CSV 结果。

#### E.7 限制
当前 MVP 只支持 JSON 与 `application/x-www-form-urlencoded` 请求体，只支持单参数队列。若后续需要多参数笛卡尔积、FormData 请求体或直接对接 Hyper Tuning 任务接口，应在现有模板捕获和字段确认链路验证通过后再扩展。

### 附录 F：自定义参数书签 v009 下载版与运行验证记录（2026-05-15）

#### F.1 研究目的
v009 版本用于解决用户批量自动回测时结果行重复为 `3` 或 `3.1` 的问题，并交付可复制到浏览器收藏夹的网址栏的 bookmarklet 下载文件。

#### F.2 实现位置
- 本地文件：`/home/horizon/chat--5179204355/lude_custom_param_bookmark.js`
- 下载版文件：`/home/horizon/chat--5179204355/lude_custom_param_bookmark_v009_download.txt`
- 构建标识：`lude-custom-param-bookmark-20260514-v009`

#### F.3 方法
v009 保留“捕获原生回测请求模板并顺序重放”的总体方案，并补充三项稳定性措施：

1. 新实例初始化时恢复旧 `fetch` 与 `XMLHttpRequest` hook，停止旧批次，避免多次注入后的旧循环继续写入结果。
2. 每次批量运行生成独立 `runId`，异步响应返回后必须匹配当前 `runId` 与 `INSTANCE_ID` 才允许写入结果。
3. 请求头分为 `headers` 与 `replayHeaders`：日志和界面只使用脱敏后的 `headers`，重放请求使用内存中的 `replayHeaders`，避免因过滤 `Access-Token` 导致认证失败。

#### F.4 运行态验证
在 `https://next.lude.site/rotation/convertible-bond` 页面验证：

1. 小批量参数 `3` 到 `3.2`、步长 `0.1` 生成队列为 `[3, 3.1, 3.2]`。
2. 请求构造日志显示止盈字段路径为 `strategy.stop_method.stop_value`，并依次写入 `0.03`、`0.031`、`0.032`。
3. 用户随后确认 v009 可用，正式下载版按 v009 标识生成。

#### F.5 交付方式
由于上传服务拦截 `.js` 后缀，下载版按历史先例使用 `.txt` 后缀交付。用户打开文件后复制整段 `javascript:...`，粘贴到浏览器书签的网址栏即可。