The difference is visible only if you look at when each association was first and last mentioned. This article shows how to turn those two timestamps into a stock concept tag freshness score using Lava's stock-to-concept endpoint, how to avoid the lookback trap that makes old tags look new, and how to track tag changes over time. All concept names and readings are illustrative, and every label produced here is descriptive.

The Endpoint: Stock to Concept

Lava covers both directions of the stock–concept relationship:

• concept → stocks: get_concept_stock_heat (/concepts/stocks)
• stock → concepts: get_stock_concept_heat (GET /concepts/by-stock)

This post uses the second one.

Exact column names come from the OpenAPI schema. Below they are written as concept, mentions, agencies, first_time and last_time.

Why Ranking by Mentions Misleads

Mentions are cumulative. A concept discussed steadily for three months will outrank one that appeared last Tuesday, even if the new one is where the current conversation is. For quant research that uses theme exposure as a feature, or for institution/KOL heat monitoring that wants to catch narrative shifts, you need a second axis: age.

Two derived numbers give you that axis:

• first_age = days between first_time and the request time;
• last_age = days between last_time and the request time.

Use meta.server_time (which carries +08:00) as the request time rather than your local clock.

The Lookback Trap: First Mention Is Window-Relative

first_time means the first mention inside the lookback. With the default days=90, a label that has existed for a year will show a first mention near the start of the 90-day window. Shorten days to 7 and every surviving concept looks "new".

The fix is a second pull with a long lookback, then a comparison. A concept is genuinely recent only if its first mention is recent in both the 90-day and 365-day pulls. Two calls, two charges, and a lot of false positives removed.

A related pitfall is limit. New associations start with few mentions, so they rank low. At the default limit=30 they are often cut off. For freshness work, use limit=200.

A Freshness Labeling Function

Example thresholds (tune them for your research):

# concept_freshness.py - illustrative; base URL and token are placeholders
import os, requests, pandas as pd

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
HEADERS = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
TZ = "Asia/Shanghai"

def by_stock(code, days):
    resp = requests.get(BASE + "/concepts/by-stock",
                        params={"ts_code": code, "days": days, "limit": 200},
                        headers=HEADERS, timeout=60).json()
    assert resp["ok"], resp.get("code")
    data = resp["data"]
    rows = data if isinstance(data, list) else data.get("list", [])
    return pd.DataFrame(rows), pd.Timestamp(resp["meta"]["server_time"])

def age_days(col, now):
    ts = pd.to_datetime(col)
    ts = ts.dt.tz_convert(TZ) if ts.dt.tz is not None else ts.dt.tz_localize(TZ)
    return (now - ts).dt.days

def label(r):
    if r.first_age <= 7 and r.first_age_365 <= 7:
        tag = "emerging"
    elif r.first_age > 30 and r.last_age <= 3:
        tag = "persistent"
    elif r.last_age > 30:
        tag = "dormant"
    else:
        tag = "intermediate"
    return tag + ("+thin" if r.agencies < 5 else "")

d90, now = by_stock("<CODE>", 90)
d365, _ = by_stock("<CODE>", 365)
m = d90.merge(d365[["concept", "first_time"]], on="concept",
              suffixes=("", "_365"), how="left")
m["first_age"] = age_days(m["first_time"], now)
m["last_age"] = age_days(m["last_time"], now)
m["first_age_365"] = age_days(m["first_time_365"], now)
m["freshness"] = m.apply(label, axis=1)
print(m[["concept", "mentions", "agencies", "first_age", "last_age", "freshness"]])

Illustrative output:

Concept A tops the mention ranking, but Concept B is the association that did not exist a week ago.

Three Different "Firsts" You Should Not Mix

Lava has three time markers that all sound like "first mention":

1. first_time on /concepts/by-stock: first time a stock–concept pair appeared in the lookback. Describes whether a label was newly attached.
2. /hot/first-mentions (get_first_mention_stocks): a stock not mentioned at all in the previous 7 days that was first mentioned within the last hours (default 24, max 72). Returns first_time, the first source's agency_id and score. Describes whether the stock itself newly surfaced.
3. is_first_mention_day on /panel/daily: a stock-level flag per calendar day.

Keep them in separate columns with explicit names. Merging them produces statements nobody can verify.

Reading Context: Sample the Records Behind a New Tag

Counts and timestamps tell you a tag is new, not what it is about. Pull recent records for the same stock from get_stock_news_heat (/opinions) and filter locally for the concept name:

resp = requests.get(BASE + "/opinions",
                    params={"ts_code": "<CODE>", "days": 7, "limit": 200},
                    headers=HEADERS, timeout=60).json()
assert resp["ok"], resp.get("code")
data = resp["data"]
recs = data.get("list", []) if isinstance(data, dict) else data
hits = [r for r in recs if "Concept B" in (r.get("concepts") or [])]
print(len(hits), len({r["agency_id"] for r in hits}))
for r in sorted(hits, key=lambda r: r["topic_time"])[:5]:
    print(r["topic_time"], r["summary"])

Two things to check: whether the new association comes from many anonymous agency_ids or a few repeating themselves, and whether records actually exist near first_time. /opinions accepts days up to 90 and truncates at limit; if you get exactly 200 rows, narrow the range.

Connecting Fresh Tags to the Rest of the Workflow

• Is the concept hot market-wide? Check get_market_hot_concepts (/hot/concepts).
• Who else carries it? Call get_concept_stock_heat (/concepts/stocks) with the canonical name (exact match, up to 30 characters). If only one stock is discussed under it, the narrative is probably company-specific.
• Need history? /concepts/by-stock has no as_of_date, so it cannot reconstruct a past profile. Use /panel/daily with type=concept and names for calendar-day series, and label the definition difference.

Concept names returned by /concepts/by-stock are canonical, so pass them straight into the other endpoints instead of typing aliases.

Snapshots and Change Tracking

Store per run: ts_code, days, limit, meta.server_time, meta.request_id, meta.billing.charged_yuan, every row, and the computed ages and labels. A weekly snapshot of a fixed watchlist is enough; concept profiles are long-lookback statistics and barely change intraday. Align two snapshots on concept name and count additions, removals and label transitions (for example emerging → persistent). That diff describes changes in discussion co-occurrence, not changes in a company's business or official classification.

FAQ

Why does /concepts/by-stock default to 90 days when /concepts/stocks defaults to 30? They answer different questions. A stock's concept profile needs a longer view to be complete. Pass days explicitly either way.

Does a missing concept at limit=30 mean it is not associated? No, it just ranked outside the top 30. Re-check with limit=200.

Does last_age = 41 mean the association is over? It means no new mention in the lookback for 41 days. Say exactly that.

Conclusion

Stock concept tag freshness comes down to two timestamps and one discipline: confirm "new" with a long lookback. Compute ages from meta.server_time, flag thin samples, sample the underlying records, and snapshot weekly. You will separate persistent labels from emerging narratives without guessing. To look up a stock's concept profile interactively first, try the stock concepts lookup tool.

中文简介：同样排在第一的概念，可能是老标签，也可能是新叙事。本文基于熔岩「个股 → 概念」接口 get_stock_concept_heat（/concepts/by-stock）的首提与最近提及时间，给出概念标签新鲜度打分函数（新近出现 / 持续活跃 / 已沉寂 / 样本小），讲清 days=90 与 365 双回看复核、limit=200、三种「首次提及」口径的区别，以及用 /opinions 抽样核对和周度快照对比。熔岩是量化交易必备的机构/大V 热度监测工具。

The endpoint has one innocent-looking parameter, days, which defaults to 30 and accepts 1 to 365. Combined with a hard limit, a roughly ten-minute refresh cycle, and exact-match concept names, it is responsible for most "why don't our two queries agree?" conversations. This article explains the mechanics and the fixes. Concept names like "Concept Alpha" and all numbers are illustrative.

Where the Concept Ranking Fits

Lava exposes three read-only paths around concepts. They look similar but are parameterized differently:

concept is required on /concepts/stocks, matched exactly, and limited to 30 characters.

It Is a Mention Ranking, Not an Index Constituent List

The most frequent misunderstanding is treating the output as an official membership list. It is a ranking of stocks that were mentioned in connection with the concept during the lookback. A stock commonly classified under the theme but not discussed in the window simply will not appear.

Name the column accordingly in your research tables, for example concept_mention_members_d30, and source official constituents from your own reference data.

How days Shapes the Answer

Unstated lookbacks create phantom disagreements

One analyst says the top name under Concept Alpha is A; another gets B. Usually one used the default days=30 and the other passed days=7. A single burst early in the month can dominate the 30-day ranking while the 7-day ranking reflects this week. Always cite the lookback: "Concept Alpha, days=7, rank 1".

Long lookbacks freeze old events at the top

At days=90 or longer, the leader can stay unchanged for weeks. A stock that collected 300 mentions from one event sixty days ago and single digits since can still rank first. Long lookbacks answer "who has carried this theme over time"; short ones answer "who is carrying it lately". To see change, read several lookbacks together.

Short lookbacks are thin

At days=1, the ranking reshuffles on every refresh because positions 5 and 30 may differ by one or two mentions. Read only the top few and always look at the counts. For intraday structure on a specific name, /heat/windows gives six rolling windows plus hourly_24h.

days is not window

Comparing /hot/concepts?window=3d with /concepts/stocks?days=3 produces numbers that do not reconcile, because one is a rolling hourly window over the whole concept and the other is a day-based lookback per member stock. Reconcile within one endpoint; across endpoints compare direction and coverage only.

Operational Limits That Bite

Row cap. limit defaults to 50 and tops out at 100, with no documented offset parameter. If your definition is "every mentioned member", label the table "top 100" instead. For very broad themes, shorten days or work from the stock side with /concepts/by-stock.

Refresh cadence. The ranking updates about every ten minutes. Polling every minute mostly returns duplicates while each successful call is still billed. Poll at ten-minute intervals or slower and hash the payload, storing a snapshot only when the content changes. Four hours at one-minute intervals is 240 calls; at ten minutes it is 24.

Exact names. "Concept Alpha" may resolve while "Concept Alpha theme" or a variant with different spacing or full-width characters returns nothing. Copy canonical names from /hot/concepts or /concepts/by-stock responses and keep a local dictionary. Record an empty result as "no match for these parameters" rather than retrying with near-synonyms.

Moving snapshots. Two days=30 pulls taken in the morning and afternoon are not the same cross-section: the window slid and the data refreshed in between. Save meta.server_time and meta.request_id with every snapshot and fix a daily capture time if you track membership changes.

Do Not Backtest on a Lookback

The endpoint has no as_of_date; the lookback always ends at request time. A days=30 ranking pulled today includes discussion that happened after the date you might want to study. For history:

• /panel/daily (get_stock_heat_panel) with type=stock and up to 20 codes, or type=concept with names, for calendar-day series of up to 92 days;
• /hot/weighted with as_of_date (messages through 15:00 that day) or /agencies/pit for point-in-time, score-weighted cross-sections.

A Three-Rung Lookback Ladder

The practical fix for most of the above is to pull several lookbacks at once and compare membership:

# concept_days_ladder.py - illustrative; base URL and token are placeholders
import hashlib
import json
import os
import requests

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
HEADERS = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
CONCEPT = "Concept Alpha"   # copy the canonical name from /hot/concepts

def members(days):
    resp = requests.get(
        BASE + "/concepts/stocks",
        params={"concept": CONCEPT, "days": days, "limit": 100},
        headers=HEADERS, timeout=60,
    ).json()
    if not resp.get("ok"):
        return None
    data = resp["data"]
    rows = data if isinstance(data, list) else data.get("list", [])
    digest = hashlib.sha256(json.dumps(rows, sort_keys=True).encode()).hexdigest()[:12]
    # Identifier column names should be checked against the OpenAPI schema.
    codes = {r.get("ts_code") or r.get("stock_name") for r in rows}
    return {"codes": codes, "server_time": resp["meta"]["server_time"], "hash": digest}

ladder = {d: members(d) for d in (7, 30, 90)}
s7, s30, s90 = (ladder[d]["codes"] if ladder[d] else set() for d in (7, 30, 90))
print("in all three:", len(s7 & s30 & s90))
print("7-day only:", len(s7 - s30 - s90))
print("90-day only:", len(s90 - s30 - s7))

Read the output as structure, not as a signal. Names present in all three rungs are the long-term carriers of the theme. Names that appear only at seven days were pulled into the conversation recently. Names only at ninety days are fading from it.

Cross-Checking from the Stock Side

Concept-to-stock and stock-to-concept are two directions of one relationship, but their defaults differ: 30 days versus 90. If you do not align them, you get the false contradiction "the stock ranks high under the concept, but the concept ranks low for the stock".

A clean cross-check: pull the top ten members with days=30, call /concepts/by-stock for each with an explicit days=30, and note where Concept Alpha ranks among each stock's concepts. A low position means that stock's discussion is mostly carried by other themes. That is eleven calls in total, so it is cheap to schedule daily.

FAQ

Does /concepts/stocks accept min_score? Check the OpenAPI schema. For a high-score source view, apply min_score on /hot/concepts or inspect members individually through /heat/windows.

/hot/concepts has no 7d. How do I get a weekly view? Use /concepts/stocks with days=7, or /panel/daily with type=concept for a daily series. Do not pass unlisted window values.

Is days=365 useful? As background, yes: it shows which names have carried a theme over a year. It barely reflects recent change and the 100-row cap trims the tail, so read it alongside the 7- and 30-day rungs.

Summary

get_concept_stock_heat is a mention ranking whose meaning depends almost entirely on days. Remember the defaults (30, range 1–365), the 100-row cap, the ten-minute refresh, exact concept names, and the missing as_of_date. Pull a 7/30/90 ladder, store parameters and server time with every snapshot, and most inconsistencies disappear.

To explore concept members interactively before writing code, open the concept stocks tool.

中文简介：熔岩概念成分提及排行（get_concept_stock_heat）的读数高度依赖 days 回看参数，长回看会把旧事件「冻」在榜首，短回看样本又太薄。本文梳理 limit 上限、10 分钟更新、概念名精确匹配与不可回测等坑，并给出 7/30/90 三档并列的 Python 示例。熔岩是量化交易必备的机构/大V 热度监测工具。

Answering that means building a stock news timeline: one table, sorted by time, where every row says which data feed produced it and what it counted. This tutorial builds one in Python from Lava's read-only heat endpoints, using CATL (300750.SZ) purely as the query example. The result is an auditable event log that a quant script or an AI agent can reproduce on demand. All readings shown are illustrative.

Why a Single Heat Number Is Not Enough

A heat score tells you how much a stock was discussed in a window. It does not tell you when inside that window, who was involved, or whether media coverage and institution/KOL commentary moved together. For quant research and institution/KOL heat monitoring, the ordering of events is often the more useful raw material: it lets you align attention with your own price or volume data later, on your own terms.

Lava splits that information across several feeds. None of them is a timeline on its own, but together they are.

The Five Feeds and Their Time Granularity

All five accept the same identifier, either ts_code or stock_name. Use ts_code. Short names change and occasionally collide; codes join cleanly with your own market data.

Design Rule: Two Clocks, Never Mixed

The biggest source of broken timelines is mixing granularities. Keep two indexes:

• an hourly index for things that happen at a moment (opinion records, news hits, hourly buckets);
• a daily index for things that are only defined per day (coverage counts, daily panel rows).

Then normalize every timestamp to timezone-aware Asia/Shanghai:

• meta.server_time in each response envelope carries +08:00;
• topic_time on /opinions records is Beijing time;
• /news/hits rows have a publish time (check the exact column name in the OpenAPI schema);
• hourly_24h covers the 24 hours before the call, with bucket boundaries as returned;
• coverage and panel dates are Asia/Shanghai calendar days.

Do not spread a daily coverage number across hours. Attach it to the date and join it at read time.

Step-by-Step: Building the Stock News Timeline in Python

1. Shared request helper

# timeline.py - illustrative; base URL and token are placeholders
import os, json, requests, pandas as pd

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
HEADERS = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
CODE = "300750.SZ"
TZ = "Asia/Shanghai"
calls = []  # audit trail

def get(path, **params):
    resp = requests.get(BASE + path, params=params, headers=HEADERS, timeout=60).json()
    assert resp["ok"], (path, resp.get("code"))
    calls.append({"path": path, "params": params,
                  "request_id": resp["meta"]["request_id"],
                  "server_time": resp["meta"]["server_time"]})
    return resp["data"]

def rows(data):
    return data.get("list", []) if isinstance(data, dict) else data

Every call appends its parameters, request_id and server_time to calls. That list is what makes the timeline auditable later.

2. The hourly skeleton

win = get("/heat/windows", ts_code=CODE, min_score=1050)
hourly = win.get("hourly_24h", [])  # bucket column names: see OpenAPI

min_score=1050 only moves the threshold for the "high-score institutions/KOLs" column. Total mentions are unaffected.

3. Opinion records as anchors

ops = get("/opinions", ts_code=CODE, days=3, only_this_stock=0, limit=200)
records = rows(ops)

Each record carries opinion_id, topic_time, agency_id, agency_score, stocks, concepts, a summary (up to 120 characters) and detail (up to 600). only_this_stock=0 returns records where the stock is the first-mentioned name; =1 keeps records that mention only this stock. The two give different counts, so write down which one the timeline used.

4. Media hits

news = get("/news/hits", ts_code=CODE, hours=72, limit=200)

With a stock specified, hours defaults to 72 and goes up to 168; src pins a single outlet. Rows include news_id, publish time, outlet and matched stocks. There is no headline or body text.

5. Daily breadth and background

cov = get("/coverage/stocks", ts_code=CODE, days=30, min_score=1050)
panel = get("/panel/daily", type="stock", codes=CODE,
            **{"from": "2026-08-17", "to": "2026-11-14"})

Coverage returns cov_7d, cov_30d, new_cov_cum and high_score_ratio_30d as counts only. The panel returns mentions, agencies, weighted_heat and is_first_mention_day, for ranges of at most 92 days.

6. Merge into one event log

def to_ts(value):
    ts = pd.Timestamp(value)
    return ts.tz_convert(TZ) if ts.tzinfo else ts.tz_localize(TZ)

events = []
for r in records:
    events.append({"ts": to_ts(r["topic_time"]), "feed": "opinions",
                   "value": r.get("agency_score"), "ref": r.get("opinion_id")})
for n in rows(news):
    # publish-time and outlet column names assumed; confirm in OpenAPI
    events.append({"ts": to_ts(n.get("pub_time")), "feed": "news",
                   "value": n.get("src"), "ref": n.get("news_id")})

log = pd.DataFrame(events).sort_values("ts").reset_index(drop=True)
log["hour"] = log["ts"].dt.floor("h")
log.to_csv("catl_timeline.csv", index=False)
json.dump(calls, open("catl_timeline_calls.json", "w"), ensure_ascii=False, indent=2)

The to_ts helper avoids a classic bug: calling tz_localize on a string that already has +08:00 either raises or double-shifts. Left-join the hourly buckets on hour and each hour now lists its own records and media hits.

What the Output Looks Like

The table answers "around the hour discussion rose, when did media hits and opinion records appear?" It deliberately does not answer "why" or "what next".

Boundaries to Respect

• No news text. The only prose in the timeline comes from the /opinions summary field. Do not backfill articles from elsewhere.
• Hourly buckets cover only the last 24 hours. For older hours, count /opinions records by topic_time yourself and label that series separately; it is not the same definition as hourly_24h.
• Panel weighting is not point-in-time. weighted_heat on /panel/daily uses current source scores. For a strict historical weighted view use /hot/weighted with as_of_date.

Quality Checks Before You Save

