114 lines
2.7 KiB
Markdown
114 lines
2.7 KiB
Markdown
# 文件 API（工作区内：上传仅限 user_upload，读取可遍历 project）
|
||
|
||
文件读写是**工作区级**的：上传仅允许写入该 workspace 的 `project/user_upload/`；列目录/下载则可访问整个 `project/`（对应容器内 `/workspace`），兼容传入 `user_upload/` 路径。
|
||
|
||
鉴权：所有接口均需要 `Authorization: Bearer <TOKEN>`
|
||
|
||
---
|
||
|
||
## 1) 上传文件
|
||
|
||
### POST `/api/v1/workspaces/{workspace_id}/files/upload`
|
||
|
||
说明：
|
||
|
||
- 仅可上传到 workspace 的 `user_upload/` 目录（及其子目录）；路径越界将被拒绝。
|
||
|
||
请求（multipart/form-data）：
|
||
|
||
- Headers：
|
||
- `Authorization: Bearer <TOKEN>`
|
||
- Form：
|
||
- `file`：文件本体（必填）
|
||
- `filename`：可选，自定义文件名（服务端会清洗）
|
||
- `dir`：可选，`user_upload` 下子目录（如 `inputs` / `a/b`）
|
||
|
||
成功响应（200）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"workspace_id": "ws1",
|
||
"path": "inputs/hello.txt",
|
||
"filename": "hello.txt",
|
||
"size": 16,
|
||
"sha256": "0f5bd6..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2) 列出目录内容
|
||
|
||
### GET `/api/v1/workspaces/{workspace_id}/files?path=<dir>`
|
||
|
||
说明：
|
||
|
||
- `path` 是 `project/` 下的相对路径；不传或传空则表示 `project` 根目录。兼容传入 `user_upload/...`。
|
||
|
||
成功响应（200）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"workspace_id": "ws1",
|
||
"base": "inputs",
|
||
"items": [
|
||
{ "name": "hello.txt", "is_dir": false, "size": 16, "modified_at": 1769182550.59, "path": "inputs/hello.txt" },
|
||
{ "name": "images", "is_dir": true, "size": 64, "modified_at": 1769182552.01, "path": "inputs/images" }
|
||
]
|
||
}
|
||
```
|
||
|
||
常见错误：
|
||
|
||
- `404`：路径不存在
|
||
- `400`：path 指向文件（不是目录）或非法路径
|
||
|
||
---
|
||
|
||
## 3) 下载文件或目录
|
||
|
||
### GET `/api/v1/workspaces/{workspace_id}/files/download?path=<file_or_dir>`
|
||
|
||
说明：
|
||
|
||
- `path` 是 `project/` 下相对路径（兼容传入 `user_upload/...`）
|
||
- 若 `path` 是文件：直接下载该文件
|
||
- 若 `path` 是目录：服务端打包为 zip 返回
|
||
|
||
成功响应：
|
||
|
||
- 文件：`Content-Type: application/octet-stream`
|
||
- 目录：`Content-Type: application/zip`
|
||
|
||
---
|
||
|
||
## curl 示例
|
||
|
||
上传到 `ws1/user_upload/inputs/hello.txt`：
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
-F "file=@hello.txt" \
|
||
-F "dir=inputs" \
|
||
https://agent.cyjai.com/api/v1/workspaces/ws1/files/upload
|
||
```
|
||
|
||
列出 `ws1/user_upload/inputs`：
|
||
|
||
```bash
|
||
curl -sS \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
"https://agent.cyjai.com/api/v1/workspaces/ws1/files?path=inputs"
|
||
```
|
||
|
||
下载目录 `ws1/user_upload/inputs`：
|
||
|
||
```bash
|
||
curl -L -o inputs.zip \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
"https://agent.cyjai.com/api/v1/workspaces/ws1/files/download?path=inputs"
|
||
```
|