文件浏览器、编辑与预览

详情面板的 Files 页以当前工作目录为根。双击 Markdown、reStructuredText、HTML、SVG 或普通源码会在右侧以可编辑 Source 打开；图片、PDF、富文档、diff、Agent transcript 和二进制保持只读预览。目录用箭头或双击在树内展开。右键菜单包含：

• Open：使用 macOS 默认应用；可执行文件或 .app 会再次确认。
• Open in Aster：可选 Current Pane、New Tab、New Window、Split Right/Left/Top/Bottom。
• New File… / New Folder…：文件选中时创建在其父目录，目录选中时创建在目录内部；不会覆盖同名项。新文件会在右侧以可编辑 Source 打开。
• Rename… / Move to Trash：重命名后已打开 Pane 会继续跟踪新路径；删除进入系统废纸篓，可以恢复。
• Copy Path / Copy Relative Path / Reveal in Finder：相对路径以当前 Files 根目录为准且不带 ./。

File Pane 顶部左侧提供模式胶囊、发送到 Chat 和共享；中间显示文件名与更多菜单；右侧显示 ✓ Saved、Edited、磁盘冲突或错误，并提供保存和关闭。Markdown、reStructuredText、HTML 与 SVG 使用 code/eye 在可编辑 Source 和 Preview 间切换；普通源码使用 code/lock 就地锁定或解锁。Source 会随 Pane 尺寸调整显示区域；… → Soft Wrap 可切换自动换行，关闭后可横向滚动长行。切换会保留源码选区、滚动位置和撤销记录；⌘S 原子保存，不会自动保存。存在未保存内容时关闭仍会询问保存、放弃或取消。外部程序修改文件时，未编辑的 Pane 自动重载；本地已有修改时显示 Modified on Disk，可从 … → Reload from Disk 明确放弃本地内容。

Preview 支持 Markdown（含 GFM 表格、任务列表等）、reStructuredText、HTML、SVG、常见图片/GIF、PDF、diff、Office/媒体/字体 Quick Look、二进制 hex 和 Aster 已识别的 Agent transcript。HTML/SVG/Markdown 预览禁用 JavaScript 与网络请求；Agent transcript 以会话视图渲染（角色区分、Markdown、工具折叠），可 Resume 或 Fork。二进制 hex 只按可见行绘制，超大文本和二进制只读取有界内容，避免单个 Pane 占满内存。远程 SSH 路径暂不支持 File Pane。

普通 UTF-8 文件可从 File Pane 点气泡图标“发送到 Chat”；文件必须是非符号链接且不超过 64 KiB，内容会先移除控制字符并遮盖常见 secret。无法读取或保存时，Pane 会显示明确错误，未保存内容不会被清除。

把 Finder 文件或目录拖到 Pane 边缘，可按高亮方向创建预览、文件浏览器或继承目录的新终端；把纯文本拖到终端会经过与粘贴相同的危险内容确认。HTTP/HTTPS URL 会在对应方向创建 Web Pane。一次最多处理 32 个 URL，符号链接和特殊文件不会被读取。

打开终端中的文件与链接

按住 ⌘ 时，终端视口里所有可点击的目标都会显示实线下划线；松开即消失。按住 ⌘ 悬停在目标上鼠标变成手形；鼠标已停在目标上时，按下 ⌘ 也会立即切换，松开或移出目标后恢复原指针。点击即用系统默认应用（或“打开方式”里选的目的地）打开。Aster 能解析绝对路径、~/、./、基于当前 OSC 7 目录的相对路径与裸文件名（如 Makefile、site/README.md，只有在当前目录下真实存在时才会标记）、path:line:column、普通 URL、mailto:，以及程序发出的 OSC 8 显式链接。远端 Shell 里的相对路径不会被当成本机文件。

“设置 → 控制 → 链接协议”里“自动识别链接协议”选“全部”可识别所有合法协议，选“自定义”则把普通文字 URL 限制为 http、https、file、mailto 加下方列出的自定义 scheme。OSC 8 显式链接不受列表限制，但不会绕过安全检查。“显示链接预览”控制按住 Command 悬停时左下角的完整目标提示，关闭后链接仍可点击；本地相对路径会按当前可信目录展开为绝对路径。提示使用固定半透明圆角底：浅色外观为黑底白字，深色外观反转为白底黑字，不会被当前终端主题染色。“重置安全提示”清除所有“始终允许”记忆。

