SAFS

Serverless AI Coding Agent Forwarding for SSH

简体中文 | English

SAFS 让你在 VS Code 中通过 SFTP 浏览、编辑远程文件，并通过 SSH 使用远程终端；服务器无需安装 VS Code Server。启用 Agent 转发后，Copilot、Codex、Claude Code 等 AI Coding Agent 也能在当前远程工作区读写文件、搜索代码和执行命令。

适用场景

• 服务器不能或不方便安装 VS Code Server。
• 内网、VPN、跳板机或禁止端口转发的环境。
• 希望 Agent 操作远程代码，但不想在服务器安装 Agent。
• 需要将远程目录同步到本地，继续使用 Git、语言服务器、构建和调试工具。

快速开始

1. 添加 SSH 配置

1. 安装并启用 SAFS 扩展。
2. 点击左侧活动栏的 SAFS 图标。
3. 点击远程目录视图右上角的 ＋，连续填写主机名、IP 地址、端口和账号凭据。
4. 在已有主机旁点击 ＋，可以继续追加账号。
5. 首次连接时核对并确认服务器主机密钥指纹。

SAFS 会自动扫描 ~/.ssh/config 及其 Include 文件，并导入字面量 Host 条目的主机名、账号、端口和私钥。导入账号自动标记 source: "ssh-config"，统一使用系统 SSH/SFTP，直接按 ssh 别名 连接，由 OpenSSH 从 SSH config 读取账号、端口、私钥、代理、证书和 SSH agent，并使用其主机密钥策略和 known_hosts；导入配置不执行 SAFS 的额外密钥探测，也不使用 safs.hostKeyChangedAction 覆盖策略；通配符 Host 仅作为配置规则使用，不会单独出现在 SAFS 列表中。

直接在 SAFS 中添加或手动写入 ~/.safs/config.json 的账号默认使用内置 ssh2，不根据全局 SSH 配置、SSH agent 或是否填写密码/私钥推断通道。原有 WSL VPN 中继及实际连接失败后的兼容回退规则不变。

配置保存在 ~/.safs/config.json。一般使用界面添加即可；需要手动维护时，可运行 SAFS: 打开配置：

{
  "encrypt_passwords": true,
  "hosts": [
    {
      "name": "开发机",
      "ip": "10.0.0.2",
      "accounts": [
        {
          "user": "alice",
          "port": 22,
          "private_key_path": "~/.ssh/id_ed25519"
        }
      ]
    }
  ]
}

配置按 SAFS 目录树中的主机、账号分组：hosts 是主机，accounts 是账号。历史目录继续保存在 VS Code 扩展的全局状态中，不写入 config.json。账号只需填写 user 和认证信息，内部连接标识由主机名和账号自动生成；界面和 Agent 工作区使用主机名、账号和目录展示。旧版平铺的 hosts / mounts 配置会自动转换，并保留 config.json.legacy.bak 备份。密码、私钥、端口与 VPN 设置保留在对应账号下。

2. 打开并编辑远程目录

在 SAFS 视图中点击连接项旁的 打开远程目录按钮，或运行 SAFS: 打开远程目录。选择目录后，SAFS 会在新窗口中打开 safs:// 虚拟工作区。

之后可以像编辑本地项目一样浏览、打开、保存、新建、重命名和删除文件。SAFS 会在主机名下记住每个连接最近打开的目录；展开连接项即可从历史记录重新打开。

远程终端默认在当前文件所在目录打开；没有活动文件时使用工作区根目录。终端中的文件路径支持 Ctrl+点击（macOS 为 Cmd+点击）直接打开。

首次从连接父节点打开配置的远程家目录时，SAFS 会提示当前平台用于“打开远程目录 / 终端”的两个快捷键，之后不再重复显示。

3. 让 Agent 操作远程工作区

默认使用 CLI 模式，需要本地 Node.js 18+。插件自动安装全局 safs 命令和 Skill；缺少 Node.js 时，弹窗提供安装链接或切换 MCP 模式。

安装 Node.js 后，请完全退出所有 VS Code 窗口，再重新打开（仅重新加载窗口不会更新 PATH）。在终端运行 safs --version 检查安装，然后在 Agent 中输入 /safs-cli，选择远程工作区。

