tqsdk-rust

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TQSDK Rust

使用本 skill 时，把 TQSDK Rust 请求映射到正确的入口、crate、调用形态和最小代码，同时保持 workspace 的 crate 边界。

Use this skill to map TQSDK Rust requests to the correct entry points, crates, invocation patterns, and minimal code while maintaining crate boundaries within the workspace.

先路由请求

Route Requests First

只读取当前问题需要的 reference。

每个请求先读 references/scenario-router.md。按用户想持有或消费的对象分类，不要按用户第一个提到的 API 名分类。
用户不确定该用哪个 crate、或问题涉及依赖写法和 crate 边界时，读 references/crate-selection.md。
写示例代码或修复示例编译错误前，读 references/code-patterns.md。
用户要求按角色给示例、完整覆盖场景、场景契约、public API 证据，或问“每类用户应该怎么做”时，读 references/scenario-contracts.md。
策略循环、事件总线、研究、回放、测试、低延迟柜台工作流，读 references/quant-workflows.md。
凭证、权限、实盘交易、模拟、下单副作用、风控、live smoke test，读 references/safety-and-operations.md。
只有用户要求新建独立 starter project 时，才使用 scripts/new-tqsdk-rust-project.py 和 assets/templates/tq-strategy-loop。明确要求 Python-style wait starter 时才选
```
--template wait-quote-loop
```
。

Only read the references required for the current question.

For each request, first read references/scenario-router.md. Classify based on the objects users want to hold or consume, not by the first API name mentioned by the user.
When users are unsure which crate to use, or the question involves dependency writing and crate boundaries, read references/crate-selection.md.
Before writing sample code or fixing sample compilation errors, read references/code-patterns.md.
When users request role-based examples, full scenario coverage, scenario contracts, public API evidence, or ask "what should each type of user do", read references/scenario-contracts.md.
For strategy loops, event buses, research, replay, testing, and low-latency trading desk workflows, read references/quant-workflows.md.
For credentials, permissions, live trading, simulation, order side effects, risk control, and live smoke tests, read references/safety-and-operations.md.
Only use scripts/new-tqsdk-rust-project.py and assets/templates/tq-strategy-loop when users explicitly request a new independent starter project. Only select
```
--template wait-quote-loop
```
when a Python-style wait starter is explicitly requested.

核心规则

Core Rules

写代码前先选择能覆盖场景的最高层入口。普通策略、目标持仓和轻量历史访问优先从默认
```
tqsdk
```
crate 开始；明确需要内部能力时再下钻。
官方 Python TqSdk 行为是语义参考，但 Rust 要映射到 crate 归属，不要重建 Python 单体
```
TqApi
```
。
默认 facade 放在
```
tqsdk
```
；one-shot query 放在
```
tqsdk-session
```
，Python-style live ref 放在
```
tqsdk-wait
```
，事件管线放在
```
tqsdk-stream
```
，执行工具放在
```
tqsdk-task
```
，离线/历史数据放在
```
tqsdk-data
```
。
history cache 默认关闭；只有显式
```
DataClientBuilder::history_cache_enabled(true)
```
或显式
```
HistorySeriesCache::open(...)
```
cache-only reader 才生效。
```
tqsdk-data
```
不提供 live stream 写 Python-compatible mmap history cache 的 bridge；
```
tqsdk-stream
```
本身也不读写 mmap/cache，不为热路径增加持久化语义。
```
HistorySeriesCache
```
只服务 offline
```
get_*_data_series
```
/ cache-only
```
read_*_data_series
```
/ scan / maintenance；不要使用它作为 live serial 缓存或外部最新行情 API。
官方 Python serial 的
```
id
```
列来自序列路径 key / 行序号，不要求 raw Kline/Tick payload 自带
```
id
```
；Rust 解码应保持 path-key id 兼容。
只有低层 runtime、自定义 facade、adapter、command 状态机、commit/cursor、hot-path
```
RuntimeReader
```
才使用
```
tqsdk-core
```
。
所有可见状态变化都必须经过 runtime commit 和
```
RuntimeReader
```
/
```
UpdateCursor
```
；不要发明私有状态树、本地订单 overlay 或旁路通知。
live/network 示例默认需要 Tokio、凭证、行情权限，以及明确的交易权限。
优先使用
```
futures_market()
```
、
```
stock_market()
```
、
```
trade_target_tqkq()
```
、
```
enable_query()
```
这类命名 builder，不要使用裸 bool route flag。
下单示例默认使用模拟/TqKq 风格；只有用户明确要求实盘接入并接受副作用时，才给 real-account 集成。
精确 API 形状重要时，先检查目标 crate README 和
```
crates/*/examples/api_contract_sXX_*.rs
```
，再定稿代码。

