docs: close rate limit middleware rollout

Author: linhay

docs-linhay/memory/2026-05-16.md

@@ -24,3 +24,28 @@
 - `v1.0.7` 已发布为正式 Release：`https://github.com/AxApp/GetTokens/releases/tag/v1.0.7`。
 - Release 资产齐全：`GetTokens_macOS_AppleSilicon.dmg`、`GetTokens_macOS_AppleSilicon.tar.gz`、`GetTokens_macOS_Intel.dmg`、`GetTokens_macOS_Intel.tar.gz`、`checksums.txt`。
 - Sparkle 分发已更新到 `sparkle-appcast` 分支，`appcast-arm64.xml` 首条指向 `GetTokens_macOS_AppleSilicon.dmg`，`appcast-amd64.xml` 首条指向 `GetTokens_macOS_Intel.dmg`，二者 `sparkle:version` 均为 `1.0.7`。
+
+## Rate Limit 需求设计核对
+
+- 重新核对 `20260515-rate-limit-middleware` 后确认：旧限流设计稿仍停留在“旧账号卡追加 Rate Limits 进度条”的口径，已落后于 2026-05-15 完成的共享 `AttributionCard` 母版、Codex 完整/缩略密度和 Usage Desk attribution 真源。
+- 已重做 `docs-linhay/spaces/20260515-rate-limit-middleware/rate-limit-design-v01.html`，把限流表达收敛为共享卡片里的 `Route Guard` 区域；Codex 顺序卡在完整/缩略模式下都保留超限 chip 与 route policy 语义。
+- 已同步更新 space README 与 `plans/20260515-rate-limit-frontend-design.md`：限流规则配置区命名为 `Route Guard Rules`，放在 `Management` 与 `Verification` 之间；Usage Desk 的 `rate-limit` 若进入首期，应作为第三个 source 数据面实现并补测试。
+
+## Rate Limit 实现与冒烟
+
+- `20260515-rate-limit-middleware` 已完成首期实现：sidecar fork 增加 `RateLimitStrategyRegistry`、SQLite 规则/事件表、`RateLimitEvaluator` 定时评估、`rateLimitPolicy` 路由过滤与 `/gettokens/rate-limit-*` management API；GetTokens Go/Wails 与前端账号池完成策略、规则、状态展示和编辑闭环。
+- 关键约束：API key 规则保存时必须使用 attribution `match_key`（例如 `auth-id:codex:apikey:a6ba88c12cad`），不能只用本地 `codex-api-key:*`，否则 sidecar routing candidate 无法命中规则。
+- 验证结果：sidecar `go test ./...`、主仓库 `go test ./...`、前端 typecheck/unit/build 均通过；Wails dev app 冒烟确认 `30d token-window limit=1 block` 能让账号卡显示 `ROUTE GUARD / 30D TOKENS 已满`，management status 返回 `blocked=true`。冒烟测试规则与事件已从本机 SQLite 清理。
+- 追加多场景验证：自动化补测 token-window、request-window、warn 不 deny、窗口滑过恢复、disabled/unconfigured 放行、注册式新策略、CRUD/event；Wails dev `VERSION 2026.05.16.15` 的 live sidecar API 使用 synthetic account 跑通 block/events/warn/recovery/disabled/delete cleanup，测试数据已清理。
+- Subagent 体验修复：浏览器预览 `?preview=accounts#frame=accounts&workspace=codex` 因账号池只认 Wails `ready` 显示 `0 UNITS`，已增加无 Wails 绑定时加载 preview 数据的就绪判断；另修复 API Key 详情未透传 rate limit 状态导致 `Route Guard Rules` 空白的问题。最后一轮体验补齐 preview 下规则保存/删除不再误触 Wails binding，而是本地更新并提示 `BROWSER PREVIEW ONLY`。复验确认账号池 5 个 preview 资产、详情规则、Codex 顺序卡 `1H REQUESTS 已满` chip 均显示正常。
+- 主控真实桌面复验继续抓到两个体验缺口并修复：`Route Guard Rules` 编辑中可能被后台 `rateLimitStatus` 刷新覆盖 draft，已加 dirty draft 保护；OpenAI-compatible provider 详情缺少规则编辑区，已抽出共享 `RateLimitRulesSection` 并接入 provider 详情。Wails `VERSION 2026.05.16.15` 复验 UI 保存、blocked 刷新和清理通过，测试规则删除后 `rules_len=0`、`blocked=false`。
+- 追加 Wails binding 复验：dev app `VERSION 2026.05.16.16` 通过 UI 新增 `ui-smoke-20260516` 规则，management API 确认 `match_key=auth-id:codex:apikey:a6ba88c12cad`、`limit_value=1`；随后通过 UI 删除，API 查询该 label 数量为 `0`。该轮覆盖 Sartre 最后提示的真实 Wails 保存/删除风险。
+
+## Session Management Provider 归并保存修复
+
+- 修复 Provider 归并弹窗在 localhost 桌面态保存时优先走 dev HTTP bridge 的问题：`window.go.main.App.UpdateCodexSessionProviders` 存在时必须优先走 Wails runtime，避免多个 dev bridge 端口逐个 5 秒等待导致按钮长时间停在“保存中”。
+- Provider 来源标签不再强制大写，保留原 provider 显示大小写；保存按钮补充 `aria-busy` 与旋转状态图标，便于识别保存进行中。
+- 回归测试新增 localhost 桌面态 runtime 优先级断言，保留无 Wails 绑定时 dev bridge fallback。
+- 继续定位到真实 app 保存卡住的主因：后端 `UpdateCodexSessionProviders` 在缓存冷启动时会先执行完整 session 扫描；本机约 3000 条 session 时，这会让保存按钮长期停在“保存中”。修复为前端保存请求携带当前快照，后端优先使用该快照完成定向 rewrite 与内存计数更新，仅在没有快照时才回退加载后端快照。
+- 后端保存完成后不再清空缓存并强制全量刷新，而是更新当前项目/global provider counts 与缓存快照后直接返回，避免保存路径二次扫描。
+- 桌面排障结论：同时存在旧 `/Applications/GetTokens.app` 与 dev `build/bin/GetTokens.app` 会造成用户实际点击的 app 与当前开发实例不一致；已杀掉旧进程，只保留 wails dev 下的 `GetTokens`。

