Q WorkBuddy-QMT Bridge · API 参考
v0.3.5
入门

概览

WorkBuddy-QMT Bridge 是一套运行在本机的交易桥接层。它把 Tencent WorkBuddy 的自然语言请求，翻译成结构化的大 QMT 查询与下单动作，并在整条链路上强制实施「失败关闭」（fail-closed）风控。

本桥接服务不托管任何资金接口，也不连接任何远端服务。Worker 只监听本机回环地址，QMT Adapter 以策略脚本形式运行在大 QMT 客户端内部，两者通过本机签名文件队列通信。

v0.3.5 优化了 MCP 下单等待与 QMT 查询开销。新增 prepare_trade 与 wait_trade_intent，缩短 Worker / Adapter 默认轮询间隔；委托与成交改为实时回调优先、每 30 秒完整对账兜底。安装资产见 GitHub Release v0.3.5。

31

MCP 工具

覆盖健康检查、账户、行情、持仓、委托、成交、信用、准备、预览、提交、等待、授权与熔断。

4

运行模式

OBSERVE_ONLY / SIM_SIGNAL / MANUAL_LIVE / LIMITED_AUTO。

2

传输通道

MCP stdio（WorkBuddy 侧）与本机 HTTP POST /rpc（Worker 侧）。

15

硬风控维度

资金、可卖量、单笔/单日额度、行情时效、价格笼子、活动委托、信用指标等。

核心设计原则

原则含义
失败关闭任何未知参数、类型错误、越界数值、过期快照、签名不符或模式漂移，一律按拒绝处理，绝不降级放行。
先预览后提交交易必须经过 preview_trade 生成可审计的预览；submit_trade_intent 只接受未过期预览，并重算全部硬风控。
决策指纹比对提交时比对风险决策指纹（动作、价格、数量、可用资金、持仓、价格保护、活动委托、日内额度、信用字段）。任一实质变化即要求重新预览。
一意图一委托不自动拆单、不追单、不尝试第二价格。SUBMIT_UNKNOWN 时不会自动重发。
模式不可远程切换MCP 无法切换 Worker/Adapter 运行模式，也无法解除熔断——这两项只由本机控制台完成。
双端独立复核Worker 签发的命令，Adapter 在调用 passorder 前会重新读取行情并独立复核账户、持仓、价格、额度与授权。

零外部依赖。本桥接不上传账户号、密钥、令牌或数据库。Profile 签名必须在目标电脑本机完成；从其他电脑复制的签名 Profile 一律无效。

入门

5 分钟只读上手

第一次使用只需要完成一个目标：让 WorkBuddy 能查询 QMT，同时保持 OBSERVE_ONLY，不会实际报单。

  1. 从 GitHub Releases 下载完整 ZIP，全部解压到独立目录；
  2. 双击 安装、升级或修复.cmd。安装器会检查 Python 并自动核验 wheel 的 SHA-256；
  3. 按自动打开的账户目录中的 部署说明.txt，把 qmt_adapter.py 放入对应 QMT 策略并启动；
  4. 双击桌面的 启动QMT桥接.cmd，直接按 Enter 使用 OBSERVE_ONLY；
  5. 双击 验证QMT桥接.cmd。全部显示“完成”后，重启 WorkBuddy 并调用 qmt_health。

首次只读连接不需要签名 Profile。只有准备进入模拟报单或真实交易时，才需要继续 P0 映射验证、Profile 签名和额外授权。

常用命令PowerShell
workbuddy-qmt --version
workbuddy-qmt verify --human
workbuddy-qmt account list --human
workbuddy-qmt open qmt-ready --human
workbuddy-qmt upgrade-check --human
workbuddy-qmt support-bundle --redact --human
入门

架构与数据流

系统由三个进程组成：MCP 前端（stdio，由 WorkBuddy 拉起）、Worker（本机 HTTP + SQLite + 文件队列）、QMT Adapter（大 QMT 内运行的策略脚本）。

WorkBuddy 自然语言 / Agent MCP 前端 stdio · tools/call Worker 127.0.0.1:17642 QMT Adapter 大 QMT 策略实例 大 QMT 柜台 / 行情 stdio POST queue API SQLite state · audit · intents 签名文件队列 HMAC · TTL · 死信 回程：Adapter 回传签名事件 → Worker 入库 → WorkBuddy 通过查询工具取得结构化结果 每一条消息均携带 HMAC-SHA256 签名与 TTL；超时、重放、时钟偏移超过 5 秒即被丢弃。

交易链路十二步

 1  单标的调用 prepare_trade；多标的一次 request_sync 批量刷新后再分别 preview_trade
 2  Adapter 返回最新价、盘口、涨跌停、最小价位、动态价格笼子
 3  prepare_trade / preview_trade 把意图转成结构化动作、数量与限价（不产生可执行命令）
 4  Worker 校验：零股 / 最小数量 / 资金 / 可卖量 / 单笔单日限额 /
    行情年龄 / 价格笼子 / 活动委托冲突 / 信用指标
 5  MANUAL_LIVE 逐笔授权（authorize_manual_trade）
    或 1–60 分钟账户级不限笔数授权（authorize_manual_session）
 6  LIMITED_AUTO 先过 readiness，再创建绑定当日时段/标的/动作/策略版本/额度的签名许可
 7  submit_trade_intent 再次比对风险决策指纹与授权状态，并在同一事务内原子占用自动额度
 8  通过后 Worker 把带 HMAC 签名和 TTL 的唯一命令写入目标账户队列
 9  Adapter 重新检查账户、数量、资金、实时行情、涨跌停、价格笼子、本地授权、P1 策略哈希
10  Adapter 校验签名 Profile 与 QMT 构建、柜台构建、账户、策略、Adapter 实例完全一致
11  Adapter 先写入 PRE_SUBMIT 防重复日志，再调用一次 passorder
12  委托 / 成交 / 错误回调写回 Worker；提交后先调用一次 wait_trade_intent 取首个状态

模式名称不代表柜台。SIM_SIGNAL、MANUAL_LIVE、LIMITED_AUTO 都无法识别当前连接的是模拟柜台还是真实资金柜台，操作者必须在 QMT 中自行核对账户与柜台。

入门

传输层与鉴权

桥接暴露两个通道：MCP stdio 供 WorkBuddy 调用，本机 HTTP /rpc 供 Worker 内部与手工排障使用。两者最终汇聚到同一套 BridgeCore 方法表。

POST /rpc

POST 127.0.0.1:17642

Worker 的唯一 HTTP 入口。使用本机令牌做 Bearer 鉴权，仅接受 JSON-RPC 风格的单条调用。

请求头

头值说明
Content-Typeapplication/json固定值。
AuthorizationBearer <worker_token>读取自 bridge.json 的 worker_token_file；不一致直接返回 UNAUTHORIZED。
Content-Length1 … max_message_bytes默认上限 65536 字节（可配置 1024–16777216）。越界返回 INVALID_REQUEST。

请求体

字段类型必填说明
methodstring必填方法名，必须是 31 个受支持方法之一，否则 METHOD_NOT_FOUND。
paramsobject可选方法入参，键必须与 Python 函数签名一一对应，缺参/多参抛 INVALID_REQUEST。
request_idstring可选缺省时 Worker 自动生成；原样回显，并写入 mcp_requests 审计表。
RequestPOST http://127.0.0.1:17642/rpc
{
  "method": "get_quote_snapshot",
  "params": {
    "account_alias": "main_stock",
    "symbols": ["600000.SH", "000001.SZ"]
  },
  "request_id": "req_9f2c1ab4"
}
Response200 OK · application/json
{
  "ok": true,
  "request_id": "req_9f2c1ab4",
  "as_of": "2026-09-01T02:11:03.412Z",
  "data": {
    "quotes": [
      {
        "snapshot_id": "qsnap_7a1f",
        "captured_at": "2026-09-01T02:11:02.880Z",
        "age_seconds": 1.2,
        "quote": {
          "symbol": "600000.SH",
          "last_price": 11.42,
          "tick_size": 0.01,
          "upper_limit": 12.56,
          "lower_limit": 10.28,
          "tick_at": "2026-09-01T02:11:02.500Z"
        }
      }
    ],
    "missing_symbols": []
  },
  "warnings": [],
  "error": null
}

HTTP 状态码

状态触发条件响应体
200请求被正常处理，包括业务错误。所有 BridgeError 都以 ok:false + 200 返回。完整信封
401Bearer 令牌不匹配。{"ok":false,"error":{"code":"UNAUTHORIZED"}}
404路径不是 /rpc。{"ok":false}
500Worker 内部未捕获异常。error.code = INTERNAL_ERROR

MCP · tools/call

MCP stdio

WorkBuddy 以 stdio 拉起 workbuddy_qmt.mcp_server。它把 tools/call 转发为上面的 POST /rpc，并把响应信封序列化为一段 text content 返回。

Requestjsonrpc 2.0 → tools/call
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_positions",
    "arguments": {
      "account_alias": "main_stock",
      "include_zero": false
    }
  }
}
Responsecontent[0].text = 响应信封
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"ok\":true,\"request_id\":\"req_...\",\"as_of\":\"...\",\"data\":{...},\"warnings\":[],\"error\":null}"
      }
    ],
    "isError": false
  }
}

WorkBuddy MCP 配置

位于 %USERPROFILE%\.workbuddy\mcp.json，由安装向导合并生成。不要把 worker token 写进这里——它由 Worker 从 worker_token_file 读取。

JSONmcpServers.qmt-bridge
{
  "mcpServers": {
    "qmt-bridge": {
      "command": "C:\\Users\\<用户名>\\AppData\\Local\\Programs\\Python\\Python313\\python.exe",
      "args": [
        "-m",
        "workbuddy_qmt.mcp_server",
        "--config",
        "C:\\Users\\<用户名>\\AppData\\Local\\WorkBuddyQMTBridge\\runtime\\config\\bridge.json",
        "--endpoint",
        "http://127.0.0.1:17642"
      ],
      "disabled": false
    }
  }
}

Worker 不可达时不会抛异常。MCP 前端网络失败会返回 ok:false 且 error.code = BRIDGE_UNAVAILABLE。调用方必须先检查 ok，而不是只看有没有异常。

工具注解（annotations）

每个 MCP 工具都带注解，WorkBuddy 可据此决定是否要求人工确认。本文档用徽标表达同样的语义：

徽标注解含义
READreadOnlyHint=true / destructiveHint=false只读查询，不产生任何副作用。
WRITEreadOnlyHint=false / destructiveHint=false会写队列或改本机状态，但不直接触发真实报单。
RISKdestructiveHint=true可能为真实 QMT 报单打开授权条件。调用前必须向用户展示完整范围并取得明确确认。
入门

运行模式

全项目只有四种运行模式。Worker、MCP 请求中的 execution_mode、以及 QMT Adapter 的 qmt_mode 必须完全一致；任一不一致即失败关闭。熔断是独立安全状态，不是第五种模式。

模式含义可能调用 passorder额外前置条件
OBSERVE_ONLY 查询、预览、空跑 ACK 闭环。默认且最安全的模式。 — 否 无。首次安装后固定为此模式。
SIM_SIGNAL 仅用于已验收的模拟账户 / 模拟柜台。 是 已验证并本机签名的 Profile；目标柜台 P0 闭环。
MANUAL_LIVE 人工实盘。支持逐笔审批或限时不限笔数授权，均可由高风险 MCP 工具完成。 是 已验证 Profile；Worker 模式必须先在本机切换；再取得逐笔 approval_context 或账户级时间授权。
LIMITED_AUTO P1 有限自动交易。授权后可在绑定范围内连续下单。 是 Profile + 模式一致 + 健康/对账检查通过 + authorize_limited_auto 创建的签名策略许可；健康异常时失败关闭。

不要在请求处理中热切换模式。正确顺序：停止发起新请求 → Worker 控制台 Ctrl+C → 停止所有 QMT 策略实例 → 修改每个账户 qmt_adapter.json 的 qmt_mode → 重启策略 → 启动 Worker 并选择同一模式 → qmt_health 复核。

bridge.json 中的 default_mode 只在数据库首次创建时设置初始模式。修改它不会切换已有环境的模式——当前模式保存在本机状态库，由启动菜单或本机控制台改写。

切换非观察模式

PowerShellworkbuddy_qmt.console set-mode
# 切回观察模式，不需要额外确认
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" set-mode OBSERVE_ONLY

# 切换到已验收的模拟柜台；模式名和确认文字必须完全一致
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" set-mode SIM_SIGNAL --confirm SIM_SIGNAL

