@smart-portal/smart-codereview v0.0.6

Smart Code Review 智能代码服务

一个基于 MCP (Model Context Protocol) 的智能代码服务，提供代码审查和仓库分析功能，专注于 Vue.js 生态系统的代码质量提升和架构分析。

📋 服务概述

Smart Code Review 服务提供两个核心工具：

1. 智能代码审查 (smart_Code_Review): 深度分析代码质量、安全性、性能等问题
2. 智能仓库分析 (smart_Analyze): 分析Vue项目架构，生成全面的需求与设计文档

🚀 功能特点

核心功能

• 智能代码审查: 使用专业的Vue.js代码审查模板，识别问题并提供改进机会
• 仓库架构分析: 专门针对Vue项目的深度架构分析和文档生成
• 多文件支持: 支持单文件和多文件/文件夹的代码分析，集成Repomix工具
• 自动清理: 智能临时文件管理，防止磁盘空间浪费
• Vue特化: 专门为Vue 2/3项目优化的分析规则和最佳实践

技术特性

• 类型安全: 完整的 TypeScript 类型支持
• 模块化架构: 分层设计，易于扩展和维护
• 自动资源管理: 临时文件自动清理机制
• 错误恢复: 健壮的错误处理和恢复机制
• Repomix集成: 深度集成Repomix工具进行代码上下文收集

🏗️ 架构设计

分层架构

┌─────────────────────────────────────┐
│           MCP服务层                  │
│  index.mts (主入口)                 │
│  handleSmartAnalyze()               │
│  handleSmartCodeReview()            │
└─────────────────────────────────────┘
                    │
┌─────────────────────────────────────┐
│           业务逻辑层                 │
│  getCodeContent()                   │
│  executeServiceWithCleanup()        │
│  checkRepomixInstalled()            │
└─────────────────────────────────────┘
                    │
┌─────────────────────────────────────┐
│         核心服务层 (core/)           │
│  CodeReviewService                  │
│  AnalyzeRepoService                 │
│  BaseService                        │
└─────────────────────────────────────┘
                    │
┌─────────────────────────────────────┐
│         处理器与构建器               │
│  CodeProcessor                      │
│  CodeReviewPromptBuilder            │
│  AnalyzeRepoPromptBuilder          │
└─────────────────────────────────────┘
                    │
┌─────────────────────────────────────┐
│         Repomix集成层               │
│  gatherContext()                    │
│  executeRepomix()                   │
│  cleanupTempFile()                  │
└─────────────────────────────────────┘

核心组件说明

1. 提示构建器 (Prompt Builders)

• CodeReviewPromptTemplate: 构建代码审查的专业提示模板
• AnalyzeRepoPromptTemplate: 构建Vue项目架构分析的提示模板

2. 服务层 (Services)

• BaseService: 提供通用功能（文件读取、Repomix处理、参数验证）
• CodeReviewService: 专门的代码审查服务
• AnalyzeRepoService: 专门的仓库分析服务

3. 处理器 (Processors)

• CodeProcessor: 处理Repomix输出，支持大文件分块处理

类型系统

// 基础参数接口
interface BaseParams {
  code: string // 要分析的代码内容
  language: string // 代码语言类型
  baseDir: string // 项目基础目录路径
  repoPath?: string // 要分析的具体目录或文件路径
  fileName?: string // 文件名
  framework?: string // 前端框架类型
  fileTypes?: string[] // 文件类型过滤
  isMultiFileOrFolder?: boolean // 是否为多文件/文件夹分析
}

// 代码审查选项
interface CodeReviewOptions extends BaseParams {
  focusAreas: string[] // 重点关注领域
  vueVersion?: '2' | '3' // Vue版本
  componentType?: string // 组件类型
  detailLevel?: 'basic' | 'detailed' // 详细程度
}

// 仓库分析选项
interface AnalyzeRepoOptions extends BaseParams {
  repoPath: string // 必需的仓库路径
  detailLevel?: 'basic' | 'detailed'
  framework?: string
  vueVersion?: '2' | '3'
}

🛠️ 安装与配置

环境要求

• Node.js >= 16.x
• TypeScript 支持
• MCP 核心服务
• Repomix (推荐，用于多文件分析)

安装步骤

1. 克隆仓库
2. 安装依赖:

   npm install