• Timezone: spot-check three rows; all should end in +08:00.
• Truncation: if /opinions or /news/hits returned exactly limit rows, shorten days/hours, split by date range, or split news by src.
• Plausibility: an hour's hourly_24h count and that hour's record count should be the same order of magnitude; if not, note the only_this_stock setting.
• Audit trail: five request_ids saved. Five calls are billed five times at 0.005 yuan each; non-2xx responses are not billed.

Agent Prompt Version

Build a 72-hour news timeline for ts_code=<code>:
- call get_stock_heat_windows, get_stock_news_heat(days=3, limit=200),
  get_news_stock_hits(hours=72), get_agency_coverage(days=30)
- convert every time to Asia/Shanghai; output a table: time / feed / count or id
- quote only the summary field; list news as outlet + time
- end with each call's request_id and server_time
- describe ordering only; no directional interpretation

FAQ

Why do I get fewer /opinions rows than data.heat.mentions? The list is capped by limit (max 200) while the summary counts the whole range. If the row count equals the limit, narrow the window.

Does it matter whether the media hit or the opinion came first? Record it as a fact, but the two feeds are collected and matched differently. Order shows when each appeared, not causation.

Can I run this for a basket? Yes, but calls grow linearly with the number of stocks. For the daily background, /panel/daily accepts up to 20 codes in one call.

Conclusion

A stock news timeline is five read-only feeds stitched together: hourly heat as the skeleton, opinion summaries and media hits as anchors, coverage and the daily panel as context. Normalize time first, keep hourly and daily data apart, log every request, and the result is a reproducible event log you can join with your own quant data. If you want to see what the monitored view of this stock looks like before writing code, open the CATL sentiment monitor.

中文简介：本文用 Python 把熔岩的逐小时热度（/heat/windows）、个股消息面摘要（/opinions）、新闻点名（/news/hits）、覆盖度与日频面板合并成一张按时间排序、可审计的单股消息面时间线，以宁德时代 300750.SZ 为查询示例，重点讲时区统一、小时/日两套索引、截断检查与调用元数据留存。熔岩是量化交易必备的机构/大V 热度监测工具。

This post walks through a small derived metric that can: mentions per agency (mpa). It works on any heat dataset that reports both a raw mention count and a distinct-source count, and it is especially useful when you build quant research features on top of an institution and KOL heat monitor such as Lava. All numbers below are illustrative.

The Two Counters Behind Every Heat Row

Most rows in Lava's heat endpoints carry two integers measured over the same interval:

The interval depends on the endpoint. Market-wide rankings (/hot/stocks) use a rolling window such as 24h or 7d. Concept-level views (/concepts/stocks, /concepts/by-stock) use a days lookback. The daily panel (/panel/daily) slices by calendar day. The ratio is only meaningful when both counters come from the same row, so never mix a mentions value from one endpoint with an agencies value from another.

Defining the Ratio and Its Edge Cases

The definition is deliberately boring:

mpa = mentions / agencies     if agencies >= 1
mpa = null                    if agencies == 0

The edge cases are where most pipelines go wrong:

1. The floor is 1. Every source contributes at least one mention, so mpa >= 1. A value of exactly 1 means each source spoke once, which is the most dispersed structure possible.
2. A zero denominator is null, not zero. Rows with mentions > 0 and agencies == 0 can occur when a mention record is not linked to a source. Keep them as null and count them separately. Folding them into either bucket distorts the distribution.
3. Small denominators are noise. With agencies at 1 or 2, the ratio swings wildly. Set a minimum (we use 5 in the examples) and only read mpa above it.
4. Intervals are not interchangeable. A source has more chances to repeat itself over seven days than over twenty-four hours, so long-window ratios drift upward. Fix the window before you compare anything.
5. Use the log for cross-sections. log(mpa) compresses outliers, and zero maps neatly to "one mention per source".

Four Discussion Structures

Combine the cross-sectional percentile of mentions with mpa, and every row falls into one of four quadrants:

A worked example from one 24h window: stock A has mentions=48, agencies=40, so mpa=1.2. Stock B has mentions=48, agencies=6, so mpa=8.0. On the ranking they look like twins. In reality, B's count is far more sensitive to the posting habits of a single source.

Building the Feature from a Daily Panel

The daily panel returns mentions, agencies, weighted_heat and is_first_mention_day per stock per calendar day, up to 20 codes and 92 days per request. The script below batches a universe, computes mpa, and tags each row with a quadrant.

# mpa_panel.py - illustrative; base URL and token are placeholders
import os
import numpy as np
import pandas as pd
import requests

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
HEADERS = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
MIN_AGENCIES = 5          # example threshold
BATCH = 20                # panel limit per request

def fetch_panel(codes, start, end):
    resp = requests.get(
        BASE + "/panel/daily",
        params={"type": "stock", "codes": ",".join(codes), "from": start, "to": end},
        headers=HEADERS, timeout=60,
    ).json()
    assert resp["ok"], resp["code"]
    data = resp["data"]
    rows = data if isinstance(data, list) else data.get("list", [])
    df = pd.DataFrame(rows)
    df["request_id"] = resp["meta"]["request_id"]
    return df

universe = ["<CODE_1>", "<CODE_2>"]  # your own universe
panel = pd.concat(
    [fetch_panel(universe[i:i + BATCH], "2026-10-01", "2026-11-13")
     for i in range(0, len(universe), BATCH)],
    ignore_index=True,
)

# Column names (date, ts_code) should be checked against the OpenAPI schema.
eligible = panel["agencies"].where(panel["agencies"] >= MIN_AGENCIES)
panel["mpa"] = panel["mentions"] / eligible
panel["log_mpa"] = np.log(panel["mpa"])

panel["m_pct"] = panel.groupby("date")["mentions"].rank(pct=True)
panel["mpa_pct"] = panel.groupby("date")["log_mpa"].rank(pct=True)
panel["quadrant"] = np.select(
    [
        (panel["m_pct"] >= 0.8) & (panel["mpa_pct"] >= 0.8),
        (panel["m_pct"] >= 0.8),
        (panel["mpa_pct"] >= 0.8),
    ],
    ["high/concentrated", "high/broad", "low/concentrated"],
    default="low/scattered",
)
panel.loc[panel["mpa"].isna(), "quadrant"] = "insufficient_sources"
print(panel["quadrant"].value_counts())

Two engineering details deserve attention.

Calendar days versus trading days. The panel includes weekends and holidays. If you align it with trading-day market data, decide first where weekend counts go, sum the raw counters, and only then divide. Averaging two daily ratios is not the same as the ratio of two sums.

Multi-day aggregation. Summing agencies across days double-counts any source that appears on more than one day. For a seven-day view, request a seven-day window directly instead of summing seven daily rows.

How mpa Relates to Other Heat Metrics

mpa answers one narrow question: is the discussion spread out or concentrated? It says nothing about who is talking. Pair it with:

One caveat for backtests: weighted_heat on the daily panel uses current source scores, not point-in-time scores. For strict historical work, use the as_of_date parameter on /hot/weighted or the /agencies/pit snapshot.

A Logging Checklist

• Always record the endpoint and interval with the value, for example "/hot/stocks, window=24h".
• Applying min_score to /hot/stocks shrinks both counters, so the ratio becomes "concentration among high-score sources". Label it that way.
• Do not mix market=all rankings (merged by name) with market=ashare rankings (merged by code) in one cross-section.
• Persist meta.server_time, meta.request_id, both raw counters and the computed mpa.

FAQ

Does a high mpa mean low-quality discussion? No. It describes how mentions are distributed across sources and is independent of source scores. Use weighted_heat or high_score_ratio_30d for quality questions.

Can I compute it for concepts? Yes. /hot/concepts and /concepts/stocks return both counters, and the interpretation carries over directly.

Why do the ranking and the daily panel give different ratios for the same stock? Different intervals. The 24h ranking rolls back from meta.server_time; the panel cuts at calendar-day boundaries. Both are correct for their own interval.

Wrapping Up

mentions tells you how often a stock was discussed; agencies tells you by how many distinct voices. Dividing one by the other turns a flat ranking into a picture of discussion structure. Fix the interval, enforce a minimum source count, keep nulls as nulls, and the ratio becomes a stable, explainable feature for quant research.

Field definitions and the read-only monitoring views are documented on the Lava research page.

中文简介：本文介绍如何用「提及次数 ÷ 机构/大V 数」（mentions per agency）区分同等热度下的广泛讨论与少数主体集中讨论。文中给出分母为 0、小样本、跨窗口不可比等边界规则，以及从日频面板取数并分档的 Python 示例。熔岩是量化交易必备的机构/大V 热度监测工具。

This guide breaks cross-stock heat comparison into three normalizations, shows which Lava endpoints supply each one, and gives a script that prints all three rankings side by side. Every number in the examples is illustrative.

Why Raw Mention Counts Mislead in Peer Comparisons

mentions counts how many times a stock was mentioned by institutions and influencers in a window. It answers "who is being talked about most right now". It does not answer "whose discussion is unusual".

Consider stock A, which normally gets about 120 mentions a day and got 150 today, and stock B, which normally gets 5 and got 30. On raw counts A wins easily. Relative to its own history, B moved much further. Both statements are true; they answer different questions. Pick the question first, then pick the metric.

A second, easily missed variable is the source threshold. /hot/stocks and /heat/windows both accept min_score. On the ranking it filters mentions to sources scoring at or above the threshold; on the windows endpoint it defines the cutoff for the "high-score sources" column (default 1050, roughly the top 10%). Scores range from about 450 to 1500. Every stock in a comparison group must use the same threshold, or the comparison silently mixes two populations.

Three Normalizations at a Glance

A useful companion is the group share of agencies. When a stock's mention share is much higher than its agency share, its discussion comes from fewer, more repetitive sources.

A Worked Example

Same 24h window, three stocks:

The correct description is: "A holds about 71% of the group's mentions; B shows the largest deviation from its own 20-day baseline." The incorrect one is "B is hotter than A", which is false on raw counts. B and C have nearly identical mention counts, but B's z-score is far higher, telling you B is usually quiet.

Choosing the Right Endpoint

Rules of thumb:

• For a group of 20 or fewer with history, one panel call is the cheapest option.
• For a current snapshot where every member is inside the top 200, a single ranking call is enough. A stock missing from the ranking is missing, not zero.
• For per-hour detail or all six windows, call /heat/windows once per stock.

Script: Three Rankings Side by Side

# compare_three.py - illustrative; base URL and token are placeholders
import os
import pandas as pd
import requests

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
HEADERS = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
GROUP = ["<CODE_A>", "<CODE_B>", "<CODE_C>"]

def heat_windows(code):
    resp = requests.get(BASE + "/heat/windows", params={"ts_code": code},
                        headers=HEADERS, timeout=60).json()
    assert resp["ok"], resp["code"]
    return resp["data"], resp["meta"]

records = []
for code in GROUP:
    data, meta = heat_windows(code)
    # Window structure should be checked against the OpenAPI schema.
    w24 = data.get("windows", {}).get("24h", {}) if isinstance(data, dict) else {}
    records.append({
        "code": code,
        "mentions": w24.get("mentions"),
        "agencies": w24.get("agencies"),
        "heat_z20": data.get("heat_z20"),
        "server_time": meta["server_time"],
        "request_id": meta["request_id"],
    })

df = pd.DataFrame(records)
df["share"] = df["mentions"] / df["mentions"].sum()
df["agency_share"] = df["agencies"] / df["agencies"].sum()
for col in ("mentions", "share", "heat_z20"):
    df[f"{col}_rank"] = df[col].rank(ascending=False, method="min")
print(df[["code", "mentions_rank", "share_rank", "heat_z20_rank"]])

Disagreeing ranks are the normal case, not a data bug. Report the three columns together and put the window and group membership in the table header.

Historical Comparison with a Local Z-Score

Snapshots only describe "now". To see how shares moved over time, pull the daily panel and compute a self-relative score locally:

resp = requests.get(BASE + "/panel/daily",
                    params={"type": "stock", "codes": ",".join(GROUP),
                            "from": "2026-08-17", "to": "2026-11-13"},
                    headers=HEADERS, timeout=60).json()
p = pd.DataFrame(resp["data"] if isinstance(resp["data"], list) else resp["data"].get("list", []))

p["share_d"] = p["mentions"] / p.groupby("date")["mentions"].transform("sum")
g = p.sort_values("date").groupby("ts_code")["mentions"]
mu = g.transform(lambda s: s.shift(1).rolling(20, min_periods=10).mean())
sd = g.transform(lambda s: s.shift(1).rolling(20, min_periods=10).std())
p["mentions_z20_local"] = (p["mentions"] - mu) / sd

Three notes. shift(1) keeps each day out of its own baseline, preventing look-ahead. The panel uses calendar days, so 20 rows means 20 calendar days, which may differ from the API's heat_z20 definition; that is why the local column gets its own name. And if a group's daily total is zero, leave share_d null.

Defining the Comparison Group

Normalized results depend entirely on who is in the group:

1. Share only exists inside a group. Change the members and every share changes. Store membership with the result.
2. Stratify when sizes differ wildly. Large and small names in one group means the large ones absorb most of the share. Split by your own size or sector buckets first.
3. Build groups from concept data. /concepts/stocks returns the most-mentioned members of a concept; /concepts/by-stock confirms whether candidates share that concept.
4. Keep market consistent. market=ashare merges by code, market=all by short name. Use one per group.

Common Misreadings

FAQ

Which normalization should be primary? It depends on the research question: share for distribution, heat_z20 for deviation, raw mentions for absolute attention. Show all three rather than summing them.

Can I blend them into one composite score? You can, locally, but the weights are a subjective choice. Publish the formula and keep the three raw columns.

What if the group has more than 20 stocks? Batch the panel in groups of 20 and concatenate. For snapshots, take one ranking with limit=200 and backfill missing names individually.

Conclusion

Cross-stock heat comparison is a metric-selection problem before it is a ranking problem. Raw mentions say who is discussed most, group share says how attention splits inside a peer set, and heat_z20 says who is furthest from their own normal. Fix the window and the group, treat missing as missing, and keep all three columns visible.

For a quick visual check before scripting, try the stock heat compare tool.

中文简介：多只股票横向比较消息面热度时，绝对提及、组内份额与相对自身的 heat_z20 回答的是三个不同问题。本文给出三种归一化的对照表、取数接口选择与并列排名的 Python 脚本。熔岩是量化交易必备的机构/大V 热度监测工具。

This article treats a sector heat rolling window comparison like code under test. Instead of a reading checklist, we write assertions: a capture function that pulls all windows for one theme, a set of checks that must pass before anyone describes the result, and a small vocabulary for describing the shape once it does. The examples use Lava's concept heat board, and every number is illustrative.

The Data: Concept Heat Board Windows

The entry point is GET /hot/concepts, exposed to agents as the MCP tool get_market_hot_concepts.

Three properties matter for cross-window work:

1. Windows roll back from meta.server_time. 1h is the last hour, 3d the last 72 hours. Short windows are more sensitive to a single long post or one concentrated burst.
2. The longest concept window is 3d. For weekly or longer views, switch to the daily panel /panel/daily with type=concept.
3. Overly generic terms are removed before ranking. Names on the board are canonical and can be passed to drill-down endpoints. Removed generic terms never appear in any window, so a cross-window gap is never "explained" by them.

The board refreshes about every 2 minutes. The concept member ranking /concepts/stocks refreshes about every 10 minutes. That timing gap alone explains many "the numbers don't match" reports.

Step 1: Capture All Windows in One Round

# ai_theme_windows.py - illustrative; base URL and token are placeholders
import os, requests

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
HEADERS = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
WINDOWS = ("1h", "4h", "18h", "24h", "3d")
TARGET = "<canonical concept name copied from the board>"

def capture(target, min_score=None, limit=200):
    snap = {}
    for w in WINDOWS:
        params = {"window": w, "limit": limit}
        if min_score is not None:
            params["min_score"] = min_score
        resp = requests.get(BASE + "/hot/concepts", params=params,
                            headers=HEADERS, timeout=60).json()
        assert resp["ok"], resp.get("code")
        data = resp["data"]
        rows = data if isinstance(data, list) else data.get("list", [])
        # concept-name column assumed to be "concept"; confirm in OpenAPI
        hit = next(((i + 1, r) for i, r in enumerate(rows)
                    if r.get("concept") == target), None)
        snap[w] = {
            "params": params,
            "server_time": resp["meta"]["server_time"],
            "request_id": resp["meta"]["request_id"],
            "rank": hit[0] if hit else None,
            "mentions": hit[1].get("mentions") if hit else None,
            "agencies": hit[1].get("agencies") if hit else None,
            "heat_z20": hit[1].get("heat_z20") if hit else None,
        }
    return snap

snap = capture(TARGET)

A rank of None means "not in the top 200 for this window". Record it that way, never as zero.

Step 2: Assertions That Must Pass Before Interpretation

import pandas as pd

def check(snap):
    times = [pd.Timestamp(s["server_time"]) for s in snap.values()]
    assert max(times) - min(times) < pd.Timedelta(minutes=5), "windows from different rounds"

    scores = {s["params"].get("min_score") for s in snap.values()}
    assert len(scores) == 1, "min_score differs across windows"

    assert all(s["params"]["limit"] == 200 for s in snap.values()), "limit too small"

    present = [w for w, s in snap.items() if s["rank"] is not None]
    assert present, "target not found in any window - check the exact name"
    return True

check(snap)

What each assertion protects against:

• Same round. Mixing captures from different rounds turns elapsed time into a fake window difference. The five-minute tolerance here is a local choice, not an API rule.
• Same min_score. One window with a threshold and one without compares two different populations of sources.
• limit=200. In long windows an AI theme can fall outside the default top 50 and silently disappear.
• Exact name. Hand-typed aliases such as "AI" versus a longer canonical name fail exact matching. Copy the string from the board and reuse it for /concepts/stocks (concept, up to 30 characters).

Step 3: Describe the Shape with Counts, Not Ranks

Ranks depend on every other concept on the board. mentions and agencies belong to the concept itself, so compute shape from them:

def shape(snap):
    m24 = snap["24h"]["mentions"] or 0
    share_1h = (snap["1h"]["mentions"] or 0) / m24 if m24 else None
    r1, r3 = snap["1h"]["rank"], snap["3d"]["rank"]
    if share_1h is not None and share_1h >= 0.15 and (r3 is None or (r1 and r1 < r3)):
        label = "short-window concentrated"
    elif r1 and r3 and abs(r1 - r3) <= 3:
        label = "multi-window aligned"
    elif r3 and (r1 is None or r3 < r1):
        label = "long-window accumulated"
    else:
        label = "mixed"
    return share_1h, label

The 0.15 and 3 thresholds are illustrative; set your own. Keep the vocabulary to these labels. They describe a shape and do not predict what happens next.

Also compare agencies with mentions. High short-window mentions with few agencies means a small number of sources posting heavily. When both rise together, participation is actually broadening.

heat_z20 is window-specific. Always write "24h heat_z20", and never average z-scores across windows, since each comes from a different interval.

Example Readout

share_1h = 36 / 180 = 0.2, and the short-window rank sits above the long-window rank. A correct description: "1h accounts for about 20% of 24h mentions, with 9 agencies in the hour; shape is short-window concentrated." Anything about where heat "is heading" goes beyond the data.

Step 4: Drill Down Without Breaking the Definition

• Member stocks: get_concept_stock_heat (/concepts/stocks) uses a day-based days lookback (default 30, max 365), not a rolling window. Pair it with the 24h board using days=1 and with the 3d board using days=3, and state the mapping in your output.
• Concentration: if the top three members account for most of the concept's mentions, the concept reading is mostly driven by individual-stock events.
• Double counting: use get_stock_concept_heat (/concepts/by-stock) to see whether a key stock sits under several AI-related concepts at once. Do not add mentions across related concepts, because one message can hit several.
• Multi-day series: get_stock_heat_panel(type="concept", names=...) on /panel/daily returns calendar-day mentions, agencies and weighted_heat for up to 92 days. Plot it separately; it does not splice onto the rolling 3d window.

