通用資料結構 - Qoder CN 系列

Cloud Agents API 多個資源共用的響應信封與基礎對象。

Metadata 對象

metadata 是調用方自訂的扁平字串索引值對象。

規則	說明
結構	JSON object，所有 value 都必須是 string
最大鍵數量	16
key 最大長度	64 個 Unicode 字元
value 最大長度	512 個 Unicode 字元
預設值	省略時為 `{}`

樣本：

{
  "team": "docs",
  "project": "cloud-agents"
}

分頁列表

列表介面返回統一的遊標分頁信封。

欄位	類型	說明
`data`	array	當前頁的資來源物件數組
`has_more`	boolean	是否還有更多資料
`first_id`	string \| null	當前頁第一條記錄的遊標 ID；`data` 為空白時為 `null`
`last_id`	string \| null	當前頁最後一條記錄的遊標 ID；`data` 為空白時為 `null`

錯誤信封

錯誤響應使用以下結構：

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'name' is required."
  }
}

欄位	類型	說明
`type`	string	固定為 `"error"`
`error.type`	string	錯誤類別，如 `invalid_request_error`、`authentication_error`、`permission_error`、`not_found_error`、`conflict_error`、`api_error`
`error.message`	string	人類可讀的錯誤資訊

時間戳記

時間欄位是 UTC 的 ISO 8601 / RFC 3339 字串，例如 "2026-05-18T15:26:39.61669Z"。部分欄位可以為 null，具體以各資源結構說明為準。

ID 首碼

資源	首碼
Agent	`agent_`
Environment	`env_`
Session	`sess_`
Session event	`evt_`
Session thread	`sthr_`
Turn	`turn_`
File	`file_`
Vault	`vault_`
Vault credential	`vcred_`
Skill	`skill_`
Memory store	`memstore_`
Memory entry	`mem_`
Memory version	`memver_`
Forward template	`tmpl_`
Forward identity	`idn_`
Forward identity config	`cfg_`
Forward channel	`channel_`
Forward QR session	`qr_`
Forward schedule	`sched_`
Forward schedule run	`srun_`
Work item	`work_`
Forward resource	複用登入資源自身 ID 首碼