docs: record usage desk model rollup rule

Author: linhay

docs-linhay/dev/20260430-usage-desk-model-rollup-rule.md

@@ -0,0 +1,38 @@
+# Usage Desk 模型归因与展示规则
+
+## 背景
+- `Usage Desk` 的 `LocalProjectedUsage` 来自本机 Codex rollout `jsonl`。
+- 原始文件里并不是每一条 token 记录都自带 `model`。
+- `turn_context.payload.model` 提供当前模型，后续 `event_msg.token_count` 需要结合最近一次 `turn_context` 才能归因到模型。
+
+## 后端归因规则
+- 本地 usage 索引按 `时间桶 + 模型` 聚合，而不是只按时间桶聚合。
+- 这样可以保留“同一分钟 / 同一 5M 桶内存在多个模型”的原始事实，避免模型信息在索引阶段丢失。
+- 当前索引表使用 `session_usage_minutes_v2` 保存带模型的分钟聚合结果。
+
+## 前端展示规则
+
+### 图表
+- 日级趋势图和分钟趋势图都继续显示“整桶总量”。
+- 图表不按模型拆线，不把一个时间桶分成多条曲线。
+
+### 明细表
+- 明细表保持“一桶一行”。
+- `模型` 列显示该时间桶内 token 用量最大的模型。
+- 若同一个时间桶内还有其他模型参与，则模型列显示为 `<dominant-model>,*`。
+- `,*` 只表示“该桶内还有其他模型参与”，不展开列出全部模型名。
+
+### 适用范围
+- 该规则同时适用于：
+  - `天级趋势` 下的日汇总表
+  - `分钟明细` 下的分钟 / 5M / 15M / 30M / 60M 明细表
+
+## 不采用的方案
+- 不在表格里把同一时间桶按模型拆成多行。
+- 不在当前 UI 中展示完整模型列表或模型占比。
+- 不把 `天级趋势` 的模型列继续留空为 `--`。
+
+## 验收口径
+- 若某个时间桶只出现一个模型，模型列直接显示该模型名。
+- 若某个时间桶出现多个模型，模型列显示主模型并追加 `,*`。
+- 同一时间桶的请求数与 token 数始终是整桶总和，不因模型展示规则而改变。

docs-linhay/memory/2026-04-30.md

@@ -67,6 +67,11 @@
 - 代理池节点 ID 生成逻辑已把 `protocol` 纳入身份键，修复了 `http://127.0.0.1:7897` 与 `socks5://127.0.0.1:7897` 被视为同一条并发生覆盖的问题。
 - `frontend/src/features/proxy-pool/model.test.mjs` 已新增同 host/port 不同协议保留两条的测试，同时用浏览器在页面里通过“导入列表”实测确认两条都能出现在表格中。
 - 回归结果：`node --test frontend/src/features/proxy-pool/model.test.mjs`、`npm --prefix frontend run typecheck`、`npm --prefix frontend run build` 全部通过。
+- Codex 通过 `openai_base_url` 接 GetTokens relay 时，当前 relay 旧版 `/v1/models` 只返回 OpenAI 标准 `data[]` 结构，不返回 Codex 需要的 `models[] + rich metadata` 结构，因此 Codex 无法用 relay 正常刷新模型目录。
+- 已在 `docs-linhay/references/CLIProxyAPI/sdk/api/handlers/openai/openai_handlers.go` 增加 Codex 兼容分支：当 `/v1/models` 请求带 `client_version`（或 Codex UA）时，返回 Codex 可解析的 `models[]` 目录；普通 OpenAI 客户端仍保持原始 `data[]` 响应。
+- 验证结果：`go test ./sdk/api/handlers/openai -run 'TestOpenAIModels|TestOpenAIResponsesCompact'` 通过；本机另外起了修复版 sidecar `http://127.0.0.1:18417/v1`，并已把 `~/.codex/config.toml` 指向该端口，重开 Codex 后即可走兼容的 `/models`。
+- GetTokens 的“一键配置到本地 Codex”最终没有固定切成 `gettokens` provider，而是改成“用户可选 provider，默认保留 `openai` 连续性”：选 `openai` 时继续写 `openai_base_url = ...`，选自定义 provider 时才写 `model_provider = "<id>"` + `[model_providers.<id>]`，避免把既有 Codex 会话搜索和 resume picker 从 `openai` 静默切裂到 `gettokens`。
+- 同一轮修复还补齐了状态页本地工作台配置的三点一致性：前端选中的 relay `model` 会真实透传给 `ApplyRelayServiceConfigToLocal` 并写入 `~/.codex/config.toml`，不再固定为 `gpt-5.4`；`model_reasoning_effort` 也已加入同一条本地落盘链路，并限制为 Codex 支持的 `none/minimal/low/medium/high/xhigh` 枚举；provider 则和 model 一样支持本地新增/删除，用于决定本次落盘是“保持 `openai` 连续性”还是“显式创建 custom provider”。
 
 ## 代理池订阅导入与来源标签
 - 代理池已补上最小“订阅管理”能力：后端新增 `FetchProxySubscription`，只负责拉取 `http/https` 纯文本订阅；前端新增“导入订阅”弹层，导入后会把 `sourceLabel / sourceURL` 写入每条代理节点，并在主表新增“来源”列展示。
