project-analyzer

参考资料（存档）： SCAFFOLD_SKILLS_ARCHIVE_MAP.md — 基于 Auto-Claude-develop 分析器的 ProjectAnalyzer 单体仓库/服务检测。

Project Analyzer - 自动分析既有代码库，帮助快速完成项目接入和理解。 - 检测项目类型（前端、后端、全栈、库、CLI、移动端、单体仓库） - 根据清单文件和结构识别框架和库 - 生成文件统计数据和语言分布 - 绘制组件关系和模块结构 - 检测架构模式（MVC、分层、微服务等） - 分析依赖项健康状况和过期软件包 - 识别代码质量指标（代码检查、测试、类型安全） - 检测技术债务和反模式 - 生成按优先级排序的改进建议

步骤 1：识别项目根目录

通过查找清单文件定位项目根目录：

1. 搜索包管理器文件：

   • package.json（Node.js/JavaScript/TypeScript）
   • requirements.txt、pyproject.toml、setup.py（Python）
   • go.mod（Go）
   • Cargo.toml（Rust）
   • pom.xml、build.gradle（Java/Maven/Gradle）
   • composer.json（PHP）

2. 识别项目根目录：

   • 包含主要包管理器文件的目录
   • 处理单体仓库（多个 package.json 文件）
   • 检测工作区配置

3. 验证项目根目录：

   • 检查是否存在 .git 目录
   • 验证源代码目录是否存在
   • 确保清单文件可解析

步骤 2：检测项目类型

根据清单文件和目录结构对项目进行分类：

1. 前端项目：

   • 指标：React、Vue、Angular、Svelte 依赖项
   • 目录：src/components/、public/、assets/
   • 框架：Next.js、Nuxt.js、Gatsby、Vite

2. 后端项目：

   • 指标：Express、FastAPI、Django、Flask、Gin 依赖项
   • 目录：routes/、controllers/、models/、api/
   • 框架：Next.js API 路由、FastAPI、Express

3. 全栈项目：

   • 指标：同时包含前端和后端框架
   • 目录：前端和后端结构组合
   • 框架：Next.js、Remix、SvelteKit、Nuxt.js

4. 库/软件包项目：

   • 指标：没有应用专用目录
   • 文件：index.ts、lib/、dist/、build/
   • 清单：package.json 中的 library 字段

5. CLI 项目：

   • 指标：package.json 中的 bin 字段
   • 文件：CLI 入口点、命令解析器
   • 依赖项：Commander、Yargs、Inquirer

6. 移动端项目：

   • 指标：React Native、Flutter、Ionic 依赖项
   • 文件：android/、ios/、mobile/
   • 框架：React Native、Expo、Flutter

7. 单体仓库项目：

   • 指标：package.json 中的 workspaces、pnpm-workspace.yaml
   • 结构：子目录中的多个软件包
   • 工具：Turborepo、Nx、Lerna

8. 微服务项目：

   • 指标：多个服务目录
   • 文件：docker-compose.yml、服务配置
   • 结构：基于服务的组织方式

第 3 步：框架检测

从清单文件和导入语句中识别框架：

1. 读取 package.json 依赖项（Node.js）：

   • 解析 dependencies 和 devDependencies
   • 检测框架版本
   • 按类型分类（框架、UI 库、测试等）

2. 读取 requirements.txt（Python）：

   • 解析 Python 依赖项
   • 检测 FastAPI、Django、Flask
   • 识别版本约束

3. 分析导入语句（可选的深度扫描）：

   • 扫描源文件中的导入语句
   • 检测已使用与已声明的依赖项
   • 识别特定于框架的模式

4. 框架类别：

   • 框架：React、Next.js、FastAPI、Express
   • UI 库：Material-UI、Ant Design、Chakra UI
   • 状态管理：Redux、Zustand、Pinia
   • 测试：Jest、Vitest、Cypress、Playwright
   • 构建工具：Vite、Webpack、Rollup、esbuild
   • 数据库：Prisma、TypeORM、SQLAlchemy
   • ORM：Prisma、Sequelize、Mongoose
   • API：tRPC、GraphQL、REST
   • 身份验证：NextAuth、Auth0、Clerk
   • 日志记录：Winston、Pino、Bunyan
   • 监控：Sentry、Datadog、New Relic

5. 置信度评分：

   • 1.0：依赖项中列出了框架
   • 0.8：从导入语句中检测到框架
   • 0.6：根据结构推断出框架

第 4 步：文件统计

生成项目的量化统计数据：

1. 按类型统计文件数：

   • 对常见扩展名使用 glob 模式
   • 排除：node_modules/、.git/、dist/、build/
   • 按语言／文件类型分组

