taskAnalyze

Instructions

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "taskAnalyze"
  }
}

Implementation Reference

• main.ts:837-853 (registration)

  Registration of the 'taskAnalyze' MCP tool, including empty input schema and thin inline handler that delegates to TaskManagerTool.analyzeTaskStatus() and formats the response.

  server.tool("taskAnalyze",
      "獲取任務狀態分析報告",
      {},
      async () => {
          try {
              const analysis = await TaskManagerTool.analyzeTaskStatus();
  
              return {
                  content: [{ type: "text", text: `任務分析報告：\n${JSON.stringify(analysis, null, 2)}` }]
              };
          } catch (error) {
              return {
                  content: [{ type: "text", text: `分析任務失敗: ${error instanceof Error ? error.message : "未知錯誤"}` }]
              };
          }
      }
  );

• tools/taskManagerTool.ts:446-569 (handler)

  Core handler implementation in TaskManagerTool class. Analyzes tasks: counts by status, overdue tasks, tag distribution, average completion time, average time difference vs estimate, with optional filter.

  public static async analyzeTaskStatus(filter?: TaskFilter): Promise<TaskAnalysis> {
    // 如果提供了篩選條件，先進行篩選；否則使用所有任務
    const tasks = filter ? await this.searchTasks(filter) : await this.readTasks();
  
    // 初始化分析結果
    const analysis: TaskAnalysis = {
      totalTasks: tasks.length,
      completedTasks: 0,
      pendingTasks: 0,
      inProgressTasks: 0,
      cancelledTasks: 0,
      overdueTasksCount: 0,
      tagDistribution: {}
    };
  
    // 計算任務分佈
    tasks.forEach(task => {
      // 根據狀態分類
      switch (task.status) {
        case TaskStatus.COMPLETED:
          analysis.completedTasks++;
          break;
        case TaskStatus.PENDING:
          analysis.pendingTasks++;
          break;
        case TaskStatus.IN_PROGRESS:
          analysis.inProgressTasks++;
          break;
        case TaskStatus.CANCELLED:
          analysis.cancelledTasks++;
          break;
      }
  
      // 檢查過期任務
      if (task.dueDate && task.status !== TaskStatus.COMPLETED && task.status !== TaskStatus.CANCELLED) {
        const dueDate = new Date(task.dueDate);
        const now = new Date();
        if (dueDate < now) {
          analysis.overdueTasksCount++;
        }
      }
  
      // 計算標籤分佈
      task.tags.forEach(tag => {
        if (!analysis.tagDistribution[tag]) {
          analysis.tagDistribution[tag] = 0;
        }
        analysis.tagDistribution[tag]++;
      });
    });
  
    // 計算完成任務的平均完成時間
    const completedTasks = tasks.filter(task => task.status === TaskStatus.COMPLETED);
    if (completedTasks.length > 0) {
      let totalCompletionTime = 0;
      let completedTasksWithTimes = 0;
  
      completedTasks.forEach(task => {
        // 使用工具類計算完成時間
        const completionTimeHours = TaskTimeUtils.calculateTaskWorkTimeHours(task);
  
        if (!isNaN(completionTimeHours)) {
          totalCompletionTime += completionTimeHours;
          completedTasksWithTimes++;
        }
      });
  
      if (completedTasksWithTimes > 0) {
        analysis.averageCompletionTime = totalCompletionTime / completedTasksWithTimes;
      }
    }
  
    // 計算完成任務的實際時間與預計時間的差異
    if (completedTasks.length > 0) {
      let totalTimeDifference = 0;
      let tasksWithTimeDifference = 0;
      const taskTimeDifferences: Array<{
        taskId: string;
        title: string;
        completionDate: string;
        estimatedTotalTime: number;
        actualWorkTime: number;
        timeDifference: number;
      }> = [];
  
      completedTasks.forEach(task => {
        // 只處理有步驟且有預計完成時間的任務
        const stepsWithEstimatedTime = task.steps.filter(step =>
          typeof step.estimatedTime === 'number' && step.estimatedTime > 0
        );
  
        if (stepsWithEstimatedTime.length > 0) {
          // 使用工具類計算任務時間
          const totalEstimatedTime = TaskTimeUtils.calculateTotalEstimatedTime(task);
          const actualCompletionMinutes = TaskTimeUtils.calculateTaskWorkTimeMinutes(task);
          
          // 計算時間差異（正值表示超時，負值表示提前完成）
          const timeDifference = TaskTimeUtils.calculateTimeDifference(task) || 0; // 如果返回null，使用0
  
          // 記錄任務時間差異詳情
          const timeInfo = TaskTimeUtils.getTaskTimeInfo(task);
          taskTimeDifferences.push({
            taskId: task.id,
            title: task.title,
            completionDate: task.actualCompletionDate || task.updatedAt,
            estimatedTotalTime: timeInfo.estimatedTotalTime,
            actualWorkTime: timeInfo.actualWorkTime, // 實際工作時間
            timeDifference: timeInfo.timeDifference || 0 // 如果返回null，使用0
          });
  
          totalTimeDifference += timeDifference;
          tasksWithTimeDifference++;
        }
      });
  
      // 計算平均時間差異
      if (tasksWithTimeDifference > 0) {
        analysis.averageTimeDifference = totalTimeDifference / tasksWithTimeDifference;
        analysis.taskTimeDifferences = taskTimeDifferences;
      }
    }
  
    return analysis;
  }