📝 docs(ts): 优化代码文档和注释

- 为 ModelPickerService 类添加 JSDoc 文档说明
- 为 WeeklyReportService 类添加完整的代码注释和接口文档
- 改进了代码的可读性和可维护性
-【功能说明】
  - 补充了模型选择服务的方法说明
  - 添加了周报服务的类型定义和方法文档
  - 规范化了代码注释格式

src/services/ModelPickerService.ts

@@ -3,18 +3,31 @@ import { AIProviderFactory } from "../ai/AIProviderFactory";
 import { NotificationHandler } from "../utils/NotificationHandler";
 import { LocalizationManager } from "../utils/LocalizationManager";
 
+/**
+ * Service class for handling AI model selection via VS Code's quick pick interface
+ */
 export class ModelPickerService {
+  /**
+   * Shows a quick pick dialog for selecting AI provider and model
+   * @param currentProvider - Currently selected AI provider
+   * @param currentModel - Currently selected model name
+   * @returns Promise resolving to selected provider and model, or undefined if cancelled
+   * @throws {Error} When model list loading fails
+   */
   static async showModelPicker(
     currentProvider: string,
     currentModel: string
   ): Promise<{ provider: string; model: string } | undefined> {
     const locManager = LocalizationManager.getInstance();
     try {
+      // Get all available AI providers
       const providers = AIProviderFactory.getAllProviders();
+      /** Map to store provider name to available models mapping */
       const modelsMap = new Map<string, string[]>();
 
       console.log("providers", providers);
 
+      // Show progress notification while loading models
       const progressMsg = locManager.getMessage("ai.model.loading");
       await vscode.window.withProgress(
         {
@@ -23,6 +36,7 @@ export class ModelPickerService {
           cancellable: false,
         },
         async () => {
+          // Load models from each available provider
           await Promise.all(
             providers.map(async (provider) => {
               if (await provider.isAvailable()) {
@@ -37,12 +51,15 @@ export class ModelPickerService {
         }
       );
 
+      // Prepare items for quick pick dialog
       const items: vscode.QuickPickItem[] = [];
       for (const [provider, models] of modelsMap) {
+        // Add provider as separator
         items.push({
           label: provider,
           kind: vscode.QuickPickItemKind.Separator,
         });
+        // Add models under provider
         models.forEach((model) => {
           items.push({
             label: model,
@@ -52,6 +69,7 @@ export class ModelPickerService {
         });
       }
 
+      // Create and configure quick pick dialog
       const quickPick = vscode.window.createQuickPick();
       quickPick.items = items;
       quickPick.title = locManager.getMessage("ai.model.picker.title");
@@ -60,6 +78,7 @@ export class ModelPickerService {
       );
       quickPick.ignoreFocusOut = true;
 
+      // Wait for user selection
       const result = await new Promise<vscode.QuickPickItem | undefined>(
         (resolve) => {
           quickPick.onDidAccept(() => resolve(quickPick.selectedItems[0]));
@@ -70,6 +89,7 @@ export class ModelPickerService {
 
       quickPick.dispose();
 
+      // Return selected provider and model if available
       if (result && result.description) {
         return { provider: result.description, model: result.label };
       }

src/services/weeklyReport.ts

@@ -7,15 +7,36 @@ import {
   GitCommitStrategy,
   SvnCommitStrategy,
 } from "../scm/CommitLogStrategy";
+
+/**
+ * Represents a time period with start and end dates
+ */
 interface Period {
+  /** Start date in string format */
   startDate: string;
+  /** End date in string format */
   endDate: string;
 }
+
+/**
+ * Service class for generating weekly reports from source control commits
+ * Supports both Git and SVN repositories
+ */
 export class WeeklyReportService {
+  /** SCM provider instance for repository operations */
   private scmProvider: ISCMProvider | undefined = undefined;
+
+  /** Strategy for retrieving commit logs */
   private commitStrategy: CommitLogStrategy | undefined = undefined;
+
+  /** Service for handling author information */
   private authorService: AuthorService | undefined = undefined;
 
+  /**
+   * Initializes the weekly report service
+   * Sets up SCM provider, commit strategy and author service
+   * @throws {Error} When no SCM provider is detected
+   */
   async initialize(): Promise<void> {
     const workspacePath = this.getWorkspacePath();
 
@@ -28,6 +49,12 @@ export class WeeklyReportService {
     this.commitStrategy = this.createCommitStrategy(this.scmProvider.type);
   }
 
+  /**
+   * Generates work items from commits within specified period
+   * @param period - Time period to generate report for
+   * @returns Promise resolving to array of work items
+   * @throws {Error} When service is not initialized
+   */
   async generate(period: Period): Promise<WorkItem[]> {
     if (!this.scmProvider || !this.commitStrategy || !this.authorService) {
       await this.initialize();
@@ -48,13 +75,24 @@ export class WeeklyReportService {
     }));
   }
 
+  /**
+   * Retrieves the current author from the SCM system
+   * @returns Promise resolving to author name
+   * @throws {Error} When service is not initialized
+   */
   async getCurrentAuthor(): Promise<string> {
     if (!this.scmProvider || !this.authorService) {
       await this.initialize();
     }
     return await this.authorService!.getAuthor(this.scmProvider!.type);
   }
 
+  /**
+   * Gets the path of the current workspace
+   * @returns Filesystem path of current workspace
+   * @throws {Error} When no workspace is open
+   * @private
+   */
   private getWorkspacePath(): string {
     const workspaceFolders = vscode.workspace.workspaceFolders;
     if (!workspaceFolders?.[0]) {
@@ -63,6 +101,12 @@ export class WeeklyReportService {
     return workspaceFolders[0].uri.fsPath;
   }
 
+  /**
+   * Creates appropriate commit log strategy based on SCM type
+   * @param type - Type of SCM system ('git' or 'svn')
+   * @returns Commit log strategy instance
+   * @private
+   */
   private createCommitStrategy(type: "git" | "svn"): CommitLogStrategy {
     return type === "git" ? new GitCommitStrategy() : new SvnCommitStrategy();
   }