# 切换到人工实盘模式
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" set-mode MANUAL_LIVE --confirm MANUAL_LIVE

# 切换到 P1 有限自动模式；这里只切模式，不会创建策略许可
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" set-mode LIMITED_AUTO --confirm LIMITED_AUTO

控制台命令只改 Worker 本机状态，不会自动修改 qmt_adapter.json，也不会重启 QMT 策略——这两步必须手工完成。

入门

响应信封

所有 31 个方法返回完全相同的外层结构。业务数据一律装在 data 字段里。

字段类型说明
okboolean成功为 true。这是唯一的成功判据——不要只看 HTTP 状态码。
request_idstring回显请求 ID，或 Worker 自动生成。可用于审计表检索。
as_ofstring (ISO 8601)Worker 处理完成时刻（UTC，毫秒精度）。
dataobject | array | null方法返回值。失败时为 null。
warningsarray非致命提示。当前版本恒为空数组，保留字段以兼容未来扩展。
errorobject | null失败时含 code / message / details。
成功ok = true
{
  "ok": true,
  "request_id": "req_4b02",
  "as_of": "2026-09-01T02:12:44.107Z",
  "data": { "...": "方法专属结构" },
  "warnings": [],
  "error": null
}
失败ok = false · HTTP 仍为 200
{
  "ok": false,
  "request_id": "req_4b03",
  "as_of": "2026-09-01T02:12:45.330Z",
  "data": null,
  "warnings": [],
  "error": {
    "code": "RISK_REJECTED",
    "message": "trade failed hard risk checks",
    "details": {
      "reasons": ["INSUFFICIENT_AVAILABLE_CASH", "MAX_DAILY_NOTIONAL_EXCEEDED"]
    }
  }
}

快照内容是透明的。查询类方法返回的 snapshot 已经剥离传输与版本元数据（type、snapshot_id、seq、captured_at、received_at、occurred_at、event_id、account_alias、account_type），只保留业务字段。时间与 ID 由外层单独给出。

入门

错误码

错误码是稳定的 API 契约。同一 code 在不同版本间含义不变，可放心用于分支处理。

传输层

错误码触发处理建议
BRIDGE_UNAVAILABLEMCP 前端连不上 Worker。检查 Worker 控制台是否在运行、端口是否被占用。
UNAUTHORIZEDBearer 令牌不匹配（HTTP 401）。确认 MCP 启动参数与 Worker 使用同一 runtime。
METHOD_NOT_FOUND方法名不在 31 个支持列表中。核对方法名拼写。
INVALID_REQUEST参数缺失/多余、类型错误、消息体超限或信封字段非法。按本文档的参数表逐项核对；注意 additionalProperties:false。
INTERNAL_ERRORWorker 未捕获异常（HTTP 500）。查看 <runtime>\data\logs\worker-YYYY-MM-DD.log。

账户与配置

错误码触发处理建议
ACCOUNT_NOT_FOUND别名不存在或账户被禁用。先用 list_account_aliases 取可用别名。
ACCOUNT_TYPE_MISMATCH动作/账户类型不匹配（如对 STOCK 账户调用信用接口）。区分普通与信用账户分别调用。
INSTRUMENT_NOT_ALLOWED标的不在账户 instrument_allowlist 内。调整白名单或更换标的。
CONFIG_ERRORbridge.json 字段越界或类型错误。运行 doctor 定位具体字段。

交易与授权

错误码触发处理建议
PREVIEW_NOT_FOUNDpreview_id 不存在。重新预览。
PREVIEW_EXPIRED预览超过 preview_ttl_seconds（默认 120 秒）。重新 request_sync → preview_trade。
PREVIEW_ALREADY_CONSUMED预览已提交过。再次提交会返回既有意图，不重复下单。用 get_trade_intent 查询结果。
RISK_REJECTED硬风控未通过。读 details.reasons，对照风控原因码。
SNAPSHOT_CHANGED作为 details.reason 出现在 RISK_REJECTED 下：风险决策指纹变化。必须重新预览，不要尝试绕过。
LIVE_NOT_ENABLED未处于所需模式、交易已熔断、或预览模式不是 MANUAL_LIVE。核对 Worker/Adapter 模式与熔断状态。
LOCAL_APPROVAL_REQUIREDMANUAL_LIVE 下缺少有效审批或时间授权。调用 authorize_manual_trade 或 authorize_manual_session。
LOCAL_CONFIRMATION_REQUIREDconfirm 确认词不匹配。使用各工具规定的确切确认词（见对应章节）。
DUPLICATE_INTENT意图与既有请求冲突（唯一键冲突）。查询既有意图状态后再决定。
ORDER_NOT_FOUND委托不存在，或不属于本桥接（无 client_order_key）。只能撤销本桥接产生的委托。
ORDER_NOT_CANCELLABLE委托已处于终态。查询最新状态。
INTENT_NOT_FOUNDintent_id 不存在。用 list_trade_intents 检索。

快照与时效

错误码触发处理建议
ACCOUNT_SNAPSHOT_STALE账户/持仓快照缺失或超龄。request_sync 刷新 ACCOUNT / POSITION。
QUOTE_SNAPSHOT_STALE 风控码行情缺失或超过 max_quote_age_seconds（默认 30 秒）。提交前立即 request_sync 带 QUOTE 域。
CREDIT_SNAPSHOT_STALE信用快照缺失或超龄（默认 600 秒）。request_sync 刷新 CREDIT_* 域。
CREDIT_CAPACITY_UNAVAILABLE动作所需额度快照缺失。先跑 request_credit_precheck。
CREDIT_QUERY_IN_PROGRESS已有信用额度查询在执行。等待后用 get_credit_capacity 取结果。
CREDIT_QUERY_RATE_LIMITED距上次查询不足 credit_query_cooldown_seconds（默认 180 秒）。读 details.retry_after_seconds 后重试。
MARKET_DATA_STALE行情不足以计算价格笼子或涨跌停。恢复行情源并重新同步。
SYNC_TIMEOUTprepare_trade 在限定时间内未收到完整同步结果。确认 QMT 策略在运行后安全重试；超时不会创建预览或报单。
SYNC_FAILEDQMT 拒绝或未能完成准备阶段所需同步。读取 details.status 并检查 Adapter / QMT 状态。

签名与消息

错误码触发处理建议
SIGNATURE_INVALIDHMAC 校验失败或密钥轮换。确认 Adapter 与 Worker 共用同一 runtime 密钥。
MESSAGE_EXPIRED命令超过 command_ttl_seconds（默认 60 秒）才被 Adapter 读取。检查 QMT 策略是否在运行、队列是否积压。
MESSAGE_SCHEMA_INVALID信封字段集不精确匹配、协议版本不符或消息类型不符。0.3.0 修改了命令协议，需重新部署 Adapter。
MESSAGE_TOO_LARGE消息超过 max_message_bytes。拆分请求或调大上限（需同步 Adapter）。
CLOCK_SKEW时钟偏移超过 5 秒容差。校准本机时钟。

有限自动（P1）

错误码触发处理建议
AUTO_NOT_READYreadiness 检查未通过。读 details.reasons，逐项排除后重跑 readiness。
AUTO_OUTSIDE_TRADING_DAY周末授权，或本地时间已过 15:00。下一个交易日再授权。
AUTO_CREDIT_NOT_ENABLED信用账户未开启 limited_auto_credit_enabled。完成信用 P0 后在 Bridge 与 Adapter 双侧开启。
AUTO_PERMIT_NOT_FOUND没有处于 PAUSED 的许可可恢复。用 get_limited_auto_status 查当前状态。
AUTO_PERMIT_EXPIRED许可已过期（跨日或过 15:00）。创建新许可。
AUTO_STRATEGY_REAUTHORIZATION_REQUIRED连续失败达到上限，需修正规则而非恢复。更新 rule_version 并创建新许可。
AUTO_ACCOUNT_EQUITY_UNAVAILABLE创建许可时 total_asset 缺失或非正。先同步账户快照。
系统与健康

qmt_health

qmt_health

MCP READ

返回 Worker、每个 QMT Adapter、快照时效、队列深度、运行模式与熔断状态的综合健康视图。这是每次会话的第一个调用，也是授权前的必经检查。

无参数永不报单

响应 data

字段类型说明
worker_statusstring固定为 "READY"（能返回响应即代表 Worker 存活）。
modeenum当前 Worker 运行模式。
haltedboolean是否处于熔断。只能由本机控制台清除。
halt_reasonstring | null熔断原因。
accounts[]object[]每个已配置账户的健康明细（见下）。
unresolved_submit_unknowninteger未处理的 SUBMIT_UNKNOWN 意图数；大于 0 会阻止自动交易。
as_ofstringWorker 本地时间。

accounts[] 元素：ready 为 true 的条件是——有心跳、状态为 READY、且心跳年龄 ≤ 15 秒。adapter_status 无心跳时为 OFFLINE。

Requestparams: {}
{
  "method": "qmt_health",
  "params": {}
}
Responsedata
{
  "worker_status": "READY",
  "mode": "OBSERVE_ONLY",
  "halted": false,
  "halt_reason": null,
  "accounts": [
    {
      "account_alias": "main_stock",
      "account_type": "STOCK",
      "adapter_instance": "qmt_stock_01",
      "adapter_status": "READY",
      "heartbeat_age_seconds": 3.4,
      "account_snapshot_age_seconds": 12.9,
      "ready": true,
      "queue_depths": {
        "outbox": 0,
        "inbox": 0,
        "dead_letter": 0
      },
      "limited_auto": {
        "configured": false,
        "active": false,
        "status": "NONE",
        "permit_id": null,
        "health_reasons": []
      }
    }
  ],
  "unresolved_submit_unknown": 0,
  "as_of": "2026-09-01T02:15:10.204Z"
}

心跳正常 ≠ 可以下单。心跳只表示 Adapter 进程在跑。能否调用 passorder 取决于运行模式、Profile 验证状态、授权与风控，必须逐项确认。

系统与健康

list_account_aliases

list_account_aliases

MCP READ

列出已配置的账户别名。永不返回真实券商账户号——这是有意的安全设计，真实账号只存在于本机配置与 Profile 绑定中。

参数类型必填说明
account_typeenum可选STOCK 或 CREDIT。省略时返回全部。其他值抛 INVALID_REQUEST。
Request按类型过滤
{
  "method": "list_account_aliases",
  "params": { "account_type": "STOCK" }
}
Responsedata
[
  {
    "account_alias": "main_stock",
    "account_type": "STOCK",
    "adapter_instance": "qmt_stock_01",
    "enabled": true
  },
  {
    "account_alias": "main_credit",
    "account_type": "CREDIT",
    "adapter_instance": "qmt_credit_01",
    "enabled": false
  }
]

enabled:false 的账户会被 config.account() 视为不存在，任何以它为别名的调用都会返回 ACCOUNT_NOT_FOUND。信用账户默认不启用。

账户与风控

get_account_snapshot

get_account_snapshot

MCP READ

取最新的归一化普通证券账户快照。返回的是本机数据库里已存在的快照，不会主动触发 QMT 查询——要刷新请先调用 request_sync。

参数类型必填说明
account_aliasstring必填账户别名。
Requestparams
{
  "method": "get_account_snapshot",
  "params": { "account_alias": "main_stock" }
}
Responsedata
{
  "snapshot": {
    "total_asset": 988523.46,
    "available_cash": 671204.18,
    "market_value": 317319.28,
    "frozen_cash": 0,
    "trading_day": "20260901"
  },
  "age_seconds": 8.7
}

快照字段

字段类型说明
total_assetnumber总资产。LIMITED_AUTO 用它做回撤基准。
available_cashnumber可用资金。买入硬校验的输入。
market_valuenumber持仓市值。仅随行情变化，不进入风险决策指纹。
frozen_cashnumber冻结资金。
trading_daystringYYYYMMDD。

时长判定在调用方。本方法不校验 max_snapshot_age_seconds，只如实返回 age_seconds。风控校验发生在 preview_trade 与 submit_trade_intent。快照缺失时返回 ACCOUNT_SNAPSHOT_STALE。

账户与风控

get_risk_limits

get_risk_limits

MCP READ

返回某账户当前生效的本地硬风控额度与数量规则。这些值不可通过 MCP 修改，只能编辑 bridge.json 并重启 Worker。

