TQSDK Rust

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

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

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

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

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

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

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.

tqsdk-rust

NPX Install

Tags

SKILL.md Content (Chinese)