unipus-project-analyze

公司内部项目全面分析

概述

对公司内部 GitHub 项目进行深度分析，生成一份专业、详细、结构化的项目概览报告，让新成员在 5 分钟内全面了解项目的业务定位、技术选型、系统架构、代码结构、内部依赖和部署方式。

输入

输入	必选	说明
仓库地址或本地路径	是	内部 GitHub URL（如 https://github.com/{org}/{repo}）或本地已克隆路径
关注重点	否	如"重点看后端架构"、"关注数据库设计"、"梳理微服务依赖"

输出

doc/project-overview.md，包含以下 14 个章节。

图表生成规范

报告中需要生成 4 类 ASCII 艺术图，使用 Unicode 方框字符（┌─┐│└─┘）和箭头（→ ▼ ▲）绘制，不使用 Mermaid：

图表	位置	数据来源	要求
上下游系统图	2.2	配置文件中的外部服务地址、SDK 依赖	展示 用户→前端→后端→数据库/外部服务 的完整链路，标注协议
架构分层图	5.2	controller/service/repository 目录	按层展示，标注每层的类数量和关键类名
ER 关系图	7.2	entity/models/schemas 目录的 ORM 注解或模型定义	展示实体间 1:N/N:1 关系，列出关键字段。Java 项目从 JPA 注解提取，Python 从 SQLAlchemy/Django Model 提取，Go 从 struct tag 提取
CI/CD 流程图	10.2	Jenkinsfile/workflows/builds/	展示 Git→构建→镜像→部署 流水线和多环境拓扑

图表在实际分析项目时根据源码动态生成，SKILL 模板中不包含具体图表内容。

工作流程

第一步：获取项目源码

根据用户提供的输入，按以下优先级获取源码：

场景 A：用户提供本地路径
  → 直接使用该路径，验证目录存在且包含代码文件

场景 B：用户提供内部 GitHub 仓库 URL
  → git clone {repo_url} _git_src/{repo_name}
  → 如果 _git_src/ 下已有该仓库，执行 git pull 更新

场景 C：clone 失败（权限/网络问题）
  → 提示用户手动克隆到 _git_src/ 目录后重新执行
  → 或提示用户提供已克隆的本地路径

第二步：快速扫描与并行读取

克隆/定位源码后，用最少的工具调用收集最多的信息：

第一轮（1 次调用）：目录结构总览

listDirectory(path, depth=3) → 获取完整项目结构，识别技术栈类型和关键文件位置

第二轮（并行调用，1 轮完成）：核心文件批量读取

根据目录结构，用 readMultipleFiles 和 readCode 并行读取所有关键文件：

并行调用 1: readMultipleFiles([README.md, package.json/pom.xml, application.yml/.env, Dockerfile, Jenkinsfile])
  → 项目简介、技术栈版本、配置、部署方式

并行调用 2: readCode(entity/ 或 models/ 目录)
  → 所有数据模型签名和关联关系（AST 模式，不读方法体）

并行调用 3: readCode(controller/ 或 routes/ 目录)
  → 所有 API 端点签名（AST 模式）

并行调用 4: readFile(App.js 或 router 入口) + readFile(Security 配置)
  → 前端路由表 + 认证机制

第三轮（并行调用，按需补充）：

仅当第二轮信息不足时，针对性补充：

• 某个 Controller 的具体参数 → readCode(file, selector="ClassName.methodName")
• Entity 的字段细节 → readCode(file) 小文件自动返回全文
• CI/CD 构建脚本 → readFile(build.sh)

速度优化原则：

原则	说明
并行优先	无依赖关系的文件读取放在同一轮并行调用
readCode 优先	代码文件用 readCode（AST 签名模式），比 readFile 更快更精准
readMultipleFiles 批量读	配置文件、文档等小文件用 readMultipleFiles 一次读多个
目录级 readCode	readCode(directory) 一次扫描整个目录的所有类签名
不读不需要的	Repository 从命名推断，不逐个读取；前端组件从路由表推断，不逐个读取
git 命令合并	git log 和 git shortlog 合并为一次 shell 调用

典型调用轮次：

项目规模	工具调用轮次	说明
小型 (< 50 文件)	2-3 轮	目录扫描 → 并行读取全部 → 生成报告
中型 (50-500 文件)	3-4 轮	目录扫描 → 并行读核心 → 补充细节 → 生成报告
大型 (> 500 文件)	4-5 轮	目录扫描 → 并行读核心 → 按模块补充 → 补充细节 → 生成报告

第三步：深度分析

基于第二步收集的信息，按 14 个维度整理分析结果。大部分信息已在并行读取阶段获得，此步骤主要是整理和推断：

