智能盯盘事件与统计¶

网关需显式启用 --enable-desktop-phase2-reads；默认关闭，真实后台尚未验证。三个接口均需 qot:read，订阅属于当前连接/调用者的行情状态。

操作	REST POST	MCP	CLI
历史事件	`/api/tape-reading-events`	`futu_get_tape_reading_events`	`tape-reading-events`
统计快照	`/api/tape-reading-statistics`	`futu_get_tape_reading_statistics`	`tape-reading-statistics`
订阅	`/api/set-tape-reading-subscription`	`futu_set_tape_reading_subscription`	`set-tape-reading-subscription`

通用 gRPC 使用同一公开消息。extension_version 必须为 1。CLI 三个命令均使用 --ws-url 指定原生二进制 WebSocket 地址，--api-key 或 FUTU_API_KEY 提供实际调用者身份；MCP 通过 --tape-ws-url / FUTU_MCP_TAPE_WS_URL 配置同类地址。不要填 REST /ws 地址或猜测端口。API Key 只通过握手 Authorization 头传递。

读取¶

市场枚举为 HK=1、US=2、CN=3、SG=6、CA=7、AU=8、JP=9、MY=10、KR=11，不是其它行情接口的市场编号。0 不表示所有市场。

{"extension_version":1,"event_list_type":1,"stock_market":1,"iterator":0,"size":20}

event_list_type：1 按市场，2 按 stock_id_list，3 按 category_id。证券/类别标识使用真实查询结果，不从代码字符串推算。iterator 与 size 必须显式填写；响应游标原样用于下一页，响应游标为 0 表示终页，缺失游标不能推断为结束。空证券列表可返回 local_only=true 的本地空结果，不能视作新的后台确认。

可选 begin_time、end_time 是秒时间戳，0 按缺失处理；filter_event_type 保留整数过滤条件。空过滤列表使用后台用户配置。历史事件保留原始类型、原始字节与已知类型的完整整数投影；decode_state 区分 decoded、unknown_type、malformed_payload，不猜测未知格式。

统计请求：

{"extension_version":1,"stock_market":1}

缺失统计对象保留缺失，不补一组零值。价格、比例、成交量和时间保持公开消息中的整数与可选字段；调用方应按字段契约解释单位。

有市场限制的调用者只能取得已能明确授权的数据。明确市场可在查询前拒绝；历史响应中任何无法授权或无法分类的原始事件会使整页拒绝，不静默删行或重算游标。CN 聚合不等于单独 SH/SZ 权限。协议权限拒绝使用非零 ret_type、本地 err_code=403 且无 s2c；后台业务拒绝仍保留完整 s2c.retcode。CLI/MCP 在失败时保留完整响应。

订阅与停止¶

{"extension_version":1,"stream_id":"market-watch","operation":1,"sub_types":[1],"stock_market":1,"enable_statistics":true,"enable_events":true}

operation 为 Add=1、Remove=2、Clear=3、SetDelivery=4。sub_types 为市场=1、类别=2、自选证券=3、单证券=4，对应 stock_market、category_id、self_selected_stock_ids、single_stock_ids。首次 Add 必须显式给出两个布尔偏好；既有 stream 省略偏好表示保持，false 表示关闭。SetDelivery 只改已有 stream 偏好。Remove 的空目标只清本 stream 所选类别，不清其它调用者。

{"extension_version":1,"stream_id":"market-watch","operation":3}

Clear 仅接受 stream 身份与版本；不能带目标或偏好。响应区分真实确认、待收敛、拒绝、不可用及本地生效，不把引用计数命中当作一次新后台确认。断网/功能关闭时取消仍会撤销本地兴趣，防止重连恢复已取消内容。物理连接关闭释放其订阅；REST 与 gRPC 稳定逻辑 stream 需要显式 Clear。

CLI Add 会保持连接，逐行输出事件、统计或缺口，Ctrl-C 清理本 stream 并关闭连接。每次 CLI 命令是独立物理连接，不能用另一个进程的同名 stream_id 修改其订阅。

MCP 新协议返回私有 futu://tape/… 资源，通过 resources/read 取队列、subscriptions/listen 接收更新提示。旧协议通过 logging notifications 交付，服务结束释放订阅。同名 stream 的现代/旧协议投递模式不能互换；先停止再重新建立。资源读取每次重新验证调用者权限；Clear 释放资源。终止流或资源队列的 dropped_events>0 要求重取历史再重新订阅。复用前端现有 64 条队列、共享 128 个资源许可和 4 小时资源寿命；这些不是后台订阅限制。

REST / gRPC 推送¶

REST /ws 在认证后发送 {"action":"tape-attach","stream_id":"market-watch"} 绑定本调用者逻辑 stream；tape-detach 仅解绑接收，不清 HTTP 订阅。真实消息含 type=tape、stream_id、proto_id 与 body_b64（公开 Update protobuf）。

gRPC SubscribePushRequest.stream_id 显式绑定当前稳定会话的 stream，未填写时沿用原广播接口。订阅请求与接收流应使用同一 Bearer 和 grpc-session-id。接收流关闭只解绑投递，逻辑订阅仍需 Clear。

REST/gRPC attach 的起始控制消息含 gap=true、reason=attachment_started、resynchronize=true，不保证覆盖 attach 前的历史；不伪造丢失数量或 owner 版本。gRPC 该控制消息使用 event_type=gap、proto_id=0 表示没有协议帧。之后的真实 Update 保留真实 owner、stream 实例、版本和缺口计数。队列溢出明确报告缺口，不以最后一条覆盖中间事件冒充完整流。

整数单位¶

价格为千分之一货币单位；价格变化和累计变化字段为千分之一百分点。区间 multiple 为千分之一倍数，diff_price 为百分之一百分点，可选 volume 为最近三分钟股数。其它事件成交量为股数；事件时间、统计更新时间为 Unix 秒。请保留整数精度和可选字段的缺失状态。

公开command诊断只含方向、原始结果码、状态和远端代际，不包含其它调用者的目标或聚合推送偏好；顶层effective targets/preferences只属于当前stream。

旧版 MCP 客户端需允许 Info 级 logging notifications 才能接收流。所有 gap 都要求重新同步；source_changed、delivery_disabled 等诊断中的零计数不证明没有缺失，计数只覆盖已计量的丢弃。