fix(tui): token budget 接通 TUI 状态栏 (IK8MWR #12) · Pull Request !8 · andershsueh/alice-cli

## 背景 (issue IK8MWR #12)

`src/runtime/agent/tokenBudget.ts` 已经实现 (`createBudgetTracker` / `checkTokenBudget` / `estimateTokens`),`src/core/llm.ts` 每轮调用 `checkTokenBudget` 追踪用量,但**结果从未外发到 UI**。TUI 状态栏的 `ContextUsageDisplay` 永远拿 0(死代码层 `shim/qwen-code-core.ts` 硬编码返回 0,组件遇 0 直接 `return null`),用户完全看不见 token 消耗进度。

## 改动

### 1. tokenBudget 模块升级为可观测
- 新增 `BudgetUsage` 类型导出(used/total/pct/remaining/nearCompletion/nearDiminishing)
- 新增 `getUsage(tracker, budget)` 纯函数(不改 tracker,只派生快照)

### 2. 事件管道:runtime → ChatStreamEvent
- `ChatStreamEvent` 联合类型加 `budget_update` 字段(扁平 6 字段,避免客户端 import runtime 层)
- `RuntimeEvent` 加 `budget_update`(承载 `BudgetUsage`)
- `llm.chatStreamWithTools` 新增 `onBudgetUpdate` 回调,每轮 `checkTokenBudget` 后通过 `getUsage` 上抛
- `agentLoop` 在 `chatStreamWithTools` 的回调里把 usage 入队,每个 chunk 到达前 flush 一次;循环结束再 drain 一次,保证最后一帧不丢
- `chatHandler.runChatStream` 把 `RuntimeEvent.budget_update` 摊平转发到 `ChatStreamEvent.budget_update`

### 3. TUI 接通
- `useAliceStream` 接收 `budget_update` 事件,写入 `tokenBudget` state,在 `submitQuery` 时 reset
- `UIStateContext.UIState` 加 `tokenBudget?: BudgetUsage | null`
- `AppContainer` 从 `useGeminiStream` 拿 `tokenBudget` 注入 `UIState`(useMemo 依赖也加上)
- 新建 `TokenBudgetBar.tsx`:
  - `usage.total <= 0` 时返回 null(保持 Footer 干净)
  - 渲染 `[ctx NN%]` + 警示后缀
  - `nearDiminishing` → 红色 + ⚠dim(优先级最高,模型即将被强制停止)
  - `nearCompletion` → 黄色 + ⚠exh
- `Footer.rightItems` 新增 `token-budget` 槽位(优先于 `context`)

## 测试

新增 `test-case/test-issue-012.ts`,4 组共 **41 断言** 全绿:

| 用例 | 覆盖 | 断言数 |
|------|------|--------|
| ① getUsage 边界 | zero state / 40% / 80% / remaining<200 / diminishing 决策 / 100% 满预算 | 17 |
| ② ChatStreamEvent 类型联合 | 6 种事件 narrow、字段契约 | 10 |
| ③ TokenBudgetBar 渲染 | `[ctx NN%]` 格式、警示后缀优先级 | 5 |
| ④ 联调事件序列 | 3 轮 exhausted 触发 budget_update、收益率触发后仍正常推 3 个事件 | 9 |

全量回归(`001 002 003 004 005 012 019`)全绿:
- 001: 27 断言 PASS
- 002: 36 断言 PASS
- 003: 34 断言 PASS
- 004: 25 断言 PASS(含 build.ts + DCE)
- 005: 9 断言 PASS
- 012: 41 断言 PASS(新增)
- 019: 37 断言 PASS

`bun run build.ts` 构建成功(DCE 后处理折叠 0 / 剪除 0,与 flag 默认配置一致)。

## 设计决策

1. **回调 vs 直接 yield**:async generator 内不能在回调里 yield(JS 协程限制)。选择回调 + 队列 + 每次 chunk 前 flush 的模式,保证事件顺序"预算 → 当前 chunk"。
2. **扁平字段 vs 嵌套 BudgetUsage**:`ChatStreamEvent.budget_update` 选择把 `BudgetUsage` 字段全部展开,客户端(`useAliceStream`)无需 import runtime 层类型,符合已有 `model_selected` 的扁平风格。
3. **`nearDiminishing` 语义**:基于 `remaining < DIMINISHING_THRESHOLD(200)`,而不是"连续两轮小输出"——后者是 llm 决策层语义,不暴露给 TUI。这点在测试里有显式断言说明(测试 ④ 第 9 个断言)。
4. **`Footer.rightItems` 顺序**:tokenBudget 优先于 context(更精确、与模型输出强相关),且不影响 `promptTokenCount === 0` 时的 context fallback。

## 风险点

- **未触发过 `tokenBudget > 0` 的真实端到端**:本次无真实 LLM 调用验证(测试桩 mock provider),daemon↔CLI 序列化靠 NDJSON,字段顺序/类型已通过类型联合 narrow 静态保证。
- **`agentLoop.pendingBudgetUsage` 队列在异常路径(throw)不会 flush**:已 throw 的迭代器消费方不会收到此事件,设计上 OK,但日志里看不到"失败时还剩多少预算"。后续可加 logger。
- **未影响 `Footer` 既有测试**(`Footer.test.tsx` 不存在;`Footer.tsx` 不在 build 范围之外);`useAliceStream` 也没有现成的 .test.tsx。

Generated with [Claude Code](https://claude.com/claude-code)

类型	指派人员	状态
审查	andershsueh 已审查通过	已完成 (1/1人)
测试	andershsueh 已测试通过	已完成 (1/1人)

andershsueh / alice-cli .gitee-modal { width: 500px !important; }

搜索帮助

andershsueh / alice-cli