Skip to content

Commit 2989f03

Browse files
littleCarelesslittleCareless
committed
📝 docs(ai): 为AI服务提供者相关类添加完整注释文档
- 【AIProviderFactory】 - 添加工厂类整体功能说明 - 补充缓存机制和支持的提供者类型说明 - 为所有属性和方法添加JSDoc注释 - 【AI提供者实现类】 - 为DashScope、Doubao、Gemini等提供者添加类说明 - 补充模型配置列表的说明文档 - 为构造函数和核心方法添加详细注释 - 【工具类】 - 为generateHelper添加错误类型枚举说明 - 完善重试机制相关接口和函数的文档 - 新增代码审查提示获取方法的说明 整体改进了代码的可维护性和可读性，使开发者能更好地理解各个组件的功能和用途。
1 parent c9fe402 commit 2989f03

8 files changed

+284
-8
lines changed

‎src/ai/AIProviderFactory.ts

+57-1
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,47 @@ import { DashScopeProvider } from "./providers/DashScopeProvider";
1010
import { DoubaoProvider } from "./providers/DoubaoProvider";
1111
import { GeminiAIProvider } from "./providers/GeminiAIProvider";
1212

13+
/**
14+
* AI提供者工厂类，负责创建和管理不同AI服务提供者的实例
15+
* 实现了30分钟的缓存机制来重用提供者实例
16+
* 支持多种AI提供者，包括:
17+
* - OpenAI: 标准GPT模型
18+
* - Ollama: 本地部署模型
19+
* - VSCode: VSCode内置AI
20+
* - ZhipuAI: 智谱AI服务
21+
* - DashScope: 阿里云通义平台
22+
* - Doubao: 豆包AI平台
23+
* - Gemini: Google Gemini模型
24+
*/
1325
export class AIProviderFactory {
26+
/**
27+
* 存储AI提供者实例的映射
28+
* - key: 提供者类型标识符
29+
* - value: 提供者实例
30+
* @private
31+
*/
1432
private static providers: Map<string, AIProviderInterface> = new Map();
15-
private static readonly PROVIDER_CACHE_TTL = 1000 * 60 * 30; // 30分钟缓存
33+
34+
/**
35+
* 提供者实例的缓存过期时间
36+
* 默认为30分钟，超过该时间的实例会被清理
37+
* @private
38+
*/
39+
private static readonly PROVIDER_CACHE_TTL = 1000 * 60 * 30;
40+
41+
/**
42+
* 记录每个提供者实例的创建/访问时间戳
43+
* - key: 提供者类型标识符
44+
* - value: 时间戳
45+
* @private
46+
*/
1647
private static providerTimestamps: Map<string, number> = new Map();
1748

49+
/**
50+
* 清理过期的提供者实例
51+
* 遍历时间戳映射，移除超过TTL的实例和对应时间戳
52+
* @private
53+
*/
1854
private static cleanStaleProviders() {
1955
const now = Date.now();
2056
for (const [id, timestamp] of this.providerTimestamps.entries()) {
@@ -25,6 +61,14 @@ export class AIProviderFactory {
2561
}
2662
}
2763

64+
/**
65+
* 获取指定类型的AI提供者实例
66+
* 优先从缓存中获取，如果不存在或已过期则创建新实例
67+
*
68+
* @param type - 提供者类型标识符，如果未指定则使用配置中的默认值
69+
* @returns AI提供者实例
70+
* @throws Error 当提供者类型未知时抛出错误
71+
*/
2872
public static getProvider(type?: string): AIProviderInterface {
2973
this.cleanStaleProviders();
3074
const providerType =
@@ -74,6 +118,12 @@ export class AIProviderFactory {
74118
return provider;
75119
}
76120

121+
/**
122+
* 创建并返回所有支持的AI提供者的新实例
123+
* 注意: 这些实例不会被缓存，每次调用都会创建新实例
124+
*
125+
* @returns 包含所有可用AI提供者实例的数组
126+
*/
77127
public static getAllProviders(): AIProviderInterface[] {
78128
return [
79129
new OpenAIProvider(),
@@ -86,6 +136,12 @@ export class AIProviderFactory {
86136
];
87137
}
88138

139+
/**
140+
* 重新初始化指定的缓存提供者实例
141+
* 如果提供者存在且支持重初始化功能，则调用其reinitialize方法
142+
*
143+
* @param providerId - 需要重初始化的提供者ID
144+
*/
89145
public static reinitializeProvider(providerId: string): void {
90146
const provider = this.providers.get(providerId);
91147
if (provider && "reinitialize" in provider) {

‎src/ai/providers/DashScopeProvider.ts

+20
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ import { BaseOpenAIProvider } from "./BaseOpenAIProvider";
22
import { ConfigurationManager } from "../../config/ConfigurationManager";
33
import { AIModel } from "../types";
44

5+
/**
6+
* 阿里云DashScope通义千问模型配置列表
7+
* 定义了不同版本的Qwen模型及其参数设置
8+
*/
59
const dashscopeModels: AIModel[] = [
610
{
711
id: "qwen-max",
@@ -118,7 +122,15 @@ const dashscopeModels: AIModel[] = [
118122
},
119123
];
120124

125+
/**
126+
* 阿里云DashScope服务提供者实现类
127+
* 继承自BaseOpenAIProvider，提供对通义千问API的访问能力
128+
*/
121129
export class DashScopeProvider extends BaseOpenAIProvider {
130+
/**
131+
* 创建DashScope提供者实例
132+
* 从配置管理器获取API密钥，初始化基类配置
133+
*/
122134
constructor() {
123135
const configManager = ConfigurationManager.getInstance();
124136
super({
@@ -131,6 +143,10 @@ export class DashScopeProvider extends BaseOpenAIProvider {
131143
});
132144
}
133145

146+
/**
147+
* 检查DashScope服务是否可用
148+
* @returns 如果API密钥已配置返回true
149+
*/
134150
async isAvailable(): Promise<boolean> {
135151
try {
136152
return !!this.config.apiKey;
@@ -139,6 +155,10 @@ export class DashScopeProvider extends BaseOpenAIProvider {
139155
}
140156
}
141157

158+
/**
159+
* 刷新可用的模型列表
160+
* @returns 返回预定义的模型ID列表
161+
*/
142162
async refreshModels(): Promise<string[]> {
143163
return Promise.resolve(dashscopeModels.map((m) => m.id));
144164
}

‎src/ai/providers/DoubaoProvider.ts

+20
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ import { BaseOpenAIProvider } from "./BaseOpenAIProvider";
22
import { ConfigurationManager } from "../../config/ConfigurationManager";
33
import { AIModel } from "../types";
44

5+
/**
6+
* 豆包AI支持的模型配置列表
7+
* 包含Lite和Pro系列的不同规格模型
8+
*/
59
const doubaoModels: AIModel[] = [
610
{
711
id: "doubao-lite-4k",
@@ -119,7 +123,15 @@ const doubaoModels: AIModel[] = [
119123
},
120124
];
121125

126+
/**
127+
* 豆包AI服务提供者实现类
128+
* 继承自BaseOpenAIProvider，提供对豆包AI API的访问能力
129+
*/
122130
export class DoubaoProvider extends BaseOpenAIProvider {
131+
/**
132+
* 创建豆包AI提供者实例
133+
* 从配置管理器获取API密钥，初始化基类配置
134+
*/
123135
constructor() {
124136
const configManager = ConfigurationManager.getInstance();
125137
super({
@@ -132,6 +144,10 @@ export class DoubaoProvider extends BaseOpenAIProvider {
132144
});
133145
}
134146

147+
/**
148+
* 检查豆包AI服务是否可用
149+
* @returns 如果API密钥已配置返回true
150+
*/
135151
async isAvailable(): Promise<boolean> {
136152
try {
137153
return !!this.config.apiKey;
@@ -140,6 +156,10 @@ export class DoubaoProvider extends BaseOpenAIProvider {
140156
}
141157
}
142158

159+
/**
160+
* 刷新可用的模型列表
161+
* @returns 返回预定义的模型ID列表
162+
*/
143163
async refreshModels(): Promise<string[]> {
144164
return Promise.resolve(doubaoModels.map((m) => m.id));
145165
}

‎src/ai/providers/GeminiAIProvider.ts

+20
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ import { BaseOpenAIProvider } from "./BaseOpenAIProvider";
22
import { ConfigurationManager } from "../../config/ConfigurationManager";
33
import { AIModel } from "../types";
44

5+
/**
6+
* Gemini支持的AI模型配置列表
7+
* 定义了不同版本的Gemini模型及其特性
8+
*/
59
const geminiModels: AIModel[] = [
610
{
711
id: "gemini-1.5-flash",
@@ -47,7 +51,15 @@ const geminiModels: AIModel[] = [
4751
// 可以根据需要添加更多模型
4852
];
4953

54+
/**
55+
* Google Gemini AI服务提供者实现类
56+
* 继承自BaseOpenAIProvider，提供对Gemini API的访问能力
57+
*/
5058
export class GeminiAIProvider extends BaseOpenAIProvider {
59+
/**
60+
* 创建Gemini AI提供者实例
61+
* 从配置管理器获取API密钥，初始化基类配置
62+
*/
5163
constructor() {
5264
const configManager = ConfigurationManager.getInstance();
5365
super({
@@ -60,6 +72,10 @@ export class GeminiAIProvider extends BaseOpenAIProvider {
6072
});
6173
}
6274

75+
/**
76+
* 检查Gemini服务是否可用
77+
* @returns 如果API密钥已配置返回true
78+
*/
6379
async isAvailable(): Promise<boolean> {
6480
try {
6581
return !!this.config.apiKey;
@@ -68,6 +84,10 @@ export class GeminiAIProvider extends BaseOpenAIProvider {
6884
}
6985
}
7086

87+
/**
88+
* 刷新可用的Gemini模型列表
89+
* @returns 返回预定义的模型ID列表
90+
*/
7191
async refreshModels(): Promise<string[]> {
7292
return Promise.resolve(geminiModels.map((m) => m.id));
7393
}

‎src/ai/providers/OllamaProvider.ts

+54
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,27 @@ import { LocalizationManager } from "../../utils/LocalizationManager";
1212
import { generateWithRetry, getSystemPrompt } from "../utils/generateHelper";
1313
import { getWeeklyReportPrompt } from "../../prompt/weeklyReport";
1414

15+
/**
16+
* Ollama AI服务提供者实现类
17+
* 提供对本地部署的Ollama服务的访问能力
18+
*/
1519
export class OllamaProvider implements AIProvider {
20+
/** Ollama客户端实例 */
1621
private ollama: Ollama;
22+
23+
/** 提供者标识信息 */
1724
private readonly provider = {
1825
id: "ollama" as AIProviders,
1926
name: "Ollama",
2027
} as const;
28+
29+
/** 配置管理器实例 */
2130
private configManager: ConfigurationManager;
2231

32+
/**
33+
* 创建Ollama提供者实例
34+
* 初始化Ollama客户端并配置基础URL
35+
*/
2336
constructor() {
2437
this.configManager = ConfigurationManager.getInstance();
2538
const baseUrl = this.getBaseUrl();
@@ -28,13 +41,23 @@ export class OllamaProvider implements AIProvider {
2841
});
2942
}
3043

44+
/**
45+
* 获取Ollama服务的基础URL
46+
* @returns 配置的URL或默认的localhost URL
47+
* @private
48+
*/
3149
private getBaseUrl(): string {
3250
return (
3351
this.configManager.getConfig("PROVIDERS_OLLAMA_BASEURL") ||
3452
"http://localhost:11434"
3553
);
3654
}
3755

56+
/**
57+
* 刷新可用的Ollama模型列表
58+
* @returns 返回模型名称的数组
59+
* @throws 如果获取失败则返回空数组并显示错误通知
60+
*/
3861
async refreshModels(): Promise<string[]> {
3962
try {
4063
const response = await this.ollama.list();
@@ -53,6 +76,12 @@ export class OllamaProvider implements AIProvider {
5376
}
5477
}
5578

79+
/**
80+
* 生成AI响应
81+
* @param params - AI请求参数
82+
* @returns 包含生成内容和使用统计的响应
83+
* @throws 如果生成失败会通过重试机制处理
84+
*/
5685
async generateResponse(params: AIRequestParams): Promise<AIResponse> {
5786
return generateWithRetry(
5887
params,
@@ -97,6 +126,12 @@ export class OllamaProvider implements AIProvider {
97126
);
98127
}
99128

129+
/**
130+
* 生成周报内容
131+
* @param commits - 提交记录数组
132+
* @param model - 可选的指定模型
133+
* @returns 生成的周报内容和统计信息
134+
*/
100135
async generateWeeklyReport(
101136
commits: string[],
102137
model?: AIModel
@@ -135,6 +170,10 @@ export class OllamaProvider implements AIProvider {
135170
};
136171
}
137172

173+
/**
174+
* 检查Ollama服务是否可用
175+
* @returns 如果能成功获取模型列表则返回true
176+
*/
138177
async isAvailable(): Promise<boolean> {
139178
try {
140179
await this.ollama.list();
@@ -144,6 +183,11 @@ export class OllamaProvider implements AIProvider {
144183
}
145184
}
146185

186+
/**
187+
* 获取支持的AI模型列表
188+
* @returns 返回支持的模型配置数组
189+
* @throws 如果获取失败则显示错误通知
190+
*/
147191
async getModels(): Promise<AIModel[]> {
148192
try {
149193
const response = await this.ollama.list();
@@ -169,12 +213,22 @@ export class OllamaProvider implements AIProvider {
169213
}
170214
}
171215

216+
/**
217+
* 获取提供者显示名称
218+
*/
172219
getName(): string {
173220
return this.provider.name;
174221
}
175222

223+
/**
224+
* 获取提供者ID
225+
*/
176226
getId(): string {
177227
return this.provider.id;
178228
}
229+
230+
/**
231+
* 资源释放
232+
*/
179233
dispose() {}
180234
}

0 commit comments

Comments
 (0)