docs-linhay/spaces/20260515-rate-limit-middleware/README.md

@@ -95,15 +95,16 @@ Then 返回最近拦截事件列表，包含策略类型、窗口、当前用量
 
 ## 设计稿入口
 
-- 本期设计稿：`（待产出）`
+- 本期设计稿：[rate-limit-design-v01.html](rate-limit-design-v01.html)
 - 约束：单期只保留一个 HTML 文件。
 - 端约束：桌面 Wails 工作台，不做移动端适配。
 
 设计方向：
-1. 限流进度条与既有 Codex 计划额度在同卡片内上下并列，使用 amber 色轨区分。
-2. 超限账号行显示策略 chip（如 `24h tokens 已满`），左侧状态 rail 红色。
-3. 限流规则配置区在账号详情 modal 内为独立 section，每条规则一行：策略下拉 / 窗口下拉 / 阈值输入 / 行为下拉 / 启用开关。
-4. Usage Desk 新增 `限流状态` 观察源，按超限状态排序。
+1. 限流状态进入当前共享 `AttributionCard` 母版，作为 `Route Guard` 区域放在 quota 后、evidence 前；它表达路由候选是否被剔除，而不是另一条平台 quota。
+2. 超限账号同时影响左侧状态 rail、guard summary 与策略 chip；Codex 顺序卡在完整 / 缩略模式下都必须保留超限 chip 和 route policy 语义。
+3. 限流规则配置区在账号详情 modal 内独立为 `Route Guard Rules` section，位于 `Management` 与 `Verification` 之间，并展示 evaluator 快照时间与保存后立即评估语义。
+4. Usage Desk 若新增 `限流状态` 观察源，必须作为第三个 source 数据面接入，而不是复用现有 `真实请求量 / 本地投影用量` 的文案。
+5. 设计稿已经按 2026-05-15 后的账号归因卡母版重做；旧稿中“仅在旧账号卡上插入 Rate Limits 进度条”的口径不再作为实现依据。
 
 ## Worktree 映射
 
