核心概念

一個真實範例：

一個好的 goal 應該是：

• 具體：指明要用哪些輸入以及如何使用它們。
• 關注輸出：指明產物 ID 與格式。
• 可執行：使用祈使動詞（"研究"、"撰寫"、"分析"）。
• 結構化：一個帶編號小節的 10 行 goal 幾乎總是優於 2 行的版本。

AppArtifactDef：每個階段的產出

支援七種格式：

所有產物都存放在 S3（如果你是自架則放在 R2）中，位置為 app_artifact.s3_key，並記錄 MIME 類型與位元組大小。它們會在應用的整個生命週期中保留；刪除的應用封存在 30 天內仍可復原。

Resources：應用所需的技能與連接

技能是 agent 可以調用的能力模組（網頁搜尋、PDF 擷取、圖像生成），詳見 技能。連接是應用所需的 OAuth 橋樑。Aitroop 以兩層分類來組織連接：

• type: "specific"：以 connect_definition.id 鎖定單一提供方（例如 github、hubspot、gmail）。僅適配某一種整合時使用。
• type: "category"：接受 connect_category 內的任一提供方（例如 email、storage、crm）。只要使用者授權了該類別下的至少一個提供方，應用就視為滿足。當應用與具體提供方無關時（"任意信箱"、"任意 CRM"）使用。

舊的形式 "connects": ["hubspot", "github"] 仍然可用，應用執行時每個字串都會被視為 { type: "specific", id: «string», is_required: true }。應用建構器在新建應用時會寫入更豐富的形式。

資源可以在應用級宣告（如上），也可以按階段宣告（在 stage.skills / stage.connects 下）。按階段範圍化是讓多階段應用更安全的方式，給階段 1 只配置 web-search，給階段 2 只配置 CRM 連接，以此類推。請見 連接 了解完整的提供方目錄與滿足模型。

執行記錄：應用真正執行的時刻

一次執行記錄是一次走完應用所有階段的過程。它就是那個帶有狀態、階段日誌、耗時和最終產物集合的實體。

執行中的每個階段都會有自己的 app_stage_log 列，包含狀態、耗時、session ID（可據此開啟為對話）、展開後的 goal 以及任何錯誤。

兩個層級的狀態列舉並不一致：

當一個 human 階段在等待時，階段日誌會進入 waiting；父執行仍維持 running。當執行帶 start_from_stage_index > 0 恢復時，它們也會進入 skipped：較早的階段不會重新執行。請見 執行記錄 了解完整生命週期、除錯流程與 SSE 串流。

沙盒：agent 實際工作的地方

每一次對話和每一個應用階段都執行在一個沙盒中：一個隔離的執行環境，擁有自己的檔案系統、自己的行程和對外網路。agent 可以 pip install、執行 shell 指令、寫入檔案、抓取 URL，執行結束時，沙盒會被銷毀。

統一在 ISandbox 介面下提供三種後端，再由一個路由器在它們之間挑選：

• host：直接在 Aitroop 伺服器行程中執行。僅用於自架開發環境；DATABASE_URL、JWT_SECRET、E2B_API_KEY 與 S3 憑證等敏感變數會從子行程環境中剝離。
• e2b：來自 E2B 的 Firecracker 微型虛擬機。Aitroop 託管版的預設選項。
• daytona：來自 Daytona 的託管開發容器。適合重負載 / 長時間階段。
• router：按使用者分派到上述三者之一的選擇器（用於把特權使用者路由到 host）。

無論使用哪個提供方，每個沙盒都暴露相同的目錄佈局，根目錄是沙盒使用者的 home 目錄：

同一次執行中的所有階段共享同一個沙盒，所以階段 2 可以讀取階段 1 寫入的內容。不同的執行使用不同的沙盒，不會跨執行洩漏。實務上你會遇到的常數：SANDBOX_IDLE_TIMEOUT_MS = 5 分鐘、SANDBOX_KEEPALIVE_INTERVAL_MS = 30 秒，以及上限 AGENT_RUN_TIMEOUT_MS = 7 天。請見 沙盒 了解完整的運行模型。

多階段應用

