用户指南#

文档索引（英文） · 项目概览

🇺🇸 English · 🇨🇳 简体中文 · 🇭🇰 繁體中文 · 🇯🇵 日本語 · 🇰🇷 한국어 · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇧🇷 Português

本文译自英文版 USER-GUIDE.md，对应提交 68169b9。 此后英文版如有更新，或两者有出入，以英文版为准。界面名称按 Corta 的简体中文界面书写； 配置项、命令和代码保持原文。

Corta 能做的一切，以及从哪里找到它。每一节都会说明功能在哪里——菜单、快捷键还是设置—— 并链接到包含细节的参考文档。文中的快捷键是默认值，除“查找下一个”和“查找上一个”外都可以修改 （键盘快捷键）。

• 安装与更新
• 从其他终端迁移
• 窗口、标签页和窗格
• 文字、字体和主题
• 个性化终端
• 会话结束时
• 回滚、搜索和选择
• 链接与文件引用
• Shell 集成
• 工作目录
• 目录补全（zsh）
• 历史命令建议（zsh）
• 远程工作：SSH 与 SFTP
• 终端里的图片
• 命令面板
• macOS 集成
• 速度与电池
• 设置与配置文件
• 键盘快捷键
• 出问题时
• 编码代理状态与程序通知
• 使用 OSC 扩展的程序

安装与更新#

Corta 需要 macOS 26.0 或更高版本、Apple 芯片以及支持 Metal 4 的 GPU。 使用半虚拟化 GPU 的虚拟机无法渲染终端。从 GitHub Releases 下载 .dmg 及其 .sha256 文件，两者放在同一个文件夹里，打开映像前先在那里校验（把 x.y.z 换成下载的版本号）：

shasum -a 256 -c Corta-x.y.z.dmg.sha256
open Corta-x.y.z.dmg

把 Corta 拖进“应用程序”，然后推出映像。1.1.9 起的版本都是磁盘映像；1.1.8 及更早的版本保留原来的 ZIP。

正式版本都经过 Developer ID 签名和公证。如果 macOS 拒绝打开下载的文件，请按 故障排除操作。从其他位置启动时，Corta 会提出把自己移到 /Applications（suggest-applications-folder）。

更新。 Corta ▸ 检查更新… 会立即检查；除非设置了 update-auto-check = false， 后台每天检查一次。只有你同意，才会安装更新。

从其他终端迁移#

Corta 没有导入工具：它只读一个文本文件 ~/.config/corta/config，设置窗口编辑的也是这个文件。 多数习惯通过几个配置项就能延续。左栏是这个习惯在别的终端里的位置，右栏是 Corta 对应的配置项 （每一项的取值和生效时机见 Configuration，英文）。

Shell 集成。 标准的本地 zsh 会话无需改动启动文件就会加载 Corta 的钩子。如果你的 ~/.zshrc、 ~/.bashrc 或 config.fish 仍在加载其他终端的集成——iTerm2、WezTerm、Visual Studio Code 的—— 设置 ▸ 终端 ▸ Shell 集成 会提示可能冲突；两者都可能输出提示符标记。见 Shell 集成。

TERM。 Corta 声明为 xterm-256color（D08）。已经能配合 iTerm2 或 Terminal.app 工作的远程主机无需任何改动；为 xterm-ghostty 或 xterm-kitty 设置的主机则会拿到这个通用值。

复制、关闭、远程标记等细节上的不同，集中在 故障排除 → 与其他终端不同的行为。

窗口、标签页和窗格#

标签页位于标题栏这一行，紧挨着窗口的关闭、最小化和缩放按钮。每个标签页先显示其聚焦窗格正在运行的程序—— shell 是一个深色的提示符图块，其他程序用它自己的颜色——然后是名称和目录，靠左对齐。程序要真正接管终端——交互环境、编辑器、AI 代理、已连上的 ssh——才会显示它的图标； 只是运行并输出的命令（如 java -version、git status）保持提示符图块。有拆分窗格的标签页 会把其他窗格的图标叠在最前面那个后面，并略微转开；点击某个窗格，它的程序就会到最前面。把指针移到标签页上 会出现关闭按钮；拖动可以调整顺序，双击可以重命名，右键则有“新标签页”“重命名标签页…”“关闭标签页”和 “关闭其他标签页”。标签页多到放不下时，这一行可以左右滚动——在上面横向轻扫，或者转动鼠标滚轮—— 并且会跟随你选中的标签页。

• 直接在标题上重命名标签页：双击，或从右键菜单选择“重命名标签页…”。Return 保存，Esc 取消， 名称留空则恢复自动标题。自定义名称不会被 shell 输出覆盖，会话恢复后也会保留。标签页和终端的右键菜单 也有“新标签页”，工具栏的 + 按钮也能新建标签页；标签页这一行本身没有 +。
• 在窗口之间移动标签页。 把标签页向下拖出标签栏后松开，它就成为一个单独的窗口；拖到另一个窗口的标签栏上， 就移到那个窗口；其中的窗格继续运行。窗口 ▸ 将标签页移到新窗口 和标签页的右键菜单可以做前一件事， 窗口 ▸ 合并所有窗口 会把所有窗口的标签页收进最前面的窗口。标签栏可以滚动时，把标签页拖到它的任一端，这一行会跟着滚动。
• 最大化窗格是临时的：不会关闭任何东西，也不会打扰任何进程。
• 重新打开已关闭的窗格会恢复窗格的位置、大小和工作目录——但不会恢复其中运行的程序。
• 关闭仍有命令在运行的窗格前会先询问（confirm-close）。
• 恢复窗口。 退出再重新打开，每个窗口都会连同标签页、分屏、分隔线位置和每个窗格的工作目录一起回来 （restore-windows，默认开启）。每个窗格都会启动新的进程；终端文本和正在运行的任务不会恢复。
• 预设。 预设是在配置文件中定义的一组命名的 shell、目录和环境变量。Shell ▸ 使用预设新建窗格 会打开一个预设；按住 ⌥ 则在单独的窗口中打开（Presets）。
• 新窗口按 columns × rows 个字符格打开（默认 120 × 30）。

