docs(gateway): gateway 剩余文件注释改中文（逐行 1:1，代码零字节改动）
主人 2026-10-03 拍板「注释一律中文」；gateway 至此整包注释中文化完成（本会话共 3 批： 已推库 16 个文件 + 本批剩余文件）。 校验：机械校验（非注释改动行）= 空；剥注释后代码文本逐行比对全等（不一致文件数 0）； 全树 go test ./... 58 包 ok / 0 FAIL；交叉编译绿。
This commit is contained in:
AskaEth committed
1 parent
91e8d7a029
commit
074ffc4ebf
73 files changed
+2529
-2529
No files matched your search
@@ -17,15 +17,15 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
|
||||
)
|
||||
|
||||
// This file covers the gateway half of design/22 (多角色并存 + 按会话选角): the REST
|
||||
// contract for binding a session to a role, and the resolver that turns a
|
||||
// sessionID into the loop environment the turn runs under. The chain asserted end to
|
||||
// 本文件覆盖 design/22（多角色并存 + 按会话选角）的网关侧一半：把
|
||||
// 会话绑定到角色的 REST 契约，以及把 sessionID 转成该回合
|
||||
// 所运行的 loop 环境的解析器。端到端断言的链条是：
|
||||
// end is: sessionID → chat_sessions.persona_id → turnEnvResolver → loop.SessionEnv →
|
||||
// per-role agent (system prompt), so a regression at any hop shows up as the wrong
|
||||
// role answering.
|
||||
// 按角色的 agent（system prompt），因此任一环节回归都会表现为
|
||||
// 错误的角色在应答。
|
||||
|
||||
// personaAdapter records every request the loop built, so a test can assert which
|
||||
// role's system prompt actually reached the model.
|
||||
// personaAdapter 记录 loop 构建的每一个请求，使测试能断言
|
||||
// 究竟是哪个角色的 system prompt 抵达了模型。
|
||||
type personaAdapter struct {
|
||||
reqs []model.Request
|
||||
}
|
||||
@@ -41,8 +41,8 @@ func (p *personaAdapter) ChatStream(ctx context.Context, req model.Request, _ fu
|
||||
return p.Chat(ctx, req, model.Options{})
|
||||
}
|
||||
|
||||
// personaTestRegistry registers two roles (one default) so the gateway can validate
|
||||
// personaId values and resolve the default role.
|
||||
// personaTestRegistry 注册两个角色（其中一个是默认），使网关能校验
|
||||
// personaId 值并解析默认角色。
|
||||
func personaTestRegistry(t *testing.T) *personareg.Registry {
|
||||
t.Helper()
|
||||
reg := personareg.New()
|
||||
@@ -63,7 +63,7 @@ func personaTestRegistry(t *testing.T) *personareg.Registry {
|
||||
return reg
|
||||
}
|
||||
|
||||
// personaTestStore opens an in-memory chat-history store.
|
||||
// personaTestStore 打开一个内存聊天历史存储。
|
||||
func personaTestStore(t *testing.T) *history.Store {
|
||||
t.Helper()
|
||||
ctx := context.Background()
|
||||
@@ -79,8 +79,8 @@ func personaTestStore(t *testing.T) *history.Store {
|
||||
return st
|
||||
}
|
||||
|
||||
// gatewayAgentFor builds the per-role agent the composition root would build: the
|
||||
// same adapter, a role-specific instruction string.
|
||||
// gatewayAgentFor 构建组合根会构建的按角色 agent：同一个
|
||||
// 适配器，角色专属的指令字符串。
|
||||
func gatewayAgentFor(t *testing.T, instructions string, ad model.Adapter) *agent.Agent {
|
||||
t.Helper()
|
||||
ag, err := agent.New(instructions, nil, nil, agent.WithModel(ad, nil))
|
||||
@@ -90,12 +90,12 @@ func gatewayAgentFor(t *testing.T, instructions string, ad model.Adapter) *agent
|
||||
return ag
|
||||
}
|
||||
|
||||
// TestChatTurnAnswersAsTheBoundRole is design/22 acceptance 3 seen from the process
|
||||
// boundary: a sub session created and bound to role Y answers as Y (the first system
|
||||
// message is Y's prompt and the persisted messages carry Y). Its role is fixed at
|
||||
// creation (§8-1), so the PATCH that used to unbind it is refused and the session
|
||||
// keeps answering as Y; the only way to get the default role is a session created
|
||||
// without a binding.
|
||||
// TestChatTurnAnswersAsTheBoundRole 是从进程边界看 design/22 验收 3：
|
||||
// 一个创建并绑定到角色 Y 的子会话以 Y 应答（首条 system
|
||||
// 消息是 Y 的提示词，且持久化的消息携带 Y）。其角色在
|
||||
// 创建时即固定（§8-1），因此此前用于解绑的 PATCH 被拒绝，会话
|
||||
// 继续以 Y 应答；要得到默认角色，唯一的办法是创建
|
||||
// 一个不带绑定的会话。
|
||||
func TestChatTurnAnswersAsTheBoundRole(t *testing.T) {
|
||||
t.Parallel()
|
||||
ctx := context.Background()
|
||||
@@ -128,8 +128,8 @@ func TestChatTurnAnswersAsTheBoundRole(t *testing.T) {
|
||||
t.Fatalf("bound session prompt = %q, want role Y's prompt", got)
|
||||
}
|
||||
|
||||
// The orchestrator files both the user turn and the reply under the turn's role,
|
||||
// which is what makes the stored transcript readable role-by-role (design/22 §7-5).
|
||||
// 编排器把用户回合与回复都归到该回合的角色名下，
|
||||
// 这正是让已存转录能按角色阅读的原因（design/22 §7-5）。
|
||||
msgs, err := st.List(ctx, sub, 0, 10, "")
|
||||
if err != nil {
|
||||
t.Fatalf("list messages: %v", err)
|
||||
@@ -143,8 +143,8 @@ func TestChatTurnAnswersAsTheBoundRole(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// Unbinding is refused (design/22 §8-1): a session's role is decided when it is
|
||||
// created, so this PATCH answers 400 and the very next turn still answers as Y.
|
||||
// 解绑被拒绝（design/22 §8-1）：会话的角色在创建时
|
||||
// 决定，因此该 PATCH 返回 400，紧接着的下一个回合仍以 Y 应答。
|
||||
resp, body = doReq(t, http.MethodPatch, ts.URL+"/api/v1/sessions/"+sub, map[string]any{"personaId": ""}, tok)
|
||||
if resp.StatusCode != http.StatusBadRequest {
|
||||
t.Fatalf("unbind status = %d, want 400 (a session's role is immutable; body=%s)", resp.StatusCode, body)
|
||||
@@ -157,8 +157,8 @@ func TestChatTurnAnswersAsTheBoundRole(t *testing.T) {
|
||||
t.Fatalf("prompt after the refused unbind = %q, want role Y's prompt", got)
|
||||
}
|
||||
|
||||
// The default role is reached by a session created WITHOUT a binding — the only
|
||||
// way to change role now.
|
||||
// 默认角色要通过创建时不带绑定的会话才能抵达 —— 这是
|
||||
// 目前改变角色的唯一方式。
|
||||
unbound, err := st.NewSubSession(ctx, "owner")
|
||||
if err != nil {
|
||||
t.Fatalf("NewSubSession: %v", err)
|
||||
@@ -172,7 +172,7 @@ func TestChatTurnAnswersAsTheBoundRole(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// firstSystemText returns the text of the first system message of req.
|
||||
// firstSystemText 返回 req 中首条 system 消息的文本。
|
||||
func firstSystemText(req model.Request) string {
|
||||
for _, m := range req.Messages {
|
||||
if m.Role != model.RoleSystem {
|
||||
@@ -187,12 +187,12 @@ func firstSystemText(req model.Request) string {
|
||||
return ""
|
||||
}
|
||||
|
||||
// TestSessionPersonaHTTPContract covers the REST contract of design/22 §4.5 as
|
||||
// amended by §8-1: create with a personaId binds it, the session list reports it, an
|
||||
// unknown personaId on create is rejected (400) instead of binding a role that cannot
|
||||
// answer, a PATCH with neither title nor pinned is a 400, and PATCH REFUSES the
|
||||
// personaId key for every value — a session's role is fixed at creation, so there is
|
||||
// no supported rebind and the refusal can never be mistaken for a silent no-op.
|
||||
// TestSessionPersonaHTTPContract 覆盖经 §8-1 修订后的 design/22 §4.5 的
|
||||
// REST 契约：带 personaId 创建即绑定它、会话列表报告它、
|
||||
// 创建时的未知 personaId 被拒绝（400）而不是绑定一个无法
|
||||
// 应答的角色、既无 title 也无 pinned 的 PATCH 是 400，且 PATCH 对
|
||||
// personaId 键的任何取值一律拒绝 —— 会话角色在创建时固定，
|
||||
// 因此没有受支持的重绑，该拒绝绝不会被误认为静默无操作。
|
||||
func TestSessionPersonaHTTPContract(t *testing.T) {
|
||||
t.Parallel()
|
||||
st := personaTestStore(t)
|
||||
@@ -215,7 +215,7 @@ func TestSessionPersonaHTTPContract(t *testing.T) {
|
||||
t.Fatalf("create echoed personaId = %q, want yuki", created.PersonaID)
|
||||
}
|
||||
|
||||
// The session list surfaces the binding (the client renders the active role from it).
|
||||
// 会话列表浮现该绑定（客户端据此渲染活动角色）。
|
||||
var sessions []historySessionSummary
|
||||
_, body = doReq(t, http.MethodGet, ts.URL+"/api/v1/sessions", nil, tok)
|
||||
decodeDataSlice(t, body, &sessions)
|
||||
@@ -229,23 +229,23 @@ func TestSessionPersonaHTTPContract(t *testing.T) {
|
||||
t.Fatalf("listed persona_id = %q, want yuki (sessions=%+v)", found, sessions)
|
||||
}
|
||||
|
||||
// An unknown role on create is refused rather than silently ignored.
|
||||
// 创建时的未知角色被拒绝，而不是被静默忽略。
|
||||
resp, body = doReq(t, http.MethodPost, ts.URL+"/api/v1/sessions", map[string]any{"personaId": "nobody"}, tok)
|
||||
if resp.StatusCode != http.StatusBadRequest {
|
||||
t.Fatalf("create with unknown personaId status = %d, want 400 (body=%s)", resp.StatusCode, body)
|
||||
}
|
||||
|
||||
// A body with none of the supported fields stays a 400.
|
||||
// 不含任何受支持字段的请求体仍是 400。
|
||||
resp, body = doReq(t, http.MethodPatch, ts.URL+"/api/v1/sessions/"+created.SessionID, map[string]any{}, tok)
|
||||
if resp.StatusCode != http.StatusBadRequest {
|
||||
t.Fatalf("empty patch status = %d, want 400 (body=%s)", resp.StatusCode, body)
|
||||
}
|
||||
|
||||
// PATCH refuses the personaId key for EVERY value (design/22 §8-1): the role is
|
||||
// fixed when the session is created, so a rebind — to another role, to the bound
|
||||
// role, to "", or to null — is not a supported operation. Each refusal must name
|
||||
// personaId (so a client can tell it from "no field given") and must leave the
|
||||
// stored binding exactly as it was.
|
||||
// PATCH 对 personaId 键的任何取值都拒绝（design/22 §8-1）：角色在
|
||||
// 会话创建时固定，因此重绑 —— 绑到另一个角色、绑到已绑
|
||||
// 角色、绑到 ""、或绑到 null —— 都不是受支持的操作。每次拒绝都必须点明
|
||||
// personaId（使客户端能与「未给出字段」区分），并且必须让
|
||||
// 已存绑定保持原样。
|
||||
for _, bad := range []any{"xilian", "yuki", "nobody", "", " ", nil} {
|
||||
resp, body = doReq(t, http.MethodPatch, ts.URL+"/api/v1/sessions/"+created.SessionID, map[string]any{"personaId": bad}, tok)
|
||||
if resp.StatusCode != http.StatusBadRequest {
|
||||
@@ -259,8 +259,8 @@ func TestSessionPersonaHTTPContract(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// The refusal beats a legal field in the same body: a client cannot smuggle a
|
||||
// rebind alongside a rename, and the rename must not land either.
|
||||
// 该拒绝压过同一请求体中的合法字段：客户端不能借改名
|
||||
// 夹带重绑，而改名也绝不能生效。
|
||||
resp, body = doReq(t, http.MethodPatch, ts.URL+"/api/v1/sessions/"+created.SessionID, map[string]any{"title": "偷偷改名", "personaId": "xilian"}, tok)
|
||||
if resp.StatusCode != http.StatusBadRequest {
|
||||
t.Fatalf("rename+personaId status = %d, want 400 (body=%s)", resp.StatusCode, body)
|
||||
@@ -278,12 +278,12 @@ func TestSessionPersonaHTTPContract(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// The personaId check runs BEFORE the session lookup: an unknown session carrying
|
||||
// the key answers 400 (immutable role), not 404 — while a title-only patch for the
|
||||
// very same unknown id is still the store's 404, which is what proves the 400 above
|
||||
// comes from the persona rule rather than from a missing session. An empty body is
|
||||
// the third corner of the same table: 400 for a missing field, again without ever
|
||||
// looking the session up.
|
||||
// personaId 检查在会话查找之前执行：携带该键的未知会话
|
||||
// 返回 400（角色不可变），而不是 404 —— 而针对同一个未知 id
|
||||
// 的纯标题补丁仍是存储的 404，这正是证明上面的 400
|
||||
// 来自人格规则而非会话缺失的依据。空请求体是
|
||||
// 同一张表的第三个角：字段缺失返回 400，同样
|
||||
// 完全不查找会话。
|
||||
resp, body = doReq(t, http.MethodPatch, ts.URL+"/api/v1/sessions/web:missing", map[string]any{"personaId": "xilian"}, tok)
|
||||
if resp.StatusCode != http.StatusBadRequest {
|
||||
t.Fatalf("unknown session + personaId status = %d, want 400 (body=%s)", resp.StatusCode, body)
|
||||
@@ -297,7 +297,7 @@ func TestSessionPersonaHTTPContract(t *testing.T) {
|
||||
t.Fatalf("unknown session + title status = %d, want 404 (body=%s)", resp.StatusCode, body)
|
||||
}
|
||||
|
||||
// title/pinned are untouched by the refusal.
|
||||
// title/pinned 不受该拒绝影响。
|
||||
resp, body = doReq(t, http.MethodPatch, ts.URL+"/api/v1/sessions/"+created.SessionID, map[string]any{"title": "新名字"}, tok)
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
t.Fatalf("title-only patch status = %d, want 200 (body=%s)", resp.StatusCode, body)
|
||||
@@ -307,8 +307,8 @@ func TestSessionPersonaHTTPContract(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// personaBindingOf reads a session's bound role straight from the store, so the test
|
||||
// asserts the persisted state rather than only the response echo.
|
||||
// personaBindingOf 直接从存储读取会话的绑定角色，因此测试
|
||||
// 断言的是持久化状态，而不只是响应回显。
|
||||
func personaBindingOf(t *testing.T, st *history.Store, sessionID string) string {
|
||||
t.Helper()
|
||||
personaID, err := st.SessionPersona(context.Background(), sessionID)
|
||||
@@ -318,10 +318,10 @@ func personaBindingOf(t *testing.T, st *history.Store, sessionID string) string
|
||||
return personaID
|
||||
}
|
||||
|
||||
// TestTurnEnvResolver covers the resolver itself (design/22 §4.5): the session's
|
||||
// binding wins, an unknown/unbound session yields "" (so the loop falls back to the
|
||||
// global default), and the identity/memory fields stay the owner-full ones — the
|
||||
// role never changes what a turn is allowed to do.
|
||||
// TestTurnEnvResolver 覆盖解析器本身（design/22 §4.5）：会话的
|
||||
// 绑定胜出，未知/未绑定的会话得到 ""（使 loop 回退到
|
||||
// 全局默认），且身份/记忆字段保持 owner 全量 ——
|
||||
// 角色绝不改变一个回合被允许做什么。
|
||||
func TestTurnEnvResolver(t *testing.T) {
|
||||
t.Parallel()
|
||||
ctx := context.Background()
|
||||
@@ -352,7 +352,7 @@ func TestTurnEnvResolver(t *testing.T) {
|
||||
t.Fatalf("unknown session env persona = %q, want '' (inherit the default)", got)
|
||||
}
|
||||
|
||||
// A gateway without a history store cannot resolve a binding and must not fail.
|
||||
// 没有 history 存储的网关无法解析绑定，也绝不能失败。
|
||||
bare := turnEnvResolver{log: testLogger()}
|
||||
if got := bare.owner(ctx, "web").PersonaID; got != "" {
|
||||
t.Fatalf("no-store env persona = %q, want ''", got)
|
||||
@@ -362,9 +362,9 @@ func TestTurnEnvResolver(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestDefaultPersonaIDFromRegistry locks the admin fallback design/22 §4.5 asks for:
|
||||
// the default role is read from the library's default character instead of a
|
||||
// hardcoded "cyrene", and an unwired registry reports none.
|
||||
// TestDefaultPersonaIDFromRegistry 锁定 design/22 §4.5 要求的管理回退：
|
||||
// 默认角色从库的默认角色读取，而不是硬编码的
|
||||
// "cyrene"，且未接线的注册表报告无默认。
|
||||
func TestDefaultPersonaIDFromRegistry(t *testing.T) {
|
||||
t.Parallel()
|
||||
srv, _, _ := buildEnv(t, cfgDefault(), Deps{Personas: personaTestRegistry(t)})
|
||||
|
||||
Reference in new issue
Block a user