章节	数据来源（已读取）	分析方式
1. 项目概况	README + git log	直接提取
2. 业务上下文	README + application.yml + service/remote/	推断业务定位，生成上下游 ASCII 图
3. 功能清单	Controller 签名 + Security 配置	从端点推断功能模块和角色权限
4. 技术栈	package.json / pom.xml	直接提取版本号
5. 系统架构	目录结构 + Security + Service	推断架构模式，生成架构 ASCII 图
6. 目录结构	listDirectory 结果	直接输出，标注职责
7. 数据模型	Entity/Model 签名	提取字段和关联，生成 ER ASCII 图
8. API 接口	Controller 签名	逐个列出端点
9. 前端页面	App.js / router	提取路由表
10. 部署运维	Dockerfile + Jenkinsfile + build.sh	提取流程，生成 CI/CD ASCII 图
11. 内部依赖	application.yml + pom.xml/package.json	提取外部服务和 SDK
12. 快速上手	README + application.yml	整理环境搭建步骤
13. 状态管理	contexts/ / store/	分析数据流
14. 评估与风险	全部已读文件	综合评估，引用具体文件

第四步：生成报告

分析完成后生成报告到 doc/project-overview.md：

• 小型/中型项目：fsWrite 写入前半部分（第 1-8 章），fsAppend 追加后半部分（第 9-14 章）
• 大型项目：按 fsWrite + 多次 fsAppend（每次 40 行以内，不在表格/代码块中间断开）
• ASCII 图表作为完整块一次性写入，不拆分

报告模板：

# {项目名称} - 项目全面分析报告

> 仓库地址：{repo_url_or_local_path}
> 所属团队：{team_name}
> 分析日期：{date}
> 分析版本：{latest_commit_hash}

## 1. 项目概况

| 项目 | 信息 |
|------|------|
| 名称 | {name} |
| 定位 | {一句话描述} |
| 所属业务线 | {业务线} |
| 负责团队 | {团队} |
| 目标用户 | {内部/外部用户群体} |
| 技术栈 | {主要技术} |
| 主要维护者 | {从 git log 提取} |
| 最近更新 | {last_commit_date} |

## 2. 业务上下文

### 2.1 业务定位
{项目在公司整体业务中的角色和价值}

### 2.2 上下游系统
{ASCII 上下游系统图}

### 2.3 核心业务流程
{主要业务流程描述}

## 3. 功能清单

### 3.1 用户角色
| 角色 | 权限 |
|------|------|

### 3.2 功能模块
| 模块 | 功能点 | 核心/辅助 |
|------|--------|----------|

## 4. 技术栈

### 4.1 前端
| 技术 | 版本 | 用途 |
|------|------|------|

### 4.2 后端
| 技术 | 版本 | 用途 |
|------|------|------|

### 4.3 数据库与存储
| 技术 | 用途 |
|------|------|

### 4.4 中间件
| 技术 | 用途 |
|------|------|

### 4.5 第三方服务
| 服务 | 用途 |
|------|------|

## 5. 系统架构

### 5.1 架构模式
{单体/微服务/前后端分离/BFF}

### 5.2 架构图
{ASCII 架构分层图}

### 5.3 认证机制
{JWT/Session/OAuth/SSO}

### 5.4 内部服务调用
{HTTP/gRPC/消息队列调用关系}

## 6. 目录结构
{3 层深度目录树，关键目录标注职责}

## 7. 数据模型

### 7.1 核心实体
| 实体 | 关键字段 | 说明 |
|------|---------|------|

### 7.2 ER 关系图
{ASCII ER 关系图}

## 8. API 接口

### 8.1 接口清单
| 模块 | 方法 | 路径 | 认证 | 说明 |
|------|------|------|------|------|

### 8.2 关键接口示例
{请求/响应示例}

## 9. 前端页面
| 路由 | 页面 | 功能 | 权限 |
|------|------|------|------|

## 10. 部署与运维

### 10.1 本地开发
{环境要求 + 安装步骤 + 启动命令}

### 10.2 CI/CD 流水线
{ASCII CI/CD 流程图}

### 10.3 环境配置
| 环境 | 用途 | 访问地址 |
|------|------|---------|

### 10.4 环境变量
| 变量 | 说明 |
|------|------|

## 11. 内部依赖与集成

### 11.1 依赖的内部服务
| 服务 | 调用方式 | 用途 |
|------|---------|------|

### 11.2 依赖的内部公共库/SDK
| 库名 | 版本 | 用途 |
|------|------|------|

