TqJees 杰宜斯资管账户接入指南：tqsdk 多柜台直连交易架构与源码级解析

• 金融科技

在 tqsdk-python（天勤量化开发包）中，TqJees是用于直连杰宜斯（JYS）资管柜台的期货交易账户类。本文以 tqsdk.tqjees.rst 参考文档为主体，结合 tqsdk/tradeable/otg/tqjees.py 的完整实现，讲清TqJees的六个构造参数、与TqApi的配合方式、依赖包tqsdk_zq_otg的安装要求，以及登录报文、账户密钥生成、OTG 本地适配进程等底层机制，帮助使用者将量化策略接入杰宜斯程序化外接通道。

TqJees 在 tqsdk 账户体系中的定位

tqsdk 提供多种交易账户类，TqJees是其中一类企业多柜台（OTG）直连账户。从源码结构看，它与其他 OTG 账户共享同一套基类体系：

class TqJees(BaseOtg, FutureMixin): """杰宜斯资管账户类"""

• BaseOtg：负责交易连接管理（_connect_td）、登录流程（_send_login_pack）、收发数据包的分发（_handle_recv_data/_handle_req_data），并把行情与交易两条通道的数据统一合并进TqApi的数据模型；
• FutureMixin：提供期货账户通用的get_account()、get_position(symbol)、get_order(order_id)、get_trade(trade_id)四个查询方法，返回的对象在api.wait_update()时被更新。

TqJees通过 tqsdk/tradeable/otg/init.py 导出，并在 tqsdk/__init__.py 中作为顶层 API 暴露；TqApi 的account参数文档（见 tqsdk/api.py）明确列出TqJees支持"使用杰宜斯资管账号"。

版本背景（见 doc/version.rst）：

• 3.7.3 (2024/09/20)：新增TqJees账户类型，支持杰宜斯资管柜台；
• 3.7.2 (2024/09/12)：BREAKING 变更，从安装依赖中移除tqsdk_zq_otg模块，使用多柜台需要手动安装；
• 3.7.5 (2024/11/13)：为TqCtp、TqJees、TqRohon、TqYida补充了front_url格式示例。

因此，适用前提是使用 tqsdk ≥ 3.7.3 且手动安装tqsdk_zq_otg依赖。

构造参数详解

TqJees的构造函数签名为：

TqJees(account_id: str, password: str, front_broker: str, front_url: str, app_id: str, auth_code: str)

六个参数均为必填字符串，含义如下：

两条使用注意（来自源码 docstring，见 tqsdk/tradeable/otg/tqjees.py）：

1. 使用TqJees账户需要安装tqsdk_zq_otg包：pip install -U tqsdk_zq_otg；
2. front_broker、front_url、app_id和auth_code四项信息需要向杰宜斯申请程序化外接后取得。

构造完成时（tqsdk/tradeable/otg/tqjees.py），实例会把六个字段保存下来，然后以broker_id=""、td_url="zqotg://127.0.0.1:0/trade"调用BaseOtg.__init__。这里有两点值得注意：

• broker_id固定为空字符串，真正的柜台标识由front_broker承担；
• td_url中的zqotg://是一个伪协议，端口0表示"尚未确定"，实际连接地址由后文介绍的ZqOtgContext在运行时替换为ws://127.0.0.1:<动态端口>。

账户密钥与账户标识

OTG 账户的数据在 tqsdk 内部按trade/<account_key>/...的键路径组织。TqJees重写了 _get_account_key：

def _get_account_key(self): s = self._broker_id + self._account_id s += self._front_broker if self._front_broker else "" s += self._front_url if self._front_url else "" return hashlib.md5(s.encode('utf-8')).hexdigest()

即account_key是account_id + front_broker + front_url拼接后的 MD5 摘要。这意味着同一账户只要柜台代码或柜台地址不同，就会被视为不同的账户实例；同时它也解释了为什么TqJees能安全地出现在TqMultiAccount多账户列表中——各账户的键互不冲突。

另外，TqJees的 _account_auth 属性声明了feature: "tq_direct"，这个标记被 tqsdk/zq_otg.py 用来识别哪些账户需要拉起 OTG 适配进程。

快速上手：最小可运行示例

