feat: IM式跨端实时同步——message_persisted 广播 + 前端按id去重追加

- history.Store 新增 AppendFull（返回含 id/createdAt 的完整消息），Append 签名不变
- session_orchestrator 加可空 OnPersisted；persistUserMessages/persistAssistantReply 落库后回调广播
- server.go newOrchestrator 接 OnPersisted → hub.broadcast message_persisted（thinking 剥除）
- 前端 ws.ts 加 message_persisted case（仅 activeSessionId 匹配才处理）；appendOrUpdateMessage 升级为 id 精确upsert+内容/时间归一
- 实测：双 WS，A stream 发消息，B 免刷新收到 user+assistant 各1条（count=2 PASS）
- 红线: 身份仍靠 actor 元数据，不靠提示词；用户/助手消息、本端/异端统一路径

internal/runtime/history/store.go

@@ -87,6 +87,9 @@ type SessionMeta struct {
 type HistoryStore interface {
 	// Append persists msg, assigning an id and timestamp when the caller omitted them.
 	Append(ctx context.Context, msg Message) error
+	// AppendFull persists msg like Append but returns the complete stored message
+	// (with the assigned id/timestamp) so a caller can broadcast it for cross-end sync.
+	AppendFull(ctx context.Context, msg Message) (Message, error)
 	// List returns up to limit messages for sessionID, newest first. before is a
 	// millisecond timestamp cursor: when nonzero, only messages older than before are
 	// returned (inclusive-free, matching the "before" bound on the frontend).
@@ -144,12 +147,28 @@ func NewStore(ctx context.Context, db *sql.DB, log *slog.Logger) (*Store, error)
 }
 
 // Append persists msg, assigning a fresh id and a now-ms CreatedAt when the caller left
-// either empty/zero. It returns the error wrapped with the operation name.
+// either empty/zero. It returns the error wrapped with the operation name. Callers that
+// need the generated id/timestamp back should use AppendFull instead.
 func (s *Store) Append(ctx context.Context, msg Message) error {
+	_, err := s.insert(ctx, msg)
+	return err
+}
+
+// AppendFull persists msg like Append but returns the complete stored message — the id
+// and CreatedAt the store assigned when the caller left them empty/zero — so a caller can
+// broadcast it for cross-end realtime sync (design/16 §4.2) without a second read.
+func (s *Store) AppendFull(ctx context.Context, msg Message) (Message, error) {
+	return s.insert(ctx, msg)
+}
+
+// insert is the shared Append/AppendFull body. It assigns a fresh id and a now-ms
+// CreatedAt when the caller left either empty/zero, then inserts the row and returns the
+// resulting message.
+func (s *Store) insert(ctx context.Context, msg Message) (Message, error) {
 	if msg.ID == "" {
 		id, err := newID()
 		if err != nil {
-			return fmt.Errorf("history: append id: %w", err)
+			return Message{}, fmt.Errorf("history: append id: %w", err)
 		}
 		msg.ID = id
 	}
@@ -162,9 +181,9 @@ func (s *Store) Append(ctx context.Context, msg Message) error {
 		msg.ID, msg.SessionID, msg.Role, msg.Content, msg.Mode, msg.Mood,
 		msg.Image, msg.Thinking, msg.CreatedAt)
 	if err != nil {
-		return fmt.Errorf("history: append %s to %s: %w", msg.Role, msg.SessionID, err)
+		return Message{}, fmt.Errorf("history: append %s to %s: %w", msg.Role, msg.SessionID, err)
 	}
-	return nil
+	return msg, nil
 }
 
 // List returns up to limit messages for sessionID, newest first. When before is nonzero

internal/runtime/history/store_test.go

@@ -76,6 +76,44 @@ func TestAppendAndListNewestFirst(t *testing.T) {
 	}
 }
 