文字、字体和主题#

• 字体。 设置 ▸ 外观 ▸ 字体 列出系统等宽字体（默认）以及 Corta 能在网格上排版的所有已安装等宽字体， 分为两组：Apple 字体（随 macOS 提供，或在“字体册”中下载后的 Apple 按需字体）和你安装的。 菜单下方的一行说明所选字体的来源，以及它是否自带中日韩字符——这样的字体也会用其中日韩设计来绘制字母和符号， 例如位置偏高的 ~。配置文件中的 font-family 是同一个设置。font-size 默认 13 pt， 范围 10–24 pt，只取整数。这个页面会预览字体、颜色和光标。
• 字重和行距。 字重可选细体、常规（默认）或中等；字体没有该字重时使用常规，粗体文字始终使用字体自己的粗体。 行距为字号的 1.0–1.4 倍，默认 1.18；需要更高行高的字体会保留其行高，所以不会被裁切。 每种语言的每个字符都共用同一个字符格大小和同一条基线。
• 字体缺少的字符。 中文、日文和韩文来自 macOS 自带的字体：汉字按系统语言取自苹方-简、苹方-繁、 冬青黑体或 Apple SD Gothic Neo，假名无论语言都取自冬青黑体，谚文取自 Apple SD Gothic Neo。 想用自己的字体来绘制它们——比如字母用 Menlo、中文用更纱黑体或霞鹜文楷——请在 中日韩字体 （font-family-cjk）中选择。任何包含中日韩字符的已安装字体都会列出，无论是否等宽：它只绘制这些字符， 居中放在两个字符格里，字符格大小仍由主字体决定。Emoji 来自 Apple Color Emoji；若表情符号设为“尽量单色”， 则在 Apple Symbols 或 Menlo 有对应字形时使用文本字形。宽字符居中放在两个字符格里。 关闭 缺字时使用其他字体，就只显示所选字体，缺少的字形显示为方框。
• 歧义宽度字符。 设置 ▸ 终端 ▸ 歧义宽度字符 可以让 ±、§、希腊字母、西里尔字母等东亚歧义宽度字符 占两个字符格，以适配为中日韩终端编写的软件。它只作用于之后写出的输出；自行测量文本宽度的 shell 或编辑器 可能仍按一格计算。
• 下划线。 程序可以绘制单下划线、双下划线（SGR 21 或 4:2）和波浪线（SGR 4:3，Neovim 的诊断）； 点线和虚线按单下划线绘制。闪烁文字（SGR 5）会保留属性但不做动画。
• 缩放。 ⌘= / ⌘− / ⌘0 或双指捏合可以放大、缩小文字或恢复配置的大小，只作用于当前窗口。 缩放不会修改配置文件。改字体不会移动窗口或改变窗口大小：可见的行列数会重新适配窗口， 剩余不足一格的空间在最后一行下方显示为背景。
• 主题。 内置三个主题 corta、solarized 和 mono，各有浅色和深色变体；appearance = auto 会跟随 macOS 的切换。浅色模式和深色模式在 设置 → 主题 中分别选择主题——浅色用 Solarized、 深色用 Corta 写作 theme = light:solarized,dark:corta。切换时窗口会渐变到新的配色。你可以通过 显示 ▸ 主题编辑器… 或在配置文件中定义自己的主题， 也可以继承某个主题、只改几个颜色（Themes）。
• Unicode。 中文、日文和韩文文字占两列，并与其他内容对齐；emoji、组合符号、旗帜和 emoji 序列 各算一个字符簇。字体缺少的字符来自系统的回退字体。标准化的 emoji 呈现序列（文本字符后跟 VS16， 如 ⚠️ 或 ✍️）占两列；文本呈现保持窄宽度。
• 输入法。 拼音、假名、谚文以及 macOS 的其他所有输入法都在原位组字，候选窗口显示在光标旁边。
• 真彩色。 24 位色、256 色调色板、粗体、斜体、下划线、删除线、暗淡和反色。
• ⌥ 用作 Meta。 默认关闭，所以 ⌥ 输入的是键盘布局里的字符。想要 Emacs 风格的 Meta 键， 请设置 option-as-meta = true。
• 响铃。 窗格闪一下（bell = visual），或者发出声音（bell = audible）。

个性化终端#

光标外观#

打开设置（⌘,）→ 外观 → 光标。选择方块、竖线或下划线，需要的话再打开“光标闪烁”。默认是方块、不闪烁。 三种形状加上独立的开关，共六种组合。它们在配置文件中对应 cursor-shape 和 cursor-blink。 修改会作用于已打开的窗格。终端程序可以通过 DECSCUSR 临时选择自己的形状和闪烁；参数 0 或终端重置 会恢复为你配置的默认值。窗格处于非活动、隐藏或正在显示回滚内容时，闪烁会暂停。

输入法状态提示#

当前终端会在窗口右上角的工具栏显示一个小标记：确认处于直接输入时为 A，中文为 中，日文为 あ， 韩文为 한。其他输入法显示其语言代码。鼠标悬停可以看到输入法的完整名称。macOS 不报告内部输入模式的输入法 （包括带有私有中英切换的第三方输入法）会显示为中性标记。Corta 从不根据输入的文字猜测这种模式， 也从不更改输入法。

设置 ▸ 键盘与鼠标 ▸ 输入法状态提示 可选 自动（默认）、始终在聚焦窗格显示 或 关闭。 默认只为启用了非拉丁键盘布局或输入法的用户显示提示；只用拉丁键盘的用户界面保持简洁。 切回拉丁布局时，会在淡淡的背景上显示一个低调的 A——工具栏里是灰色，在提示符旁则使用主题自己的文字颜色。 在提示符旁，非拉丁布局和内置输入法的模式使用柔和的靛蓝色；在工具栏里所有输入法都是灰色，靠字形本身区分。在提示符旁时， 颜色跟随终端主题的深浅，而不是 macOS 的深浅。在工具栏里，程序运行时（Claude Code、编辑器）标记会一直保留， 因为它不会遮挡任何输出。放在命令行右侧时，在 自动 模式下，shell 集成会在命令执行期间把它隐藏； 始终 模式可以在命令输出期间保留它。两种提示符模式在查看回滚内容或使用备用屏幕程序时都会把它隐藏。

