smart-explore

Smart Explore

使用 AST 解析进行结构化代码探索。此技能会覆盖你的默认探索行为。 此技能启用期间，请优先使用 smart_search/smart_outline/smart_unfold，而不是 Read、Grep 和 Glob。

核心原则： 先建立索引，按需获取内容。在加载实现细节之前，先为代码绘制地图。每次读取文件前都应先问自己：“我需要查看全部内容吗？还是可以先获取结构概览？”答案几乎总是：先获取地图。

下一次工具调用

此技能只会加载说明。你必须自行调用 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 的发现流程。

三层工作流

第 1 步：搜索——发现文件和符号

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（字符串，可选）——筛选特定文件/路径

第 2 步：概览——获取文件结构

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

返回： 完整的结构框架——所有函数、类、方法、属性、导入（每个文件约 1–2k 个 token）

跳过此步骤：如果第 1 步的折叠文件视图已提供足够的结构信息。对于搜索结果未涵盖的文件，此步骤最有用。

参数：

• file_path（字符串，必需）——文件路径

第 3 步：展开——查看实现

查看第 1–2 步中找到的符号。挑选需要的符号，仅展开这些符号：

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

返回： 指定符号的完整源代码，包括 JSDoc、装饰器和完整实现（根据符号大小约为 400–2,100 个 token）。AST 节点边界可确保内容完整，无论符号大小如何；而 Read + Agent 摘要可能会截断较长的方法。

参数：

• file_path（字符串，必需）——文件路径（由 search/outline 返回）
• symbol_name（字符串，必需）——要展开的函数/类/方法名称

何时改用标准工具

仅在 smart_* 工具不适用时使用以下工具：

• Grep： 搜索精确字符串/正则表达式（“查找所有 TODO 注释”、“ensureWorkerStarted 定义在哪里？”）
• Read： 读取 100 行以下的小文件、非代码文件（JSON、markdown、配置）
• Glob： 按文件路径模式搜索（“查找所有测试文件”）
• Explore agent： 需要综合理解 6 个以上文件、了解架构全貌，或回答“整个系统如何端到端运作？”等开放式问题时使用。Smart-explore 是手术刀——用于回答“这个在哪里？”和“把那个展示给我”。它不会综合跨文件数据流、设计决策，也不会梳理整个功能的边界情况。

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

工作流示例

探索功能的运作方式（跨多个模块）：

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

浏览大型文件：

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

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

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

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

先探索，再精准查看：

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

令牌经济

方法	令牌数	使用场景
smart_outline	~1,000-2,000	“这个文件里有什么？”
smart_unfold	~400-2,100	“显示这个函数”
smart_search	~2,000-6,000	“在整个代码库中查找所有 X”
search + unfold	~3,000-8,000	端到端：查找并阅读（主要工作流）
Read (full file)	~12,000+	确实需要查看全部内容时
Explore agent	~39,000-59,000	跨文件综合并生成叙述

理解文件可节省 4-8 倍 的令牌（outline + unfold 对比 Read）。探索代码库可节省 11-18 倍 的令牌（对比 Explore agent）。查询范围越窄，差距越大——通过 unfold 阅读一个 27 行的函数，成本比使用 Explore agent 低 55 倍，因为该 Agent 仍会读取整个文件。

语言支持

Smart-explore 使用 tree-sitter AST 解析进行结构分析。对于不在其语言支持范围内的文件内容，请使用 rg 等文本搜索工具。

内置语言

语言	扩展名
JavaScript	.js, .mjs, .cjs
TypeScript	.ts
TSX / JSX	.tsx, .jsx
Python	.py, .pyw
Go	.go
Rust	.rs
Ruby	.rb
Java	.java
C	.c, .h
C++	.cpp, .cc, .cxx, .hpp, .hh

无法识别扩展名的文件不会为 smart_outline 或 smart_unfold 生成结构化符号。smart_search 并非通用文件内容搜索：其扩展名筛选器可能会排除不受支持的文件，而没有符号的文件只能通过路径匹配。请使用 rg 或其他文本搜索工具搜索文件内容。

其他语言

目前无法通过 .claude-mem.json 注册自定义 tree-sitter 语法。在项目的 node_modules 中安装语法包并不会为其扩展名启用结构解析。必须先将支持添加到随附的语言映射、语法包和符号查询中，smart_outline 和 smart_unfold 才能使用该语言。

Markdown 特殊支持

Markdown 文件（.md、.mdx）除通用纯文本回退处理外，还会获得特殊处理：

• smart_outline — 将标题（#、##、###）提取为符号树。可用它浏览长文档，而无需读取整个文件。
• smart_search — 除正文外，也会搜索代码围栏中的内容，因此在 ```ts ``` 代码块中搜索函数名时，会按预期工作。
• smart_unfold — 展开标题章节，而不是函数体；每个章节会作为一个文本块返回，范围从当前标题到下一个同级标题之前。
• Frontmatter — YAML frontmatter（开头的 --- 分隔符之间的行）会以合成的 frontmatter 符号包含在 smart_outline 输出中，因此无需读取整个文件即可查看 title: 和 description: 等元数据。