📝 docs(ai): 为AI服务提供者相关类添加完整注释文档

- 【AIProviderFactory】
  - 添加工厂类整体功能说明
  - 补充缓存机制和支持的提供者类型说明
  - 为所有属性和方法添加JSDoc注释

- 【AI提供者实现类】
  - 为DashScope、Doubao、Gemini等提供者添加类说明
  - 补充模型配置列表的说明文档
  - 为构造函数和核心方法添加详细注释

- 【工具类】
  - 为generateHelper添加错误类型枚举说明
  - 完善重试机制相关接口和函数的文档
  - 新增代码审查提示获取方法的说明

整体改进了代码的可维护性和可读性，使开发者能更好地理解各个组件的功能和用途。

src/ai/AIProviderFactory.ts

@@ -10,11 +10,47 @@ import { DashScopeProvider } from "./providers/DashScopeProvider";
 import { DoubaoProvider } from "./providers/DoubaoProvider";
 import { GeminiAIProvider } from "./providers/GeminiAIProvider";
 
+/**
+ * AI提供者工厂类，负责创建和管理不同AI服务提供者的实例
+ * 实现了30分钟的缓存机制来重用提供者实例
+ * 支持多种AI提供者，包括:
+ * - OpenAI: 标准GPT模型
+ * - Ollama: 本地部署模型
+ * - VSCode: VSCode内置AI
+ * - ZhipuAI: 智谱AI服务
+ * - DashScope: 阿里云通义平台
+ * - Doubao: 豆包AI平台
+ * - Gemini: Google Gemini模型
+ */
 export class AIProviderFactory {
+  /**
+   * 存储AI提供者实例的映射
+   * - key: 提供者类型标识符
+   * - value: 提供者实例
+   * @private
+   */
   private static providers: Map<string, AIProviderInterface> = new Map();
-  private static readonly PROVIDER_CACHE_TTL = 1000 * 60 * 30; // 30分钟缓存
+
+  /**
+   * 提供者实例的缓存过期时间
+   * 默认为30分钟，超过该时间的实例会被清理
+   * @private
+   */
+  private static readonly PROVIDER_CACHE_TTL = 1000 * 60 * 30;
+
+  /**
+   * 记录每个提供者实例的创建/访问时间戳
+   * - key: 提供者类型标识符
+   * - value: 时间戳
+   * @private
+   */
   private static providerTimestamps: Map<string, number> = new Map();
 
+  /**
+   * 清理过期的提供者实例
+   * 遍历时间戳映射，移除超过TTL的实例和对应时间戳
+   * @private
+   */
   private static cleanStaleProviders() {
     const now = Date.now();
     for (const [id, timestamp] of this.providerTimestamps.entries()) {
@@ -25,6 +61,14 @@ export class AIProviderFactory {
     }
   }
 
+  /**
+   * 获取指定类型的AI提供者实例
+   * 优先从缓存中获取，如果不存在或已过期则创建新实例
+   *
+   * @param type - 提供者类型标识符，如果未指定则使用配置中的默认值
+   * @returns AI提供者实例
+   * @throws Error 当提供者类型未知时抛出错误
+   */
   public static getProvider(type?: string): AIProviderInterface {
     this.cleanStaleProviders();
     const providerType =
@@ -74,6 +118,12 @@ export class AIProviderFactory {
     return provider;
   }
 
+  /**
+   * 创建并返回所有支持的AI提供者的新实例
+   * 注意: 这些实例不会被缓存，每次调用都会创建新实例
+   *
+   * @returns 包含所有可用AI提供者实例的数组
+   */
   public static getAllProviders(): AIProviderInterface[] {
     return [
       new OpenAIProvider(),
@@ -86,6 +136,12 @@ export class AIProviderFactory {
     ];
   }
 
+  /**
+   * 重新初始化指定的缓存提供者实例
+   * 如果提供者存在且支持重初始化功能，则调用其reinitialize方法
+   *
+   * @param providerId - 需要重初始化的提供者ID
+   */
   public static reinitializeProvider(providerId: string): void {
     const provider = this.providers.get(providerId);
     if (provider && "reinitialize" in provider) {

src/ai/providers/DashScopeProvider.ts

@@ -2,6 +2,10 @@ import { BaseOpenAIProvider } from "./BaseOpenAIProvider";
 import { ConfigurationManager } from "../../config/ConfigurationManager";
 import { AIModel } from "../types";
 
+/**
+ * 阿里云DashScope通义千问模型配置列表
+ * 定义了不同版本的Qwen模型及其参数设置
+ */
 const dashscopeModels: AIModel[] = [
   {
     id: "qwen-max",
@@ -118,7 +122,15 @@ const dashscopeModels: AIModel[] = [
   },
 ];
 
+/**
+ * 阿里云DashScope服务提供者实现类
+ * 继承自BaseOpenAIProvider，提供对通义千问API的访问能力
+ */
 export class DashScopeProvider extends BaseOpenAIProvider {
+  /**
+   * 创建DashScope提供者实例
+   * 从配置管理器获取API密钥，初始化基类配置
+   */
   constructor() {
     const configManager = ConfigurationManager.getInstance();
     super({
@@ -131,6 +143,10 @@ export class DashScopeProvider extends BaseOpenAIProvider {
     });
   }
 
+  /**
+   * 检查DashScope服务是否可用
+   * @returns 如果API密钥已配置返回true
+   */
   async isAvailable(): Promise<boolean> {
     try {
       return !!this.config.apiKey;
@@ -139,6 +155,10 @@ export class DashScopeProvider extends BaseOpenAIProvider {
     }
   }
 
+  /**
+   * 刷新可用的模型列表
+   * @returns 返回预定义的模型ID列表
+   */
   async refreshModels(): Promise<string[]> {
     return Promise.resolve(dashscopeModels.map((m) => m.id));
   }

src/ai/providers/DoubaoProvider.ts

@@ -2,6 +2,10 @@ import { BaseOpenAIProvider } from "./BaseOpenAIProvider";
 import { ConfigurationManager } from "../../config/ConfigurationManager";
 import { AIModel } from "../types";
 
+/**
+ * 豆包AI支持的模型配置列表
+ * 包含Lite和Pro系列的不同规格模型
+ */
 const doubaoModels: AIModel[] = [
   {
     id: "doubao-lite-4k",
@@ -119,7 +123,15 @@ const doubaoModels: AIModel[] = [
   },
 ];
 
+/**
+ * 豆包AI服务提供者实现类
+ * 继承自BaseOpenAIProvider，提供对豆包AI API的访问能力
+ */
 export class DoubaoProvider extends BaseOpenAIProvider {
+  /**
+   * 创建豆包AI提供者实例
+   * 从配置管理器获取API密钥，初始化基类配置
+   */
   constructor() {
     const configManager = ConfigurationManager.getInstance();
     super({
@@ -132,6 +144,10 @@ export class DoubaoProvider extends BaseOpenAIProvider {
     });
   }
 
+  /**
+   * 检查豆包AI服务是否可用
+   * @returns 如果API密钥已配置返回true
+   */
   async isAvailable(): Promise<boolean> {
     try {
       return !!this.config.apiKey;
@@ -140,6 +156,10 @@ export class DoubaoProvider extends BaseOpenAIProvider {
     }
   }
 
+  /**
+   * 刷新可用的模型列表
+   * @returns 返回预定义的模型ID列表
+   */
   async refreshModels(): Promise<string[]> {
     return Promise.resolve(doubaoModels.map((m) => m.id));
   }

src/ai/providers/GeminiAIProvider.ts

@@ -2,6 +2,10 @@ import { BaseOpenAIProvider } from "./BaseOpenAIProvider";
 import { ConfigurationManager } from "../../config/ConfigurationManager";
 import { AIModel } from "../types";
 
+/**
+ * Gemini支持的AI模型配置列表
+ * 定义了不同版本的Gemini模型及其特性
+ */
 const geminiModels: AIModel[] = [
   {
     id: "gemini-1.5-flash",
@@ -47,7 +51,15 @@ const geminiModels: AIModel[] = [
   // 可以根据需要添加更多模型
 ];
 
+/**
+ * Google Gemini AI服务提供者实现类
+ * 继承自BaseOpenAIProvider，提供对Gemini API的访问能力
+ */
 export class GeminiAIProvider extends BaseOpenAIProvider {
+  /**
+   * 创建Gemini AI提供者实例
+   * 从配置管理器获取API密钥，初始化基类配置
+   */
   constructor() {
     const configManager = ConfigurationManager.getInstance();
     super({
@@ -60,6 +72,10 @@ export class GeminiAIProvider extends BaseOpenAIProvider {
     });
   }
 
+  /**
+   * 检查Gemini服务是否可用
+   * @returns 如果API密钥已配置返回true
+   */
   async isAvailable(): Promise<boolean> {
     try {
       return !!this.config.apiKey;
@@ -68,6 +84,10 @@ export class GeminiAIProvider extends BaseOpenAIProvider {
     }
   }
 
+  /**
+   * 刷新可用的Gemini模型列表
+   * @returns 返回预定义的模型ID列表
+   */
   async refreshModels(): Promise<string[]> {
     return Promise.resolve(geminiModels.map((m) => m.id));
   }

src/ai/providers/OllamaProvider.ts

@@ -12,14 +12,27 @@ import { LocalizationManager } from "../../utils/LocalizationManager";
 import { generateWithRetry, getSystemPrompt } from "../utils/generateHelper";
 import { getWeeklyReportPrompt } from "../../prompt/weeklyReport";
 
+/**
+ * Ollama AI服务提供者实现类
+ * 提供对本地部署的Ollama服务的访问能力
+ */
 export class OllamaProvider implements AIProvider {
+  /** Ollama客户端实例 */
   private ollama: Ollama;
+
+  /** 提供者标识信息 */
   private readonly provider = {
     id: "ollama" as AIProviders,
     name: "Ollama",
   } as const;
+
+  /** 配置管理器实例 */
   private configManager: ConfigurationManager;
 
+  /**
+   * 创建Ollama提供者实例
+   * 初始化Ollama客户端并配置基础URL
+   */
   constructor() {
     this.configManager = ConfigurationManager.getInstance();
     const baseUrl = this.getBaseUrl();
@@ -28,13 +41,23 @@ export class OllamaProvider implements AIProvider {
     });
   }
 
+  /**
+   * 获取Ollama服务的基础URL
+   * @returns 配置的URL或默认的localhost URL
+   * @private
+   */
   private getBaseUrl(): string {
     return (
       this.configManager.getConfig("PROVIDERS_OLLAMA_BASEURL") ||
       "http://localhost:11434"
     );
   }
 
+  /**
+   * 刷新可用的Ollama模型列表
+   * @returns 返回模型名称的数组
+   * @throws 如果获取失败则返回空数组并显示错误通知
+   */
   async refreshModels(): Promise<string[]> {
     try {
       const response = await this.ollama.list();
@@ -53,6 +76,12 @@ export class OllamaProvider implements AIProvider {
     }
   }
 
+  /**
+   * 生成AI响应
+   * @param params - AI请求参数
+   * @returns 包含生成内容和使用统计的响应
+   * @throws 如果生成失败会通过重试机制处理
+   */
   async generateResponse(params: AIRequestParams): Promise<AIResponse> {
     return generateWithRetry(
       params,
@@ -97,6 +126,12 @@ export class OllamaProvider implements AIProvider {
     );
   }
 
+  /**
+   * 生成周报内容
+   * @param commits - 提交记录数组
+   * @param model - 可选的指定模型
+   * @returns 生成的周报内容和统计信息
+   */
   async generateWeeklyReport(
     commits: string[],
     model?: AIModel
@@ -135,6 +170,10 @@ export class OllamaProvider implements AIProvider {
     };
   }
 
+  /**
+   * 检查Ollama服务是否可用
+   * @returns 如果能成功获取模型列表则返回true
+   */
   async isAvailable(): Promise<boolean> {
     try {
       await this.ollama.list();
@@ -144,6 +183,11 @@ export class OllamaProvider implements AIProvider {
     }
   }
 
+  /**
+   * 获取支持的AI模型列表
+   * @returns 返回支持的模型配置数组
+   * @throws 如果获取失败则显示错误通知
+   */
   async getModels(): Promise<AIModel[]> {
     try {
       const response = await this.ollama.list();
@@ -169,12 +213,22 @@ export class OllamaProvider implements AIProvider {
     }
   }
 
+  /**
+   * 获取提供者显示名称
+   */
   getName(): string {
     return this.provider.name;
   }
 
+  /**
+   * 获取提供者ID
+   */
   getId(): string {
     return this.provider.id;
   }
+
+  /**
+   * 资源释放
+   */
   dispose() {}
 }