位置 设置可选 窗口工具栏（默认）或 命令行右侧。工具栏中的标记独立于连接和新建标签页按钮， 命令变长或换行时位置不变。关闭它或选择命令行位置，会移除它在工具栏中的位置和分隔间距。 选择命令行位置时，长命令会把标记移到下方的空闲处，使其保持在右侧；没有安全的行时它会隐藏， 绝不会插入新行或让子进程滚动。直接输入和输入法的颜色可以填十六进制值；清空输入框即使用默认的低调样式。

中文输入法标记 · 避开长命令

可选的本机系统状态#

打开设置（⌘,）→ 终端，在“底部状态栏”下启用“显示系统状态”，然后选择要显示的指标：CPU 使用率、系统负载、内存使用、 网络速率、磁盘可用空间和热状态。它默认关闭；每项指标都有自己的开关。点击状态栏可以看到本机的名称、 macOS 版本、芯片、核心数和总内存。即使在 SSH 窗格中，状态栏也显示“本机”；它不监控远程服务器。 窗口较窄时，点击即可看到完整的已选指标。

网络接口默认为自动。它只测量一个主接口，因此 VPN 流量不会叠加到物理接口的流量上。 在设置中输入具体的接口名即可改为测量该接口。所有已启用的状态栏都被隐藏时，采样会停止。 热状态是 macOS 报告的四级状态，不是温度。

状态栏使用紧凑的标签、单个空格分隔和简短的字节单位；完整名称和精确数值在它的工具提示、 辅助功能值和主机详情弹出框中。

创建和编辑主题#

在 设置 → 主题 中，点“浅色模式”或“深色模式”旁边的“新建”会打开图形化编辑器；保存的主题就用于那个模式。为你的副本命名，在深色和浅色变体之间切换， 用取色器或十六进制值修改颜色。预览会实时更新，但不改变终端窗口。“保存主题”会启用并保存它； “取消”则保留之前的主题。自定义主题提供“编辑主题”。“恢复来源配色”会重置当前变体。 你仍然可以手动编辑同一个配置文件。如果该自定义主题在编辑器之外被修改了，请在保存前重新打开编辑器。

显示 → 主题编辑器 直接打开图形化颜色编辑。显示 → 本机详情 无需开启可选的状态栏也能查看主机配置。 设置 → 终端 中也有同样的主机详情按钮。外观预览会立即跟随明确的模式切换，并显示所选的光标形状和闪烁状态。 终端程序仍然可以临时覆盖光标样式。

紧凑的 Tab 缩进（zsh）#

开启“目录补全”或“历史命令建议”（两者默认开启）时，标准的本地 zsh 会话会自动加载内置钩子，你不需要修改启动文件。 如果你使用自定义的 zsh 参数，或关闭了这一自动引导，请在 设置 → 终端 中安装或更新 Shell 集成， 然后打开一个新 shell。加载这些钩子后，在只有空白的命令行上按 Tab 会插入四个空格； 命令文字之后按 Tab 仍保留原有的补全绑定。这是一个 ZLE 小部件；终端输出的制表位仍是八列， 全屏程序照常收到 Tab 键。没有集成时，shell 保留它自己的输入 Tab 行为。

语言#

应用跟随 macOS 为 Corta 选择的首选语言：英文、简体中文、繁体中文、日文、韩文、德文、法文、西班牙文和巴西葡萄牙文。 在 macOS 中更改 Corta 的应用语言后，请重新启动 Corta。数字格式跟随当前地区设置。

会话结束时#

shell 退出后，窗格会保留它的输出：输出会稍微变暗，上面出现一个面板，用一句话说明什么结束了、怎么结束的—— 退出码，或终止它的信号。光标会消失，但面板周围的滚动、选择、复制和 ⌘F 搜索仍然可用。新建会话 会在窗格里 重新启动 shell 或预设；关闭窗格 会关闭它。直接连接的 SSH 会话会说明它连接的是哪台主机，并提供 重新连接 来建立新的连接；ssh 的退出码 255 会被解释为网络中断或主机无响应。两个按钮都会清空上面的输出——面板上会写明—— 新会话沿用窗格当前的尺寸和字号。从 Python 或其他程序退回到仍在运行的 shell，不算终端会话结束。

会话的输入或输出出错，或者窗格停止绘制时，同样的面板会提供 重试，连接则提供 重新连接； 系统给出的原始错误在 详细信息 里。

回滚、搜索和选择#

• 滚动。 触控板或滚轮，或者 ⇧PageUp / ⇧PageDown、⇧Home / ⇧End。每个会话保留 scrollback-lines 行历史（10,000）。

• 搜索。 ⌘F 在回滚内容上打开搜索栏；⌘G 和 ⇧⌘G 跳到下一个和上一个匹配。区分大小写 和 * （正则表达式）在那里切换，其状态会记在配置文件中（search-case-sensitive、search-regex）。 搜索栏位于窗格右上角，当光标或当前匹配会被它挡住时会移到底部；在较窄的分屏中，它会变窄而不是盖住整个窗格。 每个窗格都有自己的搜索栏。

• 选择。 拖动选择，双击选择一个词，三击选择一行。选择完成后会立即复制（copy-on-select）；⌘C 也能复制。 复制成功时，一道光会沿着复制的文字扫过一次（开启“减弱动态效果”时改为一次柔和的闪烁）； 文字已滚出视野时则显示一条提示。在使用鼠标的程序里——vim、htop——开始拖动时按住 ⌥ 仍然可以选择文字（mouse-override-modifier）。

