zhuchaowe/qwen_agent

Fork 0

朱潮 1321471202 add file_manage doc

2026-04-03 19:57:34 +08:00

9.3 KiB

Raw Blame History

文件管理 API 接口文档

Base URL: /api/v1/file-manager

1. 列出目录内容

GET /api/v1/file-manager/list

参数	类型	位置	必填	说明
path	string	query	否	相对路径，空字符串返回根目录（projects/prompt）
recursive	bool	query	否	是否递归列出子目录，默认 false

curl -X GET "/api/v1/file-manager/list?path=projects&recursive=false"

响应示例：

{
  "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`

curl -X POST "/api/v1/file-manager/upload" \
  -F "file=@document.pdf" \
  -F "path=projects/dataset"

响应示例：

{
  "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	是	文件相对路径

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	是	要删除的路径

curl -X DELETE "/api/v1/file-manager/delete?path=projects/report.pdf"

响应示例：

{
  "success": true,
  "message": "文件删除成功",
  "path": "projects/report.pdf"
}

5. 创建文件夹

POST /api/v1/file-manager/create-folder

请求方式：JSON

参数	类型	位置	必填	说明
path	string	body	否	父目录路径，默认 `projects`
name	string	body	是	文件夹名称

curl -X POST "/api/v1/file-manager/create-folder" \
  -H "Content-Type: application/json" \
  -d '{"path": "projects", "name": "new-folder"}'

响应示例：

{
  "success": true,
  "message": "文件夹创建成功",
  "path": "projects/new-folder"
}

6. 重命名文件或文件夹

POST /api/v1/file-manager/rename

参数	类型	位置	必填	说明
old_path	string	query	是	原路径
new_name	string	query	是	新名称

curl -X POST "/api/v1/file-manager/rename?old_path=projects/old-name.pdf&new_name=new-name.pdf"

响应示例：

{
  "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	是	目标路径

curl -X POST "/api/v1/file-manager/move?source_path=projects/a.pdf&target_path=projects/sub/a.pdf"

响应示例：

{
  "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	是	目标路径

curl -X POST "/api/v1/file-manager/copy?source_path=projects/a.pdf&target_path=projects/a-copy.pdf"

响应示例：

{
  "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`）

curl -X GET "/api/v1/file-manager/search?query=report&path=projects&file_type=.pdf"

响应示例：

{
  "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	是	文件相对路径

curl -X GET "/api/v1/file-manager/read?path=projects/config.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	是	文件内容

curl -X POST "/api/v1/file-manager/save" \
  -H "Content-Type: application/json" \
  -d '{"path": "projects/config.json", "content": "{\"key\": \"new-value\"}"}'

响应示例：

{
  "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	是	文件或文件夹路径

curl -X GET "/api/v1/file-manager/info/projects/report.pdf"

响应示例：

{
  "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	是	文件夹路径

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`

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

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"}
  ]'

响应示例：

{
  "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
安全机制：路径经过规范化处理，防止目录遍历攻击
隐藏文件：以 . 开头的文件/目录在列出和搜索时自动跳过
错误响应格式：

{
  "detail": "错误描述信息"
}

9.3 KiB Raw Blame History Unescape Escape

文件管理 API 接口文档

1. 列出目录内容

2. 上传文件

3. 下载文件

4. 删除文件或目录

5. 创建文件夹

6. 重命名文件或文件夹

7. 移动文件或文件夹

8. 复制文件或文件夹

9. 搜索文件

10. 读取文件内容

11. 保存文件内容

12. 获取文件/文件夹详细信息

13. 下载文件夹为 ZIP

14. 批量下载为 ZIP

15. 批量操作

通用说明

9.3 KiB

Raw Blame History