选择“自定义”后点“配置…”，逐行添加、修改或移除协议，有效更改即时保存；直接填写 codex 或 ssh，也接受 SSH:// 并规范化为小写。最多 64 个协议，每个最多 64 个字符。非法输入会标红并保留，保存失败可以重试；“完成”或 Esc 在保存完成后关闭并返回配置按钮。切回“全部”不会删除自定义列表。协议修改立即更新已打开终端的链接命中、下划线和手形；关闭预览不影响手形与点击。“重置安全提示”成功后显示“已重置 ✓”约 1.6 秒，保留协议列表和预览偏好。

“设置 → 控制 → 打开方式”分别选择链接、文件和文件夹的目的地。本地普通文件与文件夹可直接在 Aster 的 Editor / File Browser Pane 中打开，也可交给系统默认应用或 Finder；HTTP/HTTPS 网页可在只允许网页导航、不开放本地文件和自定义协议的 Web Pane 中打开。默认 Git 客户端和“自定义打开方式”都按 bundle ID 保存，应用移动或升级后仍由 macOS 重新查找。

首次打开外部网站、非标准 scheme（如 codex://）、可执行文件或 .app 时，Aster 会询问打开一次、始终允许或取消；可在同一设置区域点击“重置安全提示”清除全部例外，按钮会短暂显示“已重置”。可执行授权绑定当前文件身份，文件被替换或修改后会重新确认。导入设置不会导入另一台机器的安全授权。为避免阻塞或访问系统设备，FIFO、socket 和设备文件始终拒绝打开。

复制与粘贴

• 按 ⌘C、使用“编辑 → 复制”或终端右键菜单复制选区；按 ⌘V 粘贴。设置中可开启“选中即复制”“复制时去除行尾空格”和“复制后清除选区”，三项默认均关闭。启用“选中即复制”时会保留高亮以便继续扩展选区，不执行复制后的清除设置。

• 粘贴的文本末尾的回车（换行）会被自动去掉：粘贴只填入输入行，需要自己按 Return 执行。

• 粘贴保护默认开启。内容包含多行、sudo/su 或不可见控制字符时，Aster 会显示有界预览并要求选择“仍然粘贴”或“取消”。以下情况跳过普通多行告警：全屏 TUI（如 vim、less）；程序开启了 bracketed paste 且“信任括号粘贴”打开；Shell 集成确认有命令正在运行（粘贴进入该程序，而不是 Shell 提示符）。不可见控制字符始终要求确认；内嵌的 bracketed 结束标记会被转换成可见文本，不能提前执行后续命令。

• 从 Finder 复制文件后粘贴，终端里得到的是转义后的完整路径，多个文件用空格隔开。剪贴板里只有图片时，Aster 把图片存成临时 PNG 文件，再粘贴它的路径。

• “编辑 → 粘贴为”提供：粘贴选区（粘贴当前终端选中的文字，仍经过粘贴保护）、转义特殊字符后粘贴（文件粘贴为路径，文字整体变成一个 Shell 参数）、括号粘贴（无论程序是否开启都按 bracketed paste 发送）和“粘贴并在 Composer 中继续”。Base64 文件入口暂时置灰。

• “粘贴并在 Composer 中继续”会在 Agent Composer 可用时交接剪贴板文本；未打开 Composer 能力时该右键项置灰。

• “编辑 → Prompt 队列…”在当前终端 Pane 中可用，不会因 Claude Code 或 Codex 的识别状态变化而置灰。它在 Pane 底部打开输入条；按 Return 或右下角上箭头把内容加入上方列表。已在设置里安装 lifecycle hook 的 Claude Code / Codex，队列会自动发送：Agent 空闲（等你输入下一条）时立刻发出队首，正在执行时先排队、等这一轮结束再发，并且一次只发一条。等待权限确认（awaiting-input）时不会自动发送 —— 那时屏幕上是确认选择器，替你回车等于批准了一次工具调用。没有安装 hook 的普通 CLI 保持全手动。

• 任何时候都可以点击某项左侧的 ↳ 图标立即插队提交，右侧垃圾桶可移除尚未发送的项。关闭输入条不会取消队列，展开按钮可输入多行，队列仍受只读和终端输入模式限制。

