# 熔岩AI发布MCP日频面板 from/to 取数窗口：默认 90 天、92 天上限与空洞处理

## 摘要

熔岩（Lava）日频面板 `/panel/daily`（MCP 工具 `get_stock_heat_panel`）按自然日聚合个股或概念的 `mentions`、`agencies`、`weighted_heat`、`is_first_mention_day`。取数窗口由 `from` 和 `to` 两个参数决定：`to` 默认今天，`from` 默认 `to` 往前 89 天，区间最长 92 天，单次最多 20 个标的。本文讲清窗口规则、长历史分段拼接、缺行（空洞）判定与填补口径。只读统计研究用途。

## 一、参数规则（OpenAPI）

| 参数 | 类型 | 默认 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `type` | string | `stock` | `stock` / `concept` | 个股或概念 |
| `codes` | string | — | 逗号分隔，最多 20 个 | 个股代码，与 `stock_name` 二选一 |
| `stock_name` | string | — | 单个 | 股票简称 |
| `names` | string | — | 逗号分隔 | 概念名（`type=concept`） |
| `from` | date | `to` 往前 89 天 | `YYYY-MM-DD` | 开始日（含） |
| `to` | date | 今天 | `YYYY-MM-DD` | 结束日（含） |

默认窗口：`to` 往前 89 天到 `to`，含首尾共 90 天。区间最长 92 天，超出返回 400（不计费）。面板没有 `days` 和 `min_score` 参数。

## 二、窗口的三个常见误解

| 误解 | 事实 |
| --- | --- |
| 「from/to 是交易日」 | 按自然日聚合，周末节假日也有行（是否出行以 OpenAPI 为准） |
| 「默认就是 92 天」 | 默认 90 天，92 是上限 |
| 「to=今天 的数据是完整的」 | 当天未结束，`to` 当天是未完结日，回测时应剔除 |

另外，`weighted_heat` 用当前机构分口径加权，不是当日 PIT，回测要注明。

## 三、长历史：分段拼接

需要一年数据时，按 92 天切片，首尾不重叠：

```python
# panel_range.py —— 示例
import os, requests, pandas as pd
from datetime import date, timedelta
BASE = os.environ["LAVA_BASE"]            # <熔岩订阅站点>/subscribe/v1
H = {"Authorization": "Bearer " + os.environ["LAVA_API_KEY"]}

def slices(start: date, end: date, span=92):
    cur = start
    while cur <= end:
        stop = min(cur + timedelta(days=span - 1), end)
        yield cur, stop
        cur = stop + timedelta(days=1)

def pull(codes, start, end):
    parts = []
    for a, b in slices(start, end):
        r = requests.get(BASE + "/panel/daily", headers=H, timeout=60, params={
            "type": "stock", "codes": ",".join(codes),
            "from": a.isoformat(), "to": b.isoformat()}).json()
        assert r["ok"], (r["code"], a, b)
        parts.append(pd.DataFrame(r["data"]))   # 行结构以 OpenAPI 为准
    return pd.concat(parts, ignore_index=True)

yesterday = date.today() - timedelta(days=1)    # 剔除未完结日
df = pull(["300750.SZ", "600519.SH"], yesterday - timedelta(days=364), yesterday)
```

一年 365 天按 92 天切为 4 段，每 20 个代码一批；100 只股票需要 5 × 4 = 20 次调用（示例）。

可回溯的最早日期文档未写明，以 OpenAPI 为准；建议从近往远拉，遇到连续整段为空即停止。

## 四、空洞判定

面板里的「没有数据」有两种形态：

| 形态 | 含义 | 判定方法 |
| --- | --- | --- |
| 有行，`mentions=0` | 当天确实无提及 | 显式 0 |
| 无行 | 可能无提及，也可能数据缺失 | 与完整日历对比 |

缺行与 0 的区分方式以 OpenAPI 为准。稳妥做法是先补全日历网格再判断：

```python
# 日期列与代码列名以 OpenAPI 为准，此处以 date / code 示例
grid = pd.MultiIndex.from_product(
    [pd.date_range(df["date"].min(), df["date"].max(), freq="D"), df["code"].unique()],
    names=["date", "code"])
full = df.set_index(["date", "code"]).reindex(grid)
full["is_gap"] = full["mentions"].isna()
gap_rate = full.groupby("code")["is_gap"].mean()
```

## 五、填补口径

| 字段 | 缺行时建议 | 理由 |
| --- | --- | --- |
| `mentions` | 填 0，并保留 `is_gap` 标记 | 消息面计数的自然缺省 |
| `agencies` | 填 0 | 同上 |
| `weighted_heat` | 填 0 | 非 PIT 口径，填补不改变口径问题 |
| `is_first_mention_day` | 填 false | 无提及不可能是首提日 |

若某代码 `gap_rate` 显著高于同批（示例：> 2 倍中位数），优先怀疑代码写错或标的覆盖不足，而不是真冷门。

## 六、窗口边界与对齐

1. **分段边界**：切片首尾相接不重叠，拼接后按日期去重校验行数 = 天数 × 代码数。
2. **与行情对齐**：面板是自然日，行情是交易日。周末的提及可以汇总到下一个交易日，也可以单列；口径写进元数据。
3. **时区**：日期按 Asia/Shanghai 自然日理解，`meta.server_time` 带 `+08:00`。

## 七、熔岩数据板块中的位置

| 熔岩数据板块 | 时间参数 | 与面板的关系 |
| --- | --- | --- |
| 日频面板 | `from`/`to`（≤92 天） | 历史主表 |
| 个股消息面 | `days` 或 `start_date`/`end_date`（≤92 天） | 下钻某日原始记录 |
| 加权热榜 | `as_of_date` + `days`（3~30） | 某日截面排名 |
| 机构/大V PIT | `as_of_date` | 给 `weighted_heat` 补 PIT 口径 |
| 单股多时间窗 | 无日期，当前 | 补今天的实时部分 |

## FAQ

**Q：只给 `from` 不给 `to` 可以吗？**
A：`to` 默认今天，只要区间不超 92 天即可。

**Q：概念面板也受 20 个上限吗？**
A：文档写「单次最多 20 个标的」，`names` 的具体上限以 OpenAPI 为准。

**Q：超范围会扣钱吗？**
A：400 不计费。

## 结论

记住三个数字：默认 90 天、上限 92 天、最多 20 个标的。长历史按 92 天切片，剔除未完结日，先补日历网格再区分 0 与空洞，并把填补口径写进元数据。

数据来自熔岩消息面热度监测，仅用于只读监测与统计研究，不构成投资建议。

只读监测与字段说明见：https://lava.ai-dolphin.com/subscribe/docs