• 粘贴。 ⌘V。粘贴的文本会被标记为粘贴（括号粘贴），所以支持它的 shell——zsh、fish、bash 5.1 或更高版本—— 会插入粘贴的命令，但在你按 Return 之前不会执行。程序没有开启括号粘贴时（macOS 自带的 /bin/bash 3.2 从不开启）， 粘贴包含换行的文本前 Corta 会发出警告。即使开启了括号粘贴，遇到管道传给 shell（或 bash <(curl …) 之类）、 sudo、强制递归删除、反斜杠续行，或不可见 / 双向控制字符时，Corta 也会警告。选择 粘贴 或 取消 前， 请查看风险说明和文本预览；隐藏字符显示为 ⟦U+202E⟧ 这样的代码。不再对此窗格发出警告 一直有效，直到该窗格关闭。 设置 paste-warning = always 会在每次粘贴多行文本时警告，设为 off 则关闭这些对话框。这些只是保守的模式匹配， 不是 shell 解析器，也不保证其他文本是安全的。shell 仍在处理的大段粘贴可以用 ⌃C 取消：尚未发送的部分会被丢弃， 中断信号会直接送达。

• 右键点按。 被点按的窗格提供“查找…”和“复制命令输出”；后者拷贝输出中包含所点那一行的已完成命令的输出。 在提示符上、备用屏幕（全屏程序）中，以及没有 shell 集成时，拷贝项不可用。在链接上会提供“打开链接”和“复制链接”； 在 path:line:column 引用上会提供“打开路径”和“复制路径”。打开时使用与点按相同的链接检查、已配置的编辑器和 远程确认。开启了鼠标报告的程序仍会收到右键点按。

• 导出文本…（⇧⌘S）把所选内容——没有选择时则为整个回滚内容和屏幕——保存到文件。

• 清除。 有三个命令，因为它们丢弃的东西不同：

  命令	屏幕	回滚	模式和颜色
  清除屏幕（⌘K）	清除；保留已就绪的 shell 提示符和输入	保留	保留
  清除历史记录	保留	丢弃	保留
  重置终端	清除	丢弃	重置

  有 shell 集成时，清除屏幕会把已就绪的提示符及其完整输入移到顶部，保留编辑光标、换行、颜色和宽字符。 它不发送任何按键，也绝不执行输入的内容。提示符仍在打印、命令正在运行，或 shell 没有就绪的提示符标记时， 仍按普通方式清除并回到左上角。vim 等备用屏幕程序保持原样；提示符已滚入历史的编辑器也保持原样， 以免擦掉它的部分输入。

  清除历史记录和重置终端会先询问，并说明将丢弃多少行——除非回滚内容为空，或 confirm-close = false 关闭了询问。

链接与文件引用#

• URL 在鼠标悬停时显示目标和 ⌘ 点按的提示，用 ⌘ 点按打开；设置 link-activation = click 则普通点按即可打开。 在链接上按住 ⌘——包括程序明确标记的链接（OSC 8，如 ls --hyperlink 输出的）——会给它加上下划线， 并在你点按之前以工具提示显示它真正的目标；点按本身会立即打开它。
• 文件引用。 程序输出中的 path:line:column——编译错误、测试失败——用 ⌘ 点按即可在你的编辑器中打开。 通过 open-file-command 告诉 Corta 用哪个编辑器，以编辑器的完整路径开头，例如 open-file-command = /usr/local/bin/code --goto {file}:{line}:{column} （Following a file reference）。

打开任何文件引用都需要先配置 open-file-command。Corta 从不用系统默认应用打开来自输出的文件： 有些文件类型一打开就会执行代码。

Shell 集成#

Shell 集成让 Corta 能看到每条命令从哪里开始、到哪里结束。在 设置 ▸ 终端 ▸ Shell 集成 中安装： 它会在 shell 的启动文件中加入一个带标记的代码块——~/.zshrc；bash 为 ~/.bashrc 和 ~/.bash_profile （或 bash 实际读取的登录文件）；或 ~/.config/fish/config.fish——而 移除 恰好删掉这个代码块。 只有按下按钮时才会安装启动文件中的代码块。开启 目录补全（zsh） 或 历史命令建议（zsh）（默认开启）时，标准的本地 zsh 会话 也会自动加载 Corta 内置的钩子，无需编辑启动文件。自定义的 zsh 参数、bash、fish 和远程 shell 不使用这种自动引导。 要在这些 shell 中获得命令边界，请在其中安装兼容的钩子。

设置提示集成已过时时，请选择 更新 并打开一个新 shell。只更新应用，不会替换之前安装在启动文件中的代码块。

钩子加载后（无论是自动加载还是通过启动文件安装）：

• 提示符标记。 每个提示符左侧有一条细线，命令成功时为绿色，失败时为红色。空的 Return 不画线， 也不会产生已完成的命令历史记录。
• 跳转。 ⌘↑ / ⌘↓ 在命令之间移动，也会停在程序用 iTerm2 的 OSC 1337;SetMark 设下的标记处； ⇧⌘↑ / ⇧⌘↓ 在失败的命令之间移动。
• 命令的输出。 在命令面板中：拷贝上一条命令的输出、拷贝当前命令输出的快照（构建到目前为止打印的内容）、 导出命令输出… 到文件，以及 打开命令输出中的文件引用，它会打开输出中最后一个 path:line。
• 命令历史。 搜索命令历史… 列出每条命令及其时间、退出状态和目录；填充 把命令放回提示符， 运行 再次执行它（command-history-limit）。列表无法完整显示的命令——多于一行、在行尾被截断或包含制表符—— 或者文字在列表显示之后发生了变化的命令，会被填充而不是运行，这样完整的命令都在提示符上，等你按 Return 才执行。
• 历史与关于窗口。 命令历史会在调用它的窗口上方居中打开，并限制在该显示器的可用范围内；Corta ▸ 关于 Corta 会像其他应用的“关于”窗口一样，在该显示器中央打开。 已经打开的窗口保持在你移动到的位置。命令历史的固定尺寸让搜索框以及目录 / 项目 / 状态 / 主机筛选始终可见； 没有结果时显示 没有命令 和结果数量。
• 长任务通知。 设置 notify-on-long-task = true 后，运行时间超过 notification-threshold 秒（30）的命令 在结束时，如果它所在的窗口不是当前窗口，会发出通知，前提是 macOS 已授予 Corta 通知权限。 在 设置 ▸ 通用 中开启它，并在那里查看权限状态。点按通知即可跳到那条命令。

