codebase-navigator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Navigator

代码库导航器

Use this skill FIRST when exploring code, finding files, or understanding project structure.

在探索代码、查找文件或理解项目结构时，请优先使用本技能。

Quick Start

快速开始

Search scripts (preferred)

搜索脚本（推荐使用）

Run the bundled scripts for common searches:

bash

undefined

运行内置脚本进行常见搜索：

bash

undefined

Find functions/methods

查找函数/方法

./scripts/search.sh functions <pattern>

Find React components

查找React组件

./scripts/search.sh components <pattern>

Find API endpoints

查找API端点

./scripts/search.sh endpoints

Trace an API flow end-to-end

端到端追踪API流程

./scripts/trace.sh api-flow <endpoint>

Trace a data field from backend to UI

追踪数据字段从后端到UI的流向

./scripts/trace.sh data-flow <field_name>

Find component hierarchy

查找组件层级

./scripts/trace.sh component-tree <ComponentName>


Scripts are at: `.agents/skills/codebase-navigator/scripts/`

./scripts/trace.sh component-tree <ComponentName>


脚本路径：`.agents/skills/codebase-navigator/scripts/`

Direct ripgrep patterns

直接使用ripgrep规则

When you need something the scripts don't cover:

bash

undefined

当脚本无法满足需求时，可直接使用ripgrep：

bash

undefined

Find any symbol

查找任意符号

rg --no-heading -n '\bMySymbol\b' apps/

Python function definitions

Python函数定义

rg --no-heading -n '(def|async def) my_function' apps/backend/ --type py

React component usage

React组件使用情况

rg --no-heading -n '<MyComponent' apps/frontend/ --glob '*.tsx'

Type definitions

类型定义

rg --no-heading -n '(type|interface) MyType' apps/frontend/ --glob '*.ts'

Pydantic models

Pydantic模型

rg --no-heading -n 'class My.*BaseModel' apps/backend/ --type py

API route handlers

API路由处理器

Imports of a module

模块导入情况

rg --no-heading -n 'from.*my_module.*import|import.*my_module' apps/

undefined

rg --no-heading -n 'from.*my_module.*import|import.*my_module' apps/

undefined

Architecture Overview

架构概览

Read these docs for full understanding:

Need	Document
Backend architecture	`docs/agent/architecture/backend-architecture.md`
Frontend architecture	`docs/agent/architecture/frontend-architecture.md`
API contracts	`docs/agent/apis/front-end-apis.md`
API flow maps	`docs/agent/apis/api-flow-maps.md`
Full doc index	`docs/agent/README.md`

阅读以下文档以全面理解项目：

需求	文档
后端架构	`docs/agent/architecture/backend-architecture.md`
前端架构	`docs/agent/architecture/frontend-architecture.md`
API契约	`docs/agent/apis/front-end-apis.md`
API流程映射	`docs/agent/apis/api-flow-maps.md`
完整文档索引	`docs/agent/README.md`

Project Layout

项目布局

apps/
├── backend/app/
│   ├── main.py              # FastAPI entry, CORS, routers
│   ├── config.py            # Pydantic settings from env
│   ├── database.py          # TinyDB wrapper
│   ├── llm.py               # LiteLLM wrapper (multi-provider AI)
│   ├── routers/             # API endpoints
│   │   ├── config_router.py # GET/PUT /api/v1/config
│   │   ├── health_router.py # GET /api/v1/health
│   │   ├── resume_router.py # CRUD /api/v1/resumes
│   │   └── jobs_router.py   # CRUD /api/v1/jobs
│   ├── services/            # Business logic
│   │   ├── parser.py        # Resume parsing
│   │   └── improver.py      # AI resume improvement
│   ├── schemas/             # Pydantic request/response models
│   └── prompts/             # LLM prompt templates
│
└── frontend/
    ├── app/                 # Next.js pages (dashboard, builder, tailor, print)
    ├── components/          # Reusable UI components
    ├── lib/                 # API client, utilities, i18n
    ├── hooks/               # Custom React hooks
    └── messages/            # i18n translations (en, es, zh, ja)

