環境

AI 代理修改 Web 應用時，成果往往是一個能開啟的東西：開發伺服器、預覽頁、桌面 App。任務側欄的環境區域列出這條任務的執行啟動了哪些仍在執行的服務，按所在的機器分組，每個都可以直接開啟。

環境有兩種來源：

自動識別讓這個區域不用設定就能用；宣告則讓環境可以重複啟動：每次執行都用同樣的方式、在自己的埠上啟動，日誌也能在側欄裡看到。

自動識別的服務Copy Anchor Link

在 macOS 和 Linux 上，守護程序大約每 30 秒檢查一次哪些程序在監聽 TCP 埠。一個程序滿足下面兩個條件時，會出現在側欄裡：

• 它的工作目錄在這條任務某次執行的目錄裡；
• 連續兩次掃描都發現了它。這樣一閃而過的測試伺服器不會被列進來。

以下不會被列進來：

• AI 程式設計工具本身，以及 multica CLI；
• 從專案自己的本機目錄執行的服務，那是你自己啟動的，不屬於某次執行；
• 已經屬於某個宣告式環境的服務，它們只在那個環境下面列一次；
• 不在任務上的執行（例如聊天工作階段）啟動的服務。

桌面 App（例如 Electron 應用）只作為一個 App 列出，不會按埠列成好幾條。它沒有 URL；在同一台機器上的 Multica Desktop 裡，點切到視窗就能把它切到前景。它的遠端偵錯埠不會作為連結顯示。

自動識別的服務在執行結束後仍會顯示，直到它不再監聽埠。成員可以在側欄裡停止它，但守護程序不知道它是怎麼啟動的，所以沒有日誌，也不能重新啟動。需要這些功能，就把它宣告出來。

宣告環境Copy Anchor Link

在倉庫根目錄加入 .multica/environments.toml，並提交到執行會檢出的分支上。側欄只在檢出程式碼的根目錄或下一層目錄裡尋找這個檔案，檔案有錯誤時會略過；multica env start 會回報具體哪裡有問題。每個 [environments.<name>] 表是一個環境：

[environments.web]
label = "Web app"
start = "npm ci && npx vite --port $MULTICA_PORT --strictPort"
ttl = "24h"

AI 代理在自己檢出的程式碼目錄裡啟動它：

multica env start web

命令會等環境能回應後印出它的 URL。環境出現在側欄裡，執行結束後繼續執行，TTL 到期時自動停止。

欄位Copy Anchor Link

環境名稱是 environments. 後面的部分：只能用小寫字母、數字、- 和 _，以字母或數字開頭，最多 40 個字元。

埠和變數Copy Anchor Link

每個環境分到十個自己專用的空閒埠：MULTICA_PORT 到 MULTICA_PORT+9。同一台機器上的兩次執行、兩條任務都不會衝突，所以不要寫死埠。

start 和 stop 能取得這些變數：

它們還會繼承守護程序的環境變數，但不包括 MULTICA_* 變數（憑據也在其中）：環境不能以這次執行的身分操作。url 和 ready 裡只會替換 $MULTICA_PORT（或 ${MULTICA_PORT}）。需要第二個埠時，在 shell 裡計算，例如 API_PORT=$((MULTICA_PORT + 1))。

讓 start 留在前景Copy Anchor Link

start 作為一個新程序群組的組長執行。只要群組裡還有程序，環境就一直存在；停止環境時會向整個程序群組發送訊號。所以：

• 讓主服務留在前景。用 & 放到背景的輔助程序沒問題，它們仍在這個程序群組裡。
• 不要把工作交給程序群組以外的東西，例如 docker compose up -d、系統服務或 setsid。那樣環境會立刻變成已退出，停止時也碰不到那些工作。這類工具要在前景執行，並配一個 stop 命令。
• 執行檢出的程式碼裡還沒有安裝相依套件。在 start 裡安裝；守護程序等待就緒的十分鐘包含安裝時間。

範例Copy Anchor Link

每個範例都是一份完整的 .multica/environments.toml。把 npm ci 換成倉庫所用套件管理器的安裝命令（pnpm install --frozen-lockfile、yarn install --immutable）。

[environments.web]
label = "Web app"
start = "npm ci && npx next dev --port $MULTICA_PORT"
ttl = "24h"

