啟動 Session - AI Coding Assistant Lingma

Session 是 Qoder Cloud Agents 中實際執行任務的單元。它將 Agent（配置）和 Environment（基礎設施）組合在一起，形成一個有狀態的工作會話。你向 Session 發送訊息，它處理後返回事件流。

Session 生命週期

建立 → idle
新 Session 進入 idle，等待輸入。
idle → processing
發送 user.message 事件後，狀態切換到 processing。
processing → idle
本輪完成後回到 idle，可繼續下一輪。
processing → canceling → idle
取消正在執行的 Session 後，狀態先經過 canceling，再回到 idle，Session 仍可繼續使用。
archived（終態）
歸檔是終態，Session 不再可恢複。

Session 是一個狀態機器，核心狀態如下：

狀態	說明	可流轉到
`idle`	空閑，等待使用者訊息	`processing`
`processing`	正在處理，Agent 執行中	`canceling`, `idle`
`canceling`	取消指令已發出，等待中斷完成	`idle`
`archived`	已歸檔	— (終態)

欄位說明

欄位	類型	說明
`id`	string	系統產生，`sess_` 首碼
`type`	string	固定為 `"session"`
`agent`	string/object	綁定的 Agent（字串=最新版本，對象 `{id,version}`=鎖版本）。建立請求只接受此欄位。響應始終返回完整的 Agent 對象快照
`agent_id`	string	僅在響應中返回，等於綁定的 Agent ID；為向後相容保留
`environment_id`	string	綁定的 Environment ID
`status`	string	目前狀態：`idle` / `processing` / `canceling`
`turn_status`	string	當前輪次狀態：`idle` / `running` / `canceling`
`title`	string	會話標題，預設 `""`
`memory_store_ids`	array	關聯的 Memory Store ID 列表，預設 `[]`
`vault_ids`	array	關聯的 Vault ID 列表，預設 `[]`
`resources`	array	附加到 Session 的資源（檔案等），預設 `[]`
`created_at`	string	建立時間
`updated_at`	string	最後更新時間

Token 用量資料（usage）不在 REST 介面響應中返回——它僅出現在每輪結束的 SSE session.status_idle 事件中。

建立 Session

建立 Session 時需要指定 agent 和 environment_id：

方式一：使用 Agent ID（字串）

綁定該 Agent 的最新版本：

# 使用 Agent ID 建立 Session
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_019e5ce0bf307a1a8f952eb814aea3d5",
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

方式二：使用 Agent 對象（指定版本）

綁定 Agent 的特定版本，確保行為一致性：

# 指定 Agent 版本建立 Session
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": {
      "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "version": 2
    },
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

成功返回 201 Created：

{
  "id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "agent": {
    "created_at": "2026-05-18T10:00:00Z",
    "default_environment": "",
    "description": "",
    "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
    "instructions": "你是代碼審查專家。",
    "mcp_servers": [],
    "model": "ultimate",
    "name": "code-reviewer",
    "system": "你是代碼審查專家。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "type": "agent",
    "updated_at": "2026-05-18T10:00:00Z",
    "version": 2
  },
  "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": "",
  "turn_status": "idle",
  "memory_store_ids": [],
  "resources": [],
  "vault_ids": [],
  "type": "session",
  "created_at": "2026-05-18T12:00:00Z",
  "updated_at": "2026-05-18T12:00:00Z"
}

在生產環境中建議使用方式二（指定版本），避免因 Agent 更新導致行為變化。

agent 欄位格式

格式	樣本	行為
字串	`"agent_019e5ce0bf307a1a8f952eb814aea3d5"`	使用該 Agent 最新版本
對象	`{"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5", "version": 2}`	鎖定到指定版本

狀態流轉

事件請求體格式

POST /sessions/{id}/events 的請求體必須使用 events 數組封裝，content 是內容塊數組：

欄位	類型	必填	說明
`events`	array	是	事件數目組，單次請求可包含一個或多個事件
`events[].type`	string	是	事件類型，如 `user.message`
`events[].content`	array	是	內容塊數組
`events[].content[].type`	string	是	內容塊類型，如 `text`
`events[].content[].text`	string	是	常值內容

idle → processing

當你向 Session 發送 user.message 事件時，狀態從 idle 變為 processing：

# 發送訊息觸發處理
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "user.message",
      "content": [{"type": "text", "text": "分析目前的目錄下所有 Python 檔案的代碼複雜度。"}]
    }]
  }' | jq .

processing → idle

Agent 完成處理後自動回到 idle，通過事件流會收到 session.status_idle 事件。

取消 Session

中斷正在執行的 Session：

# 取消 Session
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/cancel" \
  -H "Authorization: Bearer $QODER_PAT"