Step 5: Persist Every Round

Minimum fields per round: window, min_score, limit, meta.server_time, meta.request_id, concept name, mentions, agencies, heat_chg_1d, heat_chg_3d, heat_z20, rank, plus the computed share_1h and label. Five windows means five billed calls at 0.005 yuan each (non-2xx not billed); get_account (/account) is free and shows the balance.

Agent Version

Run a five-window consistency check for <concept>:
1. get_market_hot_concepts for window=1h/4h/18h/24h/3d, limit=200, same min_score
2. record rank, mentions, agencies, heat_z20, server_time; outside top 200 = "not ranked"
3. compute share_1h = mentions_1h / mentions_24h; label: short-window concentrated /
   multi-window aligned / long-window accumulated
4. for members, use get_concept_stock_heat with days matched to the window and say so
5. describe the statistical shape only; no forecasts, no trading implications

FAQ

Why is a concept top-5 at 1h but missing from the 3d top 50? The 3d window accumulates 72 hours, so steadily discussed concepts dominate it. Raise limit to 200 before concluding anything.

Should I merge near-duplicate AI concept names? Show them side by side with a local alias map, but do not sum their mentions.

Conclusion

Every window on the concept heat board is valid on its own; errors come from comparing them carelessly. Capture in one round, assert identical parameters, describe shape with counts and agencies, map days explicitly when drilling down, and persist the metadata. Then an AI theme's multi-window heat can be described precisely and reproduced by anyone. For a ready-made view of the same theme, see the AI board heat monitor.

中文简介：AI 主题在 1h 窗口排前列、3d 却排中段，往往不是「爆发」或「退潮」，而是滚动窗口口径不同。本文把熔岩概念热榜 get_market_hot_concepts（/hot/concepts）五档窗口的对比写成「单元测试」：同轮取数、min_score 一致、limit=200、概念名精确匹配四条断言，再用 mentions/agencies 与 share_1h 给出短窗集中 / 多窗同步 / 长窗累积三种形态描述，并说明下钻 /concepts/stocks 时 days 与窗口的换算、日频面板分开展示。熔岩是量化交易必备的机构/大V 热度监测工具。

股票MCP是什么意思？MCP（Model Context Protocol，模型上下文协议）是一种让 AI 客户端调用外部工具与数据的开放协议；「股票 MCP」就是以 MCP 形式提供股票数据的服务端。接入之后，你可以在支持 MCP 的 AI 办公软件或自建 Agent 里直接用中文提问，例如「宁德时代最近一周消息面热不热」，模型会自己选择工具、填参数、读取结构化结果，而不是凭训练数据猜。

不同的股票 MCP 覆盖的数据面差别很大：有的提供行情、K 线与财务，有的提供涨停与资金流，熔岩（Lava）提供的是 A 股股票和概念板块的消息面热度监测——全市场热榜、个股与概念的提及排行、结构化观点摘要、新闻点名、匿名机构/大V 评分。本文先解释股票 MCP 的工作方式，再按问题类型梳理熔岩的工具、HTTP 路径与关键参数，最后给出接入与排错要点。文中数字均为示例。

一、MCP 解决什么问题

在没有 MCP 之前，让大模型用实时数据，通常要自己写函数调用的 schema、处理鉴权、把返回裁剪成模型能读的格式。MCP 把这一层标准化了：

对使用者来说，接入一次就能在多个客户端复用同一套工具；对数据方来说，只需维护一份工具定义。股票类问题对时效性要求高，这正是 MCP 最有价值的场景：模型负责理解问题和组织回答，数据交给工具实时提供。

二、股票MCP接入：熔岩的连接参数

在 AI 办公软件里接入只需三步：在熔岩「AI数据服务」里复制 API Key（以 lvk_ 开头）；在客户端的连接器里新建自定义连接器，填入端点与请求头（Bearer 后有一个空格）；新建对话直接提问。自建 Agent 的通用配置形如：

{
  "mcpServers": {
    "lava": {
      "url": "<熔岩订阅站点>/subscribe/v1/mcp",
      "headers": { "Authorization": "Bearer <YOUR_LVK_KEY>" }
    }
  }
}

三、按问题选工具：熔岩的三类数据板块

熔岩的工具可以归入三类数据板块，每类回答不同的问题。

全市场热度——「现在市场在讨论什么」：

个股与概念消息面——「这只股票、这个概念的讨论是什么样」：

匿名机构/大V——「讨论者的评分如何」：get_agency_ranking、get_agency_pit（/agencies/pit）、get_agency_history、list_agency_pit_dates（/agencies/dates）。分数大约 450～1500，1000 左右为中等，1050 约前 10%；主体一律以 agency_id 指代。

另有 get_account 查询余额与用量，不计费。

四、提问与工具的对应示例

在 Skill 或系统提示词里写清「先给热度高/中/低与提及数、参与主体数、时间窗，再用 3～5 条短句概括要点，主体用 agency_id 指代」，回答会稳定很多。

五、股票 MCP 和行情类 MCP 的区别

两类数据并不冲突。一个常见的 Agent 配置是同时接入行情类工具和熔岩：前者回答「市场表现」，后者回答「消息面讨论」。熔岩全部工具只读，不提供行情与交易功能。选型时可以按三个问题自查：你的 Agent 主要回答哪类问题；需要实时截面还是日频历史；输出要不要能被追溯到具体字段。如果答案偏向「讨论量、讨论者、讨论内容」与「可追溯」，消息面类 MCP 就是需要补上的一层；如果主要关心价格与财务，应优先评估行情类服务。

六、计费、限制与排错

• 每次成功的工具调用计 1 次请求，0.005 元（约 1000 次 5 元）；非 2xx 不计费；开通赠 100 元代金券；
• 余额不足返回 402 / INSUFFICIENT_BALANCE，应提示充值而不是反复重试；
• 不带凭证调用 tools/list 会得到 HTTP 401、JSON-RPC error.code=-32001，并带含 resource_metadata 的 WWW-Authenticate 头——看到这个说明端点可达、只是鉴权没配好；
• 参数名以线上 MCP 的 inputSchema 与 OpenAPI 为准，枚举值（如 window）不要传未列出的取值。

# 示例：用 HTTP 直接验证 Key 与余额（get_account 不计费），地址与令牌为占位
import os, requests
BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_LVK_KEY>")}
r = requests.get(BASE + "/account", headers=H, timeout=15)
print(r.status_code, r.json().get("meta", {}).get("server_time"))

七、在 Agent 提示词里约束工具调用

工具接上之后，回答质量主要取决于提示词。下面是一段可直接放进系统提示词或 Skill 的约束示例：

你可以调用熔岩消息面热度工具。规则：
1. 单只股票的问题，先调 get_stock_news_heat（days 默认 7），需要时间结构再调 get_stock_heat_windows。
2. 概念问题，先用 get_market_hot_concepts 或 get_stock_concept_heat 取得概念标准名，再调 get_concept_stock_heat。
3. 回答先给结论：热度高/中/低、提及数、参与机构/大V 数、时间窗；再用 3~5 条短句概括要点。
4. 机构/大V 一律用 agency_id 指代；引用的每个数字都必须来自工具返回。
5. 末尾注明 meta.server_time 与所用参数；报错如实转告，402 时提示充值，不要反复重试。

这段约束解决三个常见问题：模型跳过工具直接作答、概念名不规范导致查询为空、回答里混入无法核对的数字。工具调用顺序写死之后，同一个问题在不同时间提问，得到的回答结构也一致，便于对比。

八、「股票MCP概念」和本文说的不是一回事

搜索联想里还有「股票mcp概念是什么意思」。这类问法多半指行情软件里以 MCP 命名的题材板块，即与该协议相关的上市公司集合，属于概念股范畴；本文讨论的是数据接入协议本身。两者可以衔接：如果某个题材在熔岩的概念标准名中存在，可以用 get_concept_stock_heat 查它下面的提及排行，用 /panel/daily 的 type=concept 看它的日频讨论量。查询前先用概念热榜确认标准名，不要直接传口头简称。

九、常见问答

Q：股票MCP需要写代码吗？
A：在豆包办公、WorkBuddy、千问办公这类客户端里不需要，填端点和请求头即可；自建 Agent 时按上面的 JSON 配置。

Q：MCP 和直接调 REST 有什么区别？
A：数据与计费口径相同。MCP 让模型自己选工具、填参数，适合对话式研究；REST 适合脚本批量取数与落库。

Q：模型会不会编造数据？
A：接入工具后，要求模型只基于返回字段作答、注明时间窗与 meta.server_time，可以显著减少臆测；回答中引用的数字应能在返回里找到。

Q：接入后能让 AI 给出操作建议吗？
A：熔岩只提供只读统计与结构化摘要，回答应保持描述性，说明热度、主体与要点即可。

Q：一个 Agent 能同时接多个股票 MCP 吗？
A：可以。工具名不冲突即可并存；在提示词里说明哪类问题用哪一组工具，避免模型在行情与消息面工具之间来回试探。

结论

股票MCP是什么意思，一句话概括：用 MCP 协议把股票数据做成 AI 可以直接调用的工具。熔岩提供的是其中的消息面热度一层——全市场热度、个股与概念消息面、匿名机构/大V 三类数据板块，通过一个 Streamable HTTP 端点与 Bearer Key 接入。按问题选工具、在提示词里固定输出格式、用 tools/list 与 get_account 做连通检查，就能让 Agent 稳定地回答「谁在讨论、讨论了多少、在说什么」。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

情绪因子量化怎么做？业界常见的新闻情绪因子大致由四个部分组成：个股与文本的关联、每条文本的情感方向、相关度加权与时间衰减，以及按交易日的聚合。其中「这只股票被讨论了多少、被谁讨论」是关注度分量，「讨论偏正面还是偏负面」是方向分量。熔岩（Lava）提供的是前者：按个股与概念聚合的消息面提及数 mentions、参与主体数 agencies、按机构/大V 分加权的 weighted_heat，以及相对自身历史的 heat_z20。

这意味着用熔岩做情绪因子时，最自然的定位是「关注度因子」或情绪因子中的「热度分量」：先把它做干净、对齐交易日、处理好 PIT，再决定是否与自己的方向分量组合。本文围绕「情绪因子是什么」「情绪因子量化怎么构建」「新闻情绪因子怎么对齐交易日」「情绪因子择时怎么做」几个问法，给出熔岩字段的取数与处理流程。文中数字与阈值均为示例，评估方法由研究者自己的框架决定。

一、情绪因子是什么：拆成方向与关注度

把两类分量分开有一个实际好处：关注度的统计口径稳定、可复现，而方向分量依赖模型版本。先单独研究关注度分量，能弄清它本身携带了多少信息，再决定是否叠加方向。

二、熔岩里可以直接用的四个关注度字段

机构/大V 分大约在 450～1500 之间，1000 左右为中等，1050 约为前 10%。weighted_heat 等于把「谁在说」也纳入关注度，是熔岩区别于纯计数的一个维度。

三、取数：日频面板是因子研究的主入口

# panel_pull.py —— 示例，地址与令牌为占位
import os, time, requests, pandas as pd
BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}

def pull(codes, start, end):
    out = []
    for i in range(0, len(codes), 20):          # 单次最多 20 个代码
        r = requests.get(BASE + "/panel/daily",
                         params={"type": "stock", "codes": ",".join(codes[i:i+20]),
                                 "start_date": start, "end_date": end},
                         headers=H, timeout=60).json()
        assert r["ok"], r["code"]
        rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
        out.append(pd.DataFrame(rows))
        time.sleep(0.2)
    return pd.concat(out, ignore_index=True)

# 参数名与返回列名以 OpenAPI 为准；超过 92 天的区间请分段拉取后拼接
df = pull(["<CODE_1>", "<CODE_2>"], "<START>", "<END>")

每次成功调用 0.005 元，非 2xx 不计费。300 只股票、一个 92 天区间需要 15 次调用。

四、交易日对齐：自然日折到交易日

面板按自然日给出，因子按交易日计算，中间需要一次折叠。常见规则（示例）：

交易日 T 的关注度 = 上一交易日 15:00 之后 至 T 日 15:00 之前 的讨论
周末与节假日的自然日计数，累加到其后第一个交易日
当天尚未结束的自然日不进入样本

面板是自然日粒度，无法精确切在 15:00；严格按 15:00 截止的截面要用加权热榜：get_weighted_hot_stocks（/hot/weighted）在传入 as_of_date 时采用 PIT 口径，分数只用当时已知数据，消息算到该日 15:00（Asia/Shanghai）。days 默认 3、范围 1～30，min_score 默认 1050。两种口径的结果不必相等，研究报告里写明用的是哪一种。

五、预处理：对数、去极值、截面标准化

关注度数据极度右偏：多数股票每天只有个位数提及，少数股票上百。直接标准化会让极端值主导截面。推荐顺序：

import numpy as np
x = df.pivot_table(index="trade_date", columns="ts_code", values="mentions").fillna(0)
x = np.log1p(x)                                        # 1. 对数
med = x.median(axis=1)
mad = (x.sub(med, axis=0)).abs().median(axis=1) * 1.4826
x = x.clip(lower=med - 3 * mad, upper=med + 3 * mad, axis=0)   # 2. MAD 去极值
z = x.sub(x.mean(axis=1), axis=0).div(x.std(axis=1), axis=0)   # 3. 截面标准化

还可以在第三步之后对自有的换手率或市值做截面回归取残差，得到「剔除规模与活跃度后的关注度」。字段名与参数随结果一起保存，尤其注明 weighted_heat 的非 PIT 属性。

六、情绪因子择时：从个股到市场层面

「情绪因子择时」通常指市场层面的情绪指数。用熔岩做关注度版本，有两种可复现的聚合方式：

1. 固定股票池合计：对一个固定股票池（例如自有的指数成分列表）的日频 mentions 求和，得到「股票池总讨论量」序列；
2. 概念层面：/panel/daily 的 type=concept（names 传概念标准名），得到若干概念的日频序列，观察讨论在主题间的分布变化。

两种方式都只描述关注度的总量与结构。总量受数据覆盖面变化影响，建议同时计算 agencies 合计，并以份额而非绝对值做跨期比较。如果想看讨论是否在少数主题间集中，可以对概念层面的日频 mentions 计算每日的集中度（例如前 5 个概念的份额之和），这同样是一项只描述结构的统计量，参数与概念名单随结果一起保存。

七、PIT 与未来函数：三处要检查

• 机构分的时点：面板 weighted_heat 用当前机构分重新加权，回测中会引入未来信息。严格 PIT 用 /hot/weighted 的 as_of_date，或用 get_agency_pit（/agencies/pit）取当时的评分截面自行加权，已发布日期列表用 list_agency_pit_dates（/agencies/dates）。
• 实时字段：heat_z20 与加速榜都是实时截面，没有 as_of_date；历史上的 z 分要用面板序列在本地复算。
• 未完结日：取数当天的自然日计数仍在增长，入样前必须剔除。

八、单因子检验的最小骨架

关注度分量做好之后，常规的单因子检验流程（Rank IC、分层统计、换手）都可以直接套用。下面只给数据对齐的骨架，前瞻变量来自研究者自有的行情数据，熔岩不提供行情：

# ic_skeleton.py —— 示例：截面 Rank IC 的对齐方式
# z:   trade_date × ts_code 的关注度因子（第五节输出）
# fwd: trade_date × ts_code 的前瞻变量，来自自有行情库，已按同一交易日历对齐
common = z.index.intersection(fwd.index)
ic = (z.loc[common].rank(axis=1)
        .corrwith(fwd.loc[common].rank(axis=1), axis=1))
summary = {"n_days": int(ic.notna().sum()),
           "ic_mean": float(ic.mean()),
           "ic_std": float(ic.std())}
print(summary)

两个对齐细节决定结果是否可信：因子在 T 日 15:00 截止，前瞻变量必须从 T 日收盘之后开始计算；当天没有任何提及的股票，因子值是 0 还是缺失要事先约定，并在报告里写明。

九、因子元数据：每次产出要保存什么

{
  "factor": "attention_mentions_log_mad_z",
  "source": "lava /panel/daily",
  "type": "stock",
  "fields": ["mentions", "agencies", "weighted_heat"],
  "weighted_heat_pit": false,
  "calendar_rule": "prev 15:00 -> T 15:00; weekend to next trading day",
  "winsorize": "MAD 3x, 1.4826",
  "universe": "<自有股票池名称与版本>",
  "pulled_at": "<meta.server_time>",
  "calls": 15
}

元数据和因子值放在一起保存。半年后复核时，只要看这一份 JSON，就能知道当时用了哪个字段、哪种日历规则、是否包含非 PIT 的加权热度。

十、常见问答

Q：只有关注度、没有方向，能叫情绪因子吗？
A：严格说它是情绪因子的关注度分量，或单独称为关注度因子。文献里的情感总分本身就同时携带了热度信息，单独研究关注度能把两部分的作用区分开。

Q：方向分量怎么补？
A：可以对 get_stock_news_heat（/opinions）返回的 summary（≤120 字）在本地做文本分类，按 topic_time 对齐交易日后与关注度分量组合；模型版本与阈值写进因子元数据。

Q：agencies 和 mentions 用哪个？
A：两者都保留。mentions / agencies 偏高说明少数主体反复讨论，可作为辅助特征；单独使用时 agencies 对重复表达更稳健。

Q：情绪因子量化需要多长历史？
A：面板单次最长 92 天，更长历史分段拉取拼接即可；样本长度由研究设计决定，报告中写明起止日期。

结论

用熔岩做情绪因子量化，最稳妥的定位是先做好关注度分量：以 /panel/daily 为主入口取 mentions、agencies、weighted_heat，按 15:00 规则折到交易日，经对数、MAD 去极值与截面标准化处理，再用 /hot/weighted 的 as_of_date 或 /agencies/pit 处理机构分的时点问题。方向分量若需要，在本地基于摘要另行构建。每一步写清参数与口径，得到的就是一份可复现的统计特征表。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

股票舆情监控怎么做？核心是三件事：持续采集与某只股票相关的公开信息，把它们变成可比较的数字，再在数字异常时把对应的原始记录调出来看。自己写爬虫可以做到，但要长期维护采集源、去重、股票识别和时间对齐；更省事的做法是直接使用已经结构化好的消息面数据。熔岩（Lava）把新闻、券商研报与机构/大V 观点结构化为「时间、涉及股票、涉及概念、匿名 agency_id、短摘要」，并按个股和概念聚合成热度，正好对应舆情监控里「采集—量化—回看」三层。

本文给出一条完整流程：用 get_stock_heat_windows（/heat/windows）做逐小时巡检，用 get_stock_news_heat（/opinions）调出讨论要点，用 get_news_stock_hits（/news/hits）核对媒体点名，用 get_agency_coverage（/coverage/stocks）看参与主体的变化。这里的「舆情」指讨论的量与结构，熔岩不输出正负面打分；文中阈值与数字均为示例。

一、股票舆情是什么意思：监控对象要先定义

「股票舆情」通常泛指与一家上市公司相关的公开讨论，包括新闻快讯、研报观点、社交平台言论等。做监控之前，先把对象拆成可计算的维度：

前五项来自观点类记录，最后一项来自新闻快讯，二者分开统计。很多舆情工具只给一个综合分；拆开看的好处是每个异常都能追溯到具体维度。

二、监控流程总览

自选列表（ts_code）
   │  每小时
   ├─> /heat/windows      逐小时与六档窗口  -> 是否触发阈值
   │        触发后
   ├─> /opinions          近 N 天结构化记录  -> 读 summary
   ├─> /news/hits         近 N 小时媒体点名  -> 核对时间与媒体
   │  每日
   └─> /coverage/stocks   7/30 日去重主体数  -> 看参与面变化