Requestparams
{
  "method": "get_risk_limits",
  "params": { "account_alias": "main_stock" }
}
Responsedata · 普通账户
{
  "account_alias": "main_stock",
  "account_type": "STOCK",
  "lot_size": 100,
  "odd_lot_sell_allowed": true,
  "order_volume_rules": {
    "default": { "min_buy": 100, "min_sell": 100 },
    "prefix_overrides": [
      { "prefixes": ["688", "689"], "min_buy": 200, "min_sell": 200 }
    ]
  },
  "max_order_notional": 200000.0,
  "max_order_volume": 500000,
  "max_daily_notional": 2000000.0,
  "min_maintenance_ratio": 1.5,
  "max_snapshot_age_seconds": 90,
  "max_quote_age_seconds": 30,
  "max_credit_snapshot_age_seconds": 600,
  "preview_ttl_seconds": 120,
  "command_ttl_seconds": 60,
  "credit_query_cooldown_seconds": 180,
  "max_auto_authorization_minutes": 720,
  "max_auto_session_notional": 2000000.0,
  "max_auto_orders": 1000,
  "min_auto_order_interval_seconds": 1,
  "max_auto_concurrent_orders": 20,
  "max_auto_symbol_position_notional": 500000.0,
  "max_auto_account_drawdown": 100000.0,
  "auto_heartbeat_max_age_seconds": 15,
  "auto_max_queue_depth": 20
}

信用账户会额外返回 credit_action_mapping，默认 {"buy":"MARGIN_BUY","sell":"COLLATERAL_SELL"}——即通用买入只执行融资买入、通用卖出只执行担保品卖出，不做第二次尝试。

额度是通用硬上限，不是仓位建议。上表的 20 万 / 200 万是按百万级账户规模给的发布默认值，与账户资产比例无关。资金规模、换手率或风险承受力较低时应主动调低——但要同步修改 Bridge 与 Adapter 两侧，否则 doctor 会报不同步。

行情 · 持仓 · 委托

get_quote_snapshot

get_quote_snapshot

MCP READ

取 QMT 衍生行情，含涨跌停价、最小价位与动态价格笼子边界。这些字段是价格保护的输入，必须先 request_sync 刷新，否则拿到的是陈旧数据。

参数类型必填说明
account_aliasstring必填账户别名。
symbolsstring[]必填1–100 个代码，^\d{6}(\.(SH|SZ|BJ))?$。
Requestparams
{
  "method": "get_quote_snapshot",
  "params": {
    "account_alias": "main_stock",
    "symbols": ["600000.SH", "000001.SZ"]
  }
}
Responsedata
{
  "quotes": [
    {
      "snapshot_id": "qsnap_7a1f",
      "captured_at": "2026-09-01T02:11:02.880Z",
      "age_seconds": 4.1,
      "quote": {
        "symbol": "600000.SH",
        "last_price": 11.42,
        "open": 11.3,
        "high": 11.5,
        "low": 11.26,
        "prev_close": 11.32,
        "tick_size": 0.01,
        "upper_limit": 12.45,
        "lower_limit": 10.19,
        "cage_upper": 11.79,
        "cage_lower": 11.05,
        "bid": 11.41,
        "ask": 11.43,
        "tick_at": "2026-09-01T02:11:02.500Z"
      }
    }
  ],
  "missing_symbols": ["000001.SZ"]
}

age_seconds 取 captured_at 与 tick_at 两者中较旧的那个——取最保守值。缺失的标的列在 missing_symbols，不会被省略。

行情 · 持仓 · 委托

get_positions

get_positions

MCP READ

从同一份一致性快照取持仓。返回的所有持仓共享一个 snapshot_id，不会出现跨快照拼接的不一致数据。

参数类型必填说明
account_aliasstring必填账户别名。
symbolsstring[]可选最多 100 个代码；省略返回全部。
include_zeroboolean可选默认 false，过滤掉零持仓。
Requestparams
{
  "method": "get_positions",
  "params": {
    "account_alias": "main_stock",
    "include_zero": false
  }
}
Responsedata
{
  "snapshot_id": "psnap_31cd",
  "captured_at": "2026-09-01T02:14:55.300Z",
  "age_seconds": 21.6,
  "positions": [
    {
      "symbol": "601398.SH",
      "total_volume": 5000,
      "available_volume": 5000,
      "frozen_volume": 0,
      "avg_cost": 6.812,
      "last_price": 7.06,
      "market_value": 35300.0
    },
    {
      "symbol": "601899.SH",
      "total_volume": 1000,
      "available_volume": 1000,
      "frozen_volume": 0,
      "avg_cost": 18.44,
      "last_price": 19.12,
      "market_value": 19120.0
    }
  ]
}

available_volume 是卖出硬校验的输入——可卖量受 T+1 与冻结量影响，通常小于 total_volume。

行情 · 持仓 · 委托

get_orders

get_orders

MCP READ

取归一化后的 QMT 委托记录，按 updated_at 倒序。

参数类型必填说明
account_aliasstring必填账户别名。
statusstring | string[]可选按状态过滤；传数组时为 IN 查询。
trading_daystring可选YYYY-MM-DD 或 YYYYMMDD，内部统一去连字符。
Request按状态数组过滤
{
  "method": "get_orders",
  "params": {
    "account_alias": "main_stock",
    "status": ["ACCEPTED", "PARTIALLY_FILLED"],
    "trading_day": "2026-09-01"
  }
}
Responsedata · 数组
[
  {
    "qmt_order_id": "20260901000321",
    "client_order_key": "cok_9d31",
    "intent_id": "intent_7c2a",
    "account_alias": "main_stock",
    "symbol": "601398.SH",
    "action": "BUY",
    "status": "ACCEPTED",
    "requested_volume": 500,
    "filled_volume": 0,
    "limit_price": 7.05,
    "trading_day": "20260901",
    "updated_at": "2026-09-01T02:20:11.400Z"
  }
]

活动状态（可撤销）：QUEUED、REPORTED、ACCEPTED、ORDER_ACCEPTED、PARTIALLY_FILLED、CANCEL_REQUESTED、SUBMIT_CALLED。活动委托同时构成新订单的冲突校验输入。

行情 · 持仓 · 委托

get_trades

get_trades

MCP READ

取归一化成交记录，按 traded_at 倒序。当日累计成交额是单日额度校验的输入。

参数类型必填说明
account_aliasstring必填账户别名。
trading_daystring可选交易日过滤。
Requestparams
{
  "method": "get_trades",
  "params": {
    "account_alias": "main_stock",
    "trading_day": "20260901"
  }
}
Responsedata · 数组
[
  {
    "trade_id": "trd_4e18",
    "qmt_order_id": "20260831000104",
    "intent_id": "intent_2b90",
    "symbol": "601899.SH",
    "action": "BUY",
    "volume": 1000,
    "price": 18.44,
    "traded_at": "2026-08-31T06:12:03.000Z",
    "trading_day": "20260831"
  }
]
信用账户

get_credit_account_snapshot

get_credit_account_snapshot

MCP READ 仅 CREDIT

取最新信用账户资产、负债、额度与维持担保比例快照。对普通账户调用返回 ACCOUNT_TYPE_MISMATCH。

Requestparams
{
  "method": "get_credit_account_snapshot",
  "params": { "account_alias": "main_credit" }
}
Responsedata
{
  "snapshot": {
    "total_asset": 512300.0,
    "total_debt": 120400.0,
    "net_asset": 391900.0,
    "maintenance_ratio": 4.25,
    "available_margin": 268000.0,
    "financing_quota": 300000.0,
    "securities_quota": 150000.0,
    "trading_day": "20260901"
  },
  "age_seconds": 45.2
}

maintenance_ratio 低于 min_maintenance_ratio（默认 1.5）会触发 CREDIT_RISK_LIMIT 拒绝。快照缺失或超龄返回 CREDIT_SNAPSHOT_STALE。

信用字段名必须现场验证。field_map、credit_field_map、eligibility_allowed_values 只能填入已在当前 QMT/券商组合完成 P0 验证的结果。不同券商版本的字段与枚举差异很大，不要凭经验猜测。

信用账户

get_credit_debt_contracts

get_credit_debt_contracts

MCP READ 仅 CREDIT

取最新快照中的负债合约引用（已脱敏）。还款类动作需要用它提供的 debt_contract_ref。

参数类型必填说明
account_aliasstring必填信用账户别名。
symbolstring可选按标的代码过滤。
statusstring可选默认 "OPEN"。
Requestparams
{
  "method": "get_credit_debt_contracts",
  "params": {
    "account_alias": "main_credit",
    "symbol": "600000.SH",
    "status": "OPEN"
  }
}
Responsedata
{
  "snapshot_id": "cdsnap_19af",
  "captured_at": "2026-09-01T02:10:00.000Z",
  "debts": [
    {
      "debt_contract_ref": "dctr_****-4417",
      "symbol": "600000.SH",
      "debt_type": "MARGIN",
      "status": "OPEN",
      "open_date": "20260812",
      "remain_volume": 3000,
      "remain_amount": 34200.0
    }
  ]
}

无快照时返回 {"snapshot_id": null, "debts": []}——这是正常空结果，不是错误。

信用账户

get_credit_instrument_eligibility

get_credit_instrument_eligibility

MCP READ 仅 CREDIT

查询标的的担保品、融资买入、融券卖出资格。资格不足会产生 CREDIT_INSTRUMENT_NOT_ELIGIBLE 风控拒绝。

参数类型必填说明
account_aliasstring必填信用账户别名。
symbolsstring[]必填1–100 个代码，不可为空数组。
Requestparams
{
  "method": "get_credit_instrument_eligibility",
  "params": {
    "account_alias": "main_credit",
    "symbols": ["600000.SH", "000001.SZ"]
  }
}
Responsedata
{
  "snapshot_id": "cesnap_2f70",
  "captured_at": "2026-09-01T02:10:05.000Z",
  "instruments": [
    {
      "symbol": "600000.SH",
      "collateral_eligible": true,
      "margin_eligible": true,
      "short_eligible": false,
      "margin_ratio": 1.0,
      "short_ratio": null
    }
  ],
  "missing": ["000001.SZ"]
}

missing 列出快照中无记录的标的——不要用空数组推断"全部可交易"，应视为资格未知并先同步。

信用账户

get_credit_capacity

get_credit_capacity

MCP READ 仅 CREDIT

取最近 50 条序列化的信用额度查询结果。这是读取 request_credit_precheck 结果的配套方法——预检本身是异步的。

Requestparams
{
  "method": "get_credit_capacity",
  "params": { "account_alias": "main_credit" }
}
Responsedata · 数组
[
  {
    "seq": "creditseq_8a02",
    "status": "COMPLETED",
    "requested_at": "2026-09-01T02:09:10.000Z",
    "completed_at": "2026-09-01T02:09:12.400Z",
    "request": {
      "requests": [
        { "symbol": "600000.SH", "credit_action": "MARGIN_BUY", "price_type": "LIMIT", "price": 11.42 }
      ]
    },
    "result": {
      "capacity_snapshot_id": "ccap_creditseq_8a02",
      "items": [
        { "symbol": "600000.SH", "max_volume": 26000, "max_amount": 296920.0 }
      ]
    }
  }
]

status 取 IN_PROGRESS / COMPLETED / FAILED。result 在完成前为 null。

信用账户

request_credit_precheck

request_credit_precheck

MCP WRITE 限流

发起一次串行且限流的信用额度查询。不创建交易意图，也不下单——它只是为后续预览提供额度快照。

参数类型必填说明
account_aliasstring必填信用账户别名。
requestsobject[]必填1–20 条；同一批次必须只用一种 credit_action。
requests[].symbolstring必填6 位代码。
requests[].credit_actionenum必填COLLATERAL_BUY / COLLATERAL_SELL / MARGIN_BUY / SHORT_SELL / BUY_TO_REPAY / SELL_TO_REPAY。
requests[].price_typeenum必填当前仅支持 LIMIT。
requests[].pricenumber必填> 0 的限价。
Requestparams
{
  "method": "request_credit_precheck",
  "params": {
    "account_alias": "main_credit",
    "requests": [
      { "symbol": "600000.SH", "credit_action": "MARGIN_BUY", "price_type": "LIMIT", "price": 11.42 },
      { "symbol": "000001.SZ", "credit_action": "MARGIN_BUY", "price_type": "LIMIT", "price": 12.05 }
    ]
  }
}
Responsedata
{
  "message_id": "msg_c41f",
  "status": "DELIVERED",
  "command_type": "CREDIT_PRECHECK",
  "seq": "creditseq_8a02",
  "capacity_snapshot_id": "ccap_creditseq_8a02",
  "query_status": "IN_PROGRESS"
}

