雲端環境 - AI Coding Assistant Lingma

Environment 定義了 Session 啟動並執行容器模板——作業系統、網路原則、預裝依賴。你可以為不同情境建立不同的環境：嚴格隔離的安全審計環境、預裝資料科學庫的分析環境、或者開放網路的通用開發環境。

環境是什麼

Environment 是 Session 的基礎設施層：

容器類型 — 目前支援 cloud（雲端託管容器）
網路原則 — 控制容器的出站網路訪問
依賴包 — 預裝系統包、Python 包、Node.js 包

每個 Session 啟動時會基於指定的 Environment 模板建立隔離的運行執行個體。

欄位說明

欄位	類型	必填	說明
`id`	string	—	系統產生，`env_` 首碼
`type`	string	—	固定為 `"environment"`
`name`	string	是	環境名稱
`description`	string	否	描述資訊，預設 `""`
`config`	object	是	環境配置（類型、網路、包）
`config.type`	string	是	容器類型，當前固定為 `"cloud"`
`config.networking`	object	否	網路原則；必須為對象，可選值為 `{"type": "unrestricted" \| "limited" \| "allowed_hosts"}`
`config.packages`	object	否	預裝依賴包配置
`status`	string	—	環境狀態：`ready`
`archived`	boolean	—	是否已歸檔，預設 `false`
`archived_at`	string\|null	—	歸檔時間（ISO 8601），未歸檔時為 `null`
`created_at`	string	—	建立時間
`updated_at`	string	—	最後更新時間

網路原則

config.networking 支援三種模式，所有模式都必須使用對象格式（字串簡寫如 "unrestricted" 不被支援，會返回 400）。

模式	值	說明
完全開放	`{"type": "unrestricted"}`	容器可以訪問任意外部地址
受限	`{"type": "limited", "allow_package_managers": true}`	僅允許訪問已知安全的公用服務和包管理器
白名單	`{"type": "allowed_hosts", "allowed_hosts": [...]}`	僅允許訪問指定主機名稱

`networking` 對象欄位

欄位	類型	說明
`networking.type`	string	網路原則類型：`unrestricted` / `limited` / `allowed_hosts`
`networking.allow_package_managers`	boolean	`limited` 模式下是否允許包管理器（pip / npm / apt 等）訪問
`networking.allowed_hosts`	array	`allowed_hosts` 模式下允許的主機名稱列表

完全開放

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}

適用於需要下載依賴、訪問外部 API 的通用開發工作單位。

受限模式

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allow_package_managers": true
    }
  }
}

適用於不需要任意外網訪問、但仍需通過包管理器拉依賴的任務。

白名單模式

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "allowed_hosts",
      "allowed_hosts": [
        "api.github.com",
        "registry.npmjs.org",
        "pypi.org"
      ]
    }
  }
}

適用於安全合規要求高的情境，精確控制可訪問的外部服務。

預裝依賴

通過 config.packages 指定容器啟動時預裝的依賴：

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["git", "build-essential", "libssl-dev"],
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["typescript", "eslint", "prettier"]
    }
  }
}

包管理器	欄位	說明
apt	`packages.apt`	Debian/Ubuntu 系統包
pip	`packages.pip`	Python 包
npm	`packages.npm`	Node.js 包（全域安裝）

預裝依賴會增加環境初始化時間。只添加確實需要的包，其餘可在 Session 運行時按需安裝。

建立環境

# 建立一個資料科學專用環境
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
      }
    }
  }' | jq .

成功返回 201 Created：

{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "data-science",
  "description": "",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["build-essential"],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "status": "ready",
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

建立安全受限環境

# 建立一個僅允許訪問內部 API 的安全環境
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secure-internal",
    "config": {
      "type": "cloud",
      "networking": {
        "type": "allowed_hosts",
        "allowed_hosts": ["internal-api.mycompany.com", "git.mycompany.com"]
      },
      "packages": {
        "apt": ["git", "curl"]
      }
    }
  }' | jq .

查詢環境

# 列出所有環境
curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"

# 擷取單個環境詳情
curl -s https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

更新環境

# 為已有環境添加新的依賴包
curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential", "libpq-dev"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter", "sqlalchemy"]
      }
    }
  }' | jq .

更新環境不會影響已啟動並執行 Session。新配置僅對後續建立的 Session 生效。

刪除環境

# 刪除自訂環境
curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

當 environment 仍被未歸檔的 session 引用時，DELETE 返回 409 "Environment is in use and cannot be deleted"。需要先歸檔/刪除引用方 session，或改用 POST /environments/{id}/archive 軟刪（無參考條件約束）。

環境選型建議

情境	推薦配置
通用開發	`default` 環境，無需額外配置
資料分析	預裝 pandas/numpy，開放網路
安全審計	白名單網路，最小依賴
前端開發	預裝 Node.js 生態工具，開放 npm registry
CI/CD 整合	預裝 git/docker CLI，白名單模式

常見問題

Q: 環境建立後需要等待多久才能使用？A: 環境建立後狀態直接為 ready，可立即用於建立 Session。實際的容器初始化（包括安裝依賴）發生在 Session 啟動時。Q: 預裝包的版本可以指定嗎？A: pip 和 npm 包支援版本指定，如 "pandas==2.1.0" 或 "typescript@5.0.0"。apt 包使用系統源的預設版本。Q: networking 設定錯誤導致 Agent 運行失敗怎麼辦？A: 建立一個新的環境（或更新現有環境），修改網路原則後重新啟動 Session。Q: 一個帳號最多能建立多少個環境？A: 無硬性限制，但建議按實際需求建立，避免管理混亂。建議通過命名規範分類。