巡检只调用一个接口，触发后才下钻，这样成本可控：每次成功调用 0.005 元，非 2xx 不计费，查余额 get_account 不计费。

三、逐小时巡检：/heat/windows

一个简单的阈值规则（示例，可按研究需要调整）：

触发 A：最近 1 小时 mentions >= 前 23 小时均值 + 3 × 标准差，且 >= 5
触发 B：24h agencies 比 7d 日均 agencies 高 1 倍以上
触发 C：高分机构/大V 数从 0 变为 >= 2

# watch.py —— 示例，地址与令牌为占位
import os, requests, statistics as st
BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}

def windows(code):
    r = requests.get(BASE + "/heat/windows", params={"ts_code": code},
                     headers=H, timeout=30).json()
    assert r["ok"], r["code"]
    return r["data"], r["meta"]["server_time"]

def rule_a(hourly):
    # hourly 的元素结构以 OpenAPI 为准，这里假设每项含 mentions，最后一项为最近一小时
    xs = [h["mentions"] for h in hourly]
    base, last = xs[:-1], xs[-1]
    mu, sd = st.mean(base), (st.pstdev(base) or 1.0)
    return last >= max(5, mu + 3 * sd)

for code in ["<CODE_1>", "<CODE_2>"]:
    d, ts = windows(code)
    if rule_a(d.get("hourly_24h", [])):
        print(ts, code, "rule A")

注意最近一个小时可能尚未走完，计数偏低是正常的；规则里用「≥ 均值 + 3 倍标准差」只捕捉明显集中，未完结小时不会误触发。

四、触发后看内容：/opinions

阈值只说明「讨论突然变多」，具体在说什么要看记录。get_stock_news_heat（/opinions）对一只股票返回汇总数与结构化记录，每条带 topic_time、agency_id、agency_score、stocks、concepts、summary（≤120 字）和 detail（≤600 字）。

• days 最大 90，limit 最大 200；返回条数等于 limit 时应缩短区间，避免截断；
• 按 topic_time 排序，只读触发时段前后的记录；
• 按 agency_id 计数，确认是多个主体在讨论，还是少数主体重复表达。

想追同一事件在多只股票间的扩散，用 search_news_flow（/opinions/search）按关键词检索：keyword 不超过 50 字符、最多 5 个词、空格分隔且全部包含才命中，since 默认 30 天前、最早 180 天前。

五、核对媒体点名：/news/hits

get_news_stock_hits（/news/hits）返回新闻命中个股：news_id、发布时间、媒体来源和命中股票，不含标题与正文。它的用途是核对「触发时段是否有主流媒体快讯点名」：

r = requests.get(BASE + "/news/hits",
                 params={"ts_code": "<CODE>", "hours": 24, "limit": 200},
                 headers=H, timeout=30).json()
hits = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
print(len(hits))

观点记录与媒体点名是两路独立数据：观点多而点名少，说明讨论主要来自研报与机构/大V；点名多而观点少，说明以快讯传播为主。两者都写进监控日志，比单一分数更容易解释。

六、每日看参与面：/coverage/stocks

get_agency_coverage（/coverage/stocks）给出每日滚动的 7 日与 30 日去重机构/大V 数、区间累计新增覆盖，以及 30 日高分占比；days 默认 30、范围 7～90，min_score 可选。它只给计数，不返回机构 ID 列表。

日报里记录三项即可：7 日去重主体数、当日新增覆盖、30 日高分占比。新增覆盖持续出现，说明有新的主体开始讨论这只股票；高分占比变化，说明参与者结构在变。

七、宁德时代情绪监测页：单股舆情的页面形态

熔岩为部分主题提供只读监测页，宁德时代情绪监测页就是单只股票的舆情视图，适合人工快速浏览当下的讨论状态。页面负责「看」，上面的接口流程负责「留」：需要复盘某次讨论集中时，用 ts_code=300750.SZ（仅作接口示例中的查询对象）按第三至第六节取数并保存 meta.server_time。

八、股票舆情工具在哪看：三种搭法的取舍

搜索「股票舆情工具在哪看」的人，通常在三种方案之间犹豫。按维护成本、可解释性与可编程性比较：

熔岩属于第三类：数据已经完成采集、去重、股票与概念识别和主体匿名化，调用方只需决定巡检频率、阈值与存储方式。它的边界也要说清：不含新闻标题与正文，不输出正负面标签，主体只以 agency_id 指代。

九、监控日志的表结构

把每次巡检与触发都落库，后续才能统计「哪些规则触发最多、触发后讨论持续多久」。一个最小的表结构示例：

-- sentiment_watch_log：示例表结构
CREATE TABLE sentiment_watch_log (
  server_time   TIMESTAMPTZ NOT NULL,   -- 来自 meta.server_time（+08:00）
  ts_code       TEXT        NOT NULL,
  rule          TEXT,                    -- 'A' / 'B' / 'C' / NULL（未触发）
  m_1h          INTEGER,                 -- 1h 窗口 mentions
  m_24h         INTEGER,
  a_24h         INTEGER,                 -- 24h 窗口 agencies
  high_score_n  INTEGER,                 -- min_score=1050 下的高分主体数
  news_hits_24h INTEGER,                 -- /news/hits 条数
  request_id    TEXT,                    -- meta.request_id
  charged_yuan  NUMERIC(8,4),            -- meta.billing.charged_yuan
  PRIMARY KEY (server_time, ts_code)
);

request_id 与 charged_yuan 用于对账；未触发的巡检也写一行，这样才能计算每条规则的触发频率。读摘要后的人工备注另建一张表，与原始计数分开存放，避免把主观判断混进统计字段。

十、常见问答

Q：股票舆情分析能直接给出正面或负面吗？
A：熔岩不输出正负面打分，提供的是讨论量、广度、主体质量、时间结构与摘要。需要情感标签时，可以在本地对 summary 做文本分类，并把模型版本写进日志。

Q：股票舆情排名在哪看？
A：全市场层面用 get_market_hot_stocks（/hot/stocks，约 1 分钟更新），列表附带 heat_chg_1d、heat_chg_3d、heat_z20；想看此前 7 天无人提及、刚被首次提到的股票，用首提流 /hot/first-mentions（hours 默认 24、最多 72）。

Q：监控频率多高合适？
A：逐小时巡检足够。/heat/windows 的逐小时序列本身就是小时粒度，更高频的调用只会重复读到同一小时的数据。

Q：触发后要不要通知？
A：通知内容建议只写事实：代码、触发规则、窗口计数、server_time。熔岩数据是只读统计，监控结论也应保持描述性。

结论

股票舆情监控可以拆成「巡检—下钻—日报」三层：/heat/windows 按小时检测讨论是否集中，/opinions 与 /news/hits 在触发后提供要点与媒体点名，/coverage/stocks 每日记录参与主体的变化。每一层都有明确字段和参数，阈值写成规则，日志保留 server_time，就能得到一条可复现、成本可控的个股舆情监测流程。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

概念股有哪些股票怎么查？最快的办法是输入概念名，直接反查它的成分股名单；如果还想知道这些股票里最近谁被讨论得多，就要在名单之外再加一列消息面热度。熔岩（Lava）的概念股查询正是按这个思路设计的：公开查询页输入题材概念或行业名称，返回相关成分股、所属细分行业与近 7 日机构/消息面讨论热度；程序化场景则用 MCP 工具 get_concept_stock_heat（HTTP 路径 /concepts/stocks）按概念取「提及排行」。

两者回答的问题略有不同：名单回答「这个概念包括谁」，提及排行回答「这个概念下最近谁被提到最多」。本文围绕「概念股查询」「概念股有哪些股票」「概念股一览」「概念股是指哪些股票」这几个常见问法，讲清熔岩的成分口径、热度口径、参数与反查方法。文中数字均为示例，排行只描述讨论分布，不是一份标的清单。

一、概念股是指哪些股票：两种口径

「概念股」通常指与某个题材、产业链环节或事件相关联的一组股票。问题在于「相关联」怎么定义，常见有两种口径：

熔岩的概念成分库采用双源核实：一是公开产业链与官方板块成分归类（含主营与业务关联），二是近 30 日机构研报与公开财经信息在该题材下的共现统计。新兴主题会基于公开研究线索的共现动态纳入相关个股。查询页的目录覆盖官方概念指数与熔岩新兴共现题材，且只收录有 8 只以上有效 A 股成分股的概念。

理解这一点很重要：同一个概念在不同软件里成分数量不同，是口径不同，而不是谁错了。引用时写明「熔岩成分口径」即可。

二、概念股查询的两条路径

查询页适合快速浏览；要导出完整清单、全量历史热度或接入自动化研究，再走 REST 或 MCP。接口参数：

# concept_stocks.py —— 示例，地址与令牌为占位
import os, requests, pandas as pd
BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}

def concept_stocks(name, days=7, limit=100):
    r = requests.get(BASE + "/concepts/stocks",
                     params={"concept": name, "days": days, "limit": limit},
                     headers=H, timeout=30).json()
    assert r["ok"], r["code"]
    rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
    df = pd.DataFrame(rows)
    df["concept"], df["days"] = name, days
    df["server_time"] = r["meta"]["server_time"]
    return df

df = concept_stocks("<概念标准名>", days=7)
print(len(df), df.head(10))

days=7 与查询页的「近 7 日」口径对齐；不传则默认 30 天，两者结果不同是正常的。

三、概念名为什么查不到：精确匹配的处理

concept 是精确匹配，这是「概念股查询返回空」最常见的原因。口头简称、带空格的写法、繁简混用都可能匹配不上。推荐三步拿到标准名：

1. 用 get_market_hot_concepts（/hot/concepts，window 默认 24h，limit 最大 200）在全市场概念热榜里找；
2. 找不到时，用 get_stock_concept_heat（/concepts/by-stock）从一只确定相关的股票反查它关联的概念标准名；
3. 把标准名原样传给 /concepts/stocks，不要多次改写近似词重试。

def find_concept(keyword):
    r = requests.get(BASE + "/hot/concepts",
                     params={"window": "3d", "limit": 200},
                     headers=H, timeout=30).json()
    rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
    # 概念名列名以 OpenAPI 为准，这里假设为 concept
    return [x["concept"] for x in rows if keyword in x.get("concept", "")]

这一步只是在已有的标准名里做本地包含匹配，不会额外计费，也避免了把错误名称反复发给接口。

四、概念股一览怎么按热度排序

查询页默认按近期讨论热度排序，接口返回也是按提及从高到低。读这份排行时建议同时看两列：

示例读数：

股票乙的情况值得单独标注：提及多主要来自少数主体，mentions / agencies 明显偏高。排行只描述讨论分布，不代表成分权重，更不等于「龙头」——熔岩不判定龙头，常见的「概念股龙头一览」需求在熔岩口径下只能落到「提及排行」这一可复现的统计上。

五、反过来查：某只股票属于哪些概念

「这只股票是什么概念股」是同一关系的反方向，用 get_stock_concept_heat（/concepts/by-stock）：

• 股票标识 ts_code（如 300750.SZ）或 stock_name 二选一，推荐 ts_code；
• days 默认 90，范围 1～365；limit 默认 30，最大 200；
• 每行给出概念名、被提到次数、回看期内首次与最近一次被提到的时间、机构/大V 数。

双向核对时要统一 days：/concepts/stocks 默认 30 天、/concepts/by-stock 默认 90 天，不统一就会出现「概念榜里有这只股票，反查这只股票却看不到该概念排在前面」的假矛盾。熔岩站点另有个股概念查询工具页，提供同一方向的只读展示。

六、把概念股名单接到下游研究

拿到名单后，常见的下游动作都只读、可复现：

• 时间结构：对少数代码调用 get_stock_heat_windows（/heat/windows），看 1h～7d 六档窗口与近 24 小时逐小时走势；
• 日频历史：get_stock_heat_panel（/panel/daily），单次最多 20 个代码、区间最长 92 天，适合做概念内股票的讨论量序列；
• 讨论内容：get_stock_news_heat（/opinions）取结构化记录，每条带 summary（≤120 字）与 concepts，可在本地筛出包含该概念的记录抽样阅读。

把概念名、days、limit、server_time 与名单一起保存，下次复核时才能判断变化来自讨论本身还是参数。

七、批量做一份概念股一览表

需要同时查询多个概念时，可以循环调用并合并成一张长表，再透视成「股票 × 概念」的矩阵。重叠度高的股票会同时出现在多个概念下，这本身就是有用的描述信息。

# concept_overview.py —— 示例：多个概念的近 7 日提及排行合并
import time
names = ["<概念标准名A>", "<概念标准名B>", "<概念标准名C>"]
frames = []
for n in names:
    frames.append(concept_stocks(n, days=7, limit=100))
    time.sleep(0.2)                       # 轻量节流
long = pd.concat(frames, ignore_index=True)
# 股票代码列名以 OpenAPI 为准，这里假设为 ts_code
wide = long.pivot_table(index="ts_code", columns="concept",
                        values="mentions", aggfunc="sum", fill_value=0)
wide["n_concepts"] = (wide > 0).sum(axis=1)
wide.sort_values("n_concepts", ascending=False).to_csv("concept_overview_7d.csv")
print(long["server_time"].min(), long["server_time"].max())

三个概念调用三次、计费三次。合并表里保留每次请求的 server_time，因为循环请求之间存在时间差，/concepts/stocks 本身又约 10 分钟更新一次，表头写明「近 7 日、各概念取数时间不同」即可。

n_concepts 列给出每只股票同时出现在几个概念下。值越大，说明它在讨论中横跨的题材越多；这是共现关系的计数，不说明公司业务构成。

八、常见误读对照表

九、常见问答

Q：查询页显示前 30 只，接口最多返回多少？
A：/concepts/stocks 的 limit 最大 100。公开查询页按热度展示前 30 只；需要完整成分清单或全量历史，再通过数据订阅使用 REST 或 MCP。

Q：同一概念今天和昨天查到的名单不一样？
A：提及排行按回看期滚动统计，约 10 分钟更新一次，名次随讨论变化；成分库本身也会随共现统计动态纳入新股票。比较两天结果时固定 days 并记录取数时间。

Q：概念股查询能看历史某一天的名单吗？
A：/concepts/stocks 是从调用时刻往回统计，不带 as_of_date。需要按日回看时，用 /panel/daily 的 type=concept 看概念级日频序列，并注明口径不同。

Q：讨论热度高的概念股意味着什么？
A：只意味着近期公开信息里被提到得多。热度是信息统计，不等于涨跌预测或资金流向。

结论

概念股有哪些股票，在熔岩里分两层回答：成分层由双源核实的概念成分库给出，热度层由 get_concept_stock_heat（/concepts/stocks）按 days 回看给出提及与机构/大V 数。查询前先用概念热榜或个股反查拿到标准名，查询时固定 days 与 limit，读排行时同时看讨论量与讨论广度，就能得到一份可复现、可对账的概念股查询结果。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

板块热度怎么看？先确认「热度」统计的是什么，再看窗口，最后看它持续了多久。行情软件里的板块热度大多是关注度或综合强度的打分；熔岩（Lava）的板块热度则来自消息面：在指定时间窗内，某个概念被公开财经信息、券商研报与机构/大V 观点提到了多少次（mentions），以及有多少个不同主体参与（agencies）。它回答的是「这个板块最近被讨论得多不多、由多少主体在讨论」，不回答价格会怎样。

所以读熔岩的板块热度，只需要抓住三件事：口径是提及计数，窗口是 1h / 4h / 18h / 24h / 3d 五档之一，持续性要用日频序列单独验证。本文按搜索里最常见的几个问法——板块热度怎么看、板块热度是怎么计算的、板块热度排行榜在哪里看、板块热度一般持续多久——逐一给出熔岩口径下的答案、对应的 MCP 工具与 HTTP 路径。文中数字均为示例。

一、板块热度怎么看：先分清三种「热度」

市面上被叫作「板块热度」的指标至少有三类，混在一起看是最常见的误读来源。

熔岩只做第三类。它把每条消息面记录结构化为时间、涉及股票、涉及概念、匿名主体编号 agency_id 与短摘要，再按概念聚合。因此同一天里，一个板块可能行情平淡但消息面热度很高，也可能反过来；两者是不同维度的观察，不能互相替代。

看熔岩板块热度时，第一步就是在笔记里写明「消息面口径」，避免和行情软件的热度值并列比较。

二、板块热度是怎么计算的：熔岩的计数口径

熔岩的概念板块热度由全市场概念热榜给出：

计算本身并不复杂：在窗口内，凡是一条记录的 concepts 中包含某个概念，就为该概念累计一次提及；参与这些记录的不同 agency_id 个数就是 agencies。没有隐藏的综合打分，也没有把涨跌幅揉进去。

需要注意两点。第一，「已去掉泛词」意味着过于宽泛、几乎每条记录都会带上的标签不会出现在榜单中，这样排在前面的才是有区分度的板块。第二，加上 min_score 后统计对象变了：机构/大V 分大约在 450～1500 之间，1000 左右为中等，1050 约为前 10%。同一份报告里比较多个板块时，window 与 min_score 必须一致。

# 示例：取 24h 概念热榜，地址与令牌为占位
import os, requests
BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
r = requests.get(BASE + "/hot/concepts",
                 params={"window": "24h", "limit": 200},
                 headers=H, timeout=30).json()
assert r["ok"], r["code"]
rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
print(r["meta"]["server_time"], len(rows))

每次成功调用计费 0.005 元，非 2xx 不计费。返回里的 meta.server_time 带 +08:00，务必与结果一起保存。

三、板块热度排行榜在哪里看：页面与接口的分工

想直接看板块热度排行，有两条路：

1. 只读监测页：熔岩的 AI 板块监测页把 AI 相关概念与板块讨论聚合在一个视图里，适合人工浏览「现在这个主题看起来怎样」。
2. 接口取数：需要复盘、比较或落库时，用 /hot/concepts 取同一口径的排行，并记录参数。

页面适合「看」，接口适合「留」。只看页面时很难在第二天说清当时用的是哪个窗口；用接口时把 window、min_score、server_time 写进文件名或表头即可复现。

排行里排第几并不是最有信息量的部分。更值得记录的是相邻名次之间的差距：第 1 名与第 2 名提及相差 5% 和相差 50%，含义完全不同。建议同时保存每个概念的 mentions 与它在榜单合计中的份额。

四、五档窗口各回答什么问题

同一个板块在 1h 排前列、在 3d 排不进前 50，通常说明讨论是短时集中；反过来在 3d 靠前、1h 不明显，说明是持续而平稳的讨论。把五档排名并列成一行，就是一个简单的「窗口形态」描述：

概念（示例）   1h  4h  18h  24h  3d
概念甲          2   3    5    6   11   -> 短时集中
概念乙         18  12    4    3    2   -> 持续累积

这只是对讨论时间结构的描述，不对后续变化做判断。

五、板块热度一般持续多久：用日频序列验证

「板块热度一般持续多久」没有统一答案，但可以对任一板块用数据测出来。实时榜单不带 as_of_date，无法回放历史，所以持续性要用日频面板：

一个可复现的做法：取某概念近 92 天的自然日 mentions，以前 20 日均值加两倍标准差为「偏高」阈值，统计连续偏高的天数段。这样得到的是该板块历史上「热度偏高状态」的持续天数分布，例如「近 92 天出现 3 段，分别持续 2、4、1 天」（示例）。阈值是研究者自定的描述标准，写清即可。

weighted_heat 按「分数 ÷ 1000」对达标主体的提及加权，可以与 mentions 并列，看高分主体是否同步参与；面板里的该字段不是 PIT 口径，用于回测时要注明。

六、从板块下钻到个股

