tqsdk-rust

Imported from zynthium/tqsdk-rust (AGENTS.md). Install upstream with npx skills add zynthium/tqsdk-rust. Copyright stays with the author.

AGENTS.md

本文件是本仓库面向 AI 代码代理的跨工具入口。它应该保持短、可执行、低重复；不要在这里承载个人客户端配置、完整架构说明或可由 lint/CI 强制的细碎规则。

作用域与优先级

• 本文件适用于整个仓库。以后若在 crates/*/、docs/ 或其他子目录新增嵌套 AGENTS.md，更靠近目标文件的规则优先。
• CLAUDE.md 只补充 Claude Code 专属说明；若与本文件或 docs/architecture/* 冲突，以本文件和当前架构文档为准。
• docs/architecture/* 是当前架构权威；docs/reviews/、docs/superpowers/ 和 docs/archive/ 只能作为计划输入或历史记录，不能覆盖当前代码和架构文档。
• 个人工具配置、通知命令、客户端工具映射、一次性环境偏好不应写入仓库级 AGENTS.md；放到用户级配置或客户端专属文档中。

项目概况

tqsdk-rust 是面向天勤 / TQSDK 生态的 Rust Cargo workspace，使用 Rust edition 2024，MSRV 为 1.88。核心架构是“稳定底座 + 可替换 facade”：所有可见状态变化共享同一套 runtime state tree、commit/revision 和 cursor 语义，上层 crate 只演进用户使用形态。

开始任务前

• 修改文件前先查看 git status --short，识别用户已有改动；不要覆盖、回滚或提交未授权修改。
• 先分类任务：docs-only、局部实现、public API/facade、runtime contract、架构边界变更。
• 只读当前任务必要上下文。不要无目的通读大文档，不要全仓扫文件列表。
• 小步聚焦：只改完成当前任务必须触碰的文件，不顺手重构无关模块。
• 对外部账号、实盘、交易、转账、撤单或 live smoke 相关操作保持显式用户授权和环境变量门控。

最小上下文路由

工具策略

• 可用时优先用图谱工具理解代码和影响面；不可用或不覆盖目标文件时，再回退到 rg、sed -n 等定向读取。
• 修改 Rust 函数、方法或类型前，先做 impact analysis；如果风险为 HIGH 或 CRITICAL，先向用户报告直接调用方、受影响流程和风险再继续。
• GitNexus 适合影响面、执行流和提交前 detect changes；CodeGraph 适合源码定位、调用关系和读取已索引源文件。
• 普通文本搜索用 rg；不要用慢速全仓 grep，不要用字符串替换做重命名。
• 只改文档且不修改 Rust 符号时，不需要符号级 impact analysis。
• 提交前若 GitNexus 可用，应运行 detect changes 检查影响范围；未提交时不必为了文档-only 改动强行运行。

Codex 多代理路由

• 默认不委派。只有已确认 HIGH/CRITICAL 风险，或明确需要 public API、并发、持久化、迁移、安全的独立审查时，才读取 docs/architecture/ai-workflow.md 的“Codex 多代理路由”并使用 .codex/agents/architecture_reviewer.toml。
• 每个任务最多一个只读 reviewer；主代理负责探索、实现、验证、风险升级和结果整合，reviewer 不得继续委派。

工具自动管理区

下面的 marker 块由工具生成或更新。保持 marker 和内容完整；如果需要收敛说明，优先调整上方人工规则，不要手工删除自动块。

GitNexus — Code Intelligence

This project is indexed by GitNexus as tqsdk-rust (19516 symbols, 58260 relationships, 964 execution flows).

Index stale? Run node .gitnexus/run.cjs analyze --index-only from the project root — it auto-selects an available runner. No .gitnexus/run.cjs yet? Bootstrap with npx, bunx, or pnpm dlx — e.g. bunx gitnexus@latest analyze (npm 11 npx crash; #1939).

Always Do

• MUST run impact analysis before editing. Use impact({target: "symbolName", direction: "upstream"}) (MCP) or node .gitnexus/run.cjs impact "symbolName" --direction upstream --repo . (CLI fallback); report callers, processes, and risk. Never substitute grep for graph analysis.
• MUST analyze graph changes before committing. Use detect_changes({scope: "all"}) (MCP) or node .gitnexus/run.cjs detect-changes --scope all --repo . (CLI fallback). partial: true or truncated: true is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review: detect_changes({scope: "compare", base_ref: "main"}) or node .gitnexus/run.cjs detect-changes --scope compare --base-ref "main" --repo ..
• MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
• MUST treat risk: UNKNOWN as unresolved, not as low. An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls). impact pairs UNKNOWN with a riskNote saying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero.
• When exploring unfamiliar code, use query({search_query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
• When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use context({name: "symbolName"}).
• For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).

Never Do

• NEVER edit a function, class, or method before MCP/CLI impact analysis.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read UNKNOWN as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
• NEVER rename symbols with find-and-replace — use rename which understands the call graph.
• NEVER commit before MCP/CLI graph change analysis.

Resources

CLI

CodeGraph

In repositories indexed by CodeGraph (a .codegraph/ directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:

• MCP tools (when available): codegraph_explore answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. codegraph_node returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.
• Shell (always works): codegraph explore "<symbol names or question>" and codegraph node <symbol-or-file> print the same output.

If there is no .codegraph/ directory, skip CodeGraph entirely — indexing is the user's decision.

架构硬边界

• tqsdk-core 只负责命令、状态、commit/revision、cursor、adapter、schema types 与底层 runtime contract；不要把 facade、direct query、task/data/downloader 语义塞回 core。
• tqsdk 只做默认入口、prelude、轻量 wrapper 和 curated re-export；不得拥有第二棵状态树、第二套 runtime、第二套 direct query / task / data 实现。
• tqsdk-session 负责 shared session、one-shot request/response/direct-query、GraphQL、schema、metadata、calendar、ranking、EDB、auth refresh、replay control。
• tqsdk-wait 只做 single-owner diff-backed continuous consumption；可以通过 session() 复用底层 session，但不得复制 direct query API。
• tqsdk-task 是执行工具层；tqsdk-data 是 research/offline data 层；不要把 task/data 能力下沉回 core/session/wait 或调用方自建消费层。
• tqsdk-hard-risk 是调用方/上层服务显式选择的 single-host durable admission authority；只能向下依赖，不能把 SQLite/WAL、audit、跨进程 recovery 反向塞入 core/session/wait/task 或 TradingDeskProfile。它不拥有 broker send、runtime state tree 或多节点 HA；ambiguous submit 必须 fail closed 为 Indeterminate 并由完整 trade snapshot 对账。
• tqsdk-relay 是可选 market relay/cache service；它是 workspace member 但不属于 Cargo default-members；不要让现有 SDK crates 默认依赖 relay，也不要把 relay 扩展成通用天勤代理或多 provider 聚合框架。
• relay history 只允许作为独立 listener/runtime 的本地 CacheOnly sibling：查询/manifest/lease primitive 归 tqsdk-data，发布/恢复/GC 归 tqsdk-cache；不得进入 RelayEngine、获取 market mutex、RemoteOnMiss、读取远端凭证或直接解析 cache 文件。
• 所有可见状态变化必须经过 RuntimeHandle -> StateStore -> CommitResult -> RuntimeReader/UpdateCursor。不得新增旁路通知、第二棵状态树或 facade 私有 revision。
• domain 状态写入必须经过 MutationSource 根路径防线。hot read 优先使用 read_market_state()、read_trade_state()、read_market_trade_state()。
• command/order 状态必须遵守 runtime 状态机。不得用字符串或 adapter 本地判断绕过 record_command_status() 的转换校验。
• core public surface 保持克制。不要重新导出 TqAuthProvider、PasswordCredentials、BrokerInfo、TqKqAccountConfig、ReqwestHttpExecutor、ContractFuture 等已收口的实现细节。

如果不确定改动类别，按更高风险类别处理。任何移动 crate 归属、public API、runtime contract、feature flags 或 facade 边界的改动，都必须同步更新架构文档和受影响 crate README。

开发工作流

1. 分类：判断是 docs-only、局部实现、public API/facade、runtime contract，还是架构边界变更。
2. 探索：用图谱或定向搜索获取最小上下文；修改符号前先做影响面分析。
3. 实现：遵循现有模块边界、error 类型、async 风格和测试组织；不要新增无关抽象。
4. 同步：如果属于架构更新，按本文架构更新规则同轮更新文档。
5. 验证：选择最小但足够的验证命令；需要真实账号、实盘权限或 live smoke 的命令必须由用户明确要求。
6. 收尾：提交前确认暂存区只包含本轮改动；完成闭环的 spec / plan / review 文档迁入 docs/archive/superpowers/，当前架构权威文档不要自动归档。

环境与敏感配置

• 普通开发不需要真实天勤账号；live 行情、交易、query 和历史数据示例才需要 TQ_AUTH_USER / TQ_AUTH_PASS 及更细的 TQ_* 环境变量。
• 账号、密码、token、私钥、客户数据和敏感基础设施信息不得写入仓库、日志、测试快照或提交说明。
• 可能连接实盘或产生交易副作用的示例/测试必须保持 ignored 或显式环境变量门控。
• 任何可能真实下单、撤单、转账或访问实盘账号的命令，必须由用户明确要求并由环境变量门控。

常用验证命令

文档-only 或工作流入口改动：

git diff --check

Rust 代码快速自检：

cargo check --examples

可提交单元的默认验证：

cargo test
cargo clippy --examples --all-targets -- -D warnings

格式化相关改动：

cargo fmt --all --check

修改 feature flags、workspace 依赖或 crate feature 传播时，补充：

cargo check --no-default-features
cargo check --no-default-features --examples
cargo test -p tqsdk-session --no-default-features
cargo check --all-features --examples

release-check 环境还应对齐：

cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo deny check
cargo package --no-verify
cargo test -p tqsdk-relay --tests
cargo clippy -p tqsdk-relay --all-targets -- -D warnings
cargo check -p tqsdk-relay --no-default-features
RUSTDOCFLAGS="-D warnings" cargo doc -p tqsdk-relay --no-deps --all-features

场景驱动 public API example 是正式契约。改动 public API、crate 拆分、feature flags 或 facade/runtime 消费方式后，必须保证 crates/*/examples/api_contract_sXX_*.rs 能继续清晰、可编译地表达目标场景。