串行 + 冷却双重限制。同一账户同时只允许一个 IN_PROGRESS 查询，重复提交返回 CREDIT_QUERY_IN_PROGRESS；距上次查询不足 credit_query_cooldown_seconds（默认 180 秒）返回 CREDIT_QUERY_RATE_LIMITED，并在 details.retry_after_seconds 给出等待秒数。混合多种 credit_action 会直接抛 INVALID_REQUEST。

交易生命周期

prepare_trade

prepare_trade

MCP WRITE

单标的低延迟准备入口：校验交易请求，向 QMT 一次请求账户、持仓、委托、成交与目标标的行情，等待同步完成和事件队列清空，然后执行 preview_trade。不会提交交易意图，也不会产生可执行命令。

安全同步 + 预览永不报单
参数类型必填说明
trade_requestobject必填与 preview_trade.trade_request 完全相同。
timeout_secondsnumber可选0.5–5.0，默认 3.0；只限制准备阶段等待，不改变消息 TTL。
Request单标的准备
{
  "method": "prepare_trade",
  "params": {
    "trade_request": {
      "account_alias": "main_stock",
      "instrument": { "canonical_symbol": "601398.SH" },
      "action": "BUY",
      "sizing": { "type": "FIXED_VOLUME", "value": 500 },
      "price_policy": { "type": "LIMIT_FROM_LATEST", "offset_bps": 5 },
      "execution_mode": "OBSERVE_ONLY",
      "source": { "type": "manual", "signal_id": "sig_20260912_001" }
    },
    "timeout_seconds": 3.0
  }
}
Responsedata
{
  "sync": {
    "message_id": "msg_82f1",
    "status": "SYNC_COMPLETED",
    "scopes": ["ACCOUNT", "POSITION", "ORDER", "DEAL", "QUOTE"],
    "symbols": ["601398.SH"],
    "event_queue_drained": true
  },
  "preview": {
    "preview_id": "preview_5c8e",
    "expires_at": "2026-09-12T02:22:04.100Z",
    "account_alias": "main_stock",
    "instrument": {
      "canonical_symbol": "601398.SH",
      "qmt_symbol": "601398.SH"
    },
    "resolved_order": {
      "volume": 500,
      "price_type": "LIMIT",
      "limit_price": 7.05,
      "notional": 3525.0
    },
    "risk": { "allowed": true, "reasons": [] }
  }
}
  • 单标的优先使用本工具，可减少 WorkBuddy 与 MCP 之间的往返调用。
  • 多个标的应一次调用 request_sync，在 symbols 中批量传入全部代码，再分别调用 preview_trade；不要逐标的重复刷新账户和持仓。
  • SYNC_TIMEOUT 时不会创建预览或报单，确认 QMT 策略在运行后可安全重试；SYNC_FAILED 表示 QMT 明确拒绝或同步失败。
  • 信用账户的债务合约和额度预检查仍需按信用工具流程准备，本工具不替代 request_credit_precheck。
交易生命周期

preview_trade

preview_trade

MCP WRITE

把交易意图归一化为结构化动作、数量与限价，并跑完整硬风控。不产生任何可执行命令。价格会按有利方向取整到最小价位，并受涨跌停与交易所动态价格笼子约束。

安全永不报单TTL 120s

必须先刷新行情。单标的优先直接调用 prepare_trade；批量标的先一次执行 request_sync 并带 QUOTE 域，再分别预览。否则大概率命中 QUOTE_SNAPSHOT_STALE。

参数

参数类型必填说明
trade_requestobject必填完整交易请求（结构见下）。additionalProperties:false。

trade_request 结构

字段类型必填说明
account_aliasstring必填账户别名。
instrumentobject必填{canonical_symbol, qmt_symbol}。v1 要求两者一致，不一致抛 INVALID_REQUEST。
actionenum必填普通账户：BUY / SELL / TARGET_POSITION。信用账户：六种显式信用动作 + BUY / SELL。
sizingobject必填见 sizing 表。
price_policyobject必填见 price_policy 表。
execution_modeenum必填OBSERVE_ONLY / SIM_SIGNAL / MANUAL_LIVE / LIMITED_AUTO。必须与 Worker 当前模式一致。
sourceobject必填{type, signal_id} 必填，另可带 rule_set_id、rule_version。LIMITED_AUTO 下后两者必须与许可逐字一致。
account_typeenum可选省略时取账户配置值；不匹配抛 ACCOUNT_TYPE_MISMATCH。
asset_typeenum可选当前仅支持 STOCK。
signal_evidenceobject可选{occurred_at, quote_at, reference_price}，用于可审计性留痕。
creditobject可选{debt_contract_ref, capacity_snapshot_id}，还款动作需要。

sizing

字段类型必填说明
typeenum必填FIXED_VOLUME（股数）/ FIXED_NOTIONAL（金额）/ AVAILABLE_CASH_PERCENT（可用资金百分比）/ TARGET_PORTFOLIO_PERCENT / TARGET_POSITION。
valuenumber必填> 0。
max_volumeinteger可选≥ 1，为推导出的数量加一道上限。

搭配约束：TARGET_POSITION 动作必须配 TARGET_POSITION sizing，反之亦然；信用账户不支持 TARGET_PORTFOLIO_PERCENT 与 TARGET_POSITION。

price_policy

字段类型必填说明
typeenum必填FIXED_LIMIT / LIMIT_FROM_LATEST / LIMIT_FROM_BOOK。
limit_pricenumber条件FIXED_LIMIT 必填且 > 0；派生策略不接受此字段。
offset_bpsnumber可选−1000 … 1000 基点，仅派生策略接受；FIXED_LIMIT 不接受。
max_deviation_pctnumber可选0 … 1，相对基准价的最大偏离比例。
Request按股数限价买入
{
  "method": "preview_trade",
  "params": {
    "trade_request": {
      "account_alias": "main_stock",
      "instrument": { "canonical_symbol": "601398.SH" },
      "action": "BUY",
      "sizing": { "type": "FIXED_VOLUME", "value": 500 },
      "price_policy": {
        "type": "LIMIT_FROM_LATEST",
        "offset_bps": 5,
        "max_deviation_pct": 0.01
      },
      "execution_mode": "OBSERVE_ONLY",
      "source": {
        "type": "manual",
        "signal_id": "sig_20260901_001",
        "rule_set_id": "core-holding",
        "rule_version": "2026-09-01-v1"
      },
      "signal_evidence": {
        "quote_at": "2026-09-01T02:20:00.000Z",
        "reference_price": 7.05
      }
    }
  }
}
Responsedata
{
  "preview_id": "preview_5c8e",
  "created_at": "2026-09-01T02:20:04.100Z",
  "expires_at": "2026-09-01T02:22:04.100Z",
  "account_alias": "main_stock",
  "account_type": "STOCK",
  "asset_type": "STOCK",
  "instrument": { "canonical_symbol": "601398.SH", "qmt_symbol": "601398.SH" },
  "action": "BUY",
  "resolved_action": "BUY",
  "execution_mode": "OBSERVE_ONLY",
  "resolved_order": {
    "volume": 500,
    "price_type": "LIMIT",
    "limit_price": 7.05,
    "requested_limit_price": 7.0535,
    "notional": 3525.0,
    "volume_rule": "DEFAULT"
  },
  "price_guard": {
    "applied": true,
    "reason": "TICK_ROUNDED",
    "quote_snapshot_id": "qsnap_7a1f",
    "quote_age_seconds": 3.2
  },
  "account_summary": {
    "snapshot_id": "asnap_99b1",
    "available_cash": 671204.18,
    "total_asset": 988523.46,
    "position_total_volume": 5000,
    "position_available_volume": 5000
  },
  "credit_summary": null,
  "limited_auto": null,
  "active_order_conflicts": [],
  "snapshot_fingerprint": "9f2a1c04...",
  "snapshot_versions": { "account": "asnap_99b1", "position": "psnap_31cd", "quote": "qsnap_7a1f" },
  "risk": { "allowed": true, "reasons": [] },
  "warnings": []
}

关键响应字段

字段说明
resolved_order.limit_price经价格笼子、涨跌停与最小价位修正后的最终限价。买入向下取整、卖出向上取整（有利方向）。
resolved_order.requested_limit_price修正前的原始推导价。
resolved_order.notionalvolume × limit_price，单笔/单日额度校验的输入。
price_guard.reasonTICK_ROUNDED / CAGE_CLAMPED / LIMIT_CLAMPED 等，说明价格被如何调整。
risk.allowed唯一放行判据。false 时 risk.reasons 给出全部原因码。
snapshot_fingerprint风险决策指纹。提交时会重算并比对，变化即 SNAPSHOT_CHANGED。
active_order_conflicts同标的活动中委托的 QMT 委托号列表。
expires_atpreview_ttl_seconds（默认 120 秒）后失效。

0.2.3 起的指纹语义。提交一致性已从"所有快照 UUID 必须完全不变"改为"风险决策必须保持一致"。仅快照重新编号，或行情波动只改变市值/总资产/现价而未改变最终委托与风险输入时，不再返回 SNAPSHOT_CHANGED。但可用资金、可卖量、最终限价或数量、活动委托、日内额度、信用指标任一实质变化，仍会要求重新预览。

LIMITED_AUTO 下失败的预览会暂停许可。若 execution_mode 为 LIMITED_AUTO 且风控拒绝，活动许可会被自动暂停，原因写入 pause_reason。排除后必须用 resume_limited_auto 显式恢复——不会静默自动恢复。

交易生命周期

submit_trade_intent

submit_trade_intent

MCP RISK

提交一个未过期预览。会用最新账户、持仓、行情、活动委托与信用数据重跑完整硬风控，比对风险决策指纹，校验授权，然后才把带签名的唯一命令写入队列。

可能真实报单幂等
参数类型必填说明
preview_idstring必填来自 preview_trade。
approval_contextobject条件{local_approval_id}。MANUAL_LIVE 逐笔授权时必填；存在有效时间授权或 P1 许可时省略。

授权要求（按模式）

execution_mode提交前置条件
OBSERVE_ONLY无需授权。Adapter 空跑并回 ACK，不调用 passorder。
SIM_SIGNAL已验证并本机签名的 Profile；Adapter 同模式。
MANUAL_LIVE有效的逐笔 approval_context，或该账户存在有效的限时不限笔数授权。两者皆无 → LOCAL_APPROVAL_REQUIRED。
LIMITED_AUTO活动的 P1 许可，且策略哈希、授权代次、时段、标的、动作、策略版本、额度、频率、并发、持仓敞口、账户回撤逐项通过。
RequestMANUAL_LIVE 逐笔
{
  "method": "submit_trade_intent",
  "params": {
    "preview_id": "preview_5c8e",
    "approval_context": { "local_approval_id": "approval_1d90" }
  }
}
Responsedata · 意图对象
{
  "intent_id": "intent_7c2a",
  "intent_revision": 1,
  "preview_id": "preview_5c8e",
  "client_order_key": "cok_9d31",
  "account_alias": "main_stock",
  "status": "QUEUED",
  "action": "BUY",
  "symbol": "601398.SH",
  "requested_volume": 500,
  "limit_price": 7.05,
  "execution_mode": "OBSERVE_ONLY",
  "source_signal_id": "sig_20260901_001",
  "created_at": "2026-09-01T02:20:09.800Z",
  "updated_at": "2026-09-01T02:20:09.800Z",
  "payload": {
    "type": "EXECUTE_ORDER",
    "intent_id": "intent_7c2a",
    "client_order_key": "cok_9d31",
    "qmt_symbol": "601398.SH",
    "action": "BUY",
    "resolved_order": { "volume": 500, "price_type": "LIMIT", "limit_price": 7.05 },
    "execution_mode": "OBSERVE_ONLY",
    "auto_permit": null
  },
  "orders": [],
  "trades": []
}

提交是幂等的。重复提交同一个 preview_id 不会下第二张委托——方法会检测到 consumed_intent_id 并直接返回既有意图对象。网络超时后重试是安全的。

返回 QUEUED 不等于已报单。命令只是入队。提交后先调用一次 wait_trade_intent 取得首个进展；如尚未终态，稍后再用 get_trade_intent 或 get_orders 查询。SUBMIT_UNKNOWN 表示结果未明，系统不会自动重发，需人工处理，且会阻止新的自动订单。

交易生命周期

wait_trade_intent

wait_trade_intent

MCP READ

