简体中文 · English

Snake

Snake 是面向 macOS 15+ 的原生 SSH 工作台：会话管理、终端、SFTP 文件传输和 SSHFS 磁盘映射共用一个多窗口工作区。

官网与在线演示：snakem.com

1.4.2 安装

当前安装包为 Apple Silicon（M 系列）版，要求 macOS 15 或更高版本，不包含 Intel / Universal 2 版本。

1. 打开 Snake-1.4.2-macos-arm64.dmg。
2. 将 Snake.app 拖到 Applications（应用程序），等待复制完成。
3. 推出磁盘映像，从“应用程序”启动 Snake。更新旧版前先退出应用，复制时选择替换。

目前已生成本地安装包，上传 GitHub Releases。构建产物在 release/，不随源码提交；发布附件为 DMG 和同名 .dmg.sha256 校验文件。

当前包仅使用 ad-hoc 临时签名，未经过 Developer ID 签名与 Apple 公证，首次打开可能被系统拦截。 签名完整性检查通过不代表 Gatekeeper 放行；安装与安全提示见 安装说明。安装包不包含用户会话、密码或测试配置，磁盘映射所需的 macFUSE / sshfs 也不自动安装。

将 DMG 与校验文件放在同一目录，在该目录执行：

shasum -a 256 -c Snake-1.4.2-macos-arm64.dmg.sha256

本次更新见 1.4.2 版本说明，构建、签名与公证步骤见 发布流程。

当前功能

会话与多窗口工作区

• 原生 AppKit/SwiftUI 界面、统一顶部栏和浅色/深色外观；SSH 会话页用卡片管理，按可嵌套的文件夹整理，不再使用侧栏或标签。磁盘映射、MCP 服务与密码管理从右上角入口打开，和终端、SFTP 一样以整窗标签显示；新增与编辑统一使用同一套分组表单弹窗。设置窗口为带侧栏的大窗口（外观、传输、快捷键、终端、隐私与安全），打开时为模态，关闭后才能继续操作其他窗口。
• 启动默认打开 SSH 会话页，不注入示例服务器、示例映射或伪终端输出。双击标签栏尾部空白，或按可在设置中修改的 Command-T（默认值），可在当前分栏新增会话页，并自动聚焦检索框。
• 会话页上方是文件夹卡片、下方是未归类会话；单击选中、双击打开文件夹。文件夹可在任意一层新建子文件夹、编辑名称与图标、删除（其中会话和子文件夹移到上一层）；搜索覆盖名称、IP、用户名和文件夹。按住卡片拖动可调整文件夹或会话顺序（其他卡片会让位），把会话拖到文件夹上移入、把文件夹拖到另一文件夹中间移入，拖到顶部路径的任一层可移到该层；也可用右键「移到文件夹」或编辑页选择文件夹。旧版标签在首次启动时按第一个标签迁入同名文件夹。支持自定义照片图标裁剪。会话卡片为紧凑单行，只显示图标、名称和地址；双击打开终端，右键菜单打开 SFTP。编辑弹窗按内容自适应高度，点击头像更换图标，底部显示创建时间和最近更新时间；只有修改会话内容或密码才算更新，排序、启动时的重新保存不改变更新时间。卡片按钮、双击及右键连接操作将当前管理标签原位转换为终端或 SFTP，不追加标签。
• Bonsplit 支持标签排序、左右/上下分屏、拖出独立窗口及跨窗口合并。会话页的卡片拖动只用于排序与归类，不再拖入工作区建立连接；移动已有连接标签不重连。
• 主工作窗口中 Command-W 只关闭当前标签或多余空分栏，最后一个空分栏保持窗口打开。红色按钮只关闭窗口，Dock 重新打开恢复当前进程中的工作区；不恢复跨应用重启的标签布局。

SSH 终端与配色