没有 shell 集成时，这些命令会被禁用，而不是悄无声息地什么也不做；通知则退而根据输入和输出来推测。

工作目录#

shell 报告当前目录时（shell 集成会报告），Corta 就知道它在哪个目录。在命令面板中：

• 在访达中显示工作目录 和 拷贝工作目录路径。
• 切换到上级目录 和 切换到项目根目录（最近的含 .git 的文件夹）会替你输入 cd—— 仅在没有命令运行且提示符为空时可用。
• 在新窗格中打开上级目录 和 在新窗格中打开项目根目录 会拆分窗格，并在那里启动一个 shell。

标题栏中的文件夹图标也代表这个目录：可以拖动它，或用 ⌘ 点按它查看路径。开启 directory-history （默认开启）时，Corta 会记录你执行命令时所在的本地目录。应用中目前还没有列出它们的地方； 设置 ▸ 隐私与安全性 ▸ 历史记录 会显示数量并可以清除。

目录补全（zsh）#

Corta 自带目录补全，在标准的本地 zsh 会话中默认开启。输入 cd 就能在输入旁的紧凑面板中看到当前目录中的文件夹。 空间足够时面板出现在输入下方，靠近窗格底部时出现在上方。带色调背景和边框的圆角玻璃胶囊把它与之前的输出区分开； 它可能暂时盖住一小部分输出，但不占用终端行。继续输入可以筛选文件夹；光标旁会出现淡色的后缀。例如，cd De 可能会补全为 Developer/。 补全只是预览：在被接受之前，它们不是命令的一部分。

补全可见时：

可以筛选相对路径、子目录和 ~/ 路径。Tab 填入以 / 结尾的文件夹后，它的子目录会成为下一批候选； 重复这一步可以组成更深的路径，想执行 cd 时再按 Return。只提供文件夹，因此只包含文件的文件夹没有下一层候选。 输入点号前缀时会显示隐藏文件夹。复杂的 shell 表达式保留原生补全。 bash 和 fish 保留它们自己的补全；补全只出现在 Corta 以自动 zsh 钩子启动的 shell 中， 绝不会出现在远程机器上或自定义 shell 命令中，即使安装了 Shell 集成也是如此。

可选：关闭它。 在 设置 ▸ 终端 ▸ Shell 中关闭 目录补全（zsh），或在配置文件中设置：

directory-completion = false

这会立即停用 Corta 的补全和按键拦截，shell 的原生编辑和补全仍然可用。重新开启后请重新打开 shell。 自动加载的本地钩子没有需要删除的启动文件代码块。如果你还手动安装了 shell 集成，它的 移除 按钮会删除那个 单独的启动文件代码块；关闭目录补全不需要移除它。

历史命令建议（zsh）#

在标准的本地 zsh 会话中，输入之前某条命令的开头，光标后会以淡色显示它剩下的部分。最近一条匹配的单行命令优先。 例如运行过 git status 后，输入 git st 会补全 atus。在你接受之前，这只是预览。

输入为空、光标在行中间，以及多行的历史条目都不会显示历史提示。目录补全开启时 cd 仍显示目录补全， 关闭时则显示历史提示。输入法组字时提示会隐藏，输入法自己的候选仍然可用。 如果加载了 zsh-autosuggestions，Corta 会把历史命令建议交给它。bash、fish、远程 shell 和自定义启动命令保留各自的编辑方式。

默认开启。关闭 设置 ▸ 终端 ▸ Shell ▸ 历史命令建议（zsh），或设置 history-suggestions = false，即可立即隐藏提示并恢复原生按键。 重新开启后请重新打开 shell。目录补全有自己的开关。两者都使用临时的启动包装，不改动你的启动文件。 Corta 使用 zsh 内存中的历史，从不读取 HISTFILE，也从不记录或保存补全的文字。超过 128 个 Unicode 字符的后缀不会显示。

远程工作：SSH 与 SFTP#

Corta 使用系统的 OpenSSH——你的 ~/.ssh/config、密钥、代理和 ProxyJump 全都适用——它自己没有 SSH 实现。

