feat: 增加 MCP 研究模板保存工具
This commit is contained in:
yuxuanhui
+44
-2
@@ -1,6 +1,6 @@
|
||||
# MCP 研究接入
|
||||
|
||||
MCP 让外部助手直接查询数据元信息、查回测历史、提交固定候选、执行本地自相关检查并读取结果。无需先建立特征、模板、变体或 QuantFlow。执行仍由网页共用的持久队列负责，回测页保存同一个运行。
|
||||
MCP 让外部助手直接查询数据元信息、查回测历史、提交固定候选、执行本地自相关检查并读取结果，也能把研究后总结的模板保存到模板工坊。直接回测无需先建立特征、模板、变体或 QuantFlow。执行仍由网页共用的持久队列负责，回测页保存同一个运行。
|
||||
|
||||
## 启用与令牌
|
||||
|
||||
@@ -35,6 +35,7 @@ python -m app.cli mcp-token-revoke TOKEN_ID
|
||||
| --- | --- |
|
||||
| research:read | 能力、数据目录、元数据、历史、运行、结果、证据、刷新及自相关任务查询、自相关结果读取 |
|
||||
| research:refresh | 显式更新元数据及 PnL 缓存、发起本地自相关检查、使用已保存凭据重新连接或继续认证；同时要求 read |
|
||||
| research:write | 保存外部助手总结的研究模板及来源证据；不调用模型、不执行回测；同时要求 read |
|
||||
| backtests:execute | 直接提交固定候选；同时要求 read |
|
||||
| backtests:control | 暂停、继续、停止、恢复采集；同时要求 read |
|
||||
|
||||
@@ -49,6 +50,7 @@ python -m app.cli mcp-token-revoke TOKEN_ID
|
||||
| get_worldquant_connection | `{job_id?}`；只读连接状态及认证任务状态，不返回密码、Cookie 或验证链接 |
|
||||
| authenticate_worldquant | `{action?:"connect"或"verify"}`；默认 connect，使用已保存凭据异步认证，返回 job_id；要求 research:refresh |
|
||||
| get_research_capabilities | `{}`，含单次候选上限及完整候选 schema |
|
||||
| create_research_template | `{template,hypothesis,source_item_ids,idempotency_key,reference?}`；保存调用方生成的完整模板，要求 research:write |
|
||||
| search_catalog | `{filters:{region,universe,delay,...},dataset_id?}`；省略 dataset_id 查数据集，提供则查字段 |
|
||||
| get_research_metadata | `{query:{kind,...}}`；kind 为 scopes/settings/operators/field_availability |
|
||||
| refresh_research_data | `{query:{kind,...}}`；kind 为 catalog/operators/settings/field_availability/pnl |
|
||||
@@ -118,6 +120,46 @@ metadata 的 operators 支持 q/category 和分页；settings 支持分页；fie
|
||||
|
||||
提交自动保存固定预览和运行，返回 backtest_run_id、输入摘要、数量和 web_url。打开 web_url 可定位网页详情；来源显示“MCP 研究”，可以按来源筛选。后续 get_backtest 和 get_backtest_results 读取进度与结果。PnL 未缓存时返回 not_cached，通过显式刷新再读取。下一批可设置 source.parent_run_id 关联前一批。
|
||||
|
||||
## 研究后保存模板
|
||||
|
||||
外部大模型先用 `get_backtest_results` 阅读具体候选的指标及检查，判断哪些研究结果值得继续探索，再自行总结经济假设和参数化表达式，调用 `create_research_template`。此工具接收模型已经思考完成的模板，不调用服务端模型。保存成功后，模板出现在网页 **模板工坊**，用户可选择固定输入和模拟设置，全量展开或随机采样候选，再确认批量回测。
|
||||
|
||||
该工具使用新的 `research:write` 权限。已有 Key 不自动获得写入权限；在 **系统管理 → MCP Key** 创建 Key 时勾选“保存研究模板”，或签发专用 Key：
|
||||
|
||||
```bash
|
||||
python -m app.cli mcp-token-create --name research-template-writer \
|
||||
--scope research:read --scope research:write
|
||||
```
|
||||
|
||||
调用结构示例（候选 ID 需替换为实际读取的 `items[].id`，不是 `client_item_id` 或 Alpha ID）：
|
||||
|
||||
```json
|
||||
{
|
||||
"template": {
|
||||
"name": "短期反转窗口研究",
|
||||
"description": "将已研究的反转表达式提炼为字段和窗口候选；替换字段及其他窗口仍需逐项验证。",
|
||||
"expression": "-rank(ts_delta({price}, {window}))",
|
||||
"variables": {
|
||||
"price": {"kind": "field", "field_type": "MATRIX", "values": ["close", "vwap"]},
|
||||
"window": {"kind": "integer", "values": [3, 5, 10, 20]}
|
||||
},
|
||||
"scope": {"instrument_type": "EQUITY", "region": "USA", "universe": "TOP3000", "delay": 1}
|
||||
},
|
||||
"hypothesis": "来源结果支持继续比较短期价格反转；通过改变价格字段和观察窗口检验稳定性。",
|
||||
"source_item_ids": ["REPLACE_WITH_BACKTEST_ITEM_ID"],
|
||||
"reference": "research-round-001",
|
||||
"idempotency_key": "reversal-template-001"
|
||||
}
|
||||
```
|
||||
|
||||
`template` 复用模板工坊的结构：表达式使用 `{name}` 占位符，`variables` 必须逐一对应；变量 kind 支持 field/operator/integer/number/group/string/fragment，字段变量必须声明 MATRIX/VECTOR/GROUP 类型，VECTOR 的聚合方式应明确写在表达式中。工具只创建 category=template 的完整模板。`scope` 可省略；指定后，后续展开须使用相同范围。字段候选应先通过目录核对，工具保存时不隐式刷新元数据。
|
||||
|
||||
`source_item_ids` 为 1–20 个不重复的本地回测候选，可来自多个运行；须完成平台回测、结果采集及持久化，且存在完整结果快照。服务端读取并固定其表达式、模拟设置、运行 ID、Alpha ID、观测时间、指标和检查摘要，不接收调用方自报的成绩。研究假设和外部 reference 是调用方提供的说明。来源存在不代表经济假设成立，completed 不代表所有检查 PASS，也不代表模板的其他参数组合已回测。
|
||||
|
||||
返回 `template_id`（同 `id`）、`version`、完整模板 `content`、来源 `provenance`、字符串形式的理论 `combination_count` 和模板工坊 `web_url`。示例有 8 种参数组合；组合数不去重，也不代表已创建实验或运行。结构校验与来源记录状态在 `validation` 中说明，展开候选和平台语义仍未验证。网页展开继续执行原有字段归属、类型、设置和语法校验；全量展开超过 10000 项时需缩小候选或使用随机采样。
|
||||
|
||||
相同账户、操作和幂等键的相同请求重放首次成功响应，跨 Key 重试和服务重启仍有效；同键不同内容返回 `IDEMPOTENCY_CONFLICT`。模板同名（含已删除模板）返回 `TEMPLATE_NAME_CONFLICT`，不覆盖任何已有版本。来源缺失返回 `NOT_FOUND`，未完成返回 `SOURCE_NOT_READY`，结构错误返回 `INVALID_INPUT`。失败不创建资产、不占用幂等键。创建只写入现有资产、版本、请求和审计表，无新增迁移，不启动模型、实验、队列或定时研究。
|
||||
|
||||
## 幂等、重复与状态
|
||||
|
||||
- 成功请求按账户、操作和幂等键固定首次响应。相同请求重试返回原响应，不重新提交；换令牌不改变该范围。同键不同内容返回 IDEMPOTENCY_CONFLICT。失败校验不占用幂等键。
|
||||
@@ -135,7 +177,7 @@ metadata 的 operators 支持 q/category 和分页；settings 支持分页；fie
|
||||
|
||||
## 验证和限制
|
||||
|
||||
本地测试只使用模拟平台。后端 `uv run pytest -q tests/test_mcp.py` 包含官方 MCP ClientSession 的 HTTP 工具往返；浏览器测试在临时数据库里验证实际 MCP 提交的运行链接和来源。
|
||||
本地测试只使用模拟平台。后端 `uv run pytest -q tests/test_mcp.py tests/test_mcp_templates.py` 包含官方 MCP ClientSession 的 HTTP 工具往返，并验证模板写入权限、幂等重放、固定来源和网页模板展开；浏览器测试在临时数据库里验证实际 MCP 提交的运行链接和来源。
|
||||
|
||||
独立 PostgreSQL 检查只接受本机 `wq_mcp_test` 数据库：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user