bigdata-skill

Bigdata.com SDK + REST 工具包

获取 Bigdata.com MCP 服务不会提供的结构化底层数据。MCP 会返回清晰的文本和预先合成的 tearsheet，但其搜索工具提供的分块没有逐块情绪或实体跨度，tearsheet 提供的也是聚合值，而不是可用于构建数据管道的财政期间时间序列、全市场筛选器或逐字段 JSON。官方 bigdata-client SDK 加上一个精简的 REST 直通层，通过同一后端、同一 JWT访问包含这些数据的官方 /v1/* 端点。此技能打包了一个能完成这些工作的工具包——已经调试完毕，也已加入成本保护——因此你无需再次付出探索成本。

此工具解决的核心问题（请先阅读）

Bigdata MCP 服务会用一段易读的文字或预先合成的 tearsheet 来回答“围绕 NVIDIA 的情绪如何？”，对于一次聊天来说确实很有用。但只要你需要构建数据管道所需的机器可读底层数据，MCP 就不会提供：

• 其搜索工具返回的分块只有文本和相关性——没有逐块情绪数值，也没有实体字符跨度；
• 其 tearsheet 提供的是聚合值（单个情绪评分、估算汇总），而不是可用于计算的财政期间时间序列、全市场筛选器或逐字段 JSON。

解决办法是一种通用模式，不是 Bigdata 特有的技巧：

当 MCP 数据源只返回合成后的输出，而你需要底层结构化字段时，请改用供应商 SDK 或 REST。 MCP 针对单次聊天进行优化，而不是针对数据管道。

关键在于，Bigdata 的这些结构化字段来自官方公开文档中列出的 REST 端点（docs.bigdata.com/api-reference/...），而不是隐藏的后端；并且 Bigdata 将于 2026-12-31 终止 SDK 支持（EOL），转而采用此 REST API，因此这里的 REST 层是面向未来的路径，而非权宜之计。SDK（bigdata_client.Bigdata）覆盖搜索和知识图谱；bd._api.http 可访问 SDK 未封装的所有 /v1/* 端点。随附的 bigdata_toolkit 将两者封装在一个 BigdataClient 后面。

何时使用此技能

遇到以下任一情况时，无论使用何种语言，均可触发：

• 用户正在使用 Bigdata.com / RavenPack，但觉得 MCP 结果太单薄——“情绪评分在哪？”、“我需要实体级数据”、“日历”。
• 他们需要某个股票代码的前瞻性／结构化财务数据：分析师预估、财报或事件日历、盈利惊喜、分析师评级、目标价、公司筛选器／全市场列表。
• 他们需要带有数字情绪值和实体跨度的已注释新闻分块，或情绪时间序列／共同提及图谱。
• 他们提到 bd_v2_ API 密钥、rp_entity_id、query_unit／分块成本、bigdata-client，或“bigdata MCP 不够用”。
• 他们正在构建投资研究数据集，需要可复用且考虑成本的数据提取层，而不是一次性的 MCP 调用。

设置（仅需一次）

1 — API 密钥（切勿硬编码）。 缺少密钥时，客户端会立即报错：

export BIGDATA_API_KEY=bd_v2_xxxxxxxx

2 — 独立的 Python 环境和官方 SDK。 随附工具包会导入 bigdata_client；安装一次即可：

uv venv .venv --python 3.12
uv pip install --python .venv/bin/python bigdata-client
# Behind a slow/blocked PyPI (e.g. mainland China) add a mirror, and unset any
# outbound proxy for the install step so uv reaches the index directly:
#   --index-url https://pypi.tuna.tsinghua.edu.cn/simple

3 — 出站代理（仅在网络需要通过代理访问 api.bigdata.com 时）。 有两种等效方式——官方 SDK 都支持：设置环境变量，或在代码中使用 BigdataClient(proxy=...)。环境变量是最简单的方式：

export HTTPS_PROXY=http://<host>:<port>     # plus WSS_PROXY for chat/WebSocket

如果代理会拦截 TLS（使用自签名 CA），且你遇到 SSL 握手错误，官方解决方法是 BigdataClient(verify_ssl="<proxy-CA>.pem")，而不是盲目重试。

4 — 让 Python 能导入随附的包，方法是将此技能的 scripts/ 添加到 PYTHONPATH（或使用 sys.path.insert(0, "<this-skill>/scripts")）。

对整个流程进行冒烟测试（实体解析和配额查询免费；--with-search 会额外执行一次约 1 query_unit 的分块搜索）：

BIGDATA_API_KEY=bd_v2_xxx PYTHONPATH=scripts .venv/bin/python scripts/probe_example.py

快速开始

import sys
sys.path.insert(0, "<this-skill>/scripts")          # so `import bigdata_toolkit` resolves
from bigdata_toolkit import (
    BigdataClient, EntityResolver, AnnotatedSearcher,
    StructuredDataREST, CostTracker, CostModel, rc,   # rc = SSL-retry wrapper
)

c  = BigdataClient()                                  # SDK + REST escape hatch, one object
er = EntityResolver(c)
nvda = rc(lambda: er.resolve_id("NVIDIA", country="US"))   # -> 'E09E2B'  (rp_entity_id is the gateway key)

# --- Structured financials the MCP does NOT expose (REST escape hatch) ---
rest = StructuredDataREST(c)
est  = rc(lambda: rest.analyst_estimates(nvda, period="quarter", limit=5))  # forward consensus
surp = rc(lambda: rest.latest_surprise(nvda))                               # last EPS/revenue surprise
cal  = rc(lambda: rest.events_calendar(nvda, categories=["earnings-call"],
                                       start_date="2026-06-01", end_date="2026-12-31"))

# --- Annotated chunks the MCP STRIPS: sentiment + entity spans (cost-guarded) ---
s    = AnnotatedSearcher(c)
docs = rc(lambda: s.search_entity(nvda, keyword="data center", chunk_limit=10))
# each chunk dict: {"sentiment": float, "entities": [{"key": rp_id, "start", "end"}], "text", ...}

# --- Always know your spend (chunk-billed; see Cost discipline) ---
ct = CostTracker(c); ct.snapshot()
# ... run a batch ...
print(ct.delta())     # {'delta_chunks':..., 'delta_query_units':..., 'usd_fast':...}

将每一个网络调用都封装在 rc(lambda: ...) 中——首次握手时出现 SSL: UNEXPECTED_EOF 很常见，SDK 的内部重试机制无法处理这种情况。

路由——根据问题选择对应能力

用户想要……	使用	模块
公司名称 / ISIN / CUSIP / SEDOL → rp_entity_id	EntityResolver.resolve_id / .resolve_by_isin	kg.py（SDK）
分析师前瞻共识（按财年期间划分的营收 / EPS）	StructuredDataREST.analyst_estimates	rest_ext.py
最新盈利意外（实际值与预估值的对比）	.latest_surprise	rest_ext.py
即将公布的财报 / 事件日历（单家公司或整个市场）	.events_calendar	rest_ext.py
分析师评级 / 目标价共识	.analyst_ratings / .price_target	rest_ext.py
完整财务报表（利润表 / 资产负债表 / 现金流量表，多年数据）	.income_statement / .balance_sheet / .cash_flow_statement	rest_ext.py
TTM 估值指标与比率（EV/EBITDA、ROE、P/E、利润率）	.key_metrics_ttm / .company_ratios_ttm	rest_ext.py
公司简介（CEO、行业、员工人数、IPO 日期）	.company_profile	rest_ext.py
每日 OHLC 价格 / 股息历史	.daily_prices / .dividends	rest_ext.py
按地理区域 / 产品细分的营收	.revenue_geographic_segments / .revenue_product_segments	rest_ext.py
每日实体情绪时间序列（不要自行汇总分块数据！）	.entity_sentiment	rest_ext.py
共现实体关系图（供应链 / 竞争对手 / 客户——⚠️ 按分块计费）	.connected_entities	rest_ext.py
按市值 / 行业 / 国家构建公司范围	.company_screener	rest_ext.py
带情绪和实体跨度的新闻 / 文件 / 文字记录分块	AnnotatedSearcher.search_entity	search.py（SDK）
批量执行多项搜索，节省 50% 费用（投资组合回填）	BatchSearch（创建→上传→轮询→下载）	rest_ext.py
回填前跟踪 / 预测配额支出	CostTracker / CostModel	cost.py
调用工具包尚未封装的端点	client.http.post("v1/<resource>/query", body)	client.py

income/balance/cash-flow/daily-prices/dividends/revenue-segments 返回 {fields, values}——使用 fields_values_to_records() 将其转换为 [{field: value}]。*_ttm / company_profile 端点返回的数据已经是扁平格式。 上述所有结构化端点均免费（0 个分块），但 connected_entities 和 AnnotatedSearcher 按分块计费。

两类数据面向（不要说“Bigdata 不支持中文 / A 股”）

这是最重要、但不易察觉的结论——请准确表述：

数据面向	路径	A 股 / 中文数据情况
结构化金融数据（预估、日历、意外、评级、目标价、筛选器、财务报表、价格、股息、营收细分、每日实体情绪）	REST（rest_ext.py）	可用——通过英文名称或 ISIN（而非中文名称）解析出的 rp_entity_id 获取。数据是最新的。存在少量缺漏（部分 A 股目标价会返回实体，但没有数值目标价）。每日 entity_sentiment 序列就在这里，适用于任何可解析的实体——它并非下文所述的死胡同。
非结构化中文 NLP（中文新闻实体检测、逐分块中文情绪）	SDK 搜索（search.py）	行不通——这是数据源层面的缺口，不是 SDK 缺陷：中文实体检测几乎为 0，逐分块的 CJK 情绪继承自文档级数值，而 language 会将中文文件误标为英文。对于中文语言的分块内容，应将 Bigdata 与中国本土数据源搭配使用；使用 Bigdata 获取结构化数据（包括汇总的 entity_sentiment）+ ISIN/KG 交叉映射 + 英文分块情绪。

成本控制

1 query_unit = 10 chunks（官方规定）。只有区块搜索会计费——结构化的 /v1/* 端点（估算值、财务数据、价格、日历、意外值、评级、情绪时间序列、筛选器……）免费（0 个区块，已通过合约测试）。connected_entities（共同提及）和 AnnotatedSearcher 会按区块计费。

支付区块费用时，有三个控制手段：

1. 使用 ChunkLimit，绝不使用裸 int。 Search.run(int) 的限制单位是文档，按整页区块计费；ChunkLimit(n) 则按区块计费。AnnotatedSearcher.search 会自动为你使用 ChunkLimit。（我们曾观察到约 52 倍的差距——这只是一次测量结果，并非官方文档中的说法；具体倍数仅供参考。无论如何，“使用 ChunkLimit”这一规则都成立，因为 max_chunks 才是官方计费单位。）
2. 重新排序只对返回的区块计费（官方规定）——传入 rerank_threshold，以广泛召回结果，但只为高相关性命中项付费。
3. 批量搜索可节省 50% 费用（每 qu 为 $0.0075，而非 $0.015）——进行大型多查询回填时使用 BatchSearch。

使用 CostModel 在运行前否决超出预算的任务，并使用 CostTracker.snapshot() / delta() 衡量实际支出。完整的计费说明见 references/cost_accounting.md。

已知陷阱（均已解决——不要重复排查）

每个陷阱都会耗费实际的调试时间，工具包中已修复或设有防护。完整的复现步骤和修复方案见 references/known_pitfalls.md：

1. 首次握手出现 SSL: UNEXPECTED_EOF → 使用 rc() 包装调用；SDK 的 urllib3 重试机制只涵盖 HTTP 状态码，不涵盖 SSL EOF。
2. All(entity, Keyword(kw)) 引发 TypeError → 使用 & 运算符组合（entity & Keyword(kw)）；All 接受单个可迭代对象。（已在 AnnotatedSearcher.entity_query 中修复。）
3. 52 倍的文档限制计费陷阱 → 始终使用 ChunkLimit，绝不使用裸 int。
4. 循环中的闭包捕获 → 绑定循环变量：rc(lambda q=q, dr=dr: ...)。
5. analyst_estimates(period="quarter") 在 limit≈20 以上返回 400 错误。
6. company_screener 的筛选条件必须嵌套在 "filters" 下——顶层平铺的键不会触发 400 错误，而是被静默丢弃 → 最终得到未筛选的全集。
7. Document.reporting_period 始终为 None（SDK 模型丢弃了 REST 响应中存在的字段）→ 使用 fetch_reporting_period_raw。

本技能不会做什么

• 绝不硬编码 API 密钥。 BigdataClient 会读取 BIGDATA_API_KEY，缺少该变量时立即报错——不会回退到明文密钥（秘密扫描器恰恰会捕捉这种模式）。
• 只读取——绝不写入或上传。 所有方法都是只读查询（在 API 密钥模式下，uploads 也会触发 NotImplementedError），因此工具包无法修改你的账户，也无法向任何地方推送数据。
• 绝不虚构端点或架构。 此处的每个签名都经过运行时 L4 验证，或标记为 L3（已通过文档确认，但尚未运行）；请参阅 references/verified_api_signatures.md。对于新端点，请通过 docs.bigdata.com/llms.txt 确认路径，不要猜测。

文件布局

bigdata-skill/
├── SKILL.md                       # this file — routing + setup + quickstart
├── scripts/
│   ├── bigdata_toolkit/           # the verified, cost-guarded package
│   │   ├── client.py              # BigdataClient: SDK (.bd) + REST escape hatch (.http/.conn)
│   │   ├── kg.py                  # EntityResolver: name/ISIN/CUSIP/SEDOL → rp_entity_id
│   │   ├── search.py              # AnnotatedSearcher: chunks + sentiment + entity spans (SDK)
│   │   ├── rest_ext.py            # StructuredDataREST (estimates/financials/prices/dividends/sentiment/co-mentions/screener) + BatchSearch + fields_values_to_records — official REST
│   │   ├── cost.py                # CostTracker + CostModel: chunk billing + budget veto
│   │   └── retry.py               # rc(): SSL/transient-error retry passthrough
│   └── probe_example.py           # runnable end-to-end smoke test
└── references/
    ├── escape_hatch_architecture.md  # WHY the MCP is lossy; bd._api.http mechanism; adding endpoints
    ├── verified_api_signatures.md    # L4/L3-verified signatures + the two data faces, with evidence
    ├── cost_accounting.md            # chunk billing, the 52x trap, CostModel/CostTracker, budgeting
    └── known_pitfalls.md             # every pitfall above, with reproduction + fix

参考资料

需要了解的内容……	文件
了解 *MCP 为何不足，以及 REST 逃生通道如何工作（以及如何封装新的 /v1/* 端点）	references/escape_hatch_architecture.md
查找经过验证的方法签名及其验证级别	references/verified_api_signatures.md
为回填任务制定预算，或排查意外的配额消耗	references/cost_accounting.md
诊断拉取数据时遇到的错误	references/known_pitfalls.md