在服务端做一次有上限的短等待；交易意图首次离开 QUEUED 就立即返回。用于替代 WorkBuddy 端的高频短轮询，只查询，不提交、不重发。

只读最长 5 秒不等待终态
参数类型必填说明
intent_idstring必填submit_trade_intent 返回的意图 ID。
timeout_secondsnumber可选0.1–5.0，默认 2.5。
Request最多等待一次
{
  "method": "wait_trade_intent",
  "params": {
    "intent_id": "intent_7c2a",
    "timeout_seconds": 2.5
  }
}
Responsedata
{
  "status_observed": true,
  "timed_out": false,
  "intent": {
    "intent_id": "intent_7c2a",
    "intent_revision": 1,
    "preview_id": "preview_5c8e",
    "client_order_key": "cok_9d31",
    "account_alias": "main_stock",
    "status": "SUBMIT_CALLED",
    "action": "BUY",
    "symbol": "601398.SH",
    "requested_volume": 500,
    "limit_price": 7.05,
    "orders": [],
    "trades": []
  }
}

一次等待只取首个进展，不保证终态。若超时，返回 status_observed:false、timed_out:true、当前意图和 next_action。稍后用 get_trade_intent 查询；不要因为等待超时而重新提交预览。

交易生命周期

cancel_order

cancel_order

MCP RISK

请求撤销由本桥接产生的、处于活动状态的单张 QMT 委托。

参数类型必填说明
account_aliasstring必填账户别名。
order_idstring必填QMT 委托号。
reasonstring必填1–200 字符，写入审计日志。
Requestparams
{
  "method": "cancel_order",
  "params": {
    "account_alias": "main_stock",
    "order_id": "20260901000321",
    "reason": "用户要求撤销未成交买入委托"
  }
}
Responsedata · 重复提交时 duplicate=true
{
  "message_id": "msg_b7f2",
  "status": "DELIVERED",
  "command_type": "CANCEL_ORDER"
}
  • OBSERVE_ONLY 模式下禁用，返回 LIVE_NOT_ENABLED。
  • 委托不属于本桥接（无 client_order_key）→ ORDER_NOT_FOUND。手工在 QMT 里下的单撤不掉。
  • 委托已终态 → ORDER_NOT_CANCELLABLE。
  • 重复撤销同一委托会返回既有命令且 duplicate:true，不会重复下发。
交易生命周期

get_trade_intent

get_trade_intent

MCP READ

取单个意图，连同其关联的委托与成交流水。存在多版本时返回最新修订。

Requestparams
{
  "method": "get_trade_intent",
  "params": { "intent_id": "intent_7c2a" }
}
Responsedata
{
  "intent_id": "intent_7c2a",
  "intent_revision": 1,
  "preview_id": "preview_5c8e",
  "client_order_key": "cok_9d31",
  "account_alias": "main_stock",
  "status": "FILLED",
  "action": "BUY",
  "symbol": "601398.SH",
  "requested_volume": 500,
  "limit_price": 7.05,
  "execution_mode": "OBSERVE_ONLY",
  "created_at": "2026-09-01T02:20:09.800Z",
  "updated_at": "2026-09-01T02:20:14.200Z",
  "payload": { "...": "完整签名命令" },
  "orders": [
    {
      "qmt_order_id": "20260901000321",
      "status": "FILLED",
      "requested_volume": 500,
      "filled_volume": 500,
      "limit_price": 7.05
    }
  ],
  "trades": [
    { "trade_id": "trd_9a10", "volume": 500, "price": 7.04, "traded_at": "2026-09-01T02:20:14.000Z" }
  ]
}

意图不存在返回 INTENT_NOT_FOUND。完整状态列表见状态机。

交易生命周期

list_trade_intents

list_trade_intents

MCP READ

按稳定序号顺序列出持久化的意图，适合做增量轮询。返回的是摘要——不含 payload，需要完整命令请用 get_trade_intent。

参数类型必填说明
statusstring | string[]可选按状态过滤。
after_seqinteger可选≥ 0，游标。配合 seq 做增量拉取。
limitinteger可选1–500，默认 100。
Request查未决意图
{
  "method": "list_trade_intents",
  "params": {
    "status": ["SUBMIT_UNKNOWN", "QUEUED"],
    "after_seq": 0,
    "limit": 50
  }
}
Responsedata · 数组
[
  {
    "seq": 128,
    "intent_id": "intent_7c2a",
    "intent_revision": 1,
    "preview_id": "preview_5c8e",
    "client_order_key": "cok_9d31",
    "account_alias": "main_stock",
    "status": "QUEUED",
    "action": "BUY",
    "symbol": "601398.SH",
    "requested_volume": 500,
    "limit_price": 7.05,
    "execution_mode": "OBSERVE_ONLY",
    "created_at": "2026-09-01T02:20:09.800Z",
    "updated_at": "2026-09-01T02:20:09.800Z"
  }
]

排查 SUBMIT_UNKNOWN 的标准手法。先用 status:"SUBMIT_UNKNOWN" 列出全部未决意图，逐个用 get_trade_intent 看关联的委托；确认后再在 QMT 里人工核对。这个计数大于 0 时，LIMITED_AUTO 的新订单会被拒绝。

人工实盘授权

authorize_manual_trade

authorize_manual_trade

MCP RISK destructiveHint

为一个准确、未过期、且最新硬风控仍通过的 MANUAL_LIVE 预览开启短时 LIVE 窗口，创建一次性审批，并返回可直接交给 submit_trade_intent 的 approval_context。

调用前置条件（缺一不可）。① 操作者已从本机把 Worker 和 QMT Adapter 切到 MANUAL_LIVE；② 已向用户展示预览的账户别名、证券、方向、最终数量、最终限价、名义金额、价格保护调整与风险结果；③ 已取得用户对这一笔预览的明确确认。MCP 无法替你切换模式。

参数类型必填说明
preview_idstring必填必须是 MANUAL_LIVE 预览。
live_minutesinteger可选1–60，默认 10。LIVE 窗口时长。
approval_ttl_secondsinteger可选1–300，默认 30。审批有效期，并会被预览到期时间截断。
reasonstring必填1–200 字符，写入审计日志。
confirmenum必填必须严格等于 AUTHORIZE-MANUAL-TRADE。
Requestparams
{
  "method": "authorize_manual_trade",
  "params": {
    "preview_id": "preview_5c8e",
    "live_minutes": 10,
    "approval_ttl_seconds": 30,
    "reason": "用户已在 WorkBuddy 核对账户、证券、数量和限价",
    "confirm": "AUTHORIZE-MANUAL-TRADE"
  }
}
Responsedata
{
  "account_alias": "main_stock",
  "preview_id": "preview_5c8e",
  "approval_id": "approval_1d90",
  "approval_context": { "local_approval_id": "approval_1d90" },
  "approval_expires_at": "2026-09-01T02:20:39.900Z",
  "live_until": "2026-09-01T02:30:09.900Z",
  "authorized_by": "mcp"
}

拒绝场景

  • LOCAL_CONFIRMATION_REQUIRED — 确认词不匹配。
  • PREVIEW_NOT_FOUND / PREVIEW_EXPIRED / PREVIEW_ALREADY_CONSUMED。
  • LIVE_NOT_ENABLED — 预览模式不是 MANUAL_LIVE、Worker 不在该模式、或已熔断。
  • RISK_REJECTED — 授权时会用当前数据重算一次硬风控；指纹变化（SNAPSHOT_CHANGED）或风控不通过都会拒绝。

若该账户已存在有效时间授权，live_until 会取两者中较晚的那个，不会被缩短。

人工实盘授权

authorize_manual_session

authorize_manual_session

MCP RISK destructiveHint

为已处于 MANUAL_LIVE 的账户开启 1–60 分钟的时间授权。有效期内订单笔数不设上限，submit_trade_intent 不再要求逐笔传入 approval_context。

不限笔数 ≠ 绕过交易流程。单标的每一笔仍必须走完「prepare_trade → submit_trade_intent」；批量场景则一次同步后分别预览、提交。提交时仍复算最新硬风控并比对风险决策指纹。预览过期、风险输入变化、额度超限、模式变化或熔断，一律拒绝。

参数类型必填说明
account_aliasstring必填账户别名。
minutesinteger可选1–60，默认 10。
reasonstring必填1–200 字符。
confirmenum必填必须严格等于 AUTHORIZE-TIMED-MANUAL-TRADING。
Requestparams
{
  "method": "authorize_manual_session",
  "params": {
    "account_alias": "main_stock",
    "minutes": 10,
    "reason": "用户确认未来 10 分钟允许 WorkBuddy 按策略连续下单",
    "confirm": "AUTHORIZE-TIMED-MANUAL-TRADING"
  }
}
Responsedata
{
  "account_alias": "main_stock",
  "session_id": "manual_session_4e11",
  "expires_at": "2026-09-01T02:30:00.000Z",
  "minutes": 10,
  "unlimited_orders": true,
  "still_requires_preview_and_risk_check": true,
  "authorized_by": "mcp"
}

调用前必须让用户看到三件事：准确的账户别名、持续时间、以及"期间订单笔数不设上限"这一提示，并取得明确确认。

人工实盘授权

get_manual_authorization_status

get_manual_authorization_status

MCP READ

查询账户的时间授权剩余秒数、LIVE 窗口与未使用逐笔审批数。用于向用户展示"还剩多久"以及在提交前自检。

Requestparams
{
  "method": "get_manual_authorization_status",
  "params": { "account_alias": "main_stock" }
}
Responsedata
{
  "account_alias": "main_stock",
  "mode": "MANUAL_LIVE",
  "halted": false,
  "timed_session_active": true,
  "timed_session": {
    "session_id": "manual_session_4e11",
    "account_alias": "main_stock",
    "authorized_by": "mcp",
    "reason": "用户确认未来 10 分钟允许 WorkBuddy 按策略连续下单",
    "created_at": "2026-09-01T02:20:00.000Z",
    "expires_at": "2026-09-01T02:30:00.000Z",
    "unlimited_orders": true,
    "still_requires_preview_and_risk_check": true
  },
  "remaining_seconds": 486,
  "live_until": "2026-09-01T02:30:00.000Z",
  "active_single_trade_approvals": 1
}

timed_session_active 为 true 需要同时满足：存在未过期会话、LIVE 窗口未关闭、未熔断、且模式为 MANUAL_LIVE。任一不满足即为 false，且 timed_session 返回 null。

人工实盘授权

revoke_manual_session

revoke_manual_session

MCP WRITE

立即撤销账户的时间授权。同时终止 LIVE 窗口，并使该账户尚未使用的逐笔审批一起过期。

Requestparams
{
  "method": "revoke_manual_session",
  "params": {
    "account_alias": "main_stock",
    "reason": "用户要求停止连续下单",
    "confirm": "REVOKE-TIMED-MANUAL-TRADING"
  }
}
Responsedata
{
  "account_alias": "main_stock",
  "revoked_session_id": "manual_session_4e11",
  "timed_session_active": false,
  "expired_single_trade_approvals": 2,
  "revoked_by": "mcp"
}
  • 切换运行模式或调用 halt_trading 也会立即使所有时间授权失效。
  • 解除熔断后不会自动恢复时间授权，必须重新授权。
  • 撤销不会撤销已经提交给柜台的委托——需要撤单请用 cancel_order。
  • 确认词必须严格等于 REVOKE-TIMED-MANUAL-TRADING。
有限自动交易 P1

check_limited_auto_readiness

check_limited_auto_readiness

MCP WRITE 永不报单

为单个账户跑失败关闭的 P1 readiness 与对账检查。会扫描队列、终结对账证据，并报告模式、Adapter 心跳、快照、死信与 SUBMIT_UNKNOWN 阻塞项。

Requestparams
{
  "method": "check_limited_auto_readiness",
  "params": { "account_alias": "main_stock" }
}
Responsedata · 未就绪
{
  "account_alias": "main_stock",
  "ready": false,
  "reasons": [
    "AUTO_ADAPTER_MODE_MISMATCH",
    "AUTO_ACCOUNT_SNAPSHOT_STALE"
  ],
  "scan_error_type": null,
  "reconciliation_run_id": "reconcile_3f81"
}

readiness 阻塞项

