# Task: 诊断 Token balance exhausted 的错误呈现与请求行为

## Identity

- Task ID: 20260808-token-balance-7c2f
- Mode: Feature
- Branch: main
- Worktree: D:\Datas\OthersProjects\makelore
- Base commit: 52626b332da5e0f3848223848432cff74caa5273
- Owner: codex
- Status: Ready for Integration

## Scope

- 诊断 AI Gateway 返回 `token_balance_exhausted` 后模型请求失败、原始英文错误进入聊天记录，以及额度接口重复读取的问题。
- 修复当前会话实时额度错误的升级提示，并友好呈现已持久化的绝对余额错误。
- 为错误分类、真实 OpenCode transcript 结构及误判边界补充聚焦回归测试。

## Intent And Constraints

- 不在客户端计算或伪造远端余额；实际可用性仍由 Works Square 账本决定。
- 只把带 `isError` 标记的 assistant 错误作为错误处理，正常回复中出现同样字样不得误判。
- 绝对余额耗尽可直接确认；5 小时/周滚动额度错误继续通过现有 token usage 契约核验。
- 弹窗只绑定当前选中会话和具体失败 key；历史记录不重新激活升级弹窗。
- 保持 Renderer 经 Host API/Main 边界访问后端，不新增 IPC 或直连。

## Outcome

- 证实远端网关在 introspect 后以 `balance=0` 拒绝 authorize；本仓库不包含该 Python 网关或账本计算，客户端无法恢复真实额度。
- 证实本机 OpenCode 数据库中的三条失败均为无 parts 的 structured assistant error，原始文本此前被当作普通气泡渲染。
- 新增绝对 token-balance 判定，并仅对该类结构化错误显示中文友好文案。
- 当前会话的实时绝对余额错误直接打开升级提示，不再用滚动额度百分比错误地反证，也少发一次 token usage 请求。
- 历史错误仅做中文化，不会在充值后重进旧会话时再次弹窗；后台会话错误也不会绑定到当前会话。
- 额度确认和弹窗状态绑定具体 failure key，避免切换会话时沿用旧确认状态。
- 重复 token usage 请求的剩余来源是 Sidebar 的 stale 后立即刷新及 1.5 秒一致性复查；本次未扩大为全局请求去重重构。
- README 无需更新：产品边界和架构未变化，本次为既有错误呈现修正。

## Verification

- RED：`pnpm exec vitest run tests/unit/opencode-chat-panel.test.tsx -t "shows a subscription upgrade dialog instead of the raw quota error"`，修复前 DOM 可见原始英文错误。
- GREEN：7 个相关单测文件共 259 项通过，覆盖 ChatPanel、错误分类、消息归一化、store、token usage、AI proxy 与 Sidebar。
- `pnpm run typecheck` 通过。
- 聚焦 ESLint 通过：4 个变更源码/测试文件无报错。
- `pnpm run build:vite` 通过；仅保留既有 chunk 大小提示。
- `pnpm test` 未全绿：与本次变更无文件交集的环境/基线失败可独立复现，包括系统缺少 `zip`、`.opencode/agent` 生成目录不存在，以及 `project-progress-sync` 的 3 个既有 watcher/调用次数断言失败。
- 未新增 Electron E2E：现有共享 fixture 无远端额度错误注入点；单测使用了本机 SQLite 中核对过的真实 structured message 形状。

## Follow-ups

- Works Square 运维侧为对应账号充值，或检查 One API 用户/令牌映射与账本同步；否则模型请求仍会被远端拒绝。
- 后续可评估在 token usage 契约中暴露绝对余额维度，并集中去重 Sidebar 的即时/延迟刷新。

## Promotion Candidates

- Target: accepted architecture/domain documentation.
- Proposal: 明确区分“绝对 token balance”与“滚动 5 小时/周额度”；绝对余额错误不得被滚动百分比反证。
- Evidence: 网关日志、OpenCode SQLite structured error、错误分类与 ChatPanel 回归测试。
- Future impact: 后续新增额度来源或用量 UI 时复用同一语义，避免再次混淆。
- Human confirmation required: yes.