• 主机标记。 连接到另一台机器的窗格会在窗口标题开头显示 远程：。远程 shell 报告了主机和文件夹时 （那里安装了 shell 集成），标记会显示它们；连接来自连接面板时，显示你输入的目标；否则只说明这个窗格是远程的， 但不知道是哪台主机。
• 重新连接。 ssh 或 mosh 会话结束时，重新连接到主机 会以新连接再次运行同一条命令。
• 连接。 工具栏的地球按钮会打开 连接到主机 面板，顶部可以切换 终端 / 文件 (SFTP)：通过 SSH 打开终端， 或者打开文件浏览器。输入主机——名称、地址、user@host 或 SSH 别名。主机输入框、模式切换、补全列表和按钮都使用圆角玻璃外观； 窗口较小时面板可以滚动，所有字段和操作都能触及。高级选项 里是用户、端口和私钥； 留空就由你的 ~/.ssh/config 和 OpenSSH 的默认值决定。选中的私钥会最先提供，ssh-agent 中的其他密钥不会尝试。 面板列出你最近建立的连接（连同端口、密钥和上次使用的时间）以及 ~/.ssh/config 中的 Host 名称。 只用于 git 的主机（github.com，或带 User git 的 Host）不会列出，列表会注明隐藏了哪些。输入可以缩小列表， 点按一项（或在主机栏中用 ↑ 和 ↓）填入字段，双击或按 Return 连接。终端连接要真正建立后才会加入最近列表—— 拒绝你的主机或没有 shell 的主机不会加入。把指针移到最近的主机上点 ✕，或右键点按它，就能忘掉它； 设置 ▸ 隐私与安全性 ▸ 最近连接的主机 可以全部清除。
• 当前窗格的文件。 从连接着另一台机器的窗格打开时，面板会先提供那台主机的文件；按 Return 或点 浏览文件 即可打开。
• 浏览远程文件… 为窗格所在的主机打开 SFTP 浏览器：列出、上传、下载、重命名和删除。 第一次连接某台主机时会请你确认主机名。传输在中断后会续传，覆盖文件前一定会询问。 下载文件夹时，如果某个名称与 .corta-part 暂存文件冲突，下载会停止，保留现有文件。 请选择另一个目标位置，或单独处理那个文件；整个文件夹的覆盖不会吞掉部分文件。
• 在浏览器中，和访达一样：⌘[ 和 ⌘] 后退和前进，⌘↑ 到上一级文件夹，⌘R 刷新，⇧⌘G（或点按路径）输入路径， ⇧⌘N 新建文件夹，⇧⌘. 显示隐藏文件。点按列标题排序。右键点按一行查看它的操作；双击文件夹打开它。 从访达把文件拖到列表上——或拖到某个文件夹行上——即可上传；拖动时列表（或那一行）会描边，并写明文件会传到哪里。把文件拖到访达即可下载。 传输在工具栏的箭头按钮下，显示速度、剩余时间和“在访达中显示”。
• 编辑远程文件。 浏览器中的 编辑——或在远程窗格中 ⌘ 点按 path:line——会下载一份副本并在你的编辑器中打开。 请先设置 设置 ▸ 终端 ▸ 打开文件方式，使用编辑器可执行文件的绝对路径以及 {file}、{line}、{column} 占位符 （示例）。上传你的修改是一个单独的、明确的步骤， Corta 会先检查远程文件在此期间是否被改过。超过 64 MiB 的文件不会以这种方式复制；请从浏览器下载它们， 浏览器会显示进度并可以取消。30 天没人打开或修改过的副本，会在下次使用远程编辑时被删除； 带有你尚未上传或放弃的修改的副本会保留。
• 名称。 包含控制字符、从右到左字符或零宽字符的远程名称会把它们显示为 �，下载时保存为 _， 这样一个名称就无法冒充另一个名称。

服务器要求输入密码、密钥口令或一次性验证码时，或者主机是新的、需要你决定是否信任它的密钥时， 浏览器会在它的窗口上弹出对话框询问，并把你的回答交给 OpenSSH；不会保存任何内容，所以重新连接时会再次询问。 密码对话框中的 取消连接 会中止这次连接并回到主机栏——不会当作空密码发送。密钥口令对话框中的 取消 只会跳过那把密钥，ssh 会继续尝试下一种登录方式。主机密钥对话框会显示指纹，默认按钮是“取消”。 由 ssh-agent 或钥匙串持有的密钥，或者你终端中已有的 ControlMaster 连接，会直接登录而不询问。

连接失败时会用一句话说明原因——密码或密钥不被接受、主机没有响应、主机密钥未知或已变化、服务器不提供 SFTP—— ssh 的原话在 详细信息 里，并提供 重试 或 修改连接信息。

远程编辑上传时，除了大小和修改时间，还会比较远程内容，并发送你批准的那份私有快照。 如果你在批准提示之后又保存了一次本地编辑，Corta 会请你重新决定；上传过程中的保存会保持待处理状态。 连接失败后，下一次编辑或上传会重新连接，失败的上传会保留其待处理的决定。 连接建立后，任何操作超过 120 秒仍未完成就会被停止，并再次请你决定是否上传，连接卡住也不会让一次编辑永远挂起。删除应用数据前， 请先保存尚未决定的本地编辑。见静态数据策略（英文）。

终端里的图片#

支持 kitty 图形协议 的程序可以内联显示图片：

kitten icat --transfer-mode=stream picture.png

图片随文字滚动，保留在回滚内容中，并会随周围的文字一起被“清除屏幕”或“清除历史记录”删除。 在程序的滚动区域内——例如全屏程序的窗格——图片随区域中的文字移动，滚出区域边缘的部分会被裁掉。 图片每边最多 8192 像素，总计最多 1600 万像素。其他支持该协议的工具，如 timg 或 chafa， 只要发送的是图片本身，也可以使用：Corta 按设计拒绝读取程序指定的文件路径，也不支持动画。 比窗格大的图片会缩放到适合窗格。

命令面板#

⇧⌘P 打开命令面板：Corta 的每个命令都可以按名称搜索，旁边显示其快捷键。输入几个字母后按 Return。 字母按顺序匹配，不必相连（spr 能找到 Split Pane Right）；分组名（panes）或命令的配置名（new-tab）也能找到它。 最近运行过的命令排在最前。点按另一个窗口会关闭面板，并让那个窗口留在最前。 它是使用没有默认快捷键的命令最快的方法。

macOS 集成#

• 快捷指令。 两个操作：打开 Corta 窗口（可选指定文件夹）和 聚焦 Corta 窗口。 它们都不会在 shell 中执行命令。
• 服务。 选中的终端文本会提供给 服务 菜单。
• 安全键盘输入。 Shell ▸ 安全键盘输入 会在 Corta 位于最前时阻止其他应用读取你的按键——用于输入密码。 标题栏中的锁形图标表示它确实已开启。
• VoiceOver 会朗读终端的文字，并跟随当前窗格。
• 程序写入剪贴板。 默认关闭。设置 allow-clipboard-write = true 后，程序——包括 tmux 内或通过 ssh 运行的程序—— 可以把文本放到你的剪贴板上（OSC 52）。任何程序都无法读回剪贴板。

速度与电池#

Corta 会自己选择更快的做法；这里的一切都不需要设置。下面说明它做了什么，让你知道该期待什么。

