模拟实盘手工冒烟方案（live_grid_multi）

亲爱的用户，本章是一份**手工验收清单**：在真实交易日（或您方便的时间段），用仓库示例 examples/live_grid_multi.py 跑一遍模拟实盘，逐项打勾，确认 qteasy 行为与文档一致。

> 冒烟测试是什么？ > 像新船下水前的试航——不必覆盖所有策略，而是用**固定示例 + 固定检查项**快速发现「能不能用、日志能不能看懂」。本手册侧重 真实 ``qt.run`` + 人眼验收；非交易时段也可用仓库内无头脚本做架构回归（见下文）。

策略基线：``examples/live_grid_multi.py``（5 分钟 VS + 多标的网格）。 维护者若需对照内部路线图，可参考仓库 ``.cursor/plans/trader架构升级路线图_0650f0d5.plan.md``（可选，非阅读必需）。

与无头脚本的关系

  • tests/notebook_trader_headless_script.py 提供分阶段无头冒烟（含 5-A/5-B、5-C 等），可在 Notebook 分 cell 调用。

  • **本手册**侧重：您亲自启动 live、看 CLI/日志、打勾。

  • 建议节奏：**交易日**按本手册；**休市**用无头脚本补回归。

一、环境与前置条件

  1. Python：推荐 /opt/anaconda3/envs/py39/bin/python。若您通过 pip 安装 qteasy，工作目录可以是任意包含 examples/live_grid_multi.py 的路径（不必克隆全仓库，但需能访问示例脚本）。

  2. **新账户、无持仓**（避免旧订单干扰）：

    • -n/--new_account <用户名> 创建新账户；或

    • 已有 account_id 且 --restart 清空记录，并确认无持仓后再启。

  3. 数据：分钟策略需本地有 stock_1min 等表；首次 refill 可能较久，属正常。

  4. 日志：sys_log_file_path、trade_log_file_path 可写（用 artifacts 核对）。

二、启动命令模板

在含示例的目录执行（按您的账户调整）:

/opt/anaconda3/envs/py39/bin/python examples/live_grid_multi.py \\
    -a <ACCOUNT_ID> -n <NEW_USER_NAME_OR_OMIT> \\
    --ui cli \\
    [--debug] [--restart]

说明：

  • 冷启动：新建 -n 或 --restart 后确认持仓为空。

  • 勿在不明环境放大 trade_batch，以免资金压力。

  • 5-C 相关 CLI 建议加 --debug，以便 run --task diagnose_pending_orders。

三、分阶段验收（逐项打勾）

下列阶段对应内部路线图 0～5-C / 阶段 11；每项含 本阶段在验证什么、操作与验收。

阶段 0：基线、状态机与可观测性

验证什么：Trader 能正常启动、状态迁移合理、日志能还原「启动 → 日程 → 关键任务」顺序。

  • 操作：观察 CLI/日志中状态（stopped → sleeping/running 等）与任务入队。

  • 验收：无未解释死锁；能还原一次完整启动时间线。

阶段 1：规范退出

验证什么：正常 stop/退出后资源释放，断点与日志无异常截断。

  • 操作：用 Shell 正常退出，勿强杀进程。

  • 验收：无僵尸线程；日志完整。

阶段 2：任务调度与 SKIP

验证什么：异步拉价与策略任务边界清晰；跳过任务时日志含可读的 skip_reason。

  • 操作：观察 acquire_live_price、run_strategy 等调度。

  • 验收：异常/跳过可解释、可统计。

阶段 3：日程与 catch-up

验证什么：同一配置下日程可复现；盘中启动的「补跑」行为与文档一致。

  • 操作：对比同日两次关键任务时刻，或盘中启动一次。

  • 验收：日程输出可复现。

阶段 3.5：成交入账一致性

验证什么：成交后现金/持仓/订单一致，无重复扣款。

  • 操作：至少一笔模拟成交后核对账本。

  • 验收：无「半提交」矛盾。

阶段 4-A：成交回报路径

验证什么：成交经 poll_fills 等公开路径消费，整日 sim 可稳定运行。

  • 操作：跑满半个交易日或整日。

  • 验收：无内部队列类报错栈。

阶段 4-B：SKIP 原因分桶

验证什么：日志中 skip_reason= 可人工归类（如 gate_failed、snapshot_stale）。

  • 操作：检索 skip_reason=。

  • 验收：字段齐全、含义可懂。

阶段 5-A：策略快照

验证什么：开启 split 后，prepare 在 run 之前；快照过期时跳过有日志。

  • 操作：先 live_trade_split_strategy_prepare=False 作基线；再 True 并设 live_trade_prepare_lead_seconds、live_trade_strategy_snapshot_max_age_seconds``（须在 ``qt.run 前 configure）。

  • 验收：日程/日志见 prepare；snapshot_stale 可解释。

阶段 5-B：启动门禁

验证什么：warn 只告警；block 在严重失败时阻断策略入队。

  • 操作：分档试 warn / block；Shell 执行 gate。

  • 验收：block 不误杀正常交易日（先 warn 灰度）。

阶段 11 / 5-C：映射、轮换、诊断、对账

验证什么：券商号回写、risk 日志轮换、在途单诊断、收盘对账 JSON。

  1. 订单映射 — 成功单有 broker_order_id；柜台拒单 rejected 且 broker 空；风控拒单无新订单行、risk_log 有 <RISK REJECTED>。

  2. 产物与轮换 — artifacts 四键可写；rotatelogs --days 30 清理超期 *.risk.log。

  3. 在途单诊断 — DEBUG：run --task diagnose_pending_orders，字段齐全。

  4. post_close — reconcile JSON 含 is_ok、failures 等。

四、与 live_grid_multi 相关的补充

  • 多标的 VS + multi_pars：各标的网格参数首日初始化合理。

  • 子日频 refill：冒烟日可先缩小 refill 表，仅保留 stock_1min 等最小集。

  • 验收：无持仓起步下首日行为与示例逻辑一致；无 NaN 价误成交。

五、Notebook 无头冒烟（可选）

休市时在 Notebook 中可调用 tests/notebook_trader_headless_script.py 各 stage* 函数；详见脚本内注释。与手工 live 可二选一或组合。

六、当日收工简表

手工冒烟结束时，可用下表快速勾选「今天测到哪一步」。各行对应上文第三部分的阶段编号；**您执行的动作摘要**请按实际填写，**打勾标准**来自该阶段验收说明。本表范围覆盖路线图 0～5-C / 阶段 11，不含 Broker/QMT 接入（见 券商适配层与集成）。

各列含义：**阶段**为路线图编号；**您执行的动作摘要**由您记录；**打勾标准**为通过该阶段的最小条件。

如何使用：冒烟过程中完成某阶段后，在「动作摘要」列写一句（如「warn 模式下 gate 通过」），达标则在心中或副本上打勾；未达标则记入 §七记录模板的「结论」列。

阶段

动作摘要

打勾标准

0

看状态/日志

启动链路可还原

1

规范退出

资源正常释放

2～4-B

调度与 SKIP

skip_reason 可懂

5-A/B

快照与门禁

stale/gate 可解释

11 / 5-C

映射/轮换/诊断/对账

见上文四节

七、记录模板（建议填写）

每次冒烟后记录：版本号、核心 live_trade_* 配置、gate 结果、拒单抽检、reconcile 摘要、结论（通过/待查/阻塞）。便于下一交易日对照。

相关文档