• “编辑 → 发送到聊天…”以及终端右键“发送选区到 Chat”会打开确认面板。可同时选择当前选区与当前终端 transcript，并从当前工作区所有运行中的 Claude Code/Codex Pane 选择接收端；点击 Send 会以普通键入预填 Comment 和清理、脱敏后的上下文，不会自动回车。

• 远端受管终端粘贴图片：当剪贴板包含图片（PNG 或 TIFF）且当前终端是远端受管终端时，⌘V 会自动上传图片到远端临时目录，然后仅在终端粘贴远端文件路径（不含换行），不发送图片内容本身。上传失败、取消或粘贴期间终端切换/租约丢失时不粘贴任何内容，远端不留半文件。单张图片最大 20 MiB。图片内容不进入诊断日志。

终端程序可用 OSC 52 请求访问系统剪贴板。“设置 → 控制 → 复制与粘贴”分别提供“允许 / 每次询问 / 拒绝”：写入默认允许，读取默认每次询问。每次询问只授权当前请求，不会记住；连续请求在提示后有 5 秒安全冷却。导入配置不能把读取权限静默改成“允许”；拒绝或超限请求不会读取剪贴板。

选择终端文本

• 拖动选择字符，双击选择单词，三击选择整行；按住 Shift 点击可从现有锚点扩展。按住 Option 拖动会选择矩形列。
• Vi / Mark Mode 可用键盘移动和扩展选区；鼠标选择与 Option 矩形选择由 Ghostty 处理。
• vim、tmux 等程序开启鼠标报告时，Shift 是否保留为本地选择由 Ghostty 与前台程序协商。
• “设置 → 控制 → 选择”的选中即复制、输入时清除、复制后清除和行尾空格处理会实时应用；旧引擎专属的 Shift 方向键与退格删除开关暂不生效。

滚动终端历史

• 滚轮或触控板浏览 normal buffer；平滑滚动开启时，触控板按像素移动、内容跟着手指走，手势（含惯性）结束后对齐到字符行；鼠标滚轮仍按行滚动。向终端输入会回到最新内容；新输出只在视口已位于底部时跟随——上滚查看历史时，正在运行的命令或 TUI 的持续输出不会把画面拉回底部。
• 内容超出 Pane 高度时，滚动或把指针移到右边缘会出现滚动条（停下后自动淡出）：拖动滑块定位到任意位置，点击滑块上下的空白处按一屏翻页。
• Shift+Page Up / Page Down 向上或向下翻页，Shift+Home / End 跳到最早或最新内容；Command+Page Up / Page Down 按 Shell 命令跳转。相同命令也位于“显示 → 终端滚动”。
• “设置 → 控制 → 滚动”可关闭平滑滚动，并选择滚过末尾或开头时，把最后内容行、光标行或第一内容行停在视口顶部、中部或底部。全屏 TUI 的 alternate screen 始终禁用越界空白。

渲染与持续输出

Aster 使用 Ghostty 的 Metal renderer。PTY 读取、VT 状态、scrollback 和绘制由同一终端 内核管理，Aster 只响应最终渲染请求；持续大量输出不再经过旧的 AppKit 字节批次与 Core Graphics 网格路径。

命令输出末尾没有换行时（例如 cat 一个末尾不带换行的文件），zsh 默认会在行尾补一个反色的 %。 Aster 默认不显示它，输出照常保留，提示符换到下一行。想恢复时，在 ~/.zshrc 里写 PROMPT_EOL_MARK='%B%S%#%s%b'。

输入与安全键盘