3. 安装 Repomix (推荐):

   npm install -g repomix

启动服务

node monorepo/agi/smart-codereview/index.mts

📚 工具详解

1. smart_Code_Review - 智能代码审查工具

专门针对Vue.js项目的深度代码审查，使用专业的审查模板和分类体系。

参数说明

审查问题分类体系

服务使用专业的问题分类体系，包含29个问题类别：

focusAreas 完整列表

使用示例

{
  "code": "<template><div>{{ message }}</div></template>\n<script>\nexport default {\n  data() {\n    return { message: 'Hello' }\n  }\n}\n</script>",
  "language": "vue",
  "baseDir": "/Users/username/projects/vue-project",
  "repoPath": "src/components",
  "fileName": "HelloWorld.vue",
  "vueVersion": "3",
  "framework": "vue",
  "focusAreas": ["vue_best_practices", "security", "performance"]
}

2. smart_Analyze - 智能仓库分析工具

深度分析Vue项目架构，生成专业的需求与设计文档。

参数说明

分析输出结构

生成的文档遵循以下专业结构：

# [项目名称] - 需求与设计文档

## 1. 项目概述

### 1.1 项目背景

### 1.2 项目目标

## 2. 核心需求

### 2.1 功能需求

### 2.2 非功能需求

## 3. 系统设计

### 3.1 架构概览

### 3.2 组件设计

### 3.3 数据流程

### 3.4 状态管理

### 3.5 路由设计

## 4. 技术栈

## 5. 第三方依赖

## 6. 开发指南

## 7. 构建与部署

## 8. 未来扩展计划

使用示例

{
  "code": "// Vue项目代码内容",
  "language": "vue",
  "baseDir": "/Users/username/projects/vue-app",
  "repoPath": "src",
  "fileTypes": ["*.vue", "*.js", "*.ts", "*.scss"],
  "framework": "vue"
}

🔧 高级功能

多文件分析模式

服务智能检测分析模式：

1. 单文件模式 (isMultiFileOrFolder: false)

   • 直接分析提供的代码内容
   • 适用于单个文件的快速审查

2. 多文件/文件夹模式 (isMultiFileOrFolder: true)

   • 自动使用 Repomix 工具收集代码上下文
   • 支持整个项目或文件夹的深度分析
   • 自动处理文件依赖关系

自动模式判断逻辑

// 自动判断分析模式
if (result.isMultiFileOrFolder === undefined) {
  const hasRepoPathWithoutFileName = !!result.repoPath && result.fileName === undefined
  result.isMultiFileOrFolder = hasRepoPathWithoutFileName
  console.log(`自动判断走读类型: ${result.isMultiFileOrFolder ? '多文件/文件夹' : '单文件'}`)
}

Repomix集成功能

自动工具检测

async function checkRepomixInstalled(): Promise<boolean> {
  // 检查Repomix是否已安装
  // 如果未安装，服务会自动降级到单文件模式
}

上下文收集配置

const contextResult = await gatherContext({
  baseDir: baseDirToUse,
  targetDirs: targetDirsToUse,
  patterns: params.fileTypes || ['*.vue', '*.js', '*.ts', '*.jsx', '*.tsx', '*.css', '*.scss'],
  depth: 'full',
  includeConfigs: true,
  scopeToTargets: false
})

临时文件管理

智能清理策略

async function executeServiceWithCleanup<T>(
  serviceFunction: () => Promise<T>,
  tempFilePath?: string,
  serviceName: string = '服务'
): Promise<T> {
  try {
    const result = await serviceFunction()
    return result
  } finally {
    // 确保临时文件始终被清理
    if (tempFilePath) {
      await cleanupTempFile(tempFilePath)
    }
  }
}

文件命名策略

• 格式：repomix-output-{timestamp}-{randomString}.txt
• 位置：优先使用项目临时目录，失败时使用系统临时目录
• 清理：服务完成后自动清理，异常情况下通过finally确保清理

📊 输出格式

代码审查结果

审查结果严格按照以下结构输出：

一. 代码整体功能概述

提供对代码整体功能的清晰概述，包括各文件的主要功能和它们之间的关系。

二. 重要问题及缺陷清单

按严重程度排序的问题列表，每个问题包含简短描述和所在文件/行号。

