docs(gateway): WS 帧门相关 11 个文件的注释改中文(只改注释,代码零字节改动)
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

主人 2026-10-03 拍板「注释一律中文」。本次先把本会话动过的文件就地翻;
不做全仓一次性翻译,存量按包分批排期(见 工作小结.md 待办)。

范围:ws_frame_scope.go / ws_frame_scope_test.go / broadcast.go / ws_hub_turn.go /
ws_hub_message_event.go / session_read.go / server.go / ws_hub_stream_scope_test.go /
history_write_broadcast_test.go / mood_test.go / extra_test.go
含中文的整行注释 18 → 382。

校验(判据 = "只改注释、零代码字节改动"):
- `git diff -U0 | 排除 +++/--- | 排除注释行/空行/行尾注释` → 为空
- 独立实现:两侧剥掉注释后逐行比对代码文本 → 11/11 文件全等,不一致数 0
- 行尾注释 7 行逐条列出,代码列与原文逐字节相同(gofmt 未要求重排)
- gofmt -l 干净;全树 go build/vet 绿;go test ./... = 58 包 ok / 0 FAIL;
  linux/amd64 + darwin/arm64 交叉编译绿
语义未删减:部分折行英文长句合并为更少行,故整行注释数 438 → 399。
This commit is contained in:
AskaEth committed 2026-10-03 22:07:56 +08:00
1 parent 770a83c3fb
commit fe1ff33115
11 files changed
+392 -431

No files matched your search

+24 -24
View File
@@ -1,34 +1,34 @@
package gateway
// This file owns the outbound WS frame role gate (design/11 §7.1 「WS 下行帧的
// 角色门」, decided by the owner on 2026-10-03). It is the ONE place that decides
// which connections a downstream frame may reach:
// 本文件是 WS 下行帧角色门的唯一归属地(design/11 §7.1「WS 下行帧的
// 角色门」,主人于 2026-10-03 决策)。它是判定一个下行帧可以触达哪些
// 连接的唯一位置:
//
// - a frame whose type is listed in frameReachesAll is a 「状态机信号」: it
// carries no content, so every authenticated connection receives it;
// - EVERY other frame type — reply text (message.*), thinking, tool calls and
// results, persisted/edited/deleted messages, graph updates, sub-agent and
// task traffic, private persona/device state — goes to owner + admin only.
// - 类型列在 frameReachesAll 中的帧属于「状态机信号」:不含内容,
// 因此每个已认证连接都能收到;
// - 其余所有帧类型 —— 回复正文(message.*)、思考、工具调用与
// 结果、持久化/编辑/删除的消息、图谱更新、子代理与任务
// 流量、角色私有状态/设备状态 —— 只发 owner + admin。
//
// The classification is fail-closed: a new frame type answers false until someone
// deliberately registers it here AND in design/11 §7.1, so forgetting to classify
// a type can never leak content. No call site decides visibility for itself (a
// per-call-site flag is exactly how one missed spot becomes a leak), which is why
// hub.broadcast looks the class up from the frame it was handed.
// 分类是 fail-closed 的:新帧类型在有人把它显式登记到此处、并且在
// design/11 §7.1 登记之前一律返回 false,因此漏分类某个类型
// 永远不会泄露内容。没有任何调用点自行决定可见性(按调用点传
// 标志正是「漏一处即成泄露」的来源),这也是 hub.broadcast
// 从收到的帧反查类别的原因。
//
// This gate decides who is PUSHED to. Data visibility stays with the REST gates:
// a viewer still reads its 12 read-only monitoring endpoints through viewerAuth
// (design/11 §7.1 「语义澄清」).
// 本门只决定向谁 PUSH。数据可见性仍归 REST 门:
// viewer 依然只能通过 viewerAuth 读取它的 12 个只读监控端点
// (design/11 §7.1「语义澄清」)。
// frameReachesAll reports whether a downstream frame type may be delivered to
// every authenticated connection. Only the 「状态机信号」 of the design/11 §7.1
// whitelist qualify: session_busy / pending_ack / pending_drain / session_idle /
// session_interrupted / pending_full / session_read. Each one only reports that a
// session changed busy state, so a read-only monitor can follow the conversation's
// activity without receiving the conversation itself.
// frameReachesAll 报告某个下行帧类型是否可投递给每个已认证
// 连接。只有 design/11 §7.1 白名单中的「状态机信号」符合条件:
// session_busy / pending_ack / pending_drain / session_idle /
// session_interrupted / pending_full / session_read。它们只报告
// 会话忙闲状态发生了变化,因此只读监控端可以跟随对话的
// 活跃度,而不必接收对话本身。
//
// Widening this list is a contract change: register the reason (「不含内容」) in
// design/11 §7.1 and mirror it in ws_frame_scope_test.go first.
// 扩大这个名单属于契约变更:先在 design/11 §7.1 登记理由
// (「不含内容」),并在 ws_frame_scope_test.go 中同步。
func frameReachesAll(typ string) bool {
switch typ {
case EventSessionBusy,