TUI Frontend
OpenSquilla 终端聊天拥有一个稳定的默认 backend 和一个可选启用的预览 backend：
| Backend or target | Status | How to use | Requirements |
|---|---|---|---|
native | Stable default | opensquilla chat | Python package only |
opentui | Preview opt-in | OPENSQUILLA_TUI_BACKEND=opentui opensquilla chat | Bun and local OpenTUI package dependencies |
live-opentui | Manual harness target | Real-terminal harness only | tmux, OpenTUI deps, and live provider config |
live-opentui 不是一个 OPENSQUILLA_TUI_BACKEND 值。它是一个受保护的测试目标，
通过真实 CLI 启动 OpenTUI 预览路径。
TUI contracts 与 renderer 无关，并围绕两个独立的平面构建：
- Streaming plane: 在写入终端之前对 token deltas 进行批处理，因此长答案不会 为每个 token 重绘整个界面。
- Structured UI plane: 将归一化的 TUI domain events 发送给 plugins。Plugin snapshots 可由有能力的 TUI backends 以及未来的 renderers 渲染。
稳定的默认终端聊天是 Python-native 的，不需要 Bun、npm 或 OpenTUI node modules。
OpenTUI 是一个通过 OPENSQUILLA_TUI_BACKEND=opentui 显式选择的预览 backend。
Plugin Slots
Plugins 消费与 renderer 无关的 events，并通过命名的 slots 发布小型 snapshots。 当前的 slots 包括：
| Slot | Purpose |
|---|---|
router_hud | Active-turn model-routing decision. |
status | Compact status or queue notices. |
tool_activity | Tool cards and tool summary history. |
usage | Token, cache, and cost summary. |
inspector | Optional detail panel state for selected items. |
第一个 plugin 是 RouterHudPlugin。它监听 router_decision events 并更新底部
工具栏，而不改变 router 的选择行为。
Router HUD
当路由 metadata 可用时，有能力的 TUI backends 可以渲染一个 Router HUD。在当前 实现中，OpenTUI footer 是该 HUD 的主要预览显示。该 HUD 仅用于显示：它消费 turn metadata，并不改变 model 选择。
该 HUD 可以显示：
- selected tier and model;
- baseline model;
- route source;
- confidence;
- estimated savings;
- fallback state;
- thinking mode;
- prompt policy;
- whether routing was applied;
- rollout phase.
routing_applied=true 加上完整 rollout 显示为一条 active route。
routing_applied=false 或一个 observe rollout 显示为 observe-only。Fallback
routes 使用警告样式。
Backend Selection
默认 backend 是稳定的 Python-native 终端聊天。
内部的 backend 选择器读取 OPENSQUILLA_TUI_BACKEND。未设置或为空的值会选择稳定的
终端聊天。仅在评估预览 backend 时才将该变量设为 opentui。Legacy 值会在聊天启动
之前以一个清晰的 unsupported-backend 错误失败。
OPENSQUILLA_TUI_BACKEND=opentui opensquilla chat预览 backend 需要 Bun 以及本地的 OpenTUI package 依赖：
bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package在没有新的产品方向以及 replay 加真实终端证据的情况下，不要添加并行的 终端/前端实现。
Replay Benchmarks
replay harness 在没有实时 provider 的情况下测量 OpenTUI 渲染路径：
uv run python scripts/bench_tui_replay.py --renderer opentui --fixture long-stream --summary-json .artifacts/tui/opentui-long-stream.json
uv run python scripts/bench_tui_replay.py --renderer opentui --fixture dense-history --summary-json .artifacts/tui/opentui-dense-history.jsonSummary 字段包括 renderer、fixture、available、skip_reason、
event_count、text_chars、tool_count、router_decision_count、wall_ms、
flush_count、max_buffer_chars、coalescing_ratio、transcript_items、
visible_items、expanded_tools、projection_wall_ms、
rendered_text_matches、plugin_error_count 与 errors。
将 OpenTUI 结果用作预览 backend 的证据。
关于终端级别的启动与渲染证据，请使用 real-terminal TUI harness。