• Rust/russh TerminalHandle 提供真实 SSH PTY，SwiftTerm 负责渲染（默认 Metal GPU）与输入。支持密码/私钥认证、主机密钥校验、真实协商算法详情、UTF-8 输入输出、PTY resize、远端退出和 5 秒 Keepalive；同一会话的终端、SFTP 浏览与 MCP 命令复用一条已认证连接，传输分片使用独立连接；瞬时连接错误自动重试一次，断线后自动重连，并显示具体失败阶段。SFTP 标签每 2 秒检查一次所用连接，网络断开后自动按 0.5/2/5 秒重连并回到原目录，不再停在旧连接的错误上。新开的 SSH 会话标签直接打开上次浏览的文件夹（文件夹已删除则回到最外层）。终端与 SFTP 连接时显示连接动画，可取消或「查看日志」；连接失败时动画保留、中间链路显示为断开，并给出原因与「重新连接」。连接日志按标签记录每次尝试的开始、用时、协商算法、失败阶段码与自动重试，不含密码或口令，可一键复制。终端右键菜单提供复制、粘贴、粘贴所选内容、全选、清屏、上传文件到当前目录、在 SFTP 中打开当前目录、复制 SSH 命令、重新连接与查看连接日志；SSH 会话页在空白处右键可新建会话或文件夹（在文件夹内则新建到该文件夹）。所有右键菜单（终端、会话卡片、SFTP、映射、隧道、密码与密钥）统一风格：每项带图标，主要操作在前、其后分组带小标题，删除类操作单独置底并标红，不可用项置灰而非隐藏，菜单项不带省略号；会话卡片和 SFTP 文件另可复制 SSH 命令或路径。会话编辑页用「密码类型」下拉框在密码与密钥间切换，密钥可直接从密钥管理下拉选用或选择本机文件。
• 设置支持终端字体、字号及“Ghostty 清晰”“纯白”“经典”“鲜明”“Tokyo Night”“Catppuccin”“Gruvbox”“Solarized”内置主题，也可导入、删除 .itermcolors。默认 Ghostty 清晰，深色使用灰黑背景、白色正文和提高可读性的 ANSI 色；首次升级将原 Tokyo Night 选择迁入，其他主题保留。“纯白”在应用深色外观中也保持白底深字；其他内置浅色主题使用白底，导入主题保留原色。主题切换保留连接与输出缓冲。
• 日志关键词和权限、时间、路径、地址等输出字段可本地高亮，不改写终端数据；尊重远端 ANSI / True Color，备用屏幕停用本地高亮。
• Snake 不再自动改写远端 ls/ll、LS_COLORS 或 CLICOLOR；若服务器自身输出 ANSI 色，终端照常显示。详见 当前终端配色说明。

SFTP 与文件传输

• 支持路径输入、前进/后退/上一级、文件检索、软链接、新建文件/文件夹、重命名、可视化权限与递归权限修改、Command/Shift 多选删除，以及远程文件下载到缓存后打开。
• 打开远程文件的缓存目录可在设置中更换（默认系统缓存目录），并按保留时长与容量上限自动清理，默认 7 天 / 500 MB；也可随时手动清理。回收只针对 Snake 自己下载的副本，不会改动所选目录中的其他文件。
• 文件夹和空白区域右键提供新建与上传入口，目标均为当前浏览目录。文件/文件夹可下载到用户选择的本地目录；文件夹传输保留目录层级及空文件夹。
• Finder 文件/文件夹可拖到 SSH 终端或 SFTP 内容区上传，与标签拖动隔离。SSH 使用最近报告的 Shell 目录，未知时先确认；SFTP 使用当前目录。详见 Finder 上传说明。
• 上传与下载支持配置化并行传输，默认超过 50 MB 使用 4 个连接分片。上传支持分片续传与隐藏暂存文件安全覆盖；SFTP-only 兼容路径失败重试重新上传。把文件从一个 SFTP 标签拖到另一台服务器时经本机中转：先下载到设置「传输 › 服务器互传」中的中转目录（默认系统缓存目录），再上传到目标的当前目录，上传结束后（无论成功、失败或取消）立即删除中转文件；两段进度都显示在目标标签的传输记录里，冲突按上传规则询问，不传输软链接，失败后需重新拖动。同时进行多个传输时，同一台主机的分片与逐文件传输连接受「每主机连接数」限制（默认 8，可设 2–16）；每个标签的常驻连接、每个上传批次的 1 条操作连接不计入。超出的传输会排队并在记录里显示“等待中”。
• 优先使用远端 SHA-256，无法使用时尝试 MD5；不可用或探测失败时标记“未校验”，不阻止正常上传/下载，不回读远端文件。已获得的双方摘要不一致仍视为失败，不覆盖旧文件。详见 下载与完整性校验。
• SSH 连接带和 SFTP 底部按需显示紧凑进度入口，点击查看当前标签的文件级记录、耗时、结果与校验状态，并可暂停、继续、取消或重试。记录不写入 SQLite，关闭标签或退出应用后清空。
• SFTP 默认快捷键：Command-F 检索、Command-Delete（⌫） 删除、Command-U 上传文件；可在设置中修改。

磁盘映射与数据

