docs(patrol): 2026-06-18 文档维护 — session key 公式 + Pool 指标同步

[aaronwong1989]

Summary

变更驱动巡逻，窗口 44f461ff..5bc8c0ce（WebChat 多租户 spec ②③⑤ + 测试/CI）。

• docs/explanation/session-lifecycle.md — DeriveSessionKey 公式补全 workspaceID 维度。key.go:52 实际签名为 5 字段 (ownerID|workerType|clientKey[|workspaceID]|workDir)，原文档漏 workspaceID（spec ① 方案3 锚点）。spec ③ 回归测试重新锁定 key 派生维度不变量，使该公式描述落本次窗口照射范围。
• docs/reference/metrics.md — Pool 指标表补 5 个 ObservableGauge（utilization / active_sessions / distinct_users / distinct_workspaces / memory_reserved_bytes，后 4 个为 spec ⑤ 新增）；获取结果标签表补 workspace_quota_exceeded / memory_exceeded。spec ⑤ 重新照亮 Pool 配额监控区域，按 reference 1:1 同步原则补全。

判断依据

WebChat 多租户 HTTP 端点（/api/workspaces、/api/auth）自 spec ① 起潜伏、未注册路由（routes.go TODO spec ⑥），前端登录 UI 归 spec ⑥。故 multi-tenant.md / admin-api.md / agent-config-system.md 对潜伏功能保持沉默，一致不文档化——待 spec ⑥ 前端上线后统一补充。

Closes #758

🤖 Generated with Claude Code

[hotplex-ai]

Code Review — hotplex-ai

Verdict: ✅ APPROVE | P0:0 P1:0 P2:0 P3:1

纯文档维护 PR（+8/-1，2 文件）。逐条核对文档声称与源码，全部吻合：

session-lifecycle.md — DeriveSessionKey 公式

• key.go:52-58 签名确为 5 字段，workspaceID != "" 时才加入派生 → 与文档 [|workspaceID] 及"仅非空时加入"完全一致；切换 workspace 产生新 Key 成立。
• MaxClientKeyLen = 256（manager.go:41）与文档一致。

metrics.md — Pool 指标 + result 标签

• 5 个 ObservableGauge 名称/描述与 pool.go:33-72 逐一匹配；utilization 确为 Float64ObservableGauge，文档 "(float)" 标注准确；其余为 Int64。
• workerMemoryEstimate = 512MB（pool.go:122）与文档"512MB/worker 估算值"一致。
• result 标签 workspace_quota_exceeded/memory_exceeded 与常量（pool.go:127-128）+ Acquire emit（184-198）一致；配置键 max_per_workspace（config_types.go:619）与文档注释一致。
• distinct_workspaces 仅在 workspaceID 非空时累加，platform/cron 走 workspaceID="" 确实被排除 → 与文档"不含 platform 会话"一致。

---

[P3] 表格类型标注风格不一致 (docs/reference/metrics.md:142)
hotplex.pool.utilization 标为 ObservableGauge (float)，而同表新增的其他 4 个 gauge 及全文其他 ObservableGauge（worker.memory.bytes / gateway.connections）均只写 ObservableGauge。utilization 是 Float64、其余是 Int64，单点标注略显突兀——建议要么统一标 (float)/(int)，要么统一不标。非阻塞，可选。

---

可选 FYI（超本 PR scope，勿在此处理）：hotplex.session.transition.guard.repersist.failures / .overwrites（instruments.go:674,688）两个 Counter 已注册但 metrics.md 未文档化，可纳入下一轮文档巡逻。