参考文档给出的标准用法：

from tqsdk import TqApi, TqAuth, TqJees account = TqJees( account_id="杰宜斯账户", password="杰宜斯密码", front_broker="杰宜斯柜台代码", front_url="杰宜斯柜台地址", # 形如 tcp://129.211.138.170:10001 app_id="杰宜斯 AppID", auth_code="杰宜斯 AuthCode", ) api = TqApi(account, auth=TqAuth("快期账户", "账户密码")) # 账户资金，内容在 wait_update 时更新 acc = account.get_account() print(acc.balance, acc.float_profit) quote = api.get_quote("SHFE.rb2610") while api.wait_update(): print(quote.last_price)

要点说明：

• TqAuth为必填项，即使使用实盘账户也需要快期账户授权（参见 tqsdk/api.py 中auth参数说明）；
• 行情仍然走 tqsdk 的行情服务，交易走杰宜斯柜台；下单、撤单使用TqApi的标准接口，多账户场景下需通过account=参数或account_obj指定目标账户；
• 由于TqJees混入了FutureMixin，可直接调用get_account()/get_position()/get_order()/get_trade()获取资金、持仓、委托、成交对象，其字段语义与期货标准对象（Account、Position、Order、Trade）一致，实现见 tqsdk/tradeable/mixin.py。

多账户模式：TqMultiAccount 下的 TqJees

TqMultiAccount 的文档明确支持在账户列表中包含TqJees（见 tqsdk/multiaccount.py）。一个策略同时操作资管账户与模拟账户的写法：

from tqsdk import TqApi, TqAuth, TqMultiAccount, TqJees, TqSim jees = TqJees(account_id="...", password="...", front_broker="...", front_url="tcp://ip:port", app_id="...", auth_code="...") sim = TqSim() api = TqApi(TqMultiAccount([jees, sim]), auth=TqAuth("快期账户", "账户密码")) acc1 = jees.get_account() acc2 = sim.get_account() while api.wait_update(): print(acc1.float_profit, acc2.float_profit)

注意：多账户模式下，insert_order、cancel_order、get_account等对账户敏感的接口必须显式传入account=参数（参见 tqsdk/risk_rule.py 等处的参数说明），否则会触发"多账户模式下, 需要指定账户实例 account"错误。

底层连接链：zqotg 伪协议与本地适配进程

TqJees的td_url为zqotg://127.0.0.1:0/trade，这条 URL 在 tqsdk/connect.py 中被特殊处理：

elif url_info.scheme.startswith("zqotg"): cm = ZqOtgContext(self._api)

ZqOtgContext 是本地进程级的上下文管理器，其职责与关键约束如下：

1. 依赖检查：__init__中尝试from tqsdk_zq_otg import get_zq_otg_path，导入失败抛出使用 TqJees 账户需要安装 tqsdk_zq_otg 包: pip install -U tqsdk_zq_otg；版本低于3.10.1时抛出需要更新 tqsdk_zq_otg 包到最新版本的异常。错误信息中的账户类型列表正是通过匹配_account_auth.feature == "tq_direct"统计出来的（tqsdk/zq_otg.py）；
2. 拉起 otg_adapter 进程：get_url 中以--mode=cmd启动tqsdk_zq_otg包提供的otg_adapter可执行文件，并把LD_LIBRARY_PATH指向包安装路径；启动参数指定了日志目录、用户配置目录，以及host=127.0.0.1、port=0（系统分配空闲端口）；
3. 动态端口协商：适配进程启动后会在数据目录写入port.json，ZqOtgContext最多轮询 30 秒读取其中的port，成功后把伪协议 URL 改写为ws://127.0.0.1:<port>/trade，随后TqConnect用 WebSocket 连接到该本地进程；
4. 日志与配置目录：每次运行在~/.tqsdk/otg_logs/<时间戳>-<uuid>/下创建独立日志目录，用户配置存于~/.tqsdk/otg_config/；日志目录超过TQ_OTG_MAX_LOG_DIRS环境变量（默认 30）时自动清理，但 3 天内的目录受保护（见 tqsdk/zq_otg.py 与_clear_otg_logs）。

因此，从源码结构看，TqJees的实际数据流是：Python 策略 → WebSocket → 本机 otg_adapter 进程 → 杰宜斯柜台front_url，适配进程负责把杰宜斯柜台协议翻译成 tqsdk 统一的req_login/rtn_data报文格式。进程退出时由__aexit__关闭 stdin 并等待进程结束，保证 TqApi 关闭时子进程不泄漏。

登录报文与数据回流

连接建立后，BaseOtg._run 首先调用账户自身的_send_login_pack。TqJees的登录报文（tqsdk/tradeable/otg/tqjees.py）为：

req = { "aid": "req_login", "bid": "tqsdk_zq_otg", "user_name": self._account_id, "password": self._password, "broker_id": self._front_broker, "front": self._front_url, "app_id": self._app_id, "auth_code": self._auth_code, "backend": "jees" } await self._td_send_chan.send(req)

其中backend: "jees"是柜台路由关键字——它告诉本地otg_adapter进程使用杰宜斯后端协议。对比同族的 TqRohon（backend: "rohon"）可以看到，OTG 账户家族在 tqsdk 侧几乎同构，差异仅在于登录报文的backend字段与 docstring 中的柜台名称。

收到柜台回执后，BaseOtg的 _handle_recv_data 会把交易通道rtn_data中的 notify 补上_account_name字段（用于 Web 界面展示），而 _td_handler 会把 OTG 返回的成交记录中trade的键从原始user_id替换为统一的_account_key，与行情通道数据合并后进入TqApi._data——这正是get_trade()等接口能按trade/<account_key>/trades路径取数的原因。

下单与撤单的路由

交易类请求（insert_order、cancel_order等）由 Tradeable._is_self_trade_pack 依据account_key匹配到对应账户实例，再经 _handle_req_data 发往该账户自己的_td_send_chan。因此在多账户场景下，请求不会被错发到其他柜台。

运行环境与排障要点

结合上述实现，使用TqJees时建议按以下清单核对：

1. tqsdk 版本：≥ 3.7.3（TqJees引入版本），pip install -U tqsdk保持升级；
2. 依赖包：pip install -U tqsdk_zq_otg，且版本 ≥ 3.10.1（由 tqsdk/zq_otg.py 的版本比较逻辑强制检查）；自 tqsdk 3.7.2 起该依赖不再随主包自动安装；
3. 参数获取：front_broker/front_url/app_id/auth_code来自杰宜斯程序化外接申请，其中front_url必须为tcp://ip:port形式；
4. 启动失败排查：
   • 若提示"使用 TqJees 账户需要安装 tqsdk_zq_otg 包"，说明依赖缺失或版本过低；
   • 若提示"获取交易服务地址失败"（tqsdk/zq_otg.py 抛出的TqContextManagerError），说明 30 秒内port.json未就绪，可检查~/.tqsdk/otg_logs/下对应时间戳目录中的适配进程日志，以及到杰宜斯柜台的网络连通性；
   • Windows 与 Linux/macOS 的进程拉起方式不同（前者subprocess.Popen，后者asyncio.create_subprocess_exec，见 tqsdk/zq_otg.py），跨平台部署时以各自系统实测为准；
5. 日志管理：每次运行都会生成新的~/.tqsdk/otg_logs/<时间戳>-<uuid>目录，长期运行环境可通过环境变量TQ_OTG_MAX_LOG_DIRS调整保留上限（默认 30 个目录）。

小结

tqsdk.TqJees以六个构造参数封装了杰宜斯资管柜台的直连信息，复用BaseOtg的连接管理与FutureMixin的期货数据查询能力；其底层通过zqotg://伪协议触发ZqOtgContext拉起tqsdk_zq_otg提供的本地otg_adapter进程，再以动态端口的 WebSocket 完成 Python 层与杰宜斯柜台协议之间的桥接。掌握account_key生成、登录报文backend路由、port.json端口协商这三个机制，即可独立排查接入问题，并将其平滑扩展到TqMultiAccount多账户策略中。相关源码入口：tqsdk/tradeable/otg/tqjees.py、tqsdk/tradeable/otg/base_otg.py、tqsdk/zq_otg.py、tqsdk/connect.py。

• 金融科技