架构更新规则

以下行为属于架构更新，不能“顺手改”：

• 新增、删除或重命名 crate
• 移动 direct query、live consumption、task/data 能力归属
• 改变 RuntimeHandle、RuntimeReader、UpdateCursor、CommitResult 的语义
• 改变状态树、domain partition、mutation guard、command lifecycle 规则
• 扩大或收窄 core/session/facade public surface
• 改变 feature flags 或依赖裁剪策略，导致用户选择路径变化
• 引入新的 session ownership、actor、cache、aggregation 或 multi-source 模型

同一轮改动必须同步更新相关权威文档：

• docs/architecture/ai-workflow.md
• docs/architecture/README.md
• 受影响的架构专题文档
• 受影响 crate 的 README.md
• 根 README.md，如果用户可见入口变化
• AGENTS.md / CLAUDE.md，如果 AI 工作流入口或硬约束变化
• docs/architecture/validation.md，如果验收命令、contract tests 或风险面变化

提交或最终说明中应明确是否属于架构更新；如果没有更新架构文档，也要说明原因。

DIFF 协议查阅规则

只有当任务涉及修改 WebSocket 数据报文、状态树字段、DIFF 合并、行情/交易同步机制时，才查阅 docs/diff_protocol_spec.md。不要在 session 开始时或无针对性地全文读取。

查阅步骤：

1. 先用 rg 在 docs/diff_protocol_spec.md 中检索特定 aid、状态路径或字段名。
2. 再按相关章节定向读取小范围内容，例如 sed -n '129,216p' docs/diff_protocol_spec.md。
3. 只读取与当前改动相关的章节。

常用范围：

维护规则

• 根 AGENTS.md 应保持为高信号入口，避免超过约 200 行；细节放入架构文档、crate README 或嵌套 AGENTS.md。
• 不要在本文件复制 README、完整验证矩阵、长协议索引、个人通知命令或客户端私有工具映射。
• 新增长期规则时，写成可执行约束；能由 formatter、clippy、CI 或 tests 强制的内容，不要用自然语言重复。
• 如果某个目录规则持续增长，优先新增该目录的嵌套 AGENTS.md，不要继续膨胀根文件。