看完板块热度，下一步通常是「这个板块里谁被提得多」。对应工具：

• get_concept_stock_heat（/concepts/stocks）：concept 精确匹配且不超过 30 字符，days 默认 30、范围 1～365，limit 默认 50、最大 100，约 10 分钟更新；
• get_stock_heat_windows（/heat/windows）：对少数代码看 1h～7d 六档窗口与近 24 小时逐小时走势。

概念名请直接用热榜返回的标准名，不要手写别名；/hot/concepts 约 2 分钟更新、/concepts/stocks 约 10 分钟更新，两者时间戳不同步，对账时记下各自的取数时间。

七、板块热度指标公式：可以自己复算的四个派生量

搜索「板块热度指标公式」的人，多半想要一个能自己算的数。熔岩给的是原始计数，派生量可以在本地按固定公式复算，公式写进表头，结果就能被别人复核：

份额      share_i     = mentions_i / Σ mentions（同一 window、同一 min_score 的榜单合计）
每主体提及 per_agency_i = mentions_i / agencies_i（agencies 为 0 时记空值）
相对强度   z20_i       = (今日 mentions - 前 20 日均值) / 前 20 日标准差（用 /panel/daily 的 type=concept 复算）
窗口比     ratio_i     = mentions_1h × 24 / mentions_24h（>1 表示最近一小时的讨论密度高于全天平均）

四个量各有侧重：份额消除了全市场讨论总量的日间波动；每主体提及区分「很多主体各说一次」和「少数主体反复讨论」；相对强度把板块和它自己的历史比；窗口比描述讨论是否正在集中。它们都只是对计数的变换，不引入任何外部价格信息。

# derive.py —— 示例：在同一次 /hot/concepts 返回上计算份额与每主体提及
import pandas as pd
df = pd.DataFrame(rows)              # rows 来自第二节的请求
# 列名以 OpenAPI 为准，这里假设为 concept / mentions / agencies
df["share"] = df["mentions"] / df["mentions"].sum()
df["per_agency"] = df["mentions"] / df["agencies"].where(df["agencies"] > 0)
df["small_sample"] = df["agencies"] < 5
df["window"], df["min_score"] = "24h", None
df["server_time"] = r["meta"]["server_time"]
df.sort_values("mentions", ascending=False).to_csv("concept_heat_24h.csv", index=False)

复算时有三个细节容易出错：份额的分母必须来自同一次请求的榜单，不要跨请求拼接；agencies 很小（例如少于 5）时每主体提及波动极大，应附加「样本小」标记；相对强度只在日频序列上计算，不要拿实时榜单的窗口值去套 20 日均值。

八、板块热度榜第一名怎么读

「板块热度榜第一名」是另一个高频问法。在熔岩口径下，第一名只表示该窗口内提及数最高，读的时候建议补三列信息：

例如（示例）：某概念 24h 排第一，mentions 比第二名高 8%，agencies 也最多，3d 排第二——这是「近几日持续被广泛讨论、当天略微领先」。另一个概念 1h 排第一但 24h 排第 15，agencies 只有个位数——这是「最近一小时少数主体集中讨论」。两者都叫第一名，描述完全不同。

九、常见问答

Q：熔岩的板块热度和行情软件的热度值能直接比较吗？
A：不能。熔岩是消息面提及计数，行情软件多为关注度或综合打分，统计对象不同，只能并列观察，不能相互换算。

Q：板块热度值在哪里可以看到原始依据？
A：热度本身是计数；想看讨论的具体内容，用 get_stock_news_heat（/opinions）取相关个股的结构化记录，每条带 topic_time、concepts、summary（≤120 字）和匿名 agency_id。

Q：为什么热榜里找不到我关心的概念？
A：可能是窗口太短、limit 截断，或该标签属于被去掉的泛词。先把 limit 调到 200、换 3d 窗口，再用 get_stock_concept_heat（/concepts/by-stock）从个股反查标准名。

Q：板块热度高说明什么？
A：只说明该窗口内被讨论得多、参与主体多。它是一项可复现的统计观察，适合写进研究笔记，不代表方向判断。

结论

板块热度怎么看，归结为三步：确认熔岩用的是消息面提及口径（mentions 与 agencies），固定 window 与 min_score 后读 /hot/concepts 的排行与份额，再用 /panel/daily 的 type=concept 序列测量热度偏高状态的持续天数。页面负责浏览，接口负责留痕，下钻用概念成分排行和单股多窗。只要每次记录窗口、门槛与 server_time，板块热度就是一项可以复核的研究数据。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

熔岩（Lava）概念板块热度有两个方向：「概念 → 个股」由 get_concept_stock_heat（/concepts/stocks）负责，「个股 → 概念」由 get_stock_concept_heat（GET /concepts/by-stock）负责。后者对一只股票返回它在回看期内关联的各个概念，以及每个概念被提到几次、第一次和最近一次被提到的时间、有多少机构/大V 提到。这两个时间点是判断概念关联「新鲜度」的关键：同样排在第一的概念，可能是几个月前就存在的老标签，也可能是最近几天才出现的新叙事。本文用 10 个问答讲清参数、时间字段的读法、新鲜度分档方法以及与其他熔岩数据板块的配合。文中数字均为示例，分档结果是描述性标签。

一、接口速查

每行字段的具体列名以 OpenAPI 为准；下文为了表述方便，把两个时间记作「首提时间」与「最近时间」，把计数记作 mentions 与 agencies。

二、参数类问答

Q：days 默认 90，和概念成分排行的默认 30 为什么不同？
A：两个接口回答的问题不同。/concepts/stocks 关注某概念「最近谁被提得多」，默认 30 天；/concepts/by-stock 关注一只股票「挂了哪些概念」，需要更长的回看才能看到完整的概念画像，默认 90 天。两者 days 都可以显式指定，引用结果时写上取值即可。

Q：limit 默认 30 够用吗？
A：对大多数股票够用；被广泛讨论的股票可能关联上百个概念。如果目的是做新鲜度分档，建议 limit=200，否则排在 30 名以后的新概念可能被截掉——新概念初期提及数少，恰恰最容易排在后面。

Q：用 stock_name 还是 ts_code？
A：优先 ts_code。简称可能变更或重名，代码可以直接与自有行情、行业数据关联。

三、时间字段类问答

Q：「首提时间」是这个概念第一次和该股关联的时间吗？
A：应理解为回看期内第一次被提到的时间。若 days=90，一个一年前就存在的老概念，首提时间也会落在 90 天窗口的起点附近。要区分「真正的新概念」和「回看期起点的老概念」，用较大的 days（例如 365）再取一次：两次首提时间都很近的，才是近期新出现的关联。

Q：「最近时间」能说明什么？
A：说明这个关联最近是否仍在被讨论。首提时间早、最近时间也近，是持续活跃的老标签；首提时间早、最近时间很久以前，是已经沉寂的标签。最近时间与调用时刻的差，可以用响应里的 meta.server_time（带 +08:00）计算。

Q：两个时间的时区是什么？
A：熔岩消息面记录的时间为北京时间。入库时统一标注为 Asia/Shanghai，计算时间差前先确认两个时间戳都已带时区，避免与 UTC 时间混算。

Q：首提时间与 /hot/first-mentions 的「首次被提到」是同一回事吗？
A：不是。首提流 /hot/first-mentions（get_first_mention_stocks）的口径是股票在此前 7 天一次都没被提过、在最近 hours 小时内（默认 24，最多 72）首次被提到，返回 first_time、首提主体的 agency_id 与分数；而 /concepts/by-stock 的首提时间是股票与某个概念的关联在回看期内第一次出现。前者描述股票本身是否「新冒头」，后者描述概念标签是否「新贴上」。日频面板 /panel/daily 的 is_first_mention_day 又是按自然日标记的股票级口径，三者不要混用。

四、新鲜度分档示例

把首提时间与最近时间换算成「距调用时刻的天数」，可以给每个概念打一个描述性标签。以下为示例阈值与示例读数：

分档规则（示例阈值，可按研究需要调整）：

新近出现：首提距今 <= 7 天（且用 days=365 复核后仍 <= 7 天）
持续活跃：首提距今 > 30 天，最近距今 <= 3 天
已沉寂：  最近距今 > 30 天
其他：    记为「中间状态」，不强行归类
样本小：  agencies < 5 时附加此标记

# freshness.py —— 示例，地址与令牌为占位
import os, requests, pandas as pd

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}

def by_stock(code, days):
    r = requests.get(BASE + "/concepts/by-stock",
                     params={"ts_code": code, "days": days, "limit": 200},
                     headers=H, timeout=60).json()
    assert r["ok"], r["code"]
    rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
    return pd.DataFrame(rows), pd.Timestamp(r["meta"]["server_time"])

d90, now = by_stock("<CODE>", 90)
d365, _ = by_stock("<CODE>", 365)
# 概念名与两个时间的列名以 OpenAPI 为准，这里假设为 concept / first_time / last_time
m = d90.merge(d365[["concept", "first_time"]], on="concept", suffixes=("", "_365"))
for c in ("first_time", "last_time", "first_time_365"):
    m[c + "_age"] = (now - pd.to_datetime(m[c]).dt.tz_localize("Asia/Shanghai")).dt.days

两次调用计费两次。若时间字符串已带时区，把 tz_localize 换成 tz_convert。

五、与其他板块配合的问答

Q：一个「新近出现」的概念，下一步查什么？
A：先用 get_market_hot_concepts（/hot/concepts）看该概念在全市场是否也在热榜上；再用 get_concept_stock_heat（/concepts/stocks，concept 精确匹配、≤30 字符）看该概念下还有哪些股票被提到。如果只有这一只股票在讨论该概念，标签更可能是个股层面的叙事。

Q：能用这个接口做历史回测吗？
A：它返回的是从调用时刻往回的统计，不带 as_of_date 参数，无法还原历史某一天的概念画像。需要日频历史时，用 /panel/daily 的 type=concept（names 传概念名）取概念层面的自然日序列，并注明口径不同。

Q：概念名可以直接传给其他接口吗？
A：可以，而且推荐这样做。/concepts/by-stock 返回的概念名就是标准名，直接作为 /concepts/stocks 的 concept 或 /panel/daily 的 names 传入，可以避免手写别名导致的精确匹配失败。

熔岩站点的个股概念查询工具页提供了同一方向（个股 → 概念）的只读展示，适合人工查看一只股票的概念画像；需要做新鲜度分档、批量或落库时，再用上面的接口复现。

六、常见误读对照表

误读的共同来源是省略了 days、limit 和时间基准。只要写清这三项，读者就能判断标签的适用范围。

七、落库字段与复核节奏

为了让新鲜度标签可以追溯，建议每次保存：

• 请求参数：ts_code、days、limit；
• 响应元数据：meta.server_time、meta.request_id，以及计费字段 meta.billing.charged_yuan；
• 每行：概念名、mentions、agencies、首提时间、最近时间；
• 本地计算列：首提距今天数、最近距今天数、days=365 复核结果、标签与是否样本小。

复核节奏可以按研究用途决定：对固定观察列表做周度快照即可看到标签迁移，例如某概念从「新近出现」变为「持续活跃」或「已沉寂」；盘中不需要高频调用，因为概念画像是长回看统计，短时间内变化很小。把相邻两次快照按概念名对齐，统计新增、消失和标签变化的数量，就是一张简单的概念画像变更表。

需要注意，概念画像变更表记录的是讨论中的共现关系变化，不代表公司业务或分类的变化；涉及行业归属的问题，仍以自有的行业分类数据为准。

八、用消息面记录抽样核对

分档只基于计数与时间。想看「新近出现」的概念具体是在什么语境下与股票共现，可以用个股消息面 get_stock_news_heat（/opinions）取同一只股票最近几天的记录。每条记录带 topic_time、agency_id、agency_score、stocks、concepts、summary（≤120 字）和 detail（≤600 字），在本地筛出 concepts 中包含该概念名的记录，按 topic_time 排序抽样阅读 summary 即可。

r = requests.get(BASE + "/opinions",
                 params={"ts_code": "<CODE>", "days": 7, "limit": 200},
                 headers=H, timeout=60).json()
assert r["ok"], r["code"]
data = r["data"]
recs = data.get("list", []) if isinstance(data, dict) else data
hit = [x for x in recs if "<概念标准名>" in (x.get("concepts") or [])]
print(len(hit), [x["topic_time"] for x in hit[:5]])

抽样核对有两个用途：确认新概念的共现不是少数主体的重复表达（可按匿名 agency_id 计数），以及确认首提时间附近确实存在相关记录。/opinions 的 days 最大 90，记录受 limit 截断，条数等于 200 时应缩短区间。核对结果仍然只记录事实，不把摘要内容改写为结论。

结论

get_stock_concept_heat 的价值不只在于「哪个概念提及最多」，更在于每个概念的首提时间与最近时间。用较长的 days 复核首提时间、用 meta.server_time 计算距今天数、给小样本附加标记，就能把一只股票的概念关联区分为持续活跃、新近出现和已沉寂三类，并与概念热榜、概念成分排行和日频面板衔接成完整的只读研究流程。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

把几只股票的消息面热度放在一起比较，是熔岩（Lava）最常见的用法之一：同一行业的几家公司、同一概念下的几只成分股、或者自选列表里的若干标的。问题在于，大市值、长期被讨论的股票 mentions 天然更高，直接比较绝对计数，几乎总是同一批股票排在前面。本文把横向比较拆成三种归一化口径——绝对提及、窗口份额、相对自身的 heat_z20——用对照表说明各自回答什么问题、从哪个接口取数、什么时候会误导，并给出一段同窗三口径并列的 Python 示例。文中所有数字均为示例，三种口径都是描述性统计量。

一、为什么不能只比 mentions

mentions 是窗口内被提到的次数。它适合回答「现在谁被讨论得最多」，但不适合回答「谁的讨论相对平常更不寻常」。示例：股票 A 平时日均提及 120 次，今天 150 次；股票 B 平时日均 5 次，今天 30 次（均为示例数字）。按绝对提及 A 远高于 B；按相对自身变化，B 的偏离更大。两种说法都成立，只是回答的问题不同。横向比较之前，先确定要回答哪个问题，再选口径。

还有一个常被忽略的变量是主体门槛。/hot/stocks 与 /heat/windows 都接受 min_score：前者加上门槛后只统计机构/大V 分 ≥ 该值的提及，后者用它定义「高分机构/大V 数」这一列的分数线（默认 1050，约前 10%）。比较组里的每只股票必须使用同一门槛，否则份额与名次混入了两种统计对象。分数范围约 450～1500，1000 左右为中等，门槛取值写进结果表头即可。

二、三种口径的定义

另有一个常用的辅助口径：agencies 的组内份额，用来区分「讨论量份额高」是来自更多主体还是更集中的少数主体。

三、示例对照

同一 24h 窗口，三只股票的示例读数（均为示例数字）：

规范描述是：「A 在组内讨论量份额约 71%；B 相对自身近 20 日日均偏离最大」。不应写成「B 比 A 更热」——在绝对口径下并非如此。B 与 C 的绝对提及几乎相同，但 B 的 heat_z20 明显更高，说明 B 平时更安静。

四、取数路径对照

三种口径都可以从多个接口取到，差别在时效、批量与是否可回看：

几点取舍：

• 比较组在 20 只以内且需要历史序列时，用日频面板一次批量取数最省调用；
• 只需要当前截面且比较组都在热榜前 200 内，用一次 /hot/stocks 即可，但不在榜上的股票会缺失，缺失不能当作 0；
• 需要六档窗口或逐小时细节时，用 /heat/windows 逐只调用，调用次数等于股票数，每次 0.005 元，非 2xx 不计费。

五、同窗三口径并列的示例脚本

# compare_three.py —— 示例，地址与令牌为占位
import os, requests, pandas as pd

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
CODES = ["<CODE_A>", "<CODE_B>", "<CODE_C>"]

def windows(code):
    r = requests.get(BASE + "/heat/windows", params={"ts_code": code},
                     headers=H, timeout=60).json()
    assert r["ok"], r["code"]
    return r["data"], r["meta"]

rows = []
for c in CODES:
    d, m = windows(c)
    # 各窗口的结构与列名以 OpenAPI 为准，这里假设 24h 窗口可按键读取
    w24 = d.get("windows", {}).get("24h", {}) if isinstance(d, dict) else {}
    rows.append({"code": c, "mentions": w24.get("mentions"),
                 "agencies": w24.get("agencies"),
                 "heat_z20": d.get("heat_z20"),
                 "server_time": m["server_time"], "request_id": m["request_id"]})

df = pd.DataFrame(rows)
df["share"] = df["mentions"] / df["mentions"].sum()
df["agency_share"] = df["agencies"] / df["agencies"].sum()
for col in ("mentions", "share", "heat_z20"):
    df[col + "_rank"] = df[col].rank(ascending=False, method="min")
print(df)

脚本输出三列名次。名次不一致是常态，不是数据问题。报告时把三列并列展示，并在表头写清窗口与比较组成员。

六、比较组怎么定

归一化结果高度依赖「和谁比」：

1. 份额只在组内有意义。 换一个比较组，同一只股票的 share 就会变。比较组成员与数量要随结果一起保存。
2. 组内规模差异过大时先分层。 大市值与小市值股票放在一组，份额几乎总是被前者占据。可以先按自有的市值或行业分层，再在层内计算份额。
3. 概念成员可以从熔岩取。 想比较「某概念下的几只股票」，用 get_concept_stock_heat（/concepts/stocks，concept 精确匹配，days 默认 30）取前若干只成分股作为比较组；反过来，get_stock_concept_heat（/concepts/by-stock）可以确认这些股票是否共享同一概念。
4. market 口径保持一致。 热榜 market=ashare 按代码合并，all 按简称合并，同组比较时只用一种。

熔岩站点的个股热度对比工具页面提供了多只股票热度并列展示的只读视图，适合快速目测；需要保存口径、做批量或回看时，再用上面的接口复现。

七、常见误读对照表

八、用日频面板做历史横向比较

实时截面只能回答「现在」。要看过去一段时间里比较组内份额怎么变化，用日频面板 /panel/daily（get_stock_heat_panel）一次取回最多 20 只股票、最长 92 天的自然日序列，再在本地逐日计算份额与相对自身的偏离：

r = requests.get(BASE + "/panel/daily",
                 params={"type": "stock", "codes": ",".join(CODES),
                         "from": "2026-08-17", "to": "2026-11-13"},
                 headers=H, timeout=60).json()
assert r["ok"], r["code"]
p = pd.DataFrame(r["data"] if isinstance(r["data"], list) else r["data"].get("list", []))

# 日期列与代码列的列名以 OpenAPI 为准，这里假设为 date / ts_code
p["share_d"] = p["mentions"] / p.groupby("date")["mentions"].transform("sum")
g = p.sort_values("date").groupby("ts_code")["mentions"]
mu = g.transform(lambda s: s.shift(1).rolling(20, min_periods=10).mean())
sd = g.transform(lambda s: s.shift(1).rolling(20, min_periods=10).std())
p["mentions_z20_local"] = (p["mentions"] - mu) / sd

三点说明：

• shift(1) 保证每天的基准只用此前的数据，避免把当天计入自己的基准；
• 面板是自然日，周末与节假日也有行，滚动 20 行即 20 个自然日，与接口 heat_z20 的「近 20 日」口径未必相同，所以本地列单独命名；
• 某天比较组合计为 0 时 share_d 为空，保留空值，不要填 0。

这样得到的是一张「每天、每只股票、三口径」的长表，可以画组内份额堆叠图，也可以按日统计哪只股票的本地 z 分最高，作为描述性记录。

FAQ

Q：三种口径应该选哪一个作为主口径？
A：取决于研究问题。描述「讨论量分配」用份额；描述「相对常态的偏离」用 heat_z20；描述「绝对关注度」用 mentions。报告里建议三列并列，不做加总。

