深度研究流水線

深度研究是一條專用流水線，與主 Agent 循環並行運行，但相互獨立。主 Agent 循環以對話形式推進，並受權限管控；深度研究流水線則是一個六步狀態機，最終產出一份結構化報告。實現位於 apps/agent/src/deep-research/pipeline.ts。

為何單獨設計流水線，而不讓 Agent 循環迭代？ 多源研究需要並行採集數據（扇出後合併）、LLM-as-Judge 質量檢查，以及重試邏輯。這些需求與對話式 plan → call → observe 節奏不符。專用流水線還能保證研究輸出的確定性與可溯源性，這是對話循環無法做到的。

查看實際效果：功能 → 深度研究介紹了面向用戶的一側，包含報告輸出示例。

適用場景

當目標是生成書面產物而非聊天回答時，使用此流水線：

針對特定資產或主題的長篇市場分析。
需要為每項論斷註明來源的多源綜合報告。
定時研究任務，希望獲得可通過 id 查閱的產物。

對於快速對話問題（"BTC 現價是多少"、"這裡應該做多嗎"），請使用 Agent 循環。深度研究流水線延遲更高、工具調用預算固定，且不保留當前對話的上下文。

六個步驟

除 collectData 外，每個步驟都是單次 LLM 調用。collectData 會針對每個目標，在工具註冊表上運行一個子 Agent 循環。

與主 Agent 循環的隔離

流水線刻意保持隔離：

不讀取聊天的對話歷史。
不消耗技能系統的激活狀態。
為數據採集自行構建一套精簡工具子集，而不使用當前激活的技能。
不觸發學習記錄（review-engine 不會在流水線輪次中運行）。

隔離帶來兩項收益：確定性（每次研究任務從相同狀態出發）；成本管控（長會話的歷史不會滲入研究成本）。

模式

interface ResearchRequest {
  chatId: string;
  userMessage: string;
  mode?: "light" | "heavy";
  language?: string;
}

light（默認）。2 個並行採集目標，較小的最大迭代數，單遍報告生成。典型延遲：30–60 秒。
heavy。4 個並行採集目標，更大的迭代預算，綜合分析更深入。典型延遲：2–5 分鐘。

定時/cron 研究任務選 light；用戶明確要求深度報告時選 heavy。

場景

報告圍繞場景組織，即預定義的分析角度，例如"多方觀點"、"空方觀點"、"基準情形"、"監管風險"、"宏觀背景"。metaPlan 步驟根據研究主題，從 apps/agent/src/deep-research/scenarios.ts 的目錄中選取 1–4 個場景。

場景選擇對報告質量至關重要：缺少"宏觀"場景的 BTC 研究報告往往遺漏最重要的背景信息；缺少"空方觀點"則會產生確認偏差。目錄刻意保持精簡，以確保 LLM 場景選擇器的可靠性。

輸出產物

結果以 report 類型產物存儲在 ArtifactStore 中：

interface ResearchResult {
  report_id: string;
  status: "completed" | "error" | "waiting_for_input";
  title: string | null;
  research_topic: string | null;
  scenarios: string[];
  summary: string | null;
  key_findings: string[];
  report_markdown: string | null;
  error?: string;
  tokens: { input: number; output: number };
}

主 Agent 可通過 report://{id} URI 方案將已完成的報告引用給用戶。這就是將研究與對話結合的方式：用戶請求研究，獲得 report_id，隨後在聊天中提出引用該報告的後續問題。

報告正文為 Markdown 格式，包含場景標題、行內引用（通過 [text](url)），以及由 summarize 步驟生成的"關鍵發現"要點列表。

運行方式

在 REPL 中運行

主 Agent 激活 deep-research 領域技能，調用 deep_research_run 工具：

> write me a report on ETH staking yields this quarter
assistant: [activates deep-research skill]
assistant: [calls deep_research_run with mode=heavy]
assistant: ✓ report_id: r_abc123 — here's the summary…

使用 CLI 子命令運行

完全繞過 REPL：

minara research "BTC ETF flows this quarter"
minara research "macro risks for Solana" --mode heavy

完整參數列表見子命令 → minara research。

通過 HTTP 請求運行

curl -X POST http://localhost:8080/research \
  -H 'content-type: application/json' \
  -d '{"topic": "BTC ETF flows", "mode": "light"}'

請求與響應結構見 API → /research。

成本與可觀測性

每個步驟都會在審計日誌中以 source: "deep-research" 記錄 {provider, model, tokens}。ResearchResult 上的 tokens 字段是用於快速核算成本的彙總估算值。如需精確的成本歸因，可查詢審計日誌：

SELECT model, SUM(input_tokens), SUM(output_tokens), COUNT(*)
  FROM audit
 WHERE source = 'deep-research'
   AND trace_id = ?
 GROUP BY model;

深度研究流水線是大多數 Minara 部署中單次 LLM 成本最高的環節。若賬單異常偏高，通常先運行此查詢排查。

擴展流水線

流水線刻意保持精簡（pipeline.ts 約 700 行）。常見擴展方式：

新增場景：在 scenarios.ts 中追加到目錄。元計劃提示詞在運行時讀取目錄，無需修改提示詞。
調整採集併發數：在 PipelineConfig 中設置 collectConcurrency。默認值為 4，與 v1 上限一致。
調整每個目標的最大迭代數：設置 collectMaxIterations。默認值為 8，即每個數據採集子 Agent 的 LLM 輪次預算。
新增後處理步驟：在流水線類中追加一個方法，在 summarize 與返回之間調用。不要將邏輯內聯到已有步驟中；步驟邊界是流水線可調試性的保障。

不要將流水線接入主 Agent 循環的歷史記錄。隔離是設計特性；一旦破壞，聊天成本將滲入研究成本。

不適合放入研究的內容

依賴實時價格的決策。 流水線耗時數分鐘，價格隨時變動。任何依賴當前執行條件的操作，請使用 Agent 循環。
涉及資金的工具調用。 數據採集使用的精簡工具子集排除了所有涉及資金的工具。若工具子集意外包含此類工具，流水線將拒絕運行。
用戶私人上下文。 流水線不讀取用戶的錢包餘額或歷史記錄，僅面向公開市場數據。若報告需要考慮用戶的具體倉位，請在 bootstrap 階段將倉位信息放入用戶消息；流水線會將其傳遞至後續步驟。

本頁目錄