如需 MCP 模式，先将 safs.agentInterface 设置为 mcp： 从 CLI 切换时，当前操作窗口会自动提示输入 Agent 名称并复制安装提示词；取消后可通过下述安装命令重试。 (1) 在 SAFS 视图中点击连接父节点旁的 启用 Agent 转发。也可以主动运行 SAFS: 为我的Agent安装转发功能 进行修复。 (2) 按提示输入 Agent 名称，扩展会复制一段包含本机 Streamable HTTP URL 的英文安装提示词。 (3) 将提示词粘贴给 Agent，由 Agent 自行安装 Streamable HTTP 类型的 safs MCP。 (4) 打开该连接的远程目录。 (5) 重启 Agent 并新建对话，然后通过 /mcp 或 MCP 管理界面确认存在 safs 服务。 (6) 在 Agent里输入：use safs mcp，Agent 会列出工作区并让你明确选择目标。

插件首次启动时会检查 ALL_PROXY、HTTPS_PROXY 和 HTTP_PROXY 等环境变量。检测到代理环境变量且 NO_PROXY 未完整覆盖本机回环地址时，会提示可能影响 Agent 本机转发连接；这不代表代理软件开启了全局模式。可设置 NO_PROXY=localhost,127.0.0.1,::1，然后重启 Agent，让本机转发请求绕过代理。

启用后，Agent可以在当前远程工作区下：

• 列出、读取、搜索、创建和精确修改远程文件；
• 移动、删除、修改权限以及上传或下载文件；
• 在当前远程目录执行命令并分段读取长输出；
• 获取 VS Code 当前打开的远程文件；
• 在多个 SAFS 窗口之间明确选择目标工作区。

查看 Agent 活动

打开 SAFS 活动栏中的 Agent 活动，可以实时查看当前远程窗口实际执行的 MCP/CLI 操作。顶部动画显示执行中、成功或失败状态，下方时间线按最新操作优先排列，并可按 操作类型和状态筛选。连续的读取、列目录和搜索会自动折叠。

面板顶部只显示当前生效的 工作区模式 或 终端模式。 打开远程目录时使用工作区模式；没有打开远程目录、只打开 SAFS 远程终端时使用终端模式。 点击 切换工作区 可在当前窗口选择并打开远程目录；取消选择时保留当前模式。 SAFS 会读取终端实际目录并把它作为 Agent 的 workspaceRoot；命令继承该终端当前的用户 权限和环境变量，下方会显示绑定的终端及目录。

关闭时点击 关闭 Agent 转发。如果 MCP 是通过提示词或 URL 手动安装的，请运行 SAFS: 为我的Agent卸载转发功能。

文件传输与本地同步

在资源管理器中右键文件或目录：

• SAFS：可视化下载：将远程文件或目录下载到本地，支持递归、进度显示和取消。
• SAFS：可视化上传：将本地文件或目录上传到选定连接，无需先打开远程工作区。
• SAFS：同步到本地（远程目录右键）：等价于"先可视化下载，再开启双向同步"。选本地父目录，先整棵下载到 <所选目录>/<远程目录名> 作为首次基线，随后持续进行本地 ↔ 远程双向增量同步；同步完成的目录会写进 SAFS 视图的历史列表，条目上的按钮未同步时是「启动同步」，同步中是「关闭本地同步」。
• SAFS：可视化同步（本地文件夹右键）：等价于"先可视化上传，再开启双向同步"。选远程挂载与远程目录，本地目录整棵上传到 <所选目录>/<本地目录名>，再以刚上传的远程状态为基线开启双向同步（不会把刚上传的内容重复下载回来，远程独有的内容仍会补齐到本地）；同步成功后自动在新窗口打开本地目录，该远程目录同时进入历史列表，同步按钮显示已开启，可随时关闭同步。

大文件断点续传

上传或下载大文件（1 MiB 以上）中断后，再执行一次同一个文件的传输会从断点继续，不会从 0 重来。进度提示会显示已有字节数并标注「续传」。

