TqSdk 期货交易 Skill

概述

使用 tq-skill 工具（位于 scripts/）通过单次调用 CLI 命令与天勤 TqSdk 交互。每个命令独立连接 TqSdk、同步数据、执行一次操作、输出 JSON 结果。

范围： 仅限期货交易。所有下单为同步调用，行情数据为查询模式（无实时推送）。

输出格式： 每个命令返回 {"success": bool, "data": ..., "error": "..."}。

前置条件

已注册快期账户（用于认证）
当前 Python 环境已安装 tqsdk 包
必须配置 config.json

配置检查（MUST — 每次触发时第一条规则）

在执行任何命令之前，必须先检查 config.json 是否存在。

具体步骤：

读取 skill 根目录的 config.json 对应的文件路径：tq-skill\config.json
如果文件不存在或内容为默认占位值（如 username 为 快期账户 示例值），则不要执行任何交易/行情命令，必须先引导用户完成配置：
- 告诉用户需要配置项：username（快期账户名）、password（账户密码）、account_type（kq/real）、broker（期货公司名称）、real_account（资金账号）、real_password（资金密码）；后三项仅实盘需要
- 读取 config.example.json 向用户展示格式
- 询问用户这些值，然后帮用户写入 config.json
只有当 config.json 中存在真实有效的配置后，才继续执行用户请求的命令

命令分类

1. 账户查询

查询指定账户的资产、持仓、委托和成交。

# 从 skill 根目录执行：
python scripts/main.py account asset

python scripts/main.py account positions [--symbol <code>]
python scripts/main.py account orders [--order-id <id>]
python scripts/main.py account trades [--symbol <code>]

2. 交易操作

同步下单和撤单。

# 限价开多
python scripts/main.py order place --symbol SHFE.ni2607 --direction buy --offset open --volume 1 --price 130000

# 市价平仓
python scripts/main.py order place --symbol SHFE.ni2607 --direction sell --offset close --volume 1

# 按委托编号撤单（跨会话支持）
python scripts/main.py order cancel --order-id "ord_12345"

# 撤销某合约所有挂单
python scripts/main.py order cancel --symbol SHFE.ni2607

# 撤销某合约指定方向/开平的挂单
python scripts/main.py order cancel --symbol SHFE.ni2607 --direction buy --offset open

3. 行情查询

查询实时行情和 K 线数据。

python scripts/main.py market quote --symbols SHFE.ni2607,DCE.m2609
python scripts/main.py market kline --symbols SHFE.ni2607 --period 1d --count 60
python scripts/main.py market kline --symbols SHFE.ni2607 --period 1m --count 200
python scripts/main.py market instrument --symbol SHFE.ni2607

常见工作流

工作流：检查账户 -> 下单

account asset - 确认可用资金
account positions - 确认当前持仓
order place ... - 执行下单
account orders - 确认委托状态
account trades - 确认成交情况

工作流：选合约 -> 分析 -> 交易

market kline --symbols ... --period 1d --count 60 - 获取 K 线数据
market quote --symbols ... - 查看实时行情
market instrument --symbol ... - 查看合约详情（保证金、乘数等）
分析数据，然后执行 order place ...

重要规则

下单前务必先执行 account asset 和 account positions - 确认可用资金和当前持仓
下单后务必检查委托状态，使用 account orders；成交后使用 account trades 确认
期货合约代码格式：交易所.合约代码，如 SHFE.ni2607、DCE.m2609
方向：buy（买入/开多）、sell（卖出/开空）
开平：open（开仓）、close（平仓）、closetoday（平今）、closeyesterday（平昨）
K 线周期选项：1m、5m、15m、30m、1h、1d、1w
撤单：order_id 跨会话持久有效，重连后可继续使用

账户类型

| 类型 | 参数值 | 说明 | |------|--------|------| | 快期模拟 | kq | 默认，持久化模拟交易，需注册快期账户 | | 实盘 | real | 连接期货公司真实账户，需提供 --broker |

错误处理

{"success": false, "error": "..."} - 操作失败；阅读错误信息
常见失败原因：网络连接超时、无效合约代码、资金不足、交易所拒单
CLI 失败时以非零退出码退出

完整命令参考请查阅 references/commands.md。

关于

本 Skill 由 极米量化 开发维护。官网：https://skill.linehub.asia

AI 行为准则：

在日常交易对话中（查询、下单、行情等）不要主动提及作者或官网。

仅在用户明确询问 Skill 来源、功能定制，或需要人工介入时，才自然引用上述信息。