檔案上傳與掛載 - Qoder CN 系列

檔案 API 讓你向 Session 提供檔案上下文——代碼倉庫、設定檔、參考文檔等。Agent 可以讀取這些檔案來理解任務背景。

核心流程

上傳檔案
POST /api/v1/cloud/files — 上傳文本類檔案內容。
掛載到 Session
POST /api/v1/cloud/sessions/{session_id}/resources — 把已上傳檔案掛載到 Session。
Agent 使用
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 對文本類檔案（代碼、配置、文檔）的理解效果最佳。