• 续传不依赖 rsync，也不需要远端安装任何东西：SFTP 协议的读写报文自带字节偏移，SAFS 直接用它做定位读写；只有网关没有 SFTP 子系统、退回 scp 通道时才退化为整传。
• 中断时残片保留在目标旁边（上传是远端同目录的 .<文件名>.safs-part-<哈希>，下载是本地同目录的 <文件名>.safs-part-<哈希>），成功提交后会改名到最终位置。
• 源文件变过就不续传：残片名里编进了源文件的 size+mtime；真正续传前还会分别计算源文件前缀和残片的 SHA-256。元数据或内容任一不一致都会删除残片并自动完整重传，避免把两个版本的字节拼成一个看起来正常的坏文件。
• 小于 1 MiB 的残片不留（续传收益不抵一个垃圾文件），残片超过 7 天会在下一次传输时顺手清掉。

远程 Git 源代码管理

保存 SAFS 文件后会自动刷新更改列表；窗口处于前台时，每 2 秒轻量检查一次远程工作区，以发现终端或其他工具直接修改的文件。切回窗口会立即检查。自动检查不拉取、推送或刷新同步状态，手动刷新仍会更新完整状态。

通过 SAFS 打开远程 Git 仓库根目录 后，VS Code「源代码管理」会出现 Git (SAFS) 仓库。状态、差异、暂存和提交在 SSH 主机上执行，使用远端的 Git 配置和提交身份；推送与拉取都通过本地 Git 中转，使用本地网络和凭据。无需同步工作区到本地或启用 Agent 转发。

常用设置

在 VS Code 设置中搜索 SAFS：

更多高级选项及说明可直接查看 VS Code 的 SAFS 设置页。

工作原理

SAFS 在本地 VS Code 扩展进程中建立 SSH/SFTP 连接，将远程目录映射为 safs:// 虚拟文件系统。文件浏览与编辑通过 SFTP 完成，终端和 Agent 命令通过 SSH 执行，因此服务器无需安装 VS Code Server 或 Agent。

SAFS 提供 MCP 和 CLI 两种 Agent 接口，让 Agent 安全、高效地调用插件的文件操作与远程命令能力。两种接口共用插件管理的连接、工作区边界和安全检查，支持结构化文件操作、批量请求与分段读取输出，减少重复连接和不必要的数据传输。

启用 Agent 转发后，每个远程窗口都会启动仅本机可访问的 MCP 服务。多个窗口共用固定的本地路由入口；每次路由操作都显式携带 workspaceId，精确指向目标窗口，避免将命令发到错误的服务器或工作区。

结构化写入被限制在当前远程工作区。Agent 发起的 SSH 命令若命中高风险规则，默认会被拒绝并记录脱敏审计日志。但 SSH 命令不是沙箱：获准执行后仍拥有登录账号的权限，建议使用非 root、最小权限账号并禁用免密提权。

限制

• 本地命令行和只支持 file:// 的扩展不能直接访问 safs://；需要时请使用双向同步。
• SFTP 没有原生文件变更通知，SAFS 通过轮询检测远程修改。
• 支持Agent转发的 safs MCP/CLI 依赖本地 VS Code 持续运行，并保持对应挂载的转发已启用。
• 服务器没有 SFTP 子系统时会回退到 SCP/exec；基础文件操作仍可用，但性能和兼容性可能不同。
• MCP 工具能限制结构化文件操作，但无法拦截 Agent 自己调用的其他本地工具。

SAFS 与免密 SSH alias 对比

另一种常见的无Agent服务操作远程主机的方式是在 ~/.ssh/config 中配置主机别名和密钥，让 Agent 直接执行 ssh dev '命令'。两者都不需要在远程安装 Agent，但侧重点不同。

选择建议：

• 需要文件树、编辑器、同步，并希望 Agent 明确绑定当前工作区：选择 SAFS。
• 已有成熟的 SSH 密钥和权限体系，只需执行命令或现有脚本：SSH alias 更简单。
• 两者可以并用：日常编辑与 Agent 文件操作走 SAFS，已审查的运维脚本或批量传输走 SSH/rsync。