• 支持 macFUSE/sshfs 依赖检测、映射编辑、密码与私钥 SSHFS 挂载、Finder 打开与安全卸载，使用受约束的 SnakeMountHelper。密码（或已保存的私钥口令）经受管 SSH_ASKPASS 通道交给 ssh，只尝试一次，挂载失败时清理整个进程组。
• 磁盘映射页切换到「SSH 隧道」可做本地端口转发（等同 ssh -L）：选一个 SSH 会话，填本地端口、远端主机（按服务器视角，默认 127.0.0.1）、远端端口和备注。本地端口只监听 127.0.0.1；每条隧道单独建立一条 SSH 连接，需要该服务器的主机指纹已在终端里确认过。状态显示运行中的连接数；SSH 断开后停在「已断开」，需手动重连；可设随 Snake 启动。删除会话时其隧道保留但解除绑定。映射与隧道列表共用同一套行样式：左侧名称与路径，右侧状态和「自动挂载/自动连接」徽标，最右是挂载/打开或连接/断开、编辑和删除按钮；单击立即选中，双击编辑。映射编辑页的「访问路径」竖向列出远程目录 → 实际挂载点（含 Finder 磁盘名）→ Finder 入口，每条路径整行显示并可复制。
• Finder 磁盘名称显示“映射名称 · SSH 会话名称”；以系统实际挂载表为准。退出时如还有未卸载的目录或正在运行的 SSH 隧道，会在同一个确认框里列出：确认后等待挂载操作、安全卸载受管映射并断开隧道，卸载失败取消退出；取消则保持原样。仅关闭窗口或映射标签不卸载磁盘。
• Rust snake_core 提供 SQLite 数据存储、会话/映射/传输记录接口及 UniFFI Swift 绑定；凭据单独加密保存，不写入数据库。

本地 MCP 远程命令

• 在右上角「MCP 服务」标签中启用回环 HTTP 服务，默认地址为 http://127.0.0.1:47821/mcp；创建绑定指定 SSH 会话的 Token，可配置有效期、吊销与删除。
• MCP 客户端先调用 list_sessions，再用返回的会话 ID 调用 run_command。命令使用远端 /bin/sh，没有 PTY；每次调用独立，使用 cwd 或 cd / && ls -l 指定目录，不支持交互程序。
• Token 加密保存；查看已有 Token 需要系统身份验证。命令、返回摘录和拒绝记录进入审计，可筛选、删除和设置滚动保留策略；保留天数与条数在按回车或离开输入框时才生效，修改本身不删除记录，超出部分在启动、每新增 100 条、每小时或点「立即清理」时删除。Token 赋予所绑定 SSH 账号的执行权限，不能当作只读沙箱；命令和输出中不要放秘密。服务不监听公网，不在安装包中附带真实 Token。

安全边界

• 密码和私钥口令使用 AES-256-GCM 加密保存到 ~/Library/Application Support/Snake/credentials.json，随机 256 位密钥保存在系统钥匙串，文件权限为 0600、目录为 0700。文件损坏或密钥丢失时不会覆盖原文件或回退明文。
• 连接自动解密；编辑页查看已保存的明文须通过 Touch ID 或 Mac 登录密码等系统身份验证，30 秒后或窗口失焦时隐藏；验证通过后 30 秒内查看其他密码或口令不再重复验证。临时签名更新仍可能触发独立的钥匙串访问授权，不保证开发包无提示。
• SQLite 仍只保存 credential reference，不保存密码；后续接入密码工具时只替换 CredentialStore 后端。
• 私钥通过 security-scoped bookmark 引用；直接选择的文件不复制。
• 密码管理标签内的「密钥」页可导入 OpenSSH/PEM/PuTTY 私钥或生成 Ed25519 密钥，并复制 authorized_keys 公钥行。导入的私钥统一转存为 OpenSSH 格式（口令不变），以 0600 文件保存在 ~/Library/Application Support/Snake/Keys/（目录 0700），口令加密保存；新建或编辑会话时可从「密钥管理」菜单选用，终端、SFTP、MCP 与 SSHFS 都使用同一文件。指纹重复的私钥不会重复导入，仍有会话使用的密钥不能删除。密码与密钥列表都显示创建和修改时间（重命名、改用户名或改密码都算修改）；单击立即选中，双击打开编辑，密钥的编辑窗口可改名，并显示公钥、指纹和使用它的会话。
• 右上角的密码管理标签加密保存常用账号和密码，填入 SSH 后各会话保有独立副本；条目变更可多选关联会话同步，会话单独改账号或密码会解除关联。私钥编辑页展示书签解析出的本机路径。
• 设置 › 隐私与安全可关闭「点击密码输入框时显示系统密码自动填充」；关闭后 Snake 的密码与私钥口令输入框不再弹出 macOS「密码」的自动填充建议（默认开启，不改动系统设置）。
• SSH 终端、SFTP 和远程目录选择器在主机密钥变化时显示原、新指纹，只有明确确认后才更新对应地址和端口的信任记录并重连；取消保留原记录，重连时再次校验实际指纹。
• SnakeMountHelper 只接受受管挂载目录与允许列表中的 sshfs 可执行路径。
• 终端凭据以字节通过 UniFFI 传给 Rust/russh，认证材料在使用后清零；连接池只按凭据摘要区分，不保存明文；不会启动系统 ssh，也不会把密码传递给 argv、环境变量或拖放载荷。
• 密码型 SSHFS 挂载不经 argv、环境变量或文件传密：App 在私有临时目录开一次性 Unix socket，只向本用户、可执行文件为 SnakeMountHelper 且处于本次挂载进程组内的 askpass 进程交付密码；挂载结束即清零并删除。