• 键盘、IME、修饰键和 Kitty 键盘协议由 Ghostty 编码；Aster 不再额外猜测普通 Shell 的行编辑序列。
• “编辑 → 插入”可选择一个或多个文件/文件夹路径，或调用系统交互式截屏；结果会以安全转义后的路径预填到当前前台程序的输入框（包括 Codex/Claude 等 TUI），但不会自动执行。“编辑 → Insert from iPhone”会显示附近可用的 iPhone/iPad 拍照或扫描入口，完成后通过同一入口把私有临时文件路径插入当前输入框。手机导入只接受常见图片或 PDF，单项最大 32 MiB。
• “编辑 → 编辑器”（⇧⌘E）会在当前 Pane 底部打开 Composer 输入区，可直接输入、发送或加入 Prompt 队列；不会弹出文件选择器。需要编辑本地文件时，请从“文件”、文件树或路径入口打开。“Prompt 队列…”（⇧⌘M）和“发送到聊天…”分别打开当前终端的队列输入条与发送确认面板。
• 新安装默认关闭“Option 作为 Meta”，因此 Option 可继续输入重音和特殊字符；需要 Emacs/Vim 风格 Esc 前缀时可在“设置 → 控制 → 键盘”选择左右两侧、仅左侧或仅右侧。VT100 数字键盘模式默认允许，关闭后即使前台程序请求 DECKPAM，小键盘也保持输入数字。
• “设置 → 控制 → 鼠标”可配置右键为菜单、复制、粘贴、按选区自动选择或忽略；无论怎样设置，Control + 右键 始终打开菜单。还可选择 TUI 鼠标上报的绕过修饰键、输入时隐藏指针、悬停聚焦 Pane，以及在可靠 Shell 提示符行单击移动光标。
• “自动安全输入”默认开启。当前聚焦终端进入 canonical 隐藏输入（例如密码提示）时，Aster 会在输出到达及首个按键发送前启用 macOS Secure Event Input；Vim、less 等 raw-mode TUI 不会误占用。恢复回显、失焦、进程结束或切到其它应用后自动释放。也可从“编辑 → 安全键盘输入”手动开启或关闭；系统保护真实生效后，主工作区标题栏右侧显示蓝色 SECURE INPUT 胶囊。手动状态在 Aster 失活时暂停，切回后恢复。
• Codex、Claude 和普通 Shell 输入框保留 Ctrl+A、Ctrl+E、Ctrl+K、Ctrl+U、Ctrl+W 等常用行编辑控制键；Aster 的 ⌘←、⌥← 等原生菜单快捷键不会占用这些组合。

字号与全屏

• 在“显示”菜单选择“增大字号”“减小字号”或“重置字号”，也可使用 ⌘=、⌘-、⌘0。字号范围为 9–32pt，重置值为 13pt，并会同步应用到所有已打开终端。
• 选择“显示 → 进入全屏幕”或按 Fn+F 切换当前工作区窗口；进入后同一菜单项会显示为“退出全屏幕”。

界面字号与加深文字

• 上面的字号只管终端。侧栏、详情面板、弹出面板和设置页的文字大小在“设置 → 外观 → 界面文字 → 界面字号”里调，共五档：小、默认、大、更大、最大。
• 设置页会立即按新字号显示，方便你先看大小合不合适。侧栏和面板要重新启动 Aster 才会变；改完会询问“立即重启”还是“稍后”。
• 觉得说明文字、未选中的标签太淡，打开同一分组里的“加深界面文字”。它会让次要文字更深，立即生效，不需要重启。macOS“辅助功能 → 显示 → 增强对比度”开启时，这个效果会自动打开。
• 这两项都不改变终端里的字号和颜色。

只读模式

• Aster Vi / Mark / Hint Mode 使用 Ghostty retained buffer 的稳定坐标；输出或窗口 reflow 使旧锚点失效时会安全退出当前模式。
• “Shell → 只读模式”或 ⇧⌘P 命令面板按 Pane 切换只读。锁定后键盘、IME、粘贴和 TUI 鼠标报告不会到达程序；输出、滚动、选择、复制和查找仍可用。编辑器 Pane 也会停止接受修改。关闭并恢复工作区后只读锁不会保留。

收起实时画面

