feat(history): 消息搜索/编辑/删除 + 会话置顶(D2/D3/D5)

- history/message_ops.go(新): Search(会话内, q/after互斥, LIKE参数化+%/_转义+大小写不敏感, 严格限定会话doc) / UpdateMessage(返回更新后Message) / DeleteMessage / messageByID / escapeLike
- history/session_pin.go(新): SetPinned; 迁移0009 chat_sessions加pinned INTEGER DEFAULT 0; store.go SessionMeta.Pinned + createSessionsTable加列
- session_preview.go: 查询加s.pinned + ORDER BY pinned DESC,(type=main) DESC,created_at ASC
- gateway history_write.go(新,保持history.go≤500): handlePatchSession(pinned+title) / handlePatchMessage / handleDeleteMessage; server.go加PATCH/DELETE /api/v1/messages/{id} + /sessions/{id}置顶
- history.go: handleListMessages读q分流Search; 契约PATCH title/置顶
- D2会话内搜索(不做跨会话,隔离会话不外泄红线); D3不做重发端点(客户端编辑后再发); D5用pinned bool
- 测试(message_ops/history_messages/migrate_pinned), build/vet/test绿+3平台交叉编译; Docs/api-client v0.30
- 未做: 编辑/删除WS实时广播(message_edited/deleted), 下批

internal/runtime/history/message_ops.go

@@ -0,0 +1,113 @@
+package history
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// This file owns the single-message operations behind the Android collaboration batch
+// ③a (D2 search, D3 edit/delete). Both are strictly session-scoped or id-scoped: a
+// message is only ever reached through the session it belongs to (Search) or its own
+// opaque id (UpdateMessage/DeleteMessage), so an isolated group/stranger session can
+// never surface in another session's results (project red line).
+
+// Search returns up to limit messages for sessionID whose content contains query,
+// newest first. The match is a case-insensitive ASCII LIKE (SQLite's default for
+// LIKE) with the query's %/_/\ escaped so they match literally; before is the same
+// millisecond cursor as List (strictly older than before) and limit is clamped to
+// [1, maxPageLimit]. rowid breaks created_at ties so same-millisecond messages keep a
+// stable order. An empty query returns an empty (non-nil) slice — the caller uses
+// List for plain paging instead. Search never crosses the session boundary.
+func (s *Store) Search(ctx context.Context, sessionID, query string, before int64, limit int) ([]Message, error) {
+	limit = clampLimit(limit)
+	if query == "" {
+		return make([]Message, 0), nil
+	}
+	sqlText := `SELECT id, session_id, role, content, mode, mood, image, thinking, platform, device_id, sender_name, adapter_id, created_at
+		FROM chat_messages WHERE session_id = ? AND content LIKE ? ESCAPE '\'`
+	args := []any{sessionID, "%" + escapeLike(query) + "%"}
+	if before > 0 {
+		sqlText += ` AND created_at < ?`
+		args = append(args, before)
+	}
+	sqlText += ` ORDER BY created_at DESC, rowid DESC LIMIT ?`
+	args = append(args, limit)
+
+	rows, err := s.db.QueryContext(ctx, sqlText, args...)
+	if err != nil {
+		return nil, fmt.Errorf("history: search %s: %w", sessionID, err)
+	}
+	defer func() { _ = rows.Close() }()
+
+	msgs := make([]Message, 0)
+	for rows.Next() {
+		m, err := scanMessage(rows)
+		if err != nil {
+			return nil, fmt.Errorf("history: scan search %s: %w", sessionID, err)
+		}
+		msgs = append(msgs, m)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("history: iterate search %s: %w", sessionID, err)
+	}
+	return msgs, nil
+}
+
+// UpdateMessage replaces the content of the message with id and returns the updated
+// message (like AppendFull, so the caller can return/broadcast it without a second
+// read). Only content changes; role, platform, timestamps and the rest stay as stored.
+// An unknown id returns ErrMessageNotFound.
+func (s *Store) UpdateMessage(ctx context.Context, id, content string) (Message, error) {
+	res, err := s.db.ExecContext(ctx, `UPDATE chat_messages SET content = ? WHERE id = ?`, content, id)
+	if err != nil {
+		return Message{}, fmt.Errorf("history: update message %s: %w", id, err)
+	}
+	n, err := res.RowsAffected()
+	if err != nil {
+		return Message{}, fmt.Errorf("history: update message %s rows: %w", id, err)
+	}
+	if n == 0 {
+		return Message{}, fmt.Errorf("history: update message %s: %w", id, ErrMessageNotFound)
+	}
+	return s.messageByID(ctx, id)
+}
+
+// DeleteMessage removes a single message. An unknown id returns ErrMessageNotFound.
+func (s *Store) DeleteMessage(ctx context.Context, id string) error {
+	res, err := s.db.ExecContext(ctx, `DELETE FROM chat_messages WHERE id = ?`, id)
+	if err != nil {
+		return fmt.Errorf("history: delete message %s: %w", id, err)
+	}
+	n, err := res.RowsAffected()
+	if err != nil {
+		return fmt.Errorf("history: delete message %s rows: %w", id, err)
+	}
+	if n == 0 {
+		return fmt.Errorf("history: delete message %s: %w", id, ErrMessageNotFound)
+	}
+	return nil
+}
+
+// messageByID reads one message by id, returning ErrMessageNotFound when the row is
+// absent.
+func (s *Store) messageByID(ctx context.Context, id string) (Message, error) {
+	row := s.db.QueryRowContext(ctx, `SELECT id, session_id, role, content, mode, mood, image, thinking, platform, device_id, sender_name, adapter_id, created_at
+		FROM chat_messages WHERE id = ?`, id)
+	m, err := scanMessage(row)
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return Message{}, fmt.Errorf("history: read message %s: %w", id, ErrMessageNotFound)
+		}
+		return Message{}, fmt.Errorf("history: read message %s: %w", id, err)
+	}
+	return m, nil
+}
+
+// escapeLike escapes the LIKE wildcards in a user query so %, _ and \ match literally
+// (the caller pairs it with ESCAPE '\'). It is applied before the %...% wrapping.
+func escapeLike(query string) string {
+	return strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(query)
+}

