project-analyzer

name	project-analyzer
description	深度分析现有项目代码和文档，总结功能与交互，生成结构化文档目录（产品介绍、技术文档、架构、数据模型等），并深入分析代码结构以支持新项目创建和重构。

项目分析器

概述

本项目分析器技能旨在深入理解现有软件项目，通过自动化分析项目代码和相关文档，提取核心功能、用户交互模式、技术栈、系统架构、数据模型等关键信息。最终生成一套结构化、详尽且易于理解的中文文档，旨在赋能团队快速理解项目、指导新项目开发、或为现有项目重构提供坚实基础。

此技能特别注重对代码结构的深度分析，识别项目分层、模块职责，为理解复杂内部系统提供清晰视角，对重构和维护至关重要。

何时使用此技能

• 在接手一个新项目时，需要快速了解其功能、技术和结构。
• 需要为现有项目创建全面的产品文档和技术文档。
• 计划重构现有项目，需要深入理解其代码架构和分层。
• 需要向新团队成员或非技术人员介绍项目全貌。
• 需要从现有项目中提取可复用的设计模式或架构思想。
• 作为新项目启动的参考蓝图。

核心功能与能力

1. 项目全景分析: 扫描整个项目目录，识别代码文件、文档、配置文件等。
2. 功能与交互总结: 从代码注释、文档和文件结构中推断并总结项目的主要功能模块及其用户交互流程。
3. 结构化文档生成:
   • 产品介绍: 详尽的产品概述、目标用户、核心价值、功能列表等。
   • 技术文档:
     • 系统架构: 宏观架构图、关键组件及其交互。
     • 技术栈: 使用的编程语言、框架、库、数据库、中间件等。
     • 前后端技术: 分别介绍前端技术选型、模块划分，后端服务、API 接口定义。
     • 数据模型: 核心实体关系图（ERD）、关键数据表结构及字段说明。
   • 代码结构分析: 详细描述项目的分层、模块组织、代码规范、重要设计模式等。
4. 代码结构深度理解:
   • 识别项目内的代码分层（如：控制器、服务、持久层、领域模型）。
   • 分析各层级之间的依赖关系和职责边界。
   • 提取重复的代码模式或架构决策。
   • 生成关键代码模块的概览，包含文件路径、简要功能。

如何使用此技能

此技能通过执行核心分析脚本来运作，并辅以多种参考资料和输出模板。

第 1 步：分析项目并生成初始文档结构

执行 analyze_project.py 脚本，指定目标项目路径。此脚本将遍历项目，进行初步分析，并生成一个包含主要文档目录和占位符文件的 docs 目录。

python scripts/analyze_project.py --project-path /path/to/your/project --output-dir ./generated_docs

参数说明:

• --project-path: 必填，待分析项目的根目录。
• --output-dir: 必填，生成的文档目录将存放的位置。

第 2 步：深入分析代码结构

如果需要对代码结构进行更精细的分析，特别是针对特定分层和模块职责，可以调用 code_analyzer.py。

python scripts/code_analyzer.py --project-path /path/to/your/project --output-file ./generated_docs/code_structure.md

第 3 步：生成详细文档内容

根据初步生成的文档目录，结合用户提供的具体信息和 AI 的推理能力，调用 doc_generator.py 来填充详细文档内容。

python scripts/doc_generator.py --docs-dir ./generated_docs --analysis-results ./analysis_summary.json

第 4 步：人工审查与完善

生成的文档是 AI 分析的初步成果，强烈建议人工审查、修正和补充。特别是针对公司内部的特定规范和背景知识，人工的完善至关重要。

捆绑资源

此技能包含以下类型的捆绑资源，用于辅助分析和文档生成：

脚本 (scripts/)

• analyze_project.py: 主分析脚本，协调整个分析流程。
• code_parser.py: 负责代码文件的解析、AST 分析、函数/类/模块提取。
• doc_summarizer.py: 负责现有文档（如 README、现有设计文档）的摘要和关键词提取。
• architecture_extractor.py: 从代码和文档中推断系统架构、服务间关系。
• data_model_extractor.py: 识别并提取数据库模式、ORM 模型定义等数据结构。
• doc_generator.py: 根据分析结果和预设模板生成结构化文档。

参考 (references/)

• docs_structure.md: 结构化文档目录的模板定义。
• analysis_guidelines.md: 项目分析的通用指南和最佳实践。
• architecture_patterns.md: 常见架构模式的描述和识别方法。
• data_model_template.md: 数据模型文档的模板。
• code_layering_patterns.md: 常见的代码分层模式及其职责定义。

资产 (assets/)

• doc_templates/: 各种文档（如产品介绍、技术概述）的Markdown模板。
• diagram_templates/: 架构图、数据流图等可复用图表模板的占位符。

最佳实践

• 逐步迭代: 从初步分析开始，逐步细化文档内容。
• 提供清晰的上下文: 在调用技能时，尽可能提供关于项目类型、技术栈、主要功能等信息，以提高分析准确性。
• 人工校对: 始终对 AI 生成的文档进行人工校对和补充，确保其准确性、完整性和符合内部规范。
• 版本控制文档: 将生成的文档纳入项目版本控制，方便追踪和管理。