AskaEth/Cyrene_v2
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(comments): 注释中文化 · internal/runtime/history（15 文件，纯替换）
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
Details
CI / Frontend (tsc + vite build) (push) Has been cancelled
Details

Browse Source 
- 只翻注释/文档字符串：剥离注释后代码行逐字节不变（机械校验只剩 4 条行尾注释的翻译，代码前缀全等）
- 交叉引用（design/16 §4.6、D4/B3、0010 迁移文件名）逐字保留
- 保留未译技术词：DDL/rowid/LIKE/LEFT JOIN/DTO/rune/WS/actor 及全部标识符与表名
- 顺带副作用：store.go、session_persona_test.go 由注释文字改变而变得 gofmt 干净（未运行 gofmt -w）
This commit is contained in:
AskaEth committed 2026-10-04 12:28:48 +08:00
1 parent b0fbb8bc0d
commit 09fba77f87
15 files changed
+430 -516
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/runtime/history/list_after.go
+6 -9
View File
@@ -5,15 +5,12 @@ import (
"fmt"
)
// ListAfter returns up to limit messages for sessionID strictly newer than after
// (created_at > after) in oldest-first order, for forward incremental catch-up: a
// client that reconnected passes the newest createdAt it has already seen and pulls
// only what it missed, however many messages that is (the "before" cursor only walks
// backwards and cannot recover a gap larger than one page). When platform is non-empty
// the page is further restricted to messages carrying that source platform, exactly as
// in List. rowid breaks created_at ties so messages written in the same millisecond
// keep their insertion order. The returned slice is non-nil; limit is clamped to
// [1, maxPageLimit].
// ListAfter 按最旧优先返回 sessionID 中严格新于 after（created_at > after）的
// 至多 limit 条消息，用于前向增量追赶：重连的客户端传入自己已见过的最新
// createdAt，只拉取错过的部分，无论有多少条（"before" 游标只能向后走，无法
// 恢复大于一页的空洞）。platform 非空时把该页进一步限制为携带该来源平台的
// 消息，与 List 完全一致。rowid 打破 created_at 的并列，使同一毫秒写入的
// 消息保持插入顺序。返回切片非 nil；limit 钳制到 [1, maxPageLimit]。
func (s *Store) ListAfter(ctx context.Context, sessionID string, after int64, limit int, platform string) ([]Message, error) {
limit = clampLimit(limit)
query := `SELECT id, session_id, role, content, mode, mood, image, thinking, platform, device_id, sender_name, adapter_id, persona_id, created_at
internal/runtime/history/list_after_test.go
+11 -12
View File
@@ -5,8 +5,8 @@ import (
"testing"
)
// TestListAfterAscendingExclusive asserts the forward cursor returns only messages
// strictly newer than after, in oldest-first order (the reconnect catch-up direction).
// TestListAfterAscendingExclusive 断言前向游标只返回严格新于 after 的消息，且按
// 最旧优先排序（重连追赶方向）。
func TestListAfterAscendingExclusive(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -25,7 +25,7 @@ func TestListAfterAscendingExclusive(t *testing.T) {
t.Fatalf("after=2000 = %+v, want ascending [3000 4000]", []int64{msgs[0].CreatedAt, msgs[1].CreatedAt})
}
// after at the newest message yields an empty (non-nil) page.
// after 落在最新消息处时得到空（非 nil）的一页。
msgs, err = st.ListAfter(ctx, MainSessionID, 4000, 50, "")
if err != nil {
t.Fatalf("list after newest: %v", err)
@@ -34,7 +34,7 @@ func TestListAfterAscendingExclusive(t *testing.T) {
t.Fatalf("after=4000 = %+v (nil=%v), want empty non-nil", msgs, msgs == nil)
}
// after=0 is the whole session, still ascending.
// after=0 即整个会话，仍为升序。
msgs, err = st.ListAfter(ctx, MainSessionID, 0, 50, "")
if err != nil {
t.Fatalf("list after 0: %v", err)
@@ -44,9 +44,8 @@ func TestListAfterAscendingExclusive(t *testing.T) {
}
}
// TestListAfterSameTimestampRowIDOrder asserts messages sharing a created_at keep their
// insertion order, so a same-millisecond batch is never reordered or dropped at a page
// boundary (rowid tiebreak).
// TestListAfterSameTimestampRowIDOrder 断言共享同一 created_at 的消息保持插入
// 顺序，使同一毫秒的一批消息在分页边界处既不会被重排也不会被丢弃（rowid 破并列）。
func TestListAfterSameTimestampRowIDOrder(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -65,8 +64,8 @@ func TestListAfterSameTimestampRowIDOrder(t *testing.T) {
}
}
// TestListAfterPlatformFilter asserts the optional platform filter applies to the forward
// query exactly as it does to the backward one.
// TestListAfterPlatformFilter 断言可选的平台过滤在前向查询上的作用与后向查询完全
// 一致。
func TestListAfterPlatformFilter(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -90,8 +89,8 @@ func TestListAfterPlatformFilter(t *testing.T) {
}
}
// TestListAfterLimitClamp asserts a client-supplied limit is capped at maxPageLimit and
// that advancing the cursor pages forward without gaps.
// TestListAfterLimitClamp 断言客户端传入的 limit 被钳制到 maxPageLimit，且推进
// 游标能无缝隙地向前翻页。
func TestListAfterLimitClamp(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -115,7 +114,7 @@ func TestListAfterLimitClamp(t *testing.T) {
t.Fatalf("clamped page bounds = [%d..%d]", page[0].CreatedAt, page[len(page)-1].CreatedAt)
}
// Advance the cursor to the last seen createdAt: the remaining messages, no gap.
// 把游标推进到最后见过的 createdAt：拿到剩余消息，无缝隙。
next, err := st.ListAfter(ctx, MainSessionID, page[len(page)-1].CreatedAt, 999, "")
if err != nil {
t.Fatalf("list after next: %v", err)
internal/runtime/history/message_ops.go
+21 -26
View File
@@ -8,20 +8,18 @@ import (
"strings"
)
// This file owns the single-message operations behind the Android collaboration batch
// ③a (D2 search, D3 edit/delete) plus the id-scoped read the D delete broadcast needs.
// All 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 (GetMessage/UpdateMessage/
// DeleteMessage), so an isolated group/stranger session can never surface in another
// session's results (project red line).
// 本文件负责 Android 协同批次 ③a 背后的单条消息操作（D2 搜索、D3 编辑/删除），
// 以及 D 删除广播所需的按 id 读取。它们都严格限定在会话作用域或 id 作用域：
// 消息只能经由它所属的会话（Search）或它自己不透明的 id（GetMessage/
// UpdateMessage/DeleteMessage）到达，因此隔离的群聊/陌生人会话绝不浮现在
// 另一个会话的结果中（项目红线）。
// 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.
// Search 按最新优先返回 sessionID 中内容包含 query 的至多 limit 条消息。匹配
// 是 ASCII 大小写不敏感的 LIKE（SQLite 对 LIKE 的默认行为），并把 query 中的
// %/_/\ 转义使它们按字面匹配；before 与 List 是同一个毫秒游标（严格早于
// before），limit 钳制到 [1, maxPageLimit]。rowid 打破 created_at 的并列，使
// 同一毫秒的消息保持稳定顺序。空 query 返回空（非 nil）切片 —— 调用方改用
// List 做普通翻页。Search 绝不跨越会话边界。
func (s *Store) Search(ctx context.Context, sessionID, query string, before int64, limit int) ([]Message, error) {
limit = clampLimit(limit)
if query == "" {
@@ -57,10 +55,9 @@ func (s *Store) Search(ctx context.Context, sessionID, query string, before int6
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.
// UpdateMessage 替换 id 所指消息的内容并返回更新后的消息（与 AppendFull
// 一样，使调用方能无需二次读取就返回/广播它）。只有 content 变化；role、
// platform、时间戳及其余字段保持已存值。未知 id 返回 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 {
@@ -76,7 +73,7 @@ func (s *Store) UpdateMessage(ctx context.Context, id, content string) (Message,
return s.messageByID(ctx, id)
}
// DeleteMessage removes a single message. An unknown id returns ErrMessageNotFound.
// DeleteMessage 删除单条消息。未知 id 返回 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 {
@@ -92,16 +89,14 @@ func (s *Store) DeleteMessage(ctx context.Context, id string) error {
return nil
}
// GetMessage reads the message with id, returning ErrMessageNotFound when no such
// row exists. It is the id-scoped read the transport uses before removing a
// message: DeleteMessage leaves nothing to ask afterwards, yet the broadcast that
// tells other clients to drop the row is session-scoped.
// GetMessage 读取 id 所指消息，没有该行时返回 ErrMessageNotFound。它是传输层
// 在移除消息之前使用的按 id 读取：DeleteMessage 之后已无从再问，而那条告知
// 其他客户端丢弃该行的广播是按会话划分的。
func (s *Store) GetMessage(ctx context.Context, id string) (Message, error) {
return s.messageByID(ctx, id)
}
// messageByID reads one message by id, returning ErrMessageNotFound when the row is
// absent.
// messageByID 按 id 读取一条消息，行不存在时返回 ErrMessageNotFound。
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, persona_id, created_at
FROM chat_messages WHERE id = ?`, id)
@@ -115,8 +110,8 @@ func (s *Store) messageByID(ctx context.Context, id string) (Message, error) {
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.
// escapeLike 转义用户查询中的 LIKE 通配符，使 %、_ 与 \ 按字面匹配（调用方
// 配合 ESCAPE '\' 使用）。它在 %...% 包裹之前应用。
func escapeLike(query string) string {
return strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(query)
}
internal/runtime/history/message_ops_test.go
+17 -18
View File
@@ -6,7 +6,7 @@ import (
"testing"
)
// seedMessages appends msgs and returns them with their store-assigned ids.
// seedMessages 追加 msgs 并返回它们（带存储分配的 id）。
func seedMessages(t *testing.T, st *Store, msgs ...Message) []Message {
t.Helper()
out := make([]Message, 0, len(msgs))
@@ -31,7 +31,7 @@ func TestSearchSessionScopedNewestFirstAndPaged(t *testing.T) {
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)
@@ -40,7 +40,7 @@ func TestSearchSessionScopedNewestFirstAndPaged(t *testing.T) {
t.Fatalf("page = %+v, want [4000 3000]", page)
}
// before cursor walks to the older hits.
// before 游标走到更旧的命中。
older, err := st.Search(ctx, MainSessionID, "hit", 3000, 2)
if err != nil {
t.Fatalf("search older: %v", err)
@@ -49,7 +49,7 @@ func TestSearchSessionScopedNewestFirstAndPaged(t *testing.T) {
t.Fatalf("older = %+v, want [2000 1000]", older)
}
// An empty query yields an empty (non-nil) slice, not the whole session.
// 空查询得到空（非 nil）切片，而不是整个会话。
empty, err := st.Search(ctx, MainSessionID, "", 0, 10)
if err != nil {
t.Fatalf("search empty: %v", err)
@@ -69,7 +69,7 @@ func TestSearchCaseInsensitiveAndLiteralWildcards(t *testing.T) {
Message{SessionID: MainSessionID, Role: RoleUser, Content: "under_score", CreatedAt: 3000},
)
// ASCII case-insensitive LIKE.
// ASCII 大小写不敏感的 LIKE。
got, err := st.Search(ctx, MainSessionID, "hello", 0, 10)
if err != nil {
t.Fatalf("search hello: %v", err)
@@ -78,7 +78,7 @@ func TestSearchCaseInsensitiveAndLiteralWildcards(t *testing.T) {
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)
@@ -87,7 +87,7 @@ func TestSearchCaseInsensitiveAndLiteralWildcards(t *testing.T) {
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)
@@ -97,9 +97,8 @@ func TestSearchCaseInsensitiveAndLiteralWildcards(t *testing.T) {
}
}
// 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).
// TestSearchNeverCrossesSessionBoundary 是红线守卫：搜索限定在单个会话内，因此
// 隔离的群聊/陌生人会话内容绝不浮现在主会话的结果里（反之亦然）。
func TestSearchNeverCrossesSessionBoundary(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -144,7 +143,7 @@ func TestUpdateMessageContentOnly(t *testing.T) {
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)
@@ -153,7 +152,7 @@ func TestUpdateMessageContentOnly(t *testing.T) {
t.Fatalf("listed = %+v, want content=after", listed)
}
// An unknown id returns the sentinel.
// 未知 id 返回哨兵错误。
if _, err := st.UpdateMessage(ctx, "missing", "x"); !errors.Is(err, ErrMessageNotFound) {
t.Fatalf("update missing err = %v, want ErrMessageNotFound", err)
}
@@ -196,10 +195,10 @@ func TestSetPinnedOrdersSessions(t *testing.T) {
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)
}
@@ -208,19 +207,19 @@ func TestSetPinnedOrdersSessions(t *testing.T) {
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.
// 未知会话 id 是 not-found 错误。
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.
// listMetas 返回 ListSessions 的结果，用于顺序/置顶断言。
func listMetas(t *testing.T, st *Store) []SessionMeta {
t.Helper()
metas, err := st.ListSessions(context.Background())
@@ -230,7 +229,7 @@ func listMetas(t *testing.T, st *Store) []SessionMeta {
return metas
}
// assertSessionOrder fails unless ListSessions returns exactly ids in order.
// assertSessionOrder 在 ListSessions 没有严格按 ids 的顺序返回时使测试失败。
func assertSessionOrder(t *testing.T, st *Store, ids []string) {
t.Helper()
metas := listMetas(t, st)
internal/runtime/history/session_persona.go
+19 -24
View File
@@ -9,22 +9,20 @@ import (
"time"
)
// This file owns the per-session role binding (DevDocs/design/22 多角色并存 +
// 按会话选角 §2/§4.1). A session's role is the single source of truth for "which
// role answers in this conversation": the loop resolves the system prompt, the
// memory scope, the emotion machine and the thinking budget from it. The value
// is display/scope metadata only — identity and permissions are still decided by
// the channel actor metadata (project red line).
// 本文件负责每会话的角色绑定（DevDocs/design/22 多角色并存 +
// 按会话选角 §2/§4.1）。一个会话的角色是「这个对话里由哪个角色应答」的唯一
// 事实来源：循环据此解析系统提示词、记忆作用域、情绪机与思考预算。该值只是
// 展示/作用域元数据 —— 身份与权限仍由渠道 actor 元数据决定（项目红线）。
//
// '' means "inherit the current global default role", so it is both the column
// default and a legal explicit value: setting it clears an explicit binding and
// lets the session follow a default-role change again (design/22 §7-6).
// 空意味着「继承当前全局默认角色」，因此它既是列默认值，也是一个合法的显式
// 取值：把它设为空即清除显式绑定，让会话重新跟随默认角色变更
// （design/22 §7-6）。
// NewSubSessionFor creates a sub session bound to personaID and returns its id
// (MainSessionID:uuid). A blank personaID binds no explicit role, so the session
// inherits the global default — the same behavior as NewSubSession. ownerID is
// accepted for symmetry with NewSubSession (the Web owner is identified by JWT,
// not stored per session); it is logged at debug and not persisted.
// NewSubSessionFor 创建绑定到 personaID 的子会话并返回其 id
// （MainSessionID:uuid）。personaID 为空则不绑定任何显式角色，会话因此继承
// 全局默认 —— 与 NewSubSession 行为相同。ownerID 为与 NewSubSession 对称而
// 接受（Web 主人由 JWT 识别，不按会话存储）；它只以 debug 级别记日志，不被
// 持久化。
func (s *Store) NewSubSessionFor(ctx context.Context, ownerID, personaID string) (string, error) {
id, err := newID()
if err != nil {
@@ -42,11 +40,10 @@ func (s *Store) NewSubSessionFor(ctx context.Context, ownerID, personaID string)
return sessionID, nil
}
// SetSessionPersona binds (or clears, when personaID is blank) a session's role.
// Both the fixed main session and sub sessions may be retargeted: the binding is
// scope metadata, not identity. An unknown id returns ErrSessionNotFound. It
// never touches the conversation: the stored messages keep the role that spoke
// them (design/22 §7-5), and the next turn simply resolves the new role.
// SetSessionPersona 绑定（或在 personaID 为空时清除）一个会话的角色。固定主
// 会话与子会话都可被改绑：该绑定是作用域元数据，不是身份。未知 id 返回
// ErrSessionNotFound。它绝不触碰对话：已存消息保留说出它们的那个角色
// （design/22 §7-5），下一个回合只是解析新角色。
func (s *Store) SetSessionPersona(ctx context.Context, sessionID, personaID string) error {
res, err := s.db.ExecContext(ctx, `UPDATE chat_sessions SET persona_id = ? WHERE id = ?`,
strings.TrimSpace(personaID), sessionID)
@@ -63,11 +60,9 @@ func (s *Store) SetSessionPersona(ctx context.Context, sessionID, personaID stri
return nil
}
// SessionPersona returns the role bound to sessionID, or "" when the session
// inherits the global default. An unknown id returns ErrSessionNotFound so a
// caller can tell "no explicit role" (a real session, empty binding) from "no
// such session"; a caller that only needs the effective role treats both as
// "use the default".
// SessionPersona 返回绑定到 sessionID 的角色，会话继承全局默认时返回空。未知
// id 返回 ErrSessionNotFound，使调用方能区分「没有显式角色」（真实会话、绑定
// 为空）与「没有这个会话」；只需要有效角色的调用方把两者都当作「用默认」。
func (s *Store) SessionPersona(ctx context.Context, sessionID string) (string, error) {
var personaID string
err := s.db.QueryRowContext(ctx, `SELECT persona_id FROM chat_sessions WHERE id = ?`, sessionID).Scan(&personaID)
internal/runtime/history/session_persona_test.go
+18 -23
View File
@@ -6,8 +6,7 @@ import (
"testing"
)
// personaOf returns the stored role binding of a session, failing the test when the
// session is absent from the list.
// personaOf 返回某个会话已存储的角色绑定，会话不在列表中时使测试失败。
func personaOf(t *testing.T, st *Store, id string) string {
t.Helper()
sessions, err := st.ListSessions(context.Background())
@@ -23,11 +22,10 @@ func personaOf(t *testing.T, st *Store, id string) string {
return ""
}
// TestSessionPersonaRoundTrip is design/22 acceptance 1: the session-level role is
// the single source of truth, so a value written through SetSessionPersona must come
// back from both the direct read and the list projection (the DTO the client gets),
// and the main session — which always exists — starts out unbound ('' = inherit the
// global default). An explicit "" clears the binding back to that same state.
// TestSessionPersonaRoundTrip 是 design/22 验收 1：会话级角色是唯一事实来源，
// 因此通过 SetSessionPersona 写入的值必须能从直接读取与列表投影（客户端拿到的
// DTO）两条路径读回，而始终存在的主会话初始为未绑定（空 = 继承全局默认）。
// 显式空串会把绑定清回同一状态。
func TestSessionPersonaRoundTrip(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -52,8 +50,7 @@ func TestSessionPersonaRoundTrip(t *testing.T) {
}
}
// An explicit empty value is the documented "unbind" (follow the default again),
// not a no-op.
// 显式空值是文档化的「解绑」（重新跟随默认），不是空操作。
if err := st.SetSessionPersona(ctx, MainSessionID, ""); err != nil {
t.Fatalf("SetSessionPersona(\"\"): %v", err)
}
@@ -62,9 +59,9 @@ func TestSessionPersonaRoundTrip(t *testing.T) {
}
}
// TestSessionPersonaUnknownSession covers the error contract: binding or reading the
// role of a session that does not exist reports ErrSessionNotFound (so the HTTP layer
// answers 404) instead of silently creating/looking up nothing.
// TestSessionPersonaUnknownSession 覆盖错误契约：绑定或读取一个不存在的会话的
// 角色会报 ErrSessionNotFound（因此 HTTP 层回答 404），而不是悄悄创建/查不到
// 任何东西。
func TestSessionPersonaUnknownSession(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -78,10 +75,9 @@ func TestSessionPersonaUnknownSession(t *testing.T) {
}
}
// TestNewSubSessionForBindsPersona locks the create path: a sub session created with a
// role carries it from its first read (no extra PATCH needed), and the plain
// NewSubSession still creates an unbound session — the pre-multi-character contract,
// which every existing caller relies on.
// TestNewSubSessionForBindsPersona 锁定创建路径：带角色创建的子会话从第一次读取
// 起就携带它（无需额外 PATCH），而朴素的 NewSubSession 仍创建未绑定会话 —— 即
// 多角色之前的契约，每个既有调用方都依赖它。
func TestNewSubSessionForBindsPersona(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -104,11 +100,10 @@ func TestNewSubSessionForBindsPersona(t *testing.T) {
}
}
// TestMessagePersonaPersisted proves design/22 §7-5's storage half: a session may
// switch roles while keeping its context, so every message records the role that
// SPOKE it. The column survives the write/read round trip through the same scanner
// the REST/WS DTOs use, and messages written without a role stay '' (= the default
// role), which is what keeps pre-upgrade history readable.
// TestMessagePersonaPersisted 证明 design/22 §7-5 的存储一半：一个会话可以在保留
// 上下文的同时切换角色，因此每条消息都记录说出它的那个角色。该列通过 REST/WS
// DTO 使用的同一个扫描器活过写入/读取往返，而未指定角色写入的消息保持为空
// （= 默认角色），这正是升级前历史仍可读的原因。
func TestMessagePersonaPersisted(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -139,8 +134,8 @@ func TestMessagePersonaPersisted(t *testing.T) {
t.Fatalf("unattributed message persona_id = %q, want ''", got)
}
// The persona column must also survive Recent (the WS replay path) and
// AppendFull (the orchestrator's realtime-sync path).
// persona 列还必须活过 Recent（WS 回放路径）与 AppendFull（编排器的实时
// 同步路径）。
recent, err := st.Recent(ctx, MainSessionID, 10)
if err != nil {
t.Fatalf("recent: %v", err)
internal/runtime/history/session_pin.go
+4 -5
View File
@@ -5,10 +5,9 @@ import (
"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.
// SetPinned 置顶或取消置顶一个持久化会话。置顶只是展示/排序元数据（与标题
// 一样）：固定主会话与子会话都可置顶，身份/权限绝不由它推导。未知 id 返回
// 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 {
@@ -24,7 +23,7 @@ func (s *Store) SetPinned(ctx context.Context, sessionID string, pinned bool) er
return nil
}
// pinnedValue maps the boolean to SQLite's 0/1 integer representation.
// pinnedValue 把布尔值映射为 SQLite 的 0/1 整数表示。
func pinnedValue(pinned bool) int {
if pinned {
return 1
internal/runtime/history/session_preview.go
+26 -33
View File
@@ -7,34 +7,29 @@ import (
"strings"
)
// This file owns the two derived per-session display fields carried in the session
// list (GET /api/v1/sessions): the last-message preview and the unread count. Both are
// read-only projections so a client can render a conversation row (with its unread
// badge) without one request per session. The preview is truncated for display, and
// neither field ever feeds identity or permission decisions — identity comes from
// channel actor metadata / JWT (project red line).
// 本文件负责会话列表中携带的两个派生展示字段（GET /api/v1/sessions）：最后
// 消息预览与未读数。两者都是只读投影，使客户端无需逐会话请求就能渲染对话行
// （及其未读角标）。预览会被截断以便展示，两个字段都绝不参与身份或权限判定
// —— 身份来自渠道 actor 元数据 / JWT（项目红线）。
// lastMessagePreviewRunes bounds the preview content so a long message cannot bloat the
// session-list response. A longer message is whitespace-collapsed and truncated to this
// many runes with an ellipsis.
// lastMessagePreviewRunes 限制预览内容，使一条长消息不会撑大会话列表响应。
// 更长的消息会先折叠空白，再截断到这么多 rune 并加省略号。
const lastMessagePreviewRunes = 60
// MessageSummary is a display-only preview of a session's most recent message.
// MessageSummary 是会话最新消息的纯展示预览。
type MessageSummary struct {
Role string // "user" | "assistant"
Content string // whitespace-collapsed, truncated preview
CreatedAt int64 // Unix milliseconds
Role string // "user" | "assistant"（用户 | 助手）
Content string // 已折叠空白、已截断的预览
CreatedAt int64 // Unix 毫秒
}
// listSessionsQuery reads every session plus its newest message and its unread count
// in one statement. The 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. The unread count is a correlated COUNT(*) over the same index
// (session_id = s.id AND created_at > s.read_at is an equality + range scan), so no
// per-session round trip (N+1) is needed and no extra index is required. Ordering floats
// pinned sessions first, then keeps the main session before unpinned subs, then subs
// oldest-first.
// listSessionsQuery 用一条语句读取每个会话及其最新消息与未读数。LEFT JOIN 的
// 关联子查询经由 (session_id, created_at DESC) 索引解析每个会话最新的那一行
// （rowid DESC 按插入顺序打破同一毫秒的并列），因此没有消息的会话仍会以预览
// 列全为 NULL 的形式出现。未读数是同一个索引上的关联 COUNT(*)
// （session_id = s.id AND created_at > s.read_at 是一次等值 + 范围扫描），
// 因此无需逐会话往返（N+1），也不需要额外索引。排序把置顶会话浮到最前，
// 再把主会话排在未置顶子会话之前，然后子会话最旧优先。
const listSessionsQuery = `SELECT s.id, s.type, s.title, s.pinned, s.created_at, s.persona_id,
m.role, m.content, m.created_at,
(SELECT COUNT(*) FROM chat_messages c
@@ -48,11 +43,10 @@ const listSessionsQuery = `SELECT s.id, s.type, s.title, s.pinned, s.created_at,
)
ORDER BY s.pinned DESC, (s.type = ?) DESC, s.created_at ASC`
// 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) and the UnreadCount derived from the session's read cursor.
// Sessions, previews and unread counts 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 按置顶会话在前、其后是主会话、最后是每个子会话（最旧优先）的
// 顺序返回，每个会话携带其最新消息的 LastMessage 预览（没有消息时为 nil）与
// 由会话读游标推导出的 UnreadCount。会话、预览与未读数在单次查询中读出，
// 因此查询数量不随会话数增长。返回切片非 nil。
func (s *Store) ListSessions(ctx context.Context) ([]SessionMeta, error) {
rows, err := s.db.QueryContext(ctx, listSessionsQuery, SessionMain)
if err != nil {
@@ -74,10 +68,9 @@ func (s *Store) ListSessions(ctx context.Context) ([]SessionMeta, error) {
return sessions, nil
}
// scanSessionMeta reads one joined chat_sessions + last-message + unread-count row. The
// three message columns are NULL for a session that has never received a message, so they
// scan into nullable holders and only produce a LastMessage when a row is present. The
// unread count is a non-NULL COUNT(*), so it scans into a plain int.
// scanSessionMeta 读取一行已连接的 chat_sessions + 最新消息 + 未读数。从未收到
// 消息的会话那三个消息列为 NULL，因此它们扫描到可空的容器里，只有该行存在时
// 才产出 LastMessage。未读数是非 NULL 的 COUNT(*)，因此扫描到普通 int。
func scanSessionMeta(sc rowScanner) (SessionMeta, error) {
var (
meta SessionMeta
@@ -102,8 +95,8 @@ func scanSessionMeta(sc rowScanner) (SessionMeta, error) {
return meta, nil
}
// previewContent collapses whitespace runs (newlines included) to single spaces and
// truncates to lastMessagePreviewRunes runes with an ellipsis. It is display-only.
// previewContent 把连续空白（含换行）折叠为单个空格，并截断到
// lastMessagePreviewRunes 个 rune 加省略号。它只用于展示。
func previewContent(content string) string {
joined := strings.Join(strings.Fields(content), " ")
runes := []rune(joined)
internal/runtime/history/session_preview_test.go
+6 -8
View File
@@ -6,8 +6,7 @@ import (
"testing"
)
// sessionOf returns the SessionMeta of one session from ListSessions, failing the test
// when the session is absent.
// sessionOf 从 ListSessions 里返回某个会话的 SessionMeta，会话缺失时使测试失败。
func sessionOf(t *testing.T, st *Store, id string) SessionMeta {
t.Helper()
sessions, err := st.ListSessions(context.Background())
@@ -28,7 +27,7 @@ func TestListSessionsLastMessagePreview(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// The empty main session has no preview.
// 空的主会话没有预览。
if got := sessionOf(t, st, MainSessionID); got.LastMessage != nil {
t.Fatalf("empty main LastMessage = %+v, want nil", got.LastMessage)
}
@@ -47,7 +46,7 @@ func TestListSessionsLastMessagePreview(t *testing.T) {
t.Fatalf("append sub: %v", err)
}
// Main stays first and carries its newest message, not the first one.
// 主会话仍在最前，携带它最新的消息，而不是第一条。
sessions, err := st.ListSessions(ctx)
if err != nil {
t.Fatalf("list sessions: %v", err)
@@ -64,7 +63,7 @@ func TestListSessionsLastMessagePreview(t *testing.T) {
t.Fatalf("sub LastMessage = %+v, want user/sub question/1500", subPreview)
}
// A sub session created after the main one but never written has no preview.
// 在主会话之后创建、但从未写入的子会话没有预览。
empty, err := st.NewSubSession(ctx, "owner")
if err != nil {
t.Fatalf("new empty sub: %v", err)
@@ -88,8 +87,7 @@ func TestListSessionsLastMessageTruncatesAndCollapses(t *testing.T) {
t.Fatalf("truncated preview = %+v, want %q", got, want)
}
// Whitespace runs (including newlines) collapse to single spaces, and a short
// message is returned whole.
// 连续空白（含换行）折叠为单个空格，短消息原样返回。
sub, err := st.NewSubSession(ctx, "owner")
if err != nil {
t.Fatalf("new sub: %v", err)
@@ -107,7 +105,7 @@ func TestListSessionsLastMessageTieBreaksByInsertion(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// Two messages sharing a millisecond timestamp: the later insert is the newest.
// 两条消息共享同一毫秒时间戳：后插入的是最新的。
for _, content := range []string{"older", "newer"} {
if err := st.Append(ctx, Message{SessionID: MainSessionID, Role: RoleAssistant, Content: content, CreatedAt: 5000}); err != nil {
t.Fatalf("append %s: %v", content, err)
internal/runtime/history/session_read.go
+13 -17
View File
@@ -6,26 +6,22 @@ import (
"time"
)
// This file owns the per-session read cursor (design/16 §4.2, Android 协同批次
// D4/B3). There is a single owner account and no per-device identity at this
// layer, so the cursor is session-scoped: reading on any one end marks the session
// read for every end of the account. The cursor lives on chat_sessions.read_at in
// the same millisecond unit as chat_messages.created_at, so the unread badge is a
// plain `created_at > read_at` count (see listSessionsQuery).
// 本文件负责每会话的读游标（design/16 §4.2，Android 协同批次 D4/B3）。本层
// 只有一个主人账号、没有按设备的身份，因此游标是会话作用域的：在任一端已读
// 即为该账号的每一端把该会话标为已读。游标存放在 chat_sessions.read_at，与
// chat_messages.created_at 同为毫秒单位，因此未读角标就是一个朴素的
// `created_at > read_at` 计数（见 listSessionsQuery）。
// MarkSessionRead advances the session's read cursor to before and returns the
// resulting cursor as a Unix millisecond timestamp. A zero before means "now" — the
// caller's "mark everything I have seen" case, which does not have to read the
// clock itself.
// MarkSessionRead 把会话的读游标推进到 before，并把结果游标作为 Unix 毫秒
// 时间戳返回。before 为零意味着「现在」—— 调用方「把我看到的全部标为已读」
// 的场景，无需自己读时钟。
//
// The cursor only ever moves forward: the UPDATE applies SQLite's two-argument
// scalar MAX, so a stale or out-of-order request (two ends racing, a retried
// request) can never un-read messages. A negative before therefore leaves the stored
// value untouched rather than moving it backwards.
// 游标只向前移动：该 UPDATE 使用 SQLite 的双参数标量 MAX，因此一个过期或
// 乱序的请求（两端竞争、请求重试）绝不能让消息重新变为未读。负的 before
// 因此不会挪动已存的值，而不是把它向后移。
//
// An unknown session id returns ErrSessionNotFound, matching RenameSession/SetPinned
// — isolated (group/stranger) sessions have no chat_sessions row and are not
// addressable here.
// 未知的会话 id 返回 ErrSessionNotFound，与 RenameSession/SetPinned 一致
// —— 隔离（群聊/陌生人）会话没有 chat_sessions 行，在此不可寻址。
func (s *Store) MarkSessionRead(ctx context.Context, sessionID string, before time.Time) (int64, error) {
ms := before.UnixMilli()
if before.IsZero() {
internal/runtime/history/session_read_test.go
+46 -56
View File
@@ -13,15 +13,14 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/db"
)
// These tests cover the D4 per-session read cursor (design/16 §4.2, Android
// collaboration B3): the unread count derived in ListSessions, the forward-only
// cursor semantics of MarkSessionRead, and the 0010 migration's upgrade backfill.
// 这些测试覆盖 D4 的每会话读游标（design/16 §4.2，Android 协同 B3）：
// ListSessions 推导出的未读数、MarkSessionRead 只向前推进的游标语义，
// 以及 0010 迁移的升级回填。
// TestListSessionsUnreadCountFromCursor pins the unread derivation: a message counts as
// unread only when it is strictly newer than the session's cursor (created_at > read_at),
// so the cursor is inclusive of the timestamp it names (a client that has rendered a
// message sent at T marks T read). A fresh session starts at cursor 0 with everything
// unread, and a cursor at the newest message clears the badge.
// TestListSessionsUnreadCountFromCursor 锁定未读推导：一条消息只有在严格新于
// 会话游标（created_at > read_at）时才计为未读，因此游标包含它所命名的那个
// 时间戳（渲染过 T 时刻消息的客户端把 T 标为已读）。全新会话从游标 0 开始、
// 一切皆未读，而游标落在最新消息处会清空角标。
func TestListSessionsUnreadCountFromCursor(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -31,11 +30,11 @@ func TestListSessionsUnreadCountFromCursor(t *testing.T) {
t.Fatalf("seed %d: %v", ts, err)
}
}
// Never read: all three messages are unread (a brand-new account/session).
// 从未读过：三条消息全未读（全新账号/会话）。
if got := sessionOf(t, st, MainSessionID).UnreadCount; got != 3 {
t.Fatalf("initial unreadCount = %d, want 3", got)
}
// Cursor on a message's own timestamp counts that message as read.
// 游标压在消息自身的毫秒上就算该消息已读。
readAt, err := st.MarkSessionRead(ctx, MainSessionID, time.UnixMilli(2000))
if err != nil {
t.Fatalf("mark read: %v", err)
@@ -46,14 +45,14 @@ func TestListSessionsUnreadCountFromCursor(t *testing.T) {
if got := sessionOf(t, st, MainSessionID).UnreadCount; got != 1 {
t.Fatalf("unreadCount after cursor 2000 = %d, want 1 (only 3000 newer)", got)
}
// A cursor between two messages reads the earlier one only.
// 游标落在两条消息之间只读到较早那条。
if _, err := st.MarkSessionRead(ctx, MainSessionID, time.UnixMilli(2500)); err != nil {
t.Fatalf("mark read 2500: %v", err)
}
if got := sessionOf(t, st, MainSessionID).UnreadCount; got != 1 {
t.Fatalf("unreadCount after cursor 2500 = %d, want 1", got)
}
// A cursor at the newest message clears the badge.
// 游标落在最新消息处清空角标。
if _, err := st.MarkSessionRead(ctx, MainSessionID, time.UnixMilli(3000)); err != nil {
t.Fatalf("mark read 3000: %v", err)
}
@@ -62,9 +61,8 @@ func TestListSessionsUnreadCountFromCursor(t *testing.T) {
}
}
// TestListSessionsUnreadCountSessionIsolation pins the per-session scope: each session
// carries its own cursor, so reading the main session must not clear (or inflate) a sub
// session's badge, and vice versa.
// TestListSessionsUnreadCountSessionIsolation 锁定每会话作用域：每个会话携带
// 自己的游标，因此读取主会话不得清空（或撑大）子会话的角标，反之亦然。
func TestListSessionsUnreadCountSessionIsolation(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -89,7 +87,7 @@ func TestListSessionsUnreadCountSessionIsolation(t *testing.T) {
t.Fatalf("sub unreadCount = %d, want 1", got)
}
// Reading the main session must leave the sub untouched.
// 读取主会话不得动子会话。
if _, err := st.MarkSessionRead(ctx, MainSessionID, time.UnixMilli(2000)); err != nil {
t.Fatalf("mark main read: %v", err)
}
@@ -100,7 +98,7 @@ func TestListSessionsUnreadCountSessionIsolation(t *testing.T) {
t.Fatalf("sub unreadCount after main read = %d, want 1 (cursors are per-session)", got)
}
// A message arriving after the read re-opens the main badge.
// 读取之后到达的消息会重新点亮主会话角标。
if err := st.Append(ctx, Message{SessionID: MainSessionID, Role: RoleUser, Content: "main-3", CreatedAt: 3000}); err != nil {
t.Fatalf("append main-3: %v", err)
}
@@ -109,9 +107,8 @@ func TestListSessionsUnreadCountSessionIsolation(t *testing.T) {
}
}
// TestMarkSessionReadForwardOnly covers the racing/malformed-request side of the cursor
// contract: the cursor never moves backwards, so a stale or repeated request is
// idempotent and can never resurrect already-read messages.
// TestMarkSessionReadForwardOnly 覆盖游标契约中竞争/畸形请求的一面：游标绝不后
// 退，因此过期或重复的请求是幂等的，绝不能让已读消息复活。
func TestMarkSessionReadForwardOnly(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -121,13 +118,12 @@ func TestMarkSessionReadForwardOnly(t *testing.T) {
t.Fatalf("seed %d: %v", ts, err)
}
}
// Advance to the newest message.
// 推进到最新消息。
readAt, err := st.MarkSessionRead(ctx, MainSessionID, time.UnixMilli(3000))
if err != nil || readAt != 3000 {
t.Fatalf("mark 3000 = (%d, %v), want (3000, nil)", readAt, err)
}
// A stale request (an end that was behind, or a retry of an older read) must not
// move the cursor back and re-open the badge.
// 过期请求（落后的端，或一次更旧读取的重试）不得把游标后退并重新点亮角标。
readAt, err = st.MarkSessionRead(ctx, MainSessionID, time.UnixMilli(1000))
if err != nil {
t.Fatalf("stale mark: %v", err)
@@ -138,8 +134,7 @@ func TestMarkSessionReadForwardOnly(t *testing.T) {
if got := sessionOf(t, st, MainSessionID).UnreadCount; got != 0 {
t.Fatalf("unreadCount after stale mark = %d, want 0 (never un-read)", got)
}
// Repeating the same cursor is a no-op, and a negative cursor is clamped by the
// same MAX (it cannot move the stored value at all).
// 重复同一游标是空操作，负游标被同一个 MAX 钳制（它根本无法挪动已存的值）。
if readAt, err = st.MarkSessionRead(ctx, MainSessionID, time.UnixMilli(3000)); err != nil || readAt != 3000 {
t.Fatalf("repeat mark = (%d, %v), want (3000, nil)", readAt, err)
}
@@ -148,9 +143,9 @@ func TestMarkSessionReadForwardOnly(t *testing.T) {
}
}
// TestMarkSessionReadZeroTimeMeansNow covers the "mark everything I have seen" call the
// HTTP layer makes when the body omits before: the zero time resolves to the wall clock,
// which reads every message that already exists.
// TestMarkSessionReadZeroTimeMeansNow 覆盖 HTTP 层在请求体省略 before 时发出的
// 「把我看到的全部标为已读」调用：零时刻解析为墙上时钟，从而读到所有已存在的
// 消息。
func TestMarkSessionReadZeroTimeMeansNow(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -174,10 +169,9 @@ func TestMarkSessionReadZeroTimeMeansNow(t *testing.T) {
}
}
// TestMarkSessionReadUnknownSession pins the error contract: an id with no chat_sessions
// row (including an isolated group/stranger session) is ErrSessionNotFound, so the HTTP
// layer can answer 404 instead of silently reporting success for a session that does not
// exist.
// TestMarkSessionReadUnknownSession 锁定错误契约：没有 chat_sessions 行的 id
// （包括隔离的群聊/陌生人会话）是 ErrSessionNotFound，因此 HTTP 层可以回答 404，
// 而不是为一个不存在的会话悄悄报告成功。
func TestMarkSessionReadUnknownSession(t *testing.T) {
t.Parallel()
st := newStore(t)
@@ -186,8 +180,8 @@ func TestMarkSessionReadUnknownSession(t *testing.T) {
}
}
// migrationFileSQL reads one migration file from the source tree, so the test applies
// the same SQL text the embedded migration runs rather than a copy.
// migrationFileSQL 从源码树读取一个迁移文件，使测试应用的是嵌入式迁移执行的那份
// SQL 文本，而不是一份副本。
func migrationFileSQL(t *testing.T, name string) string {
t.Helper()
b, err := os.ReadFile(filepath.Join("..", "..", "db", "migrations", name))
@@ -197,7 +191,7 @@ func migrationFileSQL(t *testing.T, name string) string {
return string(b)
}
// columnPresent reports whether table has a column named column.
// columnPresent 报告 table 是否有名为 column 的列。
func columnPresent(t *testing.T, conn *sql.DB, table, column string) bool {
t.Helper()
var n int
@@ -208,10 +202,9 @@ func columnPresent(t *testing.T, conn *sql.DB, table, column string) bool {
return n == 1
}
// openLegacyDB opens an in-memory DB carrying the pre-0010 schema (chat_sessions with no
// read_at column) plus two legacy sessions with prior history — the real fixed main
// session "web" and a sub session — so the 0010 migration can be applied to a database
// that really predates this feature.
// openLegacyDB 打开一个携带 0010 之前 schema（chat_sessions 没有 read_at 列）的
// 内存库，放入两个带既有历史的遗留会话 —— 真实固定主会话 "web" 与一个子会话
// —— 使 0010 迁移能应用到一个真正早于此特性的数据库上。
func openLegacyDB(t *testing.T) *sql.DB {
t.Helper()
ctx := context.Background()
@@ -273,12 +266,11 @@ func openLegacyDB(t *testing.T) *sql.DB {
return conn
}
// TestMigration0010ReadAtBackfill exercises the real 0010 migration against a legacy
// database: up adds the column and backfills each session's cursor to its newest message,
// so upgrade day reports 0 unread for existing history — including the fixed main session,
// whose existing history is the whole point of the upgrade — and the store (which
// re-issues the canonical DDL idempotently) then works on top of it; a message that arrives
// after the migration is unread until it is marked read; down drops the column again.
// TestMigration0010ReadAtBackfill 拿真实的 0010 迁移跑在一个遗留库上：up 增加该
// 列并把每个会话的游标回填到其最新消息，使升级日对既有历史报告 0 未读 —— 包括
// 固定主会话，它的既有历史正是这次升级的全部意义 —— 而存储（它幂等地重发规范
// DDL）随后能在其上工作；迁移之后到达的消息在标记已读前都是未读；down 再次
// 丢弃该列。
func TestMigration0010ReadAtBackfill(t *testing.T) {
ctx := context.Background()
conn := openLegacyDB(t)
@@ -289,18 +281,17 @@ func TestMigration0010ReadAtBackfill(t *testing.T) {
if _, err := conn.ExecContext(ctx, migrationFileSQL(t, "0010_chat_session_read_at.up.sql")); err != nil {
t.Fatalf("apply 0010 up: %v", err)
}
// Bring the simulated legacy database up to the current head (0011 adds the
// session/message persona columns), because the store reads the canonical schema:
// a database left one migration behind would lack persona_id. Upgrade ordering in
// production is db.MigrateUp, so this mirrors what a real upgrade produces.
// 让模拟的遗留库追到当前 head（0011 增加会话/消息 persona 列），因为存储
// 读取的是规范 schema：落后一个迁移的库会缺 persona_id。生产中的升级顺序是
// db.MigrateUp，因此这复现了真实升级的结果。
if _, err := conn.ExecContext(ctx, migrationFileSQL(t, "0011_session_persona.up.sql")); err != nil {
t.Fatalf("apply 0011 up: %v", err)
}
if !columnPresent(t, conn, "chat_sessions", "read_at") {
t.Fatal("read_at should exist after the 0010 up migration")
}
// The backfill is each session's newest message timestamp, not a blanket 0 (which
// would mark the whole existing history unread) and not the first message's.
// 回填的是每个会话最新消息的时间戳，不是一刀切的 0（那会把既有历史全部标为
// 未读），也不是第一条消息的时间戳。
for _, tc := range []struct {
sessionID string
want int64
@@ -318,10 +309,9 @@ func TestMigration0010ReadAtBackfill(t *testing.T) {
}
}
// The store comes up on the migrated schema and reports no unread for either
// pre-existing session (upgrade day must not light up every row, main session
// included); the store's INSERT OR IGNORE for the main session must not overwrite
// the backfilled cursor.
// 存储建立在迁移后的 schema 上，对两个既有会话都报告无未读（升级日不得点亮
// 每一行，主会话包括在内）；存储为主会话做的 INSERT OR IGNORE 不得覆盖回填
// 的游标。
st, err := NewStore(ctx, conn, testLogger())
if err != nil {
t.Fatalf("new store on migrated db: %v", err)
@@ -331,7 +321,7 @@ func TestMigration0010ReadAtBackfill(t *testing.T) {
t.Fatalf("legacy session %s unreadCount = %d, want 0 after backfill", sessionID, got)
}
}
// A message written after the migration is unread, and marking it read clears it.
// 迁移之后写入的消息是未读的，标记已读即清除。
if err := st.Append(ctx, Message{SessionID: "web:legacy", Role: RoleAssistant, Content: "new", CreatedAt: 9000}); err != nil {
t.Fatalf("append after migration: %v", err)
}
internal/runtime/history/store.go
+172 -206
View File
@@ -1,16 +1,15 @@
// Package history implements the persistent chat-history session model described in
// DevDocs/design/16-会话持久化与主次级会话.md.
// Package history 实现 DevDocs/design/16-会话持久化与主次级会话.md 描述的持久化
// 聊天历史会话模型。
//
// It is the storage layer, not the orchestration/context layer: it persists the raw
// message stream (chat_messages) and the persistent session records (chat_sessions)
// so the Web frontend can request + display history, and secondary (sub) sessions can
// be created, listed and deleted. It intentionally does not touch memory (design/16
// §3.2: memory is persona-scoped and lives in runtime/memory), does not build context
// (runtime/loop) and does not schedule turns (gateway/session_orchestrator).
// 它是存储层，而不是编排/上下文层：它持久化原始消息流（chat_messages）与持久化
// 会话记录（chat_sessions），使 Web 前端能请求并展示历史，子会话也能被创建、列出
// 与删除。它刻意不碰记忆（design/16 §3.2：记忆是角色作用域的，住在
// runtime/memory）、不构建上下文（runtime/loop），也不调度回合
// （gateway/session_orchestrator）。
//
// Session model (design/16 §2.1): there is exactly one fixed main session (id "web") and
// any number of sub sessions (id "web:<uuid>"). Main + sub share the same persona and
// therefore the same memory; this package only models sessions + messages.
// 会话模型（design/16 §2.1）：有且只有一个固定主会话（id "web"）与任意数量的子
// 会话（id "web:<uuid>"）。主会话与子会话共享同一角色，因而共享同一记忆；本包
// 只建模会话与消息。
package history
import (
@@ -27,50 +26,50 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
)
// Session roles and types. These are the values persisted in the role / type columns.
// 会话角色与类型。这些就是持久化在 role / type 列中的取值。
const (
// RoleUser, RoleAssistant, RoleSystem classify a message's author.
// RoleUser、RoleAssistant、RoleSystem 归类一条消息的作者。
RoleUser = "user"
RoleAssistant = "assistant"
RoleSystem = "system"
// SessionMain and SessionSub classify a persistent session.
// SessionMain 与 SessionSub 归类一个持久化会话。
SessionMain = "main"
SessionSub = "sub"
// PlatformWeb is the source-platform tag for messages that originate on the Web
// main session (design/16 §4.4). It is both the column default and the value
// assigned when a caller leaves Message.Platform empty.
// PlatformWeb 是源自 Web 主会话的消息所用的来源平台标签
// （design/16 §4.4）。它既是该列的默认值，也是调用方未设置
// Message.Platform 时赋的值。
PlatformWeb = "web"
)
// MainSessionID is the fixed id of the one main session (design/16 §2.1). Sub session
// ids are MainSessionID + ":" + uuid.
// MainSessionID 是那个唯一主会话的固定 id（design/16 §2.1）。子会话 id 为
// MainSessionID + ":" + uuid。
const MainSessionID = "web"
// defaultPageLimit is the page size used when the caller does not pass one.
// defaultPageLimit 是调用方未传限制时使用的页大小。
const defaultPageLimit = 50
// maxPageLimit bounds a client-supplied limit so a single request cannot drain memory.
// maxPageLimit 为客户端传入的 limit 设上界，使单个请求无法耗尽内存。
const maxPageLimit = 200
// Sentinels distinguishing history package failures. Callers wrap them with %w so
// errors.Is works through the chain.
// 区分 history 包各类失败的哨兵错误。调用方用 %w 包装它们，使 errors.Is 能穿透
// 错误链。
var (
// ErrNilDB is returned when NewStore receives a nil *sql.DB.
// ErrNilDB 在 NewStore 收到 nil 的 *sql.DB 时返回。
ErrNilDB = errors.New("history: nil db")
// ErrImmutableMain is returned when a caller tries to delete the fixed main session.
// ErrImmutableMain 在调用方试图删除固定主会话时返回。
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 在没有 chat_messages 行携带所请求 id 时由
// UpdateMessage/DeleteMessage 返回。
ErrMessageNotFound = errors.New("history: message not found")
)
// Message is one persisted chat message. CreatedAt is a Unix millisecond timestamp and
// doubles as the pagination cursor (design/16 §3.1): pages are ordered newest-first and
// "before" is the created_at of the oldest message on the previous page.
// Message 是一条已持久化的聊天消息。CreatedAt 是 Unix 毫秒时间戳，同时兼任
// 分页游标（design/16 §3.1）：页按最新优先排序，"before" 就是上一页最旧那条
// 消息的 created_at。
type Message struct {
ID string
SessionID string
@@ -80,174 +79,151 @@ type Message struct {
Mood string
Image string
Thinking string
// Platform tags the source platform of a message (design/16 §4.4). The Web main
// session is shared across platforms: messages that originate on the Web carry
// "web", while IM-owner-private messages carry the channel platform (e.g.
// "telegram", "qq-obv11", "weixin-ilink"). An empty Platform defaults to "web" so
// legacy/explicitly-Web writes stay on the Web lane without a separate assignment.
// Platform 标注一条消息的来源平台（design/16 §4.4）。Web 主会话是跨平台
// 共享的：源自 Web 的消息携带 "web"，而主人的 IM 私聊消息携带渠道平台
// （例如 "telegram"、"qq-obv11"、"weixin-ilink"）。Platform 为空时默认
// 为 "web"，使历史/显式 Web 写入无需额外赋值就留在 Web 通道。
Platform string
// DeviceID is a short, client-produced identifier for the concrete device/app
// that sent the message (design/16 §4.5) — e.g. "web:chrome:a1b2c3" for a
// browser, "weixin-ilink:conf0:wx_uid_123" for IM. It complements Platform: two
// clients on the same platform share Platform but differ in DeviceID.
// DeviceID 是发送该消息的具体设备/APP 的短标识，由客户端产出
// （design/16 §4.5）—— 例如浏览器的 "web:chrome:a1b2c3"、IM 的
// "weixin-ilink:conf0:wx_uid_123"。它与 Platform 互补：同一平台上的两个
// 客户端共享 Platform，但 DeviceID 不同。
DeviceID string
// SenderName is the human-readable display name of the message's sender
// (design/16 §4.6). It is set for third-party messages (group chats and
// stranger private chats) so the agent and the IM adapter log page can label
// who is speaking; it is intentionally blank for the owner's private chat on
// the main session (the owner is never labeled). It is display metadata only —
// identity is never decided from this field.
// SenderName 是消息发送者给人看的显示名（design/16 §4.6）。它为第三方
// 消息（群聊与陌生人私聊）设置，使 agent 与 IM 适配器日志页能标注说话者
// 是谁；对主会话上主人的私聊它刻意留空（主人从不被标注）。它只是展示
// 元数据 —— 身份绝不由该字段判定。
SenderName string
// AdapterID is the adapter (platform + account) registration name of the IM
// source that produced the message, e.g. "kook:3bef..." for a multi-account
// channels.json registration or a bare platform name (e.g. "kook") when the
// account comes from env. IM adapter-originated messages carry it; the Web main
// session leaves it empty, so it is always '' for Web messages.
// AdapterID 是产出该消息的 IM 来源的适配器（平台 + 账号）注册名，例如
// 多账号 channels.json 注册的 "kook:3bef..."，或账号来自环境变量时的裸
// 平台名（例如 "kook"）。IM 适配器来源的消息携带它；Web 主会话留空，
// 因此对 Web 消息它恒为空。
AdapterID string
// PersonaID is the role that SPOKE this message (design/22 §7-5). A session
// may switch roles while keeping its context, so the authoring role is recorded
// per message and the context/UI can tell "who said the Nth turn". Empty means
// "inherit the current global default role" — the pre-multi-character rows and
// any message written without an explicit role, so they read exactly as before.
// It is display/attribution metadata only: identity and permissions are decided
// by the channel actor metadata (project red line).
// PersonaID 是说出这条消息的角色（design/22 §7-5）。一个会话可以在保留
// 上下文的同时切换角色，因此作者角色按消息记录，上下文/UI 才能分辨
// 「第 N 个回合是谁说的」。为空意味着「继承当前全局默认角色」—— 多角色
// 之前的行、以及任何未显式指定角色写入的消息，因此它们读起来与以往完全
// 一致。它只是展示/归属元数据：身份与权限由渠道 actor 元数据决定
// （项目红线）。
PersonaID string
CreatedAt int64
}
// SessionMeta is the wire-facing metadata of one persistent session.
// SessionMeta 是一个持久化会话面向线上的元数据。
type SessionMeta struct {
ID string
Type string // "main" | "sub"
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 把会话浮到 ListSessions 顶部。它只是展示/排序元数据；身份与权限
// 绝不由它推导。
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;
// identity and permissions never derive from it.
// LastMessage 是会话最新消息的纯展示预览，由 ListSessions 在同一次查询中
// 填充。没有消息的会话为 nil。客户端用它渲染对话行，无需逐会话请求；
// 身份与权限绝不由它推导。
LastMessage *MessageSummary
// UnreadCount is the number of messages newer than the session's read cursor
// (design/16 §4.2, D4), computed by ListSessions in the same query. The cursor
// is session-scoped and single-owner: reading on any one end marks the session
// read for every end of the account. Like LastMessage it is display-only —
// identity and permissions never derive from it.
// UnreadCount 是比会话读游标更新的消息数（design/16 §4.2，D4），由
// ListSessions 在同一次查询中算出。游标是会话作用域且单归属：在任一端
// 已读即为该账号的每一端把该会话标为已读。与 LastMessage 一样，它只是
// 展示用 —— 身份与权限绝不由它推导。
UnreadCount int
// PersonaID is the role this session belongs to (design/22 §2/§4.1). It is the
// single source of truth for "which role answers in this conversation": the loop
// resolves memory scope, system prompt, emotion and thinking budget from it. Empty
// means "inherit the current global default role" (owner.yaml:defaultPersona), so
// every pre-existing session and any session created without an explicit role
// keeps the pre-multi-character behavior (design/22 §4.7) and still follows a
// default-role change (design/22 §7-6).
// PersonaID 是该会话所属的角色（design/22 §2/§4.1）。它是「这个对话里由
// 哪个角色应答」的唯一事实来源：循环据此解析记忆作用域、系统提示词、
// 情绪与思考预算。为空意味着「继承当前全局默认角色」
// （owner.yaml:defaultPersona），因此每个既有会话、以及任何未显式指定
// 角色创建的会话都保持多角色之前的行为（design/22 §4.7），并且仍跟随
// 默认角色变更（design/22 §7-6）。
PersonaID string
}
// HistoryStore abstracts the chat-history store so callers (the gateway) and tests can
// hold an interface rather than a concrete *Store. It is deliberately kept to the calls
// the runtime-level consumers (channelbridge, backthink) actually make: the D4 read
// cursor (MarkSessionRead) is declared on the consumer-side interface in
// internal/services/gateway (contracts.go) instead, so a narrower store fake elsewhere
// does not have to implement a cursor it never advances. *Store satisfies both.
// HistoryStore 抽象聊天历史存储，使调用方（网关）与测试可以持有接口而不必持有
// 具体的 *Store。它刻意只保留运行时层消费者（channelbridge、backthink）实际
// 会做的调用：D4 读游标（MarkSessionRead）改为声明在消费者侧的接口里
// （internal/services/gateway 的 contracts.go），这样别处更窄的存储替身不必
// 实现一个它从不推进的游标。*Store 同时满足两者。
type HistoryStore interface {
// Append persists msg, assigning an id and timestamp when the caller omitted them.
// Append 持久化 msg，在调用方省略时分配 id 与时间戳。
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 像 Append 一样持久化 msg，但返回完整的已存消息（含分配的
// id/时间戳），使调用方能广播它做跨端同步。
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). platform
// is an optional source-platform filter (design/16 §4.4): when non-empty only
// messages carrying that platform are returned; when empty all platforms are
// returned (the Web client requests the full main session, an IM adapter asks for
// its own platform only).
// List 按最新优先返回 sessionID 的至多 limit 条消息。before 是毫秒时间戳
// 游标：非零时只返回早于 before 的消息（不含边界，与前端 "before" 语义
// 一致）。platform 是可选的来源平台过滤（design/16 §4.4）：非空时只返回
// 携带该平台的消息；为空时返回全部平台（Web 客户端请求完整主会话，IM
// 适配器只请求自己的平台）。
List(ctx context.Context, sessionID string, before int64, limit int, platform string) ([]Message, error)
// ListAfter returns up to limit messages for sessionID strictly newer than after
// (created_at > after) in oldest-first order, so a client that reconnects can pull
// the messages it missed forward from the newest createdAt it has already seen.
// platform filters as in List. limit is clamped to [1, maxPageLimit].
// ListAfter 按最旧优先返回 sessionID 中严格新于 after（created_at >
// after）的至多 limit 条消息，使重连的客户端能从自己已见过的最新
// createdAt 向前拉取错过的消息。platform 的过滤同 List。limit 钳制到
// [1, maxPageLimit]。
ListAfter(ctx context.Context, sessionID string, after int64, limit int, platform string) ([]Message, error)
// Recent returns the most recent n messages for sessionID in oldest-first order,
// for WS replay / context tail usage.
// Recent 按最旧优先返回 sessionID 最近的 n 条消息，供 WS 回放 / 上下文
// 尾部使用。
Recent(ctx context.Context, sessionID string, n int) ([]Message, error)
// ListPlatformLog returns up to limit messages for an IM platform across every
// non-main (isolated) session, newest first, for the adapter log page (design/16
// §4.6 §4). It excludes the fixed main web session, so the platform's non-owner
// message stream (groups + stranger private chats) is surfaced without the
// owner-private mirror. before is a millisecond cursor; 0 means newest page.
// ListPlatformLog 按最新优先返回某个 IM 平台跨所有非主（隔离）会话的至多
// limit 条消息，供适配器日志页使用（design/16 §4.6 §4）。它排除固定主 Web
// 会话，从而在不带主人私聊镜像的情况下浮现该平台的非主人消息流
// （群聊 + 陌生人私聊）。before 是毫秒游标；0 表示最新一页。
ListPlatformLog(ctx context.Context, platform string, before int64, limit int) ([]Message, error)
// ListAdapterLog returns up to limit messages for a single IM adapter (platform +
// account registration name, e.g. "kook:3bef..."), newest first, for the
// per-adapter log page. Unlike ListPlatformLog it does NOT exclude the main web
// session: an owner-private IM chat lives in the main session but still carries
// the adapter_id, so a per-adapter log includes the owner mirror. before is a
// millisecond cursor; 0 means the newest page. An empty adapterID returns an
// empty slice.
// ListAdapterLog 按最新优先返回单个 IM 适配器（平台 + 账号注册名，例如
// "kook:3bef..."）的至多 limit 条消息，供按适配器的日志页使用。与
// ListPlatformLog 不同，它不排除主 Web 会话：主人的 IM 私聊住在主会话里
// 但仍携带 adapter_id，因此按适配器的日志包含主人镜像。before 是毫秒
// 游标；0 表示最新一页。adapterID 为空时返回空切片。
ListAdapterLog(ctx context.Context, adapterID string, before int64, limit int) ([]Message, error)
// ListAllLog returns up to limit messages across every IM adapter source
// (adapter_id != ''), newest first, for the adapter overview page. before is a
// millisecond cursor; 0 means the newest page.
// ListAllLog 按最新优先返回跨所有 IM 适配器来源（adapter_id 非空）的至多
// limit 条消息，供适配器总览页使用。before 是毫秒游标；0 表示最新一页。
ListAllLog(ctx context.Context, before int64, limit int) ([]Message, error)
// DeleteSession removes a sub session and all its messages. The main session is
// immutable and returns ErrImmutableMain.
// DeleteSession 删除一个子会话及其全部消息。主会话不可变，返回
// 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 按最新优先返回 sessionID 中内容包含 query 的至多 limit 条消息
// （ASCII 大小写不敏感的 LIKE，%/_/\ 已转义）。before 与 List 是同一个
// 毫秒游标；limit 钳制到 [1, maxPageLimit]。空 query 返回空切片（调用方
// 退回 List 做普通翻页）。Search 始终限定在单个会话内，因此隔离的
// 群聊/陌生人会话绝不浮现在另一个会话的结果中。
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 替换 id 所指消息的内容并返回更新后的消息（与 AppendFull
// 一样，使调用方能无需二次读取就广播它）。只有 content 变化；role、时间
// 戳、platform 保持已存值。未知 id 返回 ErrMessageNotFound。
UpdateMessage(ctx context.Context, id, content string) (Message, error)
// DeleteMessage removes a single message. An unknown id returns
// ErrMessageNotFound.
// DeleteMessage 删除单条消息。未知 id 返回 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 设置会话的显示标题。主会话与子会话都可重命名（标题只是
// 展示元数据）；未知 id 返回 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 置顶或取消置顶一个会话。置顶只是展示/排序元数据；主会话与
// 子会话都可置顶。未知 id 返回 ErrSessionNotFound。
SetPinned(ctx context.Context, sessionID string, pinned bool) error
// NewSubSession creates a new sub session and returns its id (MainSessionID:uuid).
// It binds no explicit role, so the new session inherits the global default
// (persona_id = ''); *Store additionally offers NewSubSessionFor for the
// role-bound variant (design/22 §4.1), which this narrow consumer-side interface
// deliberately omits because neither channelbridge nor backthink ever creates a
// session.
// NewSubSession 创建一个子会话并返回其 id（MainSessionID:uuid）。它不绑定
// 显式角色，因此新会话继承全局默认（persona_id 为空）；*Store 另提供
// NewSubSessionFor 这个绑定角色的变体（design/22 §4.1），本窄接口刻意
// 省略它，因为 channelbridge 与 backthink 都不创建会话。
NewSubSession(ctx context.Context, ownerID string) (string, error)
// ListSessions returns pinned sessions first, then the main session, then every
// sub session oldest first.
// ListSessions 先返回置顶会话，再返回主会话，最后返回每个子会话（最旧
// 优先）。
ListSessions(ctx context.Context) ([]SessionMeta, error)
}
// Store is the SQLite-backed chat-history store. It owns the chat_sessions and
// chat_messages tables. Concurrency is delegated to *sql.DB (safe for concurrent use),
// so Store holds no further lock. Every query is parameterized and reads list columns
// explicitly (no SELECT *); reads take a context.
// Store 是基于 SQLite 的聊天历史存储。它拥有 chat_sessions 与 chat_messages
// 两张表。并发交给 *sql.DB（可安全并发使用），因此 Store 不再持有额外的锁。
// 每条查询都参数化，读取时显式列出列（不用 SELECT *）；读取都接受 context。
type Store struct {
db *sql.DB
log *slog.Logger
}
// rowScanner is satisfied by both *sql.Row and *sql.Rows, so a single scanMessage
// helper serves List and Recent.
// rowScanner 由 *sql.Row 与 *sql.Rows 同时满足，因此单个 scanMessage 辅助函数
// 就能服务 List 与 Recent。
type rowScanner interface {
Scan(dest ...any) error
}
// NewStore builds a Store on db, ensuring the chat_sessions/chat_messages schema exists
// and that the fixed main session row is present. The DDL mirrors the 0003 migration;
// it is idempotent so the store is self-contained and usable from any *sql.DB, matching
// the memory and session packages. db must be live; nil returns ErrNilDB. log may be nil.
// NewStore 在 db 上构建一个 Store，确保 chat_sessions/chat_messages schema 存在
// 且固定主会话行在位。该 DDL 与 0003 迁移一致；它是幂等的，因此存储自足、可从
// 任意 *sql.DB 使用，与 memory 和 session 包一致。db 必须可用；nil 返回
// ErrNilDB。log 可以为 nil。
func NewStore(ctx context.Context, db *sql.DB, log *slog.Logger) (*Store, error) {
if db == nil {
return nil, ErrNilDB
@@ -269,24 +245,23 @@ func NewStore(ctx context.Context, db *sql.DB, log *slog.Logger) (*Store, error)
return s, nil
}
// 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. Callers that
// need the generated id/timestamp back should use AppendFull instead.
// Append 持久化 msg，在调用方把 id/CreatedAt 留空/留零时分配新的 id 与现在的
// 毫秒时间戳。它返回包装了操作名的错误。需要拿回生成的 id/时间戳的调用方应
// 改用 AppendFull。
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.
// AppendFull 像 Append 一样持久化 msg，但返回完整的已存消息 —— 即调用方留空/
// 留零时存储分配的 id 与 CreatedAt —— 使调用方能广播它做跨端实时同步
// （design/16 §4.2），无需二次读取。
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.
// insert 是 Append/AppendFull 共用的主体。它在调用方把 id/CreatedAt 留空/留零时
// 分配新的 id 与现在的毫秒时间戳，然后插入该行并返回得到的消息。
func (s *Store) insert(ctx context.Context, msg Message) (Message, error) {
if msg.ID == "" {
id, err := newID()
@@ -315,13 +290,11 @@ func (s *Store) insert(ctx context.Context, msg Message) (Message, error) {
return msg, nil
}
// List returns up to limit messages for sessionID, newest first. When before is nonzero
// it bounds the query to messages strictly older than before, so a client can page upward
// by passing the oldest message's created_at from the previous page. When platform is
// non-empty it further restricts the page to messages carrying that source platform
// (design/16 §4.4: the Web client omits platform for the full main session, an IM
// adapter passes its own platform to see only its lane). The returned slice is non-nil.
// limit is clamped to [1, maxPageLimit].
// List 按最新优先返回 sessionID 的至多 limit 条消息。before 非零时把查询限制为
// 严格早于 before 的消息，使客户端可以传入上一页最旧那条消息的 created_at 向上
// 翻页。platform 非空时把该页进一步限制为携带该来源平台的消息（design/16 §4.4：
// Web 客户端省略 platform 以拿到完整主会话，IM 适配器传入自己的平台只看自己的
// 通道）。返回切片非 nil。limit 钳制到 [1, maxPageLimit]。
func (s *Store) List(ctx context.Context, sessionID string, before int64, limit int, platform string) ([]Message, error) {
limit = clampLimit(limit)
query := `SELECT id, session_id, role, content, mode, mood, image, thinking, platform, device_id, sender_name, adapter_id, persona_id, created_at
@@ -358,11 +331,10 @@ func (s *Store) List(ctx context.Context, sessionID string, before int64, limit
return msgs, nil
}
// ListPlatformLog returns up to limit messages for platform across every non-main
// (isolated) session, newest first. Main-session messages are excluded so only the
// platform's own message stream (groups + stranger private chats) is surfaced to the
// adapter log page (design/16 §4.6 §4). before is a millisecond cursor; when nonzero
// only strictly older messages are returned. The returned slice is non-nil.
// ListPlatformLog 按最新优先返回 platform 跨所有非主（隔离）会话的至多 limit
// 条消息。主会话消息被排除，因此只有该平台自己的消息流（群聊 + 陌生人私聊）
// 浮现到适配器日志页（design/16 §4.6 §4）。before 是毫秒游标；非零时只返回
// 严格更旧的消息。返回切片非 nil。
func (s *Store) ListPlatformLog(ctx context.Context, platform string, before int64, limit int) ([]Message, error) {
limit = clampLimit(limit)
query := `SELECT id, session_id, role, content, mode, mood, image, thinking, platform, device_id, sender_name, adapter_id, persona_id, created_at
@@ -395,13 +367,11 @@ func (s *Store) ListPlatformLog(ctx context.Context, platform string, before int
return msgs, nil
}
// ListAdapterLog returns up to limit messages for a single IM adapter (platform +
// account registration name, e.g. "kook:3bef..."), newest first, for the per-adapter
// log page. It does NOT exclude the main web session: an owner-private IM chat lives
// in the main session but still carries the adapter_id, so a per-adapter log includes
// the owner mirror. An empty adapterID returns an empty (non-nil) slice. before is a
// millisecond cursor; when nonzero only strictly older messages are returned. The
// returned slice is non-nil.
// ListAdapterLog 按最新优先返回单个 IM 适配器（平台 + 账号注册名，例如
// "kook:3bef..."）的至多 limit 条消息，供按适配器的日志页使用。它不排除主 Web
// 会话：主人的 IM 私聊住在主会话里但仍携带 adapter_id，因此按适配器的日志包含
// 主人镜像。adapterID 为空时返回空（非 nil）切片。before 是毫秒游标；非零时只
// 返回严格更旧的消息。返回切片非 nil。
func (s *Store) ListAdapterLog(ctx context.Context, adapterID string, before int64, limit int) ([]Message, error) {
limit = clampLimit(limit)
if adapterID == "" {
@@ -437,10 +407,9 @@ func (s *Store) ListAdapterLog(ctx context.Context, adapterID string, before int
return msgs, nil
}
// ListAllLog returns up to limit messages across every IM adapter source
// (adapter_id != ''), newest first, for the adapter overview page. before is a
// millisecond cursor; when nonzero only strictly older messages are returned. The
// returned slice is non-nil.
// ListAllLog 按最新优先返回跨所有 IM 适配器来源（adapter_id 非空）的至多 limit
// 条消息，供适配器总览页使用。before 是毫秒游标；非零时只返回严格更旧的消息。
// 返回切片非 nil。
func (s *Store) ListAllLog(ctx context.Context, before int64, limit int) ([]Message, error) {
limit = clampLimit(limit)
query := `SELECT id, session_id, role, content, mode, mood, image, thinking, platform, device_id, sender_name, adapter_id, persona_id, created_at
@@ -473,8 +442,8 @@ func (s *Store) ListAllLog(ctx context.Context, before int64, limit int) ([]Mess
return msgs, nil
}
// Recent returns the most recent n messages for sessionID in oldest-first order (the
// tail-most window), for WS replay / context tail. The returned slice is non-nil.
// Recent 按最旧优先返回 sessionID 最近的 n 条消息（最靠尾部的那段窗口），供
// WS 回放 / 上下文尾部使用。返回切片非 nil。
func (s *Store) Recent(ctx context.Context, sessionID string, n int) ([]Message, error) {
if n < 1 {
n = defaultPageLimit
@@ -486,8 +455,7 @@ func (s *Store) Recent(ctx context.Context, sessionID string, n int) ([]Message,
}
defer func() { _ = rows.Close() }()
// Recent returns newest-last so the window is in chronological order; build it and
// reverse in place.
// Recent 让最新的排在最后，使窗口处于时间顺序；先按查询顺序构建再原地反转。
msgs := make([]Message, 0)
for rows.Next() {
m, err := scanMessage(rows)
@@ -505,8 +473,8 @@ func (s *Store) Recent(ctx context.Context, sessionID string, n int) ([]Message,
return msgs, nil
}
// DeleteSession removes a sub session and all its messages in one transaction. The fixed
// main session is immutable and returns ErrImmutableMain (design/16 §6).
// DeleteSession 在一个事务中删除一个子会话及其全部消息。固定主会话不可变，
// 返回 ErrImmutableMain（design/16 §6）。
func (s *Store) DeleteSession(ctx context.Context, sessionID string) error {
if sessionID == MainSessionID {
return ErrImmutableMain
@@ -529,17 +497,16 @@ func (s *Store) DeleteSession(ctx context.Context, sessionID string) error {
return nil
}
// NewSubSession creates a sub session with no explicit role and returns its id
// (MainSessionID:uuid). The new session therefore inherits the global default role
// (persona_id = ''); use NewSubSessionFor to bind a role at creation time. ownerID
// is accepted for interface completeness (the Web owner is identified by JWT, not
// stored per session); it is logged at debug and not persisted.
// NewSubSession 创建一个不绑定显式角色的子会话并返回其 id
// （MainSessionID:uuid）。新会话因此继承全局默认角色（persona_id 为空）；要在
// 创建时绑定角色请用 NewSubSessionFor。ownerID 为接口完整性而接受（Web 主人
// 由 JWT 识别，不按会话存储）；它只以 debug 级别记日志，不被持久化。
func (s *Store) NewSubSession(ctx context.Context, ownerID string) (string, error) {
return s.NewSubSessionFor(ctx, ownerID, "")
}
// ensureMainSession inserts the fixed main session row when it is absent, so ListSessions
// always reports the main session even before any message is written.
// ensureMainSession 在固定主会话行缺失时插入它，使 ListSessions 在任何消息写入
// 之前也能报告出主会话。
func (s *Store) ensureMainSession(ctx context.Context) error {
_, err := s.db.ExecContext(ctx, `INSERT OR IGNORE INTO chat_sessions (id, type, title, created_at)
VALUES (?, ?, ?, ?)`, MainSessionID, SessionMain, "", time.Now().UnixMilli())
@@ -549,7 +516,7 @@ func (s *Store) ensureMainSession(ctx context.Context) error {
return nil
}
// scanMessage reads one chat_messages row. message columns are scanned positionally.
// scanMessage 读取一行 chat_messages。消息各列按位置扫描。
func scanMessage(sc rowScanner) (Message, error) {
var m Message
var mode, mood, platform, deviceID, senderName, adapterID string
@@ -560,8 +527,8 @@ func scanMessage(sc rowScanner) (Message, error) {
return m, nil
}
// clampLimit bounds limit to [1, maxPageLimit]; a caller-supplied 0 or negative falls back
// to defaultPageLimit.
// clampLimit 把 limit 钳制到 [1, maxPageLimit]；调用方传入的 0 或负数回退到
// defaultPageLimit。
func clampLimit(limit int) int {
if limit < 1 {
return defaultPageLimit
@@ -572,8 +539,8 @@ func clampLimit(limit int) int {
return limit
}
// newID returns a 128-bit cryptographically random id, hex-encoded. It avoids a UUID
// dependency so the package stays self-contained.
// newID 返回一个 128 位密码学随机的 id，以十六进制编码。它避免引入 UUID 依赖，
// 使本包保持自足。
func newID() (string, error) {
b := make([]byte, 16)
if _, err := rand.Read(b); err != nil {
@@ -582,7 +549,7 @@ func newID() (string, error) {
return hex.EncodeToString(b), nil
}
// discardLogger returns log if non-nil, otherwise a logger that writes nowhere.
// discardLogger 在 log 非 nil 时返回 log，否则返回一个什么都不写的日志器。
func discardLogger(log *slog.Logger) *slog.Logger {
if log != nil {
return log
@@ -590,9 +557,8 @@ func discardLogger(log *slog.Logger) *slog.Logger {
return slog.New(slog.NewTextHandler(io.Discard, nil))
}
// Schema DDL. The 0003 migration in internal/db is the authoritative mechanism for
// domain tables, but it is intentionally also re-issued here idempotently so the store is
// self-contained and usable from any *sql.DB (matching the memory and session packages).
// Schema DDL。internal/db 里的 0003 迁移是领域表的权威机制，但这里刻意再幂等
// 地发出一次，使存储自足、可从任意 *sql.DB 使用（与 memory 和 session 包一致）。
const createSessionsTable = `
CREATE TABLE IF NOT EXISTS chat_sessions (
id TEXT PRIMARY KEY,
internal/runtime/history/store_test.go
+39 -42
View File
@@ -11,12 +11,12 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/db"
)
// testLogger returns a logger that writes nowhere, keeping test output clean.
// testLogger 返回一个不写任何地方的日志器，保持测试输出干净。
func testLogger() *slog.Logger {
return slog.New(slog.NewTextHandler(io.Discard, nil))
}
// newStore opens an isolated in-memory DB and returns a Store on it.
// newStore 打开一个隔离的内存库并在其上返回 Store。
func newStore(t *testing.T) *Store {
t.Helper()
ctx := context.Background()
@@ -58,11 +58,11 @@ func TestAppendAndListNewestFirst(t *testing.T) {
if len(msgs) != 3 {
t.Fatalf("len = %d, want 3", len(msgs))
}
// Newest first.
// 最新优先。
if msgs[0].CreatedAt != 3000 || msgs[1].CreatedAt != 2000 || msgs[2].CreatedAt != 1000 {
t.Fatalf("order = %+v, want [3000 2000 1000]", []int64{msgs[0].CreatedAt, msgs[1].CreatedAt, msgs[2].CreatedAt})
}
// Id/timestamp assigned when the caller omits them.
// 调用方省略时分配 id/时间戳。
empty := Message{SessionID: MainSessionID, Role: RoleAssistant, Content: "ok"}
if err := st.Append(ctx, empty); err != nil {
t.Fatalf("append no ts: %v", err)
@@ -95,7 +95,7 @@ func TestAppendFullReturnsID(t *testing.T) {
t.Fatalf("AppendFull returned %+v, want the stored message unchanged plus id/created_at", full)
}
// The message is actually persisted under the returned id.
// 消息确实以返回的 id 落盘。
msgs, err := st.List(ctx, MainSessionID, 0, 50, "")
if err != nil {
t.Fatalf("list: %v", err)
@@ -104,7 +104,7 @@ func TestAppendFullReturnsID(t *testing.T) {
t.Fatalf("list = %+v, want exactly the persisted message id %q", msgs, full.ID)
}
// A caller-supplied id/timestamp is preserved, not regenerated.
// 调用方传入的 id/时间戳被保留，而不是重新生成。
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)
@@ -119,8 +119,7 @@ func TestAppendFullListPlatformRoundTrip(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// An IM owner-private message carries its channel platform through the round
// trip: AppendFull → List.
// 一条 IM 主人私聊消息在 AppendFull → List 往返中携带它的渠道平台。
full, err := st.AppendFull(ctx, Message{SessionID: MainSessionID, Role: RoleUser, Content: "从微信来", Platform: "weixin-ilink"})
if err != nil {
t.Fatalf("append full: %v", err)
@@ -136,7 +135,7 @@ func TestAppendFullListPlatformRoundTrip(t *testing.T) {
t.Fatalf("list round trip = %+v, want platform weixin-ilink", msgs)
}
// A message without an explicit platform defaults to the web lane.
// 未显式指定平台的消息默认为 web 通道。
web, err := st.AppendFull(ctx, Message{SessionID: MainSessionID, Role: RoleAssistant, Content: "ok"})
if err != nil {
t.Fatalf("append web default: %v", err)
@@ -151,8 +150,8 @@ func TestAppendFullListDeviceIDRoundTrip(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// A Web message tagged with a browser deviceID survives the AppendFull → List
// round trip (design/16 §4.5).
// 一条带浏览器 deviceID 的 Web 消息活过 AppendFull → List 往返
// （design/16 §4.5）。
full, err := st.AppendFull(ctx, Message{SessionID: MainSessionID, Role: RoleUser, Content: "来自浏览器", DeviceID: "web:chrome:a1b2c3"})
if err != nil {
t.Fatalf("append full: %v", err)
@@ -168,7 +167,7 @@ func TestAppendFullListDeviceIDRoundTrip(t *testing.T) {
t.Fatalf("list round trip = %+v, want DeviceID web:chrome:a1b2c3", msgs)
}
// Recent (WS replay / context tail) reads the same device_id column.
// Recent（WS 回放 / 上下文尾部）读同一个 device_id 列。
recent, err := st.Recent(ctx, MainSessionID, 5)
if err != nil {
t.Fatalf("recent: %v", err)
@@ -177,7 +176,7 @@ func TestAppendFullListDeviceIDRoundTrip(t *testing.T) {
t.Fatalf("recent = %+v, want DeviceID web:chrome:a1b2c3", recent)
}
// A message without an explicit deviceID persists the column default ('').
// 未显式指定 deviceID 的消息持久化列默认值（空）。
om, err := st.AppendFull(ctx, Message{SessionID: MainSessionID, Role: RoleAssistant, Content: "ok"})
if err != nil {
t.Fatalf("append empty device: %v", err)
@@ -192,7 +191,7 @@ func TestListPlatformFilter(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// Seed across the web lane (explicit + default) and one IM lane.
// 跨 web 通道（显式 + 默认）与一条 IM 通道播种。
for _, m := range []Message{
{SessionID: MainSessionID, Role: RoleUser, Content: "web1", Platform: PlatformWeb, CreatedAt: 1000},
{SessionID: MainSessionID, Role: RoleUser, Content: "tg", Platform: "telegram", CreatedAt: 2000},
@@ -203,7 +202,7 @@ func TestListPlatformFilter(t *testing.T) {
}
}
// No platform filter → all three (the empty-platform message defaulted to web).
// 不带平台过滤 → 三条全出（未指定平台的那条在插入时默认为 web）。
all, err := st.List(ctx, MainSessionID, 0, 50, "")
if err != nil {
t.Fatalf("list all: %v", err)
@@ -212,7 +211,7 @@ func TestListPlatformFilter(t *testing.T) {
t.Fatalf("all = %d, want 3", len(all))
}
// Filter to the IM lane → only its message.
// 过滤到 IM 通道 → 只有它的消息。
tg, err := st.List(ctx, MainSessionID, 0, 50, "telegram")
if err != nil {
t.Fatalf("list telegram: %v", err)
@@ -221,8 +220,7 @@ func TestListPlatformFilter(t *testing.T) {
t.Fatalf("telegram page = %+v, want [tg]", tg)
}
// Filter to the web lane → web1 + web2 (the one left without an explicit
// platform defaulted to web on insert).
// 过滤到 web 通道 → web1 + web2（那条未显式指定平台的在插入时默认为 web）。
web, err := st.List(ctx, MainSessionID, 0, 50, PlatformWeb)
if err != nil {
t.Fatalf("list web: %v", err)
@@ -231,7 +229,7 @@ func TestListPlatformFilter(t *testing.T) {
t.Fatalf("web page = %d, want 2 (%+v)", len(web), web)
}
// The filter composes with the before cursor.
// 过滤与 before 游标可组合。
older, err := st.List(ctx, MainSessionID, 2000, 50, PlatformWeb)
if err != nil {
t.Fatalf("list web before: %v", err)
@@ -252,7 +250,7 @@ func TestListPaginationBefore(t *testing.T) {
}
}
// First page: newest 2.
// 第一页：最新 2 条。
page, err := st.List(ctx, MainSessionID, 0, 2, "")
if err != nil {
t.Fatalf("first page: %v", err)
@@ -260,7 +258,7 @@ func TestListPaginationBefore(t *testing.T) {
if len(page) != 2 || page[0].CreatedAt != 6000 || page[1].CreatedAt != 5000 {
t.Fatalf("first page = %+v, want [6000 5000]", page)
}
// Cursor on the page's oldest (5000) → older page [4000 3000].
// 游标落在该页最旧那条（5000）→ 更旧的一页 [4000 3000]。
next, err := st.List(ctx, MainSessionID, page[1].CreatedAt, 2, "")
if err != nil {
t.Fatalf("next page: %v", err)
@@ -268,7 +266,7 @@ func TestListPaginationBefore(t *testing.T) {
if len(next) != 2 || next[0].CreatedAt != 4000 || next[1].CreatedAt != 3000 {
t.Fatalf("next page = %+v, want [4000 3000]", next)
}
// Past the start → empty.
// 越过起点 → 空。
tail, err := st.List(ctx, MainSessionID, 1000, 50, "")
if err != nil {
t.Fatalf("tail: %v", err)
@@ -302,7 +300,7 @@ func TestNewSubSessionAndListSessions(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// Main session exists by default.
// 主会话默认存在。
sessions, err := st.ListSessions(ctx)
if err != nil {
t.Fatalf("list sessions initial: %v", err)
@@ -362,7 +360,7 @@ func TestDeleteSession(t *testing.T) {
t.Fatalf("sessions after delete = %+v, want [main]", sessions)
}
// Main session is immutable.
// 主会话不可变。
if err := st.DeleteSession(ctx, MainSessionID); !errors.Is(err, ErrImmutableMain) {
t.Fatalf("delete main err = %v, want ErrImmutableMain", err)
}
@@ -373,21 +371,21 @@ func TestSenderNameRoundTripOnListRecentAndPlatformLog(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// An isolated group session carries the sender display name (design/16 §4.6).
// 隔离的群聊会话携带发送者显示名（design/16 §4.6）。
groupID := "sess-g"
if err := st.Append(ctx, Message{SessionID: groupID, Role: RoleUser, Content: "hello all", Platform: "telegram", SenderName: "张三", DeviceID: "telegram:-20:9", CreatedAt: 1000}); err != nil {
t.Fatalf("append group msg: %v", err)
}
// An owner-private message on the main session carries no sender name.
// 主会话上主人的私聊消息不携带发送者名。
if err := st.Append(ctx, Message{SessionID: MainSessionID, Role: RoleUser, Content: "hi", Platform: "telegram", CreatedAt: 900}); err != nil {
t.Fatalf("append main msg: %v", err)
}
// An unrelated platform on the main session should not leak into the log.
// 主会话上一个无关平台不得泄进该日志。
if err := st.Append(ctx, Message{SessionID: MainSessionID, Role: RoleUser, Content: "web msg", Platform: "web", CreatedAt: 800}); err != nil {
t.Fatalf("append web msg: %v", err)
}
// List reads the sender_name back.
// List 读回 sender_name。
ls, err := st.List(ctx, groupID, 0, 50, "")
if err != nil {
t.Fatalf("list: %v", err)
@@ -396,7 +394,7 @@ func TestSenderNameRoundTripOnListRecentAndPlatformLog(t *testing.T) {
t.Fatalf("list = %+v, want SenderName 张三", ls)
}
// Recent reads it too.
// Recent 也读它。
rs, err := st.Recent(ctx, groupID, 5)
if err != nil {
t.Fatalf("recent: %v", err)
@@ -405,8 +403,8 @@ func TestSenderNameRoundTripOnListRecentAndPlatformLog(t *testing.T) {
t.Fatalf("recent = %+v, want SenderName 张三", rs)
}
// Platform log surfaces only the isolated (non-main) messages of the platform,
// newest first, excluding the owner-private mirror on the main session.
// 平台日志只浮现该平台的隔离（非主）消息，最新优先，排除主会话上的主人
// 私聊镜像。
log, err := st.ListPlatformLog(ctx, "telegram", 0, 50)
if err != nil {
t.Fatalf("platform log: %v", err)
@@ -418,7 +416,7 @@ func TestSenderNameRoundTripOnListRecentAndPlatformLog(t *testing.T) {
t.Fatalf("platform log[0] = %+v, want group session with SenderName 张三", log[0])
}
// A platform with only main-session messages yields an empty log.
// 只有主会话消息的平台得到空日志。
if log, err := st.ListPlatformLog(ctx, "web", 0, 50); err != nil || len(log) != 0 {
t.Fatalf("web platform log = %+v, err=%v; want empty", log, err)
}
@@ -429,8 +427,8 @@ func TestAdapterLogFiltersByAdapter(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// Seed across two adapters, an empty-adapter web message, and a main-session
// owner-private mirror that still carries the adapter (design/16 §4.4).
// 跨两个适配器、一条空适配器的 web 消息，以及一条仍携带适配器的主会话
// 主人私聊镜像播种（design/16 §4.4）。
for _, m := range []Message{
{SessionID: MainSessionID, Role: RoleUser, Content: "kook-owner", Platform: "kook", AdapterID: "kook:3bef", CreatedAt: 1000},
{SessionID: "sess-g1", Role: RoleUser, Content: "kook-group", Platform: "kook", AdapterID: "kook:3bef", SenderName: "张三", CreatedAt: 2000},
@@ -442,8 +440,7 @@ func TestAdapterLogFiltersByAdapter(t *testing.T) {
}
}
// Per-adapter log includes BOTH the owner-private main mirror and the group
// message, newest first.
// 按适配器日志同时包含主人私聊的主会话镜像与群聊消息，最新优先。
kook, err := st.ListAdapterLog(ctx, "kook:3bef", 0, 50)
if err != nil {
t.Fatalf("adapter log kook:3bef: %v", err)
@@ -458,7 +455,7 @@ func TestAdapterLogFiltersByAdapter(t *testing.T) {
t.Fatalf("kook[1] = %+v, want owner mirror on main session", kook[1])
}
// A different adapter yields only its own lane.
// 另一个适配器只得到它自己的通道。
tg, err := st.ListAdapterLog(ctx, "telegram:conf0", 0, 50)
if err != nil {
t.Fatalf("adapter log telegram:conf0: %v", err)
@@ -467,7 +464,7 @@ func TestAdapterLogFiltersByAdapter(t *testing.T) {
t.Fatalf("telegram adapter log = %+v, want [tg-group]", tg)
}
// An unknown / empty adapter yields a non-nil empty slice.
// 未知 / 空适配器得到非 nil 的空切片。
none, err := st.ListAdapterLog(ctx, "kook:unknown", 0, 50)
if err != nil {
t.Fatalf("adapter log unknown: %v", err)
@@ -483,7 +480,7 @@ func TestAdapterLogFiltersByAdapter(t *testing.T) {
t.Fatalf("empty adapter log = %#v, want non-nil empty slice", empty)
}
// The before cursor pages backward through the adapter's stream.
// before 游标在该适配器的消息流中向后翻页。
older, err := st.ListAdapterLog(ctx, "kook:3bef", 2000, 50)
if err != nil {
t.Fatalf("adapter log before: %v", err)
@@ -508,7 +505,7 @@ func TestAllLogSurfacesOnlyAdapterMessages(t *testing.T) {
}
}
// The overview only surfaces IM adapter sources; the web message is excluded.
// 总览只浮现 IM 适配器来源；web 消息被排除。
all, err := st.ListAllLog(ctx, 0, 50)
if err != nil {
t.Fatalf("all log: %v", err)
@@ -519,14 +516,14 @@ func TestAllLogSurfacesOnlyAdapterMessages(t *testing.T) {
if all[0].Content != "tg-group" || all[1].Content != "kook-owner" {
t.Fatalf("all log order = %+v, want [tg-group kook-owner]", all)
}
// The web message never leaks into the adapter overview.
// web 消息绝不泄进适配器总览。
for _, m := range all {
if m.Content == "web-msg" {
t.Fatalf("web message leaked into adapter overview: %+v", m)
}
}
// An empty store yields a non-nil empty slice.
// 空存储得到非 nil 的空切片。
st2 := newStore(t)
e, err := st2.ListAllLog(ctx, 0, 50)
if err != nil {
internal/runtime/history/title.go
+20 -25
View File
@@ -7,30 +7,27 @@ import (
"strings"
)
// This file owns the two session-title paths: auto-naming a session from its first
// user message and an explicit rename. A title is display-only metadata (design/16
// §2.1) and is never used to identify a session, a sender or a permission — identity
// always comes from the channel actor metadata / JWT (project red line).
// 本文件负责两条会话标题路径：从第一条用户消息为会话自动命名，以及显式
// 重命名。标题只是展示元数据（design/16 §2.1），绝不用于标识会话、发送者
// 或权限 —— 身份永远来自渠道 actor 元数据 / JWT（项目红线）。
const (
// autoTitleMaxRunes bounds an auto-generated title so a session list row never
// overflows; a longer first message is truncated with an ellipsis.
// autoTitleMaxRunes 限制自动生成标题的长度，使会话列表行不会溢出；
// 更长的首条消息会被截断并加省略号。
autoTitleMaxRunes = 20
// titleMainFallback and titleSubFallback name a session whose first user
// message carries no text (e.g. an image-only turn), so the session list is
// never nameless.
// titleMainFallback 与 titleSubFallback 用于给首条用户消息没有任何
// 文本的会话（例如纯图片回合）命名，使会话列表不会无名。
titleMainFallback = "主会话"
titleSubFallback = "次级会话"
)
// ErrSessionNotFound is returned by RenameSession when no chat_sessions row carries
// the requested id.
// ErrSessionNotFound 在没有任何 chat_sessions 行携带所请求 id 时由
// RenameSession 返回。
var ErrSessionNotFound = errors.New("history: session not found")
// RenameSession sets the display title of sessionID. Both the fixed main session
// (id "web") and sub sessions may be renamed: renaming is not a destructive identity
// change, unlike deletion. An unknown id returns ErrSessionNotFound. The caller
// validates the title (non-empty, length-bounded); the store persists it verbatim.
// RenameSession 设置 sessionID 的显示标题。固定主会话（id "web"）与子会话
// 都可重命名：与删除不同，重命名不是破坏性的身份变更。未知 id 返回
// ErrSessionNotFound。标题由调用方校验（非空、限长）；存储原样持久化它。
func (s *Store) RenameSession(ctx context.Context, sessionID, title string) error {
res, err := s.db.ExecContext(ctx, `UPDATE chat_sessions SET title = ? WHERE id = ?`, title, sessionID)
if err != nil {
@@ -46,12 +43,11 @@ func (s *Store) RenameSession(ctx context.Context, sessionID, title string) erro
return nil
}
// ensureTitle names a session from its first user message. It is a no-op unless the
// session row exists in chat_sessions, its title is still empty, and no user message
// has been persisted for it yet (so the caller must invoke it before inserting the
// message). A message that is all whitespace falls back to the session-type label.
// The title is display-only metadata, so a failure is logged and swallowed rather
// than failing the message write it accompanies.
// ensureTitle 用第一条用户消息为会话命名。除非该会话行已存在于
// chat_sessions、其标题仍为空、且尚未为它持久化任何用户消息（因此调用方
// 必须在插入消息之前调用它），否则它是空操作。纯空白的消息回退到会话类型
// 标签。标题只是展示元数据，因此失败只记日志并吞掉，而不是让它伴随的
// 消息写入失败。
func (s *Store) ensureTitle(ctx context.Context, sessionID, content string) {
if sessionID == "" {
return
@@ -68,10 +64,9 @@ func (s *Store) ensureTitle(ctx context.Context, sessionID, content string) {
}
}
// deriveTitle turns a user message into a session title: whitespace runs (newlines
// included) collapse to a single space, then the result is truncated to
// autoTitleMaxRunes runes with an ellipsis. A message that is all whitespace yields
// "" so ensureTitle falls back to the session-type label.
// deriveTitle 把一条用户消息变成会话标题：空白串（含换行）折叠为单个空格，
// 再把结果截断到 autoTitleMaxRunes 个 rune 并加省略号。纯空白的消息得到
// 空串，使 ensureTitle 回退到会话类型标签。
func deriveTitle(content string) string {
fields := strings.Fields(content)
if len(fields) == 0 {
internal/runtime/history/title_test.go
+12 -12
View File
@@ -7,7 +7,7 @@ import (
"testing"
)
// titleOf returns the stored title of a session, failing the test when it is absent.
// titleOf 返回某个会话已存储的标题，缺失时使测试失败。
func titleOf(t *testing.T, st *Store, id string) string {
t.Helper()
sessions, err := st.ListSessions(context.Background())
@@ -28,12 +28,12 @@ func TestEnsureTitleFromFirstUserMessage(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// The main session starts nameless.
// 主会话初始无名。
if got := titleOf(t, st, MainSessionID); got != "" {
t.Fatalf("initial main title = %q, want empty", got)
}
// The first user message names it, with whitespace runs collapsed.
// 第一条用户消息为它命名，空白串被折叠。
if _, err := st.AppendFull(ctx, Message{SessionID: MainSessionID, Role: RoleUser, Content: " 你好\n世界 "}); err != nil {
t.Fatalf("append first user: %v", err)
}
@@ -41,7 +41,7 @@ func TestEnsureTitleFromFirstUserMessage(t *testing.T) {
t.Fatalf("main title = %q, want 你好 世界", got)
}
// A later user message does not overwrite the established title.
// 之后的用户消息不会覆盖已确定的标题。
if _, err := st.AppendFull(ctx, Message{SessionID: MainSessionID, Role: RoleUser, Content: "second"}); err != nil {
t.Fatalf("append second user: %v", err)
}
@@ -55,7 +55,7 @@ func TestEnsureTitleTruncatesAndFallsBack(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// A long first user message is truncated to 20 runes plus an ellipsis.
// 过长的首条用户消息被截断到 20 个 rune 并加省略号。
sub, err := st.NewSubSession(ctx, "owner")
if err != nil {
t.Fatalf("new sub: %v", err)
@@ -69,8 +69,8 @@ func TestEnsureTitleTruncatesAndFallsBack(t *testing.T) {
t.Fatalf("sub title = %q, want %q", got, want)
}
// An all-whitespace first message (e.g. an image-only turn) falls back to the
// session-type label, for both a sub and the main session.
// 纯空白的首条消息（例如纯图片回合）回退到会话类型标签，子会话与主会话
// 都是如此。
blank, err := st.NewSubSession(ctx, "owner")
if err != nil {
t.Fatalf("new blank sub: %v", err)
@@ -96,7 +96,7 @@ func TestEnsureTitleOnlyFromFirstUserMessage(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// An assistant message first does not name the session.
// 首条是 assistant 消息不会为会话命名。
sub, err := st.NewSubSession(ctx, "owner")
if err != nil {
t.Fatalf("new sub: %v", err)
@@ -108,7 +108,7 @@ func TestEnsureTitleOnlyFromFirstUserMessage(t *testing.T) {
t.Fatalf("sub title after assistant = %q, want empty", got)
}
// The first user message afterwards still names it.
// 其后的第一条用户消息仍会为它命名。
if _, err := st.AppendFull(ctx, Message{SessionID: sub, Role: RoleUser, Content: "real question"}); err != nil {
t.Fatalf("append user: %v", err)
}
@@ -122,7 +122,7 @@ func TestRenameSession(t *testing.T) {
st := newStore(t)
ctx := context.Background()
// The fixed main session may be renamed (unlike deletion).
// 固定主会话可以重命名（与删除不同）。
if err := st.RenameSession(ctx, MainSessionID, "工作台"); err != nil {
t.Fatalf("rename main: %v", err)
}
@@ -130,7 +130,7 @@ func TestRenameSession(t *testing.T) {
t.Fatalf("main title = %q, want 工作台", got)
}
// A sub session may be renamed, and a rename overwrites an auto title.
// 子会话可以重命名，且重命名会覆盖自动标题。
sub, err := st.NewSubSession(ctx, "owner")
if err != nil {
t.Fatalf("new sub: %v", err)
@@ -145,7 +145,7 @@ func TestRenameSession(t *testing.T) {
t.Fatalf("sub title = %q, want 手动标题", got)
}
// An unknown id is reported as not found.
// 未知 id 报 not found。
if err := st.RenameSession(ctx, "web:missing", "x"); !errors.Is(err, ErrSessionNotFound) {
t.Fatalf("rename unknown err = %v, want ErrSessionNotFound", err)
}