file-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

File Management

文件管理

Overview

概述

Spuree is an agent-friendly cloud storage. Projects contain folders (nestable) and files at any level. This skill manages files — they can live directly under a project or inside any folder. In the API, projects and folders are both called sessions (

sessionType

creative_project

= project,

session

= folder).

Use this skill when an agent needs to:

Search for files and folders by name across all projects
Get a file by ID with download URL
Upload new files to a project or folder
Update file metadata (rename, move) or content (with conflict detection)
Delete files (soft delete)

Spuree是一款对Agent友好的云存储服务。项目中包含可嵌套的文件夹和任意层级的文件。本Skill用于管理文件——文件可直接存放在项目下，也可存放在任意文件夹中。在API中，项目和文件夹都被称为sessions（

sessionType

creative_project

= 项目，

session

= 文件夹）。

当Agent需要以下操作时，可使用本Skill：

跨所有项目按名称搜索文件和文件夹
通过ID获取文件及下载URL
上传新文件至项目或文件夹
更新文件元数据（重命名、移动）或内容（含冲突检测）
删除文件（软删除）

Authentication

身份验证

Authorization: Bearer $SPUREE_ACCESS_TOKEN

Or:

X-API-Key: $SPUREE_API_KEY

. See the authentication skill.

Authorization: Bearer $SPUREE_ACCESS_TOKEN

或者：

X-API-Key: $SPUREE_API_KEY

。请查看身份验证Skill。

Base URLs

基础URL

Base URL	Endpoints
`https://data.spuree.com/api/v1/files`	File CRUD
`https://data.spuree.com/api/v1/search`	Cross-project search

基础URL	端点
`https://data.spuree.com/api/v1/files`	文件CRUD操作
`https://data.spuree.com/api/v1/search`	跨项目搜索

Endpoints

端点详情

GET /v1/search

Search files and folders by name (case-insensitive substring match). Returns sessions first, then files.

Query Parameters:

Parameter	Type	Default	Description
`q`	string	—	Search query (1–255 chars)
`type`	string	—	Filter: `"file"` or `"session"` . Omit for both.
`workspaceId`	string	—	Restrict results to a specific workspace
`limit`	integer	100	Max results (1–100)

Response:

{ "data": [...], "count": N }

Each result has

type

(

"file"

"session"

) plus type-specific fields:

session:

id

name

sessionType

workspaceId

createdAt

updatedAt

file:

id

fileName

fileFormat

mimeType

size

workspaceId

sessionId

entitySessionId

createdAt

updatedAt

bash

curl "https://data.spuree.com/api/v1/search?q=hero" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

按名称搜索文件和文件夹（不区分大小写的子串匹配）。返回结果先显示sessions，再显示文件。

查询参数：

参数	类型	默认值	描述
`q`	string	—	搜索关键词（1–255字符）
`type`	string	—	过滤条件： `"file"` 或 `"session"` 。留空则返回两者
`workspaceId`	string	—	将结果限制在指定工作区
`limit`	integer	100	最大返回结果数（1–100）

响应：

{ "data": [...], "count": N }

每个结果包含

type

（

"file"

或

"session"

）及对应类型的专属字段：

session:

id

name

sessionType

workspaceId

createdAt

updatedAt

file:

id

fileName

fileFormat

mimeType

size

workspaceId

sessionId

entitySessionId

createdAt

updatedAt

bash

curl "https://data.spuree.com/api/v1/search?q=hero" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/files/{fileId}

Get file metadata and presigned download URL.

Response:

{ "data": { id, fileName, fileFormat, mimeType, size, workspaceId, sessionId, entitySessionId, downloadUrl, createdAt, updatedAt } }

bash

curl "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

获取文件元数据及预签名下载URL。

响应：

{ "data": { id, fileName, fileFormat, mimeType, size, workspaceId, sessionId, entitySessionId, downloadUrl, createdAt, updatedAt } }

bash

curl "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/files

Create a file record and get presigned upload URL(s). Automatically selects upload mode based on file size:

< 100 MB → single presigned PUT URL (
```
mode: "single"
```
)
≥ 100 MB → multipart upload with per-part presigned URLs (
```
mode: "multipart"
```
)

The caller must then upload to S3 and call

POST /v1/files/{fileId}/upload/complete

. Without the complete call, the file remains pending and unusable.

Request Body:

Field	Type	Required	Description
`fileName`	string	Yes	File name without extension
`fileFormat`	string	Yes	Extension in lowercase (e.g., `fbx` , `png` )
`fileSize`	integer	Yes	File size in bytes (accepts string for backward compat)
`sessionId`	string	Yes	Target project or folder ObjectId
`checksum`	string	No	CRC32 base64 (8 chars) for end-to-end verification. When provided, the presigned URL is signed with the checksum and S3 verifies the upload matches.

