6.8 KiB

Raw Blame History

name	description
iterative-retrieval	逐步優化內容擷取的模式，旨在解決子 Agent (Subagent) 的上下文 (Context) 缺失問題。

疊代擷取模式 (Iterative Retrieval Pattern)

用於解決多 Agent 工作流中的「上下文問題」— 即子 Agent 在開始工作前，往往不知道自己具體需要哪些上下文資訊。

何時啟用

當啟動子 Agent 時，它們需要事前無法預知的程式碼庫上下文。
建構需要逐步優化上下文的廣泛多 Agent 工作流。
Agent 任務中遇到「內容過載 (Context too large)」或「缺少上下文 (Missing context)」的失敗情況。
為程式碼探索設計類 RAG (檢索增強生成) 的擷取流水線。
在 Agent 編排中優化 Token 使用量。

問題所在

子 Agent 啟動時僅具備有限的上下文。它們通常不知道：

哪些檔案包含相關程式碼。
程式碼庫中存在哪些既定模式。
專案使用了哪些特定術語。

標準做法通常會失敗：

發送全部內容：超出上下文限制。
什麼都不發送：Agent 缺少關鍵資訊。
猜測需求：往往猜錯。

解決方案：疊代擷取 (Iterative Retrieval)

一個分為 4 階段的迴圈，用於逐步精煉上下文：

┌─────────────────────────────────────────────┐
│                                             │
│   ┌──────────┐      ┌──────────┐            │
│   │   派發   │─────▶│   評估   │            │
│   └──────────┘      └──────────┘            │
│        ▲                  │                 │
│        │                  ▼                 │
│   ┌──────────┐      ┌──────────┐            │
│   │   迴圈   │◀─────│   精煉   │            │
│   └──────────┘      └──────────┘            │
│                                             │
│        最多 3 個週期，隨後繼續執行            │
└─────────────────────────────────────────────┘

階段 1：派發 (DISPATCH)

初始階段：執行廣泛查詢以蒐集候選檔案。

// 從高階意圖開始
const initialQuery = {
  patterns: ['src/**/*.ts', 'lib/**/*.ts'],
  keywords: ['authentication', 'user', 'session'],
  excludes: ['*.test.ts', '*.spec.ts']
};

// 派發給擷取 Agent
const candidates = await retrieveFiles(initialQuery);

階段 2：評估 (EVALUATE)

評估所擷取內容的相關性：

function evaluateRelevance(files, task) {
  return files.map(file => ({
    path: file.path,
    relevance: scoreRelevance(file.content, task),
    reason: explainRelevance(file.content, task),
    missingContext: identifyGaps(file.content, task)
  }));
}

評分標準：

高 (0.8-1.0)：直接實作了目標功能。
中 (0.5-0.7)：包含相關的模式或型別定義。
低 (0.2-0.4)：僅有些微關聯。
無 (0-0.2)：不相關，應排除。

階段 3：精煉 (REFINE)

根據評估結果更新搜尋準則：

function refineQuery(evaluation, previousQuery) {
  return {
    // 加入在高度相關檔案中發現的新模式
    patterns: [...previousQuery.patterns, ...extractPatterns(evaluation)],

    // 加入程式碼庫中使用的術語
    keywords: [...previousQuery.keywords, ...extractKeywords(evaluation)],

    // 排除已確認不相關的路徑
    excludes: [...previousQuery.excludes, ...evaluation
      .filter(e => e.relevance < 0.2)
      .map(e => e.path)
    ],

    // 針對特定的資訊缺口
    focusAreas: evaluation
      .flatMap(e => e.missingContext)
      .filter(unique)
  };
}

階段 4：迴圈 (LOOP)

使用精煉後的準則重複執行（最多 3 次週期）：

async function iterativeRetrieve(task, maxCycles = 3) {
  let query = createInitialQuery(task);
  let bestContext = [];

  for (let cycle = 0; cycle < maxCycles; cycle++) {
    const candidates = await retrieveFiles(query);
    const evaluation = evaluateRelevance(candidates, task);

    // 檢查是否有足夠的上下文
    const highRelevance = evaluation.filter(e => e.relevance >= 0.7);
    if (highRelevance.length >= 3 && !hasCriticalGaps(evaluation)) {
      return highRelevance;
    }

    // 精煉並繼續
    query = refineQuery(evaluation, query);
    bestContext = mergeContext(bestContext, highRelevance);
  }

  return bestContext;
}

實戰範例

範例 1：除錯任務的上下文

任務：「修復身份驗證權杖 (Auth Token) 過期的錯誤」

週期 1：

派發：在 src/** 中搜尋 "token", "auth", "expiry"。
評估：發現 auth.ts (0.9), tokens.ts (0.8), user.ts (0.3)。
精煉：加入關鍵字 "refresh", "jwt"；排除 user.ts。

週期 2：

派發：搜尋精煉後的詞彙。
評估：發現 session-manager.ts (0.95), jwt-utils.ts (0.85)。
精煉：上下文已足夠。

結果：auth.ts, tokens.ts, session-manager.ts, jwt-utils.ts

範例 2：功能實作

任務：「為 API 端點加入速率限制 (Rate Limiting)」