應用

應用是 Aitroop 中可重複工作的基本單位，把一次性的好對話變成可排程執行的工作流。本頁講建立、執行、編輯、版本管理與分享。

建立應用：四階段流程

你透過與智能體對話來建立應用。內建的 aitroop-app-create 技能（即應用建構器）每次都會依循結構化的四階段流程進行。理解這些階段有助於你引導對話，並掌握接下來會發生什麼事。

階段 0：理解意圖

當你的訊息中包含觸發詞時，應用建構器會啟動，並提出 1 到 5 個釐清性問題：

1. 這個應用應該做什麼？一句話目標。
2. 它需要哪些輸入？自由文字、檔案、日期、選項？
3. 它應該產出什麼？報告、程式碼檔案、試算表、結構化資料？
4. 有幾個步驟 / 階段？單次智能體呼叫，或多階段管線？
5. 需要哪些特定工具或整合？網路搜尋、檔案處理、OAuth？

階段 1：設計應用

應用建構器會建構完整的 AppDef JSON。它會挑選：

• 名稱：依應用功能而定，採用標題大小寫。
• 圖示：一個符合情境的 emoji。
• 標籤：可搜尋的關鍵字。
• 輸入：為每個變數挑選合適的型別：text 用於短識別碼，textarea 用於長內容，select 用於固定選項，daterange 用於時間區間，file 用於上傳。
• 階段：預設為單一階段。只有當工作天然存在可分離的步驟時，才會拆成多階段。
• 產物：markdown 用於散文，csv 用於表格，json 用於結構化資料，html 用於可渲染頁面，image 用於視覺素材，code 用於原始檔。
• 資源：加入應用所需的技能與連接。
• 逾時：預設 3 分鐘，重度研究應用會提高到 5-10 分鐘。

階段 2：驗證

儲存之前，應用建構器會執行內部檢查：

• 輸入、階段、產物中每一個 id 都唯一。
• 階段目標裡的每個 {{field_id}} 參照都對應一個真實的輸入。
• 階段之間的參照（階段 2 讀取階段 1 的產物）連接正確。
• 如果應用應該有可見輸出，那麼至少要有一個階段產出產物。
• required: true 只用在真正會阻塞執行的輸入上。
• 目標夠具體，含糊的目標會被改寫。

若驗證失敗，應用建構器會自己修正問題，而不是反過來問你。只有驗證通過後，你才會看到階段 3。

階段 3：透過 API 建立或更新

應用建構器會呼叫平台的 REST API：

請求主體即為完整的 AppDef JSON。平台會將其持久化、指派版本號，並回傳應用 ID。整個過程你看不見，是在幕後完成的。

階段 4：向使用者呈現

應用建構器會回報以下內容：

• 應用名稱與功能說明。
• 輸入清單及其型別。
• 階段清單及其說明。
• 會產出哪些產物。
• 應用 ID，方便你之後找到它。
• 提供進一步打磨的選項。

此時應用就已經上線、可執行，並出現在你的應用庫中。

範例：三種複雜度的三個應用

簡單：單輸入、單階段

中等：多輸入、單階段，需要一個連接

注意 connects 裡的 google。第一次執行這個應用時，會提示你授權 Gmail 存取權。之後再執行就不會再提示了。

複雜：多階段並包含人工審核步驟

執行這個應用時，平台會自動跑完階段 1 與階段 2。階段 3 會暫停，並在審核窗格中顯示 enriched.csv：你刪掉不要的列後，點 Approve and continue。階段 4 會以核可後的子集繼續執行。

執行應用

從應用庫執行

1. 點側邊欄的 Apps。
2. 點你想執行的應用。
3. 應用頁面會開啟，左邊是表單，右邊是輸出佔位。
4. 填寫必填欄位（帶紅色星號標記）。
5. 選填欄位會顯示佔位提示或預先填好的預設值。
6. 點 Run（表單底部的大按鈕）。

執行過程中你會看到什麼

頁面會分割，右側窗格會填入：

• 頂部的階段指示器：「Stage 1 of 3: research_and_write」。
• 推理軌跡：智能體的規劃、工具呼叫（網路搜尋、技能呼叫）、部分輸出。
• 產物即時預覽：智能體寫入產物的同時，你能即時看到它出現。
• 執行控制：執行進行中時，可使用 Cancel 按鈕取消。

執行結束後會發生什麼

產物會儲存到執行歷史。在產物預覽中，你可以：

• Download：選擇一種格式（產物的原生格式，或可渲染內容的 PDF/DOCX）。
• Copy：把原始內容複製到剪貼簿。
• Edit in chat：開啟一段針對此產物的新對話，方便快速調整。
• Share：產生指向產物的連結（可見性視應用設定而定）。

未更動的輸入

下次再進入應用頁面時，表單會自動預填上次使用的輸入。點欄位旁的重設圖示（🔄）可以把它清回預設值。

