项目理解skill-v1
This commit is contained in:
闫旭隆
408
codebase_architecture_analyzer_v1/reference/quick-scan.md
Normal file
408
codebase_architecture_analyzer_v1/reference/quick-scan.md
Normal file
@ -0,0 +1,408 @@
|
||||
# 快速扫描指南
|
||||
|
||||
本指南提供项目快速扫描的详细步骤。
|
||||
|
||||
## 目标
|
||||
|
||||
在 30 秒内识别：
|
||||
- 项目类型
|
||||
- 主要编程语言
|
||||
- 核心框架
|
||||
- 子系统组成
|
||||
|
||||
---
|
||||
|
||||
## 步骤 1: 运行技术栈检测脚本（推荐）
|
||||
|
||||
**使用自动化脚本**：
|
||||
|
||||
```bash
|
||||
python ~/.claude/skills/codebase-architecture-analyzer/scripts/detect_tech_stack.py .
|
||||
```
|
||||
|
||||
**脚本输出示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"project_path": "/path/to/project",
|
||||
"stacks": [
|
||||
{
|
||||
"language": "Python",
|
||||
"frameworks": ["FastAPI", "LangGraph"],
|
||||
"config_file": "pyproject.toml",
|
||||
"version": "3.11"
|
||||
},
|
||||
{
|
||||
"language": "TypeScript",
|
||||
"frameworks": ["React", "Next.js"],
|
||||
"version": ">=18"
|
||||
}
|
||||
],
|
||||
"docker": {
|
||||
"containerized": true,
|
||||
"compose": true,
|
||||
"services": ["backend", "frontend", "redis"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**从输出提取信息**：
|
||||
|
||||
- `stacks[].language` - 主要编程语言
|
||||
- `stacks[].frameworks` - 核心框架列表
|
||||
- `stacks[].version` - 语言/运行时版本
|
||||
- `docker.services` - Docker 服务列表（如果有）
|
||||
|
||||
**脚本支持的语言**：
|
||||
- Python (FastAPI, Django, Flask, LangGraph, CrewAI)
|
||||
- JavaScript/TypeScript (React, Vue, Next.js, Express, NestJS)
|
||||
- Go (Gin, Gorilla Mux, Fiber)
|
||||
- Rust (Actix Web, Rocket, Axum)
|
||||
- Java (Spring Boot, Quarkus)
|
||||
|
||||
---
|
||||
|
||||
## 步骤 1.5: 分析依赖关系（可选，用于深度分析）
|
||||
|
||||
**使用依赖分析脚本**：
|
||||
|
||||
```bash
|
||||
python ~/.claude/skills/codebase-architecture-analyzer/scripts/extract_dependencies.py .
|
||||
```
|
||||
|
||||
**脚本输出示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"project_path": ".",
|
||||
"analyses": [
|
||||
{
|
||||
"language": "Python",
|
||||
"files_analyzed": 45,
|
||||
"total_imports": 23,
|
||||
"third_party_imports": ["fastapi", "pydantic", "langchain", "openai"],
|
||||
"declared_dependencies": ["fastapi", "pydantic", "langchain", "openai", "requests"],
|
||||
"undeclared_usage": [],
|
||||
"unused_dependencies": ["requests"]
|
||||
},
|
||||
{
|
||||
"language": "JavaScript/TypeScript",
|
||||
"dependencies": ["react", "next", "tailwindcss"],
|
||||
"dev_dependencies": ["typescript", "@types/react", "eslint"],
|
||||
"total_dependencies": 6
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键信息提取**：
|
||||
|
||||
- `third_party_imports` - 实际使用的第三方包
|
||||
- `declared_dependencies` - 在配置文件中声明的依赖
|
||||
- `undeclared_usage` - **缺失的依赖**（代码中使用了，但未在 requirements.txt/pyproject.toml 中声明）
|
||||
- `unused_dependencies` - **冗余的依赖**（声明了但代码中未使用）
|
||||
|
||||
**使用场景**：
|
||||
|
||||
✅ **推荐使用**（当满足以下条件时）：
|
||||
- 需要验证依赖完整性
|
||||
- 准备部署到生产环境
|
||||
- 项目有复杂的依赖关系
|
||||
- 发现依赖相关的 bug
|
||||
|
||||
⚠️ **可跳过**（当满足以下条件时）：
|
||||
- 快速了解项目即可
|
||||
- 项目很小（< 10 个文件）
|
||||
- 只关注整体架构
|
||||
|
||||
**输出解读**：
|
||||
|
||||
1. **缺失依赖警告**：如果 `undeclared_usage` 不为空，说明需要更新 requirements.txt
|
||||
2. **冗余依赖清理**：如果 `unused_dependencies` 不为空，可以移除不需要的依赖
|
||||
3. **依赖健康度**：`total_imports` vs `declared_dependencies` 的比例
|
||||
|
||||
---
|
||||
|
||||
## 步骤 2: 检测技术栈（手动方法）
|
||||
|
||||
如果脚本无法运行或需要更详细分析，使用以下手动方法：
|
||||
|
||||
### Python 项目
|
||||
|
||||
**识别文件**：
|
||||
```bash
|
||||
# 优先级从高到低
|
||||
1. pyproject.toml # 现代 Python 项目（Poetry/Hatch）
|
||||
2. setup.py # 传统 Python 包
|
||||
3. requirements.txt # 依赖清单
|
||||
4. Pipfile # Pipenv 项目
|
||||
5. environment.yml # Conda 项目
|
||||
```
|
||||
|
||||
**提取信息**：
|
||||
```bash
|
||||
# 从 pyproject.toml 提取
|
||||
cat pyproject.toml | grep "python =" # Python 版本
|
||||
cat pyproject.toml | grep "\[tool.poetry.dependencies\]" -A 20 # 依赖
|
||||
|
||||
# 从 requirements.txt 提取
|
||||
cat requirements.txt | grep -E "fastapi|django|flask|langgraph"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### JavaScript/TypeScript 项目
|
||||
|
||||
**识别文件**：
|
||||
```bash
|
||||
1. package.json # Node.js 项目
|
||||
2. yarn.lock # Yarn 包管理
|
||||
3. pnpm-lock.yaml # pnpm 包管理
|
||||
4. tsconfig.json # TypeScript 配置
|
||||
```
|
||||
|
||||
**提取信息**：
|
||||
```bash
|
||||
# 从 package.json 提取
|
||||
cat package.json | grep "\"react\"\|\"vue\"\|\"express\"\|\"next\""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Go 项目
|
||||
|
||||
**识别文件**：
|
||||
```bash
|
||||
1. go.mod # Go modules
|
||||
2. go.sum # 依赖锁文件
|
||||
```
|
||||
|
||||
**提取信息**：
|
||||
```bash
|
||||
cat go.mod | grep "require" -A 20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Rust 项目
|
||||
|
||||
**识别文件**：
|
||||
```bash
|
||||
1. Cargo.toml # Rust 项目配置
|
||||
2. Cargo.lock # 依赖锁文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Java 项目
|
||||
|
||||
**识别文件**：
|
||||
```bash
|
||||
1. pom.xml # Maven 项目
|
||||
2. build.gradle # Gradle 项目
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤 3: 扫描目录结构
|
||||
|
||||
### 列出顶层目录
|
||||
|
||||
```bash
|
||||
ls -d */ | head -20
|
||||
```
|
||||
|
||||
### 识别子系统模式
|
||||
|
||||
| 目录名 | 子系统类型 |
|
||||
|-------|-----------|
|
||||
| `frontend/`, `ui/`, `web/`, `client/` | 前端 |
|
||||
| `backend/`, `api/`, `server/` | 后端 |
|
||||
| `agents/`, `workers/` | Agent 系统 |
|
||||
| `services/` + 多个子目录 | 微服务 |
|
||||
| `src/components/` | React/Vue 组件 |
|
||||
| `app/` | Next.js/Django 应用 |
|
||||
|
||||
---
|
||||
|
||||
## 步骤 4: 检测关键配置文件
|
||||
|
||||
### Docker 相关
|
||||
|
||||
```bash
|
||||
# docker-compose.yml → 多服务架构
|
||||
cat docker-compose.yml | grep "services:" -A 50
|
||||
|
||||
# Dockerfile → 容器化应用
|
||||
ls -la | grep Dockerfile
|
||||
```
|
||||
|
||||
### 环境配置
|
||||
|
||||
```bash
|
||||
# .env.example → 环境变量配置
|
||||
cat .env.example | grep -E "DATABASE_URL|REDIS_URL|API_KEY"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤 5: 识别项目规模
|
||||
|
||||
### 统计代码文件
|
||||
|
||||
```bash
|
||||
# 统计各语言文件数量
|
||||
find . -type f -name "*.py" | wc -l
|
||||
find . -type f -name "*.ts" -o -name "*.tsx" | wc -l
|
||||
find . -type f -name "*.go" | wc -l
|
||||
```
|
||||
|
||||
### 估算代码规模
|
||||
|
||||
```bash
|
||||
# 使用 cloc（如果已安装）
|
||||
cloc . --exclude-dir=node_modules,venv,.git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 输出格式模板
|
||||
|
||||
```
|
||||
✓ 项目类型: [AI 研究助手 / Web 应用 / CLI 工具 / ...]
|
||||
✓ 主语言: Python 3.11 (156 个文件)
|
||||
✓ 次要语言: TypeScript (89 个文件)
|
||||
✓ 核心框架:
|
||||
- 后端: FastAPI 0.104.1
|
||||
- 前端: React 18.2.0
|
||||
- AI: LangGraph 0.2.5
|
||||
✓ 子系统:
|
||||
- frontend/ (React + TypeScript)
|
||||
- backend/ (FastAPI + Python)
|
||||
- agents/ (LangGraph)
|
||||
✓ 容器化: 是（docker-compose.yml）
|
||||
✓ 代码规模: 约 12,500 行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见框架识别规则
|
||||
|
||||
### Python Web 框架
|
||||
|
||||
```python
|
||||
依赖中包含:
|
||||
- fastapi → FastAPI
|
||||
- django → Django
|
||||
- flask → Flask
|
||||
- starlette → Starlette
|
||||
- aiohttp → aiohttp
|
||||
```
|
||||
|
||||
### Python AI 框架
|
||||
|
||||
```python
|
||||
依赖中包含:
|
||||
- langgraph → LangGraph
|
||||
- crewai → CrewAI
|
||||
- autogen → AutoGen
|
||||
- langchain → LangChain
|
||||
- transformers → Hugging Face
|
||||
```
|
||||
|
||||
### JavaScript 框架
|
||||
|
||||
```json
|
||||
dependencies 中包含:
|
||||
- "react" → React
|
||||
- "vue" → Vue.js
|
||||
- "next" → Next.js
|
||||
- "express" → Express.js
|
||||
- "nestjs" → NestJS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速判断项目类型
|
||||
|
||||
### CLI 工具
|
||||
|
||||
**特征**：
|
||||
- 存在 `cli.py`, `main.py`, `cmd/` 目录
|
||||
- 依赖包含 `click`, `typer`, `argparse`
|
||||
- `pyproject.toml` 中有 `[project.scripts]`
|
||||
|
||||
### Web 应用
|
||||
|
||||
**特征**：
|
||||
- 存在 `routes.py`, `views.py`, `app.py`
|
||||
- 依赖包含 `fastapi`, `django`, `express`
|
||||
- 存在 `assets/`, `static/` 目录
|
||||
|
||||
### AI/ML 项目
|
||||
|
||||
**特征**：
|
||||
- 存在 `models/`, `agents/`, `pipelines/`
|
||||
- 依赖包含 `tensorflow`, `pytorch`, `langchain`
|
||||
- 存在 `notebooks/` 目录（Jupyter）
|
||||
|
||||
### 数据工程项目
|
||||
|
||||
**特征**：
|
||||
- 存在 `etl/`, `pipelines/`, `dags/`
|
||||
- 依赖包含 `airflow`, `prefect`, `dbt`
|
||||
- 存在 `sql/`, `queries/` 目录
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 问题 1: 无法识别项目类型
|
||||
|
||||
**解决方案**：
|
||||
1. 查看 README.md 的描述
|
||||
2. 搜索常见入口文件：`main.*`, `index.*`, `app.*`
|
||||
3. 查看 git 提交历史：`git log --oneline | head -20`
|
||||
|
||||
### 问题 2: 多语言混合项目
|
||||
|
||||
**解决方案**：
|
||||
- 统计各语言文件数量，确定主次
|
||||
- 识别前后端分离：`frontend/` + `backend/`
|
||||
|
||||
---
|
||||
|
||||
## 完整示例
|
||||
|
||||
```bash
|
||||
# 1. 检测配置文件
|
||||
ls -la | grep -E "package.json|pyproject.toml|go.mod|Cargo.toml"
|
||||
|
||||
# 输出: pyproject.toml, package.json (前后端分离项目)
|
||||
|
||||
# 2. 读取 Python 依赖
|
||||
cat pyproject.toml | grep -A 30 dependencies
|
||||
|
||||
# 输出: fastapi, langgraph, openai (AI Web 应用)
|
||||
|
||||
# 3. 读取 JS 依赖
|
||||
cat package.json | grep -A 20 dependencies
|
||||
|
||||
# 输出: react, typescript (React 前端)
|
||||
|
||||
# 4. 扫描目录
|
||||
ls -d */
|
||||
|
||||
# 输出: frontend/, backend/, agents/, docs/
|
||||
|
||||
# 5. 统计代码
|
||||
find backend -name "*.py" | wc -l # 156 个文件
|
||||
find frontend -name "*.ts*" | wc -l # 89 个文件
|
||||
|
||||
# 最终识别结果:
|
||||
✓ 项目类型: AI 驱动的 Web 应用
|
||||
✓ 主语言: Python (后端 + AI)
|
||||
✓ 次要语言: TypeScript (前端)
|
||||
✓ 核心框架: FastAPI + LangGraph + React
|
||||
✓ 架构: 前后端分离 + Multi-Agent
|
||||
```
|
||||
Reference in New Issue
Block a user