feat: expose local self-correlation tools through MCP

docs/mcp-research.md

@@ -1,6 +1,6 @@
 # MCP 研究接入
 
-MCP 让外部助手直接查询数据元信息、查回测历史、提交固定候选并读取结果。无需先建立特征、模板、变体或 QuantFlow。执行仍由网页共用的持久队列负责，回测页保存同一个运行。
+MCP 让外部助手直接查询数据元信息、查回测历史、提交固定候选、执行本地自相关检查并读取结果。无需先建立特征、模板、变体或 QuantFlow。执行仍由网页共用的持久队列负责，回测页保存同一个运行。
 
 ## 启用与令牌
 
@@ -33,8 +33,8 @@ python -m app.cli mcp-token-revoke TOKEN_ID
 
 | 权限 | 可调用能力 |
 | --- | --- |
-| research:read | 能力、数据目录、元数据、历史、运行、结果、证据、刷新任务查询 |
-| research:refresh | 显式更新元数据及 PnL 缓存；同时要求 read |
+| research:read | 能力、数据目录、元数据、历史、运行、结果、证据、刷新及自相关任务查询、自相关结果读取 |
+| research:refresh | 显式更新元数据及 PnL 缓存、发起本地自相关检查；同时要求 read |
 | backtests:execute | 直接提交固定候选；同时要求 read |
 | backtests:control | 暂停、继续、停止、恢复采集；同时要求 read |
 
@@ -50,7 +50,9 @@ python -m app.cli mcp-token-revoke TOKEN_ID
 | 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 |
-| get_refresh_job | `{job_id,limit?,offset?}`；错误列表独立分页 |
+| get_refresh_job | `{job_id,limit?,offset?}`；查询刷新或自相关任务，错误列表独立分页 |
+| check_self_correlation | `{alpha_ids:[...]}`，1–100 个已导入 Alpha ID；异步返回 job_id |
+| get_self_correlation | `{alpha_id}`；只读最新本地结果，含缓存和 stale 状态 |
 | search_backtests | 来源、reference、status、带时区起止时间、scope、q、候选精确匹配及分页 |
 | submit_backtests | `{name,candidates,idempotency_key,duplicate_policy?,source?}` |
 | get_backtest | `{run_id,after?,event_limit?}`，after 为事件游标 |
@@ -62,6 +64,18 @@ metadata 的 operators 支持 q/category 和分页；settings 支持分页；fie
 
 列表默认 25 项、最多 100 项；返回 total、offset、limit、has_more。快照证据按顶层 key/value 分页，嵌套内容完整保留；PnL 按日期过滤和分页。元数据仅提供字段与算子资料，不提供原始财务时间序列。
 
+## 本地自相关检查
+
+目标 Alpha 必须已导入；比较基准为本地已同步的同地区已提交 Alpha，排除自身。建议先在网页全量同步已提交 Alpha。MCP 不隐式导入 Alpha 或同步基准列表。
+
+1. 调用 `check_self_correlation`，例如 `{"alpha_ids":["LL977PqL"]}`，获取 `job_id`。目标去重排序，相同目标集合的活动任务会复用；完成后再次调用会重新计算。
+2. 用 `get_refresh_job` 查询进度、失败原因与分页错误。受理后客户端断开不影响后台任务；取消及重试可在网页任务面板执行。
+3. 完成后调用 `get_self_correlation`，例如 `{"alpha_id":"LL977PqL"}`。返回 `source=local`，`status` 为 `not_cached`、`available` 或 `stale`；没有结果时 `cached=false`、`result=null`，读取不会隐式启动检查。
+
+检查优先使用已有 PnL 缓存，缺失时由后台自动补取并落库，等待遵循平台 Retry-After。计算使用累计 PnL 的日变化、目标最新数据日前四年的共同窗口、至少 30 个有效样本，取带符号最大的 Pearson 相关系数，阈值为 0.7。结果包含比较数、跳过数、最相关 Alpha、窗口、样本和缓存时间；最多列出前 10 个匹配及前 100 个跳过原因。缺少基准或有效样本会明确报告数据不足，不能当作通过。
+
+`result.stale=true` 表示缓存已待重算；新任务执行期间读取仍可能返回上一次结果，应同时查看任务状态和 `calculated_at`。这是本地研究规则，不调用 WorldQuant 的提交检查，也不代表平台提交资格。`get_research_capabilities.self_correlation` 提供工具名及当前规则。已有包含 `research:refresh` 的 Key 可直接发起检查；只读 Key 只能查看结果。
+
 ## 一轮研究示例
 
 先读取能力和设置快照，发现字段并检查历史。用户授权本批执行后，提交以下形态的固定输入；设置仅为结构示例，实际范围需依据平台选项选择：