00. 怎么读这份文档

全屏与精简

交互式 TUI 有两种渲染模式。大多数输入和斜杠命令在两种模式里都能用。少数浮层只存在于其中一种，所以你读到的某条命令可能要切换模式后才会出现在菜单里。

这是屏幕选择，不是另一个产品。无界面（matcha -p）和 matcha agent stdio 没有 TUI，因此会忽略这些参数。

两种模式

全屏是默认：Matcha CLI 接管终端（备用屏幕），绘制回滚区和提示符，并承载教程、主题选择器和看板等浮层。

--no-alt-screen 沿用同一套全屏命令，但在现有终端里行内绘制，而不是切换屏幕。对 /theme、/tutorial 和其他门控命令来说，行内仍算全屏。它不是精简模式。

精简（--minimal / /minimal）是实验性的、以终端回滚为本的模式。完成的块进入终端自己的回滚区。一小块固定区域放着提示符和正在进行的回合。精简模式使用你终端的调色板，所以 /theme 没有可驱动的对象。

模式门控命令在无法运行它们的模式里会从 / 和 Ctrl+P 中隐藏。如果你仍然输入，Matcha CLI 会说明原因，并指出切换方式（/fullscreen 或 /minimal）或该模式内的替代操作。

用指定模式打开

matcha                 # default: fullscreen (unless you persisted minimal)
matcha --fullscreen    # this session: standard TUI
matcha --minimal       # this session: scrollback-native
matcha --no-alt-screen # this session: inline, still the fullscreen command set

这两个参数只作用于当前会话。它们不会写入 config.toml。下一次普通的 matcha 仍跟随 [ui] screen_mode（或内置默认值：全屏）。

不退出即可切换

在活动会话里输入：

/minimal

仅在全屏时提供（包括 --no-alt-screen）。Matcha CLI 会在同一段对话上重新拉起分页器。它不会改动 config.toml。一条横幅会提醒你如何切回去。

/fullscreen

别名：/full。仅在精简模式时提供。同样只重新拉起当前会话。

如果输入的是当前已经处于的模式，Matcha CLI 会说 You're already in minimal mode.（全屏同理）。

让默认值固定下来

之后每次不加参数的 matcha：

输入 /settings（别名 /config、/preferences、/prefs）。
把 Default screen mode 设为 Fullscreen 或 Minimal。

或编辑 ~/.matcha/config.toml：

[ui]
screen_mode = "minimal"    # or "fullscreen"

/minimal 和 /fullscreen 仍然不会写入这个键。只有 /settings 或这个文件会写。

只在一种模式里存在的命令

仅全屏（在精简模式里隐藏；用 /fullscreen 才能用）：

命令	为什么需要全屏
`/find`	TUI 内查找浮层
`/jump`	跳转列表
`/timeline`	时间线浮层
`/theme`（别名 `/t`）	Matcha CLI 绘制主题；精简模式使用终端调色板
`/tutorial`（别名 `/tour`、`/onboarding`）	教程浮层在精简模式里没有宿主
`/workflows`	workflows 运行看板
`/dashboard`（别名 `/agents-dashboard`、`/sessions`）	看板浮层

/dashboard 在 MATCHA_AGENT_DASHBOARD=0 或 [dashboard].enabled = false 时也会关闭。

仅精简（在全屏里隐藏）：

命令	为什么只在精简模式
`/expand`	全屏用 `Tab` 再按 `→` 展开一个块
`/edit-prompt`	给空的输入框打开外部编辑器（先 `$VISUAL`，再 `$EDITOR`，再 `vi`）

要编辑已有草稿、而终端抢走了 Ctrl+G 时，打开命令面板并选择 Edit Prompt in External Editor。输入 /edit-prompt 会替换当前输入框，所以它总是从空开始。

两种模式都有：/、/help、Ctrl+P、/docs、/new、/model、/compact、/quit，以及其余未门控的目录。/help 在精简模式里特别有用，因为那里没有始终可见的快捷键页脚。

拒绝长什么样

在精简模式里输入：

/theme isn't available in minimal mode (minimal renders with your
terminal's own palette). Run /fullscreen to switch this session.

在全屏里输入：

/expand isn't available in fullscreen mode — press Tab to focus the
scrollback, then → on the block.

试一试

matcha → 发送一条短提示以便有会话 → /minimal。
确认 /theme 和 /tutorial 已从 / 里消失。仍然输入 /theme，阅读拒绝说明。
/fullscreen → /tutorial（或 /tour）打开第一小时浮层。
默认模式请留在全屏，除非你长期待在终端回滚里，并想走 /settings → Default screen mode → Minimal。