原因码含义排除方式
AUTO_ADAPTER_NOT_READYAdapter 离线或心跳超龄（> 15 秒）。确认 QMT 已登录、策略实例在运行。
AUTO_ADAPTER_MODE_MISMATCHAdapter 的 qmt_mode 与 Worker 不一致。同步 qmt_adapter.json 后重启策略。
AUTO_ADAPTER_LOCALLY_HALTEDAdapter 侧本地熔断。本机控制台 clear-halt。
AUTO_ADAPTER_LOCALLY_PAUSED许可已在本地暂停。用 resume_limited_auto 恢复（创建许可时会忽略此项）。
AUTO_DEAD_LETTER_PRESENT存在死信消息。死信始终要求暂停，必须人工清理。
AUTO_QUEUE_BACKLOG待处理队列超过 auto_max_queue_depth（默认 20）。等待队列消化或排查 Adapter。
AUTO_SUBMIT_UNKNOWN_PRESENT存在未决 SUBMIT_UNKNOWN。人工核对后清理。
AUTO_ACCOUNT_SNAPSHOT_STALE账户快照过期。request_sync 刷新 ACCOUNT。
AUTO_POSITION_SNAPSHOT_STALE持仓快照过期。request_sync 刷新 POSITION。
AUTO_ACCOUNT_DRAWDOWN_EXCEEDED账户回撤超过许可上限。只能创建新许可。
AUTO_CONSECUTIVE_FAILURE_LIMIT连续失败达上限。必须修正规则并更新 rule_version，不能恢复。
AUTO_RECONCILIATION_SCAN_FAILED对账扫描本身抛异常。scan_error_type 给出异常类名。

每次调用都会写入一条 reconciliation_runs 记录，可据此追溯历史。调用本身也会主动暂停存在阻塞项的活动许可。

有限自动交易 P1

authorize_limited_auto

authorize_limited_auto

MCP RISK destructiveHint

创建一个仅当日有效的 P1 自动下单许可。许可绑定账户、标的、动作、sizing 类型、策略版本、交易时段，以及订单/金额/频率/并发/持仓/回撤/连续失败共七类额度。

调用前必须向用户展示完整范围与全部上限，并取得明确确认。Worker 与 Adapter 必须已经处于 LIMITED_AUTO 且健康——本方法不会替你切模式。

必填参数

参数类型说明
account_aliasstring账户别名。
symbolsstring[]1–100 个，去重后不允许重复；必须落在账户白名单内。
actionsstring[]非空且唯一。普通账户：BUY/SELL。信用账户：六种显式动作。
source_typestring1–100 字符。后续每笔订单的 source.type 必须逐字一致。
rule_set_idstring1–100 字符，策略集标识。
rule_versionstring1–100 字符，策略版本。连续失败后靠升版重建许可。
max_order_notionalnumber单笔金额上限，且 ≤ 账户 max_order_notional。
max_order_volumeinteger单笔股数上限，且 ≤ 账户 max_order_volume。
max_session_notionalnumber许可累计金额上限，≤ max_auto_session_notional 与 max_daily_notional 的较小值，且 ≥ 单笔上限。
max_ordersinteger订单数上限，≤ 账户 max_auto_orders。
max_concurrent_ordersinteger并发委托上限，≤ 账户 max_auto_concurrent_orders。
max_symbol_position_notionalnumber单标的持仓市值上限。
max_account_drawdownnumber相对许可创建时总资产的最大回撤金额。
reasonstring1–500 字符。
confirmenum必须严格等于 AUTHORIZE-LIMITED-AUTO-P1。

可选参数

参数类型默认说明
minutesinteger4801–720，且 ≤ max_auto_authorization_minutes。实际到期会截断到当天 15:00，不能跨交易日。
min_order_interval_secondsinteger11–3600。只能比账户配置更慢，不能更快。
max_consecutive_failuresinteger31–100。达到后许可暂停且不可恢复。
trading_windowsobject[]09:30–11:30 / 13:00–15:001–8 个窗口，HH:MM；必须有序、不重叠、落在 09:15–15:00 内。
allowed_sizing_typesstring[]全部 5 种信用账户默认仅 FIXED_VOLUME/FIXED_NOTIONAL/AVAILABLE_CASH_PERCENT。
allow_credit_new_debtbooleanfalse含 MARGIN_BUY 或 SHORT_SELL 时必须显式设为 true。
Request完整授权示例
{
  "method": "authorize_limited_auto",
  "params": {
    "account_alias": "main_stock",
    "symbols": ["600000.SH", "000001.SZ"],
    "actions": ["BUY", "SELL"],
    "source_type": "intraday_monitor",
    "rule_set_id": "breakout-monitor",
    "rule_version": "2026-09-01-v1",
    "minutes": 480,
    "max_order_notional": 50000,
    "max_order_volume": 5000,
    "max_session_notional": 300000,
    "max_orders": 30,
    "min_order_interval_seconds": 10,
    "max_concurrent_orders": 2,
    "max_symbol_position_notional": 200000,
    "max_account_drawdown": 20000,
    "max_consecutive_failures": 2,
    "trading_windows": [
      { "start": "09:30", "end": "11:30" },
      { "start": "13:00", "end": "15:00" }
    ],
    "allowed_sizing_types": ["FIXED_VOLUME", "FIXED_NOTIONAL"],
    "allow_credit_new_debt": false,
    "reason": "用户确认当日盘中监控策略及全部额度",
    "confirm": "AUTHORIZE-LIMITED-AUTO-P1"
  }
}
Responsedata · 许可状态
{
  "configured": true,
  "active": true,
  "status": "ACTIVE",
  "permit_id": "auto_permit_71ba",
  "policy_hash": "e3b0c442...",
  "generation": 1,
  "starts_at": "2026-09-01T01:30:00.000Z",
  "expires_at": "2026-09-01T07:00:00.000Z",
  "remaining_seconds": 16800,
  "pause_reason": null,
  "revoked_reason": null,
  "policy": {
    "policy_version": 1,
    "permit_id": "auto_permit_71ba",
    "generation": 1,
    "account_alias": "main_stock",
    "account_type": "STOCK",
    "trading_day": "20260901",
    "timezone": "Asia/Shanghai",
    "trading_windows": [
      { "start": "09:30", "end": "11:30" },
      { "start": "13:00", "end": "15:00" }
    ],
    "allowed_symbols": ["000001.SZ", "600000.SH"],
    "allowed_actions": ["BUY", "SELL"],
    "allowed_sizing_types": ["FIXED_NOTIONAL", "FIXED_VOLUME"],
    "source": {
      "type": "intraday_monitor",
      "rule_set_id": "breakout-monitor",
      "rule_version": "2026-09-01-v1"
    },
    "max_order_notional": 50000.0,
    "max_order_volume": 5000,
    "max_session_notional": 300000.0,
    "max_orders": 30,
    "min_order_interval_seconds": 10,
    "max_concurrent_orders": 2,
    "max_symbol_position_notional": 200000.0,
    "max_account_drawdown": 20000.0,
    "max_consecutive_failures": 2,
    "baseline_total_asset": 988523.46,
    "allow_credit_new_debt": false,
    "starts_at": "2026-09-01T01:30:00.000Z",
    "expires_at": "2026-09-01T07:00:00.000Z"
  },
  "usage": { "order_count": 0, "notional": 0.0 },
  "remaining_orders": 30,
  "remaining_notional": 300000.0,
  "health_reasons": []
}

480 分钟的用意。默认授权一次即可覆盖完整交易日，不需要每 60 分钟重新授权。但午休、收盘、周末和许可外时段仍然不能产生新自动订单——时段窗口是独立硬约束。

每个账户同时只允许一个活动许可。创建新许可会把旧的置为 REVOKED（revoked_reason = "superseded by a new permit"）。需要并行多策略时，应使用不同的、独立验收的账户别名与 Adapter 实例，不能共享额度。

有限自动交易 P1

get_limited_auto_status

get_limited_auto_status

MCP READ

返回最新的 P1 许可、完整策略、剩余时间/订单数/金额、暂停原因与当前健康阻塞项。这是自动交易循环里的常规轮询点。

Requestparams
{
  "method": "get_limited_auto_status",
  "params": { "account_alias": "main_stock" }
}
Responsedata · 已暂停
{
  "configured": true,
  "active": false,
  "status": "PAUSED",
  "permit_id": "auto_permit_71ba",
  "policy_hash": "e3b0c442...",
  "generation": 1,
  "starts_at": "2026-09-01T01:30:00.000Z",
  "expires_at": "2026-09-01T07:00:00.000Z",
  "remaining_seconds": 9600,
  "pause_reason": "AUTO_SUBMIT_UNKNOWN_PRESENT",
  "revoked_reason": null,
  "policy": { "...": "完整策略" },
  "usage": { "order_count": 4, "notional": 128400.0 },
  "remaining_orders": 26,
  "remaining_notional": 171600.0,
  "health_reasons": ["AUTO_SUBMIT_UNKNOWN_PRESENT"]
}

status 取值

状态含义可提交新订单
NONE从未创建过许可（configured:false）。否
ACTIVE许可有效、未暂停、代次匹配、模式正确、未熔断。是
PAUSED被健康守卫暂停，需显式恢复。否
EXPIRED剩余秒数归零（跨日或过 15:00）。否
REVOKED已撤销，或被新许可取代。否
INVALID策略 JSON 解析失败。否

active:true 的判定是五个条件同时成立：记录状态为 ACTIVE、剩余时间 > 0、generation 与当前代次一致、Worker 模式为 LIMITED_AUTO、未熔断。

有限自动交易 P1

resume_limited_auto

resume_limited_auto

MCP RISK

在 readiness 恢复后，显式恢复被健康守卫暂停的许可。同时轮换授权代次，使暂停前签发的旧命令继续无效。

Requestparams
{
  "method": "resume_limited_auto",
  "params": {
    "account_alias": "main_stock",
    "reason": "SUBMIT_UNKNOWN 已人工核对并清理，快照已重新同步",
    "confirm": "RESUME-LIMITED-AUTO-P1"
  }
}
Responsedata · 代次已 +1
{
  "configured": true,
  "active": true,
  "status": "ACTIVE",
  "permit_id": "auto_permit_71ba",
  "policy_hash": "c7f1a9d2...",
  "generation": 2,
  "remaining_seconds": 9500,
  "pause_reason": null,
  "policy": {
    "generation": 2,
    "resumed_at": "2026-09-01T04:12:00.000Z",
    "...": "其余策略字段不变"
  },
  "usage": { "order_count": 4, "notional": 128400.0 },
  "remaining_orders": 26,
  "remaining_notional": 171600.0,
  "health_reasons": []
}

连续失败达上限时不能恢复。若 pause_reason 含 AUTO_CONSECUTIVE_FAILURE_LIMIT，本方法返回 AUTO_STRATEGY_REAUTHORIZATION_REQUIRED。必须修正规则、更新 rule_version 并创建新许可——这是刻意的设计，防止坏策略自我复活。

恢复流程标准顺序：排除原因 → request_sync 重新同步 → check_limited_auto_readiness 确认 ready:true → resume_limited_auto。系统不会静默自动恢复。

有限自动交易 P1

revoke_limited_auto

revoke_limited_auto

MCP WRITE

立即撤销活动或已暂停的许可，并轮换其授权代次。

Requestparams
{
  "method": "revoke_limited_auto",
  "params": {
    "account_alias": "main_stock",
    "reason": "用户要求立即停止当日自动交易",
    "confirm": "REVOKE-LIMITED-AUTO-P1"
  }
}
Responsedata
{
  "account_alias": "main_stock",
  "revoked_permit_id": "auto_permit_71ba",
  "active": false
}

撤销不会自动撤销已提交给柜台的委托。需要平仓或撤单，请另行用 cancel_order 逐张处理。

切换模式、触发熔断、跨日，都会使许可失效。撤销后如需继续自动交易，必须重新走 readiness + 授权流程。

同步与熔断

request_sync

request_sync

MCP WRITE 永不报单

请求 Adapter 拉取全新快照。这是所有交易流程的第一步：QUOTE 域会同时取得涨跌停、最小价位、盘口基准与动态价格笼子。

参数类型必填说明
account_aliasstring必填账户别名。
scopesstring[]必填非空去重，取值见下表。
symbolsstring[]条件含 QUOTE 时必填，1–100 个；不含 QUOTE 时禁止传。

scopes 取值