要宣告多個環境，在同一個檔案裡多寫幾個表即可。每個環境的程序都隨它一起停止，即使同一份程式碼啟動的另一個環境還在呼叫它們。需要一起保持執行的服務（例如 Web 應用和它的 API）應放在同一個環境裡，參考 Web + API 範例。

用 CLI 啟動和停止Copy Anchor Link

三個命令都支援 --output json。multica environment 是 multica env 的完整寫法。

啟動命令在就緒前就退出時，multica env start 會失敗，並印出日誌的最後幾行。10 分鐘後仍未回應時，命令會回傳，環境保持啟動中，並附上原因（例如 "not answering at http://localhost:41000"）。

環境屬於任務，而不是某一次執行：同一條任務上後來的執行可以列出並停止之前執行啟動的環境。再次啟動同名環境時，只有它在本機從同一份程式碼執行，才會重用正在執行的那個。用另一份程式碼的執行會以同樣的名字另起一份，使用自己的埠，所以啟動前先用 multica env list 看一下。

在側欄裡管理環境Copy Anchor Link

每個環境顯示狀態、啟動或結束的時間、到期時間和啟動者。開啟會開啟它的 URL，複製位址會複製 URL。已經結束的環境收在"N 個已結束"裡。

• 啟動：點擊環境旁邊的 +。選單列出每台機器上最近一次執行宣告的環境，選中後用那次執行的程式碼啟動。這條任務還沒執行過、或者那份程式碼已被清理時，選單會改為讓 AI 代理來啟動：AI 代理準備好程式碼後執行 multica env start；專案裡沒有宣告時，它會自己判斷怎麼啟動。
• 停止、重新啟動、查看日誌：開啟環境的更多操作選單。重新啟動會重新讀取程式碼裡的宣告，所以那份程式碼和其中的 .multica/environments.toml 必須還在。自動識別的服務只有停止，並且需要確認。

啟動、停止和重新啟動需要工作區成員能存取這條任務，並且能使用那台機器的執行時（參見守護程序與執行時）。機器必須在線上，且上面的 Multica 版本支援環境操作；否則按鈕會說明缺了什麼。查看日誌只需要能存取這條任務。

日誌Copy Anchor Link

查看日誌顯示宣告式環境輸出的最後 500 行，最多 256 KiB。環境執行時，大約每五秒跟隨一次新輸出；可以暫停跟隨、重新整理、篩選、自動換行和複製。

環境當機時，它最後兩行輸出會和環境一起儲存，所以即使機器離線，側欄也能顯示它為什麼退出。重新讀取日誌需要機器在線上。

完整日誌留在那台機器上，位於 <workspaces root>/.environments/v1/，環境結束後保留七天。multica env start 和 multica env list 會印出它的路徑。

狀態Copy Anchor Link

守護程序停止期間不會託管任何環境；它重新啟動後，程序仍然存活的環境會被重新接管。有環境在執行的執行目錄，在環境停止前不會被守護程序的工作區清理刪除。

讓 AI 代理來寫這個檔案Copy Anchor Link

AI 代理知道這個格式：每個 AI 代理都會收到 Multica 內建的平台技能，其中說明了 .multica/environments.toml 的寫法和驗證方法。可以直接在任務裡提，例如：

給這個倉庫加一個 .multica/environments.toml，讓 Web 應用可以用 multica env start 啟動。先啟動一次確認能用，再提 PR。

AI 代理會先弄清專案怎麼啟動，用 MULTICA_PORT 寫好埠，啟動環境確認能回應，然後像其他改動一樣提交。合併之後，後續每次執行都能啟動這個環境，成員也能在側欄裡啟動。

已知限制Copy Anchor Link

• 只支援 macOS 和 Linux。 在 Windows 上不會識別服務，multica env start 會提示暫不支援。
• localhost 位址只能在執行它的機器上開啟。 環境執行在另一台機器上（例如建置機或同事的電腦）時，側欄會註明；請在那台機器上開啟，或者自己轉發埠。
• systemd 下重新啟動守護程序。 在 Linux 上開啟了開機自啟時，重新啟動或更新守護程序會同時停止它託管的宣告式環境，之後需要重新啟動。
• 一個環境只在一台機器上。 環境執行在啟動它的那次執行所在的機器上，不會隨任務遷移。

接下來Copy Anchor Link

• 守護程序與執行時 — 識別和託管環境的守護程序。
• 使用 CLI — multica env 命令和 CLI 的其他命令。
• 執行 — 執行的目錄從哪裡來。