Response (single mode):

{ messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }

Response (multipart mode):

{ messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }

Code	Description
200	Record created, presigned URL(s) returned
404	Session not found
409	File already exists

bash

curl -X POST "https://data.spuree.com/api/v1/files" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"hero_walk","fileFormat":"fbx","fileSize":5242880,"sessionId":"...","checksum":"AAAAAA=="}'

创建文件记录并获取预签名上传URL。系统会根据文件大小自动选择上传模式：

小于100 MB → 单个预签名PUT URL（
```
mode: "single"
```
）
大于等于100 MB → 分块上传，包含各分块的预签名URL（
```
mode: "multipart"
```
）

调用方必须先上传文件至S3，再调用

POST /v1/files/{fileId}/upload/complete

。若未调用该完成接口，文件将处于待处理状态，无法使用。

请求体：

字段	类型	是否必填	描述
`fileName`	string	是	不含扩展名的文件名
`fileFormat`	string	是	小写格式的扩展名（如 `fbx` , `png` ）
`fileSize`	integer	是	文件大小（字节，为兼容旧版本也接受字符串类型）
`sessionId`	string	是	目标项目或文件夹的ObjectId
`checksum`	string	否	CRC32 base64格式（8字符），用于端到端验证。提供该值时，预签名URL会附带校验和，S3将验证上传内容是否匹配。

响应（单文件模式）：

{ messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }

响应（分块模式）：

{ messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }

状态码	描述
200	文件记录创建成功，返回预签名URL
404	目标session不存在
409	文件已存在

bash

curl -X POST "https://data.spuree.com/api/v1/files" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"hero_walk","fileFormat":"fbx","fileSize":5242880,"sessionId":"...","checksum":"AAAAAA=="}'

POST /v1/files/{fileId}/upload/complete

Mark a file upload as completed. Works for both single and multipart uploads — the server auto-detects by checking whether the file has an active multipart

uploadId

. For multipart, the server calls S3

ListParts

to collect ETags and then

CompleteMultipartUpload

Request Body:

Field	Type	Required	Description
`fileId`	string	Yes	Must match path parameter
`clientChecksumCRC32`	string	No	Client-computed CRC32 for end-to-end verification

Response:

{ messageCode, fileId, checksum, checksumCRC32 }

```
checksum
```
: S3-verified CRC32 (base64) for both single and multipart uploads
```
checksumCRC32
```
: S3 FULL_OBJECT CRC32 (multipart only)

bash

curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/complete" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "..."}'

标记文件上传完成。适用于单文件和分块上传——服务器会通过检查文件是否存在活跃的分块

uploadId

自动识别模式。对于分块上传，服务器会调用S3的

ListParts

接口收集ETag，再调用

CompleteMultipartUpload

完成上传。

请求体：

字段	类型	是否必填	描述
`fileId`	string	是	必须与路径参数中的fileId一致
`clientChecksumCRC32`	string	否	客户端计算的CRC32值，用于端到端验证

响应：

{ messageCode, fileId, checksum, checksumCRC32 }

```
checksum
```
: S3验证后的CRC32值（base64格式），适用于单文件和分块上传
```
checksumCRC32
```
: S3返回的完整对象CRC32值（仅分块上传）

bash

curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/complete" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "..."}'

PATCH /v1/files/{fileId}

Update file metadata. At least one field required.

Field	Type	Description
`fileName`	string	New name (without extension)
`fileFormat`	string	New extension (lowercase)
`checksum`	string	CRC32 base64 (write-once backfill, no edit permission needed)
`sessionId`	string	Move to target project or folder

Move: Only

creative_project

(project) and

session

(folder) targets supported.

Response:

{ messageCode, fileId }

Code	Description
200	Updated
409	Filename conflict in target

bash

curl -X PATCH "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "hero_run_cycle"}'

更新文件元数据。至少需要提供一个字段。

字段	类型	描述
`fileName`	string	新文件名（不含扩展名）
`fileFormat`	string	新扩展名（小写）
`checksum`	string	CRC32 base64格式（仅可一次性补填，无需编辑权限）
`sessionId`	string	将文件移动至目标项目或文件夹

移动操作： 仅支持

creative_project

（项目）和

session

（文件夹）作为目标。

响应：

{ messageCode, fileId }

状态码	描述
200	更新成功
409	目标位置存在同名文件

bash

curl -X PATCH "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "hero_run_cycle"}'