Scope拉取内容对应查询方法
ACCOUNT账户资产快照get_account_snapshot
POSITION持仓快照get_positions
ORDER委托记录get_orders
DEAL成交记录get_trades
QUOTE行情 + 涨跌停 + 最小价位 + 价格笼子get_quote_snapshot
CREDIT_ACCOUNT信用资产与维持担保比例get_credit_account_snapshot
CREDIT_DEBT信用负债合约get_credit_debt_contracts
CREDIT_ELIGIBILITY标的两融资格get_credit_instrument_eligibility
Request交易前标准同步
{
  "method": "request_sync",
  "params": {
    "account_alias": "main_stock",
    "scopes": ["ACCOUNT", "POSITION", "ORDER", "QUOTE"],
    "symbols": ["601398.SH"]
  }
}
Responsedata
{
  "message_id": "msg_31ad",
  "status": "DELIVERED",
  "command_type": "REQUEST_SYNC"
}

返回 DELIVERED 只表示命令已入队。快照写入需要一点时间。正确做法是轮询 qmt_health 看 account_snapshot_age_seconds 回落，或直接调用对应查询方法检查 age_seconds，再进入 preview_trade。

同步与熔断

halt_trading

halt_trading

MCP RISK destructiveHint

远程失败关闭：立即停止所有新交易。只能由本机控制台清除。

参数类型必填说明
reasonstring必填1–500 字符，写入审计与 Adapter 熔断文件。
Requestparams
{
  "method": "halt_trading",
  "params": { "reason": "行情源异常，暂停全部交易" }
}
Responsedata
{
  "mode": "MANUAL_LIVE",
  "halted": true,
  "reason": "行情源异常，暂停全部交易",
  "clearing_requires_local_console": true
}

熔断时一次性完成的事

  • 删除所有账户的时间授权会话（manual_session:*）。
  • 把所有账户的 live_until 设为当前时刻，LIVE 窗口立即关闭。
  • 使所有未使用的逐笔审批过期。
  • 把全部 ACTIVE/PAUSED 的 P1 许可置为 REVOKED，原因为 global trading halt。
  • 轮换所有账户的授权代次。
  • 向每个 Adapter 运行时写入一条长效熔断文件（TTL 十年，刻意如此）。
PowerShell清除熔断（仅本机控制台）
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" clear-halt --reason "已排除的具体原因" --confirm CLEAR-HALT

桥接处于熔断时会拒绝直接改模式。必须先 clear-halt。解除熔断后模式固定回到 OBSERVE_ONLY，且时间授权不会自动恢复——先让 Worker 和所有 Adapter 在观察模式下恢复正常，再考虑切换。

附录

风控原因码

这些代码出现在 preview_trade 的 risk.reasons 数组与 RISK_REJECTED 错误的 details.reasons 中。risk.allowed 为 true 的唯一条件是这个数组为空。

通用

原因码含义
ACCOUNT_SNAPSHOT_STALE账户快照缺失或超过 max_snapshot_age_seconds。
POSITION_SNAPSHOT_STALE持仓快照缺失或超龄。
QUOTE_SNAPSHOT_STALE行情快照缺失或超过 max_quote_age_seconds。
MARKET_DATA_STALE行情不足以计算价格笼子或涨跌停。
PRICE_DEVIATION_EXCEEDED价格偏离超过 max_deviation_pct。
INSTRUMENT_NOT_ALLOWED标的不在账户白名单内。
ACTIVE_ORDER_CONFLICT同标的存在活动委托。

数量与资金

原因码含义
ZERO_RESOLVED_VOLUME推导出的数量为 0。
ZERO_BUY_VOLUME_NOT_ALLOWED买入数量为 0（0 股委托一律禁止）。
ZERO_SELL_VOLUME_NOT_ALLOWED卖出数量为 0。
MINIMUM_SELL_VOLUME_NOT_MET卖出量低于最低卖出数量且不允许零股卖出。
INSUFFICIENT_AVAILABLE_CASH可用资金不足。
INSUFFICIENT_AVAILABLE_VOLUME可卖数量不足。
MAX_ORDER_NOTIONAL_EXCEEDED超过单笔名义金额上限。
MAX_ORDER_VOLUME_EXCEEDED超过单笔股数上限。
MAX_DAILY_NOTIONAL_EXCEEDED当日累计（成交 + 活动意图 + 本笔）超过单日上限。

信用专用

原因码含义
CREDIT_SNAPSHOT_STALE信用快照缺失或超龄。
CREDIT_RISK_LIMIT维持担保比例低于下限，或负债/额度校验失败。
CREDIT_INSTRUMENT_NOT_ELIGIBLE标的不具备该动作的资格。
CREDIT_CAPACITY_UNAVAILABLE缺少动作所需的额度快照。
CREDIT_DEBT_NOT_FOUND还款动作找不到对应负债合约。
CONFIGURED_CREDIT_ACTION_REJECTED通用买卖映射到配置动作后被拒绝（不做第二次尝试）。

P1 有限自动

原因码含义
AUTO_PERMIT_REQUIRED没有活动许可。
AUTO_PERMIT_EXPIRED许可已过期。
AUTO_MODE_NOT_ENABLEDWorker 模式不是 LIMITED_AUTO。
AUTO_TRADING_HALTED已熔断。
AUTO_POLICY_HASH_MISMATCH策略哈希与许可不一致。
AUTO_POLICY_INVALID策略 JSON 无法解析。
AUTO_POLICY_EXCEEDS_CURRENT_CONFIG策略额度超出当前账户配置硬上限。
AUTO_SYMBOL_NOT_ALLOWED标的不在许可允许列表内。
AUTO_ACTION_NOT_ALLOWED动作不在许可允许列表内。
AUTO_SIZING_NOT_ALLOWEDsizing 类型不在许可允许列表内。
AUTO_STRATEGY_BINDING_MISMATCHsource.type / rule_set_id / rule_version 与许可不一致。
AUTO_OUTSIDE_TRADING_WINDOW当前时间不在许可交易时段内。
AUTO_ORDER_NOTIONAL_EXCEEDED超过许可单笔金额上限。
AUTO_ORDER_VOLUME_EXCEEDED超过许可单笔股数上限。
AUTO_SESSION_NOTIONAL_EXCEEDED超过许可累计金额上限。
AUTO_ORDER_COUNT_EXCEEDED超过许可订单数上限。
AUTO_ORDER_RATE_EXCEEDED下单间隔短于 min_order_interval_seconds。
AUTO_CONCURRENT_ORDER_LIMIT并发活动委托数超限。
AUTO_SYMBOL_POSITION_LIMIT单标的持仓市值将超过上限。
AUTO_ACCOUNT_DRAWDOWN_EXCEEDED账户回撤超过许可上限。
AUTO_CREDIT_NOT_ENABLED信用账户未开启自动交易。
AUTO_CREDIT_NEW_DEBT_NOT_ALLOWED新增负债动作未获显式许可。
AUTO_ADAPTER_NOT_READYAdapter 离线或心跳超龄。
AUTO_ADAPTER_MODE_MISMATCHAdapter 模式漂移。
AUTO_ADAPTER_LOCALLY_HALTEDAdapter 侧本地熔断。
AUTO_ADAPTER_LOCALLY_PAUSED许可已在本地暂停。
AUTO_QUEUE_BACKLOG队列积压超限。
AUTO_DEAD_LETTER_PRESENT存在死信消息。
AUTO_SUBMIT_UNKNOWN_PRESENT存在未决 SUBMIT_UNKNOWN。
AUTO_ACCOUNT_SNAPSHOT_STALE账户快照对自动交易而言过旧。
AUTO_POSITION_SNAPSHOT_STALE持仓快照对自动交易而言过旧。
AUTO_CONSECUTIVE_FAILURE_LIMIT连续失败达上限（不可恢复）。

哪些会暂停许可。只有 AUTO_PAUSE_REASONS 集合内的 10 项会触发暂停：Adapter 未就绪/模式漂移/本地熔断/本地暂停、死信、队列积压、SUBMIT_UNKNOWN、账户快照陈旧、持仓快照陈旧、账户回撤超限、连续失败超限。其余原因只拒绝当笔，不暂停许可。

附录

状态机

交易意图状态

状态类别含义
QUEUED进行中已入队，等待 Adapter 取走。
SUBMIT_CALLED进行中Adapter 已调用 passorder，等待回执。
SUBMIT_UNKNOWN需人工提交结果未明。系统不会自动重发，且会阻止新自动订单。
ACCEPTED / PARTIALLY_FILLED进行中柜台已受理，等待成交。
FILLED终态全部成交。
CANCELLED / PARTIALLY_CANCELLED终态已撤销（含部分撤单）。
OBSERVE_ONLY_ACKNOWLEDGED终态观察模式下 Adapter 空跑并回 ACK，未报单。
RISK_REJECTED终态硬风控拒绝。
APPROVAL_REJECTED终态授权/审批未通过。
QMT_REJECTED终态QMT 侧拒绝。
BROKER_REJECTED终态柜台拒绝。
EXPIRED终态命令超过 command_ttl_seconds 未被取走。
PREVIEW_EXPIRED终态预览在提交前过期。
FAILED终态其他失败。

计入 P1 连续失败的状态。QMT_REJECTED、BROKER_REJECTED、FAILED、SUBMIT_UNKNOWN 四项。达到 max_consecutive_failures 后许可暂停且不可恢复。

委托状态

活动状态（可用 cancel_order 撤销）：

QUEUED  REPORTED  ACCEPTED  ORDER_ACCEPTED  PARTIALLY_FILLED  CANCEL_REQUESTED  SUBMIT_CALLED

其余状态（FILLED、CANCELLED、REJECTED 等）为终态，撤销会返回 ORDER_NOT_CANCELLABLE。活动委托同时构成新订单的 ACTIVE_ORDER_CONFLICT 校验输入。

P1 许可状态流转

  （无许可）NONE
       │  authorize_limited_auto（需 ready）
       ▼
    ACTIVE ────── 健康守卫触发 ──────► PAUSED
       │                                  │
       │                                  │ check_limited_auto_readiness
       │                                  │ + resume_limited_auto（代次 +1）
       │◄─────────────────────────────────┘
       │
       ├── 剩余时间归零 / 跨日 ──────────► EXPIRED
       ├── revoke_limited_auto ──────────► REVOKED
       ├── 创建新许可（取代旧的）────────► REVOKED（superseded by a new permit）
       ├── halt_trading ─────────────────► REVOKED（global trading halt）
       └── 切换模式 ─────────────────────► 失效（active=false）
  PAUSED 且 pause_reason 含 AUTO_CONSECUTIVE_FAILURE_LIMIT
       └──► 不可恢复，必须更新 rule_version 后创建新许可
附录

配置参考

所有配置文件都位于本机运行目录，不支持热重载——修改后必须重启 Worker，涉及 Adapter 的还要重启 QMT 策略实例。

%LOCALAPPDATA%\WorkBuddyQMTBridge\runtime\
├── config\
│   └── bridge.json              Worker 全局、账户与风控参数
├── data\
│   ├── secrets\
│   │   ├── message_keys.json    本机消息签名密钥（绝不外传）
│   │   └── worker.token         Worker API 令牌（不写入 MCP 配置）
│   └── state\
│       └── bridge.db            状态库（改动前备份 WAL/SHM）
├── qmt_ready\
│   └── <账户别名>\
│       ├── qmt_adapter.py       部署到大 QMT 的策略源码
│       ├── qmt_adapter.json     Adapter 配置（含 qmt_mode）
│       └── qmt_profile.json     签名 Profile（P0 后生成）
└── logs\
    └── data\logs\worker-YYYY-MM-DD.log

bridge.json · 全局

参数默认值说明
data_dir../data数据库、队列、日志、运行状态目录。建议保留相对路径。
host127.0.0.1只接受数字形式的本机回环地址。
port176421–65535。MCP 的 --endpoint 必须用同一端口。
default_modeOBSERVE_ONLY仅在数据库首次创建时生效，不是当前模式。
max_message_bytes655361024–16777216。生成的 Adapter 会同步此值。
key_file../data/secrets/message_keys.json本机消息签名密钥。
worker_token_file../data/secrets/worker.tokenWorker 令牌，长度不得小于 32。
accounts[]array账户配置，alias 与 adapter_instance 必须唯一。

bridge.json · 每个账户

参数默认值说明
aliasmain_stock只能用 ASCII 字母、数字、点、下划线、连字符。
account_typeSTOCKSTOCK 或 CREDIT。
adapter_instanceqmt_stock_01所有账户之间不得重复。
enabledSTOCK:true / CREDIT:false信用账户默认不启用。
lot_size100整手单位。
odd_lot_sell_allowedtrue尾数不足最低卖出量时允许一次全卖；但 0 股仍禁止。
instrument_allowlist[]空数组不额外限制；非空时只允许列出的代码。
limited_auto_credit_enabledfalse信用 P1 开关，需在 Bridge 与 Adapter 双侧开启。
credit_action_mappingbuy:MARGIN_BUY / sell:COLLATERAL_SELL通用买卖的信用动作映射，不做第二次尝试。