### 11.3 被依赖情况
| 下游服务 | 调用方式 | 说明 |
|---------|---------|------|

### 11.4 消息队列/事件
| Topic/Queue | 生产/消费 | 说明 |
|-------------|----------|------|

## 12. 快速上手路径

### 12.1 环境搭建
{完整步骤}

### 12.2 核心业务操作
{主要操作路径}

### 12.3 调试技巧
{日志、断点、常见问题}

## 13. 前端状态管理
{数据流分析，纯后端项目标注"不适用"}

## 14. 项目评估与风险

### 14.1 代码质量
| 维度 | 评分 | 说明 |
|------|------|------|
| 结构清晰度 | {1-5 ⭐} | {说明} |
| 命名规范 | {1-5 ⭐} | {说明} |
| 注释覆盖 | {1-5 ⭐} | {说明} |
| 测试覆盖 | {1-5 ⭐} | {说明} |

### 14.2 潜在风险
| 层面 | 风险项 | 严重程度 | 说明 |
|------|--------|---------|------|

### 14.3 技术债务
{已识别的技术债务清单}

### 14.4 改进建议
{编号列表}

第五步：转换格式（可选）

工具：mcp_doc_converter_convert_markdown_to_word
参数：input_path="doc/project-overview.md", output_path="doc/project-overview.docx"

分析深度控制

项目规模	文件数	读取轮次	策略
小型	< 50	2-3 轮	全量并行读取，一次性生成
中型	50-500	3-4 轮	并行读核心文件 + 按需补充
大型	> 500	4-5 轮	readCode AST 模式 + 抽样 + 按需补充
Monorepo	不限	按子项目	先识别边界，每个子项目独立分析

大型项目提速策略：

• readCode(directory) 一次扫描整个目录签名，替代逐文件读取
• 同类文件（如 12 个 Repository）只抽样 2-3 个，其余从命名推断
• API 接口从 Controller 签名提取，不读方法体
• 前端页面从路由入口文件提取，不逐个读组件

错误处理

情况	处理方式
git clone 失败（权限不足）	提示用户检查 SSH Key / Token 配置，或手动克隆到 _git_src/
git clone 失败（网络问题）	提示用户确认 VPN 连接或内网访问权限
无 README	从代码和配置文件推断项目信息，标注"缺少 README，建议补充"
私有仓库无权限	提示用户提供 Personal Access Token 或添加 SSH Key
非主流技术栈	标注"未识别"，建议用户补充说明
API 接口无法逐个读取	先用通配符标注，后续补全具体端点
Monorepo 多项目	提示用户指定要分析的子项目路径

迭代优化规则

首次生成报告后，执行以下自检并补充：

自检项	检查方式	补充动作
API 接口是否有通配符 *	搜索报告中的 | * |	逐个读取 Controller 源码，展开为具体端点
是否缺少业务上下文	检查是否有第 2 章	从 README、配置文件、服务调用中推断业务定位
是否缺少快速上手路径	检查是否有第 12 章	从 README 和配置提取环境搭建步骤
是否分析了状态管理	检查是否有第 13 章	读取 Context/Store 文件分析数据流
是否有风险分析	检查是否有第 14 章	检查 N+1、索引、分页、输入校验等
内部依赖是否完整	检查第 11 章是否有空表	从配置文件、HTTP Client、MQ 配置中提取
技术栈版本是否完整	检查版本列是否有空值	从 package.json/pom.xml/go.mod 补全
评估是否有依据	检查评分是否附带说明	引用具体代码文件作为依据

质量检查

• 14 个章节全部输出，无遗漏
• 业务上下文清晰，上下游关系明确
• 技术栈版本号从 package.json/pom.xml 等准确提取
• 数据模型从实际代码中提取，非猜测
• API 接口从 Controller 源码逐个提取，无通配符
• 内部依赖关系（服务调用/MQ/SDK）梳理完整
• 架构图和 ER 图使用 ASCII 艺术图 格式，不使用 Mermaid 代码块，确保在任何环境中都能正确显示
• 上下游系统关系明确，包括外部用户、前端、后端、数据库、第三方服务的完整链路
• 部署步骤可实际执行，CI/CD 流程描述准确
• 评估有依据（引用具体文件/代码），非主观臆断
• 快速上手路径覆盖环境搭建和核心业务操作
• 风险分析覆盖数据库层、安全层、前端层、运维层
• 报告输出到 doc/project-overview.md
• 不泄露敏感信息（密码、Token、内部 IP 等用占位符替代）
• 敏感信息脱敏验证：搜索报告中是否包含 password、secret、token、10./192.168 等真实值，确认均已替换为 [password]、[secret] 等占位符