• Agent（Claude Code、Codex 等）持续输出时，屏幕上看得见的 Pane 每一帧都要重画，分屏里没聚焦的 Pane、放在其他应用旁边的 Aster 窗口也一样。不需要盯着看时，可以把这个 Pane 的画面收起来省电。
• 入口：把鼠标移到终端 Pane 顶边，点右上角淡入的眼睛图标；在终端 Pane 里右键选“收起实时画面”；或选“显示 → 收起实时画面”（⇧⌘B，作用于当前聚焦的 Pane），也可在命令面板搜索“收起或恢复实时画面”。Agent（如 Claude Code）接管鼠标时普通右键不会弹出菜单，这时用顶边的眼睛图标、⇧⌘B 或 Control + 右键。
• 收起后 Pane 中间显示一张小卡片：有 Agent 时显示 Agent 名称和任务状态（处理中 / 等待你确认或输入 / 空闲 / 已完成），“等待你确认或输入”会用醒目颜色标出；没有 Agent 时显示 Pane 标题。卡片只写收起的时刻（如“收起于 14:03”），没有走动的计时。
• 进程、Agent 和终端内容照常运行，终端尺寸不变；只是画面暂时不画。完成、等待输入等通知照常弹出，Aster 不会因此自动恢复画面或抢走焦点。
• 恢复：点卡片上的“恢复实时画面”，或再选一次同一菜单项（菜单会显示为“恢复实时画面”）。聚焦卡片时按 Return 或 Space 也会恢复。恢复后立即显示最新画面。
• 收起期间按键不会发给这个终端，避免在看不见的时候误输入；切换标签、切换应用都不会自动恢复。收起状态不会保存，关闭并恢复工作区后一律显示实时画面。
• 画中画中的 Pane（系统画中画或可交互小窗）不能收起，菜单项会置灰；对已收起的 Pane 打开画中画会先恢复实时画面。

Autocomplete 与 Inline Suggestion

在“设置 → 控制 → 自动补全”里选择按键：

• “接受候选”：Tab、Tab + 右方向键（两个键都能接受）、Control + Space，或“关闭”（不再用按键接受灰色建议）。macOS 默认用 Control + Space 切换输入法；选它之前，先在“系统设置 → 键盘 → 键盘快捷键 → 输入法”里关掉或改掉那个快捷键。
• “候选面板”：“自动”在输入时自动展开；“Esc 打开”按 Esc 打开；“Option + Esc 打开”按 Option + Esc 或 F5 打开；“关闭”永不显示面板。

候选面板可见时，Tab 可直接接受首项；Return 在明确选中候选后接受，未选中时仍交给 Shell。 工具明确给出的失败纠错属于确定建议，即使另有历史候选也可优先显示行内修正。

候选面板最多同时显示 8 行，超出部分可以用上下键滚动，右侧的侧栏给出当前选中项的完整说明。选中一条来自本机历史的候选（整行历史、最近使用的参数或命令名）后按 Shift + Delete 把它从历史中删除：整行历史直接删掉这条记录，参数或命令名只是不再作为候选出现，你再执行一次它就会回来；用 aster learn 钉住的命令和内置规格不受影响。空提示符（刚开 Pane 或命令刚结束、还没输入任何字符）不会自动弹出面板，敲下第一个字符后才展开，把输入退格删空后自动面板也会随之收起；此时按 Esc 仍可手动打开。面板打开后继续输入会按新前缀收窄，而不是关闭。自动面板先列出候选，不把第一条当作你的选择；用上下键选择后，Return 或 Tab 接受当前项。按一次 Esc 可以在本轮提示符内关掉它，再按一次 Esc 又能叫回来。把“Inline suggestion”和“候选面板”同时关闭等于完全停用该功能，内置规格库根本不会被查询。

Autocomplete 使用 Ghostty 的原始 PTY observer，继续显示 inline suggestion 和候选面板； 只有一个候选、第一名明显领先，或已明确选中某个候选时才显示 inline suggestion；切换选择时，预览和说明同步变化。

剪贴板建议

从浏览器、文档或聊天里复制一条命令，切回 Aster，空提示符上会用灰字提示这条命令，旁边标着“⏎ 粘贴”。 按回车只把它写进输入行，不会执行；确认无误后再按一次回车才运行。想忽略它，直接开始打字或按 Esc 即可， 同一份复制内容不会再提示第二次。

只有看起来确实是命令的内容才会提示：单行、不超过 128 个字符、不含控制字符、没有中文，也不是一个网址。 带选项、管道、重定向、&&、环境变量赋值或路径写法的内容会直接识别为命令，本机没装过这个工具也没关系； 只有「几个普通单词拼起来」这种既像命令又像一句话的情况，才要求第一个词是本机认得的命令 （内置规格库、你的别名、用过的历史命令，或 PATH 里确实存在的程序）。复制一段话、一个网址或一段日志时不会打扰你。 灰字出现后有极短的保护延迟才允许回车接受，避免你在空提示符上连按回车时误粘贴。