Select the highest-level entry that covers the scenario before writing code. Default to the
```
tqsdk
```
crate for general strategies, target positions, and lightweight historical data access; only dive deeper when explicit internal capabilities are needed.
The official Python TqSdk behavior serves as a semantic reference, but Rust should map to crate ownership instead of rebuilding the Python monolithic
```
TqApi
```
.
Default facades are placed in
```
tqsdk
```
; one-shot queries are placed in
```
tqsdk-session
```
, Python-style live refs are placed in
```
tqsdk-wait
```
, event pipelines are placed in
```
tqsdk-stream
```
, execution tools are placed in
```
tqsdk-task
```
, and offline/historical data is placed in
```
tqsdk-data
```
.
History cache is disabled by default; it only takes effect when explicitly enabled via
```
DataClientBuilder::history_cache_enabled(true)
```
or a cache-only reader like
```
HistorySeriesCache::open(...)
```
.
```
tqsdk-data
```
does not provide a bridge to write Python-compatible mmap history cache for live streams;
```
tqsdk-stream
```
itself does not read or write mmap/cache, and does not add persistence semantics to hot paths.
```
HistorySeriesCache
```
only serves offline
```
get_*_data_series
```
/ cache-only
```
read_*_data_series
```
/ scan / maintenance; do not use it as a live serial cache or external latest market data API.
The
```
id
```
column of the official Python serial comes from the sequence path key / row number; raw Kline/Tick payloads are not required to have an
```
id
```
; Rust decoding should maintain path-key id compatibility.
Only low-level runtime, custom facades, adapters, command state machines, commit/cursor, and hot-path
```
RuntimeReader
```
use
```
tqsdk-core
```
.
All visible state changes must go through runtime commit and
```
RuntimeReader
```
/
```
UpdateCursor
```
; do not invent private state trees, local order overlays, or bypass notifications.
Live/network examples require Tokio, credentials, market data permissions, and explicit trading permissions by default.
Prefer named builders like
```
futures_market()
```
,
```
stock_market()
```
,
```
trade_target_tqkq()
```
,
```
enable_query()
```
instead of bare boolean route flags.
Order examples use simulation/TqKq style by default; only provide real-account integration when users explicitly request live access and accept side effects.
When precise API shape is important, first check the target crate README and
```
crates/*/examples/api_contract_sXX_*.rs
```
before finalizing code.

常见错误

Common Mistakes

不要用
```
tqsdk-wait
```
回答 direct-query 问题；使用
```
tqsdk-session
```
或
```
api.session()
```
。
wait/stream app 里不要为了 metadata 再建第二个 client；复用 shared session。
不要把历史下载当作 live ref；使用
```
tqsdk-data
```
。如果要持久化 live
```
KlineRowBatch
```
/
```
TickRowBatch
```
或 commit stream，使用调用方自己的 sidecar，不要把 Python-compatible mmap history cache 接进 live 热路径。
普通用户示例不要直接从 sibling crate taxonomy 起步；先尝试
```
tqsdk::prelude::*
```
/
```
Tq::futures()
```
，除非用户明确要 wait、stream、session、task、data 或 core 的完整 surface。
普通用户示例不要从
```
tqsdk-core
```
起步，除非用户明确要 runtime internals。
typed ticket、ref 或 status helper 已存在时，不要发明本地订单 overlay，也不要解析 status 字符串。
不要用字符串或 adapter-local 判断绕过
```
record_command_status()
```
和 runtime command lifecycle。
示例里不要隐藏凭证、权限或实盘订单副作用。
回答用法问题时，不要跨 crate 移动 direct query、downloader、task 或 research 语义。

Do not use
```
tqsdk-wait
```
to answer direct-query questions; use
```
tqsdk-session
```
or
```
api.session()
```
instead.
Do not create a second client for metadata in wait/stream apps; reuse the shared session.
Do not treat historical download as a live ref; use
```
tqsdk-data
```
. If you need to persist live
```
KlineRowBatch
```
/
```
TickRowBatch
```
or commit streams, use the caller's own sidecar instead of connecting Python-compatible mmap history cache to live hot paths.
Do not start with sibling crate taxonomy for general user examples; first try
```
tqsdk::prelude::*
```
/
```
Tq::futures()
```
unless users explicitly require the full surface of wait, stream, session, task, data, or core.
Do not start with
```
tqsdk-core
```
for general user examples unless users explicitly require runtime internals.
Do not invent local order overlays or parse status strings when typed ticket, ref, or status helpers already exist.
Do not bypass
```
record_command_status()
```
and runtime command lifecycle using strings or adapter-local judgments.
Do not hide credentials, permissions, or live order side effects in examples.
Do not cross crate boundaries to move direct query, downloader, task, or research semantics when answering usage questions.

