Vibe-Trading 券商研报与一致预期 EPS 工具 `get_research_reports` 实战指南

Vibe-Trading 券商研报与一致预期 EPS 工具get_research_reports实战指南

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading

券商研报 + 一致预期 EPS（Research Reports）是 Vibe-Trading 中面向 A 股卖方的免费免鉴权舆情数据通道：它把东方财富reportapi的滚动券商研报列表与同花顺（THS）的市场一致预期 EPS 拼接进同一个 JSON 信封，供 Agent 在基本面研究、盈利预测对照与评级分布统计中使用。读完本文，你将掌握该工具的调用方式、全部入参与返回字段、底层双数据源拼接逻辑与 per-host 节流机制，并能在自己的分析脚本中直接复用。

本文以技能文档 券商研报.md 为主体骨架，结合其实现源码 research_reports_tool.py、底层节流层 _http.py 与测试 test_research_reports_tool.py 展开讲解。

工具定位与双数据源架构

工具名get_research_reports，实现类为src.tools.research_reports_tool.ResearchReportsTool（继承src.agent.tools.BaseTool）。它的核心设计是把两路免费、免鉴权的披露接口"拼成一个信封"：

• 东财 reportapi（主源）：返回 A 股滚动券商研报列表——标题、发布机构、分析师、发布日、机构评级标签，以及该机构给出的分年度 EPS / PE 预测。这一路驱动返回信封中的reports块。
• 同花顺 THS（basic.10jqka.com.cn，best-effort 辅源）：返回市场一致预期EPS，即全体分析师估计值的均值，按前瞻财年给出。该块驱动consensus_eps块。

两个端点分别为：

两个端点常量定义在 research_reports_tool.py 中（_REPORT_LIST_URL/_THS_CONSENSUS_URL）。

需要特别说明的是 THS 的接入细节：THS 拒绝裸requestsUA（即没有浏览器标识的默认 UA 会被拒），因此工具调用时携带桌面 UA 与Referer: https://basic.10jqka.com.cn/，并走独立thshost bucket 节流（见下文"限速机制"一节）。同时 THS 块被设计为best-effort：一旦 THS 请求失败，consensus_eps降级为空列表，绝不中断东财研报抓取。

市场范围

工具仅覆盖A 股（.SH/.SZ/.BJ后缀）。任意其他市场代码（如AAPL.US）会在发出任何 HTTP 请求之前直接返回错误信封，这一行为在测试 test_research_reports_tool.py 中有明确验证。

输入参数说明

工具入参定义在类的parameters字段（research_reports_tool.py），其中beginTime/endTime是源码相对原文档新增的可选参数：

参数处理在execute中逐项落实：

• code会先strip().upper()归一化，随后校验交易所后缀并调用resolve_secid确认代码可解析（research_reports_tool.py）。
• limit经_clamp_limit强制收敛到1..50，非法值回退默认 20（research_reports_tool.py）。
• 日期参数beginTime/endTime必须是合法YYYYMMDD字符串，否则返回错误；默认窗口为近两年（now - timedelta(days=730)），且同时满足"东财要求必须显式携带窗口否则返回 HTTP 400"的硬性约束（测试 test_research_reports_tool.py 用冻结时间验证了默认窗口beginTime=20240813 / endTime=20260813会被真实下发）。
• 一个值得注意的防御逻辑：若beginTime > endTime（窗口倒置），东财会返回 HTTP 200 且零命中，工具会因此误报"该公司没有研报覆盖"——这是关于公司的错误陈述而非关于请求的错误。因此源码在发出请求前就拦截倒置窗口并返回明确错误（research_reports_tool.py，测试见 test_research_reports_tool.py）。

端点查询参数

• reportapi：code=<裸代码>（去后缀，如600519）、qType=0（个股研报）、pageSize=<limit>、pageNo=1，外加必带的beginTime/endTime（%Y%m%d形式）。
• THS：code=<裸代码>；headers 携带桌面User-Agent+Referer: https://basic.10jqka.com.cn/。

裸代码提取由_bare_code完成（code.rpartition(".")[0]，research_reports_tool.py），测试断言东财与 THS 收到的params["code"]均为去后缀的"600519"（test_research_reports_tool.py）。

返回字段与信封结构

成功时返回 JSON 信封：

{ "ok": true, "market": "CN", "source": "eastmoney+ths", "data": { "code": "600519.SH", "reports": [...], "consensus_eps": [...] } }

失败时返回{"ok": false, "error": "..."}。字段映射发生在_normalize_report与_parse_consensus_eps中。

reports（东财源字段 → 输出键）

