Agent 循環

單次輪次如何從用戶消息流轉到最終答案，以及維持整體運作的狀態記錄機制

Agent 循環是輪次編排器，職責單一：接收用戶消息，運行至最終答案，並持久化沿途發生的一切。Minara 中的每項功能，價格查詢、交易、深度研究報告，都經由同一個循環處理。它以 AgentRuntime 類的形式，位於 apps/agent/src/agent/runtime.ts。

為何選用 Vercel AI SDK，而非自行實現循環？ 一次輪次是有界的短序列：構建上下文、調用模型、執行模型請求的工具、反饋結果、重複直到停止。AI SDK 的 streamText 已經精確建模了這一多步工具循環，並提供跨 Anthropic、OpenAI、xAI 和 OpenRouter 的統一 provider 接口。Minara 將策略邏輯（哪些工具可用、哪些閘門觸發、哪些內容被緩存、上下文如何壓縮）保留在 streamText 調用的各模塊中，由 SDK 負責機械性的"調用工具 → 觀察結果"迭代。

實際使用場景：REPL 和 HTTP 網關中的每次對話輪次都驅動此循環。首次交易演練即是一次完整的端到端輪次。

輪次流水線

AgentRuntime.run() 是一個輪次形狀的流水線，按順序執行以下階段，並輸出單一的 AsyncGenerator<AgentEvent>。兩個表層（網關 SSE 和 REPL）均消費這同一個事件流，而非分散的回調。

調用模型前，運行時先執行偏好演化和輸入掃描，再通過 buildSystemPromptBlocks() 組裝系統提示詞。提示詞由聲明式塊構建，而非字符串拼接；可緩存的前綴（身份標識與技能目錄）在各輪次之間保持字節級一致，從而命中 Anthropic 的提示詞緩存。動態尾部（活躍技能、信號上下文、待確認項）每輪重新構建。塊順序是實質性約束：任何改變緩存前綴的操作都會將一次熱調用變為緩存未命中。工作區 markdown（SOUL.md、MEMORY.md、HEARTBEAT.md）位於動態塊首位，確保操作員維護的基準事實優先於任何推斷層（參見工作區）。

活躍技能的決定由路由器優先完成：它按關鍵詞、生命週期階段、資產類別和協同激活對每項技能打分，活躍集合決定模型被允許查看哪些工具集。

2. 壓縮階梯

對話較長時，運行時在消耗模型調用前，先執行壓縮階梯（邊界切片、摺疊、自動壓縮、Top-N 重注入），以適配上下文窗口。壓縮策略優先採用零 LLM 剪枝，再考慮付費摘要。完整約定參見 docs-src/context-management.md。

3. streamText

運行時以活躍技能允許的工具（與本輪允許工具集取交集）調用 streamText。SDK 在內部驅動"調用工具 → 觀察結果"循環，並在 stopWhen: stepCountIs(maxSteps) 時停止。每一步：

prepareStep 在調用前裁剪累積 token 預算。
模型輸出文本和工具調用；工具調用通過註冊表分發（見下節）。
onStepFinish 記錄用量，並向流中發送步驟事件。

整個 streamText 調用由溢出恢復守衛包裹：若某步超出上下文窗口，則裁剪後重試。

4. 工具分發與閘門

模型發出的每次工具調用通過工具註冊表分發，並受兩道閘門約束：

權限等級。 每個工具攜帶一個 PermissionTier（READ_ONLY → CONFIRM_ONCE → ALWAYS_CONFIRM → MANUAL_ONLY），該等級強制執行，不可繞過。
資金安全棧。 涉及資金的處理程序通過共享的預覽-確認輔助函數把關；交易路徑還額外通過鉤子流水線（token 安全檢查、敞口、滑點、風險官上限、審計日誌）。被攔截的調用會返回結構化錯誤，模型將其視為正常工具結果；審計日誌對其單獨記錄。完整的 6 階段安全棧文檔參見資金安全。

輪次狀態（來源、運行中的已用工具集、風險上限）通過 ToolCallContext 傳遞，確保每次工具調用（包括子 Agent 調用和技能執行的序列）讀取相同的每輪狀態。

5. 輪次結束

streamText 停止後，運行時發出 post_turn 事件，扇出至決策捕獲、對話輪次記錄、工作區狀態更新、儀表盤緩存失效和可觀測性上報。這條記錄是可觀測性工具的讀取來源，也是學習系統反思的數據基礎。

輪次狀態記錄

兩條不變量確保循環可安全擴展：

每輪次一個上下文。 風險上限、信號上下文和已用工具集均存於 ToolCallContext，從不存於模塊級狀態。併發輪次（REPL 和網關可同時運行）之間的狀態記錄互不干擾。
緩存前綴不可變。 輪次中途激活技能會追加一條說明，而非重建系統提示詞，因為重建前綴會破壞提示詞緩存。對加載或壓縮邏輯的任何修改，都不得觸及緩存前綴。

輪次外的確定性執行

並非所有工具調用都經過 streamText。計劃和事件驅動的工作流直接通過註冊表調用已註冊的工具處理程序，無需模型往返。tool_call 工作流步驟運行與循環相同的處理程序，受同等權限等級和資金安全閘門約束，但無需消耗模型調用來做決策。

由此產生兩個結論：

常規自動化（提醒、簡報、監控）成本低廉。僅在顯式包含模型節點的步驟時才消耗 token。
執行語義取決於工具實現，而非模型對其 schema 的理解。

循環和工作流引擎是同一工具註冊表的兩個入口，因此無論在何處運行，涉及資金的步驟仍須經過兩步確認。