Update Version 3.9.2

Author: shinny-hongyan

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tqsdk
-Version: 3.9.1
+Version: 3.9.2
 Summary: TianQin SDK
 Home-page: https://www.shinnytech.com/tqsdk
 Author: TianQin
@@ -85,6 +85,20 @@ TqSdk提供的功能可以支持从简单到复杂的各类策略程序：
 
 * **配合天勤AI助手**，提供函数解释、策略编写指导、错误分析等支持
 
+## 配合 AI / Agent 使用 TqSdk
+
+如果你想让自己的 AI、Agent 或 OpenClaw 更好地理解和使用 TqSdk，可以把下面这段内容直接复制给它：
+
+> 请先下载并解压 TqSdk 技能包：https://doc.shinnytech.com/tqsdk/latest/ai_editor/skills/tqsdk-trading-and-data.zip，然后先阅读其中的 SKILL.md，并按里面的说明再回答任何 TqSdk 问题或编写任何 TqSdk 代码。
+
+相关文档与资源：
+
+* [通过 AI 工具使用 TqSdk](https://doc.shinnytech.com/tqsdk/latest/ai_editor/index.html)
+* [在 Trae 中高效学习和使用 TqSdk](https://doc.shinnytech.com/tqsdk/latest/ai_editor/tqsdk_trae.html)
+* [使用 Codex 协作开发 TqSdk 项目](https://doc.shinnytech.com/tqsdk/latest/ai_editor/tqsdk_codex.html)
+* [TqSdk Skills 压缩包与使用说明](https://doc.shinnytech.com/tqsdk/latest/ai_editor/tqsdk_skills.html)
+* [下载 TqSdk 技能包 `tqsdk-trading-and-data.zip`](https://doc.shinnytech.com/tqsdk/latest/ai_editor/skills/tqsdk-trading-and-data.zip)
+
 ## 安装方法
 
 TqSdk 仅支持 Python 3.8 及更高版本。要安装 TqSdk，可使用 pip：

README.md

@@ -69,6 +69,20 @@ TqSdk提供的功能可以支持从简单到复杂的各类策略程序：
 
 * **配合天勤AI助手**，提供函数解释、策略编写指导、错误分析等支持
 
+## 配合 AI / Agent 使用 TqSdk
+
+如果你想让自己的 AI、Agent 或 OpenClaw 更好地理解和使用 TqSdk，可以把下面这段内容直接复制给它：
+
+> 请先下载并解压 TqSdk 技能包：https://doc.shinnytech.com/tqsdk/latest/ai_editor/skills/tqsdk-trading-and-data.zip，然后先阅读其中的 SKILL.md，并按里面的说明再回答任何 TqSdk 问题或编写任何 TqSdk 代码。
+
+相关文档与资源：
+
+* [通过 AI 工具使用 TqSdk](https://doc.shinnytech.com/tqsdk/latest/ai_editor/index.html)
+* [在 Trae 中高效学习和使用 TqSdk](https://doc.shinnytech.com/tqsdk/latest/ai_editor/tqsdk_trae.html)
+* [使用 Codex 协作开发 TqSdk 项目](https://doc.shinnytech.com/tqsdk/latest/ai_editor/tqsdk_codex.html)
+* [TqSdk Skills 压缩包与使用说明](https://doc.shinnytech.com/tqsdk/latest/ai_editor/tqsdk_skills.html)
+* [下载 TqSdk 技能包 `tqsdk-trading-and-data.zip`](https://doc.shinnytech.com/tqsdk/latest/ai_editor/skills/tqsdk-trading-and-data.zip)
+
 ## 安装方法
 
 TqSdk 仅支持 Python 3.8 及更高版本。要安装 TqSdk，可使用 pip：

doc/_includes/tqsdk_ai_agent_intro.rst

@@ -0,0 +1,9 @@
+如果你想让自己的 AI、Agent 或 OpenClaw 更好地理解和使用 TqSdk，可以把下面这段内容直接复制给它：
+
+::
+
+   请先下载并解压 TqSdk 技能包：https://doc.shinnytech.com/tqsdk/latest/ai_editor/skills/tqsdk-trading-and-data.zip，然后先阅读其中的 SKILL.md，并按里面的说明再回答任何 TqSdk 问题或编写任何 TqSdk 代码。
+
+.. tqsdk_skills_ref_marker
+
+详细说明请见 :ref:`tqsdk_skills` 。

doc/advanced/for_ctp_user.rst

@@ -2,7 +2,9 @@
 
 TqSdk与使用Ctp接口开发策略程序有哪些差别
 =================================================
-如果您曾经直接使用CTP接口开发过交易策略程序, 目前刚开始接触 TqSdk, 下面的信息将帮助您尽快理解 TqSdk.
+如果您曾经直接使用 CTP 接口开发过交易策略程序，现在刚开始接触 TqSdk，下面的信息将帮助您尽快理解 TqSdk。
+
+如果你只是想先跑通一套最小程序，建议先看 :ref:`quickstart` 和 :ref:`framework`；本文更适合在迁移已有代码时对照阅读。
 
 
 系统整体架构
@@ -108,10 +110,10 @@ TqSdk则不使用事件回调机制. :py:meth:`~tqsdk.TqApi.wait_update` 函数
 
 TqSdk针对行情数据和交易信息都采用相同的 wait_update/is_changing 方案. 用户需要记住的要点包括:
 
-* get_quote, get_kline_serial, insert_order 等业务函数返回的是一个引用(refrence, not value), 它们的值总是在 wait_update 时更新.
-* 用户程序除执行自己业务逻辑外, 需要反复调用 wait_update. 在两次 wait_update 间, 所有数据都不更新
-* 用 insert_order 函数下单, 报单指令实际是在 insert_order 后调用 wait_update 时发出的. 
-* 用户程序中需要避免阻塞, 不要使用 sleep 暂停程序
+* get_quote、get_kline_serial、insert_order 等业务函数返回的是引用对象（reference, not value），它们的字段会在 wait_update 返回后刷新。
+* 用户程序除执行自己业务逻辑外，还需要反复调用 wait_update；在两次 wait_update 之间，数据不会继续推进。
+* 用 insert_order 函数下单后，还要继续调用 wait_update，报单指令才会真正发出。
+* 用户程序中需要避免阻塞，不要直接用 sleep 暂停主循环；如果需要定时控制，请参考 :ref:`timer`。
 
 关于 wait_update 机制的详细说明, 请见 :ref:`framework`
 

doc/advanced/for_vnpy_user.rst

@@ -4,6 +4,8 @@ TqSdk 与 vn.py 有哪些差别
 =================================================
 TqSdk 与 vn.py 有非常多的差别. 如果您是一位有经验的 vn.py 用户, 刚开始接触 TqSdk, 下面的信息将帮助您尽快理解 TqSdk.
 
+如果你只是想先跑通一套最小程序，建议先看 :ref:`quickstart` 和 :ref:`framework`；本文更适合在迁移已有策略代码时对照阅读。
+
 
 系统整体架构
 -------------------------------------------------
@@ -31,7 +33,7 @@ TqSdk 则使用基于网络协作的组件设计. 如下图:
 * 交易相关接口被大幅度简化, 不再需要处理CTP接口的复杂回调, 也不需要发起任何查询请求
 
 
-对于需要直连期货公司交易的用户, TqSdk 也提供了 :py:meth:`~tqsdk.TqCtp` 模块支持用户直连
+对于需要直连期货公司交易的用户, TqSdk 也提供了 :py:class:`~tqsdk.TqCtp` 模块支持用户直连
 
 
 每个策略是一个单独运行的py文件
@@ -215,10 +217,10 @@ TqSdk则不使用事件回调机制. :py:meth:`~tqsdk.TqApi.wait_update` 函数
 
 TqSdk针对行情数据和交易信息都采用相同的 wait_update/is_changing 方案. 用户需要记住的要点包括:
 
-* get_quote, get_kline_serial, insert_order 等业务函数返回的是一个引用(refrence, not value), 它们的值总是在 wait_update 时更新.
-* 用户程序除执行自己业务逻辑外, 需要反复调用 wait_update. 在两次 wait_update 间, 所有数据都不更新
-* 用 insert_order 函数下单, 报单指令实际是在 insert_order 后调用 wait_update 时发出的. 
-* 用户程序中需要避免阻塞, 不要使用 sleep 暂停程序
+* get_quote、get_kline_serial、insert_order 等业务函数返回的是引用对象（reference, not value），它们的字段会在 wait_update 返回后刷新。
+* 用户程序除执行自己业务逻辑外，还需要反复调用 wait_update；在两次 wait_update 之间，数据不会继续推进。
+* 用 insert_order 函数下单后，还要继续调用 wait_update，报单指令才会真正发出。
+* 用户程序中需要避免阻塞，不要直接用 sleep 暂停主循环；如果需要定时控制，请参考 :ref:`timer`。
 
 关于 wait_update 机制的详细说明, 请见 :ref:`framework`
 

doc/advanced/index.rst

@@ -2,20 +2,42 @@
 
 进阶主题
 ========================================
-这一部分内容提供给有经验的 TqSdk 用户, 主要讲解将 TqSdk 用于实际工作时的一些重要问题的处理方案和最佳实践.
+这一部分内容提供给有经验的 TqSdk 用户，聚焦实盘落地、策略组织、外部集成和复杂场景下的最佳实践。
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
+    :caption: 交易执行与风控
 
     order.rst
-    backtest.rst
-    multi_strategy.rst
+    targetpostask2.rst
+    emergency_stop.rst
     tq_trading_unit.rst
+
+.. toctree::
+    :maxdepth: 1
+    :caption: 策略组织与调度
+
+    multi_strategy.rst
+    scheduler.rst
+    unanttended.rst
+
+.. toctree::
+    :maxdepth: 1
+    :caption: 回测与运行
+
+    backtest.rst
     gui.rst
     dingding.rst
+
+.. toctree::
+    :maxdepth: 1
+    :caption: 定时控制
+
+    timer.rst
+
+.. toctree::
+    :maxdepth: 1
+    :caption: 生态集成
+
     for_vnpy_user.rst
     for_ctp_user.rst
-    unanttended.rst
-    emergency_stop.rst
-    targetpostask2.rst
-    scheduler.rst

doc/advanced/timer.rst

@@ -1,4 +1,65 @@
+.. _timer:
+
 定时器
 =================================================
-This part of the documentation covers the installation of Requests. The first step to using any software package is getting it properly installed.
+
+在 TqSdk 里，定时逻辑通常不是单独开一个 ``sleep`` 循环，而是和 :py:meth:`~tqsdk.TqApi.wait_update` 结合在同一个主循环里执行。这样可以保证订阅、下单、撤单以及后台任务仍然持续被驱动。
+
+优先使用“行情时间”而不是本机时间
+-------------------------------------------------
+
+如果你的逻辑和交易时段、收盘前平仓、定时检查等场景有关，优先使用 ``quote.datetime`` 代表的行情时间::
+
+    from datetime import datetime
+    from tqsdk import TqApi, TqAuth, TargetPosTask
+
+    api = TqApi(auth=TqAuth("快期账户", "账户密码"))
+    quote = api.get_quote("SHFE.rb2405")
+    target_pos = TargetPosTask(api, "SHFE.rb2405")
+    close_hour, close_minute = 14, 50
+
+    while True:
+        api.wait_update()
+        if api.is_changing(quote, "datetime"):
+            now_time = datetime.strptime(quote.datetime, "%Y-%m-%d %H:%M:%S.%f")
+            if now_time.hour == close_hour and now_time.minute >= close_minute:
+                print("临近收盘，平仓")
+                target_pos.set_target_volume(0)
+                break
+
+这种方式的好处是：你的定时判断和交易所时间保持一致，不依赖本机时钟是否漂移。
+
+用 deadline 做“等待一段时间后继续”
+-------------------------------------------------
+
+:py:meth:`~tqsdk.TqApi.wait_update` 提供了 ``deadline`` 参数。它接收的是 ``time.time()`` 风格的 unix 时间戳，适合做“最多再等多久”的控制::
+
+    import time
+    from tqsdk import TqApi, TqAuth
+
+    api = TqApi(auth=TqAuth("快期账户", "账户密码"))
+    quote = api.get_quote("SHFE.rb2405")
+
+    while True:
+        api.wait_update()
+        if api.is_changing(quote, "datetime"):
+            print("收到一次关键更新，接下来最多再等 60 秒")
+            deadline = time.time() + 60
+            while api.wait_update(deadline=deadline):
+                pass
+            print("等待结束，继续执行后续逻辑")
+
+这类写法适合：
+
+* 收盘前平仓后再等待一小段时间，确认撤单和回报处理完毕
+* 给某个阶段性任务一个最长等待时间，避免长时间阻塞
+* 在同步主循环里做简单的“超时退出”控制
+
+常见误区
+-------------------------------------------------
+
+* 不要在主循环里频繁使用 ``time.sleep()``, 否则会阻塞 ``wait_update``，数据和后台任务都会停下来
+* ``deadline`` 是 unix 时间戳，不是“秒数”本身；通常写成 ``time.time() + 60``
+* 如果你在定时逻辑里调用了 ``insert_order`` 或 ``TargetPosTask.set_target_volume``，后面仍然要继续调用 ``wait_update``，否则报单不会真正发出
+* 如果策略已经采用协程任务，优先考虑 :py:meth:`~tqsdk.TqApi.register_update_notify`，不要把同步和异步等待方式混在一起
 

doc/advanced/tq_trading_unit.rst

@@ -102,6 +102,57 @@ TqSdk 多策略使用手册
 .. image:: ../images/tq_zq_broker.png
 
 
+日志导出
+=========
+如果您在使用过程中遇到问题，您可以把日志发给我们来帮助您查询
+
+导出日志前，需要先关闭 zq_server 和 zq_server_history_go 两个进程，然后打包日志目录并发送给我们
+
+**Linux**:
+
+.. code-block:: bash
+
+    pkill -f zq_server_history_go
+    pkill -f zq_server
+    tar -czf ~/tqsdk_zq_log.tar.gz -C ~ .tqsdk/zq/log
+
+**Windows** (PowerShell):
+
+.. code-block:: powershell
+
+    taskkill /F /IM zq_server_history_go.exe 2>$null
+    taskkill /F /IM zq_server.exe 2>$null
+    cd $env:USERPROFILE
+    tar -czf tqsdk_zq_log.tar.gz .tqsdk/zq/log
+
+压缩完成后，将生成的 ``tqsdk_zq_log.tar.gz`` 文件发送给我们即可
+
+
+重置本地环境
+-------------------------------------------------
+如果你想彻底清空所有本地数据，重新开始使用众期多策略系统，可以执行以下命令来重置本地环境：
+**Linux**:
+
+.. code-block:: bash
+
+    pkill -f zq_server_history_go
+    pkill -f zq_server
+    pkill -f sock-proxy
+    pkill -f postgres
+    rm -rf ~/.tqsdk/zq
+
+**Windows** (PowerShell):
+
+.. code-block:: powershell
+
+    taskkill /F /IM zq_server_history_go.exe 2>$null
+    taskkill /F /IM zq_server.exe 2>$null
+    taskkill /F /IM sock-proxy.exe 2>$null
+    taskkill /F /IM postgres.exe 2>$null
+    Remove-Item -Recurse -Force $env:USERPROFILE\.tqsdk\zq
+
+删除之后可以使用 ``tqsdk-zq init`` 来重新初始化环境
+
 其他事项
 =========
 - 当用户在众期多策略系统中添加实盘账户时，仍然占用企业版3个实盘账户的名额，如果需要额外购买实盘账户名额请联系我们的商务同事 QQ:1539404802

doc/ai_editor/index.rst

@@ -3,10 +3,22 @@
 通过 AI 工具使用 TqSdk
 ========================================
 
+这一部分介绍如何在不同 AI 编码工具中接入 TqSdk，并复用配套 skills 与研究模板。
+
+AI 编辑器接入
+----------------------------------------
+
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     tqsdk_trae.rst
     tqsdk_codex.rst
+
+技能与研究模板
+----------------------------------------
+
+.. toctree::
+    :maxdepth: 1
+
     tqsdk_skills.rst
     nl_research.rst