Q：能把三种口径合成一个综合分吗？
A：可以在本地做，但权重是主观选择，需要在结果中写明公式，并保留原始三列，避免读者只看到一个难以解释的数字。

Q：比较组超过 20 只怎么办？
A：日频面板按 20 个一批分批取数后合并；实时截面可以先取一次 /hot/stocks 并设 limit=200，缺失的股票再逐只补取。

Q：agencies 份额和 mentions 份额差很多说明什么？
A：说明讨论结构不同：mentions 份额远高于 agencies 份额，表示该股的讨论更集中在少数主体；反之则参与主体更分散。

Q：份额曲线突然跳变，先查什么？
A：先查比较组当天的合计是否很小。合计越小，单只股票几次提及就能让份额大幅变化；其次查当天是否有成员缺行。

结论

横向比较熔岩热度，关键是先选口径再看名次：绝对提及回答「谁被说得最多」，窗口份额回答「组内如何分配」，heat_z20 回答「谁相对自身最不寻常」。固定窗口与比较组、缺失不当 0、三列并列展示并保存元数据，多只股票的热度比较就能既直观又可复现。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

只读监测与字段说明见：https://lava.ai-dolphin.com/tools/stock-heat-compare

研究一只股票的消息面时，熔岩（Lava）提供了几路互补的数据：单股多窗口热度 /heat/windows 给出近 24 小时逐小时走势，个股消息面 /opinions 给出每条记录的时间与一句话摘要，新闻点名 /news/hits 给出主流媒体快讯的发布时间与命中股票，覆盖度 /coverage/stocks 给出每日滚动的去重主体数，日频面板 /panel/daily 给出按自然日的历史序列。本文以宁德时代（300750.SZ，仅作接口示例中的查询对象）为例，用六步管线把这几路数据合并成一条按时间排序的事件表，并说明时区、时间粒度和字段边界。文中数字均为示例，时间线只描述「何时、哪一路数据、计数多少」，不包含任何方向判断。

一、五路数据各自负责什么

五路数据都只读，都用同一个股票标识查询（ts_code 或 stock_name 二选一）。建议统一用 ts_code，避免简称变更或重名带来的歧义。

二、先统一时间轴

时间线能否拼对，取决于时间戳是否在同一个时区、同一个精度上：

• 响应信封里的 meta.server_time 带 +08:00，是本次调用的服务器时刻；
• /opinions 记录的 topic_time 为北京时间；
• /news/hits 每条新闻有发布时间，列名以 OpenAPI 为准；
• hourly_24h 是从调用时刻往回 24 小时的逐小时桶，桶的起止边界以返回为准；
• /coverage/stocks 与 /panel/daily 是日粒度，日期按 Asia/Shanghai 自然日。

本地建议统一转换为带时区的 Asia/Shanghai 时间戳，再按「小时」与「自然日」两个粒度分别建索引。逐条记录挂在小时索引上，覆盖度与面板挂在日索引上，不要把日粒度数字强行摊到小时。

三、六步管线

步骤 1：取热度骨架

# timeline.py —— 示例，地址与令牌为占位
import os, requests, pandas as pd

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
CODE = "300750.SZ"

def get(path, **params):
    r = requests.get(BASE + path, params=params, headers=H, timeout=60).json()
    assert r["ok"], (path, r["code"])
    return r["data"], r["meta"]

win, m_win = get("/heat/windows", ts_code=CODE, min_score=1050)
hourly = win.get("hourly_24h", [])   # 逐小时桶，桶内列名以 OpenAPI 为准

min_score=1050 只影响「高分机构/大V 数」这一列的分数线，不改变总提及数。

步骤 2：取消息面记录

ops, m_ops = get("/opinions", ts_code=CODE, days=3, only_this_stock=0, limit=200)
records = ops.get("list", []) if isinstance(ops, dict) else ops
heat = ops.get("heat", {}) if isinstance(ops, dict) else {}

每条记录含 opinion_id、topic_time、agency_id、agency_score、stocks、concepts、summary（≤120 字）、detail（≤600 字）；data.heat 给出区间汇总的 mentions 与 agencies。only_this_stock=0 取该股为第一提及股的记录，=1 只要仅涉及该股的记录，两者条数不同，时间线上要注明用了哪一个。

步骤 3：取新闻点名

news, m_news = get("/news/hits", ts_code=CODE, hours=72, limit=200)

指定股票时 hours 默认 72、最多 168；可用 src 精确指定一家媒体。返回包含 news_id、发布时间、媒体、命中股票，不输出标题与正文。

步骤 4：取覆盖度与日频背景

cov, m_cov = get("/coverage/stocks", ts_code=CODE, days=30, min_score=1050)
pnl, m_pnl = get("/panel/daily", type="stock", codes=CODE,
                 **{"from": "2026-08-17", "to": "2026-11-14"})

覆盖度返回 cov_7d、cov_30d、new_cov_cum、high_score_ratio_30d，只给计数、不返回机构 ID 列表。面板返回 mentions、agencies、weighted_heat、is_first_mention_day，区间不超过 92 天。

步骤 5：合并为事件表

把步骤 1～3 转为统一结构：ts（带时区时间戳）、source（windows / opinions / news）、kind（小时计数 / 记录 / 点名）、value（计数或标识）、ref（opinion_id 或 news_id），按 ts 排序。步骤 4 单独生成日表，用日期与事件表关联。

TZ = "Asia/Shanghai"
ev = []
for x in records:
    ev.append({"ts": pd.Timestamp(x["topic_time"]).tz_localize(TZ),
               "source": "opinions", "kind": "记录",
               "value": x.get("agency_score"), "ref": x.get("opinion_id")})
news_rows = news.get("list", []) if isinstance(news, dict) else news
for x in news_rows:
    # 发布时间与媒体的列名以 OpenAPI 为准，这里假设为 pub_time / src
    ev.append({"ts": pd.Timestamp(x.get("pub_time")).tz_localize(TZ),
               "source": "news", "kind": "点名",
               "value": x.get("src"), "ref": x.get("news_id")})
tl = pd.DataFrame(ev).sort_values("ts").reset_index(drop=True)
tl["hour"] = tl["ts"].dt.floor("h")   # 与逐小时桶对齐

若时间字符串已带 +08:00，用 tz_convert 代替 tz_localize，否则会报错或重复偏移。逐小时桶按 hour 与事件表左连接，即可在每个小时下列出当小时的记录与点名。

步骤 6：保存调用元数据

五次调用各记录 meta.request_id 与 meta.server_time，连同参数一起写入同一个 JSON。五次调用计费五次（每次 0.005 元，非 2xx 不计费）。

四、示例时间线

以下是一条合并后的示例时间线（全部为示例数据，摘要用占位符表示）：

这张表能回答的问题是：「讨论量抬升的那个小时前后，媒体点名与消息面记录各出现在什么时刻」。它不回答「为什么」或「接下来会怎样」。

五、三条字段边界

1. 新闻没有标题和正文。 /news/hits 只给发布时间、媒体与命中股票。时间线上的「内容」只能来自 /opinions 的 summary，不要用外部渠道补全文。
2. 逐小时数据只覆盖最近 24 小时。 更早的小时级时间线需要用 /opinions 记录的 topic_time 自行按小时计数，与 hourly_24h 口径不完全一致，需分开标注。
3. 面板的加权热度不是 PIT。 /panel/daily 的 weighted_heat 用当前机构分加权；时间线上引用历史加权读数时注明这一点，严格的历史加权口径用 /hot/weighted 的 as_of_date。

六、交给 AI Agent 的提示词

为 ts_code=<代码> 生成近 72 小时消息面时间线：
- 依次调用 get_stock_heat_windows、get_stock_news_heat(days=3, limit=200)、
  get_news_stock_hits(hours=72)、get_agency_coverage(days=30)
- 所有时间统一为 Asia/Shanghai，按时间排序输出表格：时间 / 来源 / 计数或标识
- 摘要只引用 summary 字段，不改写为结论；新闻只列媒体与时间
- 末尾列出每次调用的 request_id 与 server_time
- 不输出任何方向判断或操作含义

熔岩站点上的宁德时代情绪监测页提供了同一只股票的只读走势展示，适合人工浏览；这条管线适合在脚本或 Agent 里按需复现并保存证据链。

七、时间线质量自检

合并完成后，用下面几项快速检查时间线是否可信：

自检结果建议与时间线一起保存，方便日后复盘时判断这条时间线的完整程度。

FAQ

Q：/opinions 的条数比 data.heat.mentions 少，是数据缺失吗？
A：不一定。记录列表受 limit（最大 200）截断，而汇总数统计的是整个区间。条数等于 limit 时应缩短区间或分段取数。

Q：新闻点名时间和消息面记录时间谁更早有意义吗？
A：可以作为描述记录下来，但两路数据的采集与匹配机制不同，时间先后只说明「各自何时出现」，不说明因果。

Q：能把时间线扩展到多只股票吗？
A：可以对每只股票重复管线，但调用次数随股票数线性增加。日频背景可以用 /panel/daily 的 codes 一次传最多 20 个代码来节省调用。

结论

单只股票的消息面时间线由五路只读数据拼成：逐小时热度给骨架，意见摘要与新闻点名给锚点，覆盖度与日频面板给背景。先统一时区与粒度，再按六步管线取数、合并、记录元数据，就能得到一张可复现、可审计、只描述事实顺序的事件表。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

熔岩（Lava）概念板块热度的入口是概念热榜 GET /hot/concepts（MCP 工具 get_market_hot_concepts），可选 window 为 1h、4h、18h、24h、3d 五档。以 AI 相关主题为例：同一个概念在 1h 窗口排前列、在 3d 窗口却排在中段，这种情况很常见，也最容易被误读为「突然爆发」或「热度退潮」。本文给出一份 15 项检查清单，把「取数参数是否一致、多窗口形态如何描述、下钻到成分股与日频序列时口径是否连贯、结果如何记录」逐项写清。清单面向量化研究脚本与 AI Agent，文中数字均为示例，所有字段都是描述性统计量。

一、为什么概念热度要做跨窗口检查

概念热榜有三个容易被忽略的特点：

1. 窗口是滚动的。 1h 统计的是从 meta.server_time 往回 1 小时，3d 是往回 72 小时。窗口越短，单条长文或一轮集中讨论的影响越大。
2. 没有 7d 档。 个股热榜 /hot/stocks 有 7d，概念热榜最长到 3d。需要周度概念序列时，应改用日频面板 /panel/daily 的 type=concept。
3. 已去掉泛词。 概念热榜在统计前去掉了过于宽泛的词，因此榜单上的概念名就是可以继续下钻的标准名；但被去掉的泛词也不会出现在任何窗口里，跨窗口对比时不必为它们找原因。

只看单一窗口时，这些特点不会造成问题；一旦把多个窗口的排名放在一起叙述，就必须先确认口径一致。

二、参数与口径速查

更新节奏：概念热榜约 2 分钟更新一次，概念成分提及排行 /concepts/stocks 约 10 分钟更新一次。两者时间戳不同步，是跨接口对比时最常见的「对不上」原因。

三、15 项检查清单

A. 取数一致性（1～4）

1. 五个窗口在同一轮内连续取数。 五次调用间隔尽量短，并记录每次的 meta.server_time；跨轮混用会把「时间推移」误当成「窗口差异」。
2. min_score 五档保持一致。 一档加门槛、一档不加，比较的就是两类主体。
3. limit 足够大。 目标概念在长窗口里可能排到 50 名以外，默认 50 会让它「消失」。研究 AI 主题时建议 limit=200。
4. 概念名从榜单返回里取。 不要手写「人工智能」「AI」等别名；精确匹配以榜单返回为准，后续传给 /concepts/stocks 的 concept 也用同一个字符串（≤30 字符）。

B. 多窗口形态（5～9）

5. 先排列绝对计数，再看名次。 名次受其他概念影响，mentions 是概念自身的读数。
6. 计算短窗占比。 例如 share_1h = mentions_1h / mentions_24h（本地计算列）。示例：AI 主题 mentions_1h=36、mentions_24h=180，占比 0.2，意味着最近 1 小时占了一天讨论量的五分之一（示例数字）。
7. 对照 agencies 是否同步变化。 短窗 mentions 高但 agencies 很少，说明是少数主体集中发布；两列同步升高才是参与面扩大。
8. 读 heat_z20 时带上窗口。 写成「24h 窗口 heat_z20」，不同窗口的 z 分不能互相比较。
9. 用一个形态标签描述结果。 建议只用三种描述：短窗集中（1h/4h 占比高）、多窗同步（各窗口名次接近）、长窗累积（3d 名次明显高于短窗）。标签是描述，不推断后续走势。

C. 下钻连贯性（10～13）

10. 成分股用 get_concept_stock_heat 下钻。 /concepts/stocks 用 days 回看（默认 30，最大 365），不是滚动 window；与 24h 概念热度对照时设 days=1，与 3d 对照时设 days=3，并在结果里注明。
11. 检查成分集中度。 前 3 只成分股 mentions 占概念合计的比例过高时，概念热度更像个股事件带动。
12. 反查重点个股的概念归属。 用 get_stock_concept_heat（/concepts/by-stock）确认该股是否同时挂在多个 AI 相关概念下，避免重复计数。
13. 需要多日序列时切到日频面板。 get_stock_heat_panel(type="concept", names=...)（/panel/daily）按自然日返回概念的 mentions、agencies、weighted_heat，区间最长 92 天；它与滚动窗口口径不同，不要拼接到同一条曲线上。

D. 记录与复现（14～15）

14. 每轮落库最少字段： window、min_score、limit、meta.server_time、meta.request_id、概念名、mentions、agencies、heat_chg_1d、heat_chg_3d、heat_z20、名次。
15. 记录费用。 五档窗口即五次调用，每次 0.005 元，非 2xx 不计费；用 get_account（/account，不扣费）定期核对余额。

四、窗口形态示例表

以下为某 AI 相关概念在同一轮取数中的示例读数（均为示例数字）：

这张表的规范描述是：「该概念 1h 占 24h 讨论量约 20%，短窗名次高于长窗，形态为短窗集中」。不应写成「热度即将扩散」或任何方向判断。

五、一轮五窗取数脚本

# concept_windows.py —— 示例，地址与令牌为占位
import os, requests

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
TARGET = "<从榜单返回复制的概念标准名>"

snap = {}
for w in ("1h", "4h", "18h", "24h", "3d"):
    r = requests.get(BASE + "/hot/concepts",
                     params={"window": w, "limit": 200},
                     headers=H, timeout=60).json()
    assert r["ok"], r["code"]
    rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
    # 概念名列名以 OpenAPI 为准，这里假设为 concept
    hit = [(i + 1, x) for i, x in enumerate(rows) if x.get("concept") == TARGET]
    snap[w] = {"server_time": r["meta"]["server_time"],
               "request_id": r["meta"]["request_id"],
               "rank": hit[0][0] if hit else None,
               "mentions": hit[0][1].get("mentions") if hit else None,
               "agencies": hit[0][1].get("agencies") if hit else None}

base = snap["24h"]["mentions"] or 0
share_1h = (snap["1h"]["mentions"] or 0) / base if base else None
print(snap, "share_1h:", share_1h)

rank 为空表示目标概念在该窗口前 200 名之外，应记为「未进入榜单前 200」，而不是 0。

六、与只读监测页的关系

熔岩站点上的 AI 板块热度监测页是只读展示，适合人工快速浏览主题热度的走势；本文的清单适合在 MCP 或 HTTP 层面复现同一主题的多窗口读数。两者的数据来源一致，但展示粒度与刷新时刻可能不同，引用页面上的读数时同样要注明查看时间。

七、常见误读对照表

误读多数来自省略了参数。只要规范写法里带上窗口、门槛与绝对计数，读者就能自行判断读数的适用范围。

八、给 AI Agent 的执行模板

把清单压缩成一段系统提示词，Agent 每次被问到「某个主题最近热不热」时按固定顺序执行：

对目标概念执行五窗一致性检查：
1. 用 get_market_hot_concepts 依次取 window=1h/4h/18h/24h/3d，limit=200，min_score 保持一致
2. 每档记录名次、mentions、agencies、heat_z20 与 meta.server_time；未进前 200 记为「未进入」
3. 计算 share_1h = mentions_1h / mentions_24h，给出形态标签：短窗集中 / 多窗同步 / 长窗累积
4. 如需成分股，用 get_concept_stock_heat，days 与对照窗口匹配并注明
5. 回答只描述统计形态，不推断后续走势，不给任何操作含义

模板中的步骤 2 与步骤 5 最重要：前者保证读数可复现，后者保证输出停留在描述层面。

FAQ

Q：为什么 1h 排名很高，3d 却不在前 50？
A：3d 窗口累积的是 72 小时讨论量，长期稳定讨论的概念会占据前列；一个短时集中被讨论的概念在长窗口里分量被稀释。先把 limit 调到 200 再确认名次。

Q：概念热榜能按 market 筛选吗？
A：概念热榜没有 market 参数。需要区分市场时，下钻到成分股后按代码自行过滤。

Q：五档窗口的 heat_z20 能求平均吗？
A：不建议。各窗口的统计区间不同，z 分的含义也不同，平均后没有可解释的口径。

Q：清单能直接交给 AI Agent 执行吗？
A：可以把 A、B 两组写进系统提示词，要求回答时同时给出 window、min_score、mentions、agencies，并禁止把形态标签改写为方向判断。

Q：同一主题有多个相近概念名，要合并吗？
A：可以在本地维护别名映射后并列展示，但不要把多个概念的 mentions 直接相加，同一条消息可能同时命中多个概念，相加会重复计数。

结论

概念热度的多窗口读数各自成立，问题出在把它们放在一起叙述时口径不一致。按清单做到同轮取数、参数一致、先看绝对计数、下钻时显式换算 days、需要多日序列时切换到日频面板，并把每轮参数与 meta.server_time 落库，AI 主题的热度形态就能被准确描述和复现。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

熔岩（Lava）几乎每个热度板块都同时返回两个计数：mentions（被提到几次）和 agencies（有多少个不同的机构/大V 提到）。多数用法只盯 mentions 排序，但两只 mentions 相同的股票，可能一只是 40 个主体各说一次，另一只是 4 个主体反复说了十次。本文把两列相除得到「每主体提及数」，说明它在全市场热度、概念板块、日频面板里各自怎么取、怎么处理分母为 0 和小样本，并给出一段从 /panel/daily 取数到截面分档的 Python 走读。文中所有数字均为示例，比值是描述讨论结构的统计量，不是交易信号。

一、两个计数分别数的是什么

两列在以下熔岩数据板块中同时出现，口径都是「同一统计区间内」：

注意：/heat/windows 每个窗口还给出「高分机构/大V 数」，日频面板还给出 weighted_heat。本文只用 mentions 与 agencies 两列，另外两列放在第五节讨论分工。

二、比值的定义与边界

把每主体提及数记为 mpa（mentions per agency，本地计算列，不是接口返回字段）：

mpa = mentions / agencies          （agencies >= 1）
mpa = 空值                          （agencies = 0）

几条边界规则：

1. 下限是 1。 每个主体至少贡献一次提及，所以 mpa >= 1；等于 1 表示每个主体只说了一次，讨论最分散。
2. 分母为 0 不填 0。 某些行可能出现 mentions > 0 而 agencies = 0（例如提及记录没有关联到主体），这类行应标记为空值并单独计数，不要并入「分散」或「集中」任何一档。
3. 小样本不读比值。 agencies 只有 1～2 时，比值波动极大。建议设 agencies >= 5（示例阈值）作为读比值的前提，低于阈值只记录原始计数。
4. 跨区间不可比。 24h 窗口的 mpa 与 7d 窗口的 mpa 统计区间不同，同一主体在更长区间里有更多机会重复提及，长窗口的比值天然偏高。比较时固定 window 或 days。
5. 取对数更稳。 截面比较时用 log(mpa)，可以压缩极端值，0 点对应「每主体一次」。