PUT /v1/files/{fileId}

Prepare a content update with optimistic concurrency. Acquires an upload lock. Like

POST /v1/files

, automatically selects single or multipart mode based on

fileSize

Request Body:

Field	Type	Required	Description
`expectedChecksum`	string	Yes	CRC32 base64 of current content (for conflict detection)
`newChecksum`	string	Yes	CRC32 base64 of new content to upload
`fileSize`	integer	No	Size in bytes. If ≥ 100 MB, returns multipart mode.

Response (single):

{ messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }

Response (multipart):

{ messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }

After receiving the response, upload to S3 then call

POST /v1/files/{fileId}/upload/complete

Upload lock: Single uploads lock for 1 hour. Multipart uploads lock for 6 hours. Same user can re-acquire. Expired locks auto-release.

Code	Description
200	Lock acquired, presigned URL(s) returned
409	Checksum mismatch or locked by another user

bash

curl -X PUT "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedChecksum": "a1b2...","newChecksum": "f6e5..."}'

通过乐观锁机制准备内容更新，会获取上传锁。与

POST /v1/files

类似，系统会根据

fileSize

自动选择单文件或分块模式。

请求体：

字段	类型	是否必填	描述
`expectedChecksum`	string	是	当前文件内容的CRC32 base64值（用于冲突检测）
`newChecksum`	string	是	待上传新内容的CRC32 base64值
`fileSize`	integer	否	文件大小（字节）。若大于等于100 MB，返回分块模式

响应（单文件模式）：

{ messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }

响应（分块模式）：

{ messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }

收到响应后，上传文件至S3，再调用

POST /v1/files/{fileId}/upload/complete

。

上传锁： 单文件上传锁有效期1小时，分块上传锁有效期6小时。同一用户可重新获取锁，过期锁会自动释放。

状态码	描述
200	获取锁成功，返回预签名URL
409	校验和不匹配或文件被其他用户锁定

bash

curl -X PUT "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedChecksum": "a1b2...","newChecksum": "f6e5..."}'

GET /v1/files/{fileId}/upload

Resume a multipart upload. Returns which parts are already in S3 and fresh presigned URLs for remaining parts.

Query Parameters:

Parameter	Type	Required	Description
`uploadId`	string	No	Client's expected uploadId for mismatch detection
`checksum`	string	No	Client's expected pendingChecksum for conflict detection

Response:

{ messageCode, fileId, completedParts: [{partNumber, etag, size}, ...], remainingParts: [{partNumber, startByte, endByte, url}, ...], totalParts }

Code	Description
200	Success
400	No active multipart upload
409	Not in pending status or locked by another user

bash

curl "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

恢复分块上传。返回已上传至S3的分块及剩余分块的新预签名URL。

查询参数：

参数	类型	是否必填	描述
`uploadId`	string	否	客户端预期的uploadId，用于检测不匹配情况
`checksum`	string	否	客户端预期的pendingChecksum，用于冲突检测

响应：

{ messageCode, fileId, completedParts: [{partNumber, etag, size}, ...], remainingParts: [{partNumber, startByte, endByte, url}, ...], totalParts }

状态码	描述
200	操作成功
400	无活跃的分块上传任务
409	文件未处于待处理状态或被其他用户锁定

bash

curl "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/files/{fileId}/upload/urls

Refresh presigned URLs for specific parts of a multipart upload. Use when URLs have expired before upload completes.

Request Body:

{ "partNumbers": [1, 3, 5] }

(1-indexed, min 1 part)

Response:

{ messageCode, urls: [{partNumber, startByte, endByte, url}, ...] }

Code	Description
200	Success
400	No active multipart upload or invalid part numbers

bash

curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/urls" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"partNumbers": [1, 3, 5]}'

刷新分块上传中指定分块的预签名URL。当URL在上传完成前过期时使用。

请求体：

{ "partNumbers": [1, 3, 5] }

（从1开始索引，至少指定1个分块）

响应：

{ messageCode, urls: [{partNumber, startByte, endByte, url}, ...] }

状态码	描述
200	操作成功
400	无活跃的分块上传任务或分块编号无效

bash

curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/urls" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"partNumbers": [1, 3, 5]}'

DELETE /v1/files/{fileId}/upload

Abort a multipart upload. Cleans up S3 parts and marks the file as failed. Idempotent — safe to call on already-aborted uploads.

Response:

{ messageCode, fileId, message }

Code	Description
200	Aborted
400	No active multipart upload

bash

curl -X DELETE "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

