ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

Vibe-Trading 限售解禁数据工具实战:基于 Eastmoney RPT_LIFT_STOCK 的个股解禁历史与全市场解禁日历查询

Vibe-Trading 限售解禁数据工具实战:基于 Eastmoney RPT_LIFT_STOCK 的个股解禁历史与全市场解禁日历查询 Vibe-Trading 限售解禁数据工具实战基于 Eastmoney RPT_LIFT_STOCK 的个股解禁历史与全市场解禁日历查询【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading导读限售股解禁Lockup Expiry / Restricted-Share Unlock是 A 股投资者必须跟踪的披露面事件大额临近解禁会为市场新增可流通供给往往对股价形成压制。Vibe-Trading 通过内置工具get_lockup_expiry封装东方财富Eastmoney免费免鉴权的数据中心接口一条调用即可获取个股全历史解禁表或全市场未来 N 日解禁日历。读完本文你将掌握该工具的参数约定、端点查询结构、返回信封格式以及其底层源码实现与限速保护机制可直接在量化研究与交易决策中接入使用。一、工具定位A 股披露面数据链中的限售解禁模块在 Vibe-Trading 的东财Eastmoney技能体系中get_lockup_expiry属于「参考数据披露面」分组与get_margin_trading融资融券、get_block_trades大宗交易、get_shareholder_count股东户数并列见 eastmoney 技能索引。该工具的核心价值在于两点个股维度返回某只 A 股的全历史解禁时间表可用于回溯历史上每次解禁前后的价格表现评估解禁事件对个股的冲击规律市场维度返回全市场未来一段时间默认 90 日的解禁日历可用于在组合层面提前规避解禁密集区、识别供给压力集中的窗口。从代码注释看其设计动机被明确表述为a large upcoming unlock can pressure a stock as newly tradable supply hits the market临近的大额解禁会因新增可流通供给而压制股价见 lockup_expiry_tool.py。二、工具基本属性与限速红线属性值工具名get_lockup_expiry实现类src.tools.lockup_expiry_tool.LockupExpiryTool市场A 股端点https://datacenter-web.eastmoney.com/api/data/v1/get报表名reportNameRPT_LIFT_STOCK可重复调用repeatable True只读is_readonly Truerepeatable True意味着在一次会话/流程中该工具可被多次调用例如遍历多只个股其基类语义定义于 BaseTool。is_readonly True表明该工具只读取外部数据、不产生任何订单或写操作适合安全地接入研究流程。限速红线东财按源 IP限流并对突发请求临时封禁。所有东财系工具内部都经过共享 per-host 节流层backtest.loaders._http不得绕过工具直接对端点裸发 HTTP 突发请求。最小请求间隔默认 1.0 秒可通过环境变量VIBE_TRADING_EASTMONEY_MIN_INTERVAL调整见 SKILL.md 限速说明。三、输入参数code 与 horizon_days 双模式名称类型必选描述codestr否A 股 6 位代码可带后缀600519/600519.SH/000001.SZ。给定 → 返回该股全历史解禁表省略 → 返回全市场未来 N 日解禁日历。horizon_daysint否全市场日历的未来窗口天数clamp 至 [1, 365]默认 90。给定code时该参数被忽略返回全历史。两个参数的底层处理逻辑在源码中有明确实现1. 代码规范化_normalize_code工具接受600519、600519.SH、000001.SZ等形式统一剥离交易所后缀后提取纯 6 位数字代码因为东财报表以裸数字代码为键。若传入非 6 位数字代码如AAPL.US返回规范化失败见 lockup_expiry_tool.py。2. 窗口钳制_clamp_horizonhorizon_days会先强制转为 int非法输入TypeError / ValueError / OverflowError回退默认值 90小于 1 的钳为 1大于 365 的钳为 365见 lockup_expiry_tool.py。同时测试用例确认horizon_days99999最终返回 365见 test_lockup_expiry_tool.py。此外工具对整数类型代码也做了兼容execute(code600519)非字符串不会因.strip()抛AttributeError相关回归测试见 test_lockup_expiry_integer_code.py。四、端点查询参数RPT_LIFT_STOCK 报表的请求构造工具向东财数据中心端点发出 GET 请求携带以下查询参数名称取值描述reportNameRPT_LIFT_STOCK报表名columnsSECURITY_CODE,SECURITY_NAME_ABBR,FREE_DATE,FREE_SHARES_TYPE,FREE_SHARES,CURRENT_FREE_SHARES,ABLE_FREE_SHARES,LIFT_MARKET_CAP,FREE_RATIO,TOTAL_RATIO请求列filter个股(SECURITY_CODEcode)全市场(FREE_DATEstart)(FREE_DATEend)过滤谓词sortColumns/sortTypesFREE_DATE/ 个股-1最新在前、全市场1最近解禁在前排序pageNumber/pageSize1/200分页source/clientWEB/WEB来源标识filter 构造细节源码_build_filter见 lockup_expiry_tool.py个股模式filter(SECURITY_CODE600519)不加日期边界——请求该代码的全历史解禁记录全市场模式filter(FREE_DATE2026-09-09)(FREE_DATE2026-12-08)窗口以当日UTC 日期为起点、当日 horizon_days为终点两端均闭区间日期格式为YYYY-MM-DD。排序细节源码_select_sort见 lockup_expiry_tool.py个股全历史按FREE_DATE倒序-1最新解禁排在最前便于直接看到下一次解禁全市场日历按FREE_DATE正序1即将发生的解禁排在最前让最近的供给冲击一目了然。上下文保护虽然东财pageSize允许较大数值但工具将返回记录硬性截断在_MAX_RECORDS 200条_PAGE_SIZE 200防止全市场查询的返回体淹没 Agent 上下文窗口见 lockup_expiry_tool.py。五、返回字段与信封格式5.1 字段映射源字段 → 输出键源字段输出键类型描述SECURITY_CODEcodestr代码SECURITY_NAME_ABBRnamestr简称FREE_DATEfree_datestr解禁日取YYYY-MM-DDFREE_SHARES_TYPEshare_typestr解禁股份类型如「首发原股东限售股份」FREE_SHARESfree_sharesfloat解禁股数ABLE_FREE_SHARESable_free_sharesfloat实际可流通股数LIFT_MARKET_CAPlift_market_capfloat解禁市值FREE_RATIOfree_ratiofloat占流通股比TOTAL_RATIOtotal_ratiofloat占总股本比实现上_shape_record负责将东财报表行投影为紧凑记录缺失SECURITY_CODE或FREE_DATE的行被直接丢弃数值字段free_shares、lift_market_cap、free_ratio、total_ratio等经_to_float容错转换缺失或非法值返回None而非抛错见 lockup_expiry_tool.py。5.2 响应信封成功响应统一为 JSON 字符串信封{ ok: true, market: a_share, source: eastmoney, data: { scope: single_code | market_calendar, count: 200, records: [ ... ], code: 600519, // 仅 single_code 模式 horizon_days: 90, // 仅 market_calendar 模式 as_of: 2026-09-09, // 仅 market_calendar 模式数据基准日 truncated: true // 仅当记录数触顶 200 时出现 } }scope single_code时携带code字段scope market_calendar时携带horizon_days与as_of数据基准日即查询当日当返回记录数达到 200 上限时置truncated: true提醒调用方数据可能不完整见 lockup_expiry_tool.py失败时返回{ok: false, error: ...}信封上游任何异常都会被捕获并转为可读错误信息见下文第七节。六、调用范例Python 直接调用与 MCP 接入6.1 通过工具类直接调用原文档给出的最简调用方式见 限售解禁.mdfrom src.tools.lockup_expiry_tool import LockupExpiryTool # 个股全历史解禁示例贵州茅台 print(LockupExpiryTool().execute(code600519.SH)) # 全市场未来 30 日解禁日历 print(LockupExpiryTool().execute(horizon_days30))补充说明execute内部将参数透传给底层函数get_lockup_expiry(code, horizon_days)horizon_days缺省时取默认值 90见 lockup_expiry_tool.py建议把返回的 JSON 字符串用json.loads解析后使用方便结构化处理data.records列表该工具不依赖任何token或鉴权配置只需网络可达东财接口即可。6.2 通过 MCP 服务器调用get_lockup_expiry已注册进 Vibe-Trading 的 MCP 服务器签名与工具类一致get_lockup_expiry(code: str | None None, horizon_days: int 90) - str见 mcp_server.py。这意味着具备 MCP 能力的 Agent / LLM 客户端可以直接将其作为函数工具调用无需编写 Python 代码。6.3 与其他披露面工具的组合使用作为东财披露面工具链的一员get_lockup_expiry可以与 融资融券、大宗交易、股东户数 等工具组合构建多维度的披露面研究管线技能索引页还提供了参考脚本入口资金面/龙虎榜/财报等方向见 SKILL.md 脚本示例。七、源码级原理请求生命周期与错误处理完整的请求生命周期如下对应 lockup_expiry_tool.py 的_fetch_lockups计算窗口以_today()UTC 时区当日为起点start timedelta(dayshorizon_days)为终点选择排序根据是否给定code选择FREE_DATE的排序方向构造请求调用共享客户端eastmoney_client.get_json(_DATACENTER_URL, params{...})解析归一从payload[result][data]提取行列表_extract_rows逐行经_shape_record投影为输出记录达到 200 条即停止封装返回按scope组装信封并序列化为 JSON 字符串。错误处理是全路径兜底的非法代码_normalize_code返回None时直接返回{ok: false, error: unrecognized A-share code ...}不会发网络请求如execute(codeAAPL.US)上游异常网络失败、非 2xx 状态、JSON 解析失败等任何异常都被except Exception捕获记录 warning 日志后返回{ok: false, error: eastmoney lockup query failed: ...}信封保证调用方拿到结构化错误而非裸异常见 lockup_expiry_tool.py。限速链路eastmoney_client.get_json将请求路由到throttled_get_jsonhost_keyeastmoney最小间隔默认 1.0 秒。HostThrottle以进程内共享锁 时间戳记录实现 per-host 最小间隔门控并附加 0~0.4 秒随机抖动以避免并发调用方锁步齐射同一 host 桶复用同一个requests.Session以摊销 TCP/TLS 握手开销见 _http.py。批量任务可通过环境变量调大间隔例如VIBE_TRADING_EASTMONEY_MIN_INTERVAL2但请注意节流是进程内生效的不跨机器协调。八、测试与验证工具契约的行为证据仓库为get_lockup_expiry提供了两层测试可作为理解行为边界的权威参照契约与成功路径test_lockup_expiry_tool.py断言name get_lockup_expiry、is_readonly is True、parameters[required] []且两个入参均出现在 properties 中单代码模式下断言reportName RPT_LIFT_STOCK、filter含SECURITY_CODE600519、sortTypes -1返回信封scope single_code、code 600519全市场模式下断言sortTypes 1、filter同时含FREE_DATE基准日与FREE_DATE基准日30天两个闭区间条件返回scope market_calendar、horizon_days 30、as_of正确峰值保护250 行输入被截为 200 条且truncated: true错误信封非法代码与上游异常分别返回ok: false的可读错误端到端仅 mock 冻结的 HTTP 边界throttled_get_json让真实客户端路由与工具解析全链路运行验证host_key eastmoney。整数代码回归test_lockup_expiry_integer_code.py确认code600519int 类型可正常解析不会因字符串方法调用崩溃。这些测试全部通过 mock 共享客户端完成没有任何请求真正离开进程既保证了测试的确定性也避免了在东财接口上产生真实流量。九、实战使用建议个股风险预检对持仓或候选标的先查全历史解禁表定位未来最近一次解禁日期、解禁股数与解禁市值lift_market_cap结合free_ratio占流通股比评估抛压强度——该比率越大解禁对流通盘的冲击越显著组合层面规避使用全市场日历默认 90 日窗口扫描解禁密集窗口对解禁市值占比较高的时段/板块提前降低暴露注意窗口截断horizon_days上限 365 天、记录上限 200 条若需覆盖更长周期或更多记录应分批缩小窗口查询并留意信封中的truncated标志尊重限速批量遍历个股时保持默认 1.0 秒最小间隔或按需调大VIBE_TRADING_EASTMONEY_MIN_INTERVAL避免触发东财源 IP 封禁异常兜底上游接口可能出现网络抖动或限流调用方应基于ok: false信封做重试或降级而不是直接中断流程。十、小结get_lockup_expiry是 Vibe-Trading 东财披露面工具链中一个轻量但实用的数据工具单参数切换「个股全历史」与「全市场未来窗口」两种查询模式返回字段覆盖解禁股数、解禁市值、占流通股/总股本比例等决策关键量并通过共享 per-host 节流层规避东财的源 IP 封禁风险。其实现lockup_expiry_tool.py、测试test_lockup_expiry_tool.py与技能索引SKILL.md共同构成了可复用、可验证的接入证据链可直接集成进 A 股事件的量化研究流程。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表