• 打字时使用屏幕的最高刷新率。 在你打字、粘贴或用输入法组字时，Corta 会请求显示器的最高帧率—— ProMotion 屏幕上为 120 Hz——并在最后一次按键一秒后让它回落。不打字时，低电量模式、非活动窗口和热压力 会再次降低上限；严重的热压力则始终会降低上限。
• 在 macOS 27 或更高版本上，全屏单窗格可以降低延迟。 这时 Corta 把帧直接呈现到显示器，跳过窗口服务器的合成器： 在测量的 Mac 上，按键到上屏大约少一帧。分屏、查找栏或其他任何绘制在文字之上的东西显示时，合成器会回来。 在 macOS 26 上，作为针对 WindowServer 崩溃（#380）的兼容措施，每个窗口都使用经典队列的复制路径； 上述延迟数据不是在该系统上测得的。（在启动环境中设置 CORTA_DIRECT_FULLSCREEN=0 会停用全屏相关的改动， 但不会停用 macOS 26 的兼容路径。）
• 读取输出和显示各有节奏。 PTY 读取器持续解析，而屏幕按显示器的节奏呈现最新状态。测得的核心吞吐基准达到 317.3 MiB/s；这个数字不包括 PTY I/O、渲染和显示，也不是对真实构建日志或 yes 的速度承诺。
• 滚动和全屏程序只重绘变化的部分。 vim、less、tmux 和状态栏通过移动已绘制的内容来滚动。
• 长回滚依然很小。 历史在滚出屏幕时就在内存中压缩——测得 100,000 行 120 列的内存增量约为 11 MiB—— 搜索、复制和调整大小都直接在压缩数据上进行。
• 空闲就是空闲。 闪烁的光标由 macOS 做动画，而不是由 Corta 重绘；空闲的 shell 不会引起周期性唤醒； 被遮住或最小化的窗口完全停止绘制。
• 隐藏的窗格会让路。 窗格被隐藏两秒后——切到另一个标签页、窗口最小化——它的输出以后台优先级读取， 不会和你正在看的内容争抢资源。不会丢失任何内容，向它输入或粘贴会立即恢复完整的优先级。

Performance（英文）记录了测量结果和测量方法。

设置与配置文件#

所有设置都保存在一个文本文件 ~/.config/corta/config 中。Corta ▸ 设置…（⌘,）编辑的是同一个文件， 手动编辑这个文件同样受支持：

设置窗口是一个分类侧边栏，布局和“系统设置”相同：

• 通用 —— 新窗口大小、恢复窗口、关闭确认、长任务通知和更新。
• 外观 —— 浅色或深色、系统等宽字体、字号和实时预览、光标形状/闪烁，以及图形化主题编辑。
• 终端 —— 回滚、命令历史容量、响铃、搜索默认行为、打开文件方式、shell 集成、可选的系统状态和本机详情。
• 键盘与鼠标 —— 将 Option 用作 Meta、链接的打开方式、程序占用鼠标时用于选择文字的修饰键、选中即复制， 以及输入法状态提示的模式和颜色。
• 快捷键 —— 每个命令的按键；改过的快捷键旁会出现一个重置箭头。
• 连接 —— 连接到主机，以及已保存的预设。
• 隐私与安全性 —— 程序写入剪贴板（OSC 52）、安全键盘输入、目录历史和最近连接的主机。

这些控件编辑的都是同一个配置文件。自定义主题的颜色可以图形化编辑，也可以通过文件编辑。

窗口工具栏的地球按钮用于连接主机，可以打开终端，也可以浏览它的文件：在窗口上打开一个面板，填写主机——可以是配置中的别名—— 用户、端口和私钥在 高级选项 里，并推荐最近和配置过的主机；用户、端口或私钥留空则遵循 OpenSSH 的配置。 从远程窗格打开时，会先提供那台主机的文件（远程工作）。

theme = corta
appearance = auto
font-size = 14
scrollback-lines = 20000
notify-on-long-task = true
bind.equalize-panes = ctrl+cmd+e

多数设置立即生效；少数几项（窗口大小、回滚长度）作用于下一个窗口或会话。 Configuration（英文）列出了每个配置项、默认值以及何时生效。

键盘快捷键#

在配置文件中用 bind.<command> 修改任意快捷键；值为空则移除它，之后这个按键会传给终端里的程序：

bind.equalize-panes = ctrl+cmd+e
bind.close =

帮助 ▸ 键盘快捷键 以对齐的列显示当前生效的快捷键；没有绑定的命令标为 未设置。 终端的右键菜单也显示同样的已配置快捷键。

Shell 菜单直接提供拆分、重新打开和清除屏幕。其他工具归在 移动焦点、命令与输出、工作目录、 窗格布局 以及 终端与连接 之下。

以下是本版本的默认值——Keyboard shortcuts（英文）是权威列表：

其他所有命令——均分窗格、清除历史记录、重置终端、浏览远程文件…、命令输出和工作目录相关的命令—— 都没有默认按键，在命令面板里一搜就到。Keyboard shortcuts（英文） 有完整的表格，列出每个命令的 bind. 名称。

出问题时#

故障排除介绍出问题时你会看到什么以及如何修复——macOS 打不开的下载、被拒绝的字体、 没有反应的快捷键。Features and limitations（英文）列出了 Corta 目前还做不到的事。 其他问题请在 GitHub Issues 报告。 使用问题请到 Discussions → Q&A， 或在 Discord 的 #help 频道提问。

编码代理状态与程序通知#

目前只有 Claude Code 这一个命令行工具有专门的任务状态集成。 它基于 macOS arm64 上安装的 Claude Code 2.1.310 开发和验收，这并不保证所有 Claude 版本都兼容。Codex、Gemini CLI、pi、 Kimi、Grok Build、Qwen Code、OpenCode 和 Aider 在 Corta 中都没有专门的任务状态适配。通用的通知 / 进度协议 对任何程序都可用；进程检测并不等于完整的代理集成。参见 兼容范围与验证限制（英文）。

