> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 文件上传与挂载

> 上传文件为 Agent 提供上下文，并下载 Agent 产出的文件。

文件 API 让你向 Session 提供文件上下文——代码仓库、配置文件、参考文档等。Agent 可以读取这些文件来理解任务背景。

## 核心流程

<Steps>
  <Step title="上传文件">
    `POST /api/v1/cloud/files` — 上传文本类文件内容。
  </Step>

  <Step title="挂载到 Session">
    `POST /api/v1/cloud/sessions/{session_id}/resources` — 把已上传文件挂载到 Session。
  </Step>

  <Step title="Agent 使用">
    Session 运行期间 Agent 读取文件内容，完成任务。
  </Step>
</Steps>

## 上传文件

```
POST https://api.qoder.com/api/v1/cloud/files
Content-Type: multipart/form-data
```

### 参数

| 字段     | 类型     | 必填 | 说明     |
| ------ | ------ | -- | ------ |
| `file` | binary | 是  | 文件内容   |
| `name` | string | 否  | 自定义文件名 |

<Note>
  是否可通过 `/content` 下载以 File 对象的 `downloadable` 字段为准。
</Note>

<Tabs>
  <Tab title="单个文件">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./src/main.py"
    ```

    响应：

    ```json theme={null}
    {
      "id": "file_019e6a18dc0978e9a2104c9b269748ac",
      "type": "file",
      "filename": "main.py",
      "size_bytes": 4096,
      "downloadable": false,
      "mime_type": "text/plain",
      "scope": null,
      "created_at": "2026-05-01T10:00:00Z"
    }
    ```
  </Tab>

  <Tab title="多个文件">
    ```bash theme={null}
    # 逐个上传
    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./config.yaml"

    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./requirements.txt"
    ```
  </Tab>
</Tabs>

## 挂载到 Session

上传后，通过 Resources API 将文件挂载到指定 Session：

```
POST https://api.qoder.com/api/v1/cloud/sessions/{session_id}/resources
```

请求体（发送单个 file resource）：

```json theme={null}
{
  "type": "file",
  "file_id": "file_abc123",
  "mount_path": "/data/input.txt"
}
```

<Tabs>
  <Tab title="单个文件">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "resources": [
          {"type": "file", "file_id": "file_abc123"}
        ]
      }'
    ```
  </Tab>

  <Tab title="批量挂载">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "resources": [
          {"type": "file", "file_id": "file_abc123"},
          {"type": "file", "file_id": "file_def456"},
          {"type": "file", "file_id": "file_ghi789"}
        ]
      }'
    ```
  </Tab>
</Tabs>

## 管理文件

### 查看文件元信息

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "file_id": "file_abc123",
    "mount_path": "/data/input.txt"
  }'
```

如需在 Session 创建后挂载多个文件,请对每个文件各调用一次该接口。

### 列出文件

```bash theme={null}
curl "https://api.qoder.com/api/v1/cloud/files?scope_id=sess_abc123" \
  -H "Authorization: Bearer $QODER_PAT"
```

支持按 `scope_id` 过滤 Session 范围文件。

### 下载文件

`downloadable` 为 `true` 的文件可下载:

```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_PAT" \
  -o output.txt
```

不可下载文件请求 `/content` 端点将返回 `403 Forbidden`。

## 完整工作流示例

```bash theme={null}
# 1. 上传源代码文件
FILE_ID=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./app.py" | jq -r '.id')

echo "上传完成: $FILE_ID"

# 2. 创建 Session
SESSION_ID=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agent_abc123", "environment_id": "env_abc123"}' | jq -r '.id')

# 3. 挂载文件到 Session
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{\"type\": \"file\", \"file_id\": \"$FILE_ID\"}"

# 4. 发送任务（Agent 可引用已挂载的文件）
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "审查 app.py 并修复其中的 bug"}]}
    ]
  }'
```

## 常见问题

**Q：上传的文件存储多久？**

A：文件在你调用 `DELETE /api/v1/cloud/files/{file_id}` 显式删除前会持续保留。仍被活跃 Session 引用的文件无法删除，需先删除或取消挂载相关 Session。

**Q：能否直接在创建 Session 时附带文件？**

A：可以。创建 Session 时在 `resources` 字段中传入文件资源即可。详见 [Sessions — 创建时挂载资源](/zh/cloud-agents/sessions#创建时挂载资源)。

**Q：为什么有些文件不可下载？**

A：出于安全考虑，部分文件仅供 Agent 内部使用。如需导出结果，请使用 File 对象中 `downloadable` 为 `true` 的文件。

**Q：支持哪些文件格式？**

A：上传接口接受文本类文件。代码、配置和纯文本参考文档效果最佳。

## 下一步

<CardGroup cols={2}>
  <Card title="启动 Session" icon="play" href="/zh/cloud-agents/sessions">
    创建 Session 时直接附加文件。
  </Card>

  <Card title="持久化记忆" icon="brain" href="/zh/cloud-agents/memory-stores">
    在 Session 之间持久化 Agent 知识。
  </Card>

  <Card title="Files API" icon="code" href="/zh/cloud-agents/api/files/upload">
    完整的文件 API 接口。
  </Card>
</CardGroup>