三、四种组合的读法

把 mentions 的截面分位和 mpa 放在一起，可以得到四类讨论结构：

示例：同一 24h 窗口，股票 A mentions=48、agencies=40，mpa=1.2；股票 B mentions=48、agencies=6，mpa=8.0（均为示例数字）。两者在热榜上名次接近，但 B 的讨论来自更少的主体，单一主体的表达习惯对计数的影响更大。

四、Python 走读：从日频面板到截面分档

日频面板 /panel/daily（get_stock_heat_panel）按自然日返回 mentions、agencies、weighted_heat、is_first_mention_day，单次最多 20 个代码，区间最长 92 天。下面的示例分批取数，计算每日 mpa，再按截面分档。

# mpa_panel.py —— 示例，地址与令牌为占位
import os, requests, numpy as np, pandas as pd

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}

def panel(codes, frm, to):
    r = requests.get(BASE + "/panel/daily",
                     params={"type": "stock", "codes": ",".join(codes),
                             "from": frm, "to": to},
                     headers=H, timeout=60).json()
    assert r["ok"], r["code"]
    rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
    return pd.DataFrame(rows), r["meta"]["request_id"]

universe = ["<CODE_1>", "<CODE_2>"]  # 自有股票池，按 20 个一批
frames = []
for i in range(0, len(universe), 20):
    df, rid = panel(universe[i:i + 20], "2026-10-01", "2026-11-13")
    df["request_id"] = rid
    frames.append(df)
p = pd.concat(frames, ignore_index=True)

MIN_AG = 5  # 示例阈值
p["mpa"] = p["mentions"] / p["agencies"].where(p["agencies"] >= MIN_AG)
p["log_mpa"] = np.log(p["mpa"])  # 空值保持为空

# 日期列与代码列的列名以 OpenAPI 为准，这里假设为 date / ts_code
p["m_pct"] = p.groupby("date")["mentions"].rank(pct=True)
p["mpa_pct"] = p.groupby("date")["log_mpa"].rank(pct=True)
p["bucket"] = (
    (p["m_pct"] >= 0.8).map({True: "高提及", False: "低提及"})
    + "/" + (p["mpa_pct"] >= 0.8).map({True: "集中", False: "分散"})
)
print(p.groupby("bucket").size())

示例输出可能是：「高提及/分散」312 行、「高提及/集中」57 行、「低提及/集中」41 行，其余为低提及/分散或空值（示例数字）。每批调用计费一次（0.005 元/次，非 2xx 不计费），request_id 随行保存，方便事后复现。

两个工程细节：

• 面板是自然日，周末与节假日也有行。若要和交易日行情对齐，先决定周末的计数归入哪个交易日，再计算比值；先算比值再合并会把两天的比值错误平均。
• mpa 是两个计数的比，合并多日时应该先把 mentions、agencies 分别汇总再相除。但多日 agencies 简单相加会重复计入同一主体，所以多日口径更适合直接用对应长度的 window 或 days 重新取数。

五、与加权热度、覆盖度的分工

两点口径提醒：/panel/daily 的 weighted_heat 用当前机构分加权，不是当日 PIT；严格回测要用 /hot/weighted 的 as_of_date 或 /agencies/pit 截面。覆盖度接口只给计数，不返回机构 ID 列表，因此无法从它反推「是哪几个主体在集中讨论」，需要时只能从 /opinions 的记录里按匿名 agency_id 统计分布。

六、口径检查清单

• 引用 mpa 时写明来源接口与区间，例如「24h 窗口 /hot/stocks 的 mentions/agencies」。
• market=all 时热榜按简称合并，A 股按代码合并，两种口径的比值不要放进同一张截面。
• 在 /hot/stocks 上加 min_score 后，只统计高分主体的提及，mentions 与 agencies 同时缩小，比值含义变为「高分主体内部的集中度」。
• 落库字段至少包括：接口路径、window 或 days、min_score、meta.server_time、meta.request_id、mentions、agencies 与本地计算的 mpa。

FAQ

Q：mpa 高是不是说明讨论质量低？
A：不能这样推。比值只描述讨论在主体之间是否集中，和主体分数无关。质量相关的问题用 weighted_heat 或 high_score_ratio_30d 另外回答。

Q：概念板块也能算这个比值吗？
A：可以。/hot/concepts 和 /concepts/stocks 都返回两列计数。概念层面的高比值常见于少数主体反复写同一主题的长系列内容，读法与个股一致。

Q：agencies = 0 的行能删掉吗？
A：建议保留并单独计数。删除会让「讨论结构」的统计样本看起来比实际更完整，保留空值才能看出这类行占比有多大。

Q：能把 mpa 做成回测因子吗？
A：技术上可以在 /panel/daily 上逐日计算，但要注意自然日对齐与小样本阈值，且结论需要注明口径。比值本身是描述性统计量，不包含方向含义。

Q：同一只股票在热榜和面板上算出的比值不一样，哪个对？
A：两者都对，只是统计区间不同。热榜的 24h 是从 meta.server_time 往回的滚动窗口，面板是按自然日切分，两个区间的主体集合不同，去重后的 agencies 自然不同。引用时说明来源即可，不要混用。

结论

mentions 回答「被说了多少次」，agencies 回答「有多少个不同主体在说」，两列相除得到的每主体提及数能把同样热度下的不同讨论结构区分开。读比值前固定统计区间、设好 agencies 下限、空值单独计数，再配合加权热度与覆盖度看主体质量与广度，就能把熔岩热度从单一排名扩展成更完整的结构描述。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

把熔岩（Lava）远程 MCP 接进 AI Agent 后，最常见的浪费不是调用失败，而是「同一个问题在一轮对话里被查了三次」：模型换个说法重新调用 get_market_hot_stocks，或者对同一只股票先后用简称和代码各查一次 get_stock_news_heat。熔岩的工具全部只读，成功调用按次计费，数据又各有更新节奏，因此非常适合在 Agent 侧做一层结果缓存，并在提示词里约束调用方式。本文以检查清单的形式给出 24 项要点，分为接入、缓存键、TTL、提示词、错误与计费、审计六组。TTL 数值均为示例，以你的业务节奏为准。

一、接入前提（4 项）

• 1. 端点与传输。 远程 MCP 路径为 /subscribe/v1/mcp，传输为 Streamable HTTP。HTTP 版本的路径与 MCP 工具一一对应，缓存层可以同时服务两种调用。
• 2. 鉴权放在请求头。 使用 Authorization: Bearer <API Key> 或 X-API-Key；也支持 OAuth 2.1（PKCE S256 + 动态注册）。Key 不放进网址，不写进提示词，也不进入缓存值。
• 3. 工具清单固定版本。 启动时调用一次 tools/list，把工具名与 inputSchema 的哈希记入日志。参数演进时缓存键规则需要同步调整。
• 4. 明确只读边界。 熔岩工具只返回结构化数字与短摘要，提示词里写明「不生成操作建议」，缓存层也不保存模型的二次加工结论，只保存工具原始返回。

二、缓存键怎么设计（4 项）

• 5. 键 = 工具名 + 规范化参数。 参数按名称排序，默认值显式补齐。例如 get_market_hot_stocks 不传 window 与传 window=24h 应命中同一个键。
• 6. 标的统一成代码。 stock_name 与 ts_code 二选一的工具（get_stock_news_heat、get_stock_heat_windows、get_stock_concept_heat 等），缓存前先把简称映射成代码，避免一只股票两份缓存。映射表本身可以长期缓存。
• 7. 概念名保持原样。 get_concept_stock_heat 的 concept 精确匹配、不超过 30 字符，缓存键里不要做全半角或空格「清洗」，否则会把两个实际不同的请求合并成一个。
• 8. 市场范围进键。 market=ashare 与 market=all 合并键不同（前者按代码、后者按简称），必须作为独立缓存条目。

三、按数据板块设 TTL（4 项）

TTL 的上限由数据更新节奏决定：比更新更频繁地刷新只会得到重复内容。文档给出的节奏是：个股热榜约 1 分钟，概念热榜与新闻点名约 2 分钟，概念成分约 10 分钟。其余接口没有公开周期，下表按数据性质给出示例值。

• 9. 区分「会变」与「已定格」。 日频面板中已经结束的日期、/agencies/pit 的已发布截面，是可以长期缓存的历史；含今天的数据必须短 TTL。
• 10. as_of_date 的特殊处理。 get_weighted_hot_stocks 传入 as_of_date 时消息截至当天 15:00（Asia/Shanghai）、分数走 PIT。若 as_of_date 是今天且当前早于 15:00，截面尚未定格，只能短缓存；过了截稿时间才可以长期保存。
• 11. 盘中盘后两套 TTL。 消息面盘后也在更新，但节奏较慢，盘后 TTL 可放大为盘中的 3～6 倍（示例）。
• 12. 交易日历由你提供。 熔岩接口按自然日或滚动窗口统计，是否为交易时段要用自有日历判断，不要让模型自行推断。

四、提示词约束（4 项）

• 13. 先查缓存再调用。 在工具描述或系统提示中写明：同一轮对话内，同一工具与同一参数只调用一次，结果复用。
• 14. 回答必须带时间与参数。 每次引用数字都带 window 或 days、market、min_score，以及 meta.server_time。命中缓存时，回答中的时间应是缓存条目的 server_time，而不是当前时间。
• 15. 禁止模型补写字段。 返回里没有的字段不得猜测；summary 不超过 120 字、detail 不超过 600 字，都是摘要而不是原文；新闻点名不含标题与正文；机构/大V 只用 agency_id 指代。
• 16. 工具选择写成规则表。 例如「现在谁最热 → 个股热榜；谁变化最快 → 加速榜；此前 7 天无人提及 → 首提流；高分主体在讨论什么 → 加权热榜；单股时间结构 → 多窗」。规则越明确，模型越少「换个工具再试一次」。

示例系统提示片段：

你可以调用熔岩只读工具。规则：
1) 调用前检查 cache[(tool, normalized_args)]，命中且未过期则直接使用。
2) stock_name 先映射为 ts_code 再作为缓存键。
3) 回答格式：结论(高/中/低) + 数字 + 参数 + server_time。
4) 机构/大V 只写 agency_id；不推测真名；不补写摘要外的内容。
5) 只描述统计结果，不给出任何操作建议。

五、错误、限流与计费（4 项）

• 17. 只缓存成功结果。 ok=false 的响应不进缓存，但要记录 code，避免模型在同一错误上无限重试。
• 18. 429 按 Retry-After 等待。 RATE_LIMITED 时按响应头等待后最多重试一次；DAILY_QUOTA_EXCEEDED 当日停止调用，切换为只读缓存并在回答中说明。
• 19. 402 余额不足如实转告。 INSUFFICIENT_BALANCE 时告诉用户到熔岩「AI数据服务」→「概览与充值」处理，不重试。
• 20. 用响应头核算费用。 成功调用每次 0.005 元，非 2xx 与 get_account 不计费；响应头 X-Billing-Charged-Yuan 与 X-Balance-Yuan 可直接写入缓存条目的元数据，命中缓存即节省一次计费。

六、审计与复现（4 项）

• 21. 缓存条目带 request_id。 保存 meta.request_id 与 meta.server_time，任何一条回答都能追溯到具体的那次调用。
• 22. 命中率与节省额入日志。 每日统计「命中次数 × 单价」作为节省估算。示例：一天 600 次工具请求、命中 380 次，按 0.005 元计节省约 1.9 元（示例数字），更重要的是减少了重复数据进入上下文。
• 23. 上下文只放必要字段。 榜单返回最多 200 行，放进模型上下文前按问题裁剪列和行，原始返回留在缓存里，需要时再取。
• 24. 定期回归。 用固定问题集比较「缓存命中回答」与「实时调用回答」的参数和字段是否一致，发现工具参数演进时同步更新键规则。

缓存失效的触发条件

TTL 到期只是最基本的失效方式。下面几种情况也应主动清除相关条目，否则缓存会把旧口径带进新回答：

一个容易忽略的点：get_stock_news_heat 返回的意见记录里，agency_score 是主体的当前分。机构/大V 新发布日之后，同一条记录的分数可能不同，因此消息面缓存也应在新发布日后失效，或在回答中注明「分数为取数时的当前分」。

一个最小缓存装饰器（示例）

# lava_cache.py —— 示例，地址与令牌为占位
import json, time, hashlib

TTL = {"get_market_hot_stocks": 180, "get_market_hot_concepts": 300,
       "get_concept_stock_heat": 900, "get_news_stock_hits": 300,
       "get_stock_news_heat": 600, "get_stock_heat_windows": 600}
DEFAULTS = {"get_market_hot_stocks": {"window": "24h", "market": "ashare", "limit": 50}}
_store = {}

def key(tool, args):
    a = {**DEFAULTS.get(tool, {}), **args}
    raw = tool + json.dumps(a, sort_keys=True, ensure_ascii=False)
    return hashlib.sha256(raw.encode()).hexdigest()

def cached_call(tool, args, call_fn):
    k, now = key(tool, args), time.time()
    hit = _store.get(k)
    if hit and now - hit["t"] < TTL.get(tool, 300):
        return hit["resp"], True
    resp = call_fn(tool, args)          # call_fn 负责实际 MCP/HTTP 调用
    if resp.get("ok"):
        _store[k] = {"t": now, "resp": resp}
    return resp, False

这段代码只演示键规范化与按工具区分 TTL，生产环境还需要持久化存储、并发锁与盘中盘后切换。

FAQ

Q：缓存会不会让 Agent 给出过时的热度？
A：只要 TTL 不长于业务可接受的延迟，并且回答里展示的是缓存条目的 server_time，读者就能判断数据时点。需要最新数字时，允许用户显式要求「刷新」，跳过缓存。

Q：MCP 和 HTTP 两条通道能共用一份缓存吗？
A：可以。两者对应同一套数据与参数，缓存键用工具名或路径统一映射即可；鉴权信息不进入键和值。

Q：日频面板可以缓存多久？
A：已经结束的自然日可以长期保存；包含今天的那一行是未完结日，应短 TTL 或剔除。注意 weighted_heat 是当前机构分口径，若机构分后续更新，重新拉取的历史 weighted_heat 可能变化，缓存时要标注取数日期。

结论

熔岩 MCP 的只读、按次计费与分板块更新节奏，决定了 Agent 侧缓存是性价比最高的工程优化。按「工具名 + 规范化参数」设计键，按数据板块的更新节奏设 TTL，区分已定格的历史与仍在变化的今天，再用提示词约束模型复用结果、带上参数与 server_time，就能同时降低费用、减少上下文噪声，并让每一条回答都可以追溯。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

熔岩（Lava）的概念成分提及排行 GET /concepts/stocks（MCP 工具 get_concept_stock_heat）回答的是：在某个概念下，最近哪些股票被提到最多、有多少机构/大V 提到。它有一个看似简单的参数 days：默认 30，范围 1～365。正是这个参数，加上 limit 上限、约 10 分钟的更新节奏和概念名精确匹配，造成了大量「两次查询对不上」「榜单突然换人」的困惑。本文用坑位清单的形式逐条列出，每一条都给出现象、原因和处理方式。所有数字均为示例，概念名使用「示例概念甲」等虚构名称。

先认清这张表在熔岩里的位置

熔岩的消息面数据分几块：全市场热度（个股热榜、加速榜、首提流、加权热榜）、个股热度（/opinions、/heat/windows、/panel/daily）、概念板块、机构/大V 评分（含 PIT 截面）与新闻点名。概念板块内部又有三条只读路径：

/concepts/stocks 的 concept 参数必填，精确匹配，长度不超过 30 字符。下面的坑大多围绕这张表展开。

坑 1：把「提及排行」当成官方成分表

现象：某只常被归入该概念的股票不在返回列表里。
原因：返回的是消息面里被提及的股票，不是交易所或指数公司的成分表。回看期内没被讨论的股票自然不会出现。
处理：在研究表里把这一列命名为「概念提及成分（days=N）」，不要命名为「概念成分」。需要官方成分时用你自有的数据源。

坑 2：不写 days 就默认是「最近」

现象：同事说「这个概念最近最热的是 A」，你查出来却是 B。
原因：一方用了默认 days=30，另一方传了 days=7。30 天的排行被月初的一次集中讨论主导，7 天的排行反映的是本周。
处理：任何引用都带上 days。示例写法：「示例概念甲，days=7，提及第 1 名」。

坑 3：长回看把旧事件「冻」在榜首

现象：days=90 或更长时，榜首长期不变。
原因：回看越长，单次大事件的累计提及越难被稀释。示例：某股 60 天前一次事件贡献了 300 次提及（示例数字），之后每天只有个位数，在 days=90 下仍可能排第一。
处理：长回看用于「这个概念长期由谁承载讨论」，短回看用于「最近谁在承载」。要看变化，把 7/30/90 三档并列，而不是只看一档。

坑 4：短回看的样本太薄

现象：days=1 的排行每次刷新都在大幅换人。
原因：一天内概念下的讨论条数可能很少，第 5 名和第 30 名只差一两次提及，名次对噪声非常敏感。
处理：短回看只读前几名，并同时看提及数本身；需要日内结构时，改用单股的 /heat/windows（1h 到 7d 六档加 hourly_24h）。

坑 5：days 与 window 混为一谈

现象：把 /hot/concepts?window=3d 的概念热度和 /concepts/stocks?days=3 的成分排行直接对比，觉得数字「对不上」。
原因：window 是滚动小时窗口，days 是以天计的回看；两者统计对象也不同，一个是概念整体，一个是概念下各股票。
处理：对账时只做同一接口内的比较。跨接口只比较方向和覆盖面，不比较绝对数。

坑 6：limit 上限 100 被忽视

现象：想取概念下「全部被提及股票」，结果只有 50 条或 100 条。
原因：limit 默认 50，最大 100，且没有文档化的分页偏移参数。
处理：若研究定义是「概念下全部提及股票」，就要在表头写清「前 100 名」；不要假设可以翻页。概念特别大时，可以缩短 days 让排行更集中，或从个股侧用 /concepts/by-stock 反查。

坑 7：在 10 分钟更新周期内反复刷新

现象：脚本每分钟拉一次，结果大多相同，费用却在增长。
原因：该接口约 10 分钟更新一次；成功调用每次按 0.005 元计费。
处理：轮询间隔至少 10 分钟，用内容哈希判断是否有变化，没变化就不落新快照。示例：一天盘中 4 小时按 10 分钟间隔约 24 次，按 1 分钟间隔是 240 次，后者大部分是重复数据。

坑 8：概念名不精确导致的「空榜」

现象：返回空列表或参数错误。
原因：concept 精确匹配。「示例概念甲」能查到，「示例概念甲概念」「示例 概念甲」未必能查到；全半角、空格、超过 30 字符都会失配。
处理：概念名一律从 /hot/concepts 或 /concepts/by-stock 的返回值复制，并在本地保存规范名表。空结果要如实记录为「该参数下无匹配」，不要换近似词反复试。

坑 9：把不同时刻的两次快照当成同一截面

现象：上午与下午各取一次 days=30，名次变化被解读为「讨论转移」。
原因：回看窗口在滑动，旧的一天移出、新的一天移入；上午与下午之间还经过了若干次数据更新。
处理：每次快照保存 meta.server_time 与 meta.request_id。比较「成分变化」时，固定每天同一时点取数，并把进入、退出分开统计。

坑 10：用 days 的回看去做回测