以相同輸入重新執行

在任一筆歷史執行上點 Re-run，即可以相同輸入再執行一次。適合用於：刷新具時效性的資料（例如「最新消息」類應用）、確認一致性、在不同版本之間做提示詞的 A/B 對比。

編輯應用

對話式編輯（適合非瑣碎的改動）

1. 在應用頁面，點 Edit in chat（有時顯示為「Chat with this App」）。
2. 會開啟一段對話，並把應用的設計作為上下文載入。
3. 用自然語言告訴智能體你想怎麼改。例如：
   • 「加一個 select 型別的輸入用於輸出語言，選項為 English / Chinese / Spanish。」
   • 「把這個階段拆成 'research' 與 'write'，把研究筆記作為上下文傳給寫作階段。」
   • 「把逾時改為 10 分鐘。」
   • 「移除 company_url 這個輸入。」
4. 智能體會給你一份差異說明：什麼改了、什麼沒改。
5. 核可後，智能體會呼叫 PUT /api/apps/{id}，新版本就此儲存。

直接欄位編輯（適合快速改動）

1. 在應用頁面，點 Edit。
2. 編輯器會開啟，所有欄位一覽無遺：名稱、圖示、標籤、輸入、階段、產物、資源。
3. 直接修改任意欄位：
   • 點某個輸入的型別下拉選單，把 text 切換成 textarea。
   • 點某個選項以重新命名。
   • 在目標欄位中輸入，編輯給智能體的指令。
   • 拖曳輸入項以重新排序。
4. 點 Save，新版本儲存完成。

編輯目標：常見模式

階段目標承載了應用大部分的行為。常見的編輯方式：

• 加入結構：「輸出格式：A 段（一段話） / B 段（項目符號清單）……」
• 加入限制：「最多 500 字。」「只使用最近 12 個月的來源。」
• 加入個人化掛鉤：「配合 {{tone}} 中描述的受眾語氣。」
• 提升具體性：把模糊動詞（「review」）換成具體動詞（「給 1-10 分並附理由」）。

版本管理

每次儲存都會建立一個新版本。版本以 v1、v2、v3…… 編號。應用頁面有一個 Versions 分頁，列出所有版本。

在 Versions 分頁中你可以

• 查看歷史：每個版本的儲存時間、儲存者、變更摘要。
• 檢視某個版本的完整 AppDef：點任意版本即可看到其完整設定。
• 比較兩個版本：挑兩個版本，並排查看差異。
• 回滾：一鍵將任意舊版本升為「目前版本」。目前行為會跟著回退；你回滾前的那個版本仍會保留在歷史中。

排程與版本管理

排程預設使用應用的目前版本。所以如果你週日修了一個 bug，週一的排程執行就會用上修正後的版本。

若需要穩定性（例如面向客戶的報告，不應突然變化），可以把排程固定到某個特定版本。被固定的排程會忽略後續的應用編輯。

分享與存取

每個應用有三種可見性：

• Private：只有你能看到與執行。預設。
• Team：工作區內所有人都能看見。最適合團隊共享的內部應用。
• Public link：任何有連結的人都能執行（視方案而定）。即便如此，每次執行的輸入與輸出仍各自沙盒化。

團隊應用下的逐使用者連接

當隊友執行一個團隊應用時，執行使用的是他們自己的連接，而不是你的。一個共享的「每日收件匣分類」應用，你執行時讀的是你的 Gmail，同事執行時讀的是他的 Gmail。每位使用者都會授權自己的連接。

Fork（分支複製）

任何對團隊應用具有檢視權限的人，都可以對它執行 fork：建立一份屬於自己的私人副本，並擁有獨立的版本歷史。適合「我想要這個應用，但要做一些自己的修改」又不希望影響共享版本的情境。

多階段應用詳解

什麼時候該使用多階段

滿足以下任一情境時，可以考慮多階段：

• 工作天然可拆成「先做 X，再以 X 的結果做 Y」。
• 你希望只重跑最後一步，而不必重跑之前那些昂貴的步驟。
• 中間需要一個人工核可檢查點。
• 某一步需要可預期的轉換（在兩個 agent 階段之間插入一個 script 階段）。

階段之間如何共享資料

每個階段的產物都會自動供下一階段使用。在下一階段的目標中以樣板語法引用即可：

三種階段型別的實際用法

agent：預設型別

智能體會讀取輸入（以及任何先前的產物），使用已安裝的技能與已授權的連接，並產出宣告的產物。最適合：推理、摘要、起草、研究。

script：可預期的轉換

一個 Python 或 Node 腳本，在沙盒內執行，不會呼叫語言模型。最適合：過濾 CSV、去重、格式轉換、精確算術。快速且可預期。

human：暫停以待審核

執行會暫停。平台會把目標文字與任何先前的產物呈現給使用者。使用者可以修改、核可或拒絕。下一個階段會以人工產出的內容繼續執行。最適合：核可檢查點、「挑出最好的 N 項」、「送出前修掉任何看起來不對的地方」。

