模拟实盘手工冒烟方案（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 -n \\ --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`` 有 ````。 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 接入（见 :doc:`4-broker-adapter-and-integration`）。 **各列含义**：**阶段**为路线图编号；**您执行的动作摘要**由您记录；**打勾标准**为通过该阶段的最小条件。 **如何使用**：冒烟过程中完成某阶段后，在「动作摘要」列写一句（如「warn 模式下 gate 通过」），达标则在心中或副本上打勾；未达标则记入 §七记录模板的「结论」列。 .. list-table:: :header-rows: 1 :widths: 12 28 40 * - 阶段 - 动作摘要 - 打勾标准 * - 0 - 看状态/日志 - 启动链路可还原 * - 1 - 规范退出 - 资源正常释放 * - 2～4-B - 调度与 SKIP - skip_reason 可懂 * - 5-A/B - 快照与门禁 - stale/gate 可解释 * - 11 / 5-C - 映射/轮换/诊断/对账 - 见上文四节 七、记录模板（建议填写） ------------------------ 每次冒烟后记录：版本号、核心 ``live_trade_*`` 配置、``gate`` 结果、拒单抽检、``reconcile`` 摘要、结论（通过/待查/阻塞）。便于下一交易日对照。 相关文档 -------- - 快照/门禁语义：:doc:`6-trader-snapshot-gate` - 产物与排错：:doc:`5-artifacts-and-troubleshooting` - CLI：:doc:`8-cli-trader-capability-matrix`