2. 统计代码行数：

   • 读取源文件并统计行数
   • 排除空行和注释（可选）
   • 按语言计算总代码行数（LOC）

3. 识别最大的文件：

   • 跟踪文件大小（行数）
   • 报告最大的 10 个文件
   • 标记超过 1000 行的文件（违反微服务原则）

4. 计算平均值：

   • 平均文件大小（行数）
   • 平均目录深度
   • 每个目录的文件数

5. 语言检测：

   • 将扩展名映射到语言：
     • .ts、.tsx → TypeScript
     • .js、.jsx → JavaScript
     • .py → Python
     • .go → Go
     • .rs → Rust
     • .java → Java
     • .md → Markdown
     • .json → JSON
     • .yaml、.yml → YAML

第 5 步：结构分析

分析项目结构和架构：

1. 识别根目录：

   • 按用途对目录分类：
     • 源代码：src/、app/、lib/
     • 测试：test/、__tests__/、cypress/
     • 配置：config/、.config/
     • 文档：docs/、documentation/
     • 构建：dist/、build/、out/
     • 脚本：scripts/、bin/
     • 资源：assets/、static/、public/

2. 检测入口点：

   • 主入口：index.ts、main.py、app.py
   • 应用入口：app.ts、server.ts、app/page.tsx
   • 处理程序：handler.ts、lambda.ts
   • 命令行界面：cli.ts、bin/

3. 检测架构模式：

   • MVC：models/、views/、controllers/
   • 分层架构：presentation/、business/、data/
   • 六边形架构：domain/、application/、infrastructure/
   • 微服务：多个服务目录
   • 模块化：按功能组织
   • 扁平结构：所有文件都位于 src/ 中

4. 检测模块系统：

   • 检查 package.json 中是否包含 "type": "module"（ESM）
   • 扫描 import／export（ESM）与 require（CommonJS）
   • 识别混合模块系统

第 6 步：依赖项分析

分析依赖项的健康状况：

1. 统计依赖项：

   • 生产依赖项
   • 开发依赖项
   • 依赖项总数

2. 检查过时的软件包（可选）：

   • 运行 npm outdated 或等效命令
   • 解析输出，找出过时的软件包
   • 识别主版本更新（可能包含破坏性变更）

3. 安全扫描（可选）：

   • 运行 npm audit 或等效命令
   • 按严重程度识别漏洞
   • 标记严重安全问题

步骤 7：代码质量指标

检测代码质量工具：

1. Linting 配置：

   • 检测：.eslintrc.json、eslint.config.js、ruff.toml
   • 工具：ESLint、Ruff、Flake8、Pylint
   • 如果已配置，则运行 linter（可选）

2. 格式化配置：

   • 检测：.prettierrc、pyproject.toml（Black/Ruff）
   • 工具：Prettier、Black、Ruff

3. 测试框架：

   • 检测：Jest、Vitest、Pytest、Cypress
   • 统计测试文件数量
   • 检查是否配置了覆盖率

4. 类型安全：

   • 检测 TypeScript：tsconfig.json
   • 检查严格模式："strict": true
   • 检测 Python 类型检查：mypy、pyright

步骤 8：模式检测

识别常见模式和反模式：

1. 良好实践：

   • 模块化组件结构
   • 全面的测试覆盖
   • 已启用 TypeScript 严格模式
   • 存在 CI/CD 配置

2. 反模式：

   • 大型文件（> 1000 行）
   • 缺少测试
   • 依赖项过时
   • 未配置 linting

3. 中性模式：

   • 特定的架构选择
   • 特定框架的模式

步骤 9：技术债务分析

计算技术债务评分：

1. 债务指标：

   • 依赖项过时：统计过时的软件包数量
   • 缺少测试：测试文件占比偏低
   • 死代码：未使用的导入/导出（可选）
   • 复杂度：大型文件、嵌套层级过深
   • 文档：缺少 README、文档
   • 安全性：已知漏洞
   • 性能：包大小、加载时间

2. 债务评分（0-100）：

   • 0-20：状态极佳
   • 21-40：状态良好，存在少量问题
   • 41-60：债务中等，需要关注
   • 61-80：债务较高，建议重构
   • 81-100：债务严重，需要全面整改

3. 修复工作量：

   • 轻微：< 1 小时
   • 少量：1-4 小时
   • 中等：1-3 天
   • 大量：1-2 周
   • 极大量：> 2 周

步骤 10：生成建议

创建按优先级排序的改进建议：

