文件上传与挂载-Qoder CN 系列(Lingma)-阿里云帮助中心

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

核心流程

POST /files — 上传文件二进制内容并指定 purpose。 POST /sessions/{session_id}/resources — 把已上传文件挂载到 Session。 Session 运行期间 Agent 读取文件内容，完成任务。

上传文件

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

参数

字段	类型	必填	说明
`file`	binary	是	文件内容
`purpose`	string	是	文件用途（见下表）
`filename`	string	否	自定义文件名

purpose 字段说明

值	含义	谁创建	可下载
`user_upload`	用户上传的输入文件	用户	否
`tool_output`	工具执行产出的文件	Agent/工具	是
`skill_output`	Skill 执行产出的文件	Agent/Skill	是
`session_resource`	Session 级别的资源文件	用户/系统	否
`agent_output`	Agent 最终输出文件	Agent	否

说明

仅 tool_output 和 skill_output 可通过 /content 端点下载。其他类型仅供 Agent 内部使用。

curl 上传示例

curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./src/main.py" \
  -F "purpose=user_upload"

响应：

{
  "file_id": "file_019e6a18dc0978e9a2104c9b269748ac",
  "filename": "main.py",
  "purpose": "user_upload",
  "size_bytes": 4096,
  "metadata": {},
  "mime_type": "text/plain",
  "status": "ready",
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z"
}

上传多个文件：

# 逐个上传
curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./config.yaml" \
  -F "purpose=user_upload"

curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./requirements.txt" \
  -F "purpose=user_upload"

挂载到 Session

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

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

请求体（使用 resources 数组包装，单次可批量挂载）：

{
  "resources": [
    {
      "type": "file",
      "file_id": "file_abc123"
    }
  ]
}

curl 挂载示例

curl -X POST https://api.qoder.com.cn/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"}
    ]
  }'

批量挂载多个文件（一次请求传入多个资源）：

curl -X POST https://api.qoder.com.cn/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"}
    ]
  }'

下载文件

仅 tool_output 和 skill_output 类型的文件可下载：

curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_PAT" \
  -o output.txt

其他类型请求 /content 端点将返回 403 Forbidden。

查看文件信息

curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123 \
  -H "Authorization: Bearer $QODER_PAT"

列出文件

curl "https://api.qoder.com.cn/api/v1/cloud/files?purpose=user_upload" \
  -H "Authorization: Bearer $QODER_PAT"

支持按 purpose 过滤。

完整工作流示例

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

echo "上传完成: $FILE_ID"

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

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

# 4. 发送任务（Agent 可引用已挂载的文件）
curl -X POST "https://api.qoder.com.cn/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：文件与所属资源（Agent/Session）生命周期一致。Session 删除后相关文件会被清理。

Q：能否直接在创建 Session 时附带文件？ A：当前需分步操作：先上传、再挂载。后续版本可能支持一步完成。

Q：为什么 user_upload 类型不可下载？ A：出于安全考虑，用户上传的原始文件仅供 Agent 内部使用。如需导出结果，Agent 会以 tool_output 或 skill_output 类型产出新文件。

Q：支持哪些文件格式？ A：无格式限制，任意二进制文件均可上传。Agent 对文本类文件（代码、配置、文档）的理解效果最佳。