@@ -174,9 +179,50 @@
 - 针对这次修复已补验证：`go test ./internal/wailsapp -run 'TestGetCodexLocalUsage(AggregatesTokenCountDeltas|SplitsSameMinuteByModel)$'` 与 `node --test frontend/src/features/accounts/tests/usageDesk.test.mjs` 通过。
 - 后续又按交互规则收口展示：无论日级还是分钟级，表格仍保持“一桶一行”；模型列展示该时间桶用量最大的模型，若该桶还有其他模型参与，则显示为 `<dominant-model>,*`。
 - 当前前端门禁状态已恢复：`npm --prefix frontend run typecheck` 通过；此前阻塞它的 `session-management` 文案与签名问题已一并清掉。
+- 这轮“整理”没有继续新增项目级 skill 或升级 `AGENTS.md`：因为沉淀出来的是 `Usage Desk` 的产品/实现规则，不是跨任务复用的交付流程。对应知识已单独落到 `docs-linhay/dev/20260430-usage-desk-model-rollup-rule.md`。
 
 ## Proxy Pool 测速网址配置与历史
 - 代理池顶部搜索轨道已补“测速网址”配置输入，支持指定 `http/https` 测速站点，不再固定打到默认站点。
 - 单条测速、批量测速和选中测速共用同一份 `probeTargetURL`，测速前会先做 URL 归一化与合法性校验。
 - 已配置并使用过的测速网址会写入本地历史，默认只保留最近 5 条；页面同时提供 datalist 和历史快捷按钮，便于重复切换常用测速目标。
 - 本轮验证已通过：`node --test frontend/src/features/proxy-pool/model.test.mjs`、`npm --prefix frontend run build`；`typecheck` 也已重新回归，无新增代理池类型错误。