1. 建议分类：

   • 安全性：严重漏洞、过时的身份验证
   • 性能：包优化、延迟加载
   • 可维护性：重构大型文件、添加测试
   • 测试：提高覆盖率、添加端到端测试
   • 文档：添加 README、API 文档
   • 架构：提高模块化程度，明确关注点分离
   • 依赖项：更新软件包、移除未使用的软件包

2. 按影响程度排序：

   • P0：严重安全问题、阻碍生产环境运行
   • P1：影响大，影响可靠性
   • P2：影响中等，提升质量
   • P3：影响低，可有可无

3. 估算工作量和影响：

   • 工作量：轻微、少量、中等、大量、极大量
   • 影响：低、中、高、严重

步骤 11：验证输出

根据架构验证分析输出：

1. 架构验证：

   • 根据 project-analysis.schema.json 进行验证
   • 确保所有必需字段均已提供
   • 检查数据类型和格式

2. 输出元数据：

   • 分析器版本
   • 分析耗时（ms）
   • 已分析文件数
   • 已跳过文件数
   • 遇到的错误

</execution_process>

**性能要求**：

• 目标：典型项目（< 10k 个文件）耗时 < 30 秒
• 优化：
  • 跳过大型目录：node_modules/、.git/、dist/
  • 并行处理文件
  • 缓存结果以支持增量分析
  • 将深度扫描限制在必要文件
  • 文件数量较多时使用流式处理

**与 Conductor 集成**： - 提供自动化项目发现 - 无需手动收集上下文 - 让 brownfield 项目接入速度提升 80% - 将项目上下文提供给聊天界面

与其他技能集成：

• rule-selector：根据检测到的框架自动选择规则
• repo-rag：对架构模式进行语义搜索
• dependency-analyzer：深入分析依赖项

<best_practices>

1. 渐进式披露：从清单分析开始，按需添加深度扫描
2. 性能优先：大型项目跳过开销较大的操作
3. 优雅失败：处理文件缺失和解析错误
4. 验证输出：始终根据架构验证
5. 缓存结果：存储分析输出以便复用
6. 增量更新：仅重新分析已更改的文件 </best_practices>

**程序化用法**：

# Analyze current project
node .claude/tools/analysis/project-analyzer/analyzer.mjs

# Analyze specific directory
node .claude/tools/analysis/project-analyzer/analyzer.mjs /path/to/project

# Output to file
node .claude/tools/analysis/project-analyzer/analyzer.mjs --output .claude/context/artifacts/project-analysis.json

Agent 调用：

# Analyze current project
Analyze this project

# Generate comprehensive analysis
Perform full project analysis and save to artifacts

# Quick analysis (manifest only)
Quick project type detection

</usage_example>

<formatting_example> 输出示例（.claude/context/artifacts/project-analysis.json）：

{
  "analysis_id": "analysis-llm-rules-20250115",
  "project_type": "fullstack",
  "analyzed_at": "2025-01-15T10:30:00.000Z",
  "project_root": "C:\\dev\\projects\\LLM-RULES",
  "stats": {
    "total_files": 1243,
    "total_lines": 125430,
    "languages": {
      "JavaScript": 45230,
      "TypeScript": 38120,
      "Markdown": 25680,
      "JSON": 12400,
      "YAML": 4000
    },
    "file_types": {
      ".js": 234,
      ".mjs": 156,
      ".ts": 89,
      ".md": 312,
      ".json": 145
    },
    "directories": 87,
    "avg_file_size_lines": 101,
    "largest_files": [
      {
        "path": ".claude/tools/enforcement-gate.mjs",
        "lines": 1520
      }
    ]
  },
  "frameworks": [
    {
      "name": "nextjs",
      "version": "14.0.0",
      "category": "framework",
      "confidence": 1.0,
      "source": "package.json"
    },
    {
      "name": "react",
      "version": "18.2.0",
      "category": "framework",
      "confidence": 1.0,
      "source": "package.json"
    }
  ],
  "structure": {
    "root_directories": [
      {
        "name": ".claude",
        "purpose": "config",
        "file_count": 543
      },
      {
        "name": "conductor-main",
        "purpose": "source",
        "file_count": 234
      }
    ],
    "entry_points": [
      {
        "path": "conductor-main/src/index.ts",
        "type": "main"
      }
    ],
    "architecture_pattern": "modular",
    "module_system": "esm"
  },
  "dependencies": {
    "production": 45,
    "development": 23
  },
  "code_quality": {
    "linting": {
      "configured": true,
      "tool": "eslint"
    },
    "formatting": {
      "configured": true,
      "tool": "prettier"
    },
    "testing": {
      "framework": "vitest",
      "test_files": 89,
      "coverage_configured": true
    },
    "type_safety": {
      "typescript": true,
      "strict_mode": true
    }
  },
  "tech_debt": {
    "score": 35,
    "indicators": [
      {
        "category": "complexity",
        "severity": "medium",
        "description": "3 files exceed 1000 lines",
        "remediation_effort": "moderate"
      }
    ]
  },
  "recommendations": [
    {
      "priority": "P1",
      "category": "maintainability",
      "title": "Refactor large files",
      "description": "Break down files > 1000 lines into smaller modules",
      "effort": "moderate",
      "impact": "high"
    }
  ],
  "metadata": {
    "analyzer_version": "1.0.0",
    "analysis_duration_ms": 2340,
    "files_analyzed": 1243,
    "files_skipped": 3420,
    "errors": []
  }
}