qmt_adapter.json · 轮询

参数默认值说明
command_poll_interval_ms500Adapter 读取命令队列的间隔；脚本接受 100–5000 毫秒，安装器生成且 doctor 期望的值为 500。不要手工调低，以免增加 QMT 主线程负载或形成配置漂移。
order_deal_reconcile_seconds30委托/成交完整兜底对账周期，允许 10–3600 秒。实时状态优先来自 QMT 回调；启动、显式同步和异常报单仍可提前触发完整对账。

Worker 内部队列扫描默认间隔为 250 毫秒。Adapter 每 5 秒刷新账户和持仓，委托/成交以实时回调为主并按上述周期完整对账。相关改造不跳过行情刷新、签名、授权或硬风控。

下单数量规则

适用证券最低买入最低卖出
科创板 688、689 开头200 股200 股
其他证券（含创业板）100 股100 股

默认额度（百万级账户口径）

账户类型max_order_notionalmax_order_volumemax_daily_notional
普通证券账户200000 元500000 股2000000 元
信用账户100000 元500000 股1000000 元

两个股数/金额上限同时校验：即使股数未达 50 万股，只要名义金额超过对应单笔上限仍会拒绝。信用账户上限更低，用于覆盖两融的额外杠杆与负债风险。

Profile 与 P0

新环境生成的 qmt_profile.json 刻意保持 verified=false 且签名为空，不能直接运行 SIM_SIGNAL 或 MANUAL_LIVE。完成目标电脑、目标 QMT 构建、目标柜台的 P0 后，需填写以下字段并同步：

自 v0.3.4 起的 Profile 升级保护。重复运行安装向导、setup 或 setup --force 都会保留已有 Profile。只有显式指定 --reset-profile <账户别名> 并同时提供 --confirm-reset-profile RESET-QMT-PROFILE 才能重置，且重置前会创建时间戳备份。

  1. 填 profile_id、qmt_build、broker_build、mappings，设 verified=true。
  2. 把前三个值逐字同步到 qmt_adapter.json 的 expected_profile_id、expected_qmt_build、expected_broker_build。
  3. 核对 adapter_binding 中的账户别名、账户类型、Adapter 实例、完整 QMT 账户号、策略名。
  4. 用本机密钥签名（见下）。
  5. 运行 doctor 确认全部通过。
JSONmappings · 普通股票限价买卖
{
  "mappings": {
    "STOCK:STOCK:BUY:LIMIT": {
      "op_type": 23,
      "order_type": 1101,
      "price_type": 11
    },
    "STOCK:STOCK:SELL:LIMIT": {
      "op_type": 24,
      "order_type": 1101,
      "price_type": 11
    }
  }
}
PowerShell签名（必须是最后一步）
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" sign-qmt-profile "<runtime>\qmt_ready\main_stock\qmt_profile.json" --confirm VERIFIED-PROFILE

签名后再改任何字段都会使签名失效。这些映射只覆盖普通股票限价买卖，不代表市价、信用、基金、期货或其他动作已开放。旧电脑、旧账户、旧构建的签名 Profile 不可复用——签名必须在目标电脑本机完成。

附录

本机控制台

MCP 无法做的事，全部收敛在这里：切换模式、解除熔断、签名 Profile、运行诊断。这些操作需要本机文件与命令行权限，是有意为之的安全边界。

命令作用是否需确认词
set-mode <MODE>切换 Worker 运行模式。OBSERVE_ONLY 不需要；其余需 --confirm <同名>
clear-halt解除熔断。模式会固定回到 OBSERVE_ONLY。--confirm CLEAR-HALT
sign-qmt-profile <路径>用本机密钥签名 Profile。--confirm VERIFIED-PROFILE
setup --reset-profile <账户别名>有意废弃指定账户的已有 Profile，并重建未验证模板。--confirm-reset-profile RESET-QMT-PROFILE
doctor检查配置、Profile、Adapter 与同步项。否
verify --human统一验收安装、MCP、Worker、QMT 文件和 Adapter 运行状态。否
account list/enable/configure查看、启用或重新生成账户 QMT 文件；修改前必须停止 Worker。停用账户需要 DISABLE-ACCOUNT
open qmt-ready/logs/config打开常用本机目录或配置文件。否
upgrade-check只读查询 GitHub 最新正式版本，不自动升级。否
support-bundle --redact生成不含日志正文、密钥、Token、完整账户号和 Profile 内容的诊断 ZIP。必须显式指定 --redact
PowerShell完整命令集
# 通用形式；python 可替换为安装时使用的 py -3
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" <命令>

# 切回观察模式（不需要确认）
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" set-mode OBSERVE_ONLY

# 切换到模拟信号 / 人工实盘 / 有限自动（确认词必须与模式名完全一致）
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" set-mode SIM_SIGNAL   --confirm SIM_SIGNAL
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" set-mode MANUAL_LIVE  --confirm MANUAL_LIVE
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" set-mode LIMITED_AUTO --confirm LIMITED_AUTO

# 解除熔断（熔断期间拒绝改模式，必须先执行本命令）
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" clear-halt --reason "已排除的具体原因" --confirm CLEAR-HALT

# 签名 Profile（P0 闭环后的最后一步）
python -m workbuddy_qmt.console --config "<runtime>\config\bridge.json" sign-qmt-profile "<runtime>\qmt_ready\main_stock\qmt_profile.json" --confirm VERIFIED-PROFILE

# 验证安装版本
python -c "import workbuddy_qmt; print(workbuddy_qmt.__version__)"

控制台只改 Worker 本机状态。它不会修改 qmt_adapter.json，也不会重启 QMT 策略。切模式后仍须：停止策略 → 改 qmt_mode → 重启策略 → 启动 Worker → qmt_health 复核。

升级到 0.3.0

  1. 停止 Worker 与所有 QMT Adapter，撤销现有人为时间授权。
  2. 完整备份 runtime——特别是 bridge.db 及同目录的 -wal / -shm 文件、密钥、Profile、执行日志。
  3. 把新版 ZIP 完整解压到新的独立目录（不要把新旧 wheel 混放，安装脚本只会挑一个）。
  4. 运行 安装、升级或修复.cmd。旧名称仍作为兼容入口；数据库 schema 会从 1 自动迁移到 2。
  5. 0.3.0 改了命令与 Adapter 授权协议，必须把新生成的 qmt_adapter.py 重新部署到每个策略实例，并同步 qmt_adapter.json 的 P1 硬上限后重启策略。
  6. 确认工具数变为 29，且存在五个 *_limited_auto* 工具。
  7. 先在 OBSERVE_ONLY 跑 doctor，再在目标模拟柜台完整验证失败关闭路径。

需要同步到 Adapter 的 P1 字段：adapter_max_auto_session_notional、adapter_max_auto_orders、adapter_min_auto_order_interval_seconds、adapter_max_auto_concurrent_orders、adapter_max_auto_symbol_position_notional、adapter_max_auto_account_drawdown、limited_auto_credit_enabled。

Profile schema 未变——只要没改 Profile 内容和三个 expected_* 绑定，不需要重新签名。回退时应整体恢复升级前备份，不能只装旧 wheel。

附录

排障速查

现象根因处理
BRIDGE_UNAVAILABLEWorker 未运行，或 17642 被占用。运行 查看QMT桥接状态.cmd；关闭旧 Worker 后重启。
Adapter 显示 OFFLINEQMT 未登录、策略未启动，或部署的不是最新脚本。重新部署 qmt_ready 中的脚本并重启策略；大 QMT 控制台默认每 30 秒打印一行心跳。
预览反复 QUOTE_SNAPSHOT_STALE行情超龄（默认 30 秒）。request_sync 带 QUOTE 域后立即预览；不要调大阈值绕过。
SNAPSHOT_CHANGED风险决策指纹变化（资金/可卖量/价格/活动委托/额度/信用任一实质变化）。重新预览。仅快照重编号或市值波动不会触发。
LIVE_NOT_ENABLEDWorker 模式不是 MANUAL_LIVE、已熔断、或预览模式不对。查 qmt_health 的 mode 与 halted。
ACCOUNT_TYPE_MISMATCH对普通账户调了信用接口，或动作不适用于该账户类型。核对 list_account_aliases 返回的 account_type。
MESSAGE_SCHEMA_INVALIDAdapter 与 Worker 版本不匹配（0.3.0 改了命令协议）。重新部署 qmt_adapter.py 并重启 QMT 策略。
SIGNATURE_INVALID密钥不一致或已轮换。确认 Adapter 与 Worker 指向同一 runtime 的 key_file。
切不回非观察模式处于熔断状态。先 clear-halt；解除后模式固定回到 OBSERVE_ONLY。
自动交易突然不下单了许可被健康守卫暂停。get_limited_auto_status 看 pause_reason；排除后跑 readiness 再 resume_limited_auto。
连续失败后无法恢复许可触发 AUTO_CONSECUTIVE_FAILURE_LIMIT。设计如此。修正规则、更新 rule_version、创建新许可。
MCP JSON 无效%USERPROFILE%\.workbuddy\mcp.json 语法错误。先修好 JSON 再重跑安装脚本——向导不会覆盖无效文件。
提示"找不到 wheel"没有完整解压 ZIP，或脚本与 wheel 不在同一目录。重新完整解压。
需要提交诊断材料原始日志和 runtime 可能包含敏感信息。运行 support-bundle --redact，并在分享前再次检查 ZIP 内容。

日常启动顺序

  1. 打开并登录大 QMT；
  2. 启动对应的 QMT 策略实例；
  3. 双击 启动QMT桥接.cmd，选择本次统一运行模式（不确定就直接回车用 OBSERVE_ONLY）；
  4. 保持 Worker 控制台窗口打开；
  5. 打开或重启 WorkBuddy；
  6. 在 WorkBuddy 里先查 qmt_health、账户与持仓，再做后续操作。

关闭控制台或 Ctrl+C 会安全停止 Worker——但不会自动关闭 QMT 或 WorkBuddy，也不会自动撤销已提交给柜台的委托。

不要做的事。不要通过直接修改数据库、队列或签名文件来绕过检查；不要复制其他电脑的密钥、令牌或已签名 Profile；不要把 runtime、账户号、密钥、令牌或数据库放进公开代码仓库，或发送给他人。

文档版本
2026-09-13 源码修订版
适用桥接版本
0.3.5
MCP 工具数
31
运行环境
Windows · Python ≥ 3.10
传输协议
MCP stdio + 本机 HTTP /rpc
默认监听
127.0.0.1:17642
许可证
MIT © 2026 peppaboar95
文档形态
单文件离线 · 无外部依赖

关于本文档

本文档描述 WorkBuddy-QMT Bridge 0.3.5 的 MCP 工具接口、传输协议、风控原因码与配置参数，内容与源码中的 mcp_server.py、core.py、worker.py、config.py 实现一一对应。示例中的账户别名、标的、价格、委托号与金额均为虚构演示值，不包含任何真实账户信息、密钥或令牌。

当前安装资产与升级说明：Release v0.3.5；项目源码与历史：GitHub 仓库。

本文件为自包含 HTML：不加载任何 CDN、外部字体或远程脚本，可离线双击打开，也可直接托管在任意静态站点上。

免责声明

本桥接为本地工具，不构成投资建议。它只是把操作者的指令翻译成结构化查询与下单动作，不提供任何买卖判断、策略信号或收益承诺。所有交易决策及其后果由操作者自行承担。

运行模式不代表柜台类型。SIM_SIGNAL、MANUAL_LIVE、LIMITED_AUTO 均无法识别当前连接的是模拟柜台还是真实资金柜台。启用任何非观察模式前，操作者必须在 QMT 中自行核对账户与柜台，并完成目标环境的 P0 现场验收。

软件按「原样」提供。依据 MIT 许可证，作者不对软件的适用性、准确性、完整性或未侵权作任何明示或默示的担保，亦不对因使用或无法使用本软件所导致的任何直接、间接、附带、特殊、惩罚性或后果性损失承担责任，无论该损失是否已被预见。

证券交易存在风险。融资融券交易具有财务杠杆效应，可能成倍放大收益或损失。启用自动交易功能前，请完整阅读发布包中的 P1-VALIDATION.zh-CN.md，充分理解其验证范围与仍需现场验收的边界。