三. 代码走查问题详细分析

每个问题的详细分析，格式如下：

**问题标题**: [问题简要描述]
**严重程度**: [严重/中等/轻微]
**问题描述**: [代码文件相对路径/文件名-->具体行号，详细分析问题根源]
**修复建议**:
[具体修复建议]
[示例代码]

四. 走查问题列表

表格格式的问题汇总：

仓库分析结果

生成专业的Vue项目需求与设计文档，包含：

1. 项目概述：整体描述，包括背景和目标
2. 核心需求：功能需求和非功能需求分析
3. 系统设计：架构图、组件设计、状态管理等
4. 技术栈：Vue生态系统工具分析
5. 开发指南：组件开发规范和目录结构说明

🔍 Vue特化分析

Vue版本特定检查

Vue 3特定分析

• Composition API的使用模式与抽象程度
• <script setup>语法糖的应用情况
• 响应式系统(ref/reactive/toRefs)使用策略
• 组合式函数(composables)设计与复用
• 新特性应用(Teleport/Suspense/Fragment)

Vue 2特定分析

• 混入(Mixins)的使用与组织
• 响应式陷阱规避措施
• 高阶组件(HOC)或过滤器使用情况
• Vue 2.7中Composition API的使用
• 迁移到Vue 3的准备情况

Vue生态系统识别

服务能够自动识别以下Vue生态工具：

• 核心库: Vue.js版本识别
• 路由: Vue Router配置分析
• 状态管理: Vuex/Pinia使用分析
• UI框架: Element Plus/Vuetify/Ant Design Vue
• CSS方案: SCSS/LESS/Tailwind CSS
• 构建工具: Vite/Webpack配置
• 类型系统: TypeScript集成程度

📝 最佳实践

代码审查最佳实践

1. 完整上下文: 提供足够的代码上下文以获得准确分析
2. Vue版本指定: 明确指定Vue版本以获得针对性检查
3. 关注领域选择: 根据项目阶段选择合适的focusAreas
4. 多文件分析: 对于复杂组件，使用多文件模式获得全局视图

仓库分析最佳实践

1. 项目根目录: 从项目根目录开始分析获得完整架构视图
2. 文件类型配置: 合理配置fileTypes以包含相关文件
3. 定期分析: 在重要开发节点进行架构分析
4. 文档维护: 将生成的文档作为项目文档的一部分维护

性能优化建议

1. Repomix安装: 安装Repomix工具以获得最佳分析体验
2. 文件范围: 合理限制分析文件范围避免过度分析
3. 缓存清理: 依赖服务的自动清理机制，无需手动管理

🐛 故障排除

常见问题

1. Repomix未安装

   • 症状：多文件分析降级为单文件模式
   • 解决：安装Repomix工具 npm install -g repomix

2. 路径解析错误

   • 症状：无法找到指定文件或目录
   • 解决：确保baseDir和repoPath路径正确

3. 临时文件残留

   • 症状：磁盘空间被临时文件占用
   • 解决：服务会自动清理，也可手动清理/tmp/repomix-output-*

调试信息

服务提供详细的执行日志：

检测到多文件或文件夹走读
使用gatherContext收集代码上下文
基础目录: /Users/username/projects/vue-project
目标路径: src/components
Repomix工具已安装
上下文收集完成，文件路径: /tmp/repomix-output-xxx.txt
开始执行代码审查...
代码审查完成
开始清理临时文件...
已删除临时文件: /tmp/repomix-output-xxx.txt

🚀 扩展开发

添加新的分析规则

在CodeReviewPromptTemplate中添加新的检查规则：

private readonly issueClassification: string = `
- **【新严重程度】** - 新问题分类(#新编号)
`

扩展Vue版本支持

在类型定义中添加新版本：

vueVersion?: '2' | '3' | '4' // 扩展版本支持

添加新的分析维度

在focusAreas中添加新的关注领域：

const validAreas = [
  // 现有领域...
  'new_focus_area' // 新的关注领域
]

📄 许可证

MIT

版本: 0.0.3 最后更新: 2024年12月 专业领域: Vue.js 生态系统代码质量分析

这个智能代码服务专门为Vue.js项目量身定制，提供专业的代码审查和架构分析功能，助力Vue开发团队提升代码质量和开发效率。