---
name: knowledge-interaction-surfaces-terminal-ui
description: >
  覆盖 Blade React + Ink TUI 的初始化、输入协议、消息与工具渲染、确认队列、Session
  切换、流式缓冲和 Runtime 清理。进入时机：修改终端键盘行为、粘贴、Ctrl+C、审批与
  问答、流式输出、Static 布局、会话恢复或 slash command 展示。 不包含：Headless/Print
  输出（见 ../cli-bootstrap-headless-and-print/）、Web React 状态（见 ../web-client/）。
  关键词：AppWrapper, BladeInterface, MessageArea, useCommandHandler, useAgent,
  useConfirmation, parseTerminalInput, Static, rawStreamRenderer。
---

## Module Structure

TUI 以单个 vanilla Zustand Store 投影当前 Session，React Hook 只持有活动 Agent/Runtime
和输入交互生命周期；durable 消息、权限模式与恢复数据仍由 Session 服务管理。

### Directory Layout
- `packages/cli/src/ui/App.tsx` — 版本提示、Workspace Trust、资源与 Hook 初始化
- `packages/cli/src/ui/components/BladeInterface.tsx` — 主界面、阻塞弹窗与 Session 启动路由
- `packages/cli/src/ui/components/MessageArea.tsx` — 单 Static 根、流式块和 raw tail 渲染
- `packages/cli/src/ui/components/` — 输入、确认、问答、状态和工具展示组件
- `packages/cli/src/ui/hooks/` — Agent、命令、输入、确认、Ctrl+C 与缓冲生命周期
- `packages/cli/src/ui/input/terminalInput.ts` — bracketed paste 与终端控制序列解析
- `packages/cli/src/ui/utils/` — LoopEvent 投影、Session 激活、Markdown 和工具格式化
- `packages/cli/src/store/` — React 与非 React 代码共享的当前进程状态
- `packages/cli/src/slash-commands/` — TUI 内置与自定义命令路由

### Key Entry Points
- `AppWrapper` in `packages/cli/src/ui/App.tsx` — 完成信任判断后挂载主界面
- `BladeInterface` in `packages/cli/src/ui/components/BladeInterface.tsx` — 组合输入、弹窗、消息与状态区
- `useCommandHandler()` in `packages/cli/src/ui/hooks/useCommandHandler.ts` — 单轮命令、取消和恢复编排
- `useAgent()` in `packages/cli/src/ui/hooks/useAgent.ts` — Agent/SessionRuntime 的唯一 React 所有者
- `createLoopEventHandler()` in `packages/cli/src/ui/utils/loopEventHandler.ts` — LoopEvent 到 TUI Store 的投影

## Gotchas
- 取消顺序不可交换：先 `dismissAll()` 释放阻塞审批，再排空流式缓冲，再 abort，最后 finalize；先 abort 会把审批拒绝误判为普通 permission denial，晚到 `stream_end` 还可能重复提交 (`packages/cli/src/ui/hooks/useCommandHandler.ts`, `packages/cli/src/ui/hooks/useConfirmation.ts`)
- `createAbortController()` 会主动中止并替换已有 controller；命令下层必须复用外层 controller，否则 finally 的所有权检查失败并让 `isProcessing` 永久卡住 (`packages/cli/src/ui/hooks/useCommandHandler.ts`, `packages/cli/src/store/slices/commandSlice.ts`)
- `MessageArea` 只能有一个 Ink `Static` 根；条件挂载第二个 Static 曾让 Ink 保留已释放 Yoga 节点并在后续 commit 崩溃 (`packages/cli/src/ui/components/MessageArea.tsx`, `docs/testing/tui-single-static-root-ownership-evidence.md`, `git:c68977b7`)
- 高频 Markdown tail 绕过 React 直接写 stdout；在 Static 增长、finalize、清屏、resize 或历史展开前必须先清理 raw renderer，否则终端会残留或错位 (`packages/cli/src/ui/components/MessageArea.tsx`, `packages/cli/src/ui/utils/rawStreamRenderer.ts`)
- `clearCount` 是 Static 的唯一强制重挂边界，finalize 时还必须先 `eraseScreen + cursorTo(0,0)`；仅清屏不归位会在顶部留下大段空白 (`packages/cli/src/ui/components/MessageArea.tsx`)
- 一次 stdin 回调可能是完整 IME 文本或批量自动化输入，不能逐字符假设；bracketed paste marker 还可能被 Ink 去掉 ESC 或跨 chunk 到达 (`packages/cli/src/ui/input/terminalInput.ts`, `docs/reference/tui-terminal-input.md`)
- 未闭合 paste 会留在 parser buffer，超过消息字符预算后一直丢弃到 end marker；不要把半段 paste 当普通输入提交 (`packages/cli/src/ui/input/terminalInput.ts`)
- 第一次 Ctrl+C 在执行中只取消任务并显示二次退出提示，3 秒内第二次才走 GracefulShutdown；直接恢复 Ink 的默认 `exitOnCtrlC` 会跳过资源释放 (`packages/cli/src/ui/hooks/useCtrlCHandler.ts`, `packages/cli/src/blade.tsx`)
- Session 激活必须先完成 fork/load 和 UI-safe 转换，再 `cleanupAgent()`，最后一次性恢复新 Store；清理失败时不能提前切换界面身份 (`packages/cli/src/ui/utils/sessionActivation.ts`)
- fork 提示是 UI-only assistant message，不进入恢复的 model context；把 visible messages 重建为上下文会污染后续模型输入 (`packages/cli/src/ui/utils/sessionActivation.ts`, `packages/cli/src/ui/utils/sessionContext.ts`)
- 阻塞弹窗通过 `display="none"` 隐藏主界面而不卸载，目的是保留 Static 和输入状态；改成条件卸载会重复打印历史并丢失输入组件状态 (`packages/cli/src/ui/components/BladeInterface.tsx`)