apps/
├── backend/app/
│   ├── main.py              # FastAPI入口、CORS配置、路由
│   ├── config.py            # 基于环境变量的Pydantic配置
│   ├── database.py          # TinyDB封装
│   ├── llm.py               # LiteLLM封装（多供应商AI）
│   ├── routers/             # API端点
│   │   ├── config_router.py # GET/PUT /api/v1/config
│   │   ├── health_router.py # GET /api/v1/health
│   │   ├── resume_router.py # CRUD /api/v1/resumes
│   │   └── jobs_router.py   # CRUD /api/v1/jobs
│   ├── services/            # 业务逻辑
│   │   ├── parser.py        # 简历解析
│   │   └── improver.py      # AI简历优化
│   ├── schemas/             # Pydantic请求/响应模型
│   └── prompts/             # LLM提示模板
│
└── frontend/
    ├── app/                 # Next.js页面（仪表盘、编辑器、定制器、打印页）
    ├── components/          # 可复用UI组件
    ├── lib/                 # API客户端、工具函数、国际化
    ├── hooks/               # 自定义React hooks
    └── messages/            # 国际化翻译（英文、西班牙文、中文、日文）

Common Search Workflows

常见搜索工作流

"Where is X defined?"

“X在哪里定义？”

bash

./scripts/search.sh functions my_function
./scripts/search.sh components MyComponent
./scripts/search.sh classes MyClass
./scripts/search.sh types MyType

bash

./scripts/search.sh functions my_function
./scripts/search.sh components MyComponent
./scripts/search.sh classes MyClass
./scripts/search.sh types MyType

"What calls X?"

“哪些地方调用了X？”

bash

./scripts/search.sh usage my_function
./scripts/search.sh deps my_file.py

bash

./scripts/search.sh usage my_function
./scripts/search.sh deps my_file.py

"How does data flow for feature X?"

“功能X的数据流是怎样的？”

bash

./scripts/trace.sh api-flow resumes
./scripts/trace.sh data-flow personalInfo
./scripts/trace.sh component-tree ResumeEditor

bash

./scripts/trace.sh api-flow resumes
./scripts/trace.sh data-flow personalInfo
./scripts/trace.sh component-tree ResumeEditor

"What API routes exist?"

“有哪些API路由？”

bash

./scripts/search.sh api-routes

bash

./scripts/search.sh api-routes

"What environment config is used?"

“使用了哪些环境配置？”

bash

./scripts/search.sh config

bash

./scripts/search.sh config

"What needs fixing?"

“哪些地方需要修复？”

bash

./scripts/search.sh todos

bash

./scripts/search.sh todos

Key Entry Points

关键入口点

What	File
Backend startup	`apps/backend/app/main.py`
Frontend pages	`apps/frontend/app/`
API client	`apps/frontend/lib/api.ts` or `lib/api-client.ts`
Design tokens	`apps/frontend/app/globals.css`
Resume schemas	`apps/backend/app/schemas/`
LLM prompts	`apps/backend/app/prompts/`

内容	文件
后端启动入口	`apps/backend/app/main.py`
前端页面	`apps/frontend/app/`
API客户端	`apps/frontend/lib/api.ts` 或 `lib/api-client.ts`
设计令牌	`apps/frontend/app/globals.css`
简历模型	`apps/backend/app/schemas/`
LLM提示模板	`apps/backend/app/prompts/`

Tips

提示

Always check
```
docs/agent/
```
before deep-diving into code
Use
```
rg --type py
```
for Python,
```
rg --glob '*.tsx'
```
for React components
When tracing a feature, start from the API route and follow imports
Check
```
apps/frontend/components/
```
for reusable UI patterns
Check
```
apps/backend/app/services/
```
for business logic

在深入代码之前，请先查看
```
docs/agent/
```
目录下的文档
针对Python代码使用
```
rg --type py
```
，针对React组件使用
```
rg --glob '*.tsx'
```
追踪功能时，从API路由开始并跟随导入关系
可复用UI模式请查看
```
apps/frontend/components/
```
业务逻辑请查看
```
apps/backend/app/services/
```