當一個工作流程天然有彼此銜接的步驟時，就定義多個階段。各階段按順序執行。每個階段在兩個地方都能看到前序階段的產物，但都不透過 goal 範本：

1. 共享的沙盒檔案系統。一次執行中的所有階段都在同一個沙盒中執行（沙盒）。階段 1 寫入的檔案，階段 2 仍然可以讀到。
2. system prompt 中自動注入的 ## Previous Stage Outputs 區塊。在階段 N 執行之前，執行器會載入階段 0..N-1 產生的所有產物，把每個產物渲染為 ### {{title}}\n{{content}}，並將這一段拼接到 system prompt 之前。agent 把它們當作一般上下文閱讀，不需要在 goal 中手動引用。

注意兩個 agent 階段之間夾著一個 human 階段，這就是人在迴圈（human-in-the-loop）模式。執行在此處暫停，平台會在 app_human_gate 中建立一列，狀態為 pending，階段日誌切換為 waiting。只有當 gate 被設為 approved 時下一個階段才會執行（設為 rejected 時則維持暫停）。

會話與訊息佇列

所有與 agent 的對話，無論是自由聊天、應用階段，還是排程任務的一次觸發，都發生在一個會話中。一個會話是一個穩定的容器，擁有自己的 Claude 對話 ID、自己的有序訊息日誌，以及自己的狀態追蹤佇列。在 app_session.session_type 中持久化有三種形態：

在每個會話中，每一次使用者回合都是 app_message 中的一列。這些列不是「發完就忘」，它們要走一個小型狀態機，因為 agent worker 池可能是多實例的，同一個會話必須串列化它的分派：

app_message 上重要的欄位：

• position：每個會話內的整數，單調遞增。決定相同優先級列之間的順序。DAO 在插入列時原子地分配此值。
• priority：64 位元排序鍵。優先級越高越先分派；預設為實際時鐘時間，所以兩條沒有明確優先級的訊息按到達順序執行。
• attempts：每次嘗試分派時遞增。5 次失敗後，列進入 failed，使用者可見訊息顯示錯誤。
• dispatched_at：worker 認領該列時設定；與 15 分鐘過期閾值搭配驅動恢復輪詢。
• mode：自由形式的標籤，表示這條訊息是什麼類型（用於 UI 中路由格式化）。
• last_error：最近一次失敗原因，跨重試保留。

worker 透過 SELECT … FOR UPDATE SKIP LOCKED 並按 priority DESC, position ASC 排序來認領工作，因此兩個實例永遠不會搶到同一列。一個部分唯一索引，在 session_id 上的 uq_app_message_inflight，WHERE 條件為 status = 'dispatching' AND role = 'user'：在資料庫層強制「每個會話最多一條在途使用者訊息」。如果某列在 dispatching 狀態停留超過 900 秒（worker 崩潰、節點遺失），恢復輪詢器會將其重設為 pending，以便另一個 worker 接手。

分派是如何流轉的

機制有兩層：行程內的 QueueController 與 Postgres 的 NOTIFY 頻道 queue_dispatch。當一條新訊息入佇列時，寫入端實例會在本地廣播 queue_updated 事件，並發出 pg_notify('queue_dispatch', '{sessionId}|{originInstanceId}')。監聽同一頻道的其他實例會忽略自己的回聲，並接手工作，因此分派在叢集範圍內是事件驅動的，再輔以 60 秒的輪詢作為漏掉通知時的後備。

shared-session 旗標

預設情況下，每個應用階段都會得到自己的會話。當 RunAppRequest.shared_session 為 true 時，執行器會為整次執行建立一個會話，並在每個 agent 階段重複使用其 session_id。可見差異：在執行上點擊在對話中除錯會開啟一個包含每個階段訊息的單一對話，而不是每個階段一個對話。在你希望以敘事方式閱讀整次執行時有用；其他情境很少需要。

ask_user 模式