實戰範例：只重跑最後一個階段

假設你的三階段應用順利跑完了，但最後一個階段的草稿不理想。要避免重做階段 1 與階段 2：

1. 從應用的 Runs 分頁打開該次執行。
2. 點 Re-run from stage…
3. 挑 Stage 3。
4. 階段 1 與階段 2 的產物會被重用，階段 3 會帶著你修過的內容再跑一遍。

從 API 角度看，同樣的操作如下：

關於完整的執行生命週期、取消、閘門與 SSE 串流，請參見 執行記錄。

透過 API 呼叫應用

在介面上能做的一切，也都透過 REST 提供。當你想從 webhook、CI 任務、另一個智能體或同事的腳本中觸發應用時，這非常有用。

驗證

在 Settings → API Tokens → Create 取得 token。把它當作密碼，範圍最小化、定期輪替、絕不入庫。所有端點都要求：

核心端點

端到端範例：觸發應用、等待完成、下載產物

當應用失敗時

常見的失敗模式與診斷方式：

「Debug in chat」工作流程

1. 打開失敗的執行。
2. 點 Debug in chat。
3. 會開啟一段新對話，並附上該次執行的完整上下文：輸入、部分產物、智能體推理軌跡、錯誤。
4. 與智能體交流：「為什麼失敗了？我該改什麼？」
5. 智能體會診斷、提出修正建議，並（通常）直接編輯應用以套用修正。
6. 重新執行。

需要避免的常見錯誤

• 目標含糊。「Do research」，太模糊了。要寫明來源、深度、輸出結構。
• 缺少產物。沒有 artifact_defs 的階段不會產出任何可見內容。
• 必填項過多。能給預設值的就給。冗長的表單容易被放棄。
• 逾時過短。重度研究需要 5-10 分鐘（timeout_ms: 600000）。
• 輸入型別錯誤。長文字用 textarea，不要用 text。固定選項用 select。
• 過度拆解。如果在一次對話裡它就是一個完整的想法，一個階段就夠了。不要預先拆。
• 目標過短。兩行的目標通常不如一份帶結構與限制的 10 行目標好用。

常見問題與疑難排解

我的應用每次執行輸出都不一致，怎麼收緊？

照順序使用兩個槓桿：

1. 收緊目標。加入有編號的輸出結構、字數指標，以及可接受輸出的範例。規格越精確，智能體匹配得就越接近。
2. 降低模型的自由度。在目標裡加上：「如果對任何部分不確定，請說 'insufficient data'，不要猜測。」當被允許時，智能體會更傾向給出保守的回答，而不是自信地猜。

對於真正可預期的轉換（剖析、過濾、格式化），請以 script 階段取代智能體階段。

某個階段可以依輸入跳過自己嗎？

可以，在控制它的輸入上使用 show_if（例如 "show_if": "include_competitors == true"），並在目標中使用條件區塊： {{#if include_competitors}} ... {{/if}}。智能體讀取的是未渲染的目標，所以真正告訴它要不要做這項工作的，是這個條件區塊。

如何把一個應用的輸出傳給另一個應用？

兩種模式：

• 排程 + webhook。讓應用 A 的排程 POST 到應用 B 的 /run 端點。把產物 URL 作為輸入傳過去。
• 透過 script 階段串接。階段 1 透過 API 呼叫應用 A 並讀取產物。階段 2 之後在同一應用中繼續。

原生的「應用組合」功能已在路線圖上。

兩個人可以同時編輯同一個應用嗎？

勉強可以，每次儲存都是一個新版本，所以兩人並行編輯不會互相覆蓋。但「目前版本」指標歸最後儲存者所有。對於正在積極開發的團隊應用，建議商定一位負責人，或使用對話式編輯（它會透過智能體被序列化）。

如何匯出應用的定義？

把 JSON 存到 git、分享給同事，或透過 POST /api/apps 貼到新的工作區。

可以匯入別人匯出的應用嗎？

可以。打開 Apps → New → Import JSON，貼上 AppDef，點儲存。平台會驗證並在你的工作區中建立應用。所需的技能與連接會列出來；首次執行時會提示你授權連接。

我的應用目標參照了一個使用者尚未授權的連接，會怎樣？

平台會在啟動沙盒之前就偵測到這一點。執行會轉為 failed，並附上 connect_unauthorized，指出缺少的提供者。系統會在介面中提示使用者授權，之後即可重試。對於排程執行，會通知該排程的擁有者。

能否限制誰可以執行應用？

有三種控制方式：

• 可見性：private / team / public link。
• 依角色限制執行：按組織角色限制（僅管理員、僅成員）。在 Apps → Settings 下設定。
• 逐使用者連接：即便隊友能執行你的應用，執行使用的也是他們自己的 token，而不是你的。