跳到主要内容

TUI

TUI 是 Kopi Agent 的现代化前端 —— 一个由与经典 CLI 相同的 Python 运行时驱动的终端 UI。相同的 agent、相同的会话、相同的斜杠命令;只是提供了更清爽、响应更灵敏的交互界面。

这是交互式运行 Kopi Agent 的推荐方式。

启动​

# Launch the TUI
kopi --tui

# Resume the latest TUI session (falls back to the latest classic session)
kopi --tui -c
kopi --tui --continue

# Resume a specific session by ID or title
kopi --tui -r 20260409_000000_aa11bb
kopi --tui --resume "my t0p session"

# Run source directly — skips the prebuild step (for TUI contributors)
kopi --tui --dev

你也可以通过环境变量启用它:

export KOPI_TUI=1
kopi # now uses the TUI
kopi chat # same

或者在 ~/.kopi/config.yaml 中将其设为持久默认值:

display:
interface: tui # "cli" (default) or "tui"

启用 display.interface: tui 后,单独运行 kopi(以及 kopi chat)会启动 TUI。显式标志始终优先 —— 运行 kopi --cli 可在单次调用中回退到经典 REPL,或者在配置默认值为 cli 时使用 kopi --tui / KOPI_TUI=1 强制启动 TUI。

经典 CLI 仍是随附发布的默认方式。CLI 接口中记录的所有内容 —— 斜杠命令、快捷命令、skill 预加载、个性(personality)、多行输入、中断 —— 在 TUI 中的工作方式完全一致。

为什么选择 TUI​

  • 即时首帧 —— 在应用完成加载之前横幅就已绘制,因此 Kopi Agent 启动时终端不会显得卡死。
  • 非阻塞输入 —— 在会话就绪前即可输入并排队消息。agent 一上线,你的第一条提示就会立即发送。
  • 丰富的浮层 —— 模型选择器、会话选择器、审批与澄清提示都以模态面板的形式渲染,而非内联流程。
  • 实时会话面板 —— 工具和 skill 会随着初始化逐步填充。
  • 便于鼠标操作的选择 —— 拖动即可高亮文本,并使用统一的背景色,而非 SGR 反色。用终端自带的复制手势即可复制。
  • 备用屏幕渲染 —— 差分更新意味着流式输出时不会闪烁,退出后也不会残留滚动历史。
  • 输入区便利功能 —— 长片段的内联粘贴折叠、Cmd+V / Ctrl+V 文本粘贴并回退到剪贴板图片、括号粘贴保护,以及图片/文件路径附件的规范化。

同样的皮肤(skin)和个性(personality)均适用。可在会话中途通过 /skin ares、/personality pirate 切换,UI 会实时重绘。可自定义键的完整列表,以及哪些适用于经典 CLI、哪些适用于 TUI,请参阅皮肤与主题 —— TUI 支持横幅调色板、UI 颜色、提示符字形/颜色、会话显示、补全菜单、选中背景色、tool_prefix 和 help_header。

可折叠的横幅区块​

TUI 启动横幅将运行时信息归为四个可折叠区块,每个区块标题旁都渲染有一个 ▸ / ▾ 箭头图标:

区块默认状态
工具展开
技能收起
系统提示收起
MCP 服务器收起

点击区块标题(或其箭头图标)的任意位置即可切换。工具列表默认展开,因为这是会话开始时最常查看的区块;技能、系统提示和 MCP 服务器默认收起,这样即使你安装了几十个 skill 或接入了许多 MCP 服务器,横幅也能保持紧凑。状态仅保存在当前横幅实例中,下次启动会重置为默认值。

系统要求​

  • Node.js ≥ 20 —— TUI 作为由 Python CLI 启动的子进程运行。kopi doctor 会对此进行检查。
  • TTY —— 与经典 CLI 一样,通过管道传入 stdin 或在非交互式环境中运行时会回退到单次查询模式。

首次启动时,Kopi Agent 会将 TUI 的 Node 依赖安装到 ui-tui/node_modules(一次性操作,只需几秒)。之后的启动会很快。如果你拉取了新的 Kopi Agent 版本,当源文件比 dist 更新时,TUI bundle 会自动重新构建。

外部预构建​

随附预构建 bundle 的发行版(Nix、系统包)可以让 Kopi Agent 指向它:

