Spaces CLI 為人類與代理設計

TL;DR

Mistral AI 發布了 Spaces，一個命令列介面，讓開發者僅需三條指令即可建立、執行和部署多服務專案，且其設計確保每個互動式提示都有對應的旗標或設定選項，使自主 AI 代理能無需手動介入地使用此工具。

什麼構成了良好的開發者體驗

Spaces 重點在於消除重複的設定工作。它選擇合理的目錄結構，自動產生設定檔，並自動串接服務，使得在執行以下指令後，新專案即可立即執行，並支援熱重載、資料庫與 Dockerfile：

$ spaces init my-project
$ cd my-project
$ spaces dev

CLI 將命令分為三個功能區塊：

  • 結構建立 – 建立專案結構，提問並顯示選項。
  • 開發 – 使用單一 spaces dev 指令執行內部開發循環。
  • 操作 – 執行需要明確確認的生產級操作。

為第二使用者設計：AI 代理

當 AI 程式碼代理嘗試使用 init 的互動式 TUI 選取器時，遇到了原始的 ANSI 逸出碼，無法導航介面。簡單的解決方案是公開 --components 旗標，但更深層的洞見是 CLI 所請求的每一項資訊都應有非互動式的表示方式。

旗標作為通用合約

每個互動式提問都代表一種合約：CLI 需要一個值才能繼續。透過提供旗標、設定檔或預設值，無論輸入如何到達，相同的業務邏輯都能執行。範例實作：

def init_command(
    components: str | None = Option(None),
    yes: bool = Option(False, "-y"),
):
    if components:
        selected = components.split(",")
    elif yes:
        selected = get_defaults()
    else:
        selected = show_picker()
    create_project(selected)

-y 旗標表示呼叫者以程式化方式提供所有必要資料，若缺少任何必要輸入，CLI 會明確失敗，而非掛起在 stdin 上。

端到端代理工作流程

現在代理可以：

  1. 執行 spaces --help 以發現命令簽名。
  2. 自動產生 config.yaml 和 context.json。
  3. 在無需人工介入的情況下串接 Dockerfiles、註冊表設定與 CI 管道。
  4. 在不到十分鐘內將倉儲部署為 Koyeb 上的 Space。

由於每個互動式提示都有旗標對應，代理能從開始到部署全程自主運作。

結構化資料作為介面層

Spaces 使用外掛系統，每個模組由資料模型描述，而非硬編碼邏輯：

class ModulePlugin(BaseModel):
    type_id: str
    category: str
    default_port: int
    def get_env_vars(self) -> list[EnvVarDef]: ...
    def get_dev_command(self, port: int) -> str: ...

外掛可檢視、序列化為 JSON，並可進行差異比對。人類透過 TUI 選取器互動，而代理則查詢註冊表並接收 JSON。新增模組現在僅需新增一個外掛類別，消除了在選取器、Dockerfile 產生器與 compose 模板之間重複更新的問題。

為代理提供上下文

Spaces 在每次 init 時會產生兩個檔案：

  • context.json – 專案模組、通訊埠、指令與環境變數的快照。
  • AGENTS.md – 給 LLM 的明確程序指示，例如「在測試資料庫變更前執行 mycli dev --migrate」。

這些資產為代理提供可靠的真相來源，減少猜測並防止錯誤，例如使用錯誤通訊埠或安裝重複的相依性。上下文檔案也作為快取清除器；只要專案設定變更，它就會自動更新。

消除隱含狀態

隱含假設（例如依賴目前工作目錄）會破壞代理自動化。解決方案是將所有狀態明確化，並提供合理的預設值：

# 之前
config = load_config(Path.cwd() / "config.yaml")
# 之後
config = load_config(
    path or find_config_in_parents(Path.cwd())
)

將 CWD、環境變數與隱藏檔位置明確化，同時提升了代理的可靠性與人類撰寫指令碼的品質。

代理友善實踐清單

  • 每個互動式輸入都有對應的旗標。
  • 旗標為無頭執行提供智慧預設值。
  • 所有狀態（路徑、環境變數、設定）皆明確傳遞。
  • 外掛為純資料模型，可自動檢視。
  • context.json 與 AGENTS.md 為代理提供結構化的專案描述。

為何這能改善所有人的工具

新增的代理導向設計 不會 壞壞人類體驗：TUI 選取器、旋轉圖示與確認對話框均保持不變。相反地，代理所需的約束條件（明確輸入、旗標合約、結構化元資料）也讓 CLI 對開發者更具可組合性、可腳本化與可測試性。

Mistral AI 建議任何開發者工具的創造者應審查每個 input() 呼叫、CWD 假設與僅人類可讀的輸出，並問自己：非人類流程是否也能使用相同介面？回答這些問題將使工具對人類與代理都更穩健。

Spaces CLI 由 Mistral AI 的 Lorenzo Signoretti、Riwa Hoteit 與 Sam Fenwick 建立，並獲得 Applied AI 團隊的反饋。

Sources