agent-Specialization/api_doc/files.md

文件 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）：

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

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

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：

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  "https://agent.cyjai.com/api/v1/workspaces/ws1/files?path=inputs"

下载目录 ws1/user_upload/inputs：

curl -L -o inputs.zip \
  -H "Authorization: Bearer <TOKEN>" \
  "https://agent.cyjai.com/api/v1/workspaces/ws1/files/download?path=inputs"