For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /designs/altscreen.md.
Hunea
  • 简体中文

      • 为什么使用 altscreen

      Hunea 的主界面跑在终端的 alternate screen（常说 altscreen / 备用屏幕缓冲）里。

      简单来说，进入 altscreen 之后，应用也就是 Hunea 拿到的是一块独立的全屏画布：帧刷新、全屏面板、覆盖层、状态行，都可以按自己的布局画；退出时再离开 altscreen，把终端交还给原来的主屏幕。这样主会话不会被 TUI 的中间帧、清屏和局部重绘弄脏，退出路径也更干净。

      1. 全屏模态层需要一整块可控区域
        /tree、/copy、/prompt、会话恢复列表这类界面，不是贴在底部的小浮窗，而是会接管整屏的列表、预览和分页。altscreen 让这些层可以直接占满终端，而不是和 shell 的 scrollback 抢同一条历史。
      2. 输入框可以跟着内容一起向下滚动，而不是固定在底部
        主文档把 transcript 和 composer 当成同一份可滚动文档来排。composer 可以无界增高，不会在输入框内部再开一层滚动。这种布局在主屏幕 + 固定底栏的模型里很难做干净；在 altscreen 里则可以按帧重算。
      3. 退出后的「回看」可以做成显式选择
        altscreen 的代价是：会话进行中，终端模拟器自己的 scrollback 里通常看不到 TUI 内部帧。Hunea 不把「历史一定要堆在终端滚动缓冲里」当成默认，而是提供可选的退出回放：配置里的 print_transcript_on_exit 为 true 时，退出后会把当前对话以 terminal replay 形式打回主屏幕 scrollback。默认是关闭的，因为很多人只是结束一次会话，并不想在 shell 里再刷出一整段 transcript。

      其实一开始我也考虑想做 Codex CLI 那样的底部重绘，然后内容都进终端模拟器的原生 scrollback 区域。因为好处很多：

      1. 鼠标选区、复制等都是终端模拟器原生的功能，操作起来非常自然而且符合用户的使用习惯
      2. 滚动流畅。因为滚动什么的终端模拟器原生就处理好了，所以非常自然，包括那个滚动加速度等优化都很舒服
      3. 一时想不出来了……

      但是后面还是选择没有做，原因和很简单：

      1. 工作量太大了
      2. 如果没有处理好，就会有各种奇怪的问题
      3. 有时候会出现一些意外的问题

      哪怕是成熟如 Claude Code 都提供了 altscreen 的切换选择，好巧不巧的是，前段时间我在使用 Claude Code 的时候，就碰到了问题：

      index-1

      我的 Claude Code 版本是 2.1.21x，已经很新了，但是还是会有类似的问题出现。Codex CLI 好些，但是也会出现问题。而且，在部分终端模拟器中，我观察到还会有 scrollback 内容丢失的情况，我猜测是内容推入 scrollback 后，因为终端模拟器或者其他的兼容性原因，导致一段很长的内容中会丢失中间部分内容。

      不过 Codex CLI 在大约几个月前的版本更新中加入了一个新的功能，忘记叫什么名字了（刚刚看了一下自己的 v0.144.1 版本的 Codex CLI 也没有看到这个功能了），可以实现在终端模拟器显示窗口大小变化后重建内容。也算是变相解决了这类问题，我只要改变一下我的终端模拟器显示窗口大小就好了……

      所以我还是选择了 altscreen 的方式，然后尽可能的做各种优化，使其性能和效果上更接近于底部重绘的体验。现在的性能倒还是不错的。未来也会继续打磨。