# 文件 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"
```