通用与组合提醒¶

读取需要网关启动参数 --enable-desktop-phase2-reads；设置还需 --enable-desktop-phase2-writes。默认均关闭，不增加 API Key 的权限。真实后端行为尚未验证。

操作	REST POST	MCP	CLI	scope
旧格式配置	`/api/common-reminder-settings`	`futu_get_common_reminder_settings`	`common-reminder-settings`	`qot:read`
新格式条目	`/api/common-reminder-items`	`futu_get_common_reminder_items`	`common-reminder-items`	`qot:read`
业务说明	`/api/common-reminder-business-info`	`futu_get_common_reminder_business_info`	`common-reminder-business-info`	`qot:read`
显式设置	`/api/set-common-reminders`	`futu_set_common_reminders`	`set-common-reminders`	`qot:write`

Gateway、REST、MCP、CLI及通用gRPC使用相同公开消息。extension_version 必须显式为 1。CLI/MCP使用 --c2s-json / c2s_json；设置通过配置的REST地址转发实际调用者的API Key。

读取¶

旧格式查询：

{"extension_version":1}

可选 stock_id、market、type、count、from；保留字段缺失和原始有符号分页值，不把缺失 has_more 当作已完成全量。旧格式的 stock_id 也可能是业务标识，不应一律理解为证券。

新格式查询：

{"extension_version":1,"count":0,"next_id":0}

count 和 next_id 必须显式填写，count=0 表示全量。可选 pri_id、sub_id、market、types。next_id 原样续传，不当作数组offset；sub_id 缺失与空字符串不同。原始类型、开关状态、更新时间和分页字段完整保留。

条目中的业务说明独立呈现为 enrichment：not_requested、available、rejected 或 unavailable。补充读取失败不会丢失已取得的条目。单独查询业务说明时，items 每项要求 pri_id 和有符号 type，sub_id 可省略。响应的 correspondence 保留原输入与实际编码、匹配下标及歧义标志，不因编码规则把两个提醒身份合并。

读请求被后端拒绝时，ret_type 非零，原始业务码仍保留在 s2c，不会把大无符号代码缩成负数。CLI打印完整响应后以失败状态退出；MCP返回带完整JSON的错误。传输、解析或身份失效与业务拒绝不同。

设置¶

旧、新格式互斥，不能同时填写有效的 legacy 和非空 items。每次设置都要求非空 intent_key。

{"extension_version":1,"intent_key":"REPLACE_WITH_NEW_INTENT_KEY","legacy":{"stock_id":0,"operation":2,"settings":[{"type":3,"is_open":1}]}}

⚠️ stock_id=0 为占位，请使用已查询或有真实业务来源的标识。旧格式 is_open 是无符号64位原始值，常用 0 关闭、1 开启；不要改成JSON布尔。

{"extension_version":1,"intent_key":"REPLACE_WITH_NEW_INTENT_KEY","items":[{"type":7,"is_open":false,"pri_id":"REPLACE_FROM_CURRENT_USER_QUERY","sub_id":"","operation":2}]}

⚠️ 新格式的 pri_id 与 sub_id 必须来自真实业务身份或当前用户读取结果。is_open 要求JSON布尔，显式 false 不会被当作省略。operation=1 删除、2 更新；创建也使用更新。

支持已证创建入口的财务解读、组合、IPO首日、分析总评提醒。财务解读创建需当前高级权限；分析总评按实际标的资格检查。其他类型不因枚举存在就承诺创建支持；已存在条目按已证明的身份和操作合同处理。组合ID可能与股票ID同号，身份类型不能互换；原始响应含缺失身份或无法安全转换的类型时，不会猜目标。

结果以 s2c.receipt.ack_state 为准：ack_success、ack_rejected、submitted_unknown。全局拒绝不是逐项回滚证明，也不会臆造部分成功。读回结果独立；读回一致不能解除unknown。同intent重入不重发，改变同key的请求会冲突；unknown只占用重叠目标。

变更推送¶

Qot_UpdateCommonReminders 为通知，不是可调用请求。TCP客户端按 recvNotify 接收；REST WebSocket使用现有broadcast事件及 body_b64，gRPC使用notify及二进制body。解码使用对应公开proto。

推送携带owner epoch、revision以及scope的失效/刷新结果。它与价格提醒的序号无关。仅当前活动查询参与后台刷新；后续页替换当前兴趣，断连或用户切换会清理兴趣。读取关闭时仍记录失效，但不主动查询；失败不会无限重试。