Vibe-Trading 券商研报与一致预期 EPS 工具get_research_reports实战指南【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading券商研报 一致预期 EPSResearch 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块。同花顺 THSbasic.10jqka.com.cnbest-effort 辅源返回市场一致预期EPS即全体分析师估计值的均值按前瞻财年给出。该块驱动consensus_eps块。两个端点分别为块端点 URLreports东财https://reportapi.eastmoney.com/report/listconsensus_epsTHShttps://basic.10jqka.com.cn/api/stock/profit_forecast/两个端点常量定义在 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是源码相对原文档新增的可选参数名称类型必选描述codestrYcode.exchange形式后缀 SH / SZ / BJ如600519.SH。limitintN返回最近研报数上限1–50默认 20。beginTimestrN研报发布日下界含YYYYMMDD形式如20240101默认近两年窗口起点。endTimestrN研报发布日上界含YYYYMMDD形式如20261231默认今天。参数处理在execute中逐项落实code会先strip().upper()归一化随后校验交易所后缀并调用resolve_secid确认代码可解析research_reports_tool.py。limit经_clamp_limit强制收敛到1..50非法值回退默认 20research_reports_tool.py。日期参数beginTime/endTime必须是合法YYYYMMDD字符串否则返回错误默认窗口为近两年now - timedelta(days730)且同时满足东财要求必须显式携带窗口否则返回 HTTP 400的硬性约束测试 test_research_reports_tool.py 用冻结时间验证了默认窗口beginTime20240813 / endTime20260813会被真实下发。一个值得注意的防御逻辑若beginTime endTime窗口倒置东财会返回 HTTP 200 且零命中工具会因此误报该公司没有研报覆盖——这是关于公司的错误陈述而非关于请求的错误。因此源码在发出请求前就拦截倒置窗口并返回明确错误research_reports_tool.py测试见 test_research_reports_tool.py。端点查询参数reportapicode裸代码去后缀如600519、qType0个股研报、pageSizelimit、pageNo1外加必带的beginTime/endTime%Y%m%d形式。THScode裸代码headers 携带桌面User-AgentReferer: https://basic.10jqka.com.cn/。裸代码提取由_bare_code完成code.rpartition(.)[0]research_reports_tool.py测试断言东财与 THS 收到的params[code]均为去后缀的600519test_research_reports_tool.py。返回字段与信封结构成功时返回 JSON 信封{ ok: true, market: CN, source: eastmoneyths, data: { code: 600519.SH, reports: [...], consensus_eps: [...] } }失败时返回{ok: false, error: ...}。字段映射发生在_normalize_report与_parse_consensus_eps中。reports东财源字段 → 输出键源字段输出键描述titletitle研报标题orgSName / orgNamebrokerage发布机构简称优先researcheranalyst分析师publishDatepublish_date发布日取YYYY-MM-DDemRatingName / sRatingNamerating机构评级predictThisYearEps / predictNextYearEpseps_forecast.this_year / .next_year分年度 EPS 预测predictThisYearPe / predictNextYearPepe_forecast.this_year / .next_year分年度 PE 预测注意brokerage与rating均采用首选字段为空则回退次选字段的策略orgSName优先于orgNameemRatingName优先于sRatingNamepublish_date由_clean_date截断时间戳到日期部分如2024-04-30 08:00:00→2024-04-30数值字段经_to_number转为float无法解析则为None。无 title 且无 publish_date 的研报行被直接丢弃research_reports_tool.py单行坏数据不会中断整批解析。consensus_epsTHS字段名多变按 alias 探测输出键来源 alias描述fiscal_yearyear / fiscal_year / report_year前瞻财年consensus_epseps / avg_eps / predict_eps / forecast_eps一致预期 EPS均值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(code600519.SH, limit10))支持可选窗口参数的完整调用工具描述字段中的示例from src.tools.research_reports_tool import ResearchReportsTool print( ResearchReportsTool().execute( code600519.SH, limit10, beginTime20240101, endTime20261231, ) )完整可运行示例可参考技能脚本 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 bucketeastmoney_client.py。THS 请求显式传入host_keythsmin_interval由resolve_min_interval读取环境变量VIBE_TRADING_THS_MIN_INTERVAL默认 1.0 秒research_reports_tool.py。节流实现_http.py是一个进程级HostThrottle门同 bucket 的相邻请求至少间隔min_interval秒并叠加 00.4 秒随机抖动防止并发 worker 齐步走每个 bucket 复用独立requests.Session摊销 TCP/TLS 建连成本。源码模块 docstring 明确说明不要绕过工具对端点发起裸 HTTP 突发请求批量任务可通过调大*_MIN_INTERVAL环境变量放宽间距_http.py。对东财整体还可使用技能文档 SKILL.md 中提到的VIBE_TRADING_EASTMONEY_MIN_INTERVAL默认 1.0 秒调整最小请求间隔。环境变量解析由positive_env_floatbase.py完成非法或非正数会被告警并回退默认值。错误处理与鲁棒性设计工具对三类故障采用不同策略全部体现在测试用例中入参错误不发出任何 HTTP缺code、非 A 股后缀、非法日期、倒置窗口均在请求前返回{ok: false, ...}测试断言get_json与throttled_get均未被调用如 test_research_reports_tool.py。东财失败致命get_json抛异常被捕获并包装为错误信封错误信息含原始异常文本测试用HTTP 429验证test_research_reports_tool.py。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-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考