@@ -113,6 +114,11 @@ Then 返回最近拦截事件列表，包含策略类型、窗口、当前用量
 ## 相关链接
 - 实施方案 v5：[plans/20260515-rate-limit-middleware-plan-v05.md](plans/20260515-rate-limit-middleware-plan-v05.md)（**当前方案：内存缓存 + 定时评估**）
 - 前端展示设计：[plans/20260515-rate-limit-frontend-design.md](plans/20260515-rate-limit-frontend-design.md)
+- 冒烟截图：[screenshots/20260516/rate-limit/20260516-rate-limit-route-guard-blocked-after-v03.png](screenshots/20260516/rate-limit/20260516-rate-limit-route-guard-blocked-after-v03.png)
+- 真实 Wails 复验截图：[screenshots/20260516/rate-limit/20260516-rate-limit-wails-route-guard-blocked-after-v04.png](screenshots/20260516/rate-limit/20260516-rate-limit-wails-route-guard-blocked-after-v04.png)
+- Wails 绑定保存复验截图：[screenshots/20260516/rate-limit/20260516-rate-limit-wails-binding-save-after-v05.png](screenshots/20260516/rate-limit/20260516-rate-limit-wails-binding-save-after-v05.png)
+- Wails 绑定删除复验截图：[screenshots/20260516/rate-limit/20260516-rate-limit-wails-binding-delete-after-v06.png](screenshots/20260516/rate-limit/20260516-rate-limit-wails-binding-delete-after-v06.png)
+- OpenAI-compatible 详情复验截图：[screenshots/20260516/rate-limit/20260516-rate-limit-openai-compatible-route-guard-detail-after-v01.png](screenshots/20260516/rate-limit/20260516-rate-limit-openai-compatible-route-guard-detail-after-v01.png)
 - CPA-Manager 参考分析：[reference/cpa-manager-analysis.md](reference/cpa-manager-analysis.md)
 - 历史方案 v4：[plans/20260515-rate-limit-middleware-plan-v04.md](plans/20260515-rate-limit-middleware-plan-v04.md)（已废弃：热路径查 DB）
 - 历史方案 v3（已废弃）：[plans/20260515-daily-quota-middleware-plan-v03.md](plans/20260515-daily-quota-middleware-plan-v03.md)
@@ -121,5 +127,18 @@ Then 返回最近拦截事件列表，包含策略类型、窗口、当前用量
 - Codex 账号列表：[20260511-codex-account-list-tab](../20260511-codex-account-list-tab/README.md)
 
 ## 当前状态
