资讯与提醒设置¶
两个读取接口要求 qot:read 与 --enable-desktop-phase2-reads。两个设置接口要求 qot:write，并同时开启 --enable-desktop-phase2-reads --enable-desktop-phase2-writes。两开关默认关闭，开关不会增加API key权限。真实后端行为仍为 UNVERIFIED。
| API / CLI | REST POST |
|---|---|
GetNewsPushSettings / news-push-settings |
/api/news-push-settings |
SetNewsPushSettings / set-news-push-settings |
/api/set-news-push-settings |
GetAlertSystemNotifySetting / alert-system-notify-setting |
/api/alert-system-notify-setting |
SetAlertSystemNotifySetting / set-alert-system-notify-setting |
/api/set-alert-system-notify-setting |
所有请求要求 extension_version: 1，读取不需要其它字段。资讯SET必须完整提供六项：switch、push_freq、personalized_news_switch、notice_switch、news_notification、notice_notification。bool必须显式提供，包括false。push_freq 为0关闭/隐藏、1精选资讯、2重要资讯；两个notification枚举为0未设置、1关闭、2开启。系统通知SET必须提供 system_notify_enable。所有SET还要求非空 intent_key。
futucli news-push-settings --c2s-json '{"extension_version":1}'
futucli set-alert-system-notify-setting --rest-url http://127.0.0.1:33333 --api-key "$FUTU_API_KEY" --c2s-json '{"system_notify_enable":false,"extension_version":1,"intent_key":"notify-off-001"}'
CLI设置通过鉴权REST（--rest-url/--rest-port、--api-key，支持 FUTU_REST_URL、FUTU_API_KEY）。MCP设置工具要求 --opend-rest-url 或 FUTU_MCP_OPEND_REST_URL，按原调用方api_key/HTTP bearer转发，不用共享startup连接身份替代。工具名为API的snake_case前加 futu_，参数为 c2s_json 与可选 api_key。Gateway/gRPC使用同一protobuf合同和写权限检查。
回执与重试¶
SET返回的 s2c.receipt 必含 ack_state、不透明 receipt_id、replayed、readback_status、comparison，以及可选数字 backend_code/readback_code。ACK状态只有 ack_success、ack_rejected、submitted_unknown。ret_type=0 只表示取得回执，不能据此认定设置成功。
成功ACK后做一次读回，原始optional结果放在 s2c.readback。读回失败或不一致不会改写ACK，也不会重新SET。比较为 matched、mismatched、inconclusive；缺字段保持inconclusive。资讯关闭时，已有frequency字段的数值差异不参与比较，其余字段仍要求presence和相等。系统设置容器缺失、空容器与显式false分别保留。关闭系统通知不停止消息接收。
相同 intent_key 与相同设置用于重取原回执，不再次SET；此前ACK成功时可以重新GET，拒绝/unknown重入不SET也不GET。每次新的用户操作使用新key，开→关→开是三个不同意图。旧key配不同内容会拒绝。unknown仍占同一设置目标，不能换key绕过；一次GET值相同不能证明未知写已执行或只执行一次。
若在发送前被拒绝，只释放尚未发送的目标占用，保留不可变意图；send_started或unknown绝不按此方式释放。同用户连接中断保留已知回执；用户、authority或路由owner被替换后不披露旧用户数据。结果不包含后端原始错误文本或凭据。
资讯读取保留optional字段与数字状态：1001可以没有数据，1002或缺少状态为错误。提醒读取保留setting容器和bool两层presence，缺少状态码沿合同接受，不将字段缺失补成已确认的用户偏好。