运行库存与显式数据同步

这些接口读取当前登录用户的运行库存，并查询或更新已有运行的打点数据。它们不启动、停止或执行策略，也不生成打点、时间或标的。真实后台尚未验证，读取与写入开关默认关闭。

操作	REST POST	MCP	CLI
库存单页	/api/get-quant-running-inventory	futu_get_quant_running_inventory	get-quant-running-inventory
数据单页	/api/get-quant-running-data	futu_get_quant_running_data	get-quant-running-data
显式 upsert	/api/upsert-quant-running-data	futu_upsert_quant_running_data	upsert-quant-running-data

Gateway 和 gRPC 使用同名公开协议；网关私有请求须使用带 API-key 认证的原生二进制 WebSocket。MCP 与 CLI 通过已认证 REST 转发，必须配置 REST 地址并提供调用者 API key。

读取需要 acc:read，写入同时需要 acc:read 与 qot:write。这些数据属于整个用户，账户受限 key（包括空账户列表）均不可访问。不得提供 UID 切换用户。数据读写会先核对当前运行库存中的真实 running_id；云档案 ID 或本地策略 ID 不可替代。

库存

所有请求必填 extension_version: 1。库存支持可选 filter、sort_field、is_asc、from、count；from 非负，显式 count 为 1–200。只返回一页，保留原始 all_count、has_more、next_from 是否存在；不会自动翻页。

filter 可指定 need_detail、至多 300 个 running_id_list、运行状态/停止原因/容器等级列表，以及创建或停止时间区间。区间包含可选 min_value、max_value、exclude_min、exclude_max，时间单位为 Unix 秒。响应保留未知状态值；detail_info 原字节与 decoded_detail、detail_decode_state 分离，坏内层数据不会使整行消失。

查询与写入

数据查询必填真实 running_id 和 data_type: 1。可选 next_offset 为非负 int64；0 或缺失从首/尾开始，其余为排他游标。可选 sort_ascend 控制顺序，count 为 0–1000（0/缺失交给后台默认）。返回可能因大小截断，没有可靠的终页标志；不要根据短页断言全部读取完毕。running_id 必须能表示为正 int64。

upsert 必填不可变 intent_key、真实 running_id 以及非空 data_list。每项明确提供 data_type: 1、正 int64 data_offset 和原始 data 字节数组。该字节串必须包含完整公开 BarMarker 的四个字段：bar_marker_time、bar_marker_stock、bar_marker_icon、bar_marker_content，即使值为 0 或空字符串也必须实际存在。服务端按运行、类型、offset 更新已有数据或插入新数据；同批重复目标被拒绝。

每次最多 500 项。最终序列化的后端请求必须小于 1,024,000 字节；upsert 的 REST JSON 总请求上限为 10 MiB，包含字节数组展开。这两项上限分别计算。

提交结果

写入返回持久 receipt：receipt_id、ack_state、backend_code（存在时）与 replayed。ack_success、ack_rejected 和 submitted_unknown 区分明确应答与未知结果。相同 intent 重入不会再次发送业务请求；未决目标也不能换一个 intent 绕过。

upsert 不自动读回。独立数据查询只是观察；值相同不能证明收到写入 ACK，缺行也不能证明未写入。此接口没有跨其它客户端的 CAS 或全局顺序保证。实际数据 bytes、坏内层 payload 和未知响应类型都保留，解码结果单独提供。