finnhub_utils.py
封装 FinnHub 的行情与新闻接口。它负责把外部返回整理成上游能用的结构，字段完整度取决于你的 key 档位与该接口当时的可用性。
FinRobot 数据源 / AI4Finance-Foundation
FinRobot 数据源：FinnHub / FMP / SEC / yfinance 与 API Key
智能体的「感知」靠数据源喂数据。FinRobot 内置 FinnHub、FMP、SEC EDGAR、yfinance 与 finnlp 等接入，各自需要不同的 API Key 与权限；配错一个 key，链路往往不会报错，只是安静地给你一张空表。
FinnHub行情 / 新闻
FMP三大财报
SEC EDGAR申报文件
yfinance公开行情
4 大核心源FinnHub / FMP / SEC / yfinance
另有 finnlp金融 NLP 数据
Pro 增源Adanos / NewsAggregator / FX
范围美股为主
数据源对照
FinRobot 数据源对照表：每个源能拿到什么、要不要 key
各数据源的用途与 key 需求不同，按任务选择。判断列写清了「什么时候可以不用它」，方便你只配真正需要的那几个。
| 数据源 | 主要用途 | API Key 需求 | 什么时候可以不用 |
|---|---|---|---|
| FinnHub | 行情、公司新闻等 | FinnHub API Key（用行情/新闻时必填） | 只做财报与申报分析时可以跳过 |
| FMP（Financial Modeling Prep） | 利润表 / 资产负债表 / 现金流量表 | FMP API Key（做财报与估值时必填） | 不碰财务报表时可以跳过 |
| SEC EDGAR | 上市公司申报文件与公告线索 | 按 SEC 的访问要求配置（按需） | 不看申报原文时可以跳过 |
| yfinance | 公开行情数据 | 通常无需 key | 已用 FinnHub 取行情且更看重稳定性时 |
| finnlp | 金融 NLP 相关数据 | 按 finnlp 自身要求配置 | 任务不涉及文本/情绪时 |
| Pro 增源（Adanos / NewsAggregator / FX） | 官方 Pro 段落的扩展数据源 | 获取方式与价格以官方为准 | 开源版链路还没跑通时，先不要引入 |
| 自建 / 自定义源 | A 股等官方未内置的市场数据 | 取决于你接入的接口 | 只做美股研究时不需要 |
边界：FinRobot 的数据源以美股为主；官方未内置 A 股接口，A 股需自行适配数据源。具体支持范围以官方 README 与仓库中的 data_source 实现为准。
获取原理
数据源如何喂给智能体
数据源接入统一封装在 finrobot 包的 data_source 目录，由智能体的感知（Perception）环节调用；大脑（Brain）负责推理，行动（Action）负责调用工具与产出。所以「数据拿不到」通常表现为感知环节空转，而不是整条链路报错。
fmp_utils.py
封装 FMP 的财务数据接口，是财报类任务的入口。免费档可达的字段与历史区间存在差异，取不到时优先怀疑档位而不是代码。
sec_utils.py / yfinance_utils.py
分别封装 SEC 申报与 yfinance 公开行情。yfinance 走公开接口、通常无需 key，但稳定性与限流不受这个库控制，适合做验证，不适合作为单一依赖。
读法建议：把每个 utils 文件当作「一个源对应一条取数路径」；出现空结果时，先确认这条路径是否真的被调用到，再怀疑数据本身。具体文件名与函数名以官方仓库当前版本为准。
API Key
API Key 需求清单：哪些必须、哪些按需
没有对应 key，相应数据源就无法工作；而不同 key 的「必须程度」并不相同，先分清必需与可选，能少配一半。
| Key | 用途 | 是否必须 | 注意点 |
|---|---|---|---|
| LLM API Key（官方安装说明示例为 OpenAI） | 模型推理，智能体的大脑 | 必须 | 额度不足或认证失败时，链路会在推理环节中断 |
| FinnHub API Key | 行情与新闻类感知 | 做行情/新闻时必填 | 免费档与付费档的可用范围不同，以官方定价页为准 |
| FMP API Key | 财务报表数据 | 做财报与估值时必填 | 部分字段与历史区间可能需要更高档位 |
| SEC EDGAR 访问配置 | 读取申报文件 | 按需 | 访问方式与频率要求以 SEC 官方说明为准 |
| yfinance | 公开行情 | 通常不需要 | 无障碍免 key，但限流与稳定性不受这个库控制 |
| finnlp | 金融 NLP 数据 | 按需 | 配置要求以 finnlp 自身文档为准 |
| Pro 增源 key（Adanos / NewsAggregator / FX 等） | 扩展数据源 | 可选 | 属官方 Pro 能力，获取方式与价格以官方为准 |
安全提醒：key 只应放在本地配置或环境变量里，不要提交到仓库、不要贴进截图或 issue。首次配置时先确认要跑的任务到底需要哪几个源，再逐个补齐。
成本结构
这些数据源要花多少钱：key 成本与免费档对照
官方 README 只列 key 名，不告诉你哪些能免费用、免费档会卡在哪里。下面这张表把「要不要钱、免费档能做什么、低成本怎么起步」摊开（具体价格与额度以各家官方定价页为准，本站不转述数字）。
| 项目 | 是否必须 | 免费档情况 | 计费形态 | 免费档的典型卡点 | 低成本起步建议 |
|---|---|---|---|---|---|
| 库本体 | 必须 | 开源免费（Apache-2.0） | 不按调用计费 | 无 | 直接按官方安装说明装好即可 |
| LLM API（安装说明示例为 OpenAI） | 必须 | 是否有试用额度以官方定价页为准 | 按用量计费，以官方定价页为准 | 额度用尽时推理环节直接失败 | 先用小样本、短链路跑通再放量 |
| FinnHub API Key | 做行情/新闻时必填 | 通常提供免费档，具体额度以官方为准 | 免费档 + 付费档 | 免费档容易在调用频率上受限，超限时可能返回空结果 | 先用免费档验证「能不能取到」，再决定是否升级 |
| FMP API Key | 做财报/估值时必填 | 通常提供免费档，字段范围以官方为准 | 免费档 + 付费档 | 部分报表字段或较长历史区间在免费档不可用 | 只取研报真正用到的那几张表 |
| SEC EDGAR | 按需 | 属公开申报数据，访问要求以 SEC 官方说明为准 | 通常不按调用收费 | 高频访问可能被要求降速 | 只在需要申报原文时调用，并做本地缓存 |
| yfinance | 可选 | 通常无需 key | 无 key 计费 | 公开接口的限流与可用性不受这个库控制 | 拿它做链路验证，正式研报再换稳定源 |
| Pro 增源（Adanos / NewsAggregator / FX） | 可选 | 属官方 Pro 能力，以官方为准 | 以官方为准 | 开源版用户通常用不到 | 等开源链路稳定、确有需求再评估 |
一句话结论：软件本身免费，真正的成本在「LLM 调用量 + 需要付费档的数据源」。先用免费档把链路跑通、把调用量压到最小，是控制成本更稳妥的顺序；各家额度与价格随时可能调整，请以官方定价页为准。
配置步骤
把 key 配到位：五步配置与验证
每步都写清「做什么、为什么、预期看到什么」。做完这五步，你应该能明确回答：哪个源真的通、哪个源虽然配了但没生效。
步骤一：建独立环境并激活
官方安装说明以 conda 为例，要求 Python 3.10。
conda create -n finrobot python=3.10建环境，conda activate finrobot激活。预期输出：命令行提示符前出现环境名；python -V显示对应版本。步骤二：按官方说明安装 FinRobot
依官方 README 给出的方式安装（pip 装包或从源码目录安装）。预期输出：安装过程正常结束，之后执行
python -c "import finrobot"不报错——这一步只证明包能导入，不证明数据能取到。步骤三：填入 LLM 与数据源 key
把 LLM key 与各数据源 key 写进项目配置（本站现有内容写作
config_api_keys，确切文件名与字段名以官方 README 与示例 notebook 为准）。预期输出：配置文件无占位串、无多余空格；不要把真实 key 提交到仓库。步骤四：逐个源做最小验证
用一个官方示例里的美股大盘股，分别只调用一个源，打印返回行数与列名，而不是直接跑完整研报。预期输出：非空结果 + 你认识的列名；若为空，先按下面的「key 填了却没生效」排查，再去怀疑标的本身。
步骤五：确认「实际读到的 key」是哪一个
在代码里打印每个源是否读到 key（只打印是否存在与长度，不要打印 key 本身），并记录本次跑通的 key 组合。预期输出：每个源都能明确回答「有 / 没有」；两处配置冲突时，这一步能立刻暴露。
排查
key 填了却没生效：七类常见原因
这类问题最费时间的地方在于「它不报错」。下面按排查顺序排列，从「key 本身」到「环境与档位」，每类都给出确认方法。
| 现象 | 怎么确认 | 处理 | 注意点 |
|---|---|---|---|
| 配置里还是占位符或空串 | 打开配置文件，看是否有示例占位串或空值 | 换成真实 key，去掉首尾引号与空格 | 复制 key 时最容易带上空格，肉眼很难发现 |
| 填到了另一份配置文件 | 确认运行时代码实际读取的是哪一份文件 | 只保留一处配置；notebook 里注意当前工作目录 | notebook 的工作目录常与项目根不一致 |
| 环境变量与配置文件冲突 | 在代码里打印「实际读到的值是否存在」（不打印内容） | 固定一种配置来源，避免两处并存 | 排查时要防止把 key 打到日志里 |
| 该源需要付费档才有你要的数据 | 用该源的最小样例单独调一次，看返回字段是否齐全 | 确认字段/历史区间是否属于更高档位 | 「能连通」不等于「字段都能拿到」 |
| key 有效但被限流 | 隔一段时间或降低调用频率后重试同一请求 | 加本地缓存、减少重复调用 | 限流常表现为「返回空」而不是报错 |
| 权限或市场不匹配 | 换一个官方示例里的美股大盘股再试同一路径 | 先确认标的属于该源覆盖的市场 | 官方数据源以美股为主，A 股需自行适配 |
| 环境和包的问题（key 其实没问题） | 确认当前内核/解释器能导入项目包 | 重新激活环境或修正 notebook 内核 | 命令行能跑、notebook 不能跑，通常是内核不同 |
顺序建议：先证明单个源能取到数，再把它接回智能体链路。反过来做（先跑端到端再回头查），会把「源的问题」和「编排的问题」混在一起，排查成本明显更高。
任务矩阵
按任务配源：六类研究任务要配哪些数据源
与其把所有 key 都申请一遍，不如按任务配最小集合。下表给的是「至少」而不是「最多」。
| 想做的分析 | 至少要配的源 | 关键 key | 可选的补充源 | 注意点 |
|---|---|---|---|---|
| 三大报表与财务比率 | FMP | FMP API Key | SEC EDGAR（核对申报原文） | 免费档的字段范围以官方为准 |
| 行情与技术面 | FinnHub 或 yfinance | 用 FinnHub 时需要其 key | 另一个源做交叉验证 | yfinance 通常无需 key，但稳定性不受这个库控制 |
| 申报文件与公告线索 | SEC EDGAR | 按 SEC 访问要求配置 | FMP | 主要覆盖美股申报，非美股市场需自行适配 |
| 新闻与文本情绪 | FinnHub（新闻）或 finnlp | FinnHub API Key | Pro 增源（NewsAggregator） | 情绪类结论建议人工复核后再用 |
| 估值（DCF/DDM/LBO/WACC 等） | FMP + FinnHub | 两个 key 都要 | SEC EDGAR | 估值数字由确定性算子计算，模型只负责叙述 |
| 端到端多智能体研报 | LLM + FMP + FinnHub | 三者都要 | SEC EDGAR / finnlp | 缺一个 key 时链路可能静默降级，产出仍会生成 |
市场边界
市场覆盖：为什么这套数据源偏美股
把覆盖范围和缺口一起看清，选型时才不会装完才发现数据对不上。
美股：覆盖充分
FMP、FinnHub、SEC EDGAR 与 yfinance 对美股与美股申报覆盖较完整，是官方示例的主要场景，也是这套链路最容易跑通的地方。
A 股：官方未内置
官方没有内置 A 股数据源，想在 A 股上复用这套智能体链路，需要自行适配数据接口，并且要接受部分字段口径的差异，工作量不能低估。
其他市场：需自行适配
港股、非美市场同样不在默认范围内。若目标就是这些市场，可先确认本机已核验的金融研究技能路线是否已覆盖，再决定要不要自建适配层。
边界披露：FinRobot 与 EasyClaw 无已证实集成，两边是相互独立的路线；本页只做数据源与配置层面的说明，不构成投资建议。具体数据覆盖范围以官方 README 与仓库实现为准。
FAQ
FinRobot 数据源常见问题
FinRobot 支持 A 股数据吗？
官方数据源以美股为主；A 股需自行适配数据源，官方未内置 A 股接口。若以 A 股为主，可先评估本机已核验的金融研究技能路线，再决定是否投入适配工作。以官方 README 为准。
yfinance 需要 key 吗？
通常无需 key，但它走公开接口，限流与可用性不受这个库控制，适合做链路验证，不适合作为单一数据依赖。以官方仓库的 data_source 实现为准。
数据源返回为空怎么办？
按「key 填了却没生效」的顺序排查：占位符 → 配置文件位置 → 环境变量冲突 → 档位不足 → 限流 → 标的市场。常见表现是既不报错也不返回数据。以官方 README 为准。
能只用一个数据源吗？
可以按需配置，但完整研报通常需要 FMP（财报）与 FinnHub（行情/新闻）配合；端到端链路缺 key 时可能静默降级。以官方示例 notebook 为准。
这些数据源要花钱吗？
项目本体是 Apache-2.0 开源，免费；但 LLM API 与部分数据源可能需要付费档，费用按各家官方定价页结算。免费档的字段范围与额度也以官方为准。
怎么安全保存这些 key？
只放在本地配置或环境变量里，不要提交到仓库，也不要贴进截图、日志或 issue；排查时打印「是否存在」而不是打印 key 内容。具体读取方式以官方 README 与示例为准。