回答风格

Response Style

开头先说明使用哪个入口或 crate 以及原因：默认 facade、Python-style live ref、event stream、one-shot query、task execution、offline rows 或 runtime substrate。
优先给和当前 example 匹配的短 Rust snippet，不要写大段伪代码。
覆盖用户角色或宽工作流时，引用
```
scenario-contracts.md
```
中对应的
```
api_contract_sXX_*.rs
```
示例。
点名用户下一步应调用的具体 API。
如果 Rust 答案刻意不同于 Python TqSdk，要说明原因是 Rust workspace 有默认
```
tqsdk
```
facade，并把高级能力拆成了
```
session
```
、
```
wait
```
、
```
stream
```
、
```
task
```
、
```
data
```
。
代码会下单、撤单、使用实盘账户或依赖付费行情权限时，先说明安全门槛。
请求不明确时，只问一个形状问题：“你需要一个带 ref 的单 live loop、多个事件消费者、one-shot query、task/order 抽象、历史 rows，还是 runtime commits？”

Start by explaining which entry or crate to use and why: default facade, Python-style live ref, event stream, one-shot query, task execution, offline rows, or runtime substrate.
Prefer short Rust snippets that match the current example instead of long pseudocode.
When covering user roles or broad workflows, reference the corresponding
```
api_contract_sXX_*.rs
```
examples in
```
scenario-contracts.md
```
.
Specify the exact API users should call next.
If the Rust answer intentionally differs from Python TqSdk, explain that it's because the Rust workspace has a default
```
tqsdk
```
facade and splits advanced capabilities into
```
session
```
,
```
wait
```
,
```
stream
```
,
```
task
```
, and
```
data
```
.
When code involves order placement, cancellation, live account usage, or paid market data permissions, first explain the security thresholds.
When the request is unclear, ask only one targeted question: "Do you need a single live loop with ref, multiple event consumers, one-shot query, task/order abstraction, historical rows, or runtime commits?"

验证闭环

Validation Loop

只回答用法或短 snippet 时，说明已核对的 crate README、contract example 或 reference；没能核对时明确标注。
修改本仓库 Rust API、examples 或 contract 后，至少运行
```
cargo fmt --all --check
```
和
```
cargo check --workspace --examples
```
；涉及行为时再运行相关
```
cargo test
```
。
修改本 skill、脚本或模板后，运行
```
git diff --check
```
；模板或脚本变更还要把 starter project 生成到临时目录，并在可行时运行
```
cargo check --manifest-path <tmp>/Cargo.toml
```
。
live、交易或下单 smoke test 只有在用户显式提供凭证、权限和副作用许可后才运行；否则说明未跑 live 验证。

When answering usage questions or providing short snippets, specify the crate README, contract example, or reference that has been checked; clearly mark if no check was performed.
After modifying Rust APIs, examples, or contracts in this repository, at least run
```
cargo fmt --all --check
```
and
```
cargo check --workspace --examples
```
; run relevant
```
cargo test
```
if behavior is involved.
After modifying this skill, scripts, or templates, run
```
git diff --check
```
; for template or script changes, generate the starter project to a temporary directory and run
```
cargo check --manifest-path <tmp>/Cargo.toml
```
if feasible.
Live, trading, or order smoke tests are only run if users explicitly provide credentials, permissions, and side effect consent; otherwise, state that live verification was not performed.

项目脚手架

Project Scaffolding

从内置 asset template 创建默认

tqsdk

quote loop 项目：

bash

python3 scripts/new-tqsdk-rust-project.py ./my-tqsdk-app \
  --sdk-source git \
  --sdk-value https://github.com/OWNER/tqsdk-rust \
  --symbol SHFE.au2602

本地开发使用

--sdk-source path --sdk-value /path/to/tqsdk-rust

；crate 发布后可使用

--sdk-source version --sdk-value <version>

。明确需要 Python-style wait facade starter 时，加

--template wait-quote-loop

。

Create a default

tqsdk

quote loop project from the built-in asset template:

bash

python3 scripts/new-tqsdk-rust-project.py ./my-tqsdk-app \
  --sdk-source git \
  --sdk-value https://github.com/OWNER/tqsdk-rust \
  --symbol SHFE.au2602

Use

--sdk-source path --sdk-value /path/to/tqsdk-rust

for local development; after crate release, you can use

--sdk-source version --sdk-value <version>

. Add

--template wait-quote-loop

when a Python-style wait facade starter is explicitly required.