Files API

安全列出和读取 Runtime 工作目录中的文件。

​

Files API

Files API 浏览 Runtime 当前工作目录（cwd）中的文件，不是任意主机文件访问接口。它面向运维、调试与控制台展示场景，让外部客户端通过 HTTP 浏览 Agent 的工作区，无需 SSH。API 为只读，不提供上传、写入或删除能力。

任何持有有效 API key 的调用方都可以读取 cwd 下的全部内容，包括 agents.yaml、.env、MCP server 凭证。生产部署前必须配置 ZERONE_AGENT_HTTP_API_KEY，并以最小文件权限运行容器，避免把凭据挂载进 Agent 可浏览目录。

​

端点一览

方法	路径	说明
GET	/v1/files	列出 cwd 下的文件与目录；支持 path、recursive、depth
GET	/v1/files/content	单文件流式下载（支持 Range）
HEAD	/v1/files/content	单文件元数据（仅响应头，无 body）

所有端点遵守相同的约束：

• 受 /v1/* 的 x-api-key 鉴权保护（如已配置）。
• 路径参数 path 是相对 cwd 的子路径，禁止 .. 逃逸、绝对路径和 null byte。
• cwd 内的 symlink 若解析后逃出 cwd，会被拒绝。

​

GET /v1/files

​

Query 参数

参数	类型	默认值	说明
path	string	""（cwd 根）	相对 cwd 的子目录路径
recursive	"true" | "false"	false	是否递归整棵子树
depth	number	不限	限制递归深度（仅 recursive=true 时生效）；depth=N 表示展开 N 层子目录

​

响应（200）

{
  "path": "",
  "entries": [
    {
      "name": "agents.yaml",
      "type": "file",
      "size": 482,
      "mtime": "2026-07-07T10:00:00.000Z",
      "mime": "text/yaml"
    },
    {
      "name": "src",
      "type": "directory",
      "size": 0,
      "mtime": "2026-07-07T09:30:00.000Z"
    },
    {
      "name": "outputs-link",
      "type": "symlink",
      "size": 0,
      "mtime": "2026-07-07T09:30:00.000Z",
      "target": "outputs"
    }
  ]
}

​

Entry 字段

字段	类型	必返回	说明
name	string	是	顶层模式为文件名；递归模式为相对 cwd 的路径（用 / 分隔）
type	"file" | "directory" | "symlink" | "other"	是	other 用于 FIFO/socket 等非常规类型
size	number	是	字节数；目录与 broken symlink 为 0
mtime	string (ISO 8601)	是	最后修改时间
mime	string	仅 file	由扩展名推断
target	string	仅 symlink 且 target 解析后仍在 cwd 内	链接目标的相对路径

entries 数组排序稳定：directory 优先，再按 name 字典序（区分大小写）。

​

错误响应

状态码	触发条件	响应体
400	路径非法（绝对路径、.. 逃逸、null byte）	{ "error": "Invalid path" }
400	path 指向文件而非目录	{ "error": "Not a directory" }
400	depth 不是非负整数	{ "error": "Invalid depth parameter" }
404	path 不存在	{ "error": "Directory not found" }

​

示例

# 顶层
curl -H "x-api-key: your-runtime-api-key" http://localhost:3000/v1/files

# 子目录
curl -H "x-api-key: your-runtime-api-key" "http://localhost:3000/v1/files?path=src"

# 递归整棵树
curl -H "x-api-key: your-runtime-api-key" "http://localhost:3000/v1/files?recursive=true"

# 限制深度（顶层 + 1 层子目录）
curl -H "x-api-key: your-runtime-api-key" "http://localhost:3000/v1/files?recursive=true&depth=1"

​

GET /v1/files/content

单文件流式下载，支持 HTTP Range。必填 query 参数 path 为相对 cwd 的文件路径。

成功响应（200）的响应头：

Content-Type: <由扩展名推断>
Content-Disposition: attachment; filename*=UTF-8''<percent-encoded>
Content-Length: <文件字节数>
Accept-Ranges: bytes
Last-Modified: <RFC 1123 格式>

响应不设大小上限——任何大小的文件都会被流式返回。

​

Range 请求

支持单段 Range，返回 206 Partial Content：

curl -H "x-api-key: your-runtime-api-key" \
     -H "Range: bytes=0-99" \
     "http://localhost:3000/v1/files/content?path=logs/app.log"

HTTP/1.1 206 Partial Content
Content-Type: text/plain
Content-Length: 100
Content-Range: bytes 0-99/48200
Accept-Ranges: bytes

支持的 Range 格式：

格式	含义
bytes=0-99	第 0 到 99 字节
bytes=100-	第 100 字节到文件末尾
bytes=-100	最后 100 字节

多段 Range（如 bytes=0-99,200-299）回退为 200 全文件返回。

​

错误响应

状态码	触发条件	响应体
400	路径非法、path 指向目录、symlink 逃出 cwd	{ "error": "Invalid path" } 或 { "error": "Not a file" }
404	文件不存在	{ "error": "File not found" }
416	Range 不可满足（start ≥ size）	{ "error": "Range not satisfiable" }，并携带 Content-Range: bytes */<size>

​

示例

# 全文下载
curl -H "x-api-key: your-runtime-api-key" \
     "http://localhost:3000/v1/files/content?path=outputs/report.json" \
     -o report.json

# Range 下载（前 1KB）
curl -H "x-api-key: your-runtime-api-key" \
     -H "Range: bytes=0-1023" \
     "http://localhost:3000/v1/files/content?path=logs/app.log" \
     -o partial.log

​

HEAD /v1/files/content

与 GET 相同的 query 参数和响应头，但没有响应体。用于下载前预查 Content-Length / Content-Type，或验证文件是否存在（404 与 200 区分）。

curl -I -H "x-api-key: your-runtime-api-key" \
     "http://localhost:3000/v1/files/content?path=outputs/report.json"

HTTP/1.1 200 OK
Content-Type: application/json
Content-Disposition: attachment; filename*=UTF-8''report.json
Content-Length: 482
Accept-Ranges: bytes
Last-Modified: Tue, 07 Jul 2026 10:00:00 GMT

​

路径安全

所有 path 参数都经过统一的 safeResolve 检查：

1. 拒绝 null byte：path 含 \0 返回 400。
2. 拒绝绝对路径：如 /etc/passwd 返回 400。
3. 拒绝路径遍历：如 ../、sub/../../ 返回 400。
4. 拒绝 symlink 逃逸：cwd 内的符号链接若解析后指向 cwd 外，下载时返回 400；列表时省略 target 字段。

这些是底层一致性约束，与是否配置鉴权无关。

​

范围边界

Files API 不提供：

• 文件上传、写入、删除（只读）
• 文件搜索或 glob
• 目录打包（tar/zip）
• 文件变更通知
• 内容脱敏
• 多根目录（cwd 是唯一根）

​

相关

• Agent 详情 API：同类只读接口