smart-explore

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Smart Explore

智能探索

Structural code exploration using AST parsing. This skill overrides your default exploration behavior. While this skill is active, use smart_search/smart_outline/smart_unfold as your primary tools instead of Read, Grep, and Glob.

Core principle: Index first, fetch on demand. Give yourself a map of the code before loading implementation details. The question before every file read should be: "do I need to see all of this, or can I get a structural overview first?" The answer is almost always: get the map.

基于AST解析的结构化代码探索工具。本技能会覆盖你默认的探索行为。 当该技能处于激活状态时，请将smart_search/smart_outline/smart_unfold作为你的主要工具使用，替代Read、Grep和Glob。

核心原则： 先建索引，按需获取。在加载实现细节前先拿到代码的整体地图。每次读取文件前都应该先问自己："我真的需要查看全部内容吗，还是可以先获取结构化概览？"答案几乎总是：先拿地图。

Your Next Tool Call

你的下一步工具调用

This skill only loads instructions. You must call the MCP tools yourself. Your next action should be one of:

smart_search(query="<topic>", path="./src")    -- discover files + symbols across a directory
smart_outline(file_path="<file>")              -- structural skeleton of one file
smart_unfold(file_path="<file>", symbol_name="<name>")  -- full source of one symbol

Do NOT run Grep, Glob, Read, or find to discover files first.

smart_search

walks directories, parses all code files, and returns ranked symbols in one call. It replaces the Glob → Grep → Read discovery cycle.

本技能仅加载说明，你必须自行调用MCP工具。你的下一步操作应该是以下之一：

smart_search(query="<topic>", path="./src")    -- discover files + symbols across a directory
smart_outline(file_path="<file>")              -- structural skeleton of one file
smart_unfold(file_path="<file>", symbol_name="<name>")  -- full source of one symbol

请勿首先运行Grep、Glob、Read或find来查找文件。

smart_search

会遍历目录、解析所有代码文件，并在单次调用中返回排序后的符号结果。它替代了Glob → Grep → Read的探索流程。

3-Layer Workflow

三层工作流

Step 1: Search -- Discover Files and Symbols

步骤1：搜索 -- 查找文件和符号

smart_search(query="shutdown", path="./src", max_results=15)

Returns: Ranked symbols with signatures, line numbers, match reasons, plus folded file views (~2-6k tokens)

-- Matching Symbols --
  function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)
  function httpShutdown (services/infrastructure/HealthMonitor.ts:92)
  method WorkerService.shutdown (services/worker-service.ts:846)

-- Folded File Views --
  services/infrastructure/GracefulShutdown.ts (7 symbols)
  services/worker-service.ts (12 symbols)

This is your discovery tool. It finds relevant files AND shows their structure. No Glob/find pre-scan needed.

Parameters:

```
query
```
(string, required) -- What to search for (function name, concept, class name)
```
path
```
(string) -- Root directory to search (defaults to cwd)
```
max_results
```
(number) -- Max matching symbols, default 20, max 50
```
file_pattern
```
(string, optional) -- Filter to specific files/paths

smart_search(query="shutdown", path="./src", max_results=15)

返回结果： 带函数签名、行号、匹配原因的排序符号列表，以及折叠文件视图（约2-6k Token）

-- Matching Symbols --
  function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)
  function httpShutdown (services/infrastructure/HealthMonitor.ts:92)
  method WorkerService.shutdown (services/worker-service.ts:846)

-- Folded File Views --
  services/infrastructure/GracefulShutdown.ts (7 symbols)
  services/worker-service.ts (12 symbols)

这是你的探索工具，它能找到相关文件并展示其结构，无需提前运行Glob/find预扫描。

参数：

```
query
```
（字符串，必填）-- 要搜索的内容（函数名、概念、类名）
```
path
```
（字符串）-- 搜索的根目录（默认是cwd）
```
max_results
```
（数字）-- 最大匹配符号数，默认20，最高50
```
file_pattern
```
（字符串，可选）-- 过滤特定文件/路径

