Back to Details

iterative-retrieval

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Iterative Retrieval Pattern

迭代检索模式

Solve the subagent context problem: agents don't know what they need until they start looking.
解决子Agent的上下文问题：Agent在开始查找前不知道自身需要什么。

The Problem

问题

When delegating to subagents, you face a dilemma:
  • Send everything: Context overflow, wasted tokens, confused agent
  • Send nothing: Agent lacks context, produces poor results
  • Guess what's needed: Often wrong, misses critical files
在将任务委托给子Agent时，你会面临两难困境：
  • 发送全部内容：上下文过载，浪费token，导致Agent困惑
  • 不发送任何内容：Agent缺乏上下文，产出结果质量低下
  • 猜测所需内容：通常判断错误，遗漏关键文件

The Solution: 4-Phase Iterative Loop

解决方案：四阶段迭代循环

Phase 1: DISPATCH

阶段1：DISPATCH（分发）

Send a broad initial query to gather candidate context:
markdown
Search for files related to: [topic]
Keywords: [initial keywords]
File patterns: [likely patterns]
Return: File paths with relevance scores
发送宽泛的初始查询以收集候选上下文：
markdown
Search for files related to: [topic]
Keywords: [initial keywords]
File patterns: [likely patterns]
Return: File paths with relevance scores

Phase 2: EVALUATE

阶段2：EVALUATE（评估）

Score each result for relevance (0.0 to 1.0):
markdown
| File | Relevance | Reason |
|------|-----------|--------|
| src/auth/login.ts | 0.9 | Core auth logic |
| src/utils/hash.ts | 0.7 | Used by auth |
| src/config.ts | 0.3 | Has auth config section |
| src/routes.ts | 0.2 | Only references auth path |
Identify gaps:
  • What terminology does this codebase use? (update search terms)
  • What patterns are referenced but not found?
  • What dependencies need exploration?
为每个结果的相关性打分（0.0至1.0）：
markdown
| File | Relevance | Reason |
|------|-----------|--------|
| src/auth/login.ts | 0.9 | Core auth logic |
| src/utils/hash.ts | 0.7 | Used by auth |
| src/config.ts | 0.3 | Has auth config section |
| src/routes.ts | 0.2 | Only references auth path |
识别缺口：
  • 该代码库使用哪些术语？（更新搜索词）
  • 哪些模式被提及但未找到？
  • 需要探索哪些依赖项？

Phase 3: REFINE

阶段3：REFINE（优化）

Update search criteria based on evaluation:
markdown
Updated keywords: [refined keywords from codebase terminology]
New file patterns: [patterns discovered during evaluation]
Specific files to read: [high-relevance files]
Gaps to fill: [what's still missing]
基于评估结果更新搜索条件：
markdown
Updated keywords: [refined keywords from codebase terminology]
New file patterns: [patterns discovered during evaluation]
Specific files to read: [high-relevance files]
Gaps to fill: [what's still missing]

Phase 4: LOOP

阶段4：LOOP（循环）

Repeat phases 1-3 with refined criteria.
Stopping Criteria:
  • 3+ files with relevance >= 0.7
  • No critical gaps identified
  • OR max 3 iterations reached (proceed with best available)
使用优化后的标准重复阶段1-3。
停止条件：
  • 3个及以上相关性≥0.7的文件
  • 未识别到关键缺口
  • 或已达到最大3次迭代（使用现有最佳结果继续）

Example: Finding Auth Implementation

示例：查找身份验证实现

Iteration 1:
  • DISPATCH: Search for "auth", "login", "session"
  • EVALUATE: Found middleware but not the auth service
  • REFINE: Codebase uses "identity" not "auth"
Iteration 2:
  • DISPATCH: Search for "identity", "credential", "token"
  • EVALUATE: Found IdentityService, TokenManager, SessionStore
  • Result: 5 files with relevance >= 0.8 — stop and proceed
迭代1：
  • DISPATCH：搜索“auth”、“login”、“session”
  • EVALUATE：找到中间件但未找到身份验证服务
  • REFINE：代码库使用“identity”而非“auth”
迭代2：
  • DISPATCH：搜索“identity”、“credential”、“token”
  • EVALUATE：找到IdentityService、TokenManager、SessionStore
  • 结果：5个相关性≥0.8的文件 — 停止并继续

Implementation Pattern

实现模式

typescript
async function iterativeRetrieve(topic: string, maxIterations = 3) {
  let keywords = extractKeywords(topic);
  let context: FileContext[] = [];

  for (let i = 0; i < maxIterations; i++) {
    // DISPATCH
    const candidates = await searchCodebase(keywords);

    // EVALUATE
    const scored = await scoreRelevance(candidates, topic);
    context = mergeContext(context, scored.filter(s => s.relevance >= 0.5));

    // Check stopping criteria
    const highRelevance = context.filter(c => c.relevance >= 0.7);
    if (highRelevance.length >= 3) break;

    // REFINE
    keywords = refineKeywords(keywords, scored);
  }

  return context;
}
typescript
async function iterativeRetrieve(topic: string, maxIterations = 3) {
  let keywords = extractKeywords(topic);
  let context: FileContext[] = [];

  for (let i = 0; i < maxIterations; i++) {
    // DISPATCH
    const candidates = await searchCodebase(keywords);

    // EVALUATE
    const scored = await scoreRelevance(candidates, topic);
    context = mergeContext(context, scored.filter(s => s.relevance >= 0.5));

    // Check stopping criteria
    const highRelevance = context.filter(c => c.relevance >= 0.7);
    if (highRelevance.length >= 3) break;

    // REFINE
    keywords = refineKeywords(keywords, scored);
  }

  return context;
}

When to Use

适用场景

  • Delegating research to a subagent
  • Exploring unfamiliar codebases
  • Gathering context for code review
  • Building context for architectural analysis
  • 将研究任务委托给子Agent
  • 探索不熟悉的代码库
  • 为代码审查收集上下文
  • 为架构分析构建上下文

When NOT to Use

不适用场景

  • You already know exactly what files are needed
  • The task is in a single file
  • The codebase is small enough to read entirely
  • 你已明确知道所需的文件
  • 任务仅涉及单个文件
  • 代码库小到可以完整阅读