diff --git a/docs/file_manage_apis.md b/docs/file_manage_apis.md new file mode 100644 index 0000000..6d9f612 --- /dev/null +++ b/docs/file_manage_apis.md @@ -0,0 +1,435 @@ +# 文件管理 API 接口文档 + +**Base URL:** `/api/v1/file-manager` + +--- + +## 1. 列出目录内容 + +**GET** `/api/v1/file-manager/list` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| path | string | query | 否 | 相对路径，空字符串返回根目录（projects/prompt） | +| recursive | bool | query | 否 | 是否递归列出子目录，默认 false | + +```bash +curl -X GET "/api/v1/file-manager/list?path=projects&recursive=false" +``` + +响应示例： +```json +{ + "success": true, + "path": "projects", + "items": [ + { + "name": "report.pdf", + "path": "projects/report.pdf", + "type": "file", + "size": 102400, + "modified": 1700000000.0, + "created": 1699000000.0 + } + ], + "total": 1 +} +``` + +--- + +## 2. 上传文件 + +**POST** `/api/v1/file-manager/upload` + +请求方式：表单数据上传（multipart/form-data） + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| file | file | form | 是 | 上传的文件 | +| path | string | form | 否 | 目标目录路径，默认 `projects` | + +```bash +curl -X POST "/api/v1/file-manager/upload" \ + -F "file=@document.pdf" \ + -F "path=projects/dataset" +``` + +响应示例： +```json +{ + "success": true, + "message": "文件上传成功", + "filename": "document.pdf", + "original_filename": "document.pdf", + "path": "projects/dataset/document.pdf", + "size": 102400 +} +``` + +> 注：文件名中的空格会自动替换为下划线。 + +--- + +## 3. 下载文件 + +**GET** `/api/v1/file-manager/download/{file_path}` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| file_path | string | path | 是 | 文件相对路径 | + +```bash +curl -X GET "/api/v1/file-manager/download/projects/report.pdf" -o report.pdf +``` + +响应：文件二进制流，`Content-Type` 根据文件类型自动推断。 + +--- + +## 4. 删除文件或目录 + +**DELETE** `/api/v1/file-manager/delete` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| path | string | query | 是 | 要删除的路径 | + +```bash +curl -X DELETE "/api/v1/file-manager/delete?path=projects/report.pdf" +``` + +响应示例： +```json +{ + "success": true, + "message": "文件删除成功", + "path": "projects/report.pdf" +} +``` + +--- + +## 5. 创建文件夹 + +**POST** `/api/v1/file-manager/create-folder` + +请求方式：JSON + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| path | string | body | 否 | 父目录路径，默认 `projects` | +| name | string | body | 是 | 文件夹名称 | + +```bash +curl -X POST "/api/v1/file-manager/create-folder" \ + -H "Content-Type: application/json" \ + -d '{"path": "projects", "name": "new-folder"}' +``` + +响应示例： +```json +{ + "success": true, + "message": "文件夹创建成功", + "path": "projects/new-folder" +} +``` + +--- + +## 6. 重命名文件或文件夹 + +**POST** `/api/v1/file-manager/rename` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| old_path | string | query | 是 | 原路径 | +| new_name | string | query | 是 | 新名称 | + +```bash +curl -X POST "/api/v1/file-manager/rename?old_path=projects/old-name.pdf&new_name=new-name.pdf" +``` + +响应示例： +```json +{ + "success": true, + "message": "重命名成功", + "old_path": "projects/old-name.pdf", + "new_path": "projects/new-name.pdf" +} +``` + +--- + +## 7. 移动文件或文件夹 + +**POST** `/api/v1/file-manager/move` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| source_path | string | query | 是 | 源路径 | +| target_path | string | query | 是 | 目标路径 | + +```bash +curl -X POST "/api/v1/file-manager/move?source_path=projects/a.pdf&target_path=projects/sub/a.pdf" +``` + +响应示例： +```json +{ + "success": true, + "message": "移动成功", + "source_path": "projects/a.pdf", + "target_path": "projects/sub/a.pdf" +} +``` + +--- + +## 8. 复制文件或文件夹 + +**POST** `/api/v1/file-manager/copy` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| source_path | string | query | 是 | 源路径 | +| target_path | string | query | 是 | 目标路径 | + +```bash +curl -X POST "/api/v1/file-manager/copy?source_path=projects/a.pdf&target_path=projects/a-copy.pdf" +``` + +响应示例： +```json +{ + "success": true, + "message": "复制成功", + "source_path": "projects/a.pdf", + "target_path": "projects/a-copy.pdf" +} +``` + +--- + +## 9. 搜索文件 + +**GET** `/api/v1/file-manager/search` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| query | string | query | 是 | 搜索关键词（匹配文件名） | +| path | string | query | 否 | 搜索路径，为空则搜索所有支持目录 | +| file_type | string | query | 否 | 文件类型过滤（如 `.pdf`） | + +```bash +curl -X GET "/api/v1/file-manager/search?query=report&path=projects&file_type=.pdf" +``` + +响应示例： +```json +{ + "success": true, + "query": "report", + "path": "projects", + "results": [ + { + "name": "report.pdf", + "path": "projects/report.pdf", + "type": "file" + } + ], + "total": 1 +} +``` + +--- + +## 10. 读取文件内容 + +**GET** `/api/v1/file-manager/read` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| path | string | query | 是 | 文件相对路径 | + +```bash +curl -X GET "/api/v1/file-manager/read?path=projects/config.json" +``` + +响应示例： +```json +{ + "success": true, + "content": "{\"key\": \"value\"}", + "path": "projects/config.json", + "size": 16, + "modified": 1700000000.0, + "encoding": "utf-8", + "mime_type": "application/json" +} +``` + +> 限制：最大 10MB。自动尝试 utf-8 / gbk / gb2312 / latin-1 编码。 + +--- + +## 11. 保存文件内容 + +**POST** `/api/v1/file-manager/save` + +请求方式：JSON + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| path | string | body | 是 | 文件相对路径 | +| content | string | body | 是 | 文件内容 | + +```bash +curl -X POST "/api/v1/file-manager/save" \ + -H "Content-Type: application/json" \ + -d '{"path": "projects/config.json", "content": "{\"key\": \"new-value\"}"}' +``` + +响应示例： +```json +{ + "success": true, + "message": "文件保存成功", + "path": "projects/config.json", + "size": 20, + "modified": 1700000000.0, + "encoding": "utf-8" +} +``` + +> 限制：最大 5MB。保存前自动创建备份，写入失败时自动回滚。 + +--- + +## 12. 获取文件/文件夹详细信息 + +**GET** `/api/v1/file-manager/info/{file_path}` + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| file_path | string | path | 是 | 文件或文件夹路径 | + +```bash +curl -X GET "/api/v1/file-manager/info/projects/report.pdf" +``` + +响应示例： +```json +{ + "success": true, + "info": { + "name": "report.pdf", + "path": "projects/report.pdf", + "type": "file", + "size": 102400, + "modified": 1700000000.0, + "created": 1699000000.0, + "permissions": "644", + "mime_type": "application/pdf", + "preview": "文件前1000字符预览..." + } +} +``` + +> 小于 1MB 的文本文件会包含 `preview` 字段。 + +--- + +## 13. 下载文件夹为 ZIP + +**POST** `/api/v1/file-manager/download-folder-zip` + +请求方式：JSON + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| path | string | body | 是 | 文件夹路径 | + +```bash +curl -X POST "/api/v1/file-manager/download-folder-zip" \ + -H "Content-Type: application/json" \ + -d '{"path": "projects/dataset"}' -o dataset.zip +``` + +响应：ZIP 文件二进制流（`application/zip`）。 + +> 限制：最大 500MB，最多 10000 个文件。 + +--- + +## 14. 批量下载为 ZIP + +**POST** `/api/v1/file-manager/download-multiple-zip` + +请求方式：JSON + +| 参数 | 类型 | 位置 | 必填 | 说明 | +|------|------|------|------|------| +| paths | string[] | body | 是 | 文件/文件夹路径数组 | +| filename | string | body | 否 | ZIP 文件名，默认 `batch_download.zip` | + +```bash +curl -X POST "/api/v1/file-manager/download-multiple-zip" \ + -H "Content-Type: application/json" \ + -d '{"paths": ["projects/a.pdf", "projects/sub"], "filename": "export.zip"}' \ + -o export.zip +``` + +响应：ZIP 文件二进制流（`application/zip`）。 + +> 限制：最大 500MB，最多 10000 个文件。 + +--- + +## 15. 批量操作 + +**POST** `/api/v1/file-manager/batch-operation` + +请求方式：JSON（操作数组） + +支持操作类型：`delete` / `move` / `copy` + +```bash +curl -X POST "/api/v1/file-manager/batch-operation" \ + -H "Content-Type: application/json" \ + -d '[ + {"type": "delete", "path": "projects/old.pdf"}, + {"type": "move", "source_path": "projects/a.pdf", "target_path": "projects/archive/a.pdf"}, + {"type": "copy", "source_path": "projects/b.pdf", "target_path": "projects/backup/b.pdf"} + ]' +``` + +响应示例： +```json +{ + "success": true, + "results": [ + {"type": "delete", "success": true, "message": "删除成功"}, + {"type": "move", "success": true, "message": "移动成功"}, + {"type": "copy", "success": true, "message": "复制成功"} + ], + "total": 3, + "successful": 3 +} +``` + +--- + +## 通用说明 + +- **路径约束**：所有路径必须以 `projects` 或 `prompt` 开头，否则返回 400 +- **安全机制**：路径经过规范化处理，防止目录遍历攻击 +- **隐藏文件**：以 `.` 开头的文件/目录在列出和搜索时自动跳过 +- **错误响应格式**： +```json +{ + "detail": "错误描述信息" +} +```