文件传输

终端文件上传¶

Control UI 可以将文件拖入已配对的开放节点终端。原生节点宿主会公布仅限管理员的 terminal.upload 命令；当配对升级首次出现时，请批准该升级。每个文件限制为 16 MiB，先暂存在该节点上的私有临时目录中，然后以带 shell 引号的路径形式返回给终端，而不会执行该文件。

路径插入支持 PowerShell、cmd.exe 以及可识别的 POSIX shell（sh、Bash、Dash、Ash、Ksh、Zsh 和 Fish），包括 Windows 上的 Git Bash。其他 shell 覆写会被拒绝，因为无法安全推断其引号规则；如需原生 WSL 路径，请在 WSL 中运行节点宿主。包含 % 或 ! 的 cmd.exe 路径也会被拒绝，因为该 shell 即使在双引号内也会展开这些字符。

智能体文件传输¶

File Transfer 插件 提供可独立选择的目录列表、获取和写入工具。允许其中一个工具并不会使其他工具可用；节点命令和路径策略仍然适用。

网关工作区文件¶

File Transfer 插件可以将 Gateway 工作区文件调用方连接到已配对的节点。配置智能体 ID、精确的节点 ID 以及该节点的绝对 POSIX 工作区路径：

json5 validate=false // plugins.entries.file-transfer.config { policyVersion: 2, workspaces: { main: { nodeId: "<paired-node-id>", remoteRoot: "/workspace" }, }, nodes: { "<paired-node-id>": { ask: "off", allowReadPaths: ["/workspace/AGENTS.md"], allowWritePaths: ["/workspace/AGENTS.md"], followSymlinks: false, }, }, }

配置此映射本身并不授予访问权限。请分别授权所需的节点命令和文件路径；该示例仅授予 AGENTS.md。Gateway 调用方保留自己的文档允许列表。请使用规范的工作区根目录。文档读取和写入会拒绝符号链接。当节点策略允许时，bootstrap 读取可以跟随该根目录内的目录别名；最终文件的符号链接仍然会被拒绝。当配置的节点不可用或其工作区服务停止时，不会提供本地文件回退。共享同一个 Gateway 工作区的智能体必须使用相同的节点和远程根目录；完全相同的映射共享同一个绑定，而冲突的映射会导致启动失败。

file.stat 不会新增模型工具。在现有读路径策略下，它接受常规文件和目录，而无需获取内容或列出父目录。对于 bootstrap 读取，file.fetch.rootPath 将父别名解析限制在规范工作区根目录内；它不会授予超出节点策略的访问权限。一元读取和写入保留 16 MiB 传输限制；目录读取会消耗现有的 dir.list 分页。file.write.expectedSha256 验证的是提交的字节，而不是之前的文件版本。所有者文档冲突检查仍保留在 Gateway 中。

此映射仅涵盖工作区文件。内存搜索、技能管理和附件暂存需要各自对应的工作区能力；仅靠此映射无法实现完整的存储拆分，也无法启动智能体运行框架。

服务的二进制传输¶

插件服务可以使用现有节点通道来传输文件字节：

• 当双方宿主都支持时，file.fetch 接受二进制传输，并受调用方的字节限制和节点策略约束。现有的一元调用保持其当前行为。
• file.create 通过该通道接收字节，并发布完整文件，且不会替换现有文件。它在发布前检查已受理的大小和 SHA-256 摘要。

这两个命令都保留节点配对、文件路径授权和审批检查。这些传输命令不会自动暂存任务附件；该集成由工作区适配器提供。

已传输的文件¶

每次成功的文件获取都会将字节保存到 Gateway 的文件传输媒体存储中，并返回 localPath 和 mediaId，包括内联文本和图像。获取的文件在保存的副本和转发的附件中保留经过清洗的文件名主干。检测到的媒体类型决定扩展名：被分类为纯文本的 train.py 会变成 train.txt。保存的副本包含唯一后缀，以便区分重复获取的结果。

当节点写入可用时，将该 mediaId 作为 sourceMediaId 传入，以复用已保存的字节。sourceMediaId 不接受本地路径或来自其他媒体存储的 ID。对于内联字节，请改用 contentBase64。

目录工具最多返回 8192 个 UTF-8 字节的模型可见文本，包括外部内容包装器。dir_list 显示完整名称、目录标志和大小。要继续受文本限制的列表，请将文本的 nextPageToken 作为 pageToken，并搭配相同的节点和路径传递；它会在最后显示的条目之后立即继续。默认请求仍为 200 个条目，上限为 5000。完整返回的元数据和原始页面令牌保留在结构化详细信息中。

dir_fetch 保存整个目录树，并显示其本地 rootDir、总 fileCount、以及完整 relPath 和大小记录的受限前缀。将 rootDir 与列出的 relPath 组合使用，以进行本地后续操作。被省略的文件仍保存在该根目录下，可以使用可用的本地文件或目录能力进行检查；获取操作没有分页。完整清单和附件元数据保留在结构化详细信息中。如果路径超出文本预算，或会被安全净化重写，文本会报告省略，而不是显示部分或更改后的路径。无法显示其第一个条目的列表会明确报告分页无法继续。

目录获取策略会检查源树中的后代，然后检查由用于提取的同一有界解析器和策略规划器所接受的归档成员标识。它不使用人类可读的 tar 列表：被接受的 Unicode 和换行名称会保留其确切拼写，由生产者添加的 AppleDouble 文件会被检查而不是被隐藏。即使归档省略目录头，也会检查父路径。5000 个后代的上限包括这些隐式目录，共享父目录只计算一次。被拒绝的路径会导致整个传输被拒绝。规范源路径/设备/inode 绑定、字节计数和 SHA-256 校验、链接/遍历/冲突检查以及提取限制仍然适用。格式错误的归档头和目标平台文件名限制仍会拒绝；文件名不会被截断或修复以使归档通过。