出于隐私考虑，密码管理器标记为“隐藏内容”的剪贴板（1Password、钥匙串等）永远不提示，安全输入生效时也不提示； 提示只出现在当前正在输入的那个 Pane 上。需要完全关闭时，在设置 → 控制 → 自动补全里关掉“剪贴板建议”。 注意灰字会把剪贴板内容显示在终端画面上，录屏或投屏时留意这一点。 预览使用当前终端字体，与输入保持同一行和同一基线，不覆盖 prompt 或已经回显的命令。接受候选、隐私过滤、本机学习与目录上下文规则保持不变。

空提示符会推荐当前目录的常用命令、固定命令和 README 命令，不会列出整个规格库。 上一条命令失败且能识别修正方式时，下一条提示符会优先显示纠错建议；继续输入可以忽略它。除了工具自己给出的「did you mean」和命令名拼写，Aster 还认得这些失败：git push 被远端拒绝（建议 git pull --rebase && …）、要新建的分支已存在（改为 git switch/checkout 过去）、cd 到打错的目录名（换成当前目录里名称最接近的目录）、Terraform 未初始化（先 terraform init）、权限不足（在前面加 sudo，排除 ssh 认证失败和带管道的命令）。命令没装（command not found）而它是已知的 npm / PyPI / RubyGems 命令行工具，或项目的 node_modules/.bin 里就有它时，Aster 会建议用包运行器临时执行：npx prettier …、pnpm dlx、bunx、uvx ruff …、uv run、poetry run、bundle exec rubocop …，参数原样保留。多条建议同时成立时首条画成灰字，其余在候选面板里用上下键选；灰字只是建议，回车前仍可改。 Shell 自己的灰色建议占据行尾时，Aster 隐藏行内建议，仍可用候选面板选择。 狭小 Pane 会减少面板可见行数，避免覆盖输入行。

命令名打完、还没敲空格时（例如 docker），候选里除了同前缀的其它命令名，也会直接给出这个 命令的子命令和选项——按 Tab 想看的是「它能做什么」，而不是「还有哪些可执行文件叫 docker*」。

Tab（或设置中的其他接受键）直接接受已经可见的建议，包括 zsh-autosuggestions 等 Shell 插件 画在光标后的建议；Aster 只发送建议后缀，不再触发 zsh 的「是否列出全部可能项」询问。 只有一个候选时只显示行内建议，不弹面板；已打开的面板收窄到一个候选也会自动收起。有多个候选但第一名明显领先时，也直接显示它的行内建议，按 Tab 接受：整行历史要比其它匹配的历史用得更多、并且是最近用过的那条；其它候选要在匹配程度和使用频率上明显高出第二名（约 1.5 倍）。当前目录里有多条同样常用的历史命令（比如 git commit -m … 和 git commit --amend）互相冲突时，Aster 不替你挑一条，只把它们共同的下一个词（commit ）画成灰字；Tab 只接受这个词，剩下的候选留在面板里按新前缀重算。 有多个候选且没有可见建议时，接受键可打开候选面板。既无可见建议又无候选时，才交给 Shell 原生补全。

按上下文补全：没有内置规格的命令按你的用法学：连续两次只给普通单词（foo bar、foo baz）之后，foo <Tab> 不再把整个目录倒出来；你再传一次真实路径它就恢复，打 ./、~/、/ 时永远列文件。cd 只列目录，指向目录的符号链接也算目录；cd .. 补成 ../，cd ~ 补成 ~/。历史里 cd 过、但现在已被删除或改名的目录不再推荐（远程会话不做这项检查）。命令子项位置不会混入无关项目文件。文件和目录名称包含空格、 单引号或双引号时，会沿用你已输入的引号与转义方式。选项支持 --参数=值，已经使用的非重复选项 不再推荐；-- 后按位置参数处理。历史参数按当前目录和参数位置学习，例如常用分支在增加 --force 后仍可推荐；关闭本机学习会同时停用这类历史参数建议。

PATH 里的程序：装了 Shell 集成后，Aster 在每个提示符前得知你当前 Shell 的 PATH（只传目录名，PATH 没变就不重发），据此补全 rg、mise 这类规格库里没有的程序名，剪贴板判断「这是不是一条命令」也用它；从 Finder 启动 Aster 一样有效。远端会话的 PATH 不上报。

