feat(gateway): 未读面 unreadCount 进 message_persisted 帧（契约 v0.76 ②）
- broadcastPersisted 是 Web 与 IM 两条路的**共用**函数 ⇒ 两处口径天然一致，不存在分叉
- 口径 = 绝对未读 + 主人单一已读游标（chat_sessions.read_at）⇒ 多端共享
- 可选键 omitempty：只在 >0 且确实算得出来时出现；0 与「算不出来」都不顶位
（0 只能从「会话有游标」推出，否则那个 0 就是编的）⇒ 缺席 = 老行为
- Docs/api-client.md：v0.76 ① 按实测改标「未实现且无实现路径」（见下），② 已实现，
并更正「GET /sessions 的 unreadCount 自 D4 起已在」、新增 §4.13 与 §7.4 第 23 条
⚠️ ① toolCalls[] 本版未落地（取证结论，非推断）：chat_messages.turn_id（编排器随机路标识
turn-<16hex>）与 flow_graphs.turn_id（trace.FlowGraph.ID = <session>-<轮次序号>，进程内递增）
不同源，真实库中 66 条消息行 vs 21 条图行字面交集为空 ⇒ 无法 join；按时间窗硬凑属于猜，不做。
补齐路径：链路图带回合标识（新键 + 迁移 0023 起）+ 落盘列，之后 toolCalls[] 是一条批量 SQL。
我亲自复跑的变异：去掉帧里的 n > 0 守卫 ⇒ TestBroadcastPersistedUnreadCountAbsentWhenUnknown
与 TestBroadcastPersistedCarriesUnreadCount 双双 FAIL（断言「0 不该顶位」）⇒ 测试是真护栏。
This commit is contained in:
AskaEth committed
1 parent
cb232e7360
commit
fe4c702f87
6 files changed
+369
-8
No files matched your search
@@ -32,6 +32,11 @@ func (s *Server) BroadcastPersisted(msg history.Message) {
|
||||
// 「这是她主动说的话」的结构化判据 `proactive:true`（切片 P0b，见 proactive.go 的
|
||||
// BroadcastProactivePersisted）。两条入口走**同一个**函数，因此帧类型推导、thinking
|
||||
// 抹除与角色门（design/11 §7.1）逐字一致 —— 差别只有那一个键。
|
||||
//
|
||||
// 帧的 data 另带**可选**的 `unreadCount`（契约 v0.76）：该会话此刻的绝对未读数，
|
||||
// 与 GET /sessions 的 `unreadCount` 同一口径。它只在 >0 且真能算出来时出现（见
|
||||
// unreadCountOf），缺席即老行为。Web 路径与 IM 路径共用本函数 ⇒ 两处口径天然一致，
|
||||
// 不存在「Web 帧带、IM 帧不带」的分叉。
|
||||
func (s *Server) broadcastPersisted(msg history.Message, proactive bool) {
|
||||
wire := toHistoryMessage(msg)
|
||||
wire.Thinking = ""
|
||||
@@ -43,6 +48,13 @@ func (s *Server) broadcastPersisted(msg history.Message, proactive bool) {
|
||||
if proactive {
|
||||
data["proactive"] = true
|
||||
}
|
||||
// 未读数只在**确实算出来、且非零**时进帧（契约 v0.76）。缺席 = 老行为：老客户端
|
||||
// 忽略未知键，新客户端落下这帧时角标已经是对的，不必再拉一次 GET /sessions。
|
||||
// 不用 0 顶位：0 只能从「会话有游标」推出来，而算不出来（未接线/查询失败/
|
||||
// 会话没有游标）时那个 0 就是编的（见 unreadCountOf）。
|
||||
if n, ok := s.unreadCountOf(msg.SessionID); ok && n > 0 {
|
||||
data["unreadCount"] = n
|
||||
}
|
||||
s.hub.broadcast(wsEvent{Type: typ, SessionID: msg.SessionID, Data: data})
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
package gateway
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/history"
|
||||
)
|
||||
|
||||
// 本文件钉住契约 v0.76 的**未读实时面**：`message_persisted` 帧的 data 携带该会话
|
||||
// 此刻的**绝对未读数**（与 GET /api/v1/sessions 的 unreadCount 同一口径、同一条
|
||||
// 读游标）。三条硬约束各有断言：值是对的；只在**确实算得出来且非零**时出现
|
||||
// （缺席 = 老行为）；算不出来时绝不冒出一个 0 去冒充「已读完」。
|
||||
|
||||
// unreadOf 从帧 data 里读未读数并返回 (值, 是否在场)。它刻意先断言「在场性」：
|
||||
// 本面的关键取舍就是「缺席」与「0」是两回事。
|
||||
func unreadOf(t *testing.T, ev wsEvent) (int, bool) {
|
||||
t.Helper()
|
||||
data, ok := ev.Data.(map[string]any)
|
||||
if !ok {
|
||||
t.Fatalf("frame data = %+v, want a JSON object", ev.Data)
|
||||
}
|
||||
raw, present := data["unreadCount"]
|
||||
if !present {
|
||||
return 0, false
|
||||
}
|
||||
n, ok := raw.(float64)
|
||||
if !ok {
|
||||
t.Fatalf("frame data.unreadCount = %v (%T), want a number", raw, raw)
|
||||
}
|
||||
return int(n), true
|
||||
}
|
||||
|
||||
// TestBroadcastPersistedCarriesUnreadCount 覆盖顺路径与两条边界：帧上的数字是
|
||||
// **绝对**未读数（不是「自上次以来」），游标推进之后同一条广播路径不再带该键
|
||||
// （0 不顶位），游标之后的新消息重新点亮并给出刷新后的绝对值。末段顺带钉住
|
||||
// `channel_persisted` 与 `message_persisted` 走**同一个**载荷构造函数，因此隔离
|
||||
// 渠道会话（没有 chat_sessions 行）同样不带该键 —— 它连读游标都没有。
|
||||
func TestBroadcastPersistedCarriesUnreadCount(t *testing.T) {
|
||||
t.Parallel()
|
||||
srv, _, _, st := newHistoryEnv(t)
|
||||
c := newOwnerConn(srv.hub, 32)
|
||||
srv.hub.register(c)
|
||||
ctx := context.Background()
|
||||
|
||||
appendAt := func(at int64, content string) history.Message {
|
||||
t.Helper()
|
||||
full, err := st.AppendFull(ctx, history.Message{
|
||||
SessionID: history.MainSessionID, Role: history.RoleAssistant, Content: content, CreatedAt: at,
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("append %q: %v", content, err)
|
||||
}
|
||||
return full
|
||||
}
|
||||
|
||||
// ① 历史一条（1000）+ 刚落库的一条（2000），游标仍是 0 ⇒ 两条都未读。
|
||||
if err := st.Append(ctx, history.Message{
|
||||
SessionID: history.MainSessionID, Role: history.RoleUser, Content: "old", CreatedAt: 1000,
|
||||
}); err != nil {
|
||||
t.Fatalf("seed old: %v", err)
|
||||
}
|
||||
srv.BroadcastPersisted(appendAt(2000, "new"))
|
||||
ev := readFakeFrame(t, c)
|
||||
if ev.Type != "message_persisted" {
|
||||
t.Fatalf("frame type = %q, want message_persisted", ev.Type)
|
||||
}
|
||||
if got, present := unreadOf(t, ev); !present || got != 2 {
|
||||
t.Fatalf("frame data.unreadCount = %d (present=%v), want 2 (绝对未读，不是本次 +1)", got, present)
|
||||
}
|
||||
|
||||
// ② 游标推进到最新消息 ⇒ 该会话已读：同一条广播路径**不再**带该键。
|
||||
if _, err := st.MarkSessionRead(ctx, history.MainSessionID, time.UnixMilli(2000)); err != nil {
|
||||
t.Fatalf("mark session read: %v", err)
|
||||
}
|
||||
srv.BroadcastPersisted(appendAt(2000, "exactly at the cursor"))
|
||||
if got, present := unreadOf(t, readFakeFrame(t, c)); present {
|
||||
t.Fatalf("frame data.unreadCount = %d，want 该键缺席：未读为 0 时不顶位（缺席 = 老行为，客户端回落 GET /sessions 收敛）", got)
|
||||
}
|
||||
|
||||
// ③ 游标之后的新消息 ⇒ 值是刷新后的绝对值。
|
||||
srv.BroadcastPersisted(appendAt(3000, "after the cursor"))
|
||||
if got, present := unreadOf(t, readFakeFrame(t, c)); !present || got != 1 {
|
||||
t.Fatalf("frame data.unreadCount = %d (present=%v), want 1", got, present)
|
||||
}
|
||||
|
||||
// ④ 隔离渠道会话走同一个构造函数 ⇒ 口径不分叉；它没有游标，因此不带该键。
|
||||
if err := st.Append(ctx, history.Message{
|
||||
SessionID: "sess-g", Role: history.RoleUser, Content: "isolated", CreatedAt: 5000,
|
||||
}); err != nil {
|
||||
t.Fatalf("seed isolated: %v", err)
|
||||
}
|
||||
srv.BroadcastPersisted(history.Message{
|
||||
ID: "m-iso", SessionID: "sess-g", Role: history.RoleUser, Content: "isolated", CreatedAt: 5000,
|
||||
})
|
||||
iso := readFakeFrame(t, c)
|
||||
if iso.Type != "channel_persisted" {
|
||||
t.Fatalf("frame type = %q, want channel_persisted", iso.Type)
|
||||
}
|
||||
if got, present := unreadOf(t, iso); present {
|
||||
t.Fatalf("隔离会话的帧带上了 unreadCount = %d，want 该键缺席（没有会话行就没有读游标）", got)
|
||||
}
|
||||
}
|
||||
|
||||
// TestBroadcastPersistedUnreadCountAbsentWhenUnknown 钉住三条**诚实缺席**路径：
|
||||
// 未注入 HistoryStore、注入的存储没实现单会话未读视图（`sessionUnreadCounter`）、
|
||||
// 以及隔离渠道会话本身。三条都不许冒出 `unreadCount:0` —— 把「算不出来」写成
|
||||
// 「没有未读」就是编数据。
|
||||
func TestBroadcastPersistedUnreadCountAbsentWhenUnknown(t *testing.T) {
|
||||
t.Parallel()
|
||||
pending := history.Message{
|
||||
ID: "row-1", SessionID: history.MainSessionID, Role: history.RoleUser, Content: "hi", CreatedAt: 1000,
|
||||
}
|
||||
|
||||
t.Run("history not wired", func(t *testing.T) {
|
||||
srv, _, _ := buildEnv(t, cfgDefault(), Deps{})
|
||||
c := newOwnerConn(srv.hub, 32)
|
||||
srv.hub.register(c)
|
||||
|
||||
srv.BroadcastPersisted(pending)
|
||||
if got, present := unreadOf(t, readFakeFrame(t, c)); present {
|
||||
t.Fatalf("未接线历史存储的帧带上了 unreadCount = %d，want 缺席", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("store without the unread view", func(t *testing.T) {
|
||||
srv, _, _ := buildEnv(t, cfgDefault(), Deps{History: &fakeHistory{}})
|
||||
c := newOwnerConn(srv.hub, 32)
|
||||
srv.hub.register(c)
|
||||
|
||||
srv.BroadcastPersisted(pending)
|
||||
if got, present := unreadOf(t, readFakeFrame(t, c)); present {
|
||||
t.Fatalf("未实现 sessionUnreadCounter 的存储替身带上了 unreadCount = %d，want 缺席", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("isolated session has no cursor", func(t *testing.T) {
|
||||
srv, _, _, st := newHistoryEnv(t)
|
||||
c := newOwnerConn(srv.hub, 32)
|
||||
srv.hub.register(c)
|
||||
if err := st.Append(context.Background(), history.Message{
|
||||
SessionID: "sess-g", Role: history.RoleUser, Content: "iso", CreatedAt: 1000,
|
||||
}); err != nil {
|
||||
t.Fatalf("seed isolated: %v", err)
|
||||
}
|
||||
|
||||
srv.BroadcastPersisted(history.Message{
|
||||
ID: "m-iso", SessionID: "sess-g", Role: history.RoleUser, Content: "iso", CreatedAt: 1000,
|
||||
})
|
||||
ev := readFakeFrame(t, c)
|
||||
if ev.Type != "channel_persisted" {
|
||||
t.Fatalf("frame type = %q, want channel_persisted", ev.Type)
|
||||
}
|
||||
if got, present := unreadOf(t, ev); present {
|
||||
t.Fatalf("隔离会话的帧带上了 unreadCount = %d，want 缺席", got)
|
||||
}
|
||||
})
|
||||
}
|
||||
@@ -1,6 +1,7 @@
|
||||
package gateway
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"io"
|
||||
@@ -8,6 +9,7 @@ import (
|
||||
"time"
|
||||
|
||||
apperr "git.yeij.top/AskaEth/Cyrene_v2/internal/errors"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/history"
|
||||
)
|
||||
|
||||
@@ -18,6 +20,11 @@ import (
|
||||
// 推导 unreadCount（history.go）。游标是会话级、单所有者的：
|
||||
// 一个账号每个会话一个游标 —— 在任意一端阅读即为所有端标记该
|
||||
// 会话已读。
|
||||
//
|
||||
// 同一条游标还喂养**落库那一刻**的实时面（契约 v0.76）：单会话的绝对未读数
|
||||
// 由 unreadCountOf 读回，随 `message_persisted` 帧的 `data.unreadCount` 下发，
|
||||
// 使客户端不必为换角标再拉一次 GET /sessions。两条面共用同一个数字口径
|
||||
// （`created_at > read_at`），因此不会互相打脸。
|
||||
|
||||
// wsSessionRead 是已读游标推进的 WS 事件类型。
|
||||
const wsSessionRead = "session_read"
|
||||
@@ -92,3 +99,45 @@ func (h *hub) broadcastSessionRead(sessionID string, readAt int64) {
|
||||
Data: map[string]any{"readAt": readAt},
|
||||
})
|
||||
}
|
||||
|
||||
// sessionUnreadCounter 是 HistoryStore 的一个**可选**更窄视图（与 clientMsgIDReader /
|
||||
// turnIDWriter / documentStatusWriter 同一做法）：按会话读回由已读游标推导的绝对未读数。
|
||||
// 未实现该视图的存储替身（测试替身、未接线的构建）**不报错**，只是帧上不带该键 ——
|
||||
// 未读面是增益，绝不能反过来卡住消息广播。
|
||||
type sessionUnreadCounter interface {
|
||||
UnreadCount(ctx context.Context, sessionID string) (int, error)
|
||||
}
|
||||
|
||||
const (
|
||||
// unreadCountTimeout 是**单次**未读数查询的时长上界。它跑在落库之后的广播路径上
|
||||
// （写完一条就发一帧），必须有一个界：一次库卡死绝不允许把广播挂住。
|
||||
unreadCountTimeout = 2 * time.Second
|
||||
|
||||
// unreadCountLogSource 是这条冷路径上日志的来源标签（AGENTS §10 禁无来源裸日志）。
|
||||
unreadCountLogSource = "gateway/broadcast"
|
||||
)
|
||||
|
||||
// unreadCountOf 返回该会话当前的**绝对未读数**（比 chat_sessions.read_at 新的消息数），
|
||||
// 第二个返回值表示「这个数字是真的」—— false 时调用方必须**省略**该键，绝不用 0 冒充
|
||||
// 「已读完」（缺席 = 老行为，客户端回落到 GET /sessions 收敛）。
|
||||
//
|
||||
// 三条不产生数字的情形，都不算错误：① 未注入 HistoryStore；② 注入的存储没实现上面那个
|
||||
// 窄视图；③ 查询失败（记一条带来源的 WARN，因为「读不到」不是「没有未读」）。
|
||||
func (s *Server) unreadCountOf(sessionID string) (int, bool) {
|
||||
if s.history == nil || sessionID == "" {
|
||||
return 0, false
|
||||
}
|
||||
counter, ok := s.history.(sessionUnreadCounter)
|
||||
if !ok {
|
||||
return 0, false
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(context.Background(), unreadCountTimeout)
|
||||
defer cancel()
|
||||
n, err := counter.UnreadCount(ctx, sessionID)
|
||||
if err != nil {
|
||||
logger.WithSource(s.log, unreadCountLogSource).Warn("unread count read failed",
|
||||
"err", err, "session", sessionID)
|
||||
return 0, false
|
||||
}
|
||||
return n, true
|
||||
}
|
||||
Reference in new issue
Block a user