智能探索基准
Smart Explore 使用 tree-sitter AST 解析，通过三种 MCP 工具提供结构化代码导航：smart_search、smart_outline 和 smart_unfold。本报告记录了与标准 Explore 代理（使用 Glob、Grep 和 Read 工具）的严格 A/B 对比，以量化 token 节省和质量权衡。
执行摘要
| 指标 | 智能探索 | 探索代理 | 优势 |
|---|---|---|---|
| 发现（跨文件搜索） | 约 14,200 个 token | 约 252,500 个 token | 便宜 17.8 倍 |
| 目标读取（特定符号） | 约 5,650 个 token | 约 109,400 个 token | 便宜 19.4 倍 |
| 端到端（搜索 读取） | 约 4,200 token | 约 45,000 token | 便宜 10-12 倍 |
| 完整性 | 5/5 完整源代码返回 | 4/5（最长方法被截断） | 智能探索更可靠 |
| 速度 | 每次调用低于2秒 | 每次调用5-66秒 | 快10-30倍 |
方法论
测试环境
- 代码库：claude-mem（
src/目录，194 个 TypeScript 文件，1,206 个解析符号） - 模型：Claude Opus 4.6，用于两种方法
- 测量：来自工具响应元数据的 token 计数（Explore 代理为
total_tokens，Smart Explore 自报为~N tokens for folded view）
控制
探索代理被明确指示：“不要使用 smart_search、smart_outline 或 smart_unfold 工具。只使用 Glob、Grep 和 Read 工具。” 在初始回合中，代理机会性地使用了 Smart Explore 工具，从而使比较无效，因此验证这是必要的。
查询
选择了五个查询来代表常见的探索任务：
- “会话处理” —— 跨越多个服务的通用功能
- “关闭” -- 涉及6个文件的基础设施问题
- “钩子注册”——关于插件系统的架构问题
- “sqlite数据库”——跨数据层的技术特定搜索
- “worker-service.ts 大纲”——单个大文件（1,225 行）的结构理解
第1轮：发现
“存在什么，它在哪里？”——在整个代码库中查找相关文件和符号。
结果
| 查询 | 智能探索 | 探索代理 | 比率 | 探索工具调用 |
|---|---|---|---|---|
| 会话处理 | ~4,391 t | 51,659 t | 11.8倍 | 15 |
| 停机 | ~3,852 tokens | 51,523 个 token | 13.4倍 | 18 |
| 挂钩注册 | ~1,930 tokens | 51,688 个 token | 26.8倍 | 37 |
| sqlite 数据库 | ~2,543 t | 58,633 t | 23.1倍 | 16 |
| Worker 服务概览 | ~1,500 tokens | 38,973 个 token | 26.0 倍 | 15 |
| 总计 | ~14,216 tokens | 252,476 个 token | 17.8倍 | 101 |
各自回来了什么
智能探索（每次调用 1 个工具）：10 个带有签名、行号和 JSDoc 摘要的排名符号，以及显示所有匹配文件折叠结构视图的每个函数/类/接口（主体折叠）。
探索代理（每次调用 15-37 个工具）：综合的叙述报告，包括架构图、设计模式分析、数据流说明、完整接口转储和文件结构图。说明性文字明显更多。
分析
token 差距在范围较窄的查询（“钩子注册”为 26.8 倍）中最大，因为 Explore 代理需要读取多个完整文件才能找到相对少量的相关符号。对于范围较广的查询（“会话处理”为 11.8 倍），更多的文件内容是相关的，从而缩小了比例。
Smart Explore 一贯的单工具调用模式意味着其成本是可预测的。Explore 代理的成本则取决于它读取的文件数量和合成的内容——在可比范围内，其工具调用次数范围为 15 到 37 次。
第二轮：针对性阅读
“给我看这个具体的函数。”——在发现已知符号后阅读其实现。
根据第一轮的结果，选择了五个特定符号作为自然钻取目标：
| 目标符号 | 文件 | 行数 |
|---|---|---|
SessionManager.initializeSession | services/worker/SessionManager.ts | 135 |
performGracefulShutdown | services/infrastructure/GracefulShutdown.ts | 48 |
hookCommand | cli/hook-command.ts | 45 |
DatabaseManager.initialize | services/sqlite/Database.ts | 27 |
WorkerService.startSessionProcessor | services/worker-service.ts | 158 |
结果
| 符号 | 智能展开 | 探索代理 | 比例 | 完整性 |
|---|---|---|---|---|
| 初始化会话 (135 行) | ~1,800 t | 27,816 t | 15.5 倍 | 两者都返回完整源代码 |
| 执行优雅关闭 (48 行) | ~700 t | 19,621 t | 28.0x | 两者都返回完整源代码 |
| hookCommand（45 行） | ~650 t | 18,680 t | 28.7 倍 | 两者都返回完整源代码 |
| DatabaseManager.initialize（27 行） | ~400 t | 22,334 t | 55.8 倍 | 两者都返回完整源代码 |
| startSessionProcessor（158 行） | ~2,100 t | 20,906 t | 10.0x | 智能展开：完成。探索：已截断 |
| 总计 | ~5,650 tokens | 109,357 个 token | 19.4倍 |
分析
比例与符号大小成反比。 最小的函数（initialize，27行）在55.8倍时显示出最大的差距，因为探索代理仍然需要读取整个235行的文件来提取27行。最大的函数（startSessionProcessor，158行）缩小到10倍，因为文件中更多的部分是“有用的”。
智能展开返回了更完整的代码。 对于最长的方法（158行），Explore 代理在错误处理部分使用“...错误处理继续...”，而 smart_unfold 返回了完整的实现。这是因为 smart_unfold 按 AST 节点边界提取，保证了无论符号大小如何都能完整。
探索代理对目标读取没有增加任何独特信息。 当你已经知道文件路径和符号名称时，代理的开销完全是浪费——它读取文件，定位函数，然后回显出来。唯一的额外内容是简短的解释段落。
组合工作流程
现实的工作流程是先探索，然后再进行有针对性的阅读。以下是理解单个功能的端到端成本比较：
智能探索：搜索 展开
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)探索代理：单次查询
"Find and explain the shutdown logic" ~51,523 tokens
────────────────────────────────────────────────────────────────
Total: ~51,523 tokens (18 tool calls, ~43 seconds)端到端比率：11.3倍 —— Smart Explore 工作流程为您提供实际的源代码，而 Explore 代理则为您提供可能会改写或截断的文字摘要。
质量评估
哪种方法都不是普遍更好的。它们针对不同的结果进行优化。
智能探索优势
- 可预测的成本：每次操作调用 1 次工具，token 范围一致
- 完整源代码：基于 AST 的提取保证完整的符号体
- 结构上下文：折叠视图显示匹配文件中的每个符号
- 速度：亚秒级响应实现快速迭代
- 可组合性：自然地搜索、概述和展开链条
探索代理优势
- 综合理解：生成架构叙述、数据流图和设计模式分析
- 跨切解释：连接单个符号读取无法联系的文件中的概念
- 入职质量：输出读起来像文档，而不是原始代码
- 错误处理洞察：识别需要阅读多个相关函数的边缘情况和设计决策
- 无需先前知识：可以在不知道文件路径或符号名称的情况下回答开放性问题
按任务类型分类的质量
| 任务 | 更好的工具 | 原因 |
|---|---|---|
| “X 定义在哪里？” | 智能探索 | 一次调用，精确答案 |
| “这个文件里有什么函数？” | 智能探索 | 大纲返回完整的结构图 |
| “显示这个函数” | 智能探索 | 展开返回完整源代码，绝不截断 |
| “功能 X 是如何端到端运作的？” | 探索代理 | 阅读多个文件并综合叙述 |
| “这里使用了哪些设计模式？” | 探索代理 | 需要阅读和理解，而不仅仅是提取 |
| “帮我理解这个代码库” | 探索代理 | 生成入职质量的文档 |
何时使用哪一个
在以下情况下使用智能探索：
- 你知道自己在寻找什么（函数名、概念、文件）
- 你需要的是源代码，而不是解释
- 你正在快速迭代（读取，修改，再次读取）
- token 预算很重要（大型代码库、长时间会话）
- 你需要一目了然的文件结构
使用探索代理的情况：
- 你需要综合的跨领域理解
- 这个问题是开放式的（“这个系统是如何工作的？”）
- 你正在编写文档或架构评审
- 你需要理解为什么，而不仅仅是什么
- 你正在熟悉一个不熟悉的代码库
在以下情况下同时使用：
- 从智能探索开始进行发现和导航
- 仅在需要多文件综合进行深入分析时升级至探索代理
- 这种混合方法在大多数情况下节省了token，同时在需要时仍能保持对深度理解的访问
token经济学参考
| 操作 | token | 使用案例 |
|---|---|---|
smart_search | 2,000-6,000 | 跨文件符号发现 |
smart_outline | 1,000-2,000 | 单文件结构图 |
smart_unfold | 400-2,100 | 单符号完整来源 |
smart_search smart_unfold | 3,000-8,000 | 端到端：查找并阅读 |
| 探索代理（有针对性） | 18,000-28,000 | 单一功能带解释 |
| 探索代理（跨领域） | 39,000-59,000 | 架构级理解 |
| 阅读（完整文件） | 8,000-15,000 | 完整文件内容 |
按工作流程节省
| 工作流 | 智能探索 | 传统 | 节省 |
|---|---|---|---|
| 理解一个文件 | 概要 展开 (~3,100 字) | 阅读完整文件 (~12,000 字) | 4倍 |
| 在代码库中查找函数 | 搜索 (~3,500 次) | 探索代理 (~50,000 次) | 14倍 |
| 查找并阅读特定函数 | 搜索 展开 (~4,500 条) | 探索代理 (~50,000 条) | 11次 |
| 导航一个 1,200 行的文件 | 大纲 (~1,500 字) | 阅读完整文件 (~12,000 字) | 8 倍 |