Qbot easytrader 交易模块深度解析券商客户端接入、自动登录与模拟盘跟踪调仓【免费下载链接】Qbot[updating ...] AI 自动量化交易机器人(完全本地部署) AI-powered Quantitative Investment Research Platform. online docs: https://ufund-me.github.io/Qbot ✨ :news: qbot-mini: https://github.com/Charmve/iQuant项目地址: https://gitcode.com/GitHub_Trending/qbot/Qbot本文以 Qbot 仓库内置的 easytrader 模块位于qbot/engine/trade/easytrader/为核心系统讲解这个本地程序化股票交易通道的能力边界、券商客户端接入方式、自动登录机制、交易与查询接口、模拟盘/雪球组合跟踪调仓follower机制以及它如何被 Qbot 实盘引擎与 pytrader 生态集成。读完本文你可以掌握 easytrader 从安装、客户端配置到use/prepare/买卖下单的完整使用链路并能看懂其在 Qbot 中的实际调用位置。一、easytrader 在 Qbot 中的定位easytrader 是 Qbot 交易引擎中用于驱动本地券商交易客户端的核心依赖其代码以 vendored内置拷贝形式存放在 qbot/engine/trade/easytrader/ 目录下。根据该模块的 README它提供以下能力进行自动的程序化股票交易支持跟踪 JoinQuant、RiceQuant 的模拟交易支持跟踪雪球组合调仓支持通用的同花顺客户端模拟操作实现自动登录支持通过 webserver 远程操作客户端支持命令行调用方便其他语言适配基于 Python 3.6Windows 平台。注意Linux 仅支持雪球xq客户端。从源码看当前 vendored 拷贝的版本号在 easytrader/init.py 中声明为__version__ 0.23.0。模块对外暴露的两个工厂函数use()与follower()定义在 easytrader/api.pyuse()按券商名生成交易客户端对象follower()按平台名生成跟踪器对象二者共同构成 easytrader 的全部 API 入口。目录组织上该模块包含三部分子目录/文件说明easytrader/包主体含各券商客户端 traderht_clienttrader.py、gj_clienttrader.py、xqtrader.py等、基类、远程服务、followerdocs/使用文档usage.md、install.md、other/xueqiu.mdtests/针对银河、华泰、海通客户端的集成测试二、支持券商README 清单与源码工厂映射README 中列出的支持券商为海通客户端海通网上交易系统独立委托华泰客户端网上交易系统专业版Ⅱ国金客户端全能行证券交易终端 PC 版其他券商通用同花顺客户端需要手动登录。而源码中的工厂函数use()支持的别名集合比 README 更完整。api.py 的 use() 将券商别名映射到具体的 trader 类use()参数别名生成的类对应实现文件xq/雪球XueQiuTraderxqtrader.pyyh_client/银河客户端YHClientTraderyh_clienttrader.pyht_client/华泰客户端HTClientTraderht_clienttrader.pywk_client/五矿客户端WKClientTraderwk_clienttrader.pyhtzq_client/海通证券客户端HTZQClientTraderhtzq_clienttrader.pygj_client/国金客户端GJClientTradergj_clienttrader.pygf_client/广发客户端GFClientTradergf_clienttrader.pyuniversal_client/通用同花顺客户端UniversalClientTraderuniversal_clienttrader.pyths/同花顺客户端ClientTraderclienttrader.py传参不正确时会抛出NotImplementedError。可见 README 是对外宣传的最小支持集源码中还包含银河、五矿、广发等更多客户端实现使用时应以 docs/usage.md 与use()的别名列表为准。三、安装与客户端前置设置安装方式来自 docs/install.mdpip install easytrader # 升级 pip install easytrader -UWindows 用户若pip安装时提示No module named xxx需先pip install xxx安装对应缺失模块再重新执行pip install easytrader。由于 easytrader 本质上是对 Windows 桌面客户端 GUI 的模拟操作文档特别强调客户端必须按以下要求设置否则会导致下单时价格出错以及客户端超时锁定系统设置 界面设置界面不操作超时时间设为0系统设置 交易设置默认买入价格/买入数量/卖出价格/卖出数量都设置为空客户端不能最小化也不能处于精简模式。文档还给出两条工程化建议云端部署在云服务上部署时使用自带的远程桌面会有问题推荐使用 TightVNC 方案登录验证码识别若券商登录需要识别验证码需要安装tesseract注意是 OCR 引擎本体而非 Python 包装库pytesseract并保证命令行下tesseract可用也可以手动登录后再通过easytrader连接此时登录过程会直接识别到已登录的窗口。四、快速上手use → prepare → 交易4.1 设置交易客户端类型引入包并指定券商客户端类型完整示例见 docs/usage.mdimport easytrader海通客户端user easytrader.use(htzq_client)华泰客户端user easytrader.use(ht_client)国金客户端user easytrader.use(gj_client)通用同花顺客户端user easytrader.use(universal_client)通用同花顺客户端是指同花顺官网提供的客户端软件内的下单程序内含对多个券商的交易支持适用于券商不直接提供同花顺客户端时的后备方案。其他券商专用同花顺客户端user easytrader.use(ths)即对应券商官网提供的基于同花顺修改的软件版本例如银河的双子星同花顺版本、国金证券网上交易独立下单程序等。雪球Linux 下唯一可用user easytrader.use(xq)4.2 启动并连接客户端其他券商专用同花顺客户端不支持自动登录需要先手动登录然后user.connect(r客户端xiadan.exe路径) # 类似 rC:\htzqzyb2\xiadan.exe通用同花顺客户端需要先手动登录一次添加券商、填入账户号/密码/验证码、勾选保存密码第一次登录后信息被缓存之后调用prepare函数即可自动登录仅需账户号、客户端路径密码随意输入。其它客户端可直接调用prepare函数自动登录。prepare所需的参数支持两种赋予方式方式一函数参数文档推荐user.prepare(user用户名, password雪球、银河客户端为明文密码, comm_password华泰通讯密码其他券商不用)方式二配置文件user.prepare(/path/to/your/yh_client.json) # 配置文件路径配置文件需自己用编辑器生成请勿使用记事本推荐 Notepad 或 Sublime Text。仓库内提供了两种格式的样例配置银河/国金客户端格式样例见 yh_client.json{ user: 银河用户名, password: 银河明文密码 }华泰客户端格式多一个通讯密码字段{ user: 华泰用户名, password: 华泰明文密码, comm_password: 华泰通讯密码 }雪球格式样例见 xueqiu.json{ cookies: 雪球 cookies登陆后获取, portfolio_code: 组合代码(例:ZH818559), portfolio_market: 交易市场(例:us 或者 cn 或者 hk) }4.3 源码视角prepare 与自动登录是怎么实现的所有 Web 接口型 trader 继承自 webtrader.py 中的 WebTrader 抽象基类。prepare()的入口逻辑是传入config_file时走read_config()读取 JSON读取失败会提示配置文件格式有误请勿使用记事本编辑并对整数值字段告警配置文件的值最好使用双引号包裹否则走参数登录分支最终统一调用autologin()。autologin()的实现见 webtrader.py L62-L73最多重试limit10次login()全部失败则抛出NotLoginError并提示检查密码、券商维护状态与网络。登录成功后调用keepalive()启动心跳守护线程从 check_login()L93-L106 可以看到心跳线程默认每 30 秒请求一次heartbeat()默认即查询balance来验证 token 有效性发现连接异常时会记录日志并触发autologin()重新登录。这正是 README 中实现自动登录一条的底层机制登录、保活、掉线重连由同一个心跳线程闭环完成。返回值的类型矫正也值得注意WebTrader.do()L184-L201统一封装了发请求 → 格式化 → 错误修正 → 登录态检查失败则自动重登的流水线而format_response_data_type()会依据 config/global.json 中response_format的int/float字段名清单如可用资金参考市值成交数量等中英文字段把券商接口返回的字符串批量转为数值类型——这也是为什么文档中balance、position的返回值里出现的是数值而非字符串。五、交易与查询接口全解以下接口与返回值示例完整继承自 docs/usage.md。5.1 获取资金状况user.balance返回[{参考市值: 21642.0, 可用资金: 28494.21, 币种: 0, 总资产: 50136.21, 股份参考盈亏: -90.21, 资金余额: 28494.21, 资金帐号: xxx}]5.2 获取持仓user.position返回[{买入冻结: 0, 交易市场: 沪A, 卖出冻结: 0, 参考市价: 4.71, 参考市值: 10362.0, 参考成本价: 4.672, 参考盈亏: 82.79, 当前持仓: 2200, 盈亏比例(%): 0.81%, 股东代码: xxx, 股份余额: 2200, 股份可用: 2200, 证券代码: 601398, 证券名称: 工商银行}]5.3 买入 / 5.4 卖出user.buy(162411, price0.55, amount100) user.sell(162411, price0.55, amount100)返回{entrust_no: xxxxxxxx}注系统可以配置是否返回成交回报如果没有配置则默认返回{message: success}。5.5 一键打新user.auto_ipo()5.6 撤单user.cancel_entrust(buy/sell 获取的 entrust_no)返回{message: 撤单申报成功}5.7 查询当日成交user.today_trades返回[{买卖标志: 买入, 交易市场: 深A, 委托序号: 12345, 成交价格: 0.626, 成交数量: 100, 成交日期: 20170313, 成交时间: 09:50:30, 成交金额: 62.60, 股东代码: xxx, 证券代码: 162411, 证券名称: 华宝油气}]5.8 查询当日委托user.today_entrusts返回示例含已成与已撤两种状态[{买卖标志: 买入, 交易市场: 深A, 委托价格: 0.627, 委托序号: 111111, 委托数量: 100, 委托日期: 20170313, 委托时间: 09:50:30, 成交数量: 100, 撤单数量: 0, 状态说明: 已成, 股东代码: xxxxx, 证券代码: 162411, 证券名称: 华宝油气}, {买卖标志: 买入, 交易市场: 深A, 委托价格: 0.6, 委托序号: 1111, 委托数量: 100, 委托日期: 20170313, 委托时间: 09:40:30, 成交数量: 0, 撤单数量: 100, 状态说明: 已撤, 股东代码: xxx, 证券代码: 162411, 证券名称: 华宝油气}]5.9 查询今日可申购新股from easytrader.utils.stock import get_today_ipo_data ipo_data get_today_ipo_data() print(ipo_data)返回[{stock_code: 股票代码, stock_name: 股票名称, price: 发行价, apply_code: 申购代码}]5.10 刷新数据与 5.11 雪球组合比例调仓user.refresh()user.adjust_weight(股票代码, 目标比例)例如user.adjust_weight(000001, 10)是将平安银行在组合中的持仓比例调整到 10%。最后退出客户端软件user.exit()从源码看exit()对应 WebTrader.exit()L114-L116其作用是停止心跳线程heart_active False从而结束 token 保活。六、模拟交易与组合跟踪follower 机制README 中支持跟踪 JoinQuant、RiceQuant 的模拟交易支持跟踪雪球组合调仓对应源码中的三个 follower 类JoinQuantFollower、RiceQuantFollower、XueQiuFollower由 api.py 的 follower() 工厂 生成fq/ricequant/米筐→RiceQuantFollowerjq/joinquant/聚宽→JoinQuantFollowerxq/xueqiu/雪球→XueQiuFollower。6.1 跟踪 JoinQuant / RiceQuant 模拟交易(1) 初始化被跟踪的 trader以雪球为例也可使用银河等 easytrader 支持的券商xq_user easytrader.use(xq) xq_user.prepare(xueqiu.json)(2) 初始化 followertarget jq # joinquant target rq # ricequant follower easytrader.follower(target) follower.login(userrq/jq用户名, passwordrq/jq密码)(3) 连接 follower 和 trader。JoinQuantfollower.follow(xq_user, jq的模拟交易url)jq 的模拟交易 url 指对应模拟交易可以查看持仓、交易记录的页面形如https://www.joinquant.com/algorithm/live/index?backtestIdxxx的相对地址。启动后若跟踪策略无输出通常是因为当天模拟交易没有调仓或收到的调仓信号已过期——默认只处理 120 秒内的信号。测试时可用下面的命令放宽jq_follower.follow(user, 模拟交易url, trade_cmd_expire_seconds100000000000, cmd_cacheFalse)trade_cmd_expire_seconds默认处理多少秒内的信号cmd_cache是否读取已经执行过的命令缓存以防止重复执行。目录下产生的cmd_cache.pk用于存储历史执行过的交易指令防止重启程序时重复执行已交易过的指令可通过follower.follow(xxx, cmd_cacheFalse)关闭。RiceQuantfollower.follow(xq_user, run_id)其中run_id即 RiceQuant PT 列表中的 ID。6.2 跟踪雪球组合(1)初始化 trader 同上(2)初始化 followerxq_follower easytrader.follower(xq) xq_follower.login(cookies雪球 cookies登陆后获取)(3)连接 follower 和 traderxq_follower.follow(xq_user, xq组合ID类似ZH123456, total_assets100000)由于雪球组合以百分比调仓需要额外设置组合对应的资金额度两种设定方式设置total_assets当前组合净值对应的总资金额度或设置initial_assets总资金额度为initial_assets * 组合净值。雪球额外支持adjust_sell参数决定是否根据用户的实际持仓数调整卖出股票数量解决雪球按百分比调仓时计算股数有偏差的问题卖出股数大于实际持仓数时调整为实际持仓数目前仅在银河客户端测试通过当users为多个时按第一个 user 的持仓数决定。雪球客户端的完整说明另见 docs/other/xueqiu.md。6.3 多用户跟踪多策略与调参follower.follow(users[xq_user, yh_user], strategies[组合1, 组合2], total_assets[10000, 10000])其它与跟踪相关的参数# 市价单跟踪模式目前仅支持银河 follower.follow(***, entrust_propmarket) # 调整下单间隔默认 0s调大可防止卖出买入时卖出单未成交导致买入金额不足 follower.follow(***, send_interval30) # 设置下单间隔为 30s # 设置买卖时的滑点 follower.follow(***, slippage0.05) # 设置滑点为 5%七、远端服务器模式与命令行模式7.1 远端服务器模式webserver 远程操作远端服务器模式是交易服务端与量化策略端分离的模式交易服务端是运行着 easytrader 交易服务、有固定 IP 的云服务器其上运行下单软件如同花顺xiadan.exe或雪球xq量化策略端可能是 JoinQuant、RiceQuant、Vn.Py 等物理上不在同一台电脑。交易服务端通过两种方式获得交易信号一被动接收远端策略指令。交易服务端启动服务from easytrader import server server.run(port1430) # 默认端口为 1430量化策略端调用服务from easytrader import remoteclient user remoteclient.use(使用客户端类型可选 yh_client, ht_client, ths, xq 等, host服务器ip, port服务器端口默认为1430) user.buy(...) user.sell(...) # 交易函数用法同上从源码看服务端实现为 easytrader/server.py一个 Flask 应用用模块级global_store保存登录后的user对象并暴露以下路由/preparePOST解析broker字段后调用api.use()prepare()、/balance、/position、/today_entrusts、/today_trades、/cancel_entrusts、/auto_ipoGET、/buy、/sell、/cancel_entrustPOST、/exitGET。所有路由经error_handle装饰器包裹异常统一转为400 {error: message}返回。run(port1430)定义在 server.py L134-L135监听0.0.0.0。策略端则由 remoteclient.py 提供对应的 HTTP 客户端封装。二主动监控远端策略成交记录或仓位变化即上文第六节的 follower 机制跟踪 JoinQuant/RiceQuant 模拟盘、跟踪雪球组合。7.2 命令行模式docs/usage.md 同时给出了面向其它语言适配的命令行用法python cli.py --use yh --prepare gf.json # 登录会生成 account.session 保存 user 对象 python cli.py --get balance # 获取余额/持仓/其他变量 python cli.py --do buy 162411 0.450 100 # 买卖/撤单 python cli.py --help # 查看帮助需要说明的是从当前仓库 vendored 拷贝的目录结构看该目录下未包含cli.py入口脚本此节为 upstream 文档描述的能力实际命令行调用请结合所安装版本的 easytrader 发行包确认。八、Qbot 与 pytrader 生态如何集成 easytradereasytrader 在 Qbot 中并非孤立模块而是被交易引擎与策略框架多处复用1. 实盘交易引擎。qbot/engine/trade/trade_real.py 的RealTradeEngine在股票实盘分支中先从账户配置STOCK_REAL_ACCOUNT经file2dict解析读取各平台账号再按trade_opts[platform]分派到对应的easytrader.use(...)并调用prepare(...)完成登录见 L44-L78login()、get_cash()、get_positions()、start_trade()、close()等生命周期方法则委托给内部trade_engine。从源码结构看该分支使用的平台别名如tonghuashun、xuqiu与 vendored 版use()工厂的别名集合并不完全一致可以推断 Qbot 实盘依赖的 easytrader 运行版本包含自定义扩展的券商别名。2. 策略示例网格交易。qbot/engine/trade/engine_apis/stocks/easytrader_example.py 展示了一个典型的策略封装范式GridTradeStrategy持有 easytrader 客户端对象按网格价格数组逐格判断——价格高于网格且position有可卖持仓时卖出 100 股价格低于网格且可用现金足够时买入 100 股外层while True循环驱动execute()。它以华泰客户端easytrader.use(ht_client)prepare(华泰, username..., password...)登录演示了策略逻辑只依赖 easytrader 统一接口的写法。3. pytrader 生态的平行拷贝。Qbot 中还存在一份 pytrader 使用的 easytrader 拷贝pytrader/easytrader/二者共享同一套模型与 Web 接口。可确认的引用点包括pytrader/easyquant/context.pyfrom easytrader.model import Balance, Deal, Entrust, Position及from easytrader.webtrader import WebTraderpytrader/web_server.py引入WebTrader作为 Web 交易通道pytrader/easyquant/main_engine.pyself.user easytrader.use(broker)账号文件缺失时告警easytrader 将不可用pytrader/easyquant/quotation.py 与 qbot/engine/backtest/rsrs.py、pytrader/rsrs.py复用easytrader.utils.misc.file2dict读取账户/参数配置pytrader/easyquant/backtest_engine.py回测引擎引入easytrader.mock_trader.MockTrader用 mock trader 替代真实客户端做撮合。这说明 easytrader 在 Qbot 中承担双重角色实盘/模拟盘时是真实券商通道回测与 Web 服务时其model数据结构和MockTrader又被上层框架直接复用。九、测试如何验证这些能力easytrader 目录下的 tests/test_easytrader.py 用unittest覆盖三个 Windows 客户端银河yh、华泰ht、海通htzq。其设计值得参考通过环境变量EZ_TEST_CLIENTS逗号分隔选择要启用的客户端且sys.platform ! darwinWindows 平台才执行否则整体 skipL9-L14——与Windows 专属的平台约束一致账号密码从EZ_TEST_YH_ACCOUNT、EZ_TEST_HT_PASSWORD等环境变量读取避免凭据硬编码进代码正常路径用例覆盖balance、today_entrusts、today_trades、cancel_entrusts、cancel_entrust、auto_ipo异常路径用例验证非法委托抛出easytrader.exceptions.TradeError例如test_invalid_buy中user.buy(511990, 1, 1e10)数量为 10^10与test_invalid_sellL46-L56华泰客户端额外覆盖逆回购场景test_invalid_repo与test_invalid_reverse_repouser.repo(204001, 100, 1)等。此外tests/test_xq_follower.py 与 tests/test_xqtrader.py 针对雪球 follower 与雪球 trader 提供独立测试与Linux 仅支持雪球的定位相呼应。十、使用边界与工程注意事项平台限制基于 Python 3.6 与 Windows 桌面客户端自动化Linux 仅支持xq云端部署需 VNC 类方案文档推荐 TightVNC且客户端不可最小化/精简模式、界面超时需置 0。凭据管理JSON 配置文件中是明文密码如 yh_client.json生产环境建议优先使用prepare函数参数或环境变量注入减少明文凭据落盘。重复下单防护跟踪模式下务必保留cmd_cachecmd_cache.pk语义防止服务重启后对同一调仓信号重复下单。接口差异README 的券商支持清单小于源码use()实际支持的别名集合exchangebill、current_deal、get_ipo_limit等接口在基类中仅部分券商实现webtrader.py L148-L182 有明确告警注释调用前需确认所用客户端子类是否支持。策略适配将策略接入时建议以 easytrader_example.py 的封装范式为模板只依赖use/prepare/buy/sell/position/balance等统一接口便于在不同券商与 mock trader 之间切换。十一、关键路径索引内容路径模块 README能力清单与支持券商qbot/engine/trade/easytrader/README.md使用文档客户端类型、交易接口、follower、远端与命令行qbot/engine/trade/easytrader/docs/usage.md安装文档pip 安装、客户端设置、VNC、tesseractqbot/engine/trade/easytrader/docs/install.md雪球客户端说明qbot/engine/trade/easytrader/docs/other/xueqiu.md工厂函数use()/follower()qbot/engine/trade/easytrader/easytrader/api.pyWeb 型 trader 基类prepare/心跳/请求流水线qbot/engine/trade/easytrader/easytrader/webtrader.pyFlask 远端服务默认端口 1430qbot/engine/trade/easytrader/easytrader/server.py返回字段类型转换配置qbot/engine/trade/easytrader/easytrader/config/global.json配置文件样例yh_client.json、xueqiu.json客户端集成测试qbot/engine/trade/easytrader/tests/test_easytrader.pyQbot 实盘引擎集成qbot/engine/trade/trade_real.py网格策略示例qbot/engine/trade/engine_apis/stocks/easytrader_example.py【免费下载链接】Qbot[updating ...] AI 自动量化交易机器人(完全本地部署) AI-powered Quantitative Investment Research Platform. online docs: https://ufund-me.github.io/Qbot ✨ :news: qbot-mini: https://github.com/Charmve/iQuant项目地址: https://gitcode.com/GitHub_Trending/qbot/Qbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考