project-files

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Project Files

Skill: 项目文件

Description

描述

Manage files in project directories. This skill documents the public API at

/api/v2/projects/{projectId}

(PublicApiProjectFileController). Upload flow: 1) POST prepare with directoryId; 2) PUT file to

upload_url

; 3) POST confirm with

file_id

. All paths require

projectId

; prepare/prepare-update also need

directoryId

. Authenticate with

X-API-KEY

header.

管理项目目录中的文件。本Skill记录了路径为

/api/v2/projects/{projectId}

的公共API（对应PublicApiProjectFileController）。上传流程：1）携带directoryId发起POST预准备请求；2）将文件PUT到返回的

upload_url

；3）携带

file_id

发起POST确认请求。所有路径都需要

projectId

参数；上传/更新预准备接口还需要

directoryId

参数。通过

X-API-KEY

请求头进行鉴权。

TypeScript types (request / response)

TypeScript类型定义（请求/响应）

Mirrors

PublicApiProjectFileController

data classes.

typescript

// --- Prepare upload (POST) — 201 ---
type PrepareFileUploadRequest = {
  path: string;
  file_name: string;
  mime_type: string;
  size: number;
};
type PrepareFileUploadResponse = {
  upload_url: string;
  file_id: string;
  s3_key: string;
  expires_at: string;
};

// --- Prepare update (POST) ---
type PrepareUpdateFileRequest = {
  path: string;
  mime_type?: string | null;
  size?: number | null;
};
type PrepareUpdateFileResponse = {
  upload_url: string;
  file_id: string;
  s3_key: string;
  expires_at: string;
};

// --- Confirm (POST) ---
type ConfirmFileUploadRequest = { metadata?: Record<string, unknown> | null };
type FileResponse = {
  id: string;
  name: string;
  file_type: string;
  mime_type: string;
  s3_key: string;
  size: number;
  uploaded_at: string;
  uploaded_by: string;
  status: string;
  metadata: Record<string, unknown> | null;
};

// --- Download URL (GET), Get file (GET), Delete (DELETE) ---
type DownloadUrlResponse = {
  download_url: string;
  expires_at: string;
};

与

PublicApiProjectFileController

的数据类保持一致。

typescript

// --- Prepare upload (POST) — 201 ---
type PrepareFileUploadRequest = {
  path: string;
  file_name: string;
  mime_type: string;
  size: number;
};
type PrepareFileUploadResponse = {
  upload_url: string;
  file_id: string;
  s3_key: string;
  expires_at: string;
};

// --- Prepare update (POST) ---
type PrepareUpdateFileRequest = {
  path: string;
  mime_type?: string | null;
  size?: number | null;
};
type PrepareUpdateFileResponse = {
  upload_url: string;
  file_id: string;
  s3_key: string;
  expires_at: string;
};

// --- Confirm (POST) ---
type ConfirmFileUploadRequest = { metadata?: Record<string, unknown> | null };
type FileResponse = {
  id: string;
  name: string;
  file_type: string;
  mime_type: string;
  s3_key: string;
  size: number;
  uploaded_at: string;
  uploaded_by: string;
  status: string;
  metadata: Record<string, unknown> | null;
};

// --- Download URL (GET), Get file (GET), Delete (DELETE) ---
type DownloadUrlResponse = {
  download_url: string;
  expires_at: string;
};

Prepare Project File Upload

项目文件上传预准备

Request body:

PrepareFileUploadRequest

. Response (201):

PrepareFileUploadResponse

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/directories/<directory_id>/files/prepare" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"path":"/","file_name":"doc.pdf","mime_type":"application/pdf","size":2048}'

请求体：

PrepareFileUploadRequest

。响应（201）：

PrepareFileUploadResponse

。

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/directories/<directory_id>/files/prepare" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"path":"/","file_name":"doc.pdf","mime_type":"application/pdf","size":2048}'

Prepare Project File Update

项目文件更新预准备

Request body:

PrepareUpdateFileRequest

. Response:

PrepareUpdateFileResponse

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/directories/<directory_id>/files/prepare-update" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"path":"/doc.pdf","mime_type":"application/pdf","size":2048}'

请求体：

PrepareUpdateFileRequest

。响应：

PrepareUpdateFileResponse

