企业官网建设流程全解析

Vibe-Trading 大宗交易数据工具get_block_trades实战指南：A 股折溢价与营业部席位解读

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

导读

本文聚焦 Vibe-Trading 内置的 A 股大宗交易（Block Trades）数据工具get_block_trades，完整讲解其数据来源、端点协议、输入输出参数、返回信封结构与实战调用方式。大宗交易是机构通过场外协议以相对当日收盘价折价或溢价成交的批量交易，逐笔记录中携带的成交价、折溢价率以及买卖双方营业部（"席位"）信息，是观察机构吸筹与派发行为的高价值披露面信号。读完本文，你将掌握如何用一行代码拉取任意 A 股个股近 365 天内的全部大宗交易明细，并理解 Vibe-Trading 如何通过共享限速层保障你在东财按源 IP 限流的约束下安全地批量使用该数据。

一、功能定位：A 股披露面的"折溢价观测窗口"

大宗交易（Block Trades）是 A 股特有的场外协议成交机制：大额持股方与受让方协商定价，绕过盘中连续竞价，以相对当日收盘价一定折价或溢价的价格批量交割。每笔交易在交易所披露系统中留痕，包含：

• 成交价与成交量/额：协议成交的实际价格与规模；
• 折溢价率：相对当日收盘价的偏离比例，是判断"大宗买入划算程度"的核心指标；
• 买卖双方营业部（席位）：挂单成交的券商营业部名称，可用于识别机构专用席位与游资席位。

Vibe-Trading 的get_block_trades工具（工具实现）将这一披露面数据封装为只读查询接口，供 Agent 在投研流程中直接调用，无需安装 SDK、无需申请 token。该工具的技能文档位于 大宗交易.md，是 Eastmoney 技能体系（SKILL.md）中"参考数据（披露面）"分类下与 融资融券、股东户数、限售解禁 并列的四类核心披露指标之一。

适用范围与边界

二、数据源与端点协议

工具底层直连东方财富 datacenter 报表接口，通过reportName = RPT_DATA_BLOCKTRADE拉取大宗交易明细：

https://datacenter-web.eastmoney.com/api/data/v1/get

端点查询参数在源码 block_trades_tool.py 中逐项构造：

两点实现细节值得注意：

1. 过滤用的代码是裸 6 位代码：filter中的SECURITY_CODE不带市场前缀（如600519），而对外入参接受带后缀的完整 symbol（如600519.SH）。工具内部先经resolve_secid校验，再剥离市场前缀组装过滤器（见 eastmoney_client.py）。
2. 单页 200 条上限：东财接口本身支持分页，但工具固定只拉第一页的 200 条，并通过days窗口约束总数据量，避免超大回看窗口撑爆 Agent 的上下文窗口——这是对上下文预算的显式保护（源码注释明确说明这一设计动机）。

三、工具入参与参数校验规则

输入参数

校验与容错逻辑（源码级）

• symbol 校验：code为空时返回{"ok": false, "error": "code is required"}；非 A 股 symbol（如00700.HK）返回错误信封并提示"use .SH/.SZ/.BJ"（测试用例）。
• 裸 6 位代码兼容：_resolve_code会通过_qualify_a_share将裸代码（如600519、000001）补全为带后缀的 A 股 symbol 再解析——该行为有专门回归测试锁定（test_block_trades_bare_code.py）。
• days参数 clamp：_clamp_days将任意输入强制收敛到 [1, 365]：缺失或非法值回退默认 30 天，小于 1 取 1，大于 365 取 365（源码 block_trades_tool.py）。days=99999会被 clamp 到 365，有测试验证（test_block_trades_tool.py）。
• 日期窗口：end取当日，start = end - (days - 1)，即days天窗口的闭区间。

四、返回结构与字段语义

工具返回 JSON 字符串信封，成功形态：

{ "ok": true, "market": "china_a", "source": "eastmoney", "data": { "code": "600519.SH", "days": 30, "count": 2, "records": [ ... ] } }

失败形态为{"ok": false, "error": "..."}，上游网络失败、HTTP 429 封禁等均被捕获为错误信封而非抛异常（测试用例）。

逐笔记录字段（源字段 → 输出键）

字段清洗：_to_float对空字符串与None一律映射为None，而非抛错中断——报表中部分记录的DEAL_PRICE/PREMIUM_RATIO可能缺失，测试明确覆盖了这一空值路径（test_block_trades_tool.py）。空数据窗口（如区间内无大宗交易）同样返回ok: true且count: 0，属于合法结果而非错误（test_block_trades_tool.py）。

五、调用范例与实战用法

最小调用