-- 状态：draft
-- 最近更新：2026-05-15
+- 状态：implemented-smoked
+- 最近更新：2026-05-16
+- 实现摘要：
+  - sidecar fork 已接入 `RateLimitStrategyRegistry`、`rate_limit_rules` / `rate_limit_events`、定时 `RateLimitEvaluator`、`rateLimitPolicy` 和 `/gettokens/rate-limit-*` management API。
+  - GetTokens Go/Wails 已暴露策略、规则、状态与事件查询/保存方法，root `main.App` 绑定已同步。
+  - 前端首期收敛在账号池、Codex 顺序卡与 OpenAI-compatible 账号：共享 `AttributionCard` 增加 `Route Guard` 区域，Codex API Key 与 OpenAI-compatible 详情均复用 `Route Guard Rules` 配置区。
+- 验收记录：
+  - 自动化：sidecar `go test ./...`、主仓库 `go test ./...`、`npm --prefix frontend run typecheck`、`npm --prefix frontend run test:unit`、`npm --prefix frontend run build` 均已通过。
+  - 多场景回归：已补 sidecar 场景测试，覆盖 token-window 阻断、request-window 阻断、warn 只告警不 deny、窗口滑过恢复、disabled/unconfigured 放行、注册式新策略、CRUD/event。
+  - Live sidecar API：Wails dev `VERSION 2026.05.16.15` 使用最新 sidecar binary 重新启动；用 synthetic account `smoke-rate-limit:20260516:api` 验证 strategies、空状态、token block、event 记录、warn、窗口恢复、disabled、delete cleanup 全链路通过。
+  - 桌面冒烟：Wails dev app `VERSION 2026.05.16.15` 已启动，sidecar management API ready；通过 UI 新增 `token-window limit=1 block` 规则后，SQLite `match_key` 写入 `auth-id:codex:apikey:a6ba88c12cad`，status 返回 `blocked=true / 7d tokens 已满`，账号卡显示 `ROUTE GUARD` 阻断状态。
+  - Subagent 体验修复：浏览器预览发现账号池因只等待 Wails `ready` 而显示 `0 UNITS`，已改为无 Wails 绑定时加载 preview 数据；另修复 API Key 详情未透传 `rateLimitStatus` / `rateLimitStrategies` 导致 `Route Guard Rules` 空白的问题；最后一轮体验又补齐 preview 下规则保存/删除不再误触 Wails binding，而是本地更新并提示 `BROWSER PREVIEW ONLY`。
+  - 主控追加修复：真实 Wails 体验发现 `Route Guard Rules` 编辑中会被后台 `rateLimitStatus` 刷新覆盖 draft，已增加 dirty draft 保护；Subagent 第二轮发现 OpenAI-compatible 详情缺少 `Route Guard Rules`，已抽出共享规则编辑区并接入 provider 详情。
+  - 复验确认：账号池 preview、Codex API Key 详情、OpenAI-compatible 详情、Codex 顺序卡 blocked chip、真实 Wails UI 保存/刷新/blocked 状态均可见；本机测试规则已通过 management API 删除，`rules_len=0`、`blocked=false`，避免污染 dev 环境。
+  - 追加 Wails binding 复验：dev app `VERSION 2026.05.16.16` 通过 UI 新增 `ui-smoke-20260516` 规则，API 确认 `match_key=auth-id:codex:apikey:a6ba88c12cad`、`limit_value=1`；随后通过 UI 删除，API 查询该 label 数量为 `0`。

docs-linhay/spaces/20260515-rate-limit-middleware/plans/20260515-rate-limit-frontend-design.md

@@ -2,6 +2,16 @@
 
 日期：2026-05-15
 
+## 2026-05-16 核对修正
+
+本文件原始插入点仍有参考价值，但设计稿已按 2026-05-15 之后的账号归因卡母版重做，当前实现依据以 `../rate-limit-design-v01.html` 和以下修正为准：
+
+1. `RateLimitSection` 不再按“旧账号卡新增一块进度条”理解，而是共享 `AttributionCard` 的 `Route Guard` 区域：位置在 quota 后、evidence 前，语义是 routing guard / DenyIDs，而不是平台 quota 的另一组窗口。
+2. `AccountCard`、`CodexAccountOrderRow`、`OpenAICompatibleProviderCard` 已统一到共享账号卡骨架，限流状态应作为区域配置和 badge 数据注入，不应复制独立卡片 JSX。
+3. Codex 请求顺序卡存在 `完整 / 缩略` 密度：缩略模式隐藏 traffic、usage、quota、evidence，但仍必须保留限流 blocked chip、route target、runtime、model mapping 和 route policy。
+4. `ApiKeyDetailModal` 的限流配置区命名为 `Route Guard Rules` 更准确，放在 `Management` 与 `Verification` 之间；保存规则后应触发 `EvaluateNow`，并在 UI 上展示 evaluator/cache 的最近更新时间。
+5. `UsageDeskFeature` 当前只有 `observed / projected` 两个 source。若首期继续包含 `rate-limit` source，需要同步扩展 `UsageDeskSource`、localStorage 持久化、preview data、表格视图和测试；不能只在现有页面里追加静态表。
+
 ## 现有组件架构回顾
 
 所有账号卡片共享 `AttributionCard` 组件（`frontend/src/features/accounts/components/AttributionCard.tsx`），其 section 结构为：