Smart Explore 基准测试¶

Smart Explore 利用 tree-sitter AST 解析，通过三个 MCP 工具——smart_search、smart_outline 和 smart_unfold——提供结构化代码导航。本报告记录了与标准 Explore agent（使用 Glob、Grep 和 Read 工具）的严格 A/B 对比，以量化 token 节省与质量权衡。

执行摘要¶

方法论¶

测试环境¶

• 代码库：claude-mem（src/ 目录，194 个 TypeScript 文件，1,206 个解析符号）
• 模型：两种方法均使用 Claude Opus 4.6
• 测量方式：来自工具响应元数据的 token 计数（Explore agent 使用 total_tokens，Smart Explore 使用自报的 ~N tokens for folded view）

控制条件¶

Explore agent 被明确告知：“不要使用 smart_search、smart_outline 或 smart_unfold 工具。只能使用 Glob、Grep 和 Read 工具。” 这一限制在最初一轮中被证明是必要的，因为当时 agent 会投机性地使用 Smart Explore 工具，导致对比无效。

查询¶

我们选择了五个查询来代表常见的探索任务：

1. “session processing” —— 横跨多个服务的横切功能
2. “shutdown” —— 涉及 6+ 个文件的基础设施关注点
3. “hook registration” —— 关于插件系统的架构问题
4. “sqlite database” —— 数据层中针对特定技术的搜索
5. “worker-service.ts outline” —— 单个大文件（1,225 行）的结构理解

第 1 轮：发现¶

“有什么？在哪里？” —— 在整个代码库中查找相关文件和符号。

结果¶

各自的返回结果¶

Smart Explore（每次 1 次工具调用）：返回 10 个带签名、行号和 JSDoc 摘要的排序符号，以及所有匹配文件的折叠结构视图，显示每个函数/类/接口且主体已折叠。

Explore Agent（每次 15-37 次工具调用）：生成综合性的叙述报告，包含架构图、设计模式分析、数据流说明、完整接口转储和文件结构图。解释性文字明显更多。

分析¶

token 差距在范围狭窄的查询（“hook registration”为 26.8 倍）中最大，因为 Explore agent 会读取多个完整文件来查找相对较少的相关符号。对于范围广泛的查询（“session processing”为 11.8 倍），更多文件内容与查询相关，从而缩小了比例。

Smart Explore 始终如一的单次工具调用模式意味着其成本是可预测的。Explore agent 的成本随其读取的文件数量以及综合处理量而变化——在可比范围内从 15 到 37 次工具调用不等。

第 2 轮：定向读取¶

“给我看看这个具体的函数。” —— 在发现阶段之后读取已知符号的实现。

基于第 1 轮的结果，我们选择了五个具体符号作为自然的深入目标：

结果¶

分析¶

比例与符号大小成反比。 最小的函数（initialize，27 行）显示出最大的差距，为 55.8 倍，因为 Explore agent 仍然会读取整个 235 行的文件来提取 27 行。最大的方法（startSessionProcessor，158 行）则缩小到 10 倍，因为文件中“有用”的内容更多了。

Smart Unfold 返回了更完整的代码。 对于最长的方法（158 行），Explore agent 用 "... error handling continues ..." 截断了错误处理部分，而 smart_unfold 返回了完整的实现。这是因为 smart_unfold 按 AST 节点边界提取，无论符号大小如何都能保证完整性。

对于定向读取，Explore agent 不会增加任何独特信息。 当您已经知道文件路径和符号名时，agent 的开销纯粹是浪费——它读取文件、定位函数，然后将其原样返回。唯一增加的只是一段简短的解释性文字。

组合工作流¶

实际的工作流是先进行发现，再进行定向读取。以下是理解单个函数的端到端成本对比：

Smart Explore：搜索与展开¶

smart_search("shutdown", path="./src")     ~3,852 tokens
smart_unfold("GracefulShutdown.ts", "performGracefulShutdown")  ~700 tokens
────────────────────────────────────────────────────────────────
Total: ~4,552 tokens (2 tool calls, under 3 seconds)

Explore Agent：单一查询¶

"Find and explain the shutdown logic"      ~51,523 tokens
────────────────────────────────────────────────────────────────
Total: ~51,523 tokens (18 tool calls, ~43 seconds)

端到端比率：11.3 倍——Smart Explore 工作流能提供实际源代码，而 Explore Agent 给出的只是叙述式摘要，可能会改写或截断内容。

质量评估¶

两种方法并非绝对地谁优谁劣，它们针对不同的目标进行优化。

Smart Explore 优势¶

• 可预测的成本：每个操作只需 1 次工具调用，Token 范围稳定
• 完整的源代码：基于 AST 的提取保证完整的符号主体
• 结构上下文：折叠视图显示匹配文件中的每个符号
• 速度：亚秒级响应支持快速迭代
• 可组合性：搜索、大纲和展开可以自然地串联使用

Explore Agent 优势¶

• 综合理解：生成架构说明、数据流图和设计模式分析
• 跨文件解释：能够连接多个文件中的概念，这是单独读取符号无法做到的
• 入门引导质量：输出读起来像文档，而不是原始代码
• 错误处理洞察：识别需要阅读多个相关函数才能发现的边界情况和设计决策
• 无需先前知识：无需知道文件路径或符号名称即可回答开放式问题

按任务类型的质量对比¶

何时使用哪种方式¶

在以下情况使用 Smart Explore：

• 你知道自己要找什么（函数名、概念、文件）
• 你需要源代码，而不是解释
• 你在快速迭代（读取、修改、再读取）
• Token 预算很重要（大型代码库、长时间会话）
• 你需要一眼看清文件结构

在以下情况使用 Explore Agent：

• 你需要综合性的跨文件理解
• 问题是开放式的（“这个系统是如何工作的？”）
• 你在编写文档或架构评审
• 你需要理解为什么，而不仅仅是是什么
• 你在上手一个不熟悉的代码库

在以下情况两者结合使用：

• 先用 Smart Explore 进行发现和导航
• 仅在需要多文件综合的深度分析时才升级到 Explore Agent
• 这种混合方式能获得大部分 Token 节省，同时保留在需要时进行深度理解的能力

Token 成本参考¶

各工作流的节省¶