AIEC_Skills/codebase_architecture_analyzer_v1/reference/quick-scan.md

快速扫描指南

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

目标

在 30 秒内识别：

• 项目类型
• 主要编程语言
• 核心框架
• 子系统组成

---

步骤 1: 运行技术栈检测脚本（推荐）

使用自动化脚本：

python ~/.claude/skills/codebase-architecture-analyzer/scripts/detect_tech_stack.py .

脚本输出示例：

{
  "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: 分析依赖关系（可选，用于深度分析）

使用依赖分析脚本：

python ~/.claude/skills/codebase-architecture-analyzer/scripts/extract_dependencies.py .

脚本输出示例：

{
  "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 项目

识别文件：

# 优先级从高到低
1. pyproject.toml       # 现代 Python 项目（Poetry/Hatch）
2. setup.py            # 传统 Python 包
3. requirements.txt    # 依赖清单
4. Pipfile             # Pipenv 项目
5. environment.yml     # Conda 项目

提取信息：

# 从 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 项目

识别文件：

1. package.json        # Node.js 项目
2. yarn.lock           # Yarn 包管理
3. pnpm-lock.yaml      # pnpm 包管理
4. tsconfig.json       # TypeScript 配置

提取信息：

# 从 package.json 提取
cat package.json | grep "\"react\"\|\"vue\"\|\"express\"\|\"next\""

---

Go 项目

识别文件：

1. go.mod              # Go modules
2. go.sum              # 依赖锁文件

提取信息：

cat go.mod | grep "require" -A 20

---

Rust 项目

识别文件：

1. Cargo.toml          # Rust 项目配置
2. Cargo.lock          # 依赖锁文件

---

Java 项目

识别文件：

1. pom.xml             # Maven 项目
2. build.gradle        # Gradle 项目

---

步骤 3: 扫描目录结构

列出顶层目录

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 相关

# docker-compose.yml → 多服务架构
cat docker-compose.yml | grep "services:" -A 50

# Dockerfile → 容器化应用
ls -la | grep Dockerfile

环境配置

# .env.example → 环境变量配置
cat .env.example | grep -E "DATABASE_URL|REDIS_URL|API_KEY"

---

步骤 5: 识别项目规模

统计代码文件

# 统计各语言文件数量
find . -type f -name "*.py" | wc -l
find . -type f -name "*.ts" -o -name "*.tsx" | wc -l
find . -type f -name "*.go" | wc -l

估算代码规模

# 使用 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 框架

依赖中包含:
- fastapi → FastAPI
- django → Django
- flask → Flask
- starlette → Starlette
- aiohttp → aiohttp

Python AI 框架

依赖中包含:
- langgraph → LangGraph
- crewai → CrewAI
- autogen → AutoGen
- langchain → LangChain
- transformers → Hugging Face

JavaScript 框架

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/

---

完整示例

# 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