。

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/directories/<directory_id>/files/prepare-update" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"path":"/doc.pdf","mime_type":"application/pdf","size":2048}'

Confirm Project File Upload

项目文件上传确认

Request body:

ConfirmFileUploadRequest

. Response:

FileResponse

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/files/<file_id>/confirm" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"metadata":{}}'

请求体：

ConfirmFileUploadRequest

。响应：

FileResponse

。

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/files/<file_id>/confirm" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"metadata":{}}'

Get File Download URL

获取文件下载链接

Response:

DownloadUrlResponse

bash

curl "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/files/<file_id>/download-url" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

响应：

DownloadUrlResponse

。

bash

curl "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/files/<file_id>/download-url" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Get File Details

获取文件详情

Response:

FileResponse

bash

curl "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/files/<file_id>" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

响应：

FileResponse

。

bash

curl "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/files/<file_id>" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Delete Project File

删除项目文件

Response: 204 No Content.

bash

curl -X DELETE "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/files/<file_id>" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

响应：204 No Content。

bash

curl -X DELETE "$LAYERPROOF_BASE_URL/api/v2/projects/<project_id>/files/<file_id>" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Agent behavior

Agent行为

When the user asks to manage project files (upload, update, confirm, download, delete), do the following.

当用户要求管理项目文件（上传、更新、确认、下载、删除）时，执行以下操作：

1. Choose the right endpoint

1. 选择正确的端点

Base path:

/api/v2/projects/{projectId}

. Replace

project_id

directory_id

file_id

as needed.

User intent	Endpoint	Method
Get upload URL for new file	`.../directories/{directoryId}/files/prepare`	POST
Get upload URL to update file	`.../directories/{directoryId}/files/prepare-update`	POST
Confirm upload after PUT	`.../files/{fileId}/confirm`	POST
Get download URL	`.../files/{fileId}/download-url`	GET
Get file metadata	`.../files/{fileId}`	GET
Delete file	`.../files/{fileId}`	DELETE

基础路径：

/api/v2/projects/{projectId}

，按需替换

project_id

、

directory_id

、

file_id

参数。

用户意图	端点	请求方法
获取新文件的上传地址	`.../directories/{directoryId}/files/prepare`	POST
获取更新文件的上传地址	`.../directories/{directoryId}/files/prepare-update`	POST
PUT上传完成后确认操作	`.../files/{fileId}/confirm`	POST
获取下载链接	`.../files/{fileId}/download-url`	GET
获取文件元数据	`.../files/{fileId}`	GET
删除文件	`.../files/{fileId}`	DELETE

2. Build and run the request

2. 构造并执行请求

Auth: Include
```
X-API-KEY: $LAYERPROOF_API_KEY
```
. Read env vars; if missing, tell the user.
Path: Resolve projectId, directoryId, fileId from context or user input.
POST: Build JSON body from types above; run curl and show result.
GET/DELETE: Build path only; run curl and show result.

鉴权：请求头需携带
```
X-API-KEY: $LAYERPROOF_API_KEY
```
，读取环境变量，若变量不存在则告知用户。
路径：从上下文或用户输入中解析projectId、directoryId、fileId参数。
POST请求：根据上述类型定义构造JSON请求体，执行curl命令并展示结果。
GET/DELETE请求：仅构造请求路径，执行curl命令并展示结果。

3. Upload flow

3. 上传流程

Prepare → PUT file to

upload_url

→ confirm with

file_id

. Then use

file_id

for get/download/delete.

预准备 → 将文件PUT到

upload_url

→ 携带

file_id

确认。后续可使用

file_id

执行查询、下载、删除操作。

4. Response handling

4. 响应处理

Always show raw JSON in a code block; show image + JSON if image URL present.
On error, show body and status code.

始终在代码块中展示原始JSON；若返回图片URL则同时展示图片和JSON。
请求出错时，展示响应体和状态码。

5. Example workflows

5. 示例工作流

Workflow A — User: "Upload a PDF to project X in the root directory."

Resolve projectId and directoryId (e.g. root directory from project or list directories). POST

.../directories/{directoryId}/files/prepare

with

{"path":"/","file_name":"brief.pdf","mime_type":"application/pdf","size":<bytes>}

; get

upload_url

file_id

s3_key

Tell user to PUT the file to

upload_url

with

Content-Type: application/pdf