注意：brokerage与rating均采用"首选字段为空则回退次选字段"的策略（orgSName优先于orgName，emRatingName优先于sRatingName）；publish_date由_clean_date截断时间戳到日期部分（如2024-04-30 08:00:00→2024-04-30）；数值字段经_to_number转为float，无法解析则为None。无 title 且无 publish_date 的研报行被直接丢弃（research_reports_tool.py），单行坏数据不会中断整批解析。

consensus_eps（THS，字段名多变，按 alias 探测）

THS 返回行的字段命名不稳定，因此_parse_consensus_eps借助_first按给定 key 顺序探测第一个非空值（research_reports_tool.py）。测试中 THS 载荷使用year/eps形式，被正确映射为{"fiscal_year": "2024", "consensus_eps": 12.1}（test_research_reports_tool.py）。

数据丢失防护

在reports与consensus_eps同时为空时才返回"no research coverage found"错误信封；只要有一路有数据即视为成功（research_reports_tool.py）。

调用范例

原文档给出的最小调用方式：

from src.tools.research_reports_tool import ResearchReportsTool print(ResearchReportsTool().execute(code="600519.SH", limit=10))

支持可选窗口参数的完整调用（工具描述字段中的示例）：

from src.tools.research_reports_tool import ResearchReportsTool print( ResearchReportsTool().execute( code="600519.SH", limit=10, beginTime="20240101", endTime="20261231", ) )

完整可运行示例可参考技能脚本 fundamentals_example.py：它在broker_consensus函数中把信封解析为 JSON，汇总近 N 篇研报的评级列表，并打印一致预期 EPS，与股东户数、跨市场财报工具组合成一条"基本面 + 舆情"研究流水线。运行前提是在agent/目录下执行（导入根为agent/），无需 token。

限速机制：共享 per-host 节流层

东财与 THS 都按源 IP 限流并会临时封禁突发请求，因此两个端点绝不裸连，统一走共享节流层backtest.loaders._http.throttled_get：

• 东财请求经eastmoney_client.get_json→throttled_get_json，使用eastmoneyhost bucket（eastmoney_client.py）。
• THS 请求显式传入host_key="ths"，min_interval由resolve_min_interval读取环境变量VIBE_TRADING_THS_MIN_INTERVAL，默认 1.0 秒（research_reports_tool.py）。

节流实现（_http.py）是一个进程级HostThrottle门：同 bucket 的相邻请求至少间隔min_interval秒，并叠加 0～0.4 秒随机抖动防止并发 worker 齐步走；每个 bucket 复用独立requests.Session，摊销 TCP/TLS 建连成本。源码模块 docstring 明确说明：不要绕过工具对端点发起裸 HTTP 突发请求，批量任务可通过调大*_MIN_INTERVAL环境变量放宽间距（_http.py）。

对东财整体还可使用技能文档 SKILL.md 中提到的VIBE_TRADING_EASTMONEY_MIN_INTERVAL（默认 1.0 秒）调整最小请求间隔。环境变量解析由positive_env_float（base.py）完成：非法或非正数会被告警并回退默认值。

错误处理与鲁棒性设计

工具对三类故障采用不同策略，全部体现在测试用例中：

1. 入参错误（不发出任何 HTTP）：缺code、非 A 股后缀、非法日期、倒置窗口均在请求前返回{"ok": false, ...}，测试断言get_json与throttled_get均未被调用（如 test_research_reports_tool.py）。
2. 东财失败（致命）：get_json抛异常被捕获并包装为错误信封，错误信息含原始异常文本（测试用HTTP 429验证，test_research_reports_tool.py）。
3. THS 失败（best-effort 降级）：网络异常或非 2xx 状态都只记日志并把consensus_eps降级为空列表，reports不受影响，信封仍为ok: true（测试见 test_research_reports_tool.py）。

此外，由于 THS 的 UA 与 Referer 策略、字段 alias 探测都属于"实现事实"，跨 provider 的字段差异若发生变化，应以 research_reports_tool.py 当前实现为准。

在 Vibe-Trading 中的使用场景

从技能目录结构与脚本示例可以推断，get_research_reports主要服务以下研究场景：

• 评级分布统计：汇总近 N 篇研报的rating列表，观察机构对该标的的多空倾向；
• 盈利预期对照：将各机构的eps_forecast/pe_forecast与 THS 的consensus_eps均值对照，识别乐观/保守的券商，或发现一致预期与股价走势的背离；
• 基本面交叉验证：如 fundamentals_example.py 所示，与股东户数趋势、跨市场财务指标组合，形成"披露面 + 舆情面 + 基本面"的研究闭环。

该工具已注册为 Vibe-Trading 的标准工具，Agent 可直接以get_research_reports名调用；对东财技能下资金面、龙虎榜、参考数据等其他工具的完整清单，可查阅 SKILL.md 的接口列表一节。

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading