疊代式檢索模式
解決多代理工作流程中的「上下文問題」——子代理在開始工作前不知道他們需要什麼上下文。
啟用時機
- 生成需要程式碼庫上下文但無法事先預測的子代理
- 構建逐步精煉上下文的多代理工作流程
- 遇到代理任務中「上下文過大」或「缺少上下文」的失敗情況
- 設計用於程式碼探索的 RAG 風格檢索管道
- 優化代理編排中的 Token 使用量
問題
子代理生成時僅有有限的上下文。他們不知道：
- 哪些檔案包含相關程式碼
- 程式碼庫中存在哪些模式
- 專案使用了什麼術語
標準方法會失敗：
- 發送所有內容：超出上下文限制
- 不發送任何內容：代理缺乏關鍵資訊
- 猜測需要什麼：常常出錯
解決方案：疊代式檢索
一個逐步精煉上下文的4階段循環：
┌─────────────────────────────────────────────┐
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 分派 │─────│ 評估 │ │
│ └──────────┘ └──────────┘ │
│ ▲ │ │
│ │ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 循環 │─────│ 精煉 │ │
│ └──────────┘ └──────────┘ │
│ │
│ 最多 3 次循環，然後繼續 │
└─────────────────────────────────────────────┘
階段 1：分派
初始的廣泛查詢，用於收集候選檔案：
// 從高層意圖開始
const initialQuery = {
patterns: ['src/**/*.ts', 'lib/**/*.ts'],
keywords: ['authentication', 'user', 'session'],
excludes: ['*.test.ts', '*.spec.ts']
};
// 分派給檢索代理
const candidates = await retrieveFiles(initialQuery);
階段 2：評估
評估檢索內容的相關性：
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：精煉
根據評估更新搜尋條件：
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：循環
使用精煉後的條件重複執行（最多 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：Bug 修復上下文
任務：「修復驗證 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)
精煉：擁有足夠的上下文（2 個高相關性檔案）
結果：auth.ts, tokens.ts, session-manager.ts, jwt-utils.ts
範例 2：功能實作
任務：「為 API 端點加入速率限制」
第 1 輪：
分派：在 routes/** 中搜尋「rate」、「limit」、「api」
評估：無符合項目——程式碼庫使用「throttle」術語
精煉：加入「throttle」、「middleware」關鍵字
第 2 輪：
分派：搜尋精煉後的詞彙
評估：找到 throttle.ts (0.9), middleware/index.ts (0.7)
精煉：需要路由器模式
第 3 輪：
分派：搜尋「router」、「express」模式
評估：找到 router-setup.ts (0.8)
精煉：擁有足夠的上下文
結果：throttle.ts, middleware/index.ts, router-setup.ts
與代理的整合
在代理提示中使用：
當為此任務檢索上下文時：
1. 從廣泛的關鍵字搜尋開始
2. 評估每個檔案的相關性（0-1 分）
3. 識別仍缺少哪些上下文
4. 精煉搜尋條件並重複執行（最多 3 次循環）
5. 回傳相關性 >= 0.7 的檔案
最佳實踐
- 從廣泛開始，逐步縮窄——不要過度指定初始查詢
- 學習程式碼庫術語——第一輪通常會揭示命名慣例
- 追蹤缺少的內容——明確的缺口識別驅動精煉過程
- 在「足夠好」時停止——3 個高相關性檔案勝過 10 個平庸的檔案
- 有信心地排除——低相關性檔案不會變得相關
相關資源
- 長篇指南 - 子代理編排章節
continuous-learning技能 - 用於隨時間改進的模式- 與 ECC 一起提供的代理定義（手動安裝路徑：
agents/）