终止分块上传。清理S3中的分块并标记文件上传失败。该接口是幂等的——对已终止的上传任务调用也不会报错。

响应：

{ messageCode, fileId, message }

状态码	描述
200	终止成功
400	无活跃的分块上传任务

bash

curl -X DELETE "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

DELETE /v1/files/{fileId}

Soft-delete a file.

Response:

{ messageCode, fileId }

bash

curl -X DELETE "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

软删除文件。

响应：

{ messageCode, fileId }

bash

curl -X DELETE "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

Common Patterns

常见流程

Single Upload Flow (< 100 MB)

单文件上传流程（小于100 MB）

Compute CRC32 checksum (base64):

bash

CHECKSUM=$(python3 -c "import base64, zlib, sys; print(base64.b64encode(zlib.crc32(open('$FILE_PATH','rb').read()).to_bytes(4,'big')).decode())")

Create file record —

sessionId

is the target project or folder:

POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
→ { fileId, mode: "single", uploadUrl, checksumBase64, contentType }

Upload binary to S3:

PUT {uploadUrl}
Content-Type: {contentType}
x-amz-checksum-crc32: {checksumBase64}
Body: <file binary>

Complete the upload — REQUIRED (file is not visible until this is called):
```
POST /v1/files/{fileId}/upload/complete
```

Important: All three steps (create → S3 upload → complete) must be performed. Skipping complete leaves the file in a pending state.

计算CRC32校验和（base64格式）：

bash

CHECKSUM=$(python3 -c "import base64, zlib, sys; print(base64.b64encode(zlib.crc32(open('$FILE_PATH','rb').read()).to_bytes(4,'big')).decode())")

创建文件记录 —

sessionId

为目标项目或文件夹的ID：

POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
→ { fileId, mode: "single", uploadUrl, checksumBase64, contentType }

上传二进制文件至S3：

PUT {uploadUrl}
Content-Type: {contentType}
x-amz-checksum-crc32: {checksumBase64}
Body: <文件二进制内容>

完成上传——必填（调用此接口前文件不可见）：
```
POST /v1/files/{fileId}/upload/complete
```

重要提示： 必须完成三个步骤（创建→S3上传→完成）。跳过完成步骤会导致文件处于待处理状态。

Multipart Upload Flow (≥ 100 MB)

分块上传流程（大于等于100 MB）

Create file record with

fileSize

≥ 100 MB:

POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
→ { fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }

Upload each part to its presigned URL:

PUT {part.url}
Content-Length: {part.endByte - part.startByte + 1}
Body: <file slice from startByte to endByte>

If interrupted, resume with
```
GET /v1/files/{fileId}/upload
```
to get completed parts and fresh URLs for remaining parts.
If URLs expire, refresh with
```
POST /v1/files/{fileId}/upload/urls
```
for specific parts.

Complete — server auto-detects multipart and calls S3

CompleteMultipartUpload

POST /v1/files/{fileId}/upload/complete

To abort, call
```
DELETE /v1/files/{fileId}/upload
```
to clean up S3 parts.

创建文件记录，且

fileSize

大于等于100 MB：

POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
→ { fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }

上传每个分块至对应的预签名URL：

PUT {part.url}
Content-Length: {part.endByte - part.startByte + 1}
Body: <文件切片内容，从startByte到endByte>

若上传中断，调用
```
GET /v1/files/{fileId}/upload
```
恢复上传，获取已完成分块和剩余分块的新URL。
若URL过期，调用
```
POST /v1/files/{fileId}/upload/urls
```
刷新指定分块的URL。
完成上传——服务器自动识别分块模式并调用S3的
```
CompleteMultipartUpload
```
接口：
```
POST /v1/files/{fileId}/upload/complete
```
若需终止上传，调用
```
DELETE /v1/files/{fileId}/upload
```
清理S3中的分块。

Content Update Flow

内容更新流程

```
PUT /v1/files/{fileId}
```
with checksums (and
```
fileSize
```
for multipart) → get upload URL(s)
Upload new content to S3 (single or multipart, same as above)
```
POST /v1/files/{fileId}/upload/complete
```
— REQUIRED

调用
```
PUT /v1/files/{fileId}
```
并传入校验和（分块上传需传入
```
fileSize
```
）→ 获取上传URL
将新内容上传至S3（单文件或分块模式，流程同上）
调用
```
POST /v1/files/{fileId}/upload/complete
```
——必填

Viewing / Previewing a File

文件查看/预览

When a user wants to view, preview, or see a file:

If the agent has browser tools (e.g., Chrome DevTools MCP), open the Studio preview URL directly:
```
navigate_page → https://studio.spuree.com/file/{fileId}
```
Otherwise, return the Studio preview URL for the user to click:
```
https://studio.spuree.com/file/{fileId}
```

