本地 Shell

本地 Shell 让你在正坐着的这台 Mac 上开一个 shell，和远程会话同在一个窗口里： 同样的主题、同样的字体、同样的代码片段、同样的标签页。它需要一个小的配套 App SwiftServer Helper，从 SwiftServer 的设置里安装一次即可。

为什么需要一个配套 App

SwiftServer 通过 App Store 分发，因此运行在 Apple 的沙盒里。由 App 自己启动的 shell 会继承这个沙盒：它读不到你真正的个人文件夹，跑不了 Homebrew 的工具， 行为和 Terminal.app 完全不一样。

SwiftServer Helper 解决了这个问题。它是一个独立的、经过公证的 App， 以 launchd agent 的身份在沙盒之外运行。伪终端由助手持有，你的登录 Shell 也由它启动； SwiftServer 通过 XPC 连接到它并把结果画出来。其他沙盒 Mac App 在处理沙盒禁止的工作时， 用的也是同一套形态。

SwiftServer 的其他部分都不依赖这个助手。没有它，SSH 和 Mosh 会话照常工作。

要求

• macOS 15 或更高版本。
• Mac 版 SwiftServer 2.2 或更高版本。
• 仅限 Mac。本地 Shell 不会出现在 iPhone 和 iPad 上。

安装

SwiftServer Helper 要单独下载。App Store 的沙盒不允许 SwiftServer 运行或打开任何 它自己下载的文件，所以下载由浏览器完成，拿到的是一个普通的安装包。

1. 打开设置 → 本地 Shell，选下载安装器。浏览器会把 SwiftServerHelper-<version>.pkg 下载到你的「下载」文件夹。
2. 打开下载好的安装包，按安装器的提示操作。它安装到你自己的个人文件夹里， 所以不会要求管理员密码。助手没有窗口，也没有菜单栏图标。
3. 回到 SwiftServer。安装完成后本地 Shell 页面会自行更新；如果你一直停在等待状态， 重新检查会立刻重读一次。如果 macOS 要求批准，按下面的说明批准助手。

已发布的每个版本都列在 /downloads/helper/，当前的安装器是 SwiftServerHelper-1.1.0.pkg。

打开一个本地终端

• 菜单栏里的终端 → 新建本地终端，或者该菜单项旁边显示的快捷键。
• 仪表板工具栏里的新建本地终端。

本地会话和 SwiftServer 里的其他终端表现一致。关掉它就等于挂断这个 shell， 和关掉一个 Terminal.app 窗口是一回事。

这个 shell 能拿到什么

• 你的登录 Shell：从 macOS 的账户记录里读出来，除非你改过，否则就是 zsh。
• 登录 Shell 的环境，和 Terminal.app 完全一样。PATH 从 /usr/bin:/bin:/usr/sbin:/sbin 开始，再由你的 shell 依据 /etc/zprofile 和你自己的 profile 重建，所以 Homebrew、asdf、nvm 以及你配置的其他东西都在 PATH 上。
• TERM=xterm-256color、COLORTERM=truecolor 和 TERM_PROGRAM=SwiftServer， 外加由你的区域设置推导出的 LANG。
• 你的 ssh-agent：当 macOS 把它的 socket 提供给助手所在的登录会话时， SSH_AUTH_SOCK 会被传进来，因此 agent 里的密钥在本地终端里可用。
• 你的个人文件夹作为工作目录，除非你使用的那个操作把会话开在别处。
• 与 SSH 会话相同的主题和字体、代码片段以及检查器。

由于这个 shell 运行在沙盒之外，某条命令第一次碰到「桌面」「文稿」「下载」或者可移除宗卷、 网络宗卷时，macOS 会请求文件访问权限，就像一台新 Mac 上的 Terminal.app 那样。 提示里出现的名字是 SwiftServer Helper，因为真正运行你命令的是这个进程。 每一类批准一次，或者拒绝它并改用磁盘上的其他位置。要彻底不再出现这些提示， 就给 SwiftServer Helper 授予「完全磁盘访问权限」；本地 Shell 页面上有一个按钮， 可以直接打开对应的设置面板。

更新

助手的更新和 App Store 上的 App 相互独立。