动态候选：当内置规格声明某个参数需要活数据时（git checkout <分支>、brew install <formula>、npm run <script>、make <target>、ssh <主机>、cargo run --bin <名字>），Aster 直接读取磁盘上已有的文件——.git/refs、.git/packed-refs、.git/config、package.json、Makefile、Homebrew 的 Formula/ 与 Cellar/ 目录、~/.ssh/config 的 Host 别名（跟进 Include，通配模式不列）与 known_hosts 里未哈希的主机、Cargo.toml 与 src/bin/、examples/ 里的 bin / example / feature / workspace 包。scp、rsync 的 host:path 形态暂不补主机。Aster 绝不运行被补全的工具：补全 brew install 不会触发 brew update，补全 git checkout 不会在你的仓库里执行 git。最近 check out 过的分支会排在更前面（读的是 .git/logs/HEAD）。需要真正运行工具才能取到的数据（例如 git status --short 的暂存清单）不做动态候选，退回普通文件补全。

Homebrew 4.x 默认走 JSON API：如果你的机器上没有 homebrew-core tap，也没有 API 名称缓存，brew install 只会补出已安装的包和第三方 tap 里的 formula。这是“绝不联网、绝不触发 brew update”的必然代价。

Aster 不会把 package.json、Makefile 或 justfile 里的脚本当成顶层命令主动推给你——上面那些只在规格明确要求该参数槽位时才读取。需要固定项目命令时，先在“设置 → Shell → Aster CLI”安装 CLI，然后在目标目录运行：

aster learn 'npm run deploy'

aster learn 的参数如果是 PATH 上的一个裸二进制名，它会改为在禁网、禁写文件的沙箱里运行该工具的 --help，解析出子命令与选项写进本机补全库：

aster learn ripgrep

这样生成的规格单独保存，点击“立即更新”刷新内置规格时不会被覆盖。重复对同一条命令运行 aster learn 会提升它的排序权重。

aster ignore 是 aster learn 的撤销，三种目标一一对应：

aster ignore ./old-project      # 不再把这个目录算进常用目录
aster ignore 'npm run deploy'   # 取消固定这条命令
aster ignore ripgrep            # 删掉这个工具的本机 help 规格

撤销固定命令时，如果你确实跑过它，普通使用历史会保留下来——只是不再被钉在最前面。内置 CLI 规格不是你学出来的，aster ignore 不会删它。

“本机学习”默认开启。学习库只保存脱敏后的命令、目录和计数，不保存输出；--password、--token、--api-key 等值会被移除；打开“跳过含凭据的命令”（默认关）后，命令里一出现密码、令牌、密钥（export AWS_SECRET_ACCESS_KEY=…、ghp_…、https://user:pass@host、-H "Authorization: Bearer …"）整条就不记录、也不纠错，只有真正执行过的命令才会学习：退出码 126/127、输出里明确写 command not found 的命令、明显错误的长选项和“历史忽略模式”匹配项不会保留。内置结构不完整的命令会以 --help、-h、help 固定参数在禁网且禁止写入文件的沙箱中探测，并限制为 2.5 秒和 128 KiB。判定看的是「有没有选项和参数」而不只是「有没有子命令」——上游规格里 docker 就是 58 个子命令配 0 个选项，只看子命令会让它的顶层 flag 永远补不出来。探测会挑最深的那个不完整层级：docker compose 在上游规格里是个只有名字的空壳，Aster 会去探测 docker compose --help 而不是顶层。探测结果与内置规格按字段合并（子命令、选项取并集），不会把内置规格独有的嵌套结构冲掉；远程会话不会读取本机项目文件或运行本机 help 探测。关闭本机学习后，历史、固定命令、README、纠错与 help 探测全部停用，内置规格和文件补全仍可用。

按你的习惯排序：补全会记住你在所有目录里常用的命令、子命令、选项和参数。换到新目录后，cl 仍会先补你常用的 claude；git ch 会先补你常用的那个子命令。内置规格里没有的命令（如 claude、codex）和常用参数值（如 ssh 的主机名），在任何目录都能补出来。补全也会看上一条命令：你常在 git add 之后执行 git commit，那么执行完 git add 后，git commit 会排在前面。上一条命令失败时不参考它。这些都只调整顺序，不会自动执行命令。清空学习数据时一并清空。

