// GlobInput = 文件名/路径模式搜索的输入。
// 适合“我大概知道文件名长什么样”，例如 **/*config*.ts。
type GlobInput = {
  pattern: string; // glob 表达式，例如 "src/**/*.ts"。
  limit?: number;  // 最多返回多少条，避免结果撑爆上下文。
};

// globTool = 文件名搜索工具。
// 职责：在 workspace 内找文件，并过滤掉 node_modules、dist 等无意义目录。
export async function globTool(input: GlobInput, ctx: ToolContext): Promise<ToolResult> {
  // limit 由模型传入，但程序要设置上限，防止模型请求 100000 条。
  const limit = Math.min(input.limit ?? 100, 500);

  // cwd 限制在当前项目；ignore 避免搜依赖、Git 内部目录、构建产物。
  const matches = await glob(input.pattern, {
    cwd: ctx.cwd,
    ignore: ["node_modules/**", ".git/**", "dist/**", "build/**"]
  });

  // 只返回前 limit 条，但 metadata 里保留总数。
  const limited = matches.slice(0, limit);

  return {
    summary: `Found ${matches.length} files, returning ${limited.length}.`,
    content: limited.join("\n"),
    metadata: {
      total: matches.length,
      returned: limited.length
    }
  };
}

// GrepInput = 正文搜索的输入。
// 适合“我知道某个函数名、错误信息、配置 key 或可见文案”。
type GrepInput = {
  pattern: string; // 要搜索的文本或正则。
  include?: string; // 限定文件范围，例如 "src/**/*.ts"。
  limit?: number;   // 最多返回多少条。
};

// grepTool = 正文搜索工具。
// 真实实现通常调用 ripgrep，因为它快、支持 ignore、输出可控。
export async function grepTool(input: GrepInput, ctx: ToolContext): Promise<ToolResult> {
  // runRipgrep 是对 rg 的封装，负责执行命令、解析输出、截断结果。
  const result = await runRipgrep({
    pattern: input.pattern,
    include: input.include,
    cwd: ctx.cwd,
    limit: Math.min(input.limit ?? 100, 500)
  });

  return {
    summary: `Found ${result.total} matches, returning ${result.items.length}.`,
    // formatGrepMatches 应输出 path:line:text，方便模型继续 read_file。
    content: formatGrepMatches(result.items),
    metadata: {
      total: result.total,           // 实际命中总数。
      returned: result.items.length  // 返回给模型的条数。
    }
  };
}

src/queryEngine.ts:42: const response = await callModel(...)
src/tool.ts:80: export async function executeToolCall(...)

// scoreSearchResult = 给搜索结果打分。
// 分数越高，越应该优先读这个文件。
function scoreSearchResult(item: SearchResult, query: string) {
  let score = 0;

  // 文件名直接包含 query，通常比正文偶然命中更可靠。
  if (item.path.toLowerCase().includes(query.toLowerCase())) score += 5;

  // src/ 下的源码通常比 dist/、docs/ 更接近可修改对象。
  if (item.path.startsWith("src/")) score += 3;

  // test 文件对理解预期行为很重要，所以也加分。
  if (item.path.includes("test")) score += 1;

  // 当前 Git 已改文件要优先，因为用户可能正在围绕它工作。
  if (item.gitChanged) score += 4;

  // 命中越多越可能相关，但最多加 10，避免大文件靠重复刷分。
  score += Math.min(item.matchCount, 10);

  // 太大的文件通常不适合直接塞给模型，先降权。
  if (item.sizeBytes > 200_000) score -= 5;

  return score;
}

// CodeContext = 读完文件后整理出的结构化上下文。
// 它比“整文件文本”更适合喂给模型，因为它保留了路径、语言、符号和切片。
type CodeContext = {
  path: string;      // 文件路径。
  language: string;  // 编程语言，例如 ts/java/python，用来决定解析策略。
  imports: string[]; // import/require/use 列表，帮助模型理解依赖。
  symbols: string[]; // 文件里定义的类、函数、接口等符号名。
  relevantSlices: Array<{
    startLine: number; // 切片开始行。
    endLine: number;   // 切片结束行。
    text: string;      // 这段源码。
  }>;
};

// ReadFileInput = 读取文件工具的输入。
// startLine/endLine 让模型只读关键范围，节省 token。
type ReadFileInput = {
  path: string;       // 要读取的文件路径，必须在 workspace 内。
  startLine?: number; // 可选：从第几行开始，1-based。
  endLine?: number;   // 可选：读到第几行，1-based。
};

// readFileTool = 带行号的文件读取工具。
// 带行号的输出能帮助后续 edit/diff/code review 精确定位。
export async function readFileTool(input: ReadFileInput, ctx: ToolContext) {
  // 路径解析和越界检查。
  const abs = resolveWorkspacePath(ctx.cwd, input.path);

  // 教学版默认 UTF-8。真实系统还要处理大文件、二进制、编码。
  const text = await readFile(abs, "utf8");
  const lines = text.split(/\r?\n/);

  // 没传行号就读全文件；真实系统要对全文件读取设置大小上限。
  const start = input.startLine ?? 1;
  const end = input.endLine ?? lines.length;

  // slice 用 0-based 下标，所以 start - 1。
  // 输出时重新加回真实行号。
  const selected = lines
    .slice(start - 1, end)
    .map((line, index) => `${start + index}: ${line}`)
    .join("\n");

  return {
    summary: `Read ${input.path}:${start}-${end}`,
    content: selected,
    metadata: {
      totalLines: lines.length, // 文件总行数，方便模型判断是否还要继续读。
      startLine: start,         // 本次读取开始行。
      endLine: end              // 本次读取结束行。
    }
  };
}

// GitContext = 当前工作区的 Git 状态摘要。
// 它的意义是提醒模型：哪些文件是用户已经改过的，不能随便覆盖。
type GitContext = {
  branch: string;          // 当前分支。
  changedFiles: string[];  // 已修改但未必 staged 的文件。
  stagedFiles: string[];   // 已暂存文件。
  untrackedFiles: string[];// Git 还没跟踪的新文件。
};

Git status:
- branch: feature/agent-cli
- modified: src/queryEngine.ts
- untracked: docs/notes.md

Use grep when you know a symbol, error message, function name, or config key.
Use glob when you know a filename pattern.
Prefer grep/glob before reading many files.
Do not read large generated files unless necessary.

No matches.

No matches for "QueryEngine" in src/**/*.ts.
Suggestions:
- Try case-insensitive search.
- Search for "query" or "runAgent".
- Use glob to inspect candidate files.

// ContextRetriever = 上下文检索器接口。
// 输入是用户任务和工作区信息，输出是“模型可以行动的证据包”。
type ContextRetriever = {
  // retrieve 不追求返回最多内容，而是返回最相关、最省 token 的内容。
  retrieve(task: UserTask, ctx: WorkspaceContext): Promise<ContextPackage>;
};

// classifyTask = 教学版任务分类器。
// 它决定后续搜索策略：bugfix 优先看错误栈，review 优先看 git diff。
function classifyTask(input: string): TaskKind {
  // 统一小写，方便匹配英文关键词。
  const lower = input.toLowerCase();

  // 报错/失败类任务。
  if (lower.includes("error") || lower.includes("exception") || lower.includes("失败")) return "bugfix";

  // 代码审查类任务。
  if (lower.includes("review") || lower.includes("代码审查")) return "review";

  // 重构类任务。
  if (lower.includes("重构") || lower.includes("rename")) return "refactor";

  // 配置/环境变量类任务。
  if (lower.includes("配置") || lower.includes("env")) return "config";

  // 默认按功能修改处理。
  return "feature";
}

// Candidate = 一个“可能相关文件”的候选项。
// 注意它还不是最终上下文，只是待排序、待读取的候选。
type Candidate = {
  path: string;                         // 文件路径。
  reason: string;                       // 为什么被召回，方便 trace 和调试。
  scoreSignals: Record<string, number>; // 打分信号，例如 gitChanged=1、stackTrace=1。
};

// generateCandidates = 候选召回阶段。
// 原则：召回可以宽一点，后面排序和预算读取会负责收窄。
async function generateCandidates(task: UserTask, ctx: WorkspaceContext): Promise<Candidate[]> {
  const candidates: Candidate[] = [];

  // 用户当前改动过的文件通常很相关。
  candidates.push(...await fromGitChangedFiles(ctx));

  // 如果用户贴了错误栈，从栈里的文件路径召回。
  candidates.push(...await fromErrorStack(task));

  // 从用户输入里抽关键词做 grep。
  candidates.push(...await fromGrepKeywords(task));

  // 从用户输入里抽可能的文件名/模块名做 glob。
  candidates.push(...await fromFileName(task));

  // 最近会话读过/改过的文件，也可能继续相关。
  candidates.push(...await fromRecentSessionFiles(ctx));

  // 测试名、失败用例名常常能直接定位预期行为。
  candidates.push(...await fromTestNames(task));

  // 同一个文件可能被多种方式召回，要合并信号而不是重复返回。
  return dedupeCandidates(candidates);
}

// ReadBudget = 上下文读取预算。
// 候选可以很多，但真正读进模型的内容必须受控。
type ReadBudget = {
  maxFiles: number;       // 最多读几个文件。
  maxTotalTokens: number; // 这些文件切片总共最多多少 token。
  maxLinesPerFile: number;// 单个文件最多读多少行。
};

// rankCandidate = 对候选文件精排。
// 它把多个信号加权，得到“应该先读哪个文件”的分数。
function rankCandidate(c: Candidate, task: UserTask): number {
  let score = 0;

  // 错误栈直接命中的文件，优先级最高。
  score += 10 * (c.scoreSignals.stackTrace ?? 0);

  // 当前 Git 改动文件也很关键，避免无视用户已有修改。
  score += 8 * (c.scoreSignals.gitChanged ?? 0);

  // 文件名匹配通常比正文偶然命中更强。
  score += 6 * (c.scoreSignals.fileNameMatch ?? 0);

  // 符号名匹配，例如函数/类/接口名命中。
  score += 5 * (c.scoreSignals.symbolMatch ?? 0);

  // 测试文件说明预期行为，修 bug 时很有价值。
  score += 3 * (c.scoreSignals.testFile ?? 0);

  // 最近读过的文件有连续任务相关性。
  score += 2 * (c.scoreSignals.recentFile ?? 0);

  // 生成文件、依赖目录、构建产物通常不该优先读。
  if (isGenerated(c.path)) score -= 20;
  if (isVendored(c.path)) score -= 20;

  // 巨大文件降低优先级，除非有更强信号。
  if (isHugeFile(c.path)) score -= 5;
  if (pathLooksLikeBuildOutput(c.path)) score -= 15;

  return score;
}

["src/a.ts", "src/b.ts"]

Candidate files:
1. src/auth/loginService.ts
   score: 22
   reasons: symbol match "login", route keyword "auth", referenced by failing test

2. test/auth/loginService.test.ts
   score: 18
   reasons: failing test name, assertion mentions "phone code"

// SymbolRecord = 代码里的一个“符号”。
// 符号可以是类、函数、方法、接口、常量等，是结构搜索的基础。
type SymbolRecord = {
  name: string; // 符号名，例如 LoginService、handleSubmit。
  kind: "class" | "function" | "method" | "interface" | "type" | "constant"; // 符号类型。
  path: string;       // 所在文件。
  startLine: number;  // 定义开始行。
  endLine: number;    // 定义结束行。
  signature?: string; // 函数签名/方法签名，帮助模型快速理解入参返回。
  exports?: boolean;  // 是否对外导出。导出符号影响面更大。
};

// CallGraphEdge = 调用图的一条边。
// 表示 from 这个符号通过某种关系依赖 to 这个符号。
type CallGraphEdge = {
  from: SymbolRef; // 调用方/依赖方。
  to: SymbolRef;   // 被调用方/被依赖方。
  kind: "call" | "new" | "implements" | "extends" | "route"; // 关系类型。
};

findReferences(symbol): SymbolRef[]
findCallees(symbol): SymbolRef[]

// CodeSlice = 真正喂给模型的一段代码证据。
// 它不是整文件，而是“路径 + 行号 + 片段 + 为什么读它”。
type CodeSlice = {
  path: string;       // 文件路径。
  startLine: number;  // 片段开始行。
  endLine: number;    // 片段结束行。
  text: string;       // 片段文本。
  reason: string;     // 为什么这个片段相关，例如 around matched line 42。
  symbols: string[];  // 片段里涉及的符号。
};

// sliceAroundLine = 围绕某个命中行读取上下文。
// 常用于 grep 命中后，给模型看命中行前后若干行。
function sliceAroundLine(file: TextFile, line: number, radius = 30): CodeSlice {
  // start/end 是 1-based 行号，注意不要越界。
  const start = Math.max(1, line - radius);
  const end = Math.min(file.lines.length, line + radius);

  return {
    path: file.path,       // 来源文件。
    startLine: start,      // 片段开始行。
    endLine: end,          // 片段结束行。
    // 数组 slice 用 0-based，所以 start 要减 1。
    text: file.lines.slice(start - 1, end).join("\n"),
    // reason 会进入 trace，方便复盘为什么读这段。
    reason: `around matched line ${line}`,
    // 找出这段范围内有哪些函数/类，给模型更强结构感。
    symbols: findSymbolsInRange(file.symbols, start, end)
  };
}

// ContextPackage = 一次检索最终交给模型的上下文包。
// 它把任务、工作区、证据、缺口都结构化，避免散乱粘贴。
type ContextPackage = {
  task: string; // 用户任务原文。
  workspace: {
    cwd: string;            // 当前项目根目录。
    branch?: string;        // 当前 Git 分支。
    changedFiles: string[]; // 已改文件，提醒模型不要覆盖用户改动。
  };
  evidence: EvidenceBlock[]; // 已读取的证据块。
  openQuestions: string[];   // 仍缺失的信息，例如“还没找到测试命令”。
  omitted: {
    reason: string; // 为什么没放进上下文，例如 token budget。
    count: number;  // 被省略的数量。
  }[];
};

// EvidenceBlock = 给模型看的一个证据块。
type EvidenceBlock = {
  id: string;                // 证据 ID，例如 E1，方便模型引用。
  path: string;              // 来源文件。
  lines?: [number, number];  // 行号范围。
  reason: string;            // 为什么这段证据相关。
  content: string;           // 证据正文。
};

Use the evidence blocks below. When proposing an edit, cite the evidence id
that justifies the change. If evidence is insufficient, ask for or retrieve
more context before editing.

// Hybrid Search 教学版：
// lexical 负责精确词，semantic 负责语义相近，symbols 负责代码结构。
const lexical = await grepSearch(query);
const semantic = await vectorSearch(query);
const symbols = await symbolSearch(query);

// RRF 把多个搜索器的排名融合，避免单一搜索器误判。
const merged = reciprocalRankFusion([lexical, semantic, symbols]);

// rrf = Reciprocal Rank Fusion 的单项得分。
// rank 越靠前，得分越高；k 用来平滑，避免第一名压倒一切。
function rrf(rank: number, k = 60) {
  return 1 / (k + rank);
}

// SearchFailure = 搜索失败时返回给模型的结构化信息。
// 目的：让模型知道已经试过什么，下一步该换什么关键词/范围。
type SearchFailure = {
  query: string; // 原始搜索词。
  scope: string; // 搜索范围，例如 src/**/*.ts。
  attempts: Array<{
    tool: "grep" | "glob" | "symbol" | "semantic"; // 用了哪个搜索器。
    query: string;       // 这次实际搜索词。
    resultCount: number; // 返回数量。
  }>;
  suggestions: string[]; // 建议下一步，例如换同义词、扩大范围、先看入口文件。
};

No matches for "QueryEngine" in src/**/*.ts.
Tried:
- grep "QueryEngine": 0
- glob "**/*Query*": 0

Suggestions:
- search "engine"
- search "runAgent"
- inspect package entrypoints

// RetrievalCase = 检索评估用例。
// 用来测试“给定任务时，retriever 能不能把正确文件排到前面”。
type RetrievalCase = {
  task: string;              // 用户任务描述。
  expectedFiles: string[];   // 正确答案应该包含的文件。
  expectedSymbols?: string[];// 可选：正确答案应该包含的函数/类。
};

// 这个测试验证：用户说“手机号验证码登录”时，检索器能找到实现和测试。
it("retrieves auth service for phone login task", async () => {
  // 执行检索。
  const result = await retriever.retrieve({
    text: "把登录改成手机号验证码"
  }, workspace);

  // 前 5 个候选里应该有业务实现。
  expect(topPaths(result, 5)).toContain("src/auth/loginService.ts");

  // 前 5 个候选里也应该有测试，测试说明预期行为。
  expect(topPaths(result, 5)).toContain("test/auth/loginService.test.ts");
});

// IndexedChunk = 被检索系统持久化的一段上下文。
// 它必须能在检索后重新校验，不能只保存一段裸文本。
type IndexedChunk = {
  chunkId: string;              // 稳定 chunk ID，用于 trace 和 eval。
  sourcePath: string;           // 源文件路径。
  language: string;             // 文件语言，用于选择 parser/ranker。
  startLine: number;            // chunk 在源文件中的起始行。
  endLine: number;              // chunk 在源文件中的结束行。
  contentHash: string;          // chunk 内容 hash，用于发现旧索引。
  fileHash: string;             // 整个文件 hash，用于快速判断文件是否变过。
  indexVersion: string;         // 索引器版本，parser/chunker 改动后必须更新。
  symbols: string[];            // chunk 内出现的函数、类、接口、标题。
  updatedAt: string;            // 写入索引的时间。
};

{
  "phase": "retrieve_validate",           // 检索后的证据校验阶段。
  "query": "修复登录接口 500",             // 用户任务或改写后的查询。
  "candidateChunkId": "auth-LoginService-42", // 初召回候选。
  "sourcePath": "src/auth/LoginService.java", // 候选来源。
  "indexedHash": "sha256:old",            // 索引中记录的 hash。
  "currentHash": "sha256:new",            // 当前文件实时 hash。
  "decision": "re-read-current-file",     // 因为 hash 变化，所以重新读取当前文件。
  "selected": true                        // 校验后是否进入最终上下文。
}

// LanguageProfile = 针对不同语言/框架的检索画像。
// Spring Boot、Node、Python 的入口文件和生成目录都不一样，不能一套规则打天下。
type LanguageProfile = {
  routePatterns: RegExp[]; // 路由入口模式，例如 Spring 的 @GetMapping。
  testPatterns: string[];  // 测试文件命名，例如 **/*Test.java。
  generatedDirs: string[]; // 生成目录，例如 target/、dist/。
  configFiles: string[];   // 常见配置文件，例如 application.yml。
};