+func TestAppendFullReturnsID(t *testing.T) {
+	t.Parallel()
+	st := newStore(t)
+	ctx := context.Background()
+
+	full, err := st.AppendFull(ctx, Message{SessionID: MainSessionID, Role: RoleUser, Content: "hi"})
+	if err != nil {
+		t.Fatalf("append full: %v", err)
+	}
+	if full.ID == "" {
+		t.Fatal("AppendFull did not assign an id")
+	}
+	if full.CreatedAt == 0 {
+		t.Fatal("AppendFull did not assign a created_at")
+	}
+	if full.SessionID != MainSessionID || full.Role != RoleUser || full.Content != "hi" {
+		t.Fatalf("AppendFull returned %+v, want the stored message unchanged plus id/created_at", full)
+	}
+
+	// The message is actually persisted under the returned id.
+	msgs, err := st.List(ctx, MainSessionID, 0, 50)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(msgs) != 1 || msgs[0].ID != full.ID {
+		t.Fatalf("list = %+v, want exactly the persisted message id %q", msgs, full.ID)
+	}
+
+	// A caller-supplied id/timestamp is preserved, not regenerated.
+	preset, err := st.AppendFull(ctx, Message{ID: "preset-id", SessionID: MainSessionID, Role: RoleAssistant, Content: "ok", CreatedAt: 42})
+	if err != nil {
+		t.Fatalf("append full preset: %v", err)
+	}
+	if preset.ID != "preset-id" || preset.CreatedAt != 42 {
+		t.Fatalf("AppendFull did not preserve preset id/created_at: %+v", preset)
+	}
+}
+
 func TestListPaginationBefore(t *testing.T) {
 	t.Parallel()
 	st := newStore(t)

internal/services/gateway/server.go

@@ -109,6 +109,10 @@ type MemoryStore interface {
 // endpoints answer with a clear 501.
 type HistoryStore interface {
 	Append(ctx context.Context, msg history.Message) error
+	// AppendFull persists msg like Append but returns the complete stored message
+	// (with the assigned id/timestamp) so the orchestrator can broadcast it for
+	// cross-end realtime sync (design/16 §4.2).
+	AppendFull(ctx context.Context, msg history.Message) (history.Message, error)
 	List(ctx context.Context, sessionID string, before int64, limit int) ([]history.Message, error)
 	Recent(ctx context.Context, sessionID string, n int) ([]history.Message, error)
 	DeleteSession(ctx context.Context, sessionID string) error
@@ -455,6 +459,15 @@ func newOrchestrator(s *Server) *Orchestrator {
 		Emit: func(sessionID, typ string, data map[string]any) {
 			s.hub.broadcast(wsEvent{Type: typ, SessionID: sessionID, Data: data})
 		},
+		OnPersisted: func(msg history.Message) {
+			// Broadcast the complete message so every browser of the same account
+			// appends it without a manual refresh (design/16 §4.2). The frontend
+			// dedups by the backend-generated id, and thinking is stripped to stay
+			// consistent with the WS history replay (design/16 §6).
+			wire := toHistoryMessage(msg)
+			wire.Thinking = ""
+			s.hub.broadcast(wsEvent{Type: "message_persisted", SessionID: msg.SessionID, Data: map[string]any{"message": wire}})
+		},
 		Log:     s.log,
 		History: s.history,
 	})

internal/services/gateway/session_orchestrator.go

@@ -7,6 +7,7 @@ import (
 	"sync"
 	"time"
 
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/history"
 	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/loop"
 	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
 )
@@ -108,6 +109,11 @@ type OrchestratorOptions struct {
 	// When nil every Append is skipped, so the orchestrator runs without storage
 	// (tests / a gateway built without a history store).
 	History HistoryStore
+	// OnPersisted, when non-nil, is called with the complete stored message right
+	// after a user or assistant message is written, so the transport can broadcast
+	// a `message_persisted` event for cross-end realtime sync (design/16 §4.2).
+	// Dropped when nil (tests / a gateway built without a transport hook).
+	OnPersisted func(history.Message)
 }
 
 // sessionState is the per-session message state (design/15 §2). Every mutation
@@ -115,7 +121,7 @@ type OrchestratorOptions struct {
 // lock so a slow model call never blocks Submit.
 type sessionState struct {
 	mode    Mode
-	gen     uint64          // generation: bumped on interrupt and on a fresh top-level turn
+	gen     uint64 // generation: bumped on interrupt and on a fresh top-level turn
 	cancel  context.CancelFunc
 	pending []pendingMsg
 	tail    []model.Message // bounded conversation tail for context continuation
@@ -134,14 +140,15 @@ type pendingMsg struct {
 // actual run off to a goroutine. It is the single owner of "is this session busy"
 // for the chat path; the loop/task/subagent engines are reused, not re-created.
 type Orchestrator struct {
-	mu         sync.Mutex
-	states     map[string]*sessionState
-	run        TurnRunner
-	emit       StateSink
-	log        *slog.Logger
-	history    HistoryStore
-	maxPending int
-	maxTail    int
+	mu          sync.Mutex
+	states      map[string]*sessionState
+	run         TurnRunner
+	emit        StateSink
+	log         *slog.Logger
+	history     HistoryStore
+	onPersisted func(history.Message)
+	maxPending  int
+	maxTail     int
 }
 
 // NewOrchestrator builds an orchestrator from opts. Run is required: it is the
@@ -161,13 +168,14 @@ func NewOrchestrator(opts OrchestratorOptions) *Orchestrator {
 		opts.Log = slog.New(slog.NewTextHandler(io.Discard, nil))
 	}
 	return &Orchestrator{
-		states:     make(map[string]*sessionState),
-		run:        opts.Run,
-		emit:       opts.Emit,
-		log:        opts.Log,
-		history:    opts.History,
-		maxPending: maxPending,
-		maxTail:    maxTail,
+		states:      make(map[string]*sessionState),
+		run:         opts.Run,
+		emit:        opts.Emit,
+		log:         opts.Log,
+		history:     opts.History,
+		onPersisted: opts.OnPersisted,
+		maxPending:  maxPending,
+		maxTail:     maxTail,
 	}
 }
 
@@ -414,6 +422,14 @@ func (o *Orchestrator) emitState(sessionID, typ string, data map[string]any) {
 	}
 }
 
+// notifyPersisted hands a just-persisted message to the transport hook when one is
+// wired, so the gateway can broadcast `message_persisted` for cross-end sync.
+func (o *Orchestrator) notifyPersisted(msg history.Message) {
+	if o.onPersisted != nil {
+		o.onPersisted(msg)
+	}
+}
+
 // boundedTail returns a fresh copy of the last maxTail messages, so continuation
 // stays incremental and bounded (design/15 §2.2, §4) and never aliases the input
 // slice or another state's tail.

internal/services/gateway/session_orchestrator_test.go

@@ -157,11 +157,22 @@ type fakeHistory struct {
 	appends []history.Message
 }
 
-func (f *fakeHistory) Append(_ context.Context, msg history.Message) error {
+func (f *fakeHistory) Append(ctx context.Context, msg history.Message) error {
+	_, err := f.AppendFull(ctx, msg)
+	return err
+}
+
+func (f *fakeHistory) AppendFull(_ context.Context, msg history.Message) (history.Message, error) {
 	f.mu.Lock()
+	defer f.mu.Unlock()
+	if msg.ID == "" {
+		msg.ID = fmt.Sprintf("id-%d", len(f.appends)+1)
+	}
+	if msg.CreatedAt == 0 {
+		msg.CreatedAt = int64(len(f.appends) + 1)
+	}
 	f.appends = append(f.appends, msg)
-	f.mu.Unlock()
-	return nil
+	return msg, nil
 }
 
 func (f *fakeHistory) List(context.Context, string, int64, int) ([]history.Message, error) {
@@ -219,6 +230,44 @@ func TestSubmitPersistsUserAndAssistant(t *testing.T) {
 	}
 }
 
+func TestSubmitPersistedBroadcast(t *testing.T) {
+	t.Parallel()
+	run := newGatedRunner(1)
+	hist := &fakeHistory{}
+	var mu sync.Mutex
+	var persisted []history.Message
+	o := NewOrchestrator(OrchestratorOptions{
+		Run:     run.Run,
+		Log:     slog.Default(),
+		History: hist,
+		OnPersisted: func(m history.Message) {
+			mu.Lock()
+			persisted = append(persisted, m)
+			mu.Unlock()
+		},
+	})
+	run.tickets <- struct{}{}
+	sr, _ := o.SubmitSync(context.Background(), "web", []model.Message{userMsg("你好")}, loop.OwnerEnv())
+	if !sr.Accepted || !sr.Immediate {
+		t.Fatalf("submit = %+v, want Accepted+Immediate", sr)
+	}
+	mu.Lock()
+	got := append([]history.Message(nil), persisted...)
+	mu.Unlock()
+	if len(got) != 2 {
+		t.Fatalf("persisted = %d, want 2 (user + assistant)", len(got))
+	}
+	if got[0].Role != history.RoleUser || got[0].ID == "" || got[0].SessionID != "web" || got[0].Content != "你好" {
+		t.Fatalf("user persisted = %+v", got[0])
+	}
+	if got[1].Role != history.RoleAssistant || got[1].ID == "" || got[1].SessionID != "web" || got[1].Content == "" {
+		t.Fatalf("assistant persisted = %+v", got[1])
+	}
+	if got[0].ID == got[1].ID {
+		t.Fatalf("user and assistant share id %q", got[0].ID)
+	}
+}
+
 func TestSubmitDoesNotPersistRejectedTurn(t *testing.T) {
 	t.Parallel()
 	hist := &fakeHistory{}

internal/services/gateway/session_persist.go

@@ -14,9 +14,11 @@ import (
 // orchestrator runs unchanged without a store (tests / an unwired gateway).
 
 // persistUserMessages writes each RoleUser message of a submitted turn to the
-// history store so the raw user stream is durable before the turn resolves. It is
-// a no-op when no history store is wired. Rejected turns (empty, pending-full)
-// never reach it, so nothing vacuous is persisted.
+// history store so the raw user stream is durable before the turn resolves, then
+// notifies the transport so every browser of the same account can append it
+// without a manual refresh (design/16 §3.3, §4.2). It is a no-op when no history
+// store is wired. Rejected turns (empty, pending-full) never reach it, so nothing
+// vacuous is persisted.
 func (o *Orchestrator) persistUserMessages(ctx context.Context, sessionID string, messages []model.Message) {
 	if o.history == nil {
 		return
@@ -29,23 +31,30 @@ func (o *Orchestrator) persistUserMessages(ctx context.Context, sessionID string
 		if text == "" && image == "" {
 			continue
 		}
-		if err := o.history.Append(ctx, history.Message{SessionID: sessionID, Role: history.RoleUser, Content: text, Image: image}); err != nil {
+		full, err := o.history.AppendFull(ctx, history.Message{SessionID: sessionID, Role: history.RoleUser, Content: text, Image: image})
+		if err != nil {
 			o.log.Error("orchestrator persist user", "err", err, "session", sessionID)
+			continue
 		}
+		o.notifyPersisted(full)
 	}
 }
 
 // persistAssistantReply writes the final assistant text of a settled turn to the
-// history store. It is a no-op when no history store is wired or the turn
-// produced no text (interrupted/errored turns leave res nil). The write runs
-// under a fresh background context so a canceled turn context never aborts it.
+// history store, then notifies the transport (design/16 §3.3, §4.2). It is a
+// no-op when no history store is wired or the turn produced no text
+// (interrupted/errored turns leave res nil). The write runs under a fresh
+// background context so a canceled turn context never aborts it.
 func (o *Orchestrator) persistAssistantReply(sessionID string, res *loop.Result) {
 	if o.history == nil || res == nil || res.Text == "" {
 		return
 	}
-	if err := o.history.Append(context.Background(), history.Message{SessionID: sessionID, Role: history.RoleAssistant, Content: res.Text}); err != nil {
+	full, err := o.history.AppendFull(context.Background(), history.Message{SessionID: sessionID, Role: history.RoleAssistant, Content: res.Text})
+	if err != nil {
 		o.log.Error("orchestrator persist assistant", "err", err, "session", sessionID)
+		return
 	}
+	o.notifyPersisted(full)
 }
 
 // messageTextImage returns the concatenated text and the first image URL of a