export KOPI_TUI_DIR=/path/to/prebuilt/ui-tui
kopi --tui

该目录必须包含 dist/entry.js。

按键绑定​

按键绑定与经典 CLI完全一致。仅有以下行为差异:

  • 鼠标拖动使用统一的选中背景色高亮文本。
  • Cmd+V / Ctrl+V 先尝试普通文本粘贴,然后回退到 OSC52/原生剪贴板读取,最后当剪贴板或粘贴内容解析为图片时进行图片附加。
  • /terminal-setup 会安装本地 VS Code / Cursor / Windsurf 终端绑定,以在 macOS 上获得更好的 Cmd+Enter 以及撤销/重做一致性。
  • 斜杠自动补全以带描述的浮动面板形式打开,而非内联下拉菜单。
  • Ctrl+X 打开实时会话切换器。当高亮的是排队消息(在 agent 仍在运行时发送的消息)时,它仍会删除该排队消息。Esc 则取消编辑并取消高亮,且不删除内容。
  • Ctrl+G / Ctrl+X Ctrl+E —— 在 $EDITOR 中打开当前输入缓冲区,用于编写多行/长提示;保存并退出后,内容会作为提示发送回去。

斜杠命令​

所有斜杠命令的工作方式保持不变。其中少数由 TUI 接管——它们会生成更丰富的输出,或以浮层而非内联面板的形式呈现:

命令TUI 行为
/help显示按类别分组的命令浮层,可用方向键浏览
/sessions(别名 /switch)实时会话切换器——列出当前打开的 TUI 会话,在它们之间切换、关闭,或再启动一个新会话
/model按 provider(服务提供商)分组的模态模型选择器,并附带费用提示
/skin实时预览——浏览主题时立即应用主题变更
/details切换冗长的工具调用详情(全局或按区块)
/usage丰富的 token / 费用 / 上下文面板
/agents(别名 /tasks)可观测性浮层——实时 subagent 树,带终止/暂停控制、每个分支的费用 / token / 文件汇总,以及逐轮历史记录
/reload将 ~/.kopi/.env 重新读取到正在运行的 TUI 进程中,使新添加的 API key 无需重启即可生效
/mouse [on|off|toggle|wheel|buttons|all]在运行时选择鼠标跟踪预设(同时会持久化到 config.yaml 中的 display.mouse_tracking)。wheel(1000+1006)保留滚轮滚动,同时去掉那些会让 tmux 在提示行上方不断刷屏 "No image in clipboard" 的悬停事件;buttons 增加了拖拽选择;all 是默认模式,带由悬停驱动的 UI。

其他所有斜杠命令(包括已安装的 skill、快捷命令和人格切换)都与经典 CLI 的行为完全一致。参见斜杠命令参考。

实时会话切换器​

当你想让一个终端充当多个 TUI 会话的调度器时,可以使用实时会话切换器。它只列出当前在这个 TUI 进程中处于活动状态的会话;已关闭的会话仍保留为已保存的转录记录,随时可通过 /resume 或 kopi --tui --resume <id-or-title> 重新打开。

可通过以下任一方式打开:

  • 在 TUI 中使用 Ctrl+X。
  • /sessions 或 /switch。
  • /sessions new 立即创建一个全新的实时会话。
  • 点击状态栏中的 N live sessions 计数。
Kopi Agent TUI Session Orchestrator with one live session and a +new row

在切换器中:

  • ↑ / ↓ 移动选择;鼠标点击也可选择行。
  • Enter 切换到所选的实时会话。
  • Ctrl+D 关闭所选的实时会话。
  • Ctrl+N 启动一个空白的实时会话。
  • Ctrl+R 刷新实时会话列表。
  • Esc 关闭切换器。
  • 选择 +new,输入提示词,然后按 Enter 派发一个新的实时会话。如果想仅为该新会话选择模型,请先按 Tab。

LaTeX 数学公式渲染​

TUI 的 markdown 管线会渲染行内 LaTeX 数学公式:$E = mc^2$ 和 $$\frac{a}{b}$$ 会以 Unicode 格式的数学形式呈现,而不是原始 TeX 源码。行内公式和块级公式均适用;不支持的语法会回退为在代码跨度中显示字面 TeX,从而保持可复制性。