</formatting_example>

智能分类评分（受 Skill_Seekers smart_categorize 启发）

将文件、目录或组件归类时，使用加权关键词评分，而非简单字符串匹配，以避免误判：

信号来源	权重分数	示例
文件路径/URL	3 分	/api/routes/ 匹配“API”类别
文件/类名	2 分	AuthService.ts 匹配“Authentication”
文件内容/导入项	1 分	import express 匹配“Backend”

阈值：分配类别前，要求总分达到 2 分或以上。如果没有类别的得分超过阈值，则归为“other”。这可以避免依据较弱的单一信号错误地对组件分类。

类别关键词（根据项目类型扩展）：

• API：route、endpoint、controller、handler、middleware、api、rest、graphql
• Auth：auth、login、session、jwt、oauth、token、credential、permission
• Database：model、schema、migration、seed、repository、entity、query
• Testing：test、spec、fixture、mock、stub、e2e、integration
• Config：config、env、setting、constant、option、feature-flag
• UI：component、view、page、layout、template、style、theme

## 三流分析（灵感来自 Skill_Seekers unified_codebase_analyzer）

为全面了解项目，请分析以下三个并行流：

流 1 — 代码分析：AST 模式、框架检测、依赖关系图、架构分类。这是现有的核心工作流（步骤 1-11）。

流 2 — 文档：README 质量、API 文档是否存在、内联文档覆盖率、变更日志维护情况、贡献指南。评分：按类型加权计算 docFiles / totalFiles。

流 3 — 社区/运维：Git 活动（提交频率、贡献者数量）、CI/CD 配置、问题模板、PR 模板、发布工作流、Docker/容器设置。

将这三个流合并到输出 JSON 的 analysis.streams 中：

{
  "streams": {
    "code": { "score": 0.85, "findings": [...] },
    "documentation": { "score": 0.60, "findings": [...] },
    "operations": { "score": 0.75, "findings": [...] }
  },
  "compositeHealth": 0.73
}

设计模式识别（灵感来自 Skill_Seekers C3.1 PatternRecognizer）

通过置信度评分检测常见设计模式：

模式	检测信号	置信度阈值
单例	私有构造函数 + 静态实例	0.80
工厂	返回接口类型的 create* 方法	0.70
观察者	subscribe/on/emit/addEventListener	0.70
策略	接口 + 多个实现	0.60
装饰器	实现相同接口的包装类	0.60
仓储	数据访问层抽象	0.70
中间件	请求管道中的责任链	0.70

在分析 JSON 中输出检测到的模式，并包含位置、置信度和证据：

{
  "patterns": [
    {
      "type": "Factory",
      "category": "Creational",
      "confidence": 0.85,
      "location": "src/services/UserFactory.ts",
      "evidence": ["createUser method", "returns IUser interface"]
    }
  ]
}

参考资料

有关从 Auto-Claude 分析框架中提取的其他检测模式，请参阅：

• references/auto-claude-patterns.md - Monorepo 指标、SERVICE_INDICATORS、SERVICE_ROOT_FILES、基础设施检测、约定检测
• references/service-patterns.md - 服务类型检测（前端、后端、库）、特定框架模式、入口点检测
• references/database-patterns.md - 数据库配置文件模式、ORM 检测（Prisma、SQLAlchemy、TypeORM、Drizzle、Mongoose）、连接字符串模式
• references/route-patterns.md - Express、FastAPI、Flask、Django、Next.js、Go、Rust API 路由检测模式

这些参考资料为棕地代码库分析提供全面的正则表达式模式和检测逻辑。

记忆协议（强制）

开始之前： 读取 .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 作出决策 -> .claude/context/memory/decisions.md

假定会发生中断：如果没有记录在记忆中，就等于没有发生。