spec-agent 1.0.3

package/src/commands/analyze.ts

@@ -0,0 +1,322 @@
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { Command } from 'commander';
+import { Logger } from '../utils/logger';
+import { 
+  ensureDir, 
+  fileExists, 
+  readJson, 
+  writeJson,
+  formatSize,
+  readFileContent
+} from '../utils/file';
+import { Manifest, ChunkSummary } from '../types';
+import { 
+  getLLMConfigForPurpose, 
+  validateLLMConfig, 
+  analyzeChunkWithLLM 
+} from '../services/llm';
+import { readChunkContent } from '../services/document-parser';
+
+interface AnalyzeOptions {
+  manifest: string;
+  output: string;
+  agents: string;
+  chunks?: string;
+  focus: string;
+  retries: string;
+  budgetTokens?: string;
+  applyLearned?: boolean;
+  dryRun?: boolean;
+  yes?: boolean;
+}
+
+interface ChunkFailure {
+  chunkId: number;
+  sourceFiles: string[];
+  attempts: number;
+  error: string;
+}
+
+type BatchResult =
+  | { ok: true; summary: ChunkSummary }
+  | { ok: false; failure: ChunkFailure };
+
+const ANALYZE_EXIT_CODE = {
+  INPUT_ERROR: 1,
+  CONFIG_ERROR: 2,
+  PARTIAL_FAILED: 3,
+  RUNTIME_ERROR: 10,
+} as const;
+
+export async function analyzeCommand(options: AnalyzeOptions, command: Command): Promise<void> {
+  const logger = new Logger();
+  
+  try {
+    // Check manifest exists
+    const manifestPath = path.resolve(options.manifest);
+    if (!(await fileExists(manifestPath))) {
+      logger.error(`[E_ANALYZE_INPUT] Manifest not found: ${options.manifest}`);
+      logger.info('Run spec-agent scan first to create a manifest.');
+      process.exit(ANALYZE_EXIT_CODE.INPUT_ERROR);
+    }
+
+    const manifest: Manifest = await readJson(manifestPath);
+    
+    // Determine which chunks to analyze
+    let chunkIndices: number[] = [];
+    if (options.chunks) {
+      chunkIndices = options.chunks.split(',').map(s => parseInt(s.trim(), 10));
+    } else {
+      chunkIndices = manifest.chunks.map((_, i) => i);
+    }
+
+    // Validate chunk indices
+    const invalidIndices = chunkIndices.filter(i => i < 0 || i >= manifest.chunks.length);
+    if (invalidIndices.length > 0) {
+      logger.error(`[E_ANALYZE_INPUT] Invalid chunk indices: ${invalidIndices.join(', ')}`);
+      logger.info(`Valid range: 0-${manifest.chunks.length - 1}`);
+      process.exit(ANALYZE_EXIT_CODE.INPUT_ERROR);
+    }
+
+    // Get LLM config
+    const llmConfig = getLLMConfigForPurpose('analyze');
+    
+    if (options.dryRun) {
+      logger.info('Dry run mode - analysis plan:');
+      logger.info(`LLM Config: ${llmConfig.model} @ ${llmConfig.baseUrl}`);
+      for (const idx of chunkIndices) {
+        const chunk = manifest.chunks[idx];
+        logger.info(`  Chunk ${idx}: ${chunk.sourceFiles.length} files, ${formatSize(chunk.size)}`);
+      }
+      return;
+    }
+
+    // Validate LLM config (skip if explicitly bypassed)
+    try {
+      validateLLMConfig(llmConfig);
+    } catch (error) {
+      logger.error(`LLM Configuration Error: ${error instanceof Error ? error.message : String(error)}`);
+      logger.info('\nTo use analyze, set one of these environment variables:');
+      logger.info('  export OPENAI_API_KEY=your_key_here');
+      logger.info('  export LLM_API_KEY=your_key_here');
+      logger.info('\nOptional configuration:');
+      logger.info('  export OPENAI_BASE_URL=https://api.openai.com/v1  # or your custom endpoint');
+      logger.info('  export LLM_MODEL=gpt-4o-mini                      # or gpt-4o, claude-3-sonnet, etc.');
+      process.exit(ANALYZE_EXIT_CODE.CONFIG_ERROR);
+    }
+
+    logger.info(`Analyzing ${chunkIndices.length} chunks with focus: ${options.focus}`);
+    logger.info(`Using LLM: ${llmConfig.model}`);
+
+    // Ensure output directory
+    const outputDir = path.resolve(options.output);
+    await ensureDir(outputDir);
+    const cacheDir = path.join(outputDir, '.cache', 'analyze');
+    await ensureDir(cacheDir);
+
+    // Analyze chunks
+    const results: ChunkSummary[] = [];
+    const startTime = Date.now();
+
+    logger.info('Starting parallel analysis...');
+
+    // Process chunks in parallel
+    const concurrencyRaw = options.agents === 'auto' 
+      ? Math.min(4, chunkIndices.length)
+      : parseInt(options.agents, 10);
+    const concurrency = Number.isFinite(concurrencyRaw) && concurrencyRaw > 0
+      ? concurrencyRaw
+      : 1;
+
+    let totalTokens = 0;
+    let cachedChunks = 0;
+    let llmInvocations = 0;
+    const maxRetries = Math.max(0, parseInt(options.retries || '1', 10) || 0);
+    const budgetTokens = Math.max(0, parseInt(options.budgetTokens || process.env.MAX_ANALYZE_TOKENS || '0', 10) || 0);
+    const failures: ChunkFailure[] = [];
+
+    for (let i = 0; i < chunkIndices.length; i += concurrency) {
+      const batch = chunkIndices.slice(i, i + concurrency);
+      
+      logger.progress(i, chunkIndices.length, `Analyzing chunks ${batch.join(', ')}...`);
+
+      // Process batch in parallel
+      const batchResults: BatchResult[] = await Promise.all(
+        batch.map(async (idx) => {
+          const chunk = manifest.chunks[idx];
+
+          for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+              // Read chunk content
+              logger.debug(`Reading chunk ${idx}: ${chunk.sourceFiles.length} files`);
+              let content: string;
+
+              if (chunk.contentPath && await fileExists(chunk.contentPath)) {
+                // Read from chunk file
+                content = await readFileContent(chunk.contentPath);
+              } else if (chunk.content) {
+                // Read from manifest (legacy)
+                content = chunk.content;
+              } else {
+                // Fallback: read from source files
+                content = await readChunkContent(chunk.sourceFiles);
+              }
+
+              const cacheKey = createHash('sha256')
+                .update(content)
+                .update(`|focus:${options.focus}|model:${llmConfig.model}|v:analyze-2`)
+                .digest('hex');
+              const cachePath = path.join(cacheDir, `${cacheKey}.json`);
+              if (await fileExists(cachePath)) {
+                const cached = await readJson<ChunkSummary>(cachePath);
+                cachedChunks++;
+                if (cached.llmUsage) {
+                  totalTokens += cached.llmUsage.totalTokens;
+                }
+                cached.sourceFiles = chunk.sourceFiles;
+                cached.size = formatSize(chunk.size);
+                return { ok: true as const, summary: cached };
+              }
+
+              if (budgetTokens > 0 && totalTokens >= budgetTokens) {
+                return {
+                  ok: false as const,
+                  failure: {
+                    chunkId: idx,
+                    sourceFiles: chunk.sourceFiles,
+                    attempts: attempt + 1,
+                    error: `Token budget exceeded (${totalTokens}/${budgetTokens})`,
+                  },
+                };
+              }
+
+              // Analyze with LLM
+              logger.debug(`Sending chunk ${idx} to LLM (${content.length} chars), attempt ${attempt + 1}/${maxRetries + 1}`);
+              llmInvocations++;
+              const summary = await analyzeChunkWithLLM(
+                content,
+                idx,
+                options.focus,
+                llmConfig,
+                logger
+              );
+
+              // Fill in source info
+              summary.sourceFiles = chunk.sourceFiles;
+              summary.size = formatSize(chunk.size);
+
+              if (summary.llmUsage) {
+                totalTokens += summary.llmUsage.totalTokens;
+              }
+
+              await writeJson(cachePath, summary);
+
+              return { ok: true as const, summary };
+            } catch (error) {
+              const canRetry = attempt < maxRetries;
+              const errorText = error instanceof Error ? error.message : String(error);
+              if (canRetry) {
+                logger.warn(`Chunk ${idx} 分析失败，准备重试 (${attempt + 1}/${maxRetries}): ${errorText}`);
+                continue;
+              }
+              return {
+                ok: false as const,
+                failure: {
+                  chunkId: idx,
+                  sourceFiles: chunk.sourceFiles,
+                  attempts: attempt + 1,
+                  error: errorText,
+                },
+              };
+            }
+          }
+
+          return {
+            ok: false as const,
+            failure: {
+              chunkId: idx,
+              sourceFiles: chunk.sourceFiles,
+              attempts: maxRetries + 1,
+              error: 'Unknown analysis error',
+            },
+          };
+        })
+      );
+
+      const successResults = batchResults
+        .filter((item): item is { ok: true; summary: ChunkSummary } => item.ok)
+        .map(item => item.summary);
+      const failedResults = batchResults
+        .filter((item): item is { ok: false; failure: ChunkFailure } => !item.ok)
+        .map(item => item.failure);
+
+      results.push(...successResults);
+      failures.push(...failedResults);
+
+      // Save individual chunk summaries
+      for (const summary of successResults) {
+        const summaryPath = path.join(outputDir, `chunk_${summary.chunkId}_summary.json`);
+        await writeJson(summaryPath, summary);
+      }
+    }
+
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+    const failuresPath = path.join(outputDir, 'analyze_failures.json');
+    if (failures.length > 0) {
+      await writeJson(failuresPath, {
+        status: 'partial_failed',
+        createdAt: new Date().toISOString(),
+        chunksRequested: chunkIndices.length,
+        chunksSucceeded: results.length,
+        chunksFailed: failures.length,
+        failures,
+      });
+    }
+
+    logger.success(`Analysis complete in ${duration}s`);
+    if (failures.length > 0) {
+      logger.warn(`有 ${failures.length} 个 chunk 失败，详情见: ${failuresPath}`);
+    }
+    logger.json({
+      status: failures.length > 0 ? 'partial_failed' : 'success',
+      chunksAnalyzed: results.length,
+      chunksFailed: failures.length,
+      totalFeatures: results.reduce((sum, r) => sum + r.features.length, 0),
+      totalDataModels: results.reduce((sum, r) => sum + r.dataModels.length, 0),
+      totalPages: results.reduce((sum, r) => sum + r.pages.length, 0),
+      totalApis: results.reduce((sum, r) => sum + r.apis.length, 0),
+      totalTokens,
+      cachedChunks,
+      llmInvocations,
+      tokenBudget: budgetTokens > 0 ? budgetTokens : undefined,
+      retriesPerChunk: maxRetries,
+      failuresPath: failures.length > 0 ? failuresPath : undefined,
+      outputDir,
+    });
+
+    const analyzeReportPath = path.join(outputDir, 'analyze_report.json');
+    await writeJson(analyzeReportPath, {
+      createdAt: new Date().toISOString(),
+      status: failures.length > 0 ? 'partial_failed' : 'success',
+      chunksRequested: chunkIndices.length,
+      chunksSucceeded: results.length,
+      chunksFailed: failures.length,
+      retriesPerChunk: maxRetries,
+      cachedChunks,
+      llmInvocations,
+      totalTokens,
+      tokenBudget: budgetTokens > 0 ? budgetTokens : undefined,
+      cacheDir,
+    });
+
+    if (failures.length > 0) {
+      process.exit(ANALYZE_EXIT_CODE.PARTIAL_FAILED);
+    }
+
+  } catch (error) {
+    logger.error(`Analysis failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(ANALYZE_EXIT_CODE.RUNTIME_ERROR);
+  }
+}

package/src/commands/clean.ts

@@ -0,0 +1,88 @@
+import * as path from 'path';
+import { Command } from 'commander';
+import { Logger } from '../utils/logger';
+import { fileExists, findFiles } from '../utils/file';
+import * as fs from 'fs-extra';
+
+interface CleanOptions {
+  workspace: string;
+  dryRun?: boolean;
+  yes?: boolean;
+}
+
+const INTERMEDIATE_FILES = [
+  'manifest.json',
+  'summaries/',
+  'spec_summary.json',
+  'task_plan.json',
+  'dispatch_plan.json',
+  '.patterns.json',
+  '.scan_done',
+  '.analyze_done',
+  '.merge_done',
+  '.plan_done',
+  '.dispatch_done',
+];
+
+export async function cleanCommand(options: CleanOptions, command: Command): Promise<void> {
+  const logger = new Logger();
+  const workspacePath = path.resolve(options.workspace);
+  
+  try {
+    if (!(await fileExists(workspacePath))) {
+      logger.error(`Error: Workspace not found: ${options.workspace}`);
+      process.exit(1);
+    }
+
+    // Find all intermediate files
+    const filesToClean: Array<{ path: string; type: string }> = [];
+
+    for (const pattern of INTERMEDIATE_FILES) {
+      const fullPath = path.join(workspacePath, pattern);
+      
+      if (await fileExists(fullPath)) {
+        const stats = await fs.stat(fullPath);
+        filesToClean.push({
+          path: fullPath,
+          type: stats.isDirectory() ? 'directory' : 'file',
+        });
+      }
+    }
+
+    if (filesToClean.length === 0) {
+      logger.info('No intermediate files to clean.');
+      return;
+    }
+
+    logger.info(`Found ${filesToClean.length} items to clean:`);
+    for (const item of filesToClean) {
+      logger.info(`  ${item.type === 'directory' ? '📁' : '📄'} ${path.relative(workspacePath, item.path)}`);
+    }
+
+    // Preview mode
+    if (options.dryRun) {
+      logger.info('\nDry run mode - no files were deleted.');
+      return;
+    }
+
+    // Clean files
+    for (const item of filesToClean) {
+      try {
+        if (item.type === 'directory') {
+          await fs.remove(item.path);
+        } else {
+          await fs.unlink(item.path);
+        }
+        logger.success(`  Cleaned: ${path.relative(workspacePath, item.path)}`);
+      } catch (error) {
+        logger.error(`  Failed to clean: ${path.relative(workspacePath, item.path)}`);
+      }
+    }
+
+    logger.success(`\nCleaned ${filesToClean.length} items from workspace`);
+
+  } catch (error) {
+    logger.error(`Clean failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}

package/src/commands/dispatch.ts

@@ -0,0 +1,250 @@
+import * as path from 'path';
+import { Command } from 'commander';
+import { Logger } from '../utils/logger';
+import { 
+  ensureDir, 
+  fileExists, 
+  readJson, 
+  writeJson 
+} from '../utils/file';
+import { TaskPlan, DispatchPlan, AgentAssignment, Task } from '../types';
+
+interface DispatchOptions {
+  plan: string;
+  output: string;
+  agents?: string;
+  strategy: string;
+  dryRun?: boolean;
+  yes?: boolean;
+}
+
+export async function dispatchCommand(options: DispatchOptions, command: Command): Promise<void> {
+  const logger = new Logger();
+  
+  try {
+    const planPath = path.resolve(options.plan);
+    
+    if (!(await fileExists(planPath))) {
+      logger.error(`Error: Task plan not found: ${options.plan}`);
+      logger.info('Run spec-agent plan first to create task_plan.json.');
+      process.exit(1);
+    }
+
+    const taskPlan: TaskPlan = await readJson(planPath);
+    logger.info(`Loaded task plan with ${taskPlan.totalTasks} tasks`);
+
+    // Parse agent mapping
+    const agentPools = parseAgentMapping(options.agents, taskPlan.totalTasks);
+    logger.info(`Agent pools: ${Object.entries(agentPools).map(([k, v]) => `${k}:${v}`).join(', ')}`);
+
+    // Preview mode
+    if (options.dryRun) {
+      logger.info('Dry run mode - dispatch plan preview:');
+      logger.info(`  Total tasks: ${taskPlan.totalTasks}`);
+      logger.info(`  Strategy: ${options.strategy}`);
+      for (const [type, count] of Object.entries(agentPools)) {
+        logger.info(`  ${type} agents: ${count}`);
+      }
+      return;
+    }
+
+    const startTime = Date.now();
+
+    // Collect all tasks
+    const allTasks: Task[] = [];
+    for (const group of taskPlan.parallelGroups) {
+      allTasks.push(...group.tasks);
+    }
+
+    // Assign tasks to agents based on strategy
+    const assignments = assignTasksToAgents(allTasks, agentPools, options.strategy);
+
+    // Build agent pools structure
+    const agentPoolAssignments: { [type: string]: AgentAssignment[] } = {};
+    for (const [type, count] of Object.entries(agentPools)) {
+      agentPoolAssignments[type] = [];
+      for (let i = 1; i <= count; i++) {
+        const agentId = `${type.toUpperCase()}-${i}`;
+        const assignedTasks = assignments
+          .filter(a => a.agentId === agentId)
+          .flatMap(a => a.assignedTasks);
+        
+        const totalHours = allTasks
+          .filter(t => assignedTasks.includes(t.id))
+          .reduce((sum, t) => sum + (t.estimatedHours || 0), 0);
+
+        agentPoolAssignments[type].push({
+          agentId,
+          type,
+          assignedTasks,
+          workload: `${totalHours}h`,
+        });
+      }
+    }
+
+    // Find unassigned tasks
+    const assignedTaskIds = new Set(assignments.flatMap(a => a.assignedTasks));
+    const unassigned = allTasks
+      .filter(t => !assignedTaskIds.has(t.id))
+      .map(t => t.id);
+
+    if (unassigned.length > 0) {
+      logger.warn(`${unassigned.length} tasks could not be assigned`);
+    }
+
+    // Create dispatch plan
+    const dispatchPlan: DispatchPlan = {
+      version: '1.0.0',
+      createdAt: new Date().toISOString(),
+      totalTasks: taskPlan.totalTasks,
+      agentPools: agentPoolAssignments,
+      unassigned,
+      dispatchPlanPath: path.resolve(options.output),
+    };
+
+    // Write output
+    const outputPath = path.resolve(options.output);
+    await ensureDir(path.dirname(outputPath));
+    await writeJson(outputPath, dispatchPlan);
+
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+    logger.success(`Dispatch plan created in ${duration}s`);
+    logger.json({
+      status: 'success',
+      totalTasks: taskPlan.totalTasks,
+      agentTypes: Object.keys(agentPools).length,
+      totalAgents: Object.values(agentPools).reduce((a, b) => a + b, 0),
+      unassigned: unassigned.length,
+      outputPath,
+    });
+
+    // Print assignment summary
+    for (const [type, agents] of Object.entries(agentPoolAssignments)) {
+      for (const agent of agents) {
+        logger.info(`  ${agent.agentId}: ${agent.assignedTasks.length} tasks, ${agent.workload}`);
+      }
+    }
+
+  } catch (error) {
+    logger.error(`Dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+
+function parseAgentMapping(agentsStr: string | undefined, totalTasks: number): Record<string, number> {
+  if (!agentsStr) {
+    // Auto-determine based on task count
+    if (totalTasks <= 5) {
+      return { frontend: 1, backend: 1 };
+    } else if (totalTasks <= 15) {
+      return { frontend: 2, backend: 2, qa: 1 };
+    } else {
+      return { frontend: 3, backend: 3, qa: 2 };
+    }
+  }
+
+  const pools: Record<string, number> = {};
+  const pairs = agentsStr.split(',');
+  
+  for (const pair of pairs) {
+    const [type, count] = pair.split(':');
+    if (type && count) {
+      pools[type.trim()] = parseInt(count.trim(), 10);
+    }
+  }
+
+  return pools;
+}
+
+function assignTasksToAgents(
+  tasks: Task[], 
+  agentPools: Record<string, number>,
+  strategy: string
+): AgentAssignment[] {
+  const assignments: AgentAssignment[] = [];
+  
+  // Create agent instances
+  const agents: Array<{ id: string; type: string; workload: number }> = [];
+  for (const [type, count] of Object.entries(agentPools)) {
+    for (let i = 1; i <= count; i++) {
+      agents.push({ id: `${type.toUpperCase()}-${i}`, type, workload: 0 });
+    }
+  }
+
+  // Sort tasks by priority and estimated hours
+  const sortedTasks = [...tasks].sort((a, b) => {
+    const priorityOrder = { P0: 0, P1: 1, P2: 2, P3: 3 };
+    if (priorityOrder[a.priority] !== priorityOrder[b.priority]) {
+      return priorityOrder[a.priority] - priorityOrder[b.priority];
+    }
+    return (b.estimatedHours || 0) - (a.estimatedHours || 0);
+  });
+
+  // Assign tasks
+  for (const task of sortedTasks) {
+    const taskType = mapTaskToAgentType(task);
+    
+    // Find suitable agents
+    const suitableAgents = agents.filter(a => a.type === taskType);
+    if (suitableAgents.length === 0) {
+      // Fall back to any agent
+      continue;
+    }
+
+    // Select agent based on strategy
+    let selectedAgent;
+    switch (strategy) {
+      case 'load-first':
+        // Assign to agent with least workload
+        selectedAgent = suitableAgents.reduce((min, a) => 
+          a.workload < min.workload ? a : min
+        );
+        break;
+      case 'skill-first':
+        // Assign to first suitable agent (specialization)
+        selectedAgent = suitableAgents[0];
+        break;
+      case 'balanced':
+      default:
+        // Round-robin with workload consideration
+        selectedAgent = suitableAgents.reduce((min, a) => 
+          a.workload < min.workload ? a : min
+        );
+        break;
+    }
+
+    // Record assignment
+    let assignment = assignments.find(a => a.agentId === selectedAgent.id);
+    if (!assignment) {
+      assignment = {
+        agentId: selectedAgent.id,
+        type: selectedAgent.type,
+        assignedTasks: [],
+        workload: '0h',
+      };
+      assignments.push(assignment);
+    }
+    
+    assignment.assignedTasks.push(task.id);
+    selectedAgent.workload += task.estimatedHours || 0;
+  }
+
+  return assignments;
+}
+
+function mapTaskToAgentType(task: Task): string {
+  switch (task.type) {
+    case 'page':
+    case 'component':
+      return 'frontend';
+    case 'api':
+      return 'backend';
+    case 'test':
+      return 'qa';
+    case 'setup':
+      return 'frontend'; // or devops
+    default:
+      return 'frontend';
+  }
+}