多语言

• 内置 简体中文（源语言、默认与回退） 与 English 两种界面语言，可在「设置 › 外观 › 语言」中切换；选择立即生效并会被记住。
• 系统权限弹窗、Finder 与 macOS 提供的菜单文案跟随系统语言，不由应用内选择决定。
• 新增一种语言：复制 Resources/Localization/en.lproj 为 <语言>.lproj，翻译 Localizable.strings（key 是简体中文原文，必须保留每个 %@ 占位符及 <key>#plural 复数条目），把语言加入 Resources/Info.plist 的 CFBundleLocalizations 与 AppLanguage.supportedIdentifiers，再运行 swift test --disable-sandbox --filter LocalizationTests 校验完整性。
• swift run Snake 不是打包后的 .app，Bundle.main 找不到 .lproj，界面会保持简体中文；验证其他语言请使用 scripts/package-debug-app.sh 生成的 Snake.app。

尚未完成的能力

• 不恢复跨应用重启的工作区或自动继续中断传输；下载失败重试从新的源版本重新下载，不承诺下载断点续传。
• Intel / Universal 2 安装包、Developer ID 签名与公证尚未交付。
• 1.4.2 验证：Swift 281 项中 274 项通过、6 项外部夹具跳过、1 项既有挂载 invalidMapping 失败；Rust 40 项单元测试通过（本版未改动 Rust 核心，本机 sshd 回归沿用 1.4.1 的通过结果，未重新运行）。不能将整体测试宣称为全部通过。页面、退出确认框、密码自动填充开关在真实窗口中的效果和干净 Mac 安装验收仍由用户执行。

本地开发

scripts/generate-core-bindings.sh
swift test --disable-sandbox
swift run Snake
scripts/package-debug-app.sh

cd Rust/snake_core
cargo test
# 密码由标准输入提供，不写入参数或源码
cargo run --example terminal_smoke -- <host> <port> <username> <known-hosts-path>
cargo run --example sftp_smoke -- <host> <port> <username> <known-hosts-path>

系统要求：Xcode 16.4、Swift 6.1、Rust 1.89+（russh 0.64 的最低要求）和 Python 3。SwiftTerm 固定到 v1.13.0，原因是当前工作站的 Swift 6.1 不兼容其主分支的 Swift 6.2 manifest。

scripts/package-debug-app.sh 会在 .build/debug-app/Snake.app 创建内嵌 Rust 动态库与 Mount Helper、ad-hoc 签名的开发应用，供本机界面测试使用。

构建 DMG

zsh scripts/package-release-dmg.sh 1.4.2

需要 Python 3；脚本使用 Release 优化构建，仅生成当前宿主架构的安装包。产物位于 release/，同名文件存在时拒绝覆盖。应用包含 Rust 动态库、Mount Helper、SwiftTerm Metal 资源及第三方许可证，不依赖工作区中的动态库或渲染资源。

版本号和构建号保存在 Resources/Info.plist，当前为 1.4.2 / 1420。脚本默认临时签名；Developer ID 签名、公证和重新生成校验文件的步骤见 发布流程。本地打包不会自动创建 Git 标签或发布 GitHub Release。

应用启动时自动将旧明文凭据迁移为加密文件；旧会话如果仍只有 Keychain 引用，会在首次成功读取后迁入加密存储。具体设计及手工验收见 凭据加密与查看。

完整产品与安全约束见 开发计划。公开源码不包含内部交互设计原型。

完整第三方归属见 THIRD_PARTY_NOTICES.md。