执行入门：委托状态与信号衔接

以 XtQuant 为例，可以把系统拆成两个接口方向：

• xtdata 负责在权限范围内获取行情；
• xttrader 负责连接交易服务、委托、撤单、查询和接收回报。

这两个模块通过本地客户端和相应服务协作，但本地连接不等于拥有全部数据、无限调用次数或交易权限。历史覆盖、财务字段、订阅数量和频率限制，都要按券商和服务版本核对。

更重要的是分层：

1. 研究层：用历史数据验证规则；
2. 信号层：根据当时真正可见的数据产生交易意图；
3. 执行层：检查账户和风控，提交委托，追踪状态并对账。

这样做的价值是，策略换了，不必重写连接；连接换了，也不应悄悄改变策略逻辑。

连接前先确认客户端是否人工登录成功，交易功能是否启用，数据目录、账户标识、会话 ID 和运行环境是否匹配。userdata_mini 等路径只是配置线索，不能把示例路径当成自己机器上的真实路径。

一个安全的顺序是：创建连接对象，启动并连接，订阅账户，依次查询资产、持仓、委托和成交，最后停止连接。每一步都记录返回结果；连接成功不代表订阅成功，订阅成功也不代表有委托权限。

只读核对至少包含总资产、可用现金、冻结资金、持仓市值、总量、可卖数量、成本或参考价，以及当日委托和成交。会话 ID 如 100002、100003 只是区分连接实例的示例值，不是资金账户或密码；多进程运行时要避免冲突。

遇到失败时，先检查人工登录、目录、账户权限、SDK 环境、订阅结果和日志，再判断原因。周末或非交易时段可能影响部分链路，但不能把每次失败都归因于非交易日；遇到“资金为 0 却能看到持仓”这类异常，先如实记录，再逐项排查原因。账户和密钥放在安全配置中，不能写进共享日志。

一次委托至少要表达账户、证券代码、买卖方向、数量和价格类型；限价单还要提供价格。限价是价格边界，可能不成交；市价或特定最优价更强调成交，但可能有价格偏离、保护参数和市场限制。不要把某个示例里的数字常量直接当成通用接口定义，应以当前 SDK 的明确常量和标的市场规则为准。

数量要同时通过几道检查：交易单位、最小申报量、买卖差异、可用现金、冻结资金、手续费、最大仓位和可卖数量。不能假设所有产品都必须是 100 股整数倍。价格也要符合最小价位单位和可接受区间。

把交易意图写成一条可审阅记录，例如：策略请求 ID、账户、标的、方向、目标数量、价格类型、限价、有效时间、风控结果。这样后面收到订单 ID 时，仍然知道它对应哪一次决策。

提交后返回订单 ID，只说明请求拿到了某种受理标识。它不能直接增加持仓。订单还可能经历已报、部分成交、全部成交、撤单处理中、已撤、拒绝等状态。状态数字如 50、54、56、57 可能随 SDK 版本有不同映射，必须查当前定义，不能依赖魔法数字。

部分成交时，已经成交的数量不会因为撤单消失；撤单只能针对剩余未成交部分。撤单请求被受理，也不等于最终已撤，因为成交和撤单可能同时发生。最终结果要结合成交回报、委托状态和账户查询对账。

批量撤单也要限定范围，例如只处理本策略、当前账户、指定日期和指定标的的活动订单，不能无差别取消其他手工或策略订单。

轮询是程序按固定间隔主动查询；回调是状态变化时由 SDK 通知程序。回调可以覆盖订单变化、成交、下单错误、撤单错误、断连和异步响应等事件，但具体接口和字段要以当前版本为准。

每条事件至少记录账户、订单 ID、策略请求 ID、方向、状态、成交数量、成交价格、时间和错误码。方向要显式识别买、卖和未知类型，不能把某个数字以外的所有情况都当成卖出。

回调可能重复、延迟，断连时还可能丢失。处理方式是：回调用于及时更新，轮询用于定期核对；重连后先查询活动订单和成交，再恢复新的委托。回调处理要短，日志要持久化，程序重启后仍能判断哪些请求已经提交。

提交后超时，可能是订单已经进入交易系统，只是响应没有回来。如果直接在 except 后重试，就可能产生两笔订单。

更稳妥的状态机是：

1. 提交前生成唯一请求标识，并把意图写入持久化记录；
2. 超时进入“结果未知”，暂停同一意图的重复提交；
3. 按账户、标的、时间和可用标识查询委托与成交；
4. 只有明确拒绝、原因已处理且规则允许时，才重新提交；
5. 对账不一致时暂停新增委托，先人工或程序核对。

给执行器设置单标的未完成订单上限、单次和单日金额上限、冷却时间及异常暂停。可以封装一个类似 MiniQMTTrader 的自定义对象，把连接、买卖、取消、查询和回调日志统一起来，但它不是官方 SDK 类型。封装层要区分请求状态和成交状态，失败不能返回空列表来伪装“没有持仓”。默认使用只读或模拟模式，真实执行必须由独立配置明确打开。

以 MACD 为例，常见参数是 12、26、9。判断金叉或死叉，要比较相邻两根已经完成的 bar：今天的快线从下方穿到上方，才是一次新信号；不能只判断快线当前高于慢线，然后每 60 秒重复买入。volume=150 的含义如果没有明确接口定义，就不能直接当成真实下单量。策略目标仓位和交易单位检查要分开。

日线策略可以每 60 秒查询一次，但这仍然是日线策略，不会自动变成 tick 策略。要提前写清楚：只使用完成 bar，还是允许盘中数据改变信号。历史数据和实时数据还要统一更新时间、复权方式和字段口径。

建议先做单次模式：取数据、计算信号、打印交易提案，不提交委托；再做循环模式：定时更新、检查新信号、查询账户和风险，最后生成待审阅委托。执行前还要写交易计划：跳空或价格偏离超过预设阈值时是否取消或重新评估，是否已有持仓，可卖数量是否足够，是否遇到交易时段、涨跌停、停牌、T+1 或过期数据。

这里的阈值只是系统参数示例，不是通用规则。更多数据频率也不自动更好。

Agent 可以整理账户信息、解释信号、生成交易提案和检查日志；但账户权限、仓位上限、资金检查、重复请求拦截和人工确认，必须由确定性的执行层强制执行，不能只靠提示词约束。

一个可审阅的提案至少包含：信号来源、数据时间、方向、目标数量、价格条件、已有持仓、风险检查结果、有效时间和失效条件。Agent 无情绪不等于系统安全，策略同向也可能造成拥挤，容量、滑点和异常行情仍要测试。