internal/runtime/history/message_ops_test.go

@@ -0,0 +1,249 @@
+package history
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+// seedMessages appends msgs and returns them with their store-assigned ids.
+func seedMessages(t *testing.T, st *Store, msgs ...Message) []Message {
+	t.Helper()
+	out := make([]Message, 0, len(msgs))
+	for _, m := range msgs {
+		if err := st.Append(context.Background(), m); err != nil {
+			t.Fatalf("append %q: %v", m.Content, err)
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+func TestSearchSessionScopedNewestFirstAndPaged(t *testing.T) {
+	t.Parallel()
+	st := newStore(t)
+	ctx := context.Background()
+	seedMessages(t, st,
+		Message{SessionID: MainSessionID, Role: RoleUser, Content: "hit one", CreatedAt: 1000},
+		Message{SessionID: MainSessionID, Role: RoleAssistant, Content: "miss", CreatedAt: 1500},
+		Message{SessionID: MainSessionID, Role: RoleUser, Content: "hit two", CreatedAt: 2000},
+		Message{SessionID: MainSessionID, Role: RoleUser, Content: "hit three", CreatedAt: 3000},
+		Message{SessionID: MainSessionID, Role: RoleUser, Content: "hit four", CreatedAt: 4000},
+	)
+
+	// Newest-first page of two hits; the non-matching message is skipped.
+	page, err := st.Search(ctx, MainSessionID, "hit", 0, 2)
+	if err != nil {
+		t.Fatalf("search: %v", err)
+	}
+	if len(page) != 2 || page[0].CreatedAt != 4000 || page[1].CreatedAt != 3000 {
+		t.Fatalf("page = %+v, want [4000 3000]", page)
+	}
+
+	// before cursor walks to the older hits.
+	older, err := st.Search(ctx, MainSessionID, "hit", 3000, 2)
+	if err != nil {
+		t.Fatalf("search older: %v", err)
+	}
+	if len(older) != 2 || older[0].CreatedAt != 2000 || older[1].CreatedAt != 1000 {
+		t.Fatalf("older = %+v, want [2000 1000]", older)
+	}
+
+	// An empty query yields an empty (non-nil) slice, not the whole session.
+	empty, err := st.Search(ctx, MainSessionID, "", 0, 10)
+	if err != nil {
+		t.Fatalf("search empty: %v", err)
+	}
+	if empty == nil || len(empty) != 0 {
+		t.Fatalf("empty query = %#v, want empty non-nil", empty)
+	}
+}
+
+func TestSearchCaseInsensitiveAndLiteralWildcards(t *testing.T) {
+	t.Parallel()
+	st := newStore(t)
+	ctx := context.Background()
+	seedMessages(t, st,
+		Message{SessionID: MainSessionID, Role: RoleUser, Content: "Hello World", CreatedAt: 1000},
+		Message{SessionID: MainSessionID, Role: RoleUser, Content: "100% done", CreatedAt: 2000},
+		Message{SessionID: MainSessionID, Role: RoleUser, Content: "under_score", CreatedAt: 3000},
+	)
+
+	// ASCII case-insensitive LIKE.
+	got, err := st.Search(ctx, MainSessionID, "hello", 0, 10)
+	if err != nil {
+		t.Fatalf("search hello: %v", err)
+	}
+	if len(got) != 1 || got[0].Content != "Hello World" {
+		t.Fatalf("hello = %+v, want [Hello World]", got)
+	}
+
+	// A literal % must not act as a wildcard (else it would match every row).
+	pct, err := st.Search(ctx, MainSessionID, "100%", 0, 10)
+	if err != nil {
+		t.Fatalf("search 100%%: %v", err)
+	}
+	if len(pct) != 1 || pct[0].Content != "100% done" {
+		t.Fatalf("100%% = %+v, want [100%% done]", pct)
+	}
+
+	// A literal _ must match only the underscore, not any single character.
+	us, err := st.Search(ctx, MainSessionID, "under_", 0, 10)
+	if err != nil {
+		t.Fatalf("search under_: %v", err)
+	}
+	if len(us) != 1 || us[0].Content != "under_score" {
+		t.Fatalf("under_ = %+v, want [under_score]", us)
+	}
+}
+
+// TestSearchNeverCrossesSessionBoundary is the red-line guard: a search is scoped to
+// one session, so an isolated group/stranger session's content can never surface in
+// the main session's results (or vice versa).
+func TestSearchNeverCrossesSessionBoundary(t *testing.T) {
+	t.Parallel()
+	st := newStore(t)
+	ctx := context.Background()
+	sub, err := st.NewSubSession(ctx, "owner")
+	if err != nil {
+		t.Fatalf("new sub: %v", err)
+	}
+	seedMessages(t, st,
+		Message{SessionID: MainSessionID, Role: RoleUser, Content: "secret-token main", CreatedAt: 1000},
+		Message{SessionID: sub, Role: RoleUser, Content: "secret-token sub", CreatedAt: 2000},
+		Message{SessionID: "sess-group", Role: RoleUser, Content: "secret-token group", CreatedAt: 3000, SenderName: "第三方"},
+	)
+
+	main, err := st.Search(ctx, MainSessionID, "secret-token", 0, 10)
+	if err != nil {
+		t.Fatalf("search main: %v", err)
+	}
+	if len(main) != 1 || main[0].SessionID != MainSessionID {
+		t.Fatalf("main search = %+v, want only the main-session hit", main)
+	}
+	subHits, err := st.Search(ctx, sub, "secret-token", 0, 10)
+	if err != nil {
+		t.Fatalf("search sub: %v", err)
+	}
+	if len(subHits) != 1 || subHits[0].SessionID != sub {
+		t.Fatalf("sub search = %+v, want only the sub hit", subHits)
+	}
+}
+
+func TestUpdateMessageContentOnly(t *testing.T) {
+	t.Parallel()
+	st := newStore(t)
+	ctx := context.Background()
+	seedMessages(t, st, Message{ID: "m1", SessionID: MainSessionID, Role: RoleUser, Content: "before", CreatedAt: 1000})
+
+	got, err := st.UpdateMessage(ctx, "m1", "after")
+	if err != nil {
+		t.Fatalf("update: %v", err)
+	}
+	if got.ID != "m1" || got.Content != "after" || got.Role != RoleUser || got.CreatedAt != 1000 || got.SessionID != MainSessionID {
+		t.Fatalf("updated = %+v, want content=after with role/ts/session preserved", got)
+	}
+
+	// The edit is persisted, not just echoed.
+	listed, err := st.List(ctx, MainSessionID, 0, 10, "")
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(listed) != 1 || listed[0].Content != "after" {
+		t.Fatalf("listed = %+v, want content=after", listed)
+	}
+
+	// An unknown id returns the sentinel.
+	if _, err := st.UpdateMessage(ctx, "missing", "x"); !errors.Is(err, ErrMessageNotFound) {
+		t.Fatalf("update missing err = %v, want ErrMessageNotFound", err)
+	}
+}
+
+func TestDeleteMessage(t *testing.T) {
+	t.Parallel()
+	st := newStore(t)
+	ctx := context.Background()
+	seedMessages(t, st,
+		Message{ID: "m1", SessionID: MainSessionID, Role: RoleUser, Content: "keep", CreatedAt: 1000},
+		Message{ID: "m2", SessionID: MainSessionID, Role: RoleAssistant, Content: "drop", CreatedAt: 2000},
+	)
+
+	if err := st.DeleteMessage(ctx, "m2"); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	listed, err := st.List(ctx, MainSessionID, 0, 10, "")
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(listed) != 1 || listed[0].ID != "m1" {
+		t.Fatalf("listed = %+v, want only m1", listed)
+	}
+	if err := st.DeleteMessage(ctx, "m2"); !errors.Is(err, ErrMessageNotFound) {
+		t.Fatalf("delete again err = %v, want ErrMessageNotFound", err)
+	}
+}
+
+func TestSetPinnedOrdersSessions(t *testing.T) {
+	t.Parallel()
+	st := newStore(t)
+	ctx := context.Background()
+	first, err := st.NewSubSession(ctx, "owner")
+	if err != nil {
+		t.Fatalf("new sub 1: %v", err)
+	}
+	second, err := st.NewSubSession(ctx, "owner")
+	if err != nil {
+		t.Fatalf("new sub 2: %v", err)
+	}
+
+	// Baseline: main first, subs oldest-first.
+	assertSessionOrder(t, st, []string{MainSessionID, first, second})
+
+	// Pinning the newest sub floats it above the main session.
+	if err := st.SetPinned(ctx, second, true); err != nil {
+		t.Fatalf("pin: %v", err)
+	}
+	assertSessionOrder(t, st, []string{second, MainSessionID, first})
+	if metas := listMetas(t, st); !metas[0].Pinned {
+		t.Fatalf("pinned session meta = %+v, want Pinned=true", metas[0])
+	}
+
+	// Unpinning restores the baseline order.
+	if err := st.SetPinned(ctx, second, false); err != nil {
+		t.Fatalf("unpin: %v", err)
+	}
+	assertSessionOrder(t, st, []string{MainSessionID, first, second})
+
+	// An unknown session id is a not-found error.
+	if err := st.SetPinned(ctx, "web:missing", true); !errors.Is(err, ErrSessionNotFound) {
+		t.Fatalf("pin missing err = %v, want ErrSessionNotFound", err)
+	}
+}
+
+// listMetas returns ListSessions output for order/pin assertions.
+func listMetas(t *testing.T, st *Store) []SessionMeta {
+	t.Helper()
+	metas, err := st.ListSessions(context.Background())
+	if err != nil {
+		t.Fatalf("list sessions: %v", err)
+	}
+	return metas
+}
+
+// assertSessionOrder fails unless ListSessions returns exactly ids in order.
+func assertSessionOrder(t *testing.T, st *Store, ids []string) {
+	t.Helper()
+	metas := listMetas(t, st)
+	got := make([]string, 0, len(metas))
+	for _, m := range metas {
+		got = append(got, m.ID)
+	}
+	if len(got) != len(ids) {
+		t.Fatalf("session order = %v, want %v", got, ids)
+	}
+	for i := range ids {
+		if got[i] != ids[i] {
+			t.Fatalf("session order = %v, want %v", got, ids)
+		}
+	}
+}

internal/runtime/history/session_pin.go

@@ -0,0 +1,33 @@
+package history
+
+import (
+	"context"
+	"fmt"
+)
+
+// SetPinned pins or unpins a persistent session. Pinning is display/order metadata
+// only (like the title): both the fixed main session and sub sessions may be pinned,
+// and identity/permissions never derive from it. An unknown id returns
+// ErrSessionNotFound.
+func (s *Store) SetPinned(ctx context.Context, sessionID string, pinned bool) error {
+	res, err := s.db.ExecContext(ctx, `UPDATE chat_sessions SET pinned = ? WHERE id = ?`, pinnedValue(pinned), sessionID)
+	if err != nil {
+		return fmt.Errorf("history: set pinned %s: %w", sessionID, err)
+	}
+	n, err := res.RowsAffected()
+	if err != nil {
+		return fmt.Errorf("history: set pinned %s rows: %w", sessionID, err)
+	}
+	if n == 0 {
+		return fmt.Errorf("history: set pinned %s: %w", sessionID, ErrSessionNotFound)
+	}
+	return nil
+}
+
+// pinnedValue maps the boolean to SQLite's 0/1 integer representation.
+func pinnedValue(pinned bool) int {
+	if pinned {
+		return 1
+	}
+	return 0
+}

internal/runtime/history/session_preview.go

@@ -29,8 +29,9 @@ type MessageSummary struct {
 // LEFT JOIN's correlated subquery resolves each session's newest row via the
 // (session_id, created_at DESC) index (rowid DESC breaks a same-millisecond tie by
 // insertion order), so a session with no messages still appears with NULL preview
-// columns. Ordering keeps the main session first, then subs oldest-first.
-const listSessionsQuery = `SELECT s.id, s.type, s.title, s.created_at,
+// columns. Ordering floats pinned sessions first, then keeps the main session before
+// unpinned subs, then subs oldest-first.
+const listSessionsQuery = `SELECT s.id, s.type, s.title, s.pinned, s.created_at,
 		m.role, m.content, m.created_at
 	FROM chat_sessions s
 	LEFT JOIN chat_messages m ON m.rowid = (
@@ -39,12 +40,12 @@ const listSessionsQuery = `SELECT s.id, s.type, s.title, s.created_at,
 		ORDER BY created_at DESC, rowid DESC
 		LIMIT 1
 	)
-	ORDER BY (s.type = ?) DESC, s.created_at ASC`
+	ORDER BY s.pinned DESC, (s.type = ?) DESC, s.created_at ASC`
 
-// ListSessions returns the main session first, then every sub session, oldest first,
-// each carrying a LastMessage preview of its newest message (nil when the session has
-// none). Sessions and previews are read in a single query, so the query count does not
-// grow with the number of sessions. The returned slice is non-nil.
+// ListSessions returns pinned sessions first, then the main session, then every sub
+// session, oldest first, each carrying a LastMessage preview of its newest message (nil
+// when the session has none). Sessions and previews are read in a single query, so the
+// query count does not grow with the number of sessions. The returned slice is non-nil.
 func (s *Store) ListSessions(ctx context.Context) ([]SessionMeta, error) {
 	rows, err := s.db.QueryContext(ctx, listSessionsQuery, SessionMain)
 	if err != nil {
@@ -73,14 +74,16 @@ func scanSessionMeta(sc rowScanner) (SessionMeta, error) {
 	var (
 		meta    SessionMeta
 		typeStr string
+		pinned  int
 		role    sql.NullString
 		content sql.NullString
 		lastAt  sql.NullInt64
 	)
-	if err := sc.Scan(&meta.ID, &typeStr, &meta.Title, &meta.CreatedAt, &role, &content, &lastAt); err != nil {
+	if err := sc.Scan(&meta.ID, &typeStr, &meta.Title, &pinned, &meta.CreatedAt, &role, &content, &lastAt); err != nil {
 		return SessionMeta{}, err
 	}
 	meta.Type = typeStr
+	meta.Pinned = pinned != 0
 	if role.Valid && lastAt.Valid {
 		meta.LastMessage = &MessageSummary{
 			Role:      role.String,

internal/runtime/history/store.go

@@ -62,6 +62,10 @@ var (
 
 	// ErrImmutableMain is returned when a caller tries to delete the fixed main session.
 	ErrImmutableMain = errors.New("history: the main session cannot be deleted")
+
+	// ErrMessageNotFound is returned by UpdateMessage/DeleteMessage when no
+	// chat_messages row carries the requested id.
+	ErrMessageNotFound = errors.New("history: message not found")
 )
 
 // Message is one persisted chat message. CreatedAt is a Unix millisecond timestamp and
@@ -109,6 +113,9 @@ type SessionMeta struct {
 	Type      string // "main" | "sub"
 	Title     string
 	CreatedAt int64
+	// Pinned floats the session to the top of ListSessions. It is display/order
+	// metadata only; identity and permissions never derive from it.
+	Pinned bool
 	// LastMessage is a display-only preview of the session's newest message, filled
 	// by ListSessions in the same query. It is nil for a session with no messages.
 	// A client uses it to render the conversation row without a per-session request;
@@ -161,13 +168,33 @@ type HistoryStore interface {
 	// DeleteSession removes a sub session and all its messages. The main session is
 	// immutable and returns ErrImmutableMain.
 	DeleteSession(ctx context.Context, sessionID string) error
+	// Search returns up to limit messages for sessionID whose content contains query
+	// (case-insensitive ASCII LIKE, with %/_/\ escaped), newest first. before is the
+	// same millisecond cursor as List; limit is clamped to [1, maxPageLimit]. An empty
+	// query returns an empty slice (the caller falls back to List for plain paging).
+	// Search is always scoped to one session, so an isolated group/stranger session can
+	// never surface in another session's results.
+	Search(ctx context.Context, sessionID, query string, before int64, limit int) ([]Message, error)
+	// UpdateMessage replaces the content of the message with id and returns the
+	// updated message (like AppendFull, so the caller can broadcast it without a
+	// second read). Only content changes; role/timestamps/platform stay as stored.
+	// An unknown id returns ErrMessageNotFound.
+	UpdateMessage(ctx context.Context, id, content string) (Message, error)
+	// DeleteMessage removes a single message. An unknown id returns
+	// ErrMessageNotFound.
+	DeleteMessage(ctx context.Context, id string) error
 	// RenameSession sets a session's display title. Both the main session and sub
 	// sessions may be renamed (a title is display-only metadata); an unknown id
 	// returns ErrSessionNotFound.
 	RenameSession(ctx context.Context, sessionID, title string) error
+	// SetPinned pins or unpins a session. Pinning is display/order metadata only;
+	// both the main session and sub sessions may be pinned. An unknown id returns
+	// ErrSessionNotFound.
+	SetPinned(ctx context.Context, sessionID string, pinned bool) error
 	// NewSubSession creates a new sub session and returns its id (MainSessionID:uuid).
 	NewSubSession(ctx context.Context, ownerID string) (string, error)
-	// ListSessions returns the main session first then every sub session, oldest first.
+	// ListSessions returns pinned sessions first, then the main session, then every
+	// sub session oldest first.
 	ListSessions(ctx context.Context) ([]SessionMeta, error)
 }
 
@@ -551,6 +578,7 @@ CREATE TABLE IF NOT EXISTS chat_sessions (
     id         TEXT PRIMARY KEY,
     type       TEXT NOT NULL,
     title      TEXT NOT NULL DEFAULT '',
+    pinned     INTEGER NOT NULL DEFAULT 0,
     created_at INTEGER NOT NULL
 )`