agent-Specialization/api_doc/files.md

文件接口（上传 / 列目录 / 下载）

API v1 只提供最小化的文件能力，用于把外部输入文件放入工作区，并下载产物。

核心限制：

• 上传只能落在 project/user_upload/ 目录及其子目录；
• 列目录/下载也只允许访问 user_upload 内部路径（路径穿越会被拒绝）。

目录结构见 auth.md。

1) 上传文件

POST /api/v1/files/upload

请求

• Headers：Authorization: Bearer <TOKEN>
• Content-Type：multipart/form-data
• Form 字段：
  • file：必填，上传的文件对象
  • filename：可选，覆盖原文件名（会做安全清洗）
  • dir：可选，user_upload 下的子目录（例如 docs/）；不传则落在 user_upload/ 根目录

如果你希望“完全不允许指定目录”，客户端请不要传 dir，统一上传到根目录即可。

响应

成功（200）：

{
  "success": true,
  "path": "docs/spec.pdf",
  "filename": "spec.pdf",
  "size": 12345,
  "sha256": "..."
}

字段说明：

• path：相对 user_upload 的路径（用于 list/download）
• sha256：服务端计算的文件哈希（便于客户端校验/去重）

可能错误：

• 400：缺少 file / 文件名非法 / 目录非法
• 401：缺少或无效 token
• 503：系统未初始化
• 500：保存失败（例如写入异常、扫描/隔离异常等）

curl 示例

上传到根目录：

curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@./hello.txt" \
  http://localhost:8091/api/v1/files/upload

上传到子目录：

curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  -F "dir=inputs" \
  -F "file=@./hello.txt" \
  http://localhost:8091/api/v1/files/upload

2) 列出目录内容

GET /api/v1/files?path=<dir>

请求

• Headers：Authorization: Bearer <TOKEN>
• Query：
  • path：可选，相对 user_upload 的目录路径；不传表示根目录

响应

成功（200）：

{
  "success": true,
  "base": "inputs",
  "items": [
    {
      "name": "hello.txt",
      "is_dir": false,
      "size": 16,
      "modified_at": 1769182550.594278,
      "path": "inputs/hello.txt"
    }
  ]
}

字段说明：

• base：你请求的目录（相对 user_upload），根目录时为 .
• items[].path：相对 user_upload 的路径（用于下载或继续列目录）
• modified_at：文件 mtime（UNIX 秒）

可能错误：

• 400：path 不是目录或 path 非法
• 401：缺少或无效 token
• 404：目录不存在
• 503：系统未初始化

curl 示例

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8091/api/v1/files?path=inputs"

3) 下载文件/目录

GET /api/v1/files/download?path=<file_or_dir>

请求

• Headers：Authorization: Bearer <TOKEN>
• Query：
  • path：必填，相对 user_upload 的文件或目录路径

响应

1. 若 path 指向文件：返回文件二进制流（Content-Disposition: attachment）。
2. 若 path 指向目录：服务端会把目录打包成 zip 后返回（application/zip）。

可能错误：

• 400：缺少 path 或 path 非法
• 401：缺少或无效 token
• 404：文件/目录不存在
• 503：系统未初始化

curl 示例

下载文件：

curl -L -o out.txt \
  -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8091/api/v1/files/download?path=hello.txt"

下载目录（zip）：

curl -L -o inputs.zip \
  -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8091/api/v1/files/download?path=inputs"

zip 内的路径目前是相对 project/ 的（因此通常会包含 user_upload/ 前缀）。