# 快速扫描指南

本指南提供项目快速扫描的详细步骤。

## 目标

在 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
```