Do not download the file or attempt to open it locally. The Studio URL is permanent, permission-aware, and renders images, video, 3D, and other supported formats inline in the browser.

Use case	URL	Properties
Share with user / preview	`https://studio.spuree.com/file/{fileId}`	Permanent, permission-aware, renders preview UI
Programmatic download	`downloadUrl` from `GET /v1/files/{fileId}`	Short-lived presigned S3 URL — do not share, bypasses permissions and expires

Rule of thumb: after

POST /v1/files

(upload) or

GET /v1/search

, build the Studio URL from the returned

fileId

and return that to the user. Only fetch

downloadUrl

when the agent itself needs the bytes.

当用户需要查看、预览文件时：

若Agent具备浏览器工具（如Chrome DevTools MCP），直接打开Studio预览URL：
```
navigate_page → https://studio.spuree.com/file/{fileId}
```
否则，返回Studio预览URL供用户点击：
```
https://studio.spuree.com/file/{fileId}
```

请勿下载文件或尝试在本地打开。Studio URL是永久链接，具备权限控制功能，可在浏览器中直接渲染图片、视频、3D模型及其他支持的格式。

使用场景	URL	属性
分享给用户/预览	`https://studio.spuree.com/file/{fileId}`	永久链接，权限可控，提供预览UI
程序化下载	从 `GET /v1/files/{fileId}` 获取的 `downloadUrl`	短期有效的S3预签名URL——请勿分享，会绕过权限验证且过期失效

经验法则： 在调用

POST /v1/files

（上传）或

GET /v1/search

后，使用返回的

fileId

构建Studio URL并返回给用户。仅当Agent自身需要文件字节流时，才获取

downloadUrl

。

Search Then Download

搜索后下载

```
GET /v1/search?q=hero_walk
```
→ find file ID
```
GET /v1/files/{fileId}
```
→ get
```
downloadUrl
```
Download from the presigned URL

调用
```
GET /v1/search?q=hero_walk
```
→ 找到文件ID
调用
```
GET /v1/files/{fileId}
```
→ 获取
```
downloadUrl
```
从预签名URL下载文件

File Organization

文件组织

Projects and folders are both sessions.

sessionId

always refers to a session. Session types:

creative_project

(project),

session

(folder). Folders nest inside projects or other folders.

S3 key:

works_{workspaceId}/sess_{sessionId}/file_{fileId}

项目和文件夹都是sessions。

sessionId

始终指向一个session。Session类型：

creative_project

（项目）、

session

（文件夹）。文件夹可嵌套在项目或其他文件夹中。

S3存储路径：

works_{workspaceId}/sess_{sessionId}/file_{fileId}

Studio URLs

Studio URL规则

Resource	URL Pattern
Project	`https://studio.spuree.com/projects/{projectId}`
Folder (top-level)	`https://studio.spuree.com/projects/{projectId}/folders/{folderId}`
Folder (nested)	`.../folders/{parentId}/{childId}` (up to 5 levels)
File	`https://studio.spuree.com/file/{fileId}`

资源	URL格式
项目	`https://studio.spuree.com/projects/{projectId}`
文件夹（顶层）	`https://studio.spuree.com/projects/{projectId}/folders/{folderId}`
文件夹（嵌套）	`.../folders/{parentId}/{childId}` （最多支持5层嵌套）
文件	`https://studio.spuree.com/file/{fileId}`

Error Handling

错误处理

Code	Cause	Resolution
400	Invalid checksum format, missing fields, bad ID	Fix input format
403	No workspace access or edit permission	Check permissions
404	File or session not found	Verify IDs
409 (checksum mismatch)	File modified by another user	Re-fetch checksum, retry
409 (upload lock)	Another user is uploading	Wait (lock expires in 1 hour for single, 6 hours for multipart)
409 (filename conflict)	Same name exists in target	Use different name or target
401	Invalid or expired token	Refresh via authentication skill

状态码	原因	解决方案
400	校验和格式无效、字段缺失、ID错误	修正输入格式
403	无工作区访问权限或编辑权限	检查权限设置
404	文件或session不存在	验证ID正确性
409（校验和不匹配）	文件被其他用户修改	重新获取校验和后重试
409（上传锁）	文件被其他用户锁定上传	等待（单文件上传锁1小时后过期，分块上传锁6小时后过期）
409（文件名冲突）	目标位置存在同名文件	使用其他文件名或更换目标位置
401	Token无效或过期	通过身份验证Skill刷新Token