from src.tools.block_trades_tool import BlockTradesTool # 拉取贵州茅台近 30 日大宗交易 print(BlockTradesTool().execute(code="600519.SH", days=30))

解析信封的完整示例

技能仓库提供了披露面三路交叉验证的完整脚本 disclosure_example.py，其中大宗交易部分的解析模式如下：

import json from src.tools.block_trades_tool import BlockTradesTool def recent_block_trades(code: str, days: int = 30) -> None: envelope = json.loads(BlockTradesTool().execute(code=code, days=days)) if not envelope.get("ok"): print(f"大宗交易获取失败：{envelope.get('error')}") return records = envelope["data"].get("records", []) print(f"{code} 近 {days} 日大宗交易 {len(records)} 笔：") for rec in records[:3]: print( f" {rec['trade_date']} 价={rec['deal_price']} " f"折溢价={rec['premium_ratio']} 买方={rec['buyer_seat']}" )

该脚本演示了将get_block_trades与get_dragon_tiger（龙虎榜）、get_margin_trading（融资融券）组合使用的思路：三者同属披露面数据，交叉验证可以更立体地判断机构动向——例如某日大宗交易出现"机构专用"席位承接、同时龙虎榜出现同向净买入、融资余额同步抬升，则吸筹信号的一致性更高。

运行前提

• 在agent/目录下执行（导入根为agent/），无需 token；
• 所有请求经东方财富共享 IP 限速层节流。

六、限速层与调用纪律：为什么不能绕过工具裸请求

东财按源 IP限流，并会临时封禁突发请求。因此get_block_trades不自建 HTTP 会话，而是统一走共享的东财客户端（eastmoney_client.py）与 per-host 节流层（_http.py）：

• per-host 最小间隔：同一eastmoney桶内相邻请求至少间隔VIBE_TRADING_EASTMONEY_MIN_INTERVAL秒（默认 1.0 秒），可用环境变量调整；间隔之上还会叠加最多 0.4 秒的随机抖动，避免并发调用方"锁步齐射"；
• 会话复用：每个 host 桶复用进程级requests.Session，摊薄 TCP/TLS 建连开销；
• 进程内生效：节流是 best-effort 且进程本地，不跨机器协调；批量任务应调大对应*_MIN_INTERVAL环境变量。

技能文档 SKILL.md 明确划出红线：切勿绕过工具直接对东财端点发起裸 HTTP 突发请求。测试层也在这一点上做了验证——所有测试均在get_json处 mock，绝不触碰真实东财端点（test_block_trades_tool.py），这既是对测试稳定性的保障，也呼应了"必须经节流层访问"这一调用纪律。

七、Signal 解读：如何用折溢价与席位做投研观察

大宗交易数据的价值不在单条记录，而在结构化的观察方法：

1. 折溢价率判方向：持续折价成交（premium_ratio为负）通常意味着大股东或机构急于变现，折价幅度越大，短期抛压信号越强；罕见的溢价成交（premium_ratio为正）说明买方愿意付出溢价抢筹，常被解读为对后市的强烈看好。
2. 席位定身份：buyer_seat/seller_seat中出现"机构专用"字样，提示对手方是机构而非普通游资；结合龙虎榜席位与两融数据交叉验证，可显著提升对"吸筹/派发"判断的置信度。
3. 量价配合看力度：单笔成交额（deal_amount）与当日成交量的比值越大，说明该笔协议交易对筹码结构的影响越大；将多日记录串联，可以识别股东减持节奏与承接方连续建仓行为。

需注意：大宗交易折溢价、席位名称属于披露事实，但"机构吸筹/派发"的解读属于分析推断，应作为信号而非结论使用，最好与其他披露面（龙虎榜、两融）、量价数据共同验证。

八、测试与质量保障

get_block_trades的可靠性由两个测试文件覆盖：

• test_block_trades_tool.py：覆盖成功信封与字段归一化、空窗口零记录、daysclamp、缺失code、非 A 股拒绝、上游失败转错误信封六类场景；
• test_block_trades_bare_code.py：锁定裸 6 位 A 股代码（无后缀）也能正确解析的回归行为。

所有 HTTP 均在backtest.loaders.eastmoney_client.get_json处 mock，测试不依赖网络与真实数据，稳定可复现。

小结

get_block_trades是 Vibe-Trading Eastmoney 技能体系中定位精准的披露面只读工具：一条code+ 可选days即可获取个股全部大宗交易明细（价格、折溢价、量额、买卖席位），返回结构稳定、空值与错误均有明确信封语义。配合共享限速层的纪律性访问，它可以在东财 IP 限流约束下安全地支撑批量投研任务，是观察机构吸筹/派发行为的一线数据入口。

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