默认情况下，代理窗格会在标签页上区分 工作中（强调色）、等待你操作（橙色）、已完成（绿色）、失败（红色）、 空闲（灰色）和 状态未知（空心灰点）。空闲表示没有报告正在进行的回合，包括工作开始之前和停止之后； 只有明确的 done 才表示完成。进度环跟随 OSC 7501 或 OSC 9;4 的报告。程序坞会统计等待中的窗格数量并显示总体进度。 打开命令面板或 窗口 → Agent 列表，可以找到所有窗口中的代理窗格；选择一项即可聚焦它。 在命令面板中，浏览时代理排在最前，搜索时排在匹配的命令之后；按 Return 仍执行高亮的命令—— 用方向键移到某个代理上才会跳转过去。一个窗格中有多个代理时，显示最紧急的状态。状态和应用名称由程序自行报告， 并非经过验证的身份。通用的 OSC 21337 元数据可以在任务标题为空时，为当前状态加上指示颜色和状态标签； 没有任务状态时，标签仍为 状态未知。status-color 只作为元数据保留；原生标签页和菜单文字使用系统颜色。 Claude Code 2.1.310 没有启用这个元数据通道。

在普通的交互式会话中，Claude Code 的 OSC 7501 状态探测不需要任何设置。它需要 Claude Code 2.1.295 或更高版本； Corta 验证过的参考版本是 2.1.310，并非整个版本范围。开启 tmux 的 allow-passthrough 并不能让状态穿过 tmux： Claude 会自己探测 tmux。Claude 的后台会话即使处于附着状态也不会报告 OSC 7501；这和在隐藏的 Corta 窗格中 运行交互式会话不同。取消设置 CLAUDE_CODE_DISABLE_TERMINAL_TITLE 才能允许探测和报告。参见 Anthropic 的终端要求。 当隐藏的 Corta 窗格请求权限、提出问题或需要登录时，Corta 会发出一条固定的消息。 要显示 Claude Code 自己的消息文字，请在 Claude 的 settings.json 或 /config → Local notifications 中把 preferredNotifChannel 设为 ghostty（OSC 777）、iterm2（OSC 9）或 kitty（OSC 99）。auto 不会为 Corta 选择消息通道。terminal_bell 发送 BEL，iterm2_with_bell 在 OSC 9 之外再加 BEL，notifications_disabled 关闭 Claude 自己的通知通道，但不会关闭 Corta 的 7501 提醒通知。Corta 仍以 Corta 的身份标识自己。 这些 Claude 专属的协议细节基于验证过的参考版本；可用性取决于安装的 Claude 版本。Claude 明确的权限通知 通常在大约六秒没有输入后发出；完成提醒通常要等大约 60 秒，并且要求没有正在运行的后台代理。 这些与即时的状态报告是分开的。参见通知时机。 能解析 OSC 9;4 并不意味着 Claude 会在 Corta 中发送进度：2.1.310 的进度通道需要 terminalProgressBarEnabled， 以及它认为支持进度的终端；Corta 的常规身份不在其列。

不支持状态报告的程序按前台进程名检测（claude、claude-code、codex、gemini、aider、opencode）； 可以用 agent-processes = my-agent,another-agent 添加名称。这些窗格在进程活动时显示 状态未知： 输出和提示符重绘并不能证明任务正在进行。回到 shell 或进程正常退出表示 空闲，而不是 已完成； 已知失败的退出表示 失败。通知和 BEL 只请求注意，不改变任务状态。仅仅安静并不表示完成。 BEL 原有的声音 / 视觉 / 静音设置不变。崩溃的命令行工具无法发送清除信号时，报告的 shell 命令边界也会结束 过时的状态和进度。退出状态 130（或直接启动的会话被 SIGINT 结束）表示被中断 / 空闲，而不是 已完成； 其他已知的非零退出表示 失败。新报告的命令会清除旧的摘要。没有 shell 边界或会话退出时， Corta 无法仅凭输出发现一次静默崩溃。

agent-status = false 会隐藏状态指示和列表。notify-from-programs = false 会关闭程序通知和代理提醒通知。 程序消息会以 Corta 的窗格名称标注为窗格消息，经过长度限制和清理，并按窗格合并，每五秒最多发送一次。 窗格仍处于报告的阻塞状态时，延迟到达的程序通知不会为已经宣告过的等待再次提醒。在首次发送之前到达的通知 可以改用它自己的消息。需要 macOS 的通知权限；要在程序坞显示计数，请在应用的通知设置中开启 标记应用程序图标。 通知中心可能会保留消息文字并在锁定屏幕上显示。点按通知会聚焦该窗格；关闭或重启窗格会取消待发送的程序通知。 离开一次阻塞会取消它的固定提醒通知，而独立的程序消息保有自己的生命周期。BEL 不能替换待发送的程序文字， 也不能为已经宣告过的等待再次提醒。提交之前会再次检查可见性；提交之后的系统投递由 macOS 控制。

使用 OSC 扩展的程序#

使用 iTerm2 的 imgcat picture.png（或动画 GIF）显示内嵌图片；GIF 显示第一帧。支持按单元格、像素、百分比 和自动尺寸，默认保持宽高比。图片随文字滚动；“清除历史记录”会删除历史中的图片。文件下载会被拒绝。

VS Code 的 shell 集成使用与 Corta 钩子相同的提示符和命令记录。对远程主机来说，iTerm2 的主机 / 当前目录报告 只作参考。kitty 程序可以设置颜色和指针形状；悬停在链接上时仍显示手形。使用 OSC 52、iTerm2 Copy 或 kitty 纯文本 OSC 5522 子集写入剪贴板都需要 allow-clipboard-write = true；读取剪贴板总是被拒绝。

printf '\e]1337;RequestAttention=once\a' 会在 Corta 不处于活跃状态时让程序坞图标跳动。yes 会一直请求注意， 直到 Corta 被激活；no 取消请求；fireworks 与 once 相同。程序不能把窗口带到前台。 OSC 处理表（英文）记录了每个受支持、被忽略和被拒绝的协议族。