项目与会话

项目复制链接

一个项目就是一件正在做的事——实际用起来通常就是一个仓库——有自己的终端、标签页和面板状态。

Cmd+N 新建一个，里面带一个终端。这个终端从当前会话的目录启动；如果没有当前会话，就从你的用户主目录启动，所以接下来通常是 cd 到目标位置。剩下的 Zshell 会接手：文件树和 git 面板会锚定到包含那个目录的仓库上。

想省掉这次 cd，在 Finder 里右键一个文件夹，选 服务 → New Zshell Project Here——它会作为一个项目打开，终端已经在里面启动好了。

项目是 Zshell 切换的基本单位：

项目的名字来自它当前选中的会话——也就是说，它跟着终端走，和标签页标题一样。右键侧边栏里的项目，可以 Rename…（Use Automatic Title 撤销）、Set Project Directory… 和 Close Project。关闭项目会结束它的会话，但不会动磁盘上的任何东西。

远程共享会话采用不同的关闭行为：关闭面板或项目只会分离当前客户端，主机上的 shell 和任务继续运行。

保存 SSH 项目复制链接

打开命令面板（Cmd+P），选择 新建 SSH 项目…。填写主机、 可选的用户名和端口，以及要打开的远程目录。认证方式可选 SSH 代理、密码、 私钥文件或私钥内容；保存连接后，选中它并点击 连接。

保存的连接会在重启后保留。可选的 分组 字段用于整理连接列表，每条连接旁边的编辑、 删除按钮用于维护条目。密码和粘贴的私钥保存在 macOS 钥匙串中；选择私钥文件时，记录的是 已有密钥文件的路径。

经常运行的命令或需要附加 SSH 选项的启动项，可以使用快捷启动。

侧边栏分组复制链接

点击侧边栏底部的 新建分组，可以创建普通分组或文件夹分组。普通分组中新建的终端从用户主目录启动；文件夹分组提供选定的默认目录。手动固定的项目目录始终优先。移动项目到其他分组，不会改变正在运行的终端，也不会覆盖已固定的目录。

把项目拖到分组标题或另一个项目上即可归组，拖到侧边栏底部的 ＋（新建项目） 可以移出分组。分组标题之间也可以拖拽排序。单击标题折叠或展开，双击重命名，右键打开分组菜单。通过 设置颜色标记… 自定义分组颜色，或用 移除颜色标记 清除。移除分组 会保留其中所有项目。数字快捷键按当前可见项目的顺序排列；上一项、下一项导航可以切到折叠组内的项目，并自动展开该组。

也可以从 Finder 把文件夹拖到侧栏项目列表。已打开的文件夹会被选中，不会重复创建项目。

项目目录复制链接

有两个面板需要知道自己在显示哪个文件夹：文件树和 git 面板。默认情况下 Zshell 自己判断—— 它从终端的当前目录出发，往上找到最近的那个包含它的 git 仓库。

所以在仓库里 cd 来 cd 去，文件树不会跟着跳：仓库根目录始终是根目录。不在仓库里时，这两个面板就单纯跟着终端走。

如果前台程序进入了另一个 checkout——比如 agent 切进自己的 Git worktree——文件、Git 和信息面板会跟着那个 checkout，前台任务回来时再恢复。手动固定的项目目录始终优先，也会关闭这种自动换根。

想固定住，右键项目选 Set Project Directory…。固定的目录会跨重启记住，Use Automatic Directory 则交还自动判断。

会话复制链接

每个项目可以有任意多个会话，显示为顶部的标签页。一个会话就是一个真正的登录 shell—— zsh、fish、bash，你账户设成什么就是什么——各有自己的工作目录和滚动历史。

本地新会话优先从固定的项目目录启动，其次使用侧栏分组的默认目录。没有这两项时，它继承当前会话的目录，再回退到用户主目录。

标签页分组复制链接

右键标签页选择 移动到分组 → 新建标签页分组。该标签会加入新组，分组在标签栏中仅显示彩色箭头，不显示名称。选中组内标签后新建的会话会留在该组；右键分组箭头选择 在分组中新建会话，也可以直接在组内创建会话。

把标签拖到分组箭头或另一个标签上即可移动。右键菜单也可以选择目标分组，或 移出分组。单击分组箭头折叠、展开。折叠时当前终端仍会运行并继续显示；切换到隐藏的标签会自动展开其分组。移除分组会保留所有标签与会话。固定组内标签时，该标签会移到分组之外的固定区。右键分组箭头可以 设置颜色标记… 或 移除颜色标记。标签页分组的颜色、折叠状态都会在重启后恢复。

标签还可以拖到侧栏已有项目，或拖到侧栏分组标题，在该分组内创建新项目。拖到侧边栏底部的 ＋（新建项目） 会创建不属于任何侧栏组的新项目。右键菜单的 移动标签页到项目 也支持其他窗口。移动会保留运行中的终端和窗格布局。目标项目必须具有相同的本地或 SSH 位置；从标签创建新项目时会继承来源位置。包含 Diff 的标签保留在原项目中。

标签页标题复制链接

标签页标题来自终端自己报告的内容——你 shell 提示符里的转义序列，或者当前正在跑的程序。右键标签页可以 Rename… 手动改名，Use Automatic Title 则回到跟随终端。

标签页菜单里其余的是常规那一套：Close、Close Others、Close Tabs to the Right、 Close All，外加针对会话目录的 Reveal in Finder 和 Copy Absolute Path。Close Files 与 Close Diffs 会清掉项目里的对应内容，但保留终端和浏览器窗格。

窗口复制链接

Cmd+Shift+N 新开一个窗口。窗口之间互相独立——各自的项目、各自的侧边栏状态——恢复时也是分开恢复的。

重启后还剩下什么复制链接

Zshell 会随着你的操作持续快照布局，所以退出再打开会拿回：

• 每个项目，顺序不变
• 每个标签页，包括自定义名称、固定状态和颜色标记
• 侧边栏分组的名称、颜色标记、顺序、成员和折叠状态
• 标签页分组的颜色标记、顺序、成员和折叠状态
• 固定的项目目录和空项目
• 每个标签页里的窗格布局
• 哪些侧边栏是打开的、右侧选中的是哪个面板

原终端 PTY 不可用时，若启用了 恢复 Agent 对话 和 AI 支持，Zshell 会继续已验证的 Claude Code、Codex、Pi 或 OpenCode 原对话。其他窗格在原目录打开新 shell。对话按原身份恢复；Zshell 不会重放命令来恢复运行中的构建。

开启 terminal.restore-history 时会恢复之前的滚动历史。 新配置默认开启；恢复的滚动历史会保存在磁盘上。

终端环境与初始化命令复制链接

选中项目后，通过 Terminal → Project Terminal Environment… 配置项目环境变量和初始化命令。 要只修改当前标签页，使用 Terminal → Tab Terminal Environment…。

保存后只影响之后创建的终端，已经运行的进程不变。初始化命令仅用于正常的登录 shell；自定义启动程序或显式传入 argv 时不执行。 ZSHELL_*、TERM、COLORTERM、TERM_PROGRAM 和 TERM_PROGRAM_VERSION 由 Zshell 管理，不能覆盖。