+
+## Skills 整理
+- 本轮把真正重复出现且可复用的交付模式沉淀进 `.agents/skills/gettokens-ops-governance/SKILL.md`，没有继续扩 `AGENTS.md`。
+- 新增的稳定模式有两条：
+  1. `Wails Browser Preview & Screenshot Loop`：针对 `vendor-status` 和 `session-management` 这类桌面页，先补 `?preview=` 或 dev-only HTTP bridge，再用 `docs-linhay/scripts/*-browser-check.mjs` 产稳定截图，不把浏览器验收和真实 Wails 验收混为一谈。
+  2. `Cleanup Before Claiming Done`：长会话下如果提交后仍有同轮 tracked diff，主控 agent 需要继续追到只剩参考仓、临时研究文件和本地非版本化产物，不在“主提交已落”时过早停止。
+- 这次没有升级到 AGENTS 的原因是：上述动作属于 GetTokens 项目级执行技巧，复用范围明确，但还没有必要上升成所有任务都必须遵守的 repo-wide 硬规则。
+
+## Status 页本地 Codex 模型目录改为账号池聚合来源
+- `StatusFeature` 的“应用到本地 Codex”区块不再只依赖本地静态 model 列表；当前已新增 `ListRelaySupportedModels()`，由后端聚合 openai-compatible provider 本地模型、远端 `/models` 返回，以及 codex api key 本地模型。
+- `internal/wailsapp/openai_compatible.go` 的 `/models` 解析已补齐 Codex 目录形状兼容：除 OpenAI `data[]` 外，也能识别 `models[] / slug / supported_reasoning_levels / default_reasoning_level`。
+- 状态页当前会优先用账号池聚合目录渲染 `model` 选项，并按当前模型的 `supportedReasoningEfforts` 动态收窄 `model_reasoning_effort`；只有模型没有元数据时，才回退到 Codex 通用枚举 `none/minimal/low/medium/high/xhigh`。
+- 本地手工新增 model 仍保留，但只作为账号池目录之外的补充；删除最后一个本地自定义 model 也已允许，只要账号池目录本身仍非空即可。
+- 本轮验证已通过：`go test ./internal/wailsapp -run 'TestFetchOpenAICompatibleProviderModels|TestParseOpenAICompatibleModelsResponseSupportsCodexModelCatalogShape|TestListRelaySupportedModelsAggregatesRemoteLocalAndCodexKeyModels|TestApplyRelayServiceConfigToLocal'`、`go test .`、`node --test frontend/src/features/status/tests/relayModelCatalog.test.mjs frontend/src/features/accounts/tests/accountConfig.test.mjs`、`npm --prefix frontend run typecheck`。
+
+## Session Management 浏览器开发态取数修复
+- 已确认 `http://localhost:34115/#frame=session-management` 首屏只有壳没有数据，不是列表组件本身坏掉，而是浏览器开发态取数链路不稳定。
+- 根因分三层：`34115` 当前 origin 不承接 `__dev/session-management/*`；前端最初只回退到错误端口 `4173`；即使回退端口修正后，跨域和首个无效候选请求的无超时等待仍会让页面长期停在“加载中”。
+- 当前已收口的修复包括：`session-management` 浏览器态改为优先尝试真实 Vite dev 端口候选 `5173/4173/5174/4174`；跨域 dev bridge 已补 `Access-Control-Allow-Origin: *`；每个候选请求已加快速超时；前端新增 `localStorage` snapshot 缓存；dev bridge 新增内存缓存和磁盘缓存预热，避免每次都重新顺序等待全量 rollout 扫描。
+- 在重启 `wails dev` 后已完成真实页面自测：`34115` 页面正文可见 `99 个项目 / 2860 条会话`，项目列表和项目会话列表均已渲染，不再是空壳等待。
+- 本轮验证已覆盖：`node --test frontend/src/features/session-management/model.test.mjs src/features/session-management/cache.test.mjs`、`npm --prefix frontend run test:unit`、`npm --prefix frontend run typecheck`、`npm --prefix frontend run build`，并通过 `agent-browser` 在 `34115` 页面实测可见真实项目与会话数据。
+
+## Session Management 对齐 Usage 的 App 内缓存语义
+- `session-management` 现在不再把“页面刷新”解释成“重新扫描所有 rollout 文件”。语义已经对齐 `Usage Desk`：`GetCodexSessionManagementSnapshot()` 优先返回 app 进程内缓存，只有 `RefreshCodexSessionManagementSnapshot()` 才强制重扫。
+- 对应后端已在 `internal/wailsapp` 增加 `sessionMgmt` 运行时缓存状态、并发等待和 snapshot clone 逻辑；前端挂载时也取消了“有本地快照就自动 refresh”的行为，改为始终先走 `Get...Snapshot()`。
+- 当前结果是：同一个 Wails dev / app 进程里，页面刷新、重新进入 `session-management`、切换回来都不再重新触发扫描；只有点击页面上的“刷新”按钮才会重扫本机 session 文件。
+- 本轮验证已通过：`go test ./internal/wailsapp -run 'TestGetCodexSessionManagementSnapshot(GroupsProjectsAndStatuses|UsesAppMemoryCacheUntilExplicitRefresh)|TestGetCodexSessionDetailMasksSensitiveTextAndKeepsMessageRows'`、`node --test frontend/src/features/session-management/model.test.mjs src/features/session-management/cache.test.mjs`、`npm --prefix frontend run typecheck`、`npm --prefix frontend run build`。
+
+## Session Management 完整会话行集与 localhost 分流修复
+- `session-management` 详情弹层不再只显示 `user / assistant / system` 三类 message。当前已把真实 rollout 中的 `event_msg:user_message / agent_message / agent_reasoning`、`response_item:reasoning`、`function_call / custom_tool_call / web_search_call`、`function_call_output / custom_tool_call_output` 一并并回消息列表。
+- 前端角色集合已扩成 `system / user / assistant / reasoning / tool_call / tool_result / event`，顶部“当前消息”和角色汇总也同步改为这套完整标签。
+- 浏览器 dev 回退链 `frontend/dev/sessionManagementDevData.js` 现在与 Go 解析保持同语义，不再只抽 `response_item.message`。
+- 另外修了一个 `34115` 浏览器开发页特有的分流问题：只要运行在 `localhost/127.0.0.1`，`session-management` 现在优先走带缓存的 dev HTTP bridge，而不是因为存在 `window.go` 就误走 Wails runtime 全量扫描链。
+- 验证结果：
+  - `go test ./internal/wailsapp -run 'TestGetCodexSessionManagementSnapshot|TestGetCodexSessionDetail'` 通过
+  - `node --test frontend/src/features/session-management/model.test.mjs frontend/src/features/session-management/cache.test.mjs` 通过
+  - `npm --prefix frontend run typecheck` 通过
+  - `npm --prefix frontend run build` 通过
+  - 真实 dev bridge 详情抽查已能看到 `system / event / user / reasoning / tool_call / tool_result / assistant` 混合行集
+- 仍有一个独立的开发态稳定性问题：`wails dev` 的 `34115` 壳子在本轮自测时出现过端口占用/掉线抖动，但这不影响当前代码路径本身和 dev bridge 取数结果。