docs(gateway): WS 帧门相关 11 个文件的注释改中文(只改注释,代码零字节改动)
主人 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:
1 parent
770a83c3fb
commit
fe1ff33115
11 files changed
+392
-431
No files matched your search
@@ -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,
|
||||
|
||||
Reference in new issue
Block a user