僅在 processing 狀態下 cancel 才有實際中斷效果：狀態先變為 canceling，中斷完成後回到 idle，Session 可繼續複用——直接發送下一條 user.message 即可。對已處於 idle 的 Session 調用 cancel 是空操作，同樣返回 200，不會報錯，狀態保持 idle 不變。

查詢 Session

# 擷取單個 Session 詳情
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522" \
  -H "Authorization: Bearer $QODER_PAT"

# 列出所有 Session（支援分頁）
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

分頁響應：

{
  "data": [
    {
      "id": "sess_019e5ce0bf9074b69c3481e93771a522",
      "type": "session",
      "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "status": "idle",
      "turn_status": "idle",
      "title": "",
      "memory_store_ids": [],
      "vault_ids": [],
      "resources": [],
      "created_at": "2026-05-18T12:00:00Z",
      "updated_at": "2026-05-18T12:30:00Z"
    }
  ],
  "first_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "last_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "has_more": false
}

Usage 統計

每輪的 token 用量不通過 REST 介面返回。要查看用量，請監聽每輪結束的 SSE session.status_idle 事件，其 usage 欄位攜帶累計計數：

欄位	說明
`usage.input_tokens`	本輪消耗的輸入 token 數
`usage.output_tokens`	本輪產生的輸出 token 數
`usage.cache_read_input_tokens`	命中緩衝的輸入 token 數
`usage.cache_creation_input_tokens`	寫入緩衝的輸入 token 數

SSE 事件中的樣本 payload：

{
  "type": "session.status_idle",
  "usage": {
    "input_tokens": 3840,
    "output_tokens": 2156,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

Session 與 Agent 版本綁定

Session 建立時會快照 Agent 的配置：

使用字串形式 "agent": "agent_xxx" 綁定建立時刻的最新版本
使用對象形式 "agent": {"id": "agent_xxx", "version": N} 綁定精確版本
Session 建立後，修改 Agent 不會影響已存在的 Session
想要使用新版 Agent，需要建立新的 Session

Session A — 綁定 Agent v1

在更新前建立。即使 Agent 後續更新到 v2，Session A 仍然繼續使用 v1 配置。

Session B — 綁定 Agent v2

在更新後建立，使用新的 v2 配置。

多輪對話

Session 支援多輪對話。每次發送訊息後等待 session.status_idle，然後繼續發送：

#!/bin/bash
# 多輪對話樣本
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
SESSION_ID="sess_019e5ce0bf9074b69c3481e93771a522"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

# 第一輪：提出需求
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "建立一個 Python Flask 專案腳手架。"}]}]}'

# 等待處理完成...（輪詢或監聽 SSE）
sleep 30

# 第二輪：追加要求
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "給專案添加單元測試和 CI 配置。"}]}]}'

狀態相關錯誤碼

向 Session 發送事件時，常見的狀態相關錯誤：

HTTP	type	觸發條件
409	`conflict_error`	向 `processing` 狀態的 Session 發訊息（需先 cancel 當前輪或等待 `idle`）
404	`not_found_error`	Session 不存在或已被刪除

409 錯誤響應樣本：

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Session is currently processing a turn. Cancel the current turn or wait for completion."
  }
}

最佳實務

版本鎖定 — 生產環境始終使用 {"id": ..., "version": ...} 形式建立 Session
及時取消 — 不再需要的 Session 及時 cancel，釋放資源
監控用量 — 定期檢查 usage 欄位，避免意外消耗
中繼資料標記 — 用 metadata 記錄業務上下文（任務 ID、觸發來源等）

常見問題

Q: Session 有逾時機制嗎？

A: Session 在 idle 狀態下會保持一段時間。長時間不活躍的 Session 可能被系統自動歸檔。建議按需建立，任務完成後主動 cancel。

Q: 向 processing 狀態的 Session 發訊息會怎樣？

A: 會返回 HTTP 409 conflict_error，錯誤資訊為 Session is currently processing a turn. Cancel the current turn or wait for completion.。需要先取消當前輪（cancel）或等待 Session 回到 idle，再發送新訊息。

Q: 一個 Session 最多支援多少輪對話？

A: 沒有硬性輪次限制，但受模型上下文視窗大小約束。隨著對話增長，早期內容可能被截斷。

Q: 如何擷取 Session 的完整對話歷史？

A: 通過 GET /sessions/{id}/events 擷取該 Session 的所有事件，包括使用者訊息和 Agent 響應。

Q: 取消後的 Session 還能繼續用嗎？

A: 可以。cancel 後狀態從 canceling 自動回到 idle，Session 保持可用——直接發送下一條 user.message 即可繼續對話。僅 archived 是終態，歸檔後無法恢複。