---
name: exploration-method
description: 代码库探索与外部检索方法论——Read/Grep/Glob「先入口后发散」的探索路径、外部检索、「路径+行号」举证纪律、结论先行的汇报结构。Use when 需要探索陌生代码库、定位功能实现、理解调用链，或检索外部资料并产出可溯源的探索结论。
when_to_use: 任何「先摸清现状」类任务：定位功能实现位置、理解模块调用链、盘点代码结构、查证外部文档/范式。产出物每条关于代码的论断必须带「路径+行号」举证；汇报一律结论先行。探索结论通常直接喂给同包 solution-planning skill 做方案规划。
language: zh
---

# Exploration Method — 探索与举证方法论

定位：一次探索任务的执行规程。目标不是「看过代码」，而是产出一份**每条论断都可被第三方按图索骥复核**的探索结论。

## 1. 探索路径：先入口后发散

不要从随机文件开始泛读。按固定顺序推进：

1. **找入口**：先定位系统的入口面——README / 主函数 / 路由注册表 / 工具或服务的注册中心（registry）/ 构建文件。入口告诉你「有哪些东西存在」。
2. **顺调用链**：从入口沿调用关系向下钻——谁注册了什么、谁调用了谁、数据从哪进哪出。每深入一层都记录锚点。
3. **后发散**：入口与主干链清楚之后，才向边缘模块发散（辅助工具、测试、配置）。发散阶段用模式搜索补全遗漏面。

反模式：拿到任务就全文泛读、或对单个关键词反复 Grep 而不建立整体结构认知。

## 2. 工具纪律

- **代码库探索三件套**：`Glob` 按文件名模式定位文件（禁 `find`/`ls`）；`Grep` 按内容模式搜索（禁 bash grep/rg）；`Read` 读具体文件。三者分工：Glob 回答「在哪」，Grep 回答「哪里有这个符号/字符串」，Read 回答「这里具体是什么」。
- **外部检索**：Bash curl 检索找来源、抓原文。引用外部结论必须带 URL；搜索结果可能过时，关键事实以抓取的原文为准。
- **大文件策略**：日志/长文件用 Grep 的上下文参数或 Read 的 offset/limit 分段，不全文吞。

## 3. 举证纪律（路径+行号）

**每一条关于代码事实的论断，都必须附 `文件路径:行号` 锚点**，使读者可一键跳转复核。

- 格式：`<项目内相对路径>:<起止行>`（示例形如 `src/service/registry.scala:12-75`），范围用起止行。
- 给不出行号的论断 = 未验证的猜测——要么去查实补上锚点，要么显式标注「（未验证）」。禁止把猜测写成事实。
- 引用文档/外部资料同理：给可定位的出处（文档路径+节号 / URL）。
- 盘点类产出（文件清单、工具表、配置表）每一行都带锚点；汇总统计（「共 N 个」）给出计数方法。

## 4. 汇报结构：结论先行

探索报告的固定骨架：

1. **结论**（一段话）：这次探索最重要的发现是什么，直接回答任务问题。
2. **关键证据**（表或清单）：支撑结论的锚点列表，`路径:行号` / URL。
3. **细节与结构**（分节）：模块分解、调用链、数据流——供需要深入的读者展开。
4. **未决项**：没查清的、存疑的、需要用户或上游补充的，显式列出，不藏起来。

禁忌：按探索的时间顺序记流水账；把结论埋在细节之后；只给结论不给锚点。

## 5. 会话纪律

探索与后续方案规划通常在**单次调用**内完成（探索 → （需要时）可视化展示 → 规划 → 与用户确认），不拆成多轮等指令。存在多种合理方向或关键信息缺失时，用 `AskUserQuestion` 一次问清（澄清细则见同包 `solution-planning` 的「方案前置澄清」节），拿到回答后继续推进，不在纯文本里抛问句等回复。