平台公告¶
这两个用户环境公告读取接口要求 qot:read、extension_version: 1 和 --enable-desktop-phase2-reads（默认关闭）。真实后端可用性仍为 UNVERIFIED。
| API / CLI | REST POST | 额外请求字段 |
|---|---|---|
GetPlatformAnnouncements / platform-announcements |
/api/platform-announcements |
可选 page_params 数组，省略/空表示全量查询 |
GetPlatformAnnouncementsByIds / platform-announcements-by-ids |
/api/platform-announcements-by-ids |
非空 signed integer 数组 notice_ids |
MCP工具为 futu_get_platform_announcements、futu_get_platform_announcements_by_ids，请求放入 c2s_json 字符串，可选 api_key。Gateway和gRPC使用同一typed请求。
futucli platform-announcements --c2s-json '{"extension_version":1}'
futucli platform-announcements-by-ids --c2s-json '{"extension_version":1,"notice_ids":[7]}'
请求与结果¶
每个page保留可选 page_id、params_type、params bytes（JSON字节数组）。类型0编码StockDetailPageParams（stock_id、market_id、market_type）；类型1编码PageParamList（stock_id_list、market_id_list、market_type_list）。指定page属于已绑定协议扩展；普通全量查询不带page筛选。不得把内部命令号或无关消息填入这些bytes。语言、客户端身份及主推券商取当前连接环境，调用方不覆盖用户或券商身份。
结果包含可选 backend_code、backend_message、原始 notices 以及本地 owner_epoch/revision。Notice保留全部可选字段：notice_id、start_time、end_time、pages、title、details、link、style、details_link_keyword、details_link、update_time、sort、details_html、popup_type、popup_auto、start_time_int64、end_time_int64、update_time_int64。时间为Unix秒，旧32位与新64位字段分开保留。关联page保留page ID、filter type/content bytes；未知筛选条件不能解释成全局适用。
文本、HTML和链接都作为数据返回，网关不执行HTML、不打开URL、不补造缺失内容。展示端应使用安全文本或受控富文本渲染器，不直接把返回HTML赋给不可信页面。CLI JSON输出转义控制字符。API返回原始时间窗，不模拟弹窗、用户关闭或展示节流状态。
公告快照推送¶
UpdatePlatformAnnouncement 携带当前完整缓存快照：notices、本地 owner_epoch、revision。应替换同owner的旧快照，不能作为增量追加。计数器是本地生命周期/顺序标识，不是后端消息ID，也不能跨进程比较。Gateway沿已有通知接收开关；REST WebSocket使用 subscribe-notify 并要求 qot:read；gRPC沿现有通知流。
缓存记录已观察到的公告，增量读取后不宣称包含后端全量。非空全量响应退休缺失ID，但成功空全量沿源行为保留缓存；原始读取结果仍返回该空列表。指定pages/IDs不会退休无关记录。更高 sort 整体替换；相同 sort 仅在HTML变化时更新文本和链接。下线事件立即删除，旧owner或旧revision的在途结果与排队快照不能恢复它。
上线事件把ID标记为待刷新。刷新失败保留ID并停止自动尝试，下次上线事件或显式查询可重试；不启动定时轮询或无限重试。通知允许合并中间状态，断连或流丢失后应显式全量读取恢复；原始查询结果与缓存替换快照的完整性语义不同。用户/会话、连接、语言或主推券商变化使旧owner失效。传输、状态、解码或owner过期错误都返回失败，不补造空成功。