跳至主要内容

REFERENCE

SDK 範例

@asgard-js/core 與 @asgard-js/react 的用法與可以直接操作的範例。

Sandbox 冷啟動 HUD

當 agent 需要一個 sandbox 才能繼續時，後端會在串流上送出 sandbox.launch / sandbox.ready 事件。core 把它們收斂成 sandboxPhase，SDK 則在 chat view 右下角浮出一個 獨立的「Sandbox 啟動中」HUD，ready 之後播一段收尾拍再淡出。

這是自動的——整合方不需要接任何線。

  1. 那道 1 秒門檻​

    熱啟動常常 100–300ms 就 ready。這種時候閃一下動畫只是雜訊，所以 phase 必須持續 launching 超過門檻（預設 1000ms）才會顯示 HUD；門檻內完成的啟動全程靜音。

    反過來，ready 抵達時 HUD 不會瞬間消失：它會停留一段 ready 拍（預設 900ms）讓使用者看到 「好了」，再淡出。若 ready 在門檻前就到（HUD 從未顯示），整段就保持安靜。

    phase:  idle ──► launching ─────────────────► ready ──► idle
                     │◄── 1000ms ──►│
    stage:  hidden   hidden          launching     ready ──► leaving ──► hidden
                                     （動畫）      （收尾拍）（淡出）

  2. sandboxPhase​

    type SandboxPhase = "idle" | "launching" | "ready";

    從 Channel 取得，可以訂閱也可以快照：

    channel.sandboxPhase$.subscribe((phase) => { /* … */ });
    const phase = channel.getSandboxPhase();

  3. 自己畫啟動提示​

    要換掉內建 HUD 的話，useSandboxLaunch 把 phase 轉成顯示用的 stage：

    import { useSandboxLaunch } from "@asgard-js/react";
     
    const { stage, visible } = useSandboxLaunch(phase, {
      thresholdMs: 1000, // 低於此時間完成的啟動不顯示
      readyBeatMs: 900,  // ready 後停留多久再開始淡出
      exitMs: 600,       // 淡出時間，需與你的 CSS 一致
    });
     
    // stage: 'hidden' | 'launching' | 'ready' | 'leaving'
    // visible: stage !== 'hidden' 的便利旗標

    所有計時器都會在 unmount 或 phase 變動時清掉。

  4. 與連線指示器互相獨立​

    footer 上緣的連線進度線（RunningIndicator）綁的是整個 run 的連線；HUD 只管 「sandbox 是不是卡在冷啟動」。兩者可以同時出現，互不干擾。

  5. 已啟動的 sandbox 清單​

    launchedSandboxes$ 帶出每個 sandbox 的識別與能力：

    interface LaunchedSandbox {
      sandboxName: string;          // 權威識別碼；所有 fs / browser API 都用它定位
      sandboxBlueprintName: string; // 建立它的藍圖名稱，通常比 sandboxName 好讀
      workingDirectory: string;     // File Explorer 的樹根
      editorServerEnabled: boolean;
      browserEnabled: boolean;      // 是否啟用瀏覽器（決定交接卡能不能用）
    }
    它和 sandboxPhase 不同源

    sandboxPhase 是直接從 SSE 事件收斂的；launchedSandboxes$ 不是。這份清單的唯一權威來源是 GET /channel/metadata，SSE 事件從不直接寫進去。asgard.sandbox.launch 只是一個提示——它把 名字記進待確認清單並觸發一次 metadata 重抓，由回來的結果決定誰還活著。

    所以不要拿 sandbox.launch 事件自己推斷「現在有哪些 sandbox」，那會和後端的權威狀態分岔。

    File Explorer 的 sandbox 下拉選單吃的就是這份清單。

  6. 也看看​

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們