现象：拿今天取到的 days=30 排行，当成 30 天前那一天的概念成分。
原因：接口没有 as_of_date，回看窗口以取数时刻为终点。今天的结果包含了 30 天前那一天之后的讨论。
处理：历史研究改用日频面板 /panel/daily（get_stock_heat_panel）：type=stock 配 codes（单次最多 20 个）逐股取自然日序列，或 type=concept 配 names 取概念级序列，区间最长 92 天。若需要高分机构/大V 口径的历史截面，用 /hot/weighted 的 as_of_date（消息截至当天 15:00）或 /agencies/pit。

一个把 7/30/90 并列的取数示例

# concept_days_ladder.py —— 示例，地址与令牌为占位
import os, requests

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}
CONCEPT = "示例概念甲"   # 必须是从 /hot/concepts 复制的规范名

def members(days):
    r = requests.get(BASE + "/concepts/stocks",
                     params={"concept": CONCEPT, "days": days, "limit": 100},
                     headers=H, timeout=60).json()
    if not r.get("ok"):
        return None, r.get("code")
    rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
    # 成员标识与提及数列名以 OpenAPI 为准
    return [x.get("ts_code") or x.get("stock_name") for x in rows], r["meta"]["server_time"]

ladder = {d: members(d) for d in (7, 30, 90)}
s7, s30, s90 = (set(ladder[d][0] or []) for d in (7, 30, 90))
print("三档共同:", len(s7 & s30 & s90), "仅 7 天:", len(s7 - s30 - s90))

示例读法：三档共同出现 18 只、仅在 7 天档出现 6 只（示例数字）。前者是该概念讨论的「长期承载者」，后者是「最近才被带进讨论的股票」。这种分层只描述讨论结构，不涉及任何取舍建议。

坑位速查表

与个股反查配合：双向核对

概念 → 个股（/concepts/stocks）与个股 → 概念（/concepts/by-stock）是同一关系的两个方向，但默认回看不同：前者 days 默认 30，后者默认 90。双向核对时如果不统一 days，就会出现「概念榜里有这只股票，反查这只股票却看不到该概念排在前面」的假矛盾。

建议的核对步骤（示例）：

1. 对「示例概念甲」调用 get_concept_stock_heat(concept="示例概念甲", days=30, limit=100)，取前 10 名代码；
2. 对这 10 只逐一调用 get_stock_concept_heat(ts_code=<代码>, days=30)，注意显式传 days=30，不要用默认 90；
3. 检查「示例概念甲」在每只股票的关联概念里排第几；排名靠后说明该股的讨论主要由其他概念承载，示例概念甲只是它的次要标签；
4. 把两边的 meta.server_time 都记下，两者更新节奏不同，时间差过大时重新取数。

这一步共 11 次调用，按每次 0.005 元计约 0.055 元（示例估算）。概念板块与个股热度两块数据由此连成一张可解释的关系表。

FAQ

Q：/concepts/stocks 支持 min_score 吗？
A：是否支持以 OpenAPI 为准。需要高分机构/大V 口径时，可以在概念热榜 /hot/concepts 上加 min_score 观察，或对成分股逐只查看 /heat/windows（高分线默认 1050）。

Q：概念热榜没有 7d，周度怎么看？
A：用 /concepts/stocks 的 days=7 看概念下个股的周度提及，或用 /panel/daily 且 type=concept 看概念级日频序列，不要给 /hot/concepts 传未列出的窗口值。

Q：同一只股票在两个概念里排名都很高，怎么解释？
A：一条讨论可能同时涉及多个概念，股票也可能关联多个概念。用 /concepts/by-stock 查看它关联的全部概念及提及，比在两个概念榜之间来回比较更清楚。

Q：days 直接设成 365 有意义吗？
A：范围允许到 365，适合回答「一年里这个概念主要由哪些股票承载讨论」。但它几乎不反映近期变化，且受 limit 最大 100 限制，长尾会被截掉。建议把 365 档当作背景参照，与 7 天、30 天档一起读，而不是单独使用。

结论

get_concept_stock_heat 是一张「概念下谁被讨论」的提及排行，读数高度依赖 days。记住几条口径：默认 30、范围 1～365；limit 最大 100；约 10 分钟更新；概念名精确匹配且不超过 30 字符；没有 as_of_date，不能直接拿来回测。把 7/30/90 三档并列、每次快照带上参数与时间，就能避开本文列出的大多数坑。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

熔岩（Lava）热度加速榜 GET /hot/accelerating（MCP 工具 get_accelerating_hot_stocks）在全市场热榜候选上计算动量统计，再按变化降序排列。同一张榜，order 取 chg1d、chg3d 还是 z20，排在前面的往往是完全不同的一批股票；min_mentions 与 window 又会进一步改变候选池。本文不讲概念入门，而是用多张对照表把「参数组合 → 回答的问题 → 典型偏差 → 该配合看哪个字段」逐项摆出来，方便量化脚本和 AI Agent 直接按表选参数。文中数字均为示例，三列字段都是纯统计量，不是交易信号。

一、参数总表

返回列表中的每一行都带 heat_chg_1d、heat_chg_3d、heat_z20。普通热榜 /hot/stocks（get_market_hot_stocks）也附带这三列，区别在于普通热榜按热度本身排序，加速榜按变化排序。三列的精确计算公式与基准（比率还是差值、滚动还是自然日）以 OpenAPI 为准；heat_z20 的公开描述是「相对近 20 日日均热度的 z 分」。

二、三种 order 的对照

一句话总结：chg1d 偏「快」，chg3d 偏「稳」，z20 偏「相对异常」。三者不存在谁更准确的问题，只有和研究问题是否匹配。

三、min_mentions 的取值对照

min_mentions 是控制低基数噪声最直接的开关。默认 3 很宽松，对 z20 排序尤其不够。

示例：同一时刻、window=24h、order=z20，min_mentions=3 时榜首的 mentions=4、heat_z20=8.1；改为 min_mentions=10 后，榜首变为 mentions=37、heat_z20=4.6（均为示例数字）。前者是「从几乎无人讨论到有人讨论」，后者是「本来就有讨论、今天明显更多」，两类事件含义不同，不应混在一张结论里。

四、window 与 order 的组合矩阵

两条规则：引用任何一个动量数字时都要带上 window，例如「24h 窗口 heat_z20」；跨窗口比较排名没有意义，因为候选池和当前热度的统计口径都变了。

五、加速榜与其他榜单的分工

单主题的只读监测页，例如寒武纪热度监测，展示的是一只股票自身的热度走势；在 MCP 里复现「它是否在加速」时，可以先看它是否出现在加速榜，再用 /heat/windows 的六档窗口与 hourly_24h 确认是短时脉冲还是多窗同步抬升。

六、一次三排序并读的示例脚本

# accel_three_orders.py —— 示例，地址与令牌为占位
import os, requests

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}

def accel(order, window="24h", min_mentions=10, limit=50):
    r = requests.get(BASE + "/hot/accelerating",
                     params={"window": window, "order": order,
                             "min_mentions": min_mentions,
                             "market": "ashare", "limit": limit},
                     headers=H, timeout=60).json()
    assert r["ok"], r["code"]
    rows = r["data"] if isinstance(r["data"], list) else r["data"].get("list", [])
    return rows, r["meta"]["server_time"]

tops = {}
for o in ("chg1d", "chg3d", "z20"):
    rows, ts = accel(o)
    # 代码列名以 OpenAPI 为准，这里假设为 ts_code
    tops[o] = {x.get("ts_code") for x in rows[:20]}
    print(o, ts, len(rows))

print("三榜共同出现:", len(tops["chg1d"] & tops["chg3d"] & tops["z20"]))
print("仅 z20 出现:", len(tops["z20"] - tops["chg1d"] - tops["chg3d"]))

三次调用各计费一次（每次 0.005 元，非 2xx 不计费）。示例结果可能是：三榜前 20 共同出现 6 只，仅在 z20 前 20 出现 7 只（示例数字）。共同出现的那一组，含义是「短期、多日与相对自身三个角度都显示变化较大」；仅在 z20 出现的那一组，通常要先检查 mentions 是否偏低。

七、落库字段清单

为了让加速榜快照可以复盘，建议每次至少保存：window、order、min_mentions、market、limit、meta.server_time、meta.request_id，以及每行的代码、mentions、heat_chg_1d、heat_chg_3d、heat_z20 和名次。只存名次而不存参数，是最常见的「第二天解释不了」原因。

八、常见误读对照表

九、给 AI Agent 的参数选择提示

把下面这段放进 Agent 的系统提示词或 Skill 里，可以减少「随手用默认值」带来的偏差：

调用 get_accelerating_hot_stocks 时：
- 用户问「突然被讨论」：order=z20, min_mentions>=10, window=24h
- 用户问「这几天持续升温」：order=chg3d, window=24h 或 3d
- 用户问「盘中异动」：order=chg1d, window=1h 或 4h, min_mentions>=10
- 回答必须同时给出 window / order / min_mentions / mentions / heat_z20
- 三列都是纯统计量；不得改写为方向判断或操作含义

Agent 只需要在参数层面做选择，不需要推测公式细节；公式与基准以 OpenAPI 为准，回答里不要自行补写。

FAQ

Q：order=z20 的榜首几乎都是冷门股，正常吗？
A：在默认 min_mentions=3 下很常见。冷门股历史日均低、波动小，z 分分母小，少量新增讨论就会得到很高的 z 分。把 min_mentions 提高到 10 或更高再看。

Q：加速榜能和普通热榜直接合并成一张表吗？
A：可以按代码并列字段，但名次不能合并。两张榜排序依据不同，同一只股票在普通热榜第 5、在加速榜第 40，两者都成立。

Q：heat_chg_1d 为负的股票会出现在加速榜吗？
A：加速榜按所选列降序，榜单前部以正向变化为主；是否返回负值行、返回多少，取决于候选池与 limit，以实际返回为准。研究热度回落时，用 /hot/stocks 或 /panel/daily 自行计算更直接。

Q：可以用加速榜做回测吗？
A：加速榜是实时截面，没有 as_of_date 参数。回测应以 /panel/daily 的自然日序列在本地复算变化量，并注明口径与原榜单不同。

结论

熔岩加速榜的三种排序各回答一个问题：chg1d 反映短期变化，chg3d 反映多日累积变化，z20 反映相对自身的偏离。min_mentions 决定低基数噪声有多少，window 决定当前热度的统计长度。按表选参数、引用时带上窗口与门槛、同时读 mentions 绝对值，再用 /heat/windows 下钻确认时间结构，就能把加速榜读成可复现的统计观察。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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

熔岩（Lava）回答「这只股票最近消息面热不热、大家在讨论什么」的入口，是个股消息面接口 GET /opinions（MCP 工具 get_stock_news_heat）。一次调用同时返回两层内容：汇总热度 data.heat（提及数 mentions、参与机构/大V 数 agencies）和意见记录列表 data.list[]（一句话摘要、结构化要点、涉及股票与概念、匿名 agency_id）。很多 Agent 和研究脚本只读了第一层，或者把第二层当成新闻原文引用。本文用问答形式把参数、字段和常见误读一次讲清，所有数字都标注为示例。

一、接口与参数

Q1：get_stock_news_heat 对应哪个 HTTP 路径，属于熔岩哪块数据？
A：对应 /opinions，属于「个股热度 / 个股消息面」板块。熔岩的数据大致分为：全市场热度（/hot/stocks、/hot/accelerating、/hot/first-mentions 等榜单）、个股热度（/opinions、/heat/windows、/panel/daily）、概念板块（/hot/concepts、/concepts/stocks、/concepts/by-stock）、机构/大V 评分（/agencies/ranking、/agencies/pit 等，含 PIT 截面），以及新闻点名 /news/hits。/opinions 是其中唯一同时给出「数字 + 文字要点」的个股接口。

Q2：参数怎么填？
A：按 OpenAPI，常用参数如下：

官方 Skill 模板里的示范写法是 get_stock_news_heat(stock_name 或 ts_code, days=7)，即看最近一周。

Q3：stock_name 和 ts_code 用哪个更稳？
A：研究脚本里优先 ts_code。简称存在改名、重名与全半角差异，代码更适合做主键；面向人的对话里可以用简称，但落库时应回填代码。

二、汇总热度 data.heat

Q4：data.heat.mentions 和 data.heat.agencies 分别是什么？
A：mentions 是所选区间内该股被提到的次数，agencies 是参与提及的机构/大V 数量。前者衡量讨论量，后者衡量讨论的广度。示例：days=7 时 mentions=46、agencies=19（示例数字），可读为「一周内 46 次提及，来自 19 个不同主体」。

Q5：汇总数和列表条数为什么对不上？
A：三个常见原因。第一，limit 默认 50，列表被截断，而汇总数统计的是整个区间；第二，only_this_stock 改变了列表样本；第三，部分记录的文本字段可能为空，展示层过滤后看起来「少了」。only_this_stock 是否同时影响汇总数，以 OpenAPI 说明为准，对账前先用同一参数各调一次确认。

Q6：「热度高」有统一阈值吗？
A：没有官方阈值。同一 mentions 对大市值热门股与冷门股含义不同。需要「相对自身」的读法时，改看 /heat/windows（get_stock_heat_windows）或榜单里附带的 heat_z20（相对近 20 日日均的 z 分）、heat_chg_1d、heat_chg_3d，它们都是纯统计量。

三、意见列表 data.list[]

Q7：每条意见记录有哪些字段？
A：按 Opinion 结构：

Q8：summary 能当新闻标题或原文引用吗？
A：不能。它是结构化摘要，不是任何媒体的标题，也不是原文。若需要「哪家媒体在何时点名了这只股票」，应调用 /news/hits（get_news_stock_hits），该接口给出 news_id、发布时间、媒体与命中股票，同样不含标题和正文。

Q9：agency_score 高的记录更值得看吗？
A：分数描述的是主体的历史评分，不是这条记录的质量判断。约 1000 为中等、1050 约前 10%。可以把它当作筛选或分层的一个维度，但要记住它是当前分：同一主体三个月前未必在同一档。

四、组合使用与常见误读

Q10：/opinions 和关键词检索 /opinions/search 怎么分工？
A：/opinions 以股票为入口；/opinions/search（search_news_flow）以关键词为入口，在要点里搜，keyword ≤50 字符、最多 5 个词、空格分隔且全部包含才命中，since 默认 30 天前、最早 180 天前。想追一个事件在多只股票间的扩散，用后者；想看单只股票的讨论全貌，用前者。

Q11：一个可复用的读法顺序是什么？
A：示例顺序如下，全部只读：

1. get_stock_news_heat(ts_code=<代码>, days=7, only_this_stock=0, limit=50)
   -> 记 data.heat.mentions / data.heat.agencies / meta.server_time
2. 读 list[] 前若干条的 summary，按 topic_time 倒序归纳 3~5 条要点
3. 需要时间结构：get_stock_heat_windows(ts_code=<代码>)
   -> 1h/4h/18h/24h/3d/7d 六档 + hourly_24h
4. 需要概念背景：get_stock_concept_heat(ts_code=<代码>, days=30)
5. 需要媒体点名：get_news_stock_hits(stock_name=<简称>)

输出时先给结论（热度高/中/低 + 提及数 + 参与主体数 + 时间窗），再给摘要要点，主体一律用 agency_id 指代。

Q12：Agent 最容易犯的错是什么？
A：示例中最常见的四类：

• 把 mentions 的绝对值当成跨股票可比的「热度分」；
• 把 summary 改写成带方向的判断句，或补写记录里没有的内容；
• 用 agency_score 当前分回填历史，或猜测 agency_id 背后的机构名称；
• 只给数字不给时间窗，读者无法知道是 7 天还是 10 天的统计。

五、与只读监测页的对应关系

熔岩的部分只读监测页，本质上是把同一类字段做成固定视图。例如宁德时代情绪监测页对应的就是「单只股票的消息面汇总 + 意见要点」这一组观察；在 MCP 里复现时，用 get_stock_news_heat 取汇总与摘要，用 get_stock_heat_windows 补时间结构，再记录参数与 meta.server_time。页面适合即时浏览，接口适合复盘与入库，两者口径一致但用途不同。

示例笔记格式：

[示例] 2026-11-13 09:30 (Asia/Shanghai)
标的: <代码>   接口: /opinions   days=7  only_this_stock=0
heat: mentions=46 agencies=19   (示例数字)
要点: 1) ... 2) ... 3) ...      (摘自 summary，未改写方向)
主体: AG... 等匿名编号

六、only_this_stock 两种取值的对照实验

only_this_stock 决定意见列表的样本边界，值得单独做一次对照。取值 0（默认）时，返回「该股为第一提及股」的记录；取值 1 时，只返回「仅涉及该股」的记录。前者覆盖更广，后者文本更聚焦。一个最小实验是在同一时刻、同一 days 下各调一次，比较三组数字：

# only_this_stock_ab.py —— 示例，地址与令牌为占位
import os, requests

BASE = os.environ.get("LAVA_BASE", "<YOUR_LAVA_BASE>/subscribe/v1")
H = {"Authorization": "Bearer " + os.environ.get("LAVA_API_KEY", "<YOUR_TOKEN>")}

def pull(code, flag, days=7):
    r = requests.get(BASE + "/opinions",
                     params={"ts_code": code, "days": days,
                             "only_this_stock": flag, "limit": 200},
                     headers=H, timeout=60).json()
    assert r["ok"], r["code"]
    d = r["data"]
    rows = d.get("list", [])
    return {"heat": d.get("heat"),
            "n": len(rows),
            "agencies": len({x.get("agency_id") for x in rows if x.get("agency_id")}),
            "server_time": r["meta"]["server_time"]}

print(pull("000000.SZ", 0))   # 示例代码
print(pull("000000.SZ", 1))

做 NLP 或要点归纳时，1 的文本更干净；做讨论广度统计时，0 更完整。无论选哪个，都应把取值写进笔记，否则同一只股票两天的列表条数无法比较。

七、时间区间：days 与 start_date / end_date

days 适合「最近 N 天」的滚动观察，start_date / end_date 适合事件复盘。两者不要同时随意混用：给了 start_date 后，days 不再生效。区间上限 92 天，超过会返回参数错误（非 2xx 不计费）。需要更长历史时，汇总数字改走日频面板 /panel/daily（get_stock_heat_panel，from/to 自然日、单次最多 20 个代码），意见文本则按 92 天分段拉取后以 opinion_id 去重合并。

示例：复盘某次公告前后各 10 天的讨论，可传 start_date=2026-10-20、end_date=2026-11-08（示例日期），再用 topic_time 把记录切成「公告前 / 公告后」两段。topic_time 是北京时间，切分点也应使用 Asia/Shanghai。

FAQ

Q：data.heat 为 0 且列表为空，是接口出错了吗？
A：不是。ok=true 且 data.heat.mentions 为 0、list 为空，表示在该参数下没有记录，应如实写成「该区间无消息面记录」，不要换参数反复重试来凑结果。

Q：一次调用会计费几次？
A：每次成功调用计 1 次，按文档单价每次 0.005 元；非 2xx 与查余额 get_account 不计费。读完汇总再读列表不需要额外调用。

Q：可以把多只股票的 /opinions 结果拼成全市场热榜吗？
A：不建议。全市场截面请直接用 /hot/stocks（get_market_hot_stocks），它有统一的 window、market 与 min_score 口径，自己拼的榜单很难保证时点一致。

结论

读 get_stock_news_heat 要分两层：data.heat 给出区间内的提及数与参与主体数，回答「热不热、多广」；data.list[] 给出带时间与匿名主体编号的摘要和要点，回答「在讨论什么」。参数上记住 days 默认 10、区间不超过 92 天、only_this_stock 默认 0、limit 默认 50；字段上记住 summary ≤120 字、detail ≤600 字、agency_score 是当前分。把这些口径写进笔记和 Agent 提示词，消息面热度就能被准确复述，而不会被改写成别的东西。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

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