工作空间文件 API 提供对会话工作空间中任务执行期间生成的文件的访问。Agent 在执行过程中可以生成脚本、分析结果或数据导出等产物——此 API 允许您浏览和下载这些文件。
接口列表
| 接口 | 方法 | 描述 |
|---|
/api/v1/sessions/{sessionId}/files | GET | 列出工作空间中的文件 |
/api/v1/sessions/{sessionId}/files/{path...} | GET | 下载指定文件 |
安全性
Shannon 对所有工作空间文件操作实施严格的路径安全策略：
- 路径穿越保护 — 包含
.. 或绝对路径的请求会被拒绝，返回 400 Bad Request
- 符号链接验证 — 指向工作空间外部的符号链接会被阻止
- 文件大小限制 — 单个文件下载上限为 100 MB
路径穿越尝试（如 ../../etc/passwd）在网关层被阻止。所有路径都相对于会话工作空间根目录进行解析。
列出工作空间文件
列出会话工作空间中的文件和目录。
curl "http://localhost:8080/api/v1/sessions/{sessionId}/files" \
-H "X-API-Key: sk_test_123456"
路径参数
| 参数 | 类型 | 必填 | 描述 |
|---|
sessionId | string | 是 | 会话 ID（UUID 或 external_id） |
查询参数
| 参数 | 类型 | 必填 | 描述 |
|---|
path | string | 否 | 要列出的子目录路径（默认为工作空间根目录 /） |
recursive | boolean | 否 | 若为 true，递归列出所有子目录中的文件 |
子目录查询示例
curl "http://localhost:8080/api/v1/sessions/{sessionId}/files?path=output&recursive=true" \
-H "X-API-Key: sk_test_123456"
{
"session_id": "abc-123",
"path": "/",
"files": [
{
"name": "analysis.py",
"path": "/analysis.py",
"size": 1234,
"is_dir": false,
"modified_at": "2026-03-10T10:00:00Z"
},
{
"name": "output",
"path": "/output",
"size": 0,
"is_dir": true,
"modified_at": "2026-03-10T10:05:00Z"
},
{
"name": "results.csv",
"path": "/output/results.csv",
"size": 56789,
"is_dir": false,
"modified_at": "2026-03-10T10:10:00Z"
}
]
}
响应字段
| 字段 | 类型 | 描述 |
|---|
session_id | string | 会话标识符 |
path | string | 列出的目录路径 |
files | array | 文件条目列表 |
files[].name | string | 文件或目录名称 |
files[].path | string | 相对于工作空间根目录的完整路径 |
files[].size | integer | 文件大小（字节），目录为 0 |
files[].is_dir | boolean | 该条目是否为目录 |
files[].modified_at | string | 最后修改时间戳（ISO 8601） |
下载文件
从会话工作空间下载指定文件。响应的 Content-Type 根据文件内容自动检测。
curl "http://localhost:8080/api/v1/sessions/{sessionId}/files/analysis.py" \
-H "X-API-Key: sk_test_123456" \
-o analysis.py
路径参数
| 参数 | 类型 | 必填 | 描述 |
|---|
sessionId | string | 是 | 会话 ID（UUID 或 external_id） |
path... | string | 是 | 工作空间内的完整文件路径（如 output/results.csv） |
- Content-Type: 自动检测（如
text/plain、application/octet-stream、text/csv）
- Body: 原始文件内容
当 Firecracker 执行器不可用时，网关会回退到从本地文件系统读取文件。此回退对客户端透明，但如果两种来源都不可访问，则可能返回 502。
错误响应
| 状态码 | 描述 |
|---|
| 400 | 无效的会话 ID 或路径穿越尝试（检测到 .. 或绝对路径） |
| 401 | 未授权——缺少或无效的 API key |
| 404 | 会话工作空间未找到，或文件不存在 |
| 413 | 文件超过 100 MB 大小限制 |
| 502 | Firecracker 执行器不可用且本地回退也失败 |
{
"error": "error message here"
}
错误示例：路径穿越
{
"error": "invalid path: traversal not allowed"
}
错误示例：文件过大
{
"error": "file exceeds maximum size limit (100MB)"
}
相关内容