• 设置 → 本地 Shell里的检查更新会把已安装的版本和已发布的版本比一比。 存在更新的助手时，页面会给出更新助手，助手随后原地替换自己， 既不用浏览器，也不用安装器。页面上有一条进度条跟着走。
• 自动检查更新会在你打开设置或主窗口时做同样的检查，每天最多一次， 并把结果显示在本地 Shell 页面上。它不会用通知打断你。
• 更新前请关掉所有本地终端。更新会替换正在运行的助手， 打开着的本地会话会在命令执行途中被挂断。远程会话不受影响。

卸载

用设置 → 本地 Shell里的卸载助手，或者直接运行已安装的那一份：

"$HOME/Library/Application Support/SwiftServer Helper/SwiftServer Helper.app/Contents/MacOS/SwiftServer Helper" --uninstall

从设置里卸载是常规做法，命令行那条是给脚本化配置用的。两种方式都会移除 launch agent 的注册、助手为 SwiftServer 写下的状态文件，以及 ~/Library/Application Support/SwiftServer Helper/。你的 SwiftServer 设置、机器、 主题、字体和代码片段都不会被动，远程会话也照常工作。随时可以从设置 → 本地 Shell 重新安装。

安全与隐私

• 助手只接受由 GitSwift（Team ID 7732437C8W）签名的 SwiftServer 的连接， 而 SwiftServer 也只和同一团队签名、bundle identifier 为 com.gitswift.SwiftServerHelper 的助手通信。别的 App 没法借它来执行命令。
• 不监听网络。助手从不开放端口，也从不接受远程连接。只有在你要求更新时， 它才会访问网络，从 swiftserver.app 下载自身的更新；SwiftServer 也从同一个地方 获取更新清单。这个地址固定写在助手的代码里，被篡改的清单无法把它引到别处。
• 没有任何 entitlements。它以你的身份、在你的登录会话里运行，权限和你完全一致。
• 分发时使用 Developer ID 证书、加固运行时和 Apple 公证。
• 你的按键和 shell 输出都留在这台 Mac 上，只在 SwiftServer 和助手之间通过 XPC 传递。

故障排查

本地 Shell 页面会说清楚它发现的是哪种情况，并给出解决它的那一个动作，所以先从这个页面看起。

「未启动」。助手在磁盘上，但 macOS 没有启动它。从外面看，三种原因是一样的： macOS 还在等你允许这个登录项、你在登录项里把 SwiftServer Helper 关掉了、 或者安装器做的注册没有生效。页面把每种情况的办法都列出来了： 用打开「登录项」设置去允许或打开它，用修复注册重新向 macOS 注册，然后选重新检查。 SwiftServer 不用重启就能感知到变化。

「无响应」。助手已安装也注册过，但不回应。修复注册会重新向 macOS 注册它， 通常这就够了。请先关掉你的本地终端。

原本能用，现在显示「未安装」。助手是在 SwiftServer 之外被删掉的。选下载安装器重新装一次。

「需要更新」。已安装的助手比当前这个版本的 SwiftServer 所要求的旧。选更新助手； 如果页面说这个助手旧到无法自行更新，就选下载安装器。

「等待安装器」迟迟不动。SwiftServer 正在等助手出现。如果你还没打开下载好的安装包， 现在打开它；如果已经打开过了，就选重新检查。

「SwiftServer 版本过旧」。每个助手版本都声明了它支持的最低 App 版本。 请从 App Store 更新 SwiftServer，而不是重装助手。

shell 立刻退出。助手启动的是你账户里登记的登录 Shell。 如果那个路径不存在或者不可执行，会话会立刻结束。用这条命令检查：

dscl . -read /Users/$USER UserShell

在系统设置 → 用户与群组里改（右键点你的账户，然后选高级选项）， 或者用 chsh -s /bin/zsh。

读助手的日志。助手把日志写进统一日志，子系统为 com.gitswift.SwiftServerHelper， 分成 installer、service 和 shell 三个类别：

log stream --predicate 'subsystem == "com.gitswift.SwiftServerHelper"'
log show --last 1h --predicate 'subsystem == "com.gitswift.SwiftServerHelper"'

复现问题的时候用 log stream，查已经发生过的事情用 log show。 联系支持时请把输出一并附上。

命令行选项

已安装的助手在 ~/Library/Application Support/SwiftServer Helper/SwiftServer Helper.app， 它的可执行文件接受几个参数。正常使用完全用不到这些参数， 它们是给脚本化配置和排查安装问题用的。