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计数。
在切换器中:
↑/↓移动选择;鼠标点击也可选择行。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 会自动检测浅色终端并相应切换到浅色主题。检测分三层进行:
KOPI_TUI_THEME环境变量——优先级最高。取值:light、dark,或 6 位原始背景十六进制色值(例如ffffff、1a1a2e)。COLORFGBG环境变量——经典的“我的背景色是什么?”提示,由 xterm 系终端使用。- 通过 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 仍在加载中。你可以输入 —— 消息会排队,并在就绪后发送。 |
ready | Agent 处于空闲状态,正在接受输入。 |
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 会打印诊断信息并回退 —— 不会把你卡住。