` 在 // 客户端「只要存在完整 `
` 块就不再按空行回退切分」的契约下整条塌成一坨。 // 规整是幂等的写入侧加法（已规范的文本逐字不变），因此 `
` = 一段一气泡、
// ` ` 这些
// 既有语义一条不动。
//
// 落库失败**不静默**：记一条带来源的 WARN，并把错误返回给调用方，同时
// Persisted=false —— 帧照发（实时气泡不能丢），但记录里绝不说「已推送」。
//
// 计数为零意味着没有 owner/admin 客户端在线；消息此时仍会作为一条真实记录
// 留在主会话里（下次打开就能看到），调用方据此回退到 IM bridge 把它**投出去**。
// 只有 owner/admin 连接会被作为目标（红线：主动推送仅 owner）；viewer 或未认证
// 连接绝不被触达。它绝不阻塞：发送缓冲满时对该慢客户端丢弃该帧，
// 而不是卡住后台思考推送。
func (h *hub) SendProactive(ctx context.Context, msg adapter.UnifiedMessage) (backthink.ProactiveDelivery, error) {
if err := ctx.Err(); err != nil {
return backthink.ProactiveDelivery{}, err
}
// 先规整、再落库：msg 是调用方传来的值副本，就地改写只影响本路由；
// 落库与推帧随后取的都是**同一个**字符串，两端因此逐字相同。
msg.Content = turnreply.NormalizeParagraphs(msg.Content)
persisted, persistErr := h.persistProactiveToMain(ctx, msg)
if persistErr != nil {
h.log.Warn("persist proactive message to main session failed",
"err", persistErr, "platform", msg.Platform)
}
b, err := json.Marshal(wsEvent{Type: wsProactiveMessage, Data: proactivePayloadFrom(msg, persisted)})
if err != nil {
return backthink.ProactiveDelivery{Persisted: persisted.ID != ""},
fmt.Errorf("gateway: marshal proactive: %w", err)
}
h.mu.RLock()
defer h.mu.RUnlock()
n := 0
for c := range h.conns {
if !ownerAdminClaims(c.claims) {
continue
}
select {
case c.send <- b:
n++
default:
}
}
return backthink.ProactiveDelivery{Connections: n, Persisted: persisted.ID != ""}, persistErr
}
// Server.SendProactive 通过委托给 hub 满足后台思考的 ActiveClient
// 接缝，因此组合根能把网关自身交给汇聚点设置器。
func (s *Server) SendProactive(ctx context.Context, msg adapter.UnifiedMessage) (backthink.ProactiveDelivery, error) {
return s.hub.SendProactive(ctx, msg)
}
// BroadcastProactivePersisted 把一条**刚落进主会话的主动消息**广播为**带结构化判据**的
// `message_persisted` 帧（切片 P0b）。判据就是帧的 `data` 里的 `proactive:true`：它是「她主动说的
// 话」在线上唯一的标记，客户端据此走与 `proactive_message` **同一套**提醒逻辑（非前台才
// 补一发通知，同一条只提醒一次），于是「她该不该提醒我」**与后端走了哪条路由无关**
// （主人 2026-10-05 裁定 C）。
//
// 它由 IM 桥的主动推送在**落库之后**调用（组合根接线 SetOnProactivePersisted）。为什么
// 需要它：IM 路由过去只发普通 `message_persisted`，而浏览器通知挂在 `proactive_message`
// 上 ⇒ 走 IM 的主动消息一条都不弹；偏偏 `auto` 提示在主人有已连接 IM 渠道时优先走 IM
// ⇒ 实际最可能发生的路径恰恰不弹。
//
// 判据为什么不会误伤普通消息：只有主动推送这条通道会调用本函数，普通消息（Web 回合 /
// IM 回复 / IM 镜像）走的仍是 BroadcastPersisted，那条路径**永不**往帧的 `data` 里放该键。
// 帧类型仍是 `message_persisted`，因此角色门（design/11 §7.1）与普通持久化帧逐字相同。
func (s *Server) BroadcastProactivePersisted(msg history.Message) {
s.broadcastPersisted(msg, true)
}
// proactivePayloadFrom 把 UnifiedMessage 投影为消毒后的线上载荷。
// persisted 是刚落库的主会话消息（未接线历史存储或落库失败时为零值），
// 它的 id/时间戳随之进入载荷，使客户端能把实时气泡对齐到历史行。
func proactivePayloadFrom(msg adapter.UnifiedMessage, persisted history.Message) proactivePayload {
return proactivePayload{
Platform: msg.Platform,
ChannelID: msg.ChannelID,
ChannelType: string(msg.ChannelType),
Content: msg.Content,
ContentType: string(msg.ContentType),
Sender: msg.Sender.DisplayName,
Timestamp: msg.Timestamp,
MessageID: msg.MessageID,
ID: persisted.ID,
CreatedAt: persisted.CreatedAt,
}
}
// ownerAdminClaims 报告 claims 是否授权一次主动推送（owner 或
// admin）。nil claims（未认证 / 裸测试连接）绝不被作为目标。
func ownerAdminClaims(claims *auth.Claims) bool {
if claims == nil {
return false
}
return claims.Role == auth.RoleOwner || claims.Role == auth.RoleAdmin
}
` = 气泡内分隔、`