Step 2: Outline -- Get File Structure

步骤2：大纲 -- 获取文件结构

smart_outline(file_path="services/worker-service.ts")

Returns: Complete structural skeleton -- all functions, classes, methods, properties, imports (~1-2k tokens per file)

Skip this step when Step 1's folded file views already provide enough structure. Most useful for files not covered by the search results.

Parameters:

```
file_path
```
(string, required) -- Path to the file

smart_outline(file_path="services/worker-service.ts")

返回结果： 完整的结构骨架 -- 所有函数、类、方法、属性、导入（每个文件约1-2k Token）

如果步骤1的折叠文件视图已经提供了足够的结构信息，可以跳过此步骤。该方法最适用于搜索结果未覆盖的文件。

参数：

```
file_path
```
（字符串，必填）-- 文件路径

Step 3: Unfold -- See Implementation

步骤3：展开 -- 查看实现

Review symbols from Steps 1-2. Pick the ones you need. Unfold only those:

smart_unfold(file_path="services/worker-service.ts", symbol_name="shutdown")

Returns: Full source code of the specified symbol including JSDoc, decorators, and complete implementation (~400-2,100 tokens depending on symbol size). AST node boundaries guarantee completeness regardless of symbol size — unlike Read + agent summarization, which may truncate long methods.

Parameters:

```
file_path
```
(string, required) -- Path to the file (as returned by search/outline)
```
symbol_name
```
(string, required) -- Name of the function/class/method to expand

查看步骤1-2得到的符号，选择你需要的内容，仅展开这些部分：

smart_unfold(file_path="services/worker-service.ts", symbol_name="shutdown")

返回结果： 指定符号的完整源代码，包括JSDoc、decorators和完整实现（根据符号大小约400-2100 Token）。AST节点边界保证无论符号大小都能返回完整内容 -- 不像Read + Agent总结的方式可能会截断长方法。

参数：

```
file_path
```
（字符串，必填）-- 文件路径（和搜索/大纲返回的路径一致）
```
symbol_name
```
（字符串，必填）-- 要展开的函数/类/方法名称

When to Use Standard Tools Instead

什么时候应该使用标准工具

Use these only when smart_* tools are the wrong fit:

Grep: Exact string/regex search ("find all TODO comments", "where is
```
ensureWorkerStarted
```
defined?")
Read: Small files under ~100 lines, non-code files (JSON, markdown, config)
Glob: File path patterns ("find all test files")
Explore agent: When you need synthesized understanding across 6+ files, architecture narratives, or answers to open-ended questions like "how does this entire system work end-to-end?" Smart-explore is a scalpel — it answers "where is this?" and "show me that." It doesn't synthesize cross-file data flows, design decisions, or edge cases across an entire feature.

For code files over ~100 lines, prefer smart_outline + smart_unfold over Read.

仅当smart_*工具不适用时使用这些工具：

Grep： 精确字符串/正则搜索（"查找所有TODO注释"、"
```
ensureWorkerStarted
```
定义在哪里？"）
Read： 100行以下的小文件、非代码文件（JSON、markdown、配置文件）
Glob： 匹配文件路径模式（"查找所有测试文件"）
Explore Agent： 当你需要跨6个以上文件的综合理解、架构描述，或者回答"整个系统的端到端工作流程是怎样的？"这类开放性问题时。智能探索是手术刀 -- 它回答"这在哪里？"和"给我看这个内容"，它不会综合跨文件的数据流、设计决策或者整个功能的边界情况。

对于超过100行的代码文件，优先使用smart_outline + smart_unfold而不是Read。

Workflow Examples

工作流示例

Discover how a feature works (cross-cutting):

1. smart_search(query="shutdown", path="./src")
   -> 14 symbols across 7 files, full picture in one call
2. smart_unfold(file_path="services/infrastructure/GracefulShutdown.ts", symbol_name="performGracefulShutdown")
   -> See the core implementation

Navigate a large file:

1. smart_outline(file_path="services/worker-service.ts")
   -> 1,466 tokens: 12 functions, WorkerService class with 24 members
2. smart_unfold(file_path="services/worker-service.ts", symbol_name="startSessionProcessor")
   -> 1,610 tokens: the specific method you need
Total: ~3,076 tokens vs ~12,000 to Read the full file

Write documentation about code (hybrid workflow):

1. smart_search(query="feature name", path="./src")    -- discover all relevant files and symbols
2. smart_outline on key files                           -- understand structure
3. smart_unfold on important functions                  -- get implementation details
4. Read on small config/markdown/plan files             -- get non-code context

Use smart_* tools for code exploration, Read for non-code files. Mix freely.

Exploration then precision:

1. smart_search(query="session", path="./src", max_results=10)
   -> 10 ranked symbols: SessionMetadata, SessionQueueProcessor, SessionSummary...
2. Pick the relevant one, unfold it

了解一个功能的工作原理（跨文件场景）：

1. smart_search(query="shutdown", path="./src")
   -> 单次调用就得到7个文件中的14个符号，获取全局全貌
2. smart_unfold(file_path="services/infrastructure/GracefulShutdown.ts", symbol_name="performGracefulShutdown")
   -> 查看核心实现

导航大文件：

1. smart_outline(file_path="services/worker-service.ts")
   -> 1466 Token：12个函数，包含24个成员的WorkerService类
2. smart_unfold(file_path="services/worker-service.ts", symbol_name="startSessionProcessor")
   -> 1610 Token：你需要的特定方法
总计：约3076 Token，而Read完整文件需要约12000 Token

编写代码相关文档（混合工作流）：

1. smart_search(query="feature name", path="./src")    -- 查找所有相关文件和符号
2. 对核心文件执行smart_outline                           -- 理解结构
3. 对重要函数执行smart_unfold                            -- 获取实现细节
4. Read小型配置/markdown/规划文件                         -- 获取非代码上下文

代码探索使用smart_*工具，非代码文件使用Read，可以自由混合使用。

先探索再精准定位：

1. smart_search(query="session", path="./src", max_results=10)
   -> 10个排序后的符号：SessionMetadata、SessionQueueProcessor、SessionSummary...
2. 选择相关的符号，展开查看

Token Economics

Token开销对比

Approach	Tokens	Use Case
smart_outline	~1,000-2,000	"What's in this file?"
smart_unfold	~400-2,100	"Show me this function"
smart_search	~2,000-6,000	"Find all X across the codebase"
search + unfold	~3,000-8,000	End-to-end: find and read (the primary workflow)
Read (full file)	~12,000+	When you truly need everything
Explore agent	~39,000-59,000	Cross-file synthesis with narrative

4-8x savings on file understanding (outline + unfold vs Read). 11-18x savings on codebase exploration vs Explore agent. The narrower the query, the wider the gap — a 27-line function costs 55x less to read via unfold than via an Explore agent, because the agent still reads the entire file.

方案	Token消耗	适用场景
smart_outline	~1000-2000	"这个文件里有什么？"
smart_unfold	~400-2100	"给我看这个函数"
smart_search	~2000-6000	"在代码库中查找所有X"
搜索+展开	~3000-8000	端到端：查找并阅读（核心工作流）
Read（完整文件）	~12000+	当你确实需要全部内容时
Explore Agent	~39000-59000	带描述的跨文件综合分析

文件理解（大纲+展开对比Read）可节省4-8倍Token，代码库探索对比Explore Agent可节省11-18倍Token。查询范围越窄，节省幅度越大 -- 通过unfold读取一个27行的函数比通过Explore Agent读取成本低55倍，因为Agent仍然会读取整个文件。