## Architecture
- `AppWrapper` 先处理版本提示和 Workspace Trust，再解析可信资源与 Hooks；选择“安全继续”只跳过信任授予，不跳过应用初始化 (`packages/cli/src/ui/App.tsx`)
- `useAgent` 同时拥有 Agent 和 SessionRuntime 引用；Session ID 或 workspace 改变时先幂等销毁旧 Agent，再 dispose 整个 Runtime 边界 (`packages/cli/src/ui/hooks/useAgent.ts`, `git:959149a8`)
- TUI Store 不做持久化：会话写入 JSONL、配置写入 ConfigService；Store 只保存当前进程投影和渲染缓冲 (`packages/cli/src/store/vanilla.ts`)
- `createLoopEventHandler` 为每轮创建闭包，以 `streamFinalized` 隔离 abort、fallback 和正常 `stream_end`；跨轮复用 handler 会让上一轮终态污染下一轮 (`packages/cli/src/ui/utils/loopEventHandler.ts`)
- 流式内容有 Hook 层批缓冲、Store 外模块级 chunks、Markdown 增量缓存和 raw tail 四层状态，正常结束与取消都必须按所有权逐层排空或丢弃 (`packages/cli/src/ui/hooks/useStreamingBuffer.ts`, `packages/cli/src/store/slices/sessionSlice.ts`, `packages/cli/src/ui/utils/markdownIncremental.ts`)
- Confirmation Hook 把请求串成单活动项队列，并为每项绑定 AbortSignal；工具执行并不直接依赖某个具体 Ink 组件 (`packages/cli/src/ui/hooks/useConfirmation.ts`)

## Decisions
- React 与 Agent/工具共享 vanilla Zustand 实例，但只暴露 actions 和 selectors，以避免非 React 路径另建状态源 (`packages/cli/src/store/vanilla.ts`, `packages/cli/src/store/selectors/index.ts`)
- 已完成历史使用 Ink Static，最高频 tail 使用 raw renderer，是为兼顾原生 scrollback 与流式性能；这两条路径通过 message ID 和 finalize 标记去重 (`packages/cli/src/ui/components/MessageArea.tsx`)
- TUI 启用 bracketed paste 并显式关闭 focus reporting，退出时重复恢复终端模式，避免异常关闭把宿主 shell 留在特殊输入状态 (`packages/cli/src/ui/hooks/useTerminalInputModes.ts`, `docs/reference/tui-terminal-input.md`)

## Patterns
- Session 级模型、reasoning、service tier、verbosity 和 communication style 都先刷新 Runtime、再持久化 metadata；持久化失败会回滚 Runtime，避免界面与重启状态分叉 (`packages/cli/src/ui/hooks/useAgent.ts`)
- 恢复 Session 时同时保存 UI-safe messages 与原始 model context，后续只把恢复边界后的新 UI 消息追加到原始上下文 (`packages/cli/src/store/slices/sessionSlice.ts`, `packages/cli/src/ui/utils/sessionContext.ts`)
- 用户输入在 slash command、Hook 改写和 Agent 输入之间保留不同表示：Hook 可改写模型输入，但不能回写已经提交的用户可见消息 (`packages/cli/src/ui/hooks/useCommandHandler.ts`)
- 工具进度、Provider 恢复和 MCP 事件通过统一 LoopEvent handler 投影；新增事件必须保持 exhaustive switch，并避免把结构化输出保留工具渲染成普通工具卡 (`packages/cli/src/ui/utils/loopEventHandler.ts`)
- 主题、权限、Session 选择等弹窗共享焦点状态，主输入仅在没有阻塞弹窗时接管键盘；组件自己的 `useInput` 必须检查对应 FocusId (`packages/cli/src/ui/components/BladeInterface.tsx`, `packages/cli/src/ui/components/ConfirmationPrompt.tsx`)

## Dependencies
- TUI 使用 React、Ink、Yoga 与 Zustand；`ink-text-input` 只处理编辑行为，终端 framing 和批量输入由项目自己的 parser 补齐 (`packages/cli/src/ui/components/CustomTextInput.tsx`, `packages/cli/src/ui/input/terminalInput.ts`)