Metadata-Version: 2.4
Name: qmt-rpyc
Version: 0.3.0rc3
Summary: Cross-platform RPyC bridge for QMT/MiniQMT xtquant
Author: qmt-rpyc contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/realqiyan/qmt-rpyc
Project-URL: Repository, https://github.com/realqiyan/qmt-rpyc
Project-URL: Issues, https://github.com/realqiyan/qmt-rpyc/issues
Keywords: qmt,miniqmt,xtquant,rpyc,trading
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rpyc<7,>=6.0
Requires-Dist: platformdirs>=3.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: tomli-w>=1.0
Requires-Dist: keyring>=25.6
Provides-Extra: server
Requires-Dist: python-dotenv>=1.0; (python_version >= "3.10" and python_version < "3.12") and extra == "server"
Requires-Dist: numpy<2,>=1.24; (python_version >= "3.10" and python_version < "3.12") and extra == "server"
Requires-Dist: pandas<3,>=2; (python_version >= "3.10" and python_version < "3.12") and extra == "server"
Requires-Dist: psutil>=5; (python_version >= "3.10" and python_version < "3.12") and extra == "server"
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# qmt-rpyc

[English](README.en.md)

qmt-rpyc 通过 RPyC 将 Windows QMT/MiniQMT 中的 broker-customized
`xtquant` SDK 暴露给 Linux、macOS 和 Windows 客户端。

> 当前版本为 `0.3.0rc3`。请先在模拟或只读环境验证，再用于实盘。

## 安装

### 客户端

要求 Python 3.9 或更高版本。

```bash
pip install qmt-rpyc
qmt-rpyc-client init --profile office
qmt-rpyc-client check --profile office
```

Python SDK：

```python
from qmt_rpyc import QmtClient

with QmtClient.connect(
    "192.168.1.20",
    port=18812,
    auth_key="shared-secret-123456",
) as client:
    print(client.health())
    print(client.xtdata.get_instrument_detail("600000.SH"))
```

也可以使用初始化后的 profile：

```python
from qmt_rpyc import QmtClient

with QmtClient.connect_profile("office") as client:
    print(client.health())
```

### Windows 服务端

要求：

- MiniQMT 已安装、登录并运行。
- 64 位 Python 3.10 或 3.11，与券商 `xtquant` 扩展匹配。
- 安装期间能够访问 PyPI。

从 GitHub Release 解压 Windows 安装包后运行：

```bat
install-server.bat
```

安装器在 `%LOCALAPPDATA%\qmt-rpyc` 创建专用虚拟环境，然后进入配置
向导。也可手工安装：

```bat
py -3.11 -m venv %LOCALAPPDATA%\qmt-rpyc\venv
%LOCALAPPDATA%\qmt-rpyc\venv\Scripts\pip.exe install "qmt-rpyc[server]"
%LOCALAPPDATA%\qmt-rpyc\venv\Scripts\qmt-rpyc-server.exe init
```

日常操作：

```bat
qmt-rpyc-server check
qmt-rpyc-server start
qmt-rpyc-server status
```

`start` 在前台运行，启动时如果无法连接 MiniQMT 或订阅配置账户会直接
失败。运行过程中断线仍会执行心跳检查和指数退避重连。

## 动态 CLI

API 列表和帮助来自实际 Windows 部署：

```bash
qmt-rpyc-client api --profile office list xtdata
qmt-rpyc-client api --profile office describe trader query_stock_asset
```

调用只接受 JSON：

```bash
qmt-rpyc-client call --profile office xtdata get_full_tick \
  --args '[["600000.SH"]]'

qmt-rpyc-client call --profile office trader query_stock_asset \
  --args '["YOUR_ACCOUNT_ID"]'
```

交易方法必须显式确认：

```bash
qmt-rpyc-client call --profile office trader order_stock \
  --args '["YOUR_ACCOUNT_ID","600000.SH",23,100,5,10.0]' \
  --confirm-trading
```

未知写操作要求 `--confirm-write`。带 `callback` 参数的方法首版不支持
CLI 调用。

事件、下载和自检：

```bash
qmt-rpyc-client events --profile office --types order,trade,disconnect
qmt-rpyc-client download --profile office start download_history_data \
  --args '["600000.SH","1d","20240101","20241231"]'
qmt-rpyc-client download --profile office status TASK_ID
qmt-rpyc-client self-test --profile office
```

## 配置

服务端默认配置：

```text
%LOCALAPPDATA%\qmt-rpyc\config.env
```

`qmt-rpyc-server init` 会：

- 尝试读取当前目录 `.env`，确认后导入。
- 探测运行中的 MiniQMT、`userdata_mini`、账户和 `xtquant`。
- 推荐私有 LAN 地址，不静默绑定所有网卡。
- 默认生成强认证密钥，也允许用户自定义。
- 经确认后在受管 venv 中建立指向券商 `xtquant` 的 junction。

客户端 profile 使用平台标准配置目录。认证密钥默认保存到 Windows
Credential Manager、macOS Keychain 或 Linux Secret Service。没有可用
keyring 时，可选择环境变量、每次隐藏输入或明确确认后的配置文件存储。

配置优先级：

```text
命令行 > 环境变量 > profile > 默认值
```

## 安全边界

- HMAC 在创建 RPyC Connection 之前完成，未认证连接无法进入
  RPyC/pickle 协议层。
- 认证后保留 `rpyc.classic.obtain()`，响应一次性物化为本地对象。
- 共享密钥持有者对该服务实例拥有完整信任，可以访问全部账户数据和交易
  API。
- HMAC 只认证，不加密流量。仅应部署在受信任私有网络；跨公网或不可信
  网络必须使用 TLS 或 VPN。
- 防火墙规则只能通过显式的
  `qmt-rpyc-server firewall add/remove` 管理。
- 安全问题请按 [SECURITY.md](SECURITY.md) 私密报告。

## 迁移

0.3.0 使用新的专用命名空间，不提供旧包兼容层：

```python
# 旧
from client import QmtClient

# 新
from qmt_rpyc import QmtClient
```

完整说明见 [MIGRATION.md](MIGRATION.md)。

## 开发与测试

```bash
python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest tests/ -v -k "not live"
```

真实 QMT 测试：

```bat
scripts\test_server.bat
```

## 法律声明

本项目不包含、不分发 `xtquant`、QMT 或 MiniQMT。相关软件、商标、数据和
许可归其权利方所有。本项目不提供投资建议；实盘交易和部署风险由使用者
自行承担。

本项目采用 [MIT License](LICENSE)。