. Then POST

.../files/{file_id}/confirm

with

{}

(or

{"metadata":{}}

Show JSON; use
```
file_id
```
for later get/download/delete.

Workflow B — User: "Upload two reference docs to the project, then use them when generating the slide deck outline."

For each file: prepare with path (e.g.
```
/ref1.pdf
```
,
```
/ref2.docx
```
) → user uploads to
```
upload_url
```
→ confirm. Capture both
```
file_id
```
and
```
s3_key
```
(if returned) for each.
If outline generation accepts project file references: pass the project file identifiers (e.g. s3_keys or file_ids) into the slide-deck outline/generate request (e.g.
```
file_s3_keys
```
or equivalent). Otherwise use public-files for outline references and keep project files for project-scoped use only.
Hand off to slide-decks: POST outline/generate with the resolved keys; poll job; get deck.

Workflow C — User: "Update an existing file in the project (new version) and get a download URL after."

Resolve projectId, directoryId, and existing file path. POST

.../directories/{directoryId}/files/prepare-update

with

{"path":"/brief.pdf","mime_type":"application/pdf","size":<new_bytes>}

; get

upload_url

file_id

User PUTs new content to
```
upload_url
```
; then POST
```
.../files/{file_id}/confirm
```
. GET
```
.../files/{file_id}/download-url
```
to show the user a temporary download link.
On error (e.g. path not found), show response body and suggest verifying path and project/directory IDs.

工作流A — 用户："上传一份PDF到X项目的根目录。"

解析projectId和directoryId（例如从项目信息中获取根目录ID，或调用接口查询目录列表）。携带参数
```
{"path":"/","file_name":"brief.pdf","mime_type":"application/pdf","size":<bytes>}
```
发起POST请求到
```
.../directories/{directoryId}/files/prepare
```
，获取
```
upload_url
```
、
```
file_id
```
、
```
s3_key
```
。
告知用户将文件PUT到
```
upload_url
```
，请求头需携带
```
Content-Type: application/pdf
```
，完成后携带
```
{}
```
（或
```
{"metadata":{}}
```
）发起POST请求到
```
.../files/{file_id}/confirm
```
完成确认。
展示JSON响应，后续可使用
```
file_id
```
执行查询、下载、删除操作。

工作流B — 用户："上传两份参考文档到项目中，后续生成幻灯片大纲时需要用到这些文档。"

逐个处理文件：携带路径（例如
```
/ref1.pdf
```
、
```
/ref2.docx
```
）发起预准备请求 → 用户上传文件到
```
upload_url
```
→ 确认上传。记录每个文件的
```
file_id
```
和
```
s3_key
```
（如果返回）。
如果大纲生成接口支持传入项目文件引用：将项目文件标识（例如s3_keys或file_ids）传入幻灯片大纲生成请求（对应参数
```
file_s3_keys
```
或等效参数）。否则使用公共文件作为大纲引用，项目文件仅在项目范围内使用。
流转到幻灯片生成模块：携带解析后的标识发起大纲生成POST请求，轮询任务状态，获取生成的幻灯片。

工作流C — 用户："更新项目中的现有文件（新版本），完成后获取下载链接。"

解析projectId、directoryId和现有文件路径。携带参数

{"path":"/brief.pdf","mime_type":"application/pdf","size":<new_bytes>}

发起POST请求到

.../directories/{directoryId}/files/prepare-update

，获取

upload_url

、

file_id

。

用户将新内容PUT到
```
upload_url
```
，之后发起POST请求到
```
.../files/{file_id}/confirm
```
完成确认。发起GET请求到
```
.../files/{file_id}/download-url
```
，向用户返回临时下载链接。
请求出错时（例如路径不存在），展示响应体，建议用户校验路径和项目/目录ID是否正确。

Response format (required)

响应格式（必填）

(if response contains url to show image) please show image and show json response instead of table
Always show the raw JSON response (verbatim) in a JSON code block.
If the response contains a URL for an image, render/show the image and also show the JSON response (do not convert to a table).

如果响应包含图片展示URL，请同时展示图片和JSON响应，不要使用表格。
始终在JSON代码块中展示原始JSON响应（逐字保留）。
如果响应包含图片URL，请渲染/展示图片同时展示JSON响应（不要转换为表格）。