Terminal Chat (TUI)
终端聊天，也称为 TUI，是 OpenSquilla 的命令行聊天界面。当你想要在 shell 中进行交互式对话时使用它，尤其是在本地项目目录中工作时。
Start Chat
启动终端聊天：
opensquilla chat裸的 opensquilla chat 使用 auto：它可以启动一个兼容的全屏 host，否则会在进入 alternate screen 之前回退到 plain。当前 release 不发布或安装 companion，因此通过 release 安装的用户仍然使用 plain。--ui tui 是严格的：一个缺失或不兼容的 host 是一个清晰的启动错误。--ui plain 显式选择救援 renderer。
从一个已验证的源码检出，裸聊天可以打印准备和启动源 host 所需的两条开发命令。已安装的 wheels、没有 Git worktree 的源码归档、Windows 以及不受支持的布局会保持安静，而不是宣传不可用的 release 资产。
对于隐式的本地配置，聊天会在接管终端之前检查就绪状态，并在必要时启动由生命周期管理的 Gateway。一个显式的 OPENSQUILLA_GATEWAY_URL 是由 operator 拥有的：聊天绝不会静默地启动一个本地 Gateway 作为替代。
你仍然可以显式管理本地 Gateway：
opensquilla gateway start --json
opensquilla chat为会话使用指定的 model：
opensquilla chat --model gpt-5.4-mini恢复一个已有的会话：
opensquilla chat --session <session-key>在诊断启动时显式选择终端呈现方式：
opensquilla chat --ui tui # require the full-screen host
opensquilla chat --ui plain # minimal rescue renderer终端聊天是交互式的，需要一个真实的 TTY。对于脚本、管道、CI 或一次性自动化，请使用：
opensquilla agent -m "Inspect this workspace"Gateway and Standalone Modes
默认情况下，opensquilla chat 使用 gateway-backed 聊天路径，因此它会与 Web UI 及其他 gateway 客户端共享会话、配置、审批、用量以及 model/provider 状态。
Reading the TUI
一个空的 session 以一个响应式的 OpenSquilla wordmark、一行定位文字、已解析的 Agent/model/workspace/Gateway context 以及开始所需的快捷键开始。在宽敞的宽度下，wordmark 使用一个六行的显示字面；在 80×24 时它变为一个两行的紧凑字面，而在病态的窄/短窗格中则回退到纯产品名称。这段介绍属于空的 transcript：它随工作滚动消失，在恢复规范历史时不存在，并在 /new 或 /reset 产生一个空 session 之后返回。
在 Gateway bootstrap 完成后，一个固定的 identity header 会在 transcript 上方保持产品、任务、规范 Agent identity、共享 surface 以及 Gateway 状态可见。Agent cards 使用相同的规范 identity，而不是一个 TUI 本地的别名。该 header 是显示宽度感知的：在一个小终端上它会丢弃较低优先级的字段，而不是换行进入对话。
context 的其余部分会适配终端宽度：
- 在 132 列或更宽时，一条 30–36 列、全高度的 context rail 显示 Agent、任务、workspace、surface、model、权限、Gateway、队列、context 和路由状态。transcript 和 composer 都在它旁边内缩，因此内容绝不会绘制在 rail 之下。该 rail 是这一条线性 transcript 的 context，而不是第二个滚动的对话。
- 在 132 列以下时，rail 折叠为 footer 中一条紧凑的、按优先级排序的 strip。Agent、权限、当前的 Router decision 以及 Gateway 状态优先；较低优先级的值在放不下时可能被省略。正常的 decisions 仍然显示为
router cN confidence%，而 observe/fallback routes 使用警告样式。
提交一个 prompt 会立即在 transcript 中创建一条实时的 Thinking 行。在 provider 的首个 event 之前它显示 Waiting for model output…；如果 provider 暴露 reasoning，每一个真实的 reasoning delta 会替换那条等待行并原地流式显示。最新的一行具有更强的对比度，同时一个有界的滚动窗口保持较早的 context 可见。不暴露任何 reasoning 的 providers 绝不会获得虚构的思考文本：一个亚秒级的等待会在输出开始时消失，而一个较长的等待可能会留下一条诚实的 Worked for Ns 收据。真实的 reasoning 以 Thought for Ns 结束。
已完成的 reasoning 默认保留其最新的至多八个可视行。因此短的 reasoning 无需另一个操作即可完全阅读；较长的 reasoning 保留最近的 context 外加一个精确的较早隐藏行计数。这个固定的上限避免了在终端高度变化时对已完成历史进行重排。已完成的 thinking 叙述和 tool activity 保持紧凑。按 Ctrl+O 可以在 transcript 上展开或折叠传递给 TUI 的完整 detail，包括 thinking 和 reasoning deltas 以及 tool 参数、进程更新、结果和错误。该快捷键不会将焦点移出 composer。
一次已执行的 model ensemble 显示为一条实时的 Ensemble · n/m complete 行。Ctrl+O 展开其成员 models、providers、状态、时长、token/成本 metadata 和错误。最终的收据会随 session 历史恢复；原始的候选答案不会被渲染。
Gateway 聊天暴露一个共享的 model 策略，具有三个状态：direct、router 和 ensemble。运行 /strategy 打开选择器，或使用 /strategy direct|router|ensemble|status 进行一步控制。兼容性命令 /router on|off|status 和 /ensemble on|off|status 作用于同一个状态。Gateway 持久化该选择并将其广播给 WebUI 和其他 TUI 客户端。在一个 turn 正在 streaming 时做出的更改是立即的控制平面输入：它不会进入 prompt 队列或中断正在运行的 turn，并应用于下一个被接受的 turn。footer 始终保留已配置的策略；每个 Turn 只显示实际为该 Turn 执行的 Router decision 或 Ensemble 进度。
composer 在一个 turn streaming 时保持可用。Enter 请求在正在运行的 Gateway turn 的下一个安全 tool 边界处进行 steer；如果该 turn 已经越过了那个边界，TUI 会这样说明并将输入保留为下一个排队的 turn。Tab 显式地将草稿排入队列（补全菜单的 Tab 仍会先补全所选项）。UI 本地命令继续立即运行。
对于长会话，Ctrl+O 切换完整的 thinking/tool detail，Ctrl+L 强制一次干净的完整重绘，而 Ctrl+G 或 Ctrl+End 在阅读较早的回滚内容后跳回最新输出。统一 diff 输出会获得一个更改文件/新增/删除的摘要和语义化的行颜色，同时保留其完整的原始 tool 结果。
折叠是呈现，而非删除：TUI 保留它收到的每一个 delta，包括在一个块被标记为完成之后的迟到 deltas。上游 provider 或 Gateway 压缩仍然可以限制被传递的内容；关于那个单独的契约，见 features/tool-compression.md。
当你想要不依赖 gateway 守护进程的直接终端聊天时，使用 standalone 模式：
opensquilla chat --standalonestandalone 模式接受用于本地文件和工具工作的 workspace 标志：
opensquilla chat --standalone --workspace /path/to/project --workspace-strict在 gateway 模式下，终端聊天会忽略 --workspace。请使用 gateway 可见的路径配合 /path，或使用 /file 从 CLI 机器上上传本地文件。
Common Commands
在终端聊天中输入 /help 可以查看当前模式支持的命令。输入 / 会打开精选的命令面板。继续输入可对规范名称和别名进行模糊搜索；兼容性命令不在默认面板中，但仍可被搜索到。Enter 会运行一条完整高亮的命令，而 Tab 只会补全它，以便你添加参数。带必需参数的命令在参数出现之前绝不会由补全提交。
Slash 控制和查询在命令平面上执行：它们不会成为用户的 Prompt cards，也不会进入 Turn 队列。诸如 /file、/image、/path 和 /meta <name> 之类的命令有意创建一个 Turn，因为它们的目的是发送 model 输入。
gateway 和 standalone 聊天中都可用的命令包括：
| Command | Purpose |
|---|---|
/help | Show command help. |
/status or /session | Show the active session and model. |
/new [title] | Start a new session. |
/model [auto|status|name] | Inspect or set the session model; Gateway TUI opens a picker when no argument is given. |
/cost | Show usage for the current chat state. |
/clear or /reset | Clear the current session context. |
/compact or /cmp | Compact long context when possible. |
/save [path] | Save the transcript. |
/image <path> [prompt] | Send an image file with an optional prompt. |
/path <path> [prompt] | Attach a file by path. |
/theme [name] | Open or change terminal theme settings. |
/quit or /exit | Leave chat. |
仅 gateway 可用的 model 策略控制：
| Command | Purpose |
|---|---|
/strategy [direct|router|ensemble|status] | Open the shared strategy picker, switch strategy, or inspect canonical state. |
/router [on|off|status] | Open the shared strategy picker, enable Router, select direct mode, or inspect canonical state. |
/ensemble [on|off|status] | Open the same picker, enable Model Ensemble, select direct mode, or inspect canonical state. |
standalone 聊天会将这些控制报告为不可用，而不是维护第二份本地的 Router/Ensemble 配置。
gateway-backed 聊天还支持会话和操作命令：
| Command | Purpose |
|---|---|
/sessions [limit] | Open a searchable recent-session picker in TUI (table in plain mode). |
/resume [id] | Open the picker, or resume a specific session. |
/delete <id> | Delete a session. |
/usage | Show aggregate usage. |
/meta | List MetaSkills. |
/meta <name> | Run a MetaSkill in the current session. |
/file <path> [prompt] | Upload a local file and send it with a prompt. |
/permissions ... | Inspect or change interactive permission mode. |
/approvals ... | Inspect or reset approval state. |
/models 和 /forget 仍然是可执行的兼容性命令，但从默认面板中隐藏。使用 /model 进行 session-model 选择，使用 /approvals 查看当前的 approval 状态。
standalone 聊天支持上面的核心命令，但 /models、/meta 以及 gateway 范围的用量或审批命令需要 gateway 模式。
Files and Images
对图像文件使用 /image：
/image ./screenshot.png Describe the UI issue当文件路径对运行中的聊天进程可见时使用 /path：
/path ./docs/quickstart.md Summarize the setup steps在使用远程 gateway 的 gateway 模式下，优先使用 /file，这样 CLI 会在发送该 turn 之前先上传本地文件：
/file ./report.pdf Extract the action itemsTUI Host and Source Development
当前 release 不包含平台特定的 TUI host。本仓库中的 companion 包和 builders 是开发验证机制，而不是已发布的资产。一次未来的分发 rollout 必须保持 core 和 host 处于同一版本，并单独落地。
Maintainers 可以在开发时显式使用源 host：
bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package
OPENSQUILLA_TUI_DEV_SOURCE_HOST=1 uv run opensquilla chat --ui tuiOPENSQUILLA_TUI_BACKEND 是一个内部运行时交接，而不是一个公共选择器；裸聊天会忽略任何预先存在的值，因此陈旧的 dotenv 配置无法禁用它的 plain 回退。OPENSQUILLA_TUI_DEV_SOURCE_HOST=1 是运行 Bun/源而不是一个已安装 companion 的显式许可。使用公共的 --ui 选项来选择呈现方式。
关于 OpenTUI backend 状态、Router HUD 详情以及 replay benchmarks，请阅读 features/tui-frontend.md。仅当你在运行终端渲染的 maintainer 集成测试时，才阅读 tui-real-terminal-harness.md。
Related Pages
cli.md完整的 CLI 参考。sessions.md列出、恢复、导出和删除会话。approvals-and-permissions.md权限配置文件和审批工作流。features/meta-skill-user-guide.md/meta工作流。features/tui-product-contract.md所有权、共享 session、回退以及 legacy-freeze 规则。
Docs index · Product guide · Improve this page · Report a docs issue