前言

趋势策略用 TargetPosTask 很省心，但有些场景必须限价挂单等待成交：例如固定价位补单、做市式报价、或要求「挂出去、未成再撤再挂」。手写 insert_order + 轮询 order.status，容易漏撤单、漏部分成交、或在同一帧重复下单。

天勤 TqSdk 在 tqsdk.lib 里提供 InsertOrderTask 等任务类，把「挂单—等待—撤单」封装进与 wait_update 协作的模型。下面说明适用场景、最小用法、与主循环关系，具体 API 以当前文档为准。

一、什么情况下用手写报单链太累

• 限价单挂在盘口，要直到成交或超时撤单
• 部分成交后 remainder 如何处理要一致
• 同一策略里多处下单，状态变量散落

若只是「目标净仓 = 3」，优先 TargetPosTask；限价挂单是执行层细节，再考虑 InsertOrderTask。

二、任务类与 wait_update 的关系

TqSdk 推荐在 while True: api.wait_update() 里驱动。InsertOrderTask 在每次 wait_update 后推进内部状态，你只需创建任务并在循环里调用其更新方法（以文档示例为准，常见模式如下）：

from tqsdk import TqApi, TqAuth, TqSim
from tqsdk.lib import InsertOrderTask

api = TqApi(TqSim(), auth=TqAuth("账户", "密码"))
symbol = "SHFE.rb2510"
quote = api.get_quote(symbol)

# 参数名、方向、开平以 reference/tqsdk.lib.rst 为准
task = InsertOrderTask(api, symbol, direction="BUY", offset="OPEN",
                       volume=1, limit_price=3500)

while True:
    api.wait_update()
    task.update()  # 若文档为其他方法名，以文档为准
    if task.is_finished():  # 或文档中的完成判断
        print("order task done", task.order)
        break
api.close()

上线前在模拟盘对照文档核对：update/is_finished 等名称随版本可能调整，以你安装的 tqsdk 为准。

三、与 insert_order 手写对比

方式	适合
insert_order 一次	市价或立即关心下一帧状态
InsertOrderTask	限价持续有效、需自动撤改
InsertOrderUntilAllTradedTask	必须全部成交才继续（另文）

手写时要自己对 order.volume_left、order.status 做状态机；任务类把常见路径封装，减少漏分支。

四、集成到策略主循环

不要把 InsertOrderTask 放在没有 wait_update 的代码路径里。典型结构：

1. 信号层判定「需要挂限价单」
2. 创建 InsertOrderTask，记录 task 引用
3. 主循环每帧 task.update()，直到完成或超时
4. 完成后再恢复信号逻辑或设 TargetPosTask

同一 symbol 避免同时多个未完成任务，否则撤单对象可能搞混。

五、注意边界

• 涨跌停、非交易时段报单会失败，任务类不替代时段过滤。
• 部分成交后策略总目标仓仍要对齐 position。
• 模拟与实盘撮合不同，限价挂单在 TqSim 里先测行为。

总结

限价挂单反复漏撤单、漏部分成交，根因通常是手写 insert_order 却没有与 wait_update 同步的状态机。若策略目标是净仓、追价不紧，优先 TargetPosTask；若必须「挂限价、等待、未成再撤再挂」，再考虑 tqsdk.lib 里的 InsertOrderTask，在每次 wait_update 后调用文档规定的 update（及完成判断），直到任务结束再恢复信号逻辑。

集成时注意：同一 symbol 避免多个未完成任务并行；涨跌停与非交易时段仍会拒单，任务类不替代时段过滤；部分成交后总仓位仍要对齐 position。模拟与实盘撮合不同，限价排队行为须在 TqSim 或 TqKq 里先测「成交 / 撤单 / 超时」是否符合预期。

建议以本地 reference/tqsdk.lib.rst 官方示例为准跑通一轮（方法名随版本可能变化），再嵌入信号模块；上线前用日志记录每次 task 创建、完成、撤单原因，便于与客户端委托列表对照。

FAQ

1）和 TargetPosTask 能同时用吗？

可以，注意同一合约委托冲突，先完成挂单 task 再调目标仓。

2）超时怎么设？

以 lib 文档参数为准，无则外层计时器 + 主动 cancel。

3）多合约多个 task？

每个合约独立 task 实例，循环内逐个 update。

4）回测能用吗？

视回测撮合是否支持限价排队，需实测。

风险提示

本文用于程序化交易技术说明，不构成投资建议。