Fig 命令清单不会后台更新。控制页会显示当前规格数量和版本；需要刷新时，在同一设置区域点击“立即更新”，本地 help 规格不会被覆盖。“清除…”可分别删除命令历史、固定命令和目录频率数据，不删除内置、手动更新或 help 规格。

Unicode、双向文本与终端图片

• Aster 支持组合字符、CJK 双宽字符、emoji ZWJ/肤色/旗帜序列、text/emoji variation selector，以及 24-bit truecolor、256 色和完整 SGR 样式。圈字母数字默认按两列显示；可在“设置 → 高级 → 加宽 East-Asian-Ambiguous Block”选择其它 block。该宽度策略只影响新建标签和之后写入的字符。
• “设置 → 外观 → 文本”可选择关闭、标准或 discretionary 连字，并设置粗体、斜体与 blink 的渲染策略。blink 默认稳定显示；选择动画后才会闪烁。
• 双向文本默认开启。希伯来文、阿拉伯文和混合方向行按阅读顺序显示，但复制、查找和粘贴仍使用程序写入的逻辑顺序；左右键与鼠标命中跟随视觉位置。遇到自行排版 RTL 的全屏 TUI，可在设置中关闭。程序进入 ECMA-48 mode 8 时 Aster 会自动暂停隐式重排。
• 终端程序可以显示 iTerm2、Kitty 和 Sixel 图片。Aster 会限制输入、分片、解压、像素尺寸与缓存；损坏、取消或超限图片会被丢弃，不影响之后的正常终端输出。
• 应用包原样内置 Otty 1.3.1 使用的 JetBrains Mono、Office Code Pro 和 Symbols Nerd Font Mono，同时保留 Aster Nerd Symbols fallback；无需另行安装这些字体。即使选择的基础字体没有 Powerline 或 Nerd Font 图标，终端仍能解析 BMP 与补充平面符号。

任务进度、徽章与通知

终端程序可通过 OSC 9;4 报告百分比、不定进度、错误和完成状态；支持 Shell Integration 时，Aster 也会为“设置 → 高级 → 自动进度命令”列表中的常见慢命令自动显示运行状态。列表按空白分词前缀匹配，例如 git push 会匹配 git push origin main，但不会匹配 git pushd；清空列表即可关闭自动匹配。

标签会在名称右侧显示运行、刚完成、未读完成、错误和等待输入状态；Agent 在处理、请求确认、恢复处理和完成之间切换时，图标会就地变化，不会重建终端或打断输入。未安装 lifecycle hook 时，Claude Code / Codex 启动后连续约 5 秒没有输入或输出，标签会停止旋转；再次输入或收到输出会恢复运行状态。已安装 hook 时始终以 Agent 的精确 lifecycle 为准，不会因静默推理而提前停止。等待输入只在 password、[y/n]、yes/no 或 Press Enter 提示停留约 1.5 秒后出现，输入任意内容即清除；Agent 完成后的未读圆点也会在用户继续输入后清除。外观设置可开启 Dock 运行动画；错误标红默认开启，Dock 图标标红时点击它会跳到失败标签并清除当前提示。确认过的错误不再标红，此后从别的程序切回 Aster 只会回到你最后使用的标签，不会再被拉到出错的标签。

安装 aster CLI 后，可以包装一次性任务或直接设置当前标签徽章：

aster watch make deploy
aster watch -q cargo test
aster tab badge --kind awaiting-input
aster tab badge --clear

watch 保留被包装命令的原退出码；-q 只关闭本次完成通知，不关闭进度和徽章。

终端应用可使用 OSC 9、OSC 777 或 OSC 99 发送 macOS 通知。OSC 99 支持独立标题/正文、紧急级别、base64、分片和同 ID 替换。Shell 设置可分别控制：成功、错误与 watch 完成通知，Shell Controlled，总在前台/仅未聚焦标签/关闭的前台策略，Dock 弹跳，错误退出 beep、BEL，以及错误/完成/应用通知是否附带声音。系统权限行显示 macOS 当前状态并可打开系统设置。

标题权限位于“设置 → 高级”：Shell Controlled 控制 OSC 0/1/2 是否能修改标题；“标题报告”控制程序能否读取标题，默认关闭。OSC 52 剪贴板权限与安全键盘输入仍分别位于“控制”。