From 00f784b55f76ab052571ebac5f07a42ca5c41b30 Mon Sep 17 00:00:00 2001
From: AskaEth <i@yeij.top>
Date: Tue, 8 Sep 2026 21:18:53 +0800
Subject: [PATCH] =?UTF-8?q?docs(api-client):=20=E8=A1=A5=20proactive=5Fmes?=
 =?UTF-8?q?sage=20=E4=B8=BB=E5=8A=A8=E6=8E=A8=E9=80=81=E4=BA=8B=E4=BB=B6(B?=
 =?UTF-8?q?6)=20=E2=80=94=20=C2=A73.6=20=E8=A7=A6=E5=8F=91/=E8=BD=BD?=
 =?UTF-8?q?=E8=8D=B7/=E4=B8=8Emessage=5Fpersisted=E5=8C=BA=E5=88=AB/owner-?=
 =?UTF-8?q?only+=E8=84=B1=E6=95=8F=E7=BA=A2=E7=BA=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Docs/api-client.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Docs/api-client.md b/Docs/api-client.md
index ae92fa9..1d46e4d 100644
--- a/Docs/api-client.md
+++ b/Docs/api-client.md
@@ -173,6 +173,12 @@
   - `log` 为该节点累积的 span 事件 `[{time,type,props?}]`（设计 §2「节点实时日志」）。
 - **客户端处理**：`graph_update` → `setFlowGraph(parseGraph(data))`（`src/lib/wsParse.ts`），管理面板「全链路流程」页渲染 `FlowGraphView`，节点可点开看参数/结果/实时日志；无图时诚实显示「暂无流程」。
 
+### 3.6 主动推送事件（`proactive_message`，design/12）
+- **触发**：后台思考（backthink）自主决定「此刻主动发一条」时，经 `SendProactive` 投递给**当前所有在线 owner/admin 连接**（viewer / 未登录连接**永不**投递）。`SendProactive` 返回实际送达的连接数——**0 时调用方回退 IM 桥**（`im_bridge`），把该消息经渠道主动推送发给你（KOOK/微信等已接）。
+- **载荷**：`{type:"proactive_message", data:{platform?, channelId?, channelType?, content, contentType?, sender?, timestamp?, messageId?}}`（由 `adapter.UnifiedMessage` 脱敏投影：**不含 RawData / 媒体字节 / token**，绝不让凭据漏到前端）。
+- **客户端处理**：仅 owner/admin 收到；渲染成一条「她从某平台主动发来」的气泡（内容 + platform + sender + timestamp）。**与 `message_persisted` 的区别**：`message_persisted` 是你与她的对话回显；`proactive_message` 是**她未经你输入**主动推的消息（如 IoT 完成事件、后台思考结论），两路不同、不要混用去重。
+- **红线**：owner-only；payload 已脱敏；backthink 每次主动推送**只发一个决策平台**（决策渠道→最近活跃→旋转回退），Web 端与 IM 桥为两条投递路，客户端不要据此断言「所有平台都发了」。
+
 ## 4. 客户端接入指引（Web / 移动 / 原生 / IM bridge 通用）
 
 ### 4.1 一次性接入流程（三步走）