agent 偶爾需要在執行中向使用者提問（一個歧義、一段缺失的輸入）。發出一個 ask_user 工具呼叫會暫停 agent 當前回合，將問題在對話 UI 中呈現，並等待回覆。平台會在下一次 tick 時把回覆作為工具結果回傳，所以從模型視角看，agent 的「我問過了，這是答案」只是一次普通的對話步驟。這與 human 階段（在執行級別對整個流水線設置關卡）不同；ask_user 完全是會話內部行為。

agent runner 協定

每個 agent 階段和每次對話回合最終都透過一個名為 run-agent 的 Go 二進位執行。伺服器把一個 JSON 設定交給該二進位，並按行讀取它的 stdout。每一行就是一個事件，這是一個穩定的 JSONL 協定，你會在日誌、SSE 負載以及對話 UI 的推理軌跡中看到它的引用。

轉發的事件

這些事件會在到達時被推送到 UI。線上欄位名稱使用 camelCase 以方便 JS；runner 的 snake_case 會自動轉換（tool_id → toolId、is_error → isError 等）。

內部事件（永不轉發）

三個以 __runner_*__ 命名的事件只被伺服器消費，它們是簿記，不是使用者可見的狀態：

錯誤分類

並非每一種 runner 失敗都一樣。伺服器會把捕獲到的錯誤訊息歸類到以下五個桶之一，桶決定了恢復策略：

執行設定裡有什麼

伺服器為每個回合建立一份 RunAgentConfig，並在呼叫二進位之前寫入沙盒中的 ~/.aitroop/run-agent-config.json。要點欄位：

• prompt：實際的使用者訊息（或階段展開後的 goal）。
• options.model：Claude 模型 ID；若階段未鎖定則預設為 claude-sonnet-4-6。
• options.resume：存在時表示恢復一個既有的 Claude 對話。伺服器從會話的 agent_session_id 讀取。
• options.allowedTools：runner 向模型暴露的精選工具集（通常 8 個：Read、Edit、Bash、Glob、Grep、Write、Task，以及 Aitroop MCP 集合）。
• options.permissionMode：固定為 'bypassPermissions'；平台在沙盒邊界強制權限，而不是互動式詢問。
• options.mcpServers：Aitroop 自研的 MCP 伺服器，加上應用 / 階段請求的其他 MCP。
• options.env：process.env 中所有以 SANDBOX_ENV_ 開頭的變數都會被轉發並去掉前綴，再加上 AT_USER_TOKEN（使用者的 JWT）被注入，以便沙盒內的伺服器端呼叫能通過認證。
• options.oauthToken / 代理模式：要麼是 Anthropic OAuth token，要麼在設定了代理時使用一個指向代理的 ANTHROPIC_BASE_URL，並以使用者的 JWT 作為 bearer。平台在每次呼叫時快照一次，保證一次回合內的所有重試都使用相同憑證。

應用是如何被建立出來的

你不需要手寫應用 JSON。這由 agent 完成。流程：

1. 你在對話中告訴 agent：「建立一個應用，讓它……」
2. agent 啟用 aitroop-app-create 技能（應用建構器）。
3. 必要時應用建構器會問 1-5 個釐清問題。
4. 它設計完整的 AppDef（輸入、階段、產物、資源）。
5. 它驗證設計，每個 ID 唯一、每個 {{ref}} 可解析、goal 足夠具體。
6. 它呼叫 POST /api/apps 來儲存。
7. 它回報應用 ID 並提議進一步打磨。

要編輯既有的應用，你可以說類似 「更新我的『公司簡報』應用，加入招聘資料」，應用建構器會拉取目前版本、修改它，然後呼叫 PUT /api/apps/{id}。

常見錯誤

• goal 過於模糊：「做點研究」太過寬泛。請指明資訊來源、深度、輸出格式。
• 缺少產物：一個沒有 artifact_defs 的應用不會產生任何可見輸出。
• 必填項太多：使用者會放棄需要長表單的應用。能預設就預設。
• 逾時設得太短：重度研究階段需要 5-10 分鐘。把 timeout_ms 調到 600000。
• 輸入類型選錯：長文字用 textarea，短識別字用 text，3-6 個固定選項用 select。
• 過度拆分：把本是一個想法的任務拆成 4 個階段。只有當工作天然有可分離的步驟時才使用多階段。

速查詞表