文件访问 | WingGate

WingGate 的文件访问从不脱离授权链。每次操作都绑定到某个会话，或 MCP 工具调用的授权链（每次 tools/call 背后的项目 grant 与 MCP 配置）。在 SSH / host 资产上，连接配置决定操作以哪个远端 OS 用户身份运行，WingGate 不维护自己的路径 ACL——目标主机对该用户的 OS 权限才是权威；在 SMB / WebDAV / S3 文件后端上，目标服务器自己的共享与对象权限就是权威。

文件访问的入口

Web 终端文件面板——浏览并编辑活动终端会话所在资产上的文件。直接 shell 会话中，面板跟随 shell 的工作目录。
MCP file 工具——面向 AI Agent 的 read / ls / fetch / upload / write / edit / mkdir / rename / delete / find / grep（对齐 Pi Hypa，MCP 名无 hypa_ 前缀），作用域限定在项目的 MCP 配置内。凭据与客户端配置见配置 MCP 访问。这些工具同时服务 SSH / host 资产与 SMB / WebDAV / S3 文件后端；后者没有 Web 终端入口，find / grep 也不在其中。

零安装 SFTP 操作（SSH / host 资产）

在 SSH / host 资产上，基础文件操作——列出、读取、写入、编辑、mkdir、重命名、删除——固定走零安装 SFTP provider。它们从不依赖 Runner，也从不触发其安装，只要连接配置有效即可工作：

这些操作不需要在资产上安装任何额外组件。
若 SFTP 不可用，操作返回 unavailable；不会回退到其它机制。

无进程文件后端（SMB / WebDAV / S3）

SMB 共享、WebDAV 站点与 S3 兼容对象存储是并列的资产类型：wing-connector 直接讲目标协议，文件操作不经过 SFTP、不需要 Runner，也没有会话或 Web 终端。

同一套文件工具：这九个工具（ls、read、fetch、upload、write、edit、mkdir、rename、delete）与 SSH 资产共用同一份契约、授权链、审计与错误语义。find / grep 不在这类资产上提供——它们依赖装在资产上的 Runner，而这类资产没有可安装的目标主机。
目标与凭据写在资产里：这三类资产没有「连接配置」这一层，目标（共享名 / 站点地址 / 端点与桶）与凭据引用都属于资产本身；凭据仍是只写不读的独立记录。
身份锚按协议不同：WebDAV 强制 HTTPS，并在启用工具前确认服务端 SPKI 指纹；SMB 没有可固定的证书，身份由 SMB3 的强制签名（把会话密钥绑到口令）与强制加密保证，仅接受 NTLMv2，没有降级选项；S3 端点只由 HTTP 客户端信任的公网根校验，请求方向另有逐请求 SigV4，没有需要操作员确认的身份事实。
对象语义不是 POSIX：S3 没有目录，空目录是零字节 marker 对象；rename 只支持单对象；delete 从不级联；append 只有 SMB 支持。不要按 SMB 的行为推断 WebDAV 与 S3。

Runner-only 搜索

类型化搜索是另一种能力，需要按需 Runner：

file.find 按 glob 匹配路径；file.grep 默认按字面子串搜索文件内容，可选用 ignoreCase（忽略大小写）与 regex（Rust 正则）参数。
遍历遵循 ripgrep 式作用域：隐藏条目（点开头的文件/目录，如 .git）与 .gitignore/.ignore 规则会剪枝整个子树——被忽略目录中的匹配不会出现。需要搜索这些内容时，请在 gitignore 之外单独指定路径。
首次使用 Runner-only 操作会在服务该资产的连接器上创建专用安装 Job。调用方收到 runner_installing；控制台展示 Job 进度，Runner 二进制验证通过后自动重试原操作。
搜索有硬预算限制——目录条目数、读取文件数、扫描字节数、单行长度与递归深度。预算耗尽时返回 budget-exhausted 错误，绝不伪造部分成功。
结果不是文件系统快照：页间变更可能遗漏、新增或改变匹配项。需要一致视图的客户端必须从头重新搜索。

读取与编辑语义

文件读取按字节：offset、limit 与 nextOffset 是字节偏移，不是行号。读取不是快照——页间文件哈希变化时必须从头重读。
file.edit 基于原文一次性应用一组不重叠的替换；每个 oldText 必须恰好匹配一次。
写入与编辑返回变更后完整文件的哈希，调用方可核验实际落盘内容。

边界

没有无上限的批量传输：fetch/upload 以字节上限（max_file_bytes，默认 10 MiB）移动完整小文件，其余操作仍是有界、分页的访问。超过上限返回 file_too_large，绝不截断。
文件权限在 SSH / host 资产上只由连接配置的远端 OS 用户决定：以 root 认证、或免密 sudo 的配置代表完整主机控制权，授权时必须显式审批。文件后端上没有这一层，目标服务器自己的共享与对象权限说了算。
每次文件操作都记录在组织审计中（session.file_operation），记路径、字节数与结果，不记文件正文或搜索词；文件活动与其它会话一样可追溯。

排障

SSH / host 资产上读取或列出报 SFTP 错误——确认连接配置的凭据仍有效、资产的连接器在线。
find/grep 返回 runner_installing——等待安装 Job；Runner 验证通过后操作自动重试。若 Job 失败，与 WingGate 服务运维方检查 Runner artifact 配置。
search_budget_exhausted——查询超出扫描预算。收窄路径或模式后重试；这是永久性错误，不是部分结果。
资产上权限不足——远端 OS 用户无法读写该路径。这由目标主机决定，而非 WingGate；调整连接配置的用户或主机权限。
WebDAV 报证书未确认——先对该资产执行证书探测并确认它报告的 SPKI 指纹；确认前该资产的工具组不启用。
SMB / WebDAV / S3 报不可达——从 wing-connector 所在的网络验证目标地址与端口，而不是从你的笔记本。
文件后端上 find / grep 被拒——这两个工具依赖装在资产上的 Runner，在这类资产上不提供；改用 ls 与 read。