spec-agent 1.0.3 → 2.0.0

package/src/commands/handoff.ts

@@ -0,0 +1,351 @@
+import * as path from 'path';
+import * as fs from 'fs-extra';
+import { Command } from 'commander';
+import { Logger } from '../utils/logger';
+import { ensureDir, fileExists, readJson, writeJson } from '../utils/file';
+import { DispatchPlan, SpecSummary, Task, TaskPlan } from '../types';
+
+interface HandoffOptions {
+  workspace: string;
+  output: string;
+  target: string;
+  includeSummaries?: boolean;
+  dryRun?: boolean;
+}
+
+interface HandoffTask {
+  id: string;
+  name: string;
+  type: Task['type'];
+  priority: Task['priority'];
+  dependencies: string[];
+  assignedAgent: string;
+  assignedType: string;
+  estimatedHours?: number;
+  sourceChunks?: number[];
+}
+
+export async function handoffCommand(options: HandoffOptions, command: Command): Promise<void> {
+  const logger = new Logger();
+
+  try {
+    const workspacePath = path.resolve(options.workspace);
+    const dispatchPath = path.join(workspacePath, 'dispatch_plan.json');
+    const taskPlanPath = path.join(workspacePath, 'task_plan.json');
+    const specPath = path.join(workspacePath, 'spec_summary.json');
+
+    if (!(await fileExists(dispatchPath))) {
+      logger.error(`dispatch_plan.json not found in workspace: ${workspacePath}`);
+      logger.info('Run spec-agent dispatch first.');
+      process.exit(1);
+    }
+    if (!(await fileExists(taskPlanPath))) {
+      logger.error(`task_plan.json not found in workspace: ${workspacePath}`);
+      logger.info('Run spec-agent plan first.');
+      process.exit(1);
+    }
+
+    const outputPath = path.isAbsolute(options.output)
+      ? options.output
+      : path.join(workspacePath, options.output || 'handoff');
+
+    const dispatch = await readJson<DispatchPlan>(dispatchPath);
+    const taskPlan = await readJson<TaskPlan>(taskPlanPath);
+    const spec = (await fileExists(specPath)) ? await readJson<SpecSummary>(specPath) : null;
+
+    const taskById = new Map<string, Task>();
+    for (const group of taskPlan.parallelGroups) {
+      for (const task of group.tasks) {
+        taskById.set(task.id, task);
+      }
+    }
+
+    const sourceChunkMap = buildSourceChunkMap(spec);
+    const handoffTasks: HandoffTask[] = [];
+    const agentTaskMap = new Map<string, HandoffTask[]>();
+
+    for (const [agentType, agents] of Object.entries(dispatch.agentPools)) {
+      for (const agent of agents) {
+        const rows: HandoffTask[] = [];
+        for (const taskId of agent.assignedTasks) {
+          const task = taskById.get(taskId);
+          if (!task) continue;
+          const mapped: HandoffTask = {
+            id: task.id,
+            name: task.name,
+            type: task.type,
+            priority: task.priority,
+            dependencies: task.dependencies || [],
+            assignedAgent: agent.agentId,
+            assignedType: agentType,
+            estimatedHours: task.estimatedHours,
+            sourceChunks: guessSourceChunks(task, sourceChunkMap),
+          };
+          rows.push(mapped);
+          handoffTasks.push(mapped);
+        }
+        agentTaskMap.set(agent.agentId, rows);
+      }
+    }
+
+    if (options.dryRun) {
+      logger.info('Dry run mode - handoff plan:');
+      logger.info(`  workspace: ${workspacePath}`);
+      logger.info(`  target: ${normalizeTarget(options.target)}`);
+      logger.info(`  agents: ${agentTaskMap.size}`);
+      logger.info(`  tasks: ${handoffTasks.length}`);
+      logger.info(`  output: ${outputPath}`);
+      return;
+    }
+
+    await ensureDir(outputPath);
+    const tasksDir = path.join(outputPath, 'tasks');
+    const agentsDir = path.join(outputPath, 'agents');
+    await ensureDir(tasksDir);
+    await ensureDir(agentsDir);
+
+    // Per-task handoff prompts.
+    for (const row of handoffTasks) {
+      const markdown = renderTaskPrompt({
+        row,
+        workspacePath,
+        target: normalizeTarget(options.target),
+        includeSummaries: Boolean(options.includeSummaries),
+      });
+      await fs.writeFile(path.join(tasksDir, `${row.id}.md`), markdown, 'utf-8');
+    }
+
+    // Per-agent task list.
+    for (const [agentId, rows] of agentTaskMap) {
+      const markdown = renderAgentPrompt({
+        agentId,
+        rows,
+        target: normalizeTarget(options.target),
+      });
+      await fs.writeFile(path.join(agentsDir, `${agentId}.md`), markdown, 'utf-8');
+    }
+
+    const bundlePath = path.join(outputPath, 'handoff_bundle.json');
+    await writeJson(bundlePath, {
+      version: '2.0.0-beta',
+      createdAt: new Date().toISOString(),
+      workspace: workspacePath,
+      target: normalizeTarget(options.target),
+      artifacts: {
+        specSummary: spec ? 'spec_summary.json' : null,
+        taskPlan: 'task_plan.json',
+        dispatchPlan: 'dispatch_plan.json',
+        summariesDir: options.includeSummaries ? 'summaries/' : null,
+      },
+      totals: {
+        agents: agentTaskMap.size,
+        tasks: handoffTasks.length,
+      },
+      tasks: handoffTasks,
+      unassigned: dispatch.unassigned,
+    });
+
+    const indexPath = path.join(outputPath, 'index.md');
+    await fs.writeFile(
+      indexPath,
+      renderIndexMarkdown({
+        target: normalizeTarget(options.target),
+        totalAgents: agentTaskMap.size,
+        totalTasks: handoffTasks.length,
+        includeSummaries: Boolean(options.includeSummaries),
+      }),
+      'utf-8'
+    );
+
+    logger.success('Handoff bundle generated');
+    logger.json({
+      status: 'success',
+      workspace: workspacePath,
+      target: normalizeTarget(options.target),
+      totalAgents: agentTaskMap.size,
+      totalTasks: handoffTasks.length,
+      outputPath,
+      bundlePath,
+      indexPath,
+    });
+  } catch (error) {
+    logger.error(`Handoff failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+
+function normalizeTarget(target: string | undefined): string {
+  const value = (target || 'generic').toLowerCase();
+  if (['cursor', 'qcoder', 'codebuddy', 'generic'].includes(value)) {
+    return value;
+  }
+  return 'generic';
+}
+
+function buildSourceChunkMap(spec: SpecSummary | null): {
+  features: Map<string, number[]>;
+  pages: Map<string, number[]>;
+  apis: Map<string, number[]>;
+} {
+  const features = new Map<string, number[]>();
+  const pages = new Map<string, number[]>();
+  const apis = new Map<string, number[]>();
+  if (!spec) return { features, pages, apis };
+
+  for (const item of spec.features || []) {
+    const key = normalizeName(item.name);
+    features.set(key, pushUnique(features.get(key), item.sourceChunk));
+  }
+  for (const item of spec.pages || []) {
+    const key = normalizeName(item.name);
+    pages.set(key, pushUnique(pages.get(key), item.sourceChunk));
+  }
+  for (const item of spec.apis || []) {
+    const key = normalizeName(`${item.method} ${item.path}`);
+    apis.set(key, pushUnique(apis.get(key), item.sourceChunk));
+  }
+
+  return { features, pages, apis };
+}
+
+function guessSourceChunks(
+  task: Task,
+  sourceMap: { features: Map<string, number[]>; pages: Map<string, number[]>; apis: Map<string, number[]> }
+): number[] | undefined {
+  const key = normalizeName(task.name);
+  if (task.type === 'feature' || task.type === 'component') {
+    return sourceMap.features.get(key);
+  }
+  if (task.type === 'page') {
+    return sourceMap.pages.get(key);
+  }
+  if (task.type === 'api') {
+    return sourceMap.apis.get(key);
+  }
+  return undefined;
+}
+
+function renderTaskPrompt(input: {
+  row: HandoffTask;
+  workspacePath: string;
+  target: string;
+  includeSummaries: boolean;
+}): string {
+  const { row, workspacePath, target, includeSummaries } = input;
+  const sourceChunkText = row.sourceChunks && row.sourceChunks.length > 0
+    ? row.sourceChunks.map(i => `chunk_${i}_summary.json`).join(', ')
+    : '未定位到明确 source chunk，请从 spec_summary.json 补充判断';
+
+  return [
+    `# Task Handoff - ${row.id} ${row.name}`,
+    '',
+    `- Target Tool: ${target}`,
+    `- Assigned Agent: ${row.assignedAgent} (${row.assignedType})`,
+    `- Priority: ${row.priority}`,
+    `- Type: ${row.type}`,
+    `- Estimated Hours: ${row.estimatedHours ?? 'N/A'}`,
+    '',
+    '## Objective',
+    '',
+    `实现任务 **${row.id} ${row.name}**，仅处理当前任务与已满足依赖，不越界扩展。`,
+    '',
+    '## Dependencies',
+    '',
+    row.dependencies.length > 0 ? row.dependencies.map(dep => `- ${dep}`).join('\n') : '- 无',
+    '',
+    '## Required Inputs',
+    '',
+    '- `spec_summary.json`',
+    '- `task_plan.json`',
+    '- `dispatch_plan.json`',
+    includeSummaries ? '- `summaries/`' : '- （可选）`summaries/`',
+    '',
+    '## Suggested Evidence',
+    '',
+    `- ${sourceChunkText}`,
+    '',
+    '## Execution Constraints',
+    '',
+    '- 只改与该任务直接相关文件；避免大范围重构',
+    '- 明确列出修改文件与验证步骤',
+    '- 信息不足时先输出缺失项，再请求补充，不要臆造接口',
+    '',
+    '## Deliverables',
+    '',
+    '- 变更文件列表',
+    '- 关键实现说明（why + what）',
+    '- 可复现实测步骤（命令）',
+    '',
+    '## Workspace',
+    '',
+    `- Root: ${workspacePath}`,
+  ].join('\n');
+}
+
+function renderAgentPrompt(input: { agentId: string; rows: HandoffTask[]; target: string }): string {
+  const { agentId, rows, target } = input;
+  const lines = rows.map(
+    row => `- ${row.id} | ${row.priority} | ${row.type} | deps: ${row.dependencies.join(', ') || '-'} | ${row.name}`
+  );
+  return [
+    `# Agent Handoff - ${agentId}`,
+    '',
+    `- Target Tool: ${target}`,
+    `- Total Tasks: ${rows.length}`,
+    '',
+    '## Task Queue',
+    '',
+    ...(lines.length > 0 ? lines : ['- 无任务']),
+    '',
+    '## Recommended Order',
+    '',
+    '1. 先完成依赖少/无依赖任务',
+    '2. 优先处理 P0 -> P1 -> P2 -> P3',
+    '3. 每完成一项，回填任务状态与变更摘要',
+  ].join('\n');
+}
+
+function renderIndexMarkdown(input: {
+  target: string;
+  totalAgents: number;
+  totalTasks: number;
+  includeSummaries: boolean;
+}): string {
+  const { target, totalAgents, totalTasks, includeSummaries } = input;
+  return [
+    '# Handoff Bundle Index',
+    '',
+    `- Target: ${target}`,
+    `- Total Agents: ${totalAgents}`,
+    `- Total Tasks: ${totalTasks}`,
+    `- Include Summaries: ${includeSummaries ? 'yes' : 'no'}`,
+    '',
+    '## Files',
+    '',
+    '- `handoff_bundle.json`: 机器可读任务总览',
+    '- `agents/*.md`: 每个 agent 的任务队列',
+    '- `tasks/*.md`: 每个任务可直接投喂编码 Agent 的提示词模板',
+    '',
+    '## Quick Start',
+    '',
+    '1. 先打开 `agents/<AGENT_ID>.md` 确认任务顺序',
+    '2. 按顺序将 `tasks/<TASK_ID>.md` 投喂到目标工具执行',
+    '3. 每完成一个任务后人工回填状态到你的任务系统',
+  ].join('\n');
+}
+
+function normalizeName(input: string): string {
+  return (input || '')
+    .toLowerCase()
+    .replace(/[^\u4e00-\u9fa5a-z0-9\s/:_-]/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function pushUnique(existing: number[] | undefined, value: number): number[] {
+  const base = existing ? existing.slice() : [];
+  if (!base.includes(value)) {
+    base.push(value);
+  }
+  return base;
+}

package/src/commands/learn.ts

@@ -21,6 +21,11 @@ interface LearnOptions {
 }
 
 const PATTERNS_FILE = '.patterns.json';
+type LearnPhase = 'summaries' | 'plan' | 'dispatch';
+
+function isLearnPhase(phase?: string): phase is LearnPhase {
+  return phase === 'summaries' || phase === 'plan' || phase === 'dispatch';
+}
 
 export async function learnCommand(options: LearnOptions, command: Command): Promise<void> {
   const logger = new Logger();
@@ -86,14 +91,17 @@ export async function learnCommand(options: LearnOptions, command: Command): Pro
 
     // Handle automatic learning from phase results
     if (options.from) {
-      const learnedCount = await learnFromPhase(workspacePath, options.from, patterns, logger);
-      
-      if (learnedCount > 0) {
-        await writeJson(patternsPath, patterns);
-        logger.success(`Learned ${learnedCount} new patterns from ${options.from}`);
+      if (!isLearnPhase(options.from)) {
+        logger.error(`Unknown phase: ${options.from}`);
+        return;
+      }
+      const result = await learnFromWorkspacePhase(workspacePath, options.from, logger);
+      if (result.learnedCount > 0) {
+        logger.success(`Learned ${result.learnedCount} new patterns from ${options.from}`);
       } else {
         logger.info('No new patterns learned.');
       }
+      logger.info(`Patterns file: ${result.patternsPath}`);
       return;
     }
 
@@ -126,9 +134,36 @@ export async function learnCommand(options: LearnOptions, command: Command): Pro
   }
 }
 
+export async function learnFromWorkspacePhase(
+  workspacePath: string,
+  phase: LearnPhase,
+  logger: Logger
+): Promise<{ learnedCount: number; totalPatterns: number; patternsPath: string }> {
+  const patternsPath = path.join(workspacePath, PATTERNS_FILE);
+  let patterns: Patterns = {
+    version: '1.0.0',
+    workspace: workspacePath,
+    patterns: [],
+  };
+
+  if (await fileExists(patternsPath)) {
+    patterns = await readJson<Patterns>(patternsPath);
+  }
+
+  const learnedCount = await learnFromPhase(workspacePath, phase, patterns, logger);
+  // Always persist pattern file after learn attempt to make workspace state explicit.
+  await writeJson(patternsPath, patterns);
+
+  return {
+    learnedCount,
+    totalPatterns: patterns.patterns.length,
+    patternsPath,
+  };
+}
+
 async function learnFromPhase(
   workspacePath: string,
-  phase: string,
+  phase: LearnPhase,
   patterns: Patterns,
   logger: Logger
 ): Promise<number> {

package/src/commands/pipeline.ts

@@ -12,6 +12,7 @@ import { analyzeCommand } from './analyze';
 import { mergeCommand } from './merge';
 import { planCommand } from './plan';
 import { dispatchCommand } from './dispatch';
+import { learnFromWorkspacePhase } from './learn';
 
 interface PipelineOptions {
   input?: string;
@@ -23,6 +24,7 @@ interface PipelineOptions {
   analyzeBudgetTokens: string;
   framework: string;
   strictLlm?: boolean;
+  learn?: boolean;
   stopAt?: string;
   from?: string;
   dryRun?: boolean;
@@ -206,6 +208,12 @@ async function executePhase(
         dryRun: false,
         yes: options.yes,
       }, {} as Command);
+      if (options.learn !== false) {
+        const learnResult = await learnFromWorkspacePhase(workspacePath, 'summaries', logger);
+        logger.info(
+          `  Learn complete: +${learnResult.learnedCount}, total ${learnResult.totalPatterns} (${learnResult.patternsPath})`
+        );
+      }
       break;
 
     case 'merge':

package/src/commands/scan.ts

@@ -79,9 +79,7 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
         process.exit(SCAN_EXIT_CODE.INPUT_ERROR);
       }
 
-      const stats = await ensureDir(inputPath).then(() => 
-        require('fs').promises.stat(inputPath)
-      ).catch(() => null);
+      const stats = await require('fs').promises.stat(inputPath).catch(() => null);
       
       if (!stats) {
         logger.error(`[E_SCAN_INPUT] Cannot access path: ${options.input}`);
@@ -217,6 +215,23 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
       logger.info(`图片语义统计: 检测 ${imageAssetsDetected} 张, 已摘要 ${imageAssetsDescribed} 张`);
     }
 
+    // Preview mode
+    if (options.dryRun) {
+      logger.info('Dry run mode - manifest preview:');
+      for (let i = 0; i < rawChunks.slice(0, 20).length; i++) {
+        const rawChunk = rawChunks[i];
+        const size = Buffer.byteLength(rawChunk.content, 'utf-8');
+        const preview = rawChunk.sourceFiles.length === 1
+          ? `${path.basename(rawChunk.sourceFiles[0])} (${formatSize(size)})`
+          : `${rawChunk.sourceFiles.length} files, ${formatSize(size)}`;
+        logger.info(`  Chunk ${i}: ${preview}`);
+      }
+      if (rawChunks.length > 20) {
+        logger.info(`  ... and ${rawChunks.length - 20} more chunks`);
+      }
+      return;
+    }
+
     // Prepare chunks directory
     const outputDir = path.dirname(path.resolve(options.output));
     const chunksDir = path.join(outputDir, 'chunks');
@@ -239,21 +254,6 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
       });
     }
 
-    // Preview mode
-    if (options.dryRun) {
-      logger.info('Dry run mode - manifest preview:');
-      for (const chunk of chunks.slice(0, 20)) {
-        const preview = chunk.content 
-          ? `${path.basename(chunk.sourceFiles[0])} (${formatSize(chunk.size)})`
-          : `${chunk.sourceFiles.length} files, ${formatSize(chunk.size)}`;
-        logger.info(`  Chunk ${chunk.id}: ${preview}`);
-      }
-      if (chunks.length > 20) {
-        logger.info(`  ... and ${chunks.length - 20} more chunks`);
-      }
-      return;
-    }
-
     // Create manifest
     const manifest: Manifest = {
       version: '1.0.0',

package/src/index.ts

@@ -1,5 +1,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
 import { scanCommand } from './commands/scan';
 import { analyzeCommand } from './commands/analyze';
 import { mergeCommand } from './commands/merge';
@@ -10,13 +12,25 @@ import { pipelineCommand } from './commands/pipeline';
 import { statusCommand } from './commands/status';
 import { cleanCommand } from './commands/clean';
 import { doctorCommand } from './commands/doctor';
+import { handoffCommand } from './commands/handoff';
+import { executeCommand } from './commands/execute';
 
 const program = new Command();
+const pkgVersion = (() => {
+  try {
+    const packageJsonPath = path.resolve(__dirname, '..', 'package.json');
+    const raw = fs.readFileSync(packageJsonPath, 'utf-8');
+    const parsed = JSON.parse(raw) as { version?: string };
+    return parsed.version || '1.0.0';
+  } catch {
+    return '1.0.0';
+  }
+})();
 
 program
   .name('spec-agent')
-  .description('Multi-agent CLI tool for breaking down large requirement documents')
-  .version('1.0.0');
+  .description('CLI for requirement decomposition and agent-ready planning')
+  .version(pkgVersion);
 
 program
   .command('scan')
@@ -105,6 +119,7 @@ program
   .option('--analyze-budget-tokens <count>', 'Max total tokens for analyze in pipeline (0 = unlimited)', '0')
   .option('--strict-llm', 'Fail if LLM chunking fails (no fallback)')
   .option('--framework <fw>', 'Target framework', 'vue3')
+  .option('--no-learn', 'Disable automatic learning after analyze phase')
   .option('--stop-at <phase>', 'Stop after phase: scan, analyze, merge, plan, dispatch')
   .option('--from <phase>', 'Resume from phase: scan, analyze, merge, plan, dispatch')
   .option('--dry-run', 'Preview full pipeline without executing')
@@ -134,4 +149,28 @@ program
   .option('--format <format>', 'Output format: text, json', 'text')
   .action(doctorCommand);
 
+program
+  .command('handoff')
+  .description('Generate agent handoff bundles for coding tools')
+  .option('-w, --workspace <dir>', 'Workspace directory', '.')
+  .option('-o, --output <dir>', 'Output directory for handoff bundle', 'handoff')
+  .option('-t, --target <name>', 'Target tool: cursor, qcoder, codebuddy, generic', 'generic')
+  .option('--include-summaries', 'Include summary directory as required evidence')
+  .option('--dry-run', 'Preview handoff generation plan')
+  .action(handoffCommand);
+
+program
+  .command('execute')
+  .description('Run v2 beta execution state machine from handoff bundle')
+  .option('-w, --workspace <dir>', 'Workspace directory', '.')
+  .option('-b, --bundle <path>', 'Path to handoff_bundle.json (optional)')
+  .option('-p, --max-parallel <count>', 'Max parallel running tasks', '4')
+  .option('-r, --retry <count>', 'Retry times per task after failure', '1')
+  .option('--complete <ids>', 'Mark task IDs as completed, comma-separated')
+  .option('--fail <ids>', 'Mark task IDs as failed, comma-separated')
+  .option('--error <message>', 'Failure reason when using --fail')
+  .option('--reset', 'Reset existing run state and reinitialize from bundle')
+  .option('--dry-run', 'Preview execution transitions without writing state')
+  .action(executeCommand);
+
 program.parse();

package/src/services/llm.ts

@@ -1,5 +1,5 @@
 import { Logger } from '../utils/logger';
-import { ChunkSummary, Feature, DataModel, Page, Api } from '../types';
+import { ChunkSummary, Feature, DataModel, Page, Api, LearnedPattern } from '../types';
 
 export interface LLMConfig {
   apiKey: string;
@@ -490,13 +490,21 @@ export async function analyzeChunkWithLLM(
   chunkId: number,
   focus: string,
   config: LLMConfig,
+  learnedPatterns: LearnedPattern[] = [],
   logger?: Logger
 ): Promise<ChunkSummary> {
   validateLLMConfig(config);
 
+  const learnedContext = learnedPatterns.length > 0
+    ? `\n\nLearned Patterns (reference only, do not overfit):\n${learnedPatterns
+      .slice(0, 20)
+      .map((p, i) => `${i + 1}. ${p.name}: ${p.rule} (confidence=${p.confidence.toFixed(2)})`)
+      .join('\n')}`
+    : '';
+
   const prompt = ANALYSIS_PROMPT_TEMPLATE
     .replace('{focus}', focus)
-    .replace('{content}', chunkContent);
+    .replace('{content}', chunkContent) + learnedContext;
 
   const response = await callLLM(prompt, config, logger);