codebase-explorer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Explorer

代码库探索工具

Investigates an existing codebase topic by topic, grounds every finding in actual source code, and persists results for long-term reference.

逐个主题调查现有代码库，所有调查结果均基于实际源代码，并将结果持久化以供长期参考。

Output Mode

输出模式

Active:
obsidian
(default)

Available:

obsidian

notion

files

Users can change this at any time — e.g. "use Notion", "save to files". When the mode is set, read the corresponding reference file before any documentation step:

```
obsidian
```
→ read
```
references/output-obsidian.md
```
```
notion
```
→ read
```
references/output-notion.md
```
```
files
```
→ read
```
references/output-files.md
```

当前激活模式：
obsidian
（默认）

可选模式：

obsidian

notion

files

用户可随时更改模式——例如：“使用Notion”、“保存到文件”。设置模式后，在执行任何文档步骤前，请先阅读对应的参考文件：

```
obsidian
```
→ 阅读
```
references/output-obsidian.md
```
```
notion
```
→ 阅读
```
references/output-notion.md
```
```
files
```
→ 阅读
```
references/output-files.md
```

Session Setup

会话设置

Before starting, establish with the user:

The reference repo — codebase to study and its local path
The goal — what they're building and what they need to learn
Output destination — confirm or change the active output mode, then read its reference file

Immediately create the investigation index using

assets/templates/index.md

. This becomes the navigation hub for the entire session.

开始前，需与用户确认以下信息：

参考仓库——要研究的代码库及其本地路径
目标——用户要开发的内容以及需要学习的要点
输出目标——确认或更改当前激活的输出模式，然后阅读其参考文件

立即使用

assets/templates/index.md

创建调查索引，该索引将作为整个会话的导航中心。

Core Constraints

核心约束

Non-negotiable throughout the session:

Source code is ground truth — read the actual files, never hallucinate APIs or behavior
Cite file:line — every claim ties back to a specific location:
```
src/agents/tools/web-search.ts:215
```
One topic at a time — complete, document, then move to the next
Concise — direct answers with code references, no padding or hedging

会话全程需严格遵守以下规则：

源代码为唯一依据——读取实际文件，绝不能虚构API或行为
标注文件:行号——所有结论必须关联到具体位置：
```
src/agents/tools/web-search.ts:215
```
逐个主题推进——完成一个主题的调查并记录后，再进行下一个
简洁明了——直接给出答案并附上代码参考，避免冗余或含糊表述

Investigation Loop

调查循环

For each topic the user asks about:

针对用户询问的每个主题：

1. Find relevant code

1. 查找相关代码

Use targeted searches before reading anything:

Glob: **/web-search*.ts          → find files by name pattern
Grep: "resolveSearchProvider"    → find specific function definitions
Read: specific file once located

Prefer Glob + Grep over broad reads. Only read files after confirming they're relevant.

在读取文件前，先使用定向搜索：

Glob: **/web-search*.ts          → 按文件名模式查找文件
Grep: "resolveSearchProvider"    → 查找特定函数定义
Read: 定位到文件后再读取

优先使用Glob + Grep组合，而非大范围读取文件。仅在确认文件相关后再读取。

2. Read and understand

2. 读取并理解

Read source files directly. For long files (>300 lines), read in sections using offset + limit. Focus on:

Entry point functions and their signatures
Data flow (what goes in, what comes out)
Key types and interfaces
Configuration structures

直接读取源文件。对于长文件（超过300行），可按分段读取（使用偏移量+限制行数）。重点关注：

入口函数及其签名
数据流（输入、输出内容）
关键类型与接口
配置结构

3. Answer concisely

3. 简洁作答

Structure every answer as:

What it does (1-2 sentences)
How it works (key implementation with file:line references)
Key files (list with one-line descriptions)
Notable design decisions or trade-offs

所有答案需按以下结构组织：

功能说明（1-2句话）
实现原理（关键实现细节，附带文件:行号参考）
关键文件（列表形式，每个文件配一句话说明）
值得注意的设计决策或权衡

4. Persist findings

4. 持久化调查结果

After answering, create a note using

assets/templates/topic-note.md

and write it using the active output mode (see

references/output-{mode}.md

for exact operations).

Then update the investigation index: add a

✅

entry with a 2-3 sentence summary and a link to the new note.

作答完成后，使用

assets/templates/topic-note.md

创建笔记，并通过当前激活的输出模式写入（具体操作请查看

references/output-{mode}.md

）。

然后更新调查索引：添加一个带

✅

的条目，包含2-3句话的摘要以及指向新笔记的链接。

5. Cross-link

5. 交叉链接

Link related notes to each other and back to the index. The index is the hub. See the active output mode reference for the correct linking syntax.

将相关笔记相互链接，并关联回索引。索引为核心导航中心。请根据当前激活的输出模式参考文件使用正确的链接语法。

Investigation Areas (AI Agent Codebases)

调查领域（AI Agent代码库）

When the user hasn't specified a topic, suggest from this list in rough dependency order:

Agentic loop — how the agent processes a message, calls tools, retries
Tool system — how tools are defined, registered, and executed
Streaming / feedback — how intermediate results reach the user in real-time
Short-term memory — session context, compaction, context window management
Long-term memory — RAG, vector search, embedding providers
Sub-agents / parallelism — spawning, communication, lifecycle management
Error handling — retry logic, fallbacks, recovery strategies
Configuration — how the system is configured and extended

For other codebase types, adapt the topic list to the domain.

当用户未指定主题时，可按以下大致依赖顺序推荐：

Agent循环机制——Agent如何处理消息、调用工具、重试
工具系统——工具的定义、注册与执行方式
流式传输/反馈——中间结果如何实时传递给用户
短期记忆——会话上下文、压缩、上下文窗口管理
长期记忆——RAG、向量搜索、嵌入提供商
子Agent/并行处理——Agent的生成、通信、生命周期管理
错误处理——重试逻辑、降级方案、恢复策略
配置管理——系统的配置与扩展方式

对于其他类型的代码库，请根据领域调整主题列表。

Session Continuity

会话连续性

When resuming an investigation in a new session:

Read the active output mode reference:
```
references/output-{mode}.md
```
Load the existing investigation index to recall what was covered
Confirm with the user what to investigate next
Continue the loop — don't re-document already-covered topics

在新会话中恢复调查时：

读取当前激活输出模式的参考文件：
```
references/output-{mode}.md
```
加载已有的调查索引，回顾已完成的内容
与用户确认接下来要调查的主题
继续执行调查循环——无需重新记录已覆盖的主题

Templates

模板

assets/templates/

```
index.md
```
— investigation index / README template
```
topic-note.md
```
— per-topic deep-dive note template

assets/templates/

目录下包含：

```
index.md
```
—— 调查索引/ README模板
```
topic-note.md
```
—— 单主题深入调查笔记模板