此功能默认始终开启——无需任何配置。经典 CLI 保留原始 TeX。

浅色终端检测​

TUI 会自动检测浅色终端并相应切换到浅色主题。检测分三层进行:

  1. KOPI_TUI_THEME 环境变量——优先级最高。取值:light、dark,或 6 位原始背景十六进制色值(例如 ffffff、1a1a2e)。
  2. COLORFGBG 环境变量——经典的“我的背景色是什么?”提示,由 xterm 系终端使用。
  3. 通过 OSC 11 探测终端背景色——适用于未设置 COLORFGBG 的现代终端(Ghostty、Warp、iTerm2、WezTerm、Kitty)。

如果无论使用何种终端都想永久使用浅色主题:

export KOPI_TUI_THEME=light

忙碌指示器样式​

状态栏的忙碌指示器可插拔——默认情况下,在 agent 工作期间每 2.5 秒轮换一次 Kopi Agent 的 kawaii 表情配色。可通过 config 或 /indicator 斜杠命令选择不同的样式:

display:
tui_status_indicator: kaomoji # kaomoji | emoji | unicode | ascii

或在会话内:/indicator emoji(等等)。随附的样式都带有匹配的字形宽度,因此轮换时状态栏的其余部分不会抖动。

自动恢复会话​

默认情况下,kopi --tui 每次启动都会开启一个全新会话。若想自动重新附加到最近的 TUI 会话(当终端或 SSH 连接意外断开时很有用),可选择启用:

export KOPI_TUI_RESUME=1          # most-recent TUI session
# or:
export KOPI_TUI_RESUME=<session-id> # specific session

取消设置该变量,或显式传入 --resume <id>,即可按次启动覆盖此行为。

状态行​

TUI 的状态行会实时跟踪 agent 状态:

状态含义
starting agent…Session ID 已激活;工具和 skill 仍在加载中。你可以输入 —— 消息会排队,并在就绪后发送。
readyAgent 处于空闲状态,正在接受输入。
thinking… / running…Agent 正在推理或运行工具。
interrupted当前回合已取消;按 Enter 重新发送。
forging session… / resuming…初始连接或 --resume 握手。

每个皮肤的状态栏颜色和阈值与经典 CLI 共享 —— 有关自定义,请参阅皮肤。

状态行还会显示:

  • 带 git 分支的工作目录 —— ~/projects/kopi-ai-agent (docs/two-week-gap-sweep)。当你在另一个终端中 git checkout 时,分支后缀会更新(基于 mtime 缓存),因此 TUI 反映的是你实际生效的分支,而不是启动时的分支。
  • 每次提示词的耗时 —— 回合运行期间显示 ⏱ 12s/3m 45s(实时更新),回合完成后冻结为 ⏲ 32s / 3m 45s。第一个数字是距上一条用户消息的时间;第二个是会话总时长。每次新的提示词都会重置。
  • 🗜️ N —— 当前会话已自动压缩的次数。首次压缩触发后出现。
  • ▶ N —— 此会话中当前正在运行的 /background 任务数量。只要有至少一个任务在执行就会显示。
  • ⚠ YOLO —— 当 YOLO 模式开启时(kopi --yolo、/yolo 或 KOPI_YOLO_MODE=1)显示的可见警告。该徽章同样会出现在启动横幅中,因此你不可能在未注意到的情况下启动一个自动批准的会话。

配置​

TUI 遵循所有标准的 Kopi Agent 配置:~/.kopi/config.yaml、配置文件(profiles)、个性(personalities)、皮肤(skins)、快捷命令、凭据池、memory provider、工具/skill 启用项。不存在 TUI 专用的配置文件。

少数几个键专门用于调整 TUI 的呈现:

display:
skin: default # any built-in or custom skin
personality: helpful
details_mode: collapsed # hidden | collapsed | expanded — global accordion default
sections: # optional: per-section overrides (any subset)
thinking: expanded # always open
tools: expanded # always open
activity: collapsed # opt back IN to the activity panel (hidden by default)
mouse_tracking: all # off | wheel | buttons | all (or true/false for back-compat).
# wheel — 1000+1006 (scroll + click; no drag, no hover —
# recommended inside tmux to silence the prompt-row
# "No image in clipboard" spam from hover events)
# buttons — adds 1002 for terminal-side drag selection
# all — adds 1003 for hover (scrollbar paginate-on-hover,
# link mouseenter, etc.)

运行时开关:

  • /details [hidden|collapsed|expanded|cycle] —— 设置全局模式
  • /details <section> [hidden|collapsed|expanded|reset] —— 覆盖某个部分 (部分包括:thinking、tools、subagents、activity)

默认可见性

TUI 带有针对各部分的固执默认设置,会将回合作为实时逐句记录流式呈现, 而不是一堆箭头符号:

  • thinking —— 展开。推理内容随模型输出内联流式显示。
  • tools —— 展开。工具调用及其结果以打开状态渲染。
  • subagents —— 回落到全局的 details_mode(默认折叠在 箭头符号下 —— 在实际发生委派之前保持安静)。
  • activity —— 隐藏。环境元信息(网关提示、终端一致性 提醒、后台通知)对大多数日常使用来说都是噪音。工具 失败仍会在对应的失败工具行上内联渲染;当所有面板 都被隐藏时,环境错误/警告会通过浮动警报兜底显示。

各部分的覆盖设置优先于该部分的默认值和全局的 details_mode。要重新调整布局:

  • display.sections.thinking: collapsed —— 将思考内容重新放回箭头符号下
  • display.sections.tools: collapsed —— 将工具调用重新放回箭头符号下
  • display.sections.activity: collapsed —— 重新启用活动面板
  • /details <section> <mode> 在运行时

任何在 display.sections 中显式设置的项都会覆盖默认值,因此 现有配置可以继续不变地工作。

会话​

会话在 TUI 和经典 CLI 之间共享 —— 两者都会写入同一个 ~/.kopi/state.db。你可以在其中一个中开始会话,在另一个中恢复。会话选择器会显示来自两个来源的会话,并附带来源标签。

有关生命周期、搜索、压缩和导出,请参阅会话。

TUI 如何与其网关通信​

默认情况下,TUI 会启动自己的进程内网关,因此每个 TUI 实例都是自包含的 —— 无需任何配置。

你可能会在代码库或日志中看到 KOPI_TUI_GATEWAY_URL 环境变量。这是 web 仪表板的内部接线细节,而非面向用户的远程连接开关。当你打开仪表板的“Chat”标签页(kopi dashboard → /chat)时,仪表板的 web 服务器会启动一个嵌入式 TUI 子进程,并注入 KOPI_TUI_GATEWAY_URL,使该子进程通过回环 WebSocket(/api/ws)连接到仪表板自身的进程内 tui_gateway。/api/ws 端点仅存在于仪表板服务器内部(kopi_cli/web_server.py),且绑定到该进程的生命周期和认证。

不存在通用的“将任意 TUI 指向任意独立网关端口”模式。特别是,OpenAI 兼容的 API 服务器(kopi gateway / api_server 平台)不提供 /api/ws —— 它是模型后端接口(/v1/chat/completions、/v1/models 等),刻意不暴露 TUI 的 JSON-RPC 控制通道。将 KOPI_TUI_GATEWAY_URL 设置为该端口会返回 404。

如果你希望多个界面共享同一组会话,请使用共享的 ~/.kopi/state.db(参见会话)或 web 仪表板的嵌入式聊天(参见 Web 仪表板)—— 而不是手动设置网关 URL。

切换回经典 CLI​

启动 kopi(不带 --tui)时默认使用经典 CLI。要让某台机器优先使用 TUI,可在 ~/.kopi/config.yaml 中设置 display.interface: tui(持久生效),或在 shell 配置文件中设置 KOPI_TUI=1(按 shell 生效)。要切回,设置 interface: cli / 取消设置该环境变量,或临时传入 kopi --cli。

如果 TUI 启动失败(没有 Node、缺少 bundle、TTY 问题),Kopi Agent 会打印诊断信息并回退 —— 不会把你卡住。

另请参阅​

  • CLI 接口 —— 完整的斜杠命令和键绑定参考(共享)
  • 会话 —— 恢复、分支和历史记录
  • 皮肤与主题 —— 为主题横幅、状态栏和覆盖层设置主题
  • 语音模式 —— 在两种界面中均可使用
  • 配置 —— 所有 config 键