spec-agent 2.0.4 → 2.0.6

package/src/commands/handoff.ts

@@ -23,6 +23,28 @@ interface HandoffTask {
   assignedType: string;
   estimatedHours?: number;
   sourceChunks?: number[];
+  prototypeRefs?: PrototypeMatch[];
+}
+
+interface PrototypeIndexFile {
+  assets: PrototypeAssetEntry[];
+}
+
+interface PrototypeAssetEntry {
+  id: string;
+  path: string;
+  sourceFile: string;
+  alt?: string;
+  summary?: string;
+  sourceChunks?: number[];
+}
+
+interface PrototypeMatch {
+  id: string;
+  path: string;
+  reason: string;
+  score: number;
+  summary?: string;
 }
 
 export async function handoffCommand(options: HandoffOptions, command: Command): Promise<void> {
@@ -33,6 +55,7 @@ export async function handoffCommand(options: HandoffOptions, command: Command):
     const dispatchPath = path.join(workspacePath, 'dispatch_plan.json');
     const taskPlanPath = path.join(workspacePath, 'task_plan.json');
     const specPath = path.join(workspacePath, 'spec_summary.json');
+    const prototypeIndexPath = path.join(workspacePath, 'prototype_index.json');
 
     if (!(await fileExists(dispatchPath))) {
       logger.error(`dispatch_plan.json not found in workspace: ${workspacePath}`);
@@ -52,6 +75,10 @@ export async function handoffCommand(options: HandoffOptions, command: Command):
     const dispatch = await readJson<DispatchPlan>(dispatchPath);
     const taskPlan = await readJson<TaskPlan>(taskPlanPath);
     const spec = (await fileExists(specPath)) ? await readJson<SpecSummary>(specPath) : null;
+    const prototypeIndex = (await fileExists(prototypeIndexPath))
+      ? await readJson<PrototypeIndexFile>(prototypeIndexPath)
+      : null;
+    const prototypeAssets = prototypeIndex?.assets || [];
 
     const taskById = new Map<string, Task>();
     for (const group of taskPlan.parallelGroups) {
@@ -70,6 +97,7 @@ export async function handoffCommand(options: HandoffOptions, command: Command):
         for (const taskId of agent.assignedTasks) {
           const task = taskById.get(taskId);
           if (!task) continue;
+          const sourceChunks = guessSourceChunks(task, sourceChunkMap);
           const mapped: HandoffTask = {
             id: task.id,
             name: task.name,
@@ -79,7 +107,8 @@ export async function handoffCommand(options: HandoffOptions, command: Command):
             assignedAgent: agent.agentId,
             assignedType: agentType,
             estimatedHours: task.estimatedHours,
-            sourceChunks: guessSourceChunks(task, sourceChunkMap),
+            sourceChunks,
+            prototypeRefs: matchTaskPrototypes(task, sourceChunks, prototypeAssets),
           };
           rows.push(mapped);
           handoffTasks.push(mapped);
@@ -136,10 +165,12 @@ export async function handoffCommand(options: HandoffOptions, command: Command):
         taskPlan: 'task_plan.json',
         dispatchPlan: 'dispatch_plan.json',
         summariesDir: options.includeSummaries ? 'summaries/' : null,
+        prototypeIndex: prototypeAssets.length > 0 ? 'prototype_index.json' : null,
       },
       totals: {
         agents: agentTaskMap.size,
         tasks: handoffTasks.length,
+        prototypeAssets: prototypeAssets.length,
       },
       tasks: handoffTasks,
       unassigned: dispatch.unassigned,
@@ -152,6 +183,7 @@ export async function handoffCommand(options: HandoffOptions, command: Command):
         target: normalizeTarget(options.target),
         totalAgents: agentTaskMap.size,
         totalTasks: handoffTasks.length,
+        totalPrototypeAssets: prototypeAssets.length,
         includeSummaries: Boolean(options.includeSummaries),
       }),
       'utf-8'
@@ -164,6 +196,7 @@ export async function handoffCommand(options: HandoffOptions, command: Command):
       target: normalizeTarget(options.target),
       totalAgents: agentTaskMap.size,
       totalTasks: handoffTasks.length,
+      totalPrototypeAssets: prototypeAssets.length,
       outputPath,
       bundlePath,
       indexPath,
@@ -235,6 +268,8 @@ function renderTaskPrompt(input: {
   const sourceChunkText = row.sourceChunks && row.sourceChunks.length > 0
     ? row.sourceChunks.map(i => `chunk_${i}_summary.json`).join(', ')
     : '未定位到明确 source chunk，请从 spec_summary.json 补充判断';
+  const prototypeLines = (row.prototypeRefs || [])
+    .map(ref => `- ${ref.id} | \`${ref.path}\` | score=${ref.score} | ${ref.reason}${ref.summary ? ` | ${ref.summary}` : ''}`);
 
   return [
     `# Task Handoff - ${row.id} ${row.name}`,
@@ -259,11 +294,16 @@ function renderTaskPrompt(input: {
     '- `task_plan.json`',
     '- `dispatch_plan.json`',
     includeSummaries ? '- `summaries/`' : '- （可选）`summaries/`',
+    '- （可选）`prototype_index.json` / `prototypes/*`',
     '',
     '## Suggested Evidence',
     '',
     `- ${sourceChunkText}`,
     '',
+    '## Prototype References',
+    '',
+    ...(prototypeLines.length > 0 ? prototypeLines : ['- 无直接匹配原型，必要时在 prototype_index.json 中人工筛选']),
+    '',
     '## Execution Constraints',
     '',
     '- 只改与该任务直接相关文件；避免大范围重构',
@@ -309,20 +349,23 @@ function renderIndexMarkdown(input: {
   target: string;
   totalAgents: number;
   totalTasks: number;
+  totalPrototypeAssets: number;
   includeSummaries: boolean;
 }): string {
-  const { target, totalAgents, totalTasks, includeSummaries } = input;
+  const { target, totalAgents, totalTasks, totalPrototypeAssets, includeSummaries } = input;
   return [
     '# Handoff Bundle Index',
     '',
     `- Target: ${target}`,
     `- Total Agents: ${totalAgents}`,
     `- Total Tasks: ${totalTasks}`,
+    `- Total Prototype Assets: ${totalPrototypeAssets}`,
     `- Include Summaries: ${includeSummaries ? 'yes' : 'no'}`,
     '',
     '## Files',
     '',
     '- `handoff_bundle.json`: 机器可读任务总览',
+    '- `prototype_index.json`: 原型图索引（如存在）',
     '- `agents/*.md`: 每个 agent 的任务队列',
     '- `tasks/*.md`: 每个任务可直接投喂编码 Agent 的提示词模板',
     '',
@@ -334,6 +377,67 @@ function renderIndexMarkdown(input: {
   ].join('\n');
 }
 
+function matchTaskPrototypes(
+  task: Task,
+  sourceChunks: number[] | undefined,
+  assets: PrototypeAssetEntry[]
+): PrototypeMatch[] {
+  if (assets.length === 0) {
+    return [];
+  }
+
+  const taskName = normalizeName(task.name);
+  const taskTokens = new Set(taskName.split(' ').filter(token => token.length >= 2));
+  const matches: PrototypeMatch[] = [];
+
+  for (const asset of assets) {
+    let score = 0;
+    const reasons: string[] = [];
+
+    const chunkHits = intersectCount(sourceChunks || [], asset.sourceChunks || []);
+    if (chunkHits > 0) {
+      score += 70 + Math.min(20, chunkHits * 5);
+      reasons.push(`chunk重合(${chunkHits})`);
+    }
+
+    const text = normalizeName(`${asset.alt || ''} ${asset.summary || ''} ${path.basename(asset.sourceFile || '')}`);
+    let tokenHits = 0;
+    for (const token of taskTokens) {
+      if (token.length >= 2 && text.includes(token)) {
+        tokenHits++;
+      }
+    }
+    if (tokenHits > 0) {
+      score += Math.min(30, tokenHits * 8);
+      reasons.push(`关键词命中(${tokenHits})`);
+    }
+
+    if (score >= 35) {
+      matches.push({
+        id: asset.id,
+        path: asset.path,
+        score,
+        reason: reasons.join(' + ') || '弱匹配',
+        summary: asset.summary,
+      });
+    }
+  }
+
+  return matches
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 5);
+}
+
+function intersectCount(a: number[], b: number[]): number {
+  if (a.length === 0 || b.length === 0) return 0;
+  const set = new Set(a);
+  let count = 0;
+  for (const value of b) {
+    if (set.has(value)) count++;
+  }
+  return count;
+}
+
 function normalizeName(input: string): string {
   return (input || '')
     .toLowerCase()

package/src/commands/scan.ts

@@ -1,4 +1,5 @@
 import * as path from 'path';
+import * as fs from 'fs-extra';
 import { Command } from 'commander';
 import { Logger } from '../utils/logger';
 import { 
@@ -8,8 +9,7 @@ import {
   formatSize, 
   parseSize,
   findFiles,
-  writeJson,
-  readFileContent
+  writeJson
 } from '../utils/file';
 import { parseDocument, analyzeBase64Images } from '../services/document-parser';
 import { 
@@ -19,7 +19,7 @@ import {
   getLLMConfigForPurpose,
   validateLLMConfig 
 } from '../services/llm';
-import { Manifest, Chunk } from '../types';
+import { Manifest, Chunk, PrototypeAsset } from '../types';
 
 interface ScanOptions {
   input?: string;
@@ -53,6 +53,16 @@ const SCAN_EXIT_CODE = {
   RUNTIME_ERROR: 10,
 } as const;
 
+interface PrototypeAssetPending {
+  id: string;
+  sourceFile: string;
+  alt: string;
+  mimeType: string;
+  estimatedSize: number;
+  dataUri: string;
+  summary?: string;
+}
+
 export async function scanCommand(options: ScanOptions, command: Command): Promise<void> {
   const logger = new Logger();
   
@@ -118,6 +128,7 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
     let llmChunkingFallbackFiles = 0;
     let imageAssetsDetected = 0;
     let imageAssetsDescribed = 0;
+    const pendingPrototypeAssets: PrototypeAssetPending[] = [];
     if (useLLMChunking && llmConfig) {
       // LLM chunking is enabled by default; fail fast so we don't silently degrade
       // to regex-only behavior on complex documents.
@@ -129,23 +140,44 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
       }
     }
 
-    for (const filePath of inputFiles) {
+    for (let fileIdx = 0; fileIdx < inputFiles.length; fileIdx++) {
+      const filePath = inputFiles[fileIdx];
       logger.info(`Parsing ${path.basename(filePath)}...`);
       
       try {
         const parsed = await parseDocument(filePath);
         let contentForChunking = parsed.content;
-        imageAssetsDetected += parsed.images?.length || 0;
+        const parsedImages = (parsed.images || []).map(image => ({
+          ...image,
+          id: scopeImageId(fileIdx, image.id),
+        }));
+        const idMapping = new Map<string, string>();
+        for (let i = 0; i < (parsed.images || []).length; i++) {
+          idMapping.set(parsed.images![i].id, parsedImages[i].id);
+        }
+        contentForChunking = replaceImageIds(contentForChunking, idMapping);
+        imageAssetsDetected += parsedImages.length;
         let imageSummaries: Record<string, string> = {};
 
-        if (parsed.images && parsed.images.length > 0) {
-          logger.info(`  检测到 ${parsed.images.length} 张嵌入图片`);
+        if (parsedImages.length > 0) {
+          logger.info(`  检测到 ${parsedImages.length} 张嵌入图片`);
           if (llmConfig && llmConfig.apiKey) {
-            imageSummaries = await describeEmbeddedImages(parsed.images, llmConfig, logger);
+            imageSummaries = await describeEmbeddedImages(parsedImages, llmConfig, logger);
             imageAssetsDescribed += Object.keys(imageSummaries).length;
           } else {
             logger.warn('  未配置 LLM，图片仅保留占位信息，不含语义摘要');
           }
+          for (const image of parsedImages) {
+            pendingPrototypeAssets.push({
+              id: image.id,
+              sourceFile: filePath,
+              alt: image.alt,
+              mimeType: image.mimeType,
+              estimatedSize: image.estimatedSize,
+              dataUri: image.dataUri,
+              summary: imageSummaries[image.id],
+            });
+          }
         }
         
         // Log if base64 images were found and removed
@@ -235,7 +267,9 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
     // Prepare chunks directory
     const outputDir = path.dirname(path.resolve(options.output));
     const chunksDir = path.join(outputDir, 'chunks');
+    const prototypesDir = path.join(outputDir, 'prototypes');
     await ensureDir(chunksDir);
+    await ensureDir(prototypesDir);
 
     // Write chunks to files
     const chunks: Chunk[] = [];
@@ -244,7 +278,7 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
       const chunkFileName = `chunk_${i}.txt`;
       const chunkFilePath = path.join(chunksDir, chunkFileName);
       
-      await require('fs-extra').writeFile(chunkFilePath, rawChunk.content, 'utf-8');
+      await fs.writeFile(chunkFilePath, rawChunk.content, 'utf-8');
       
       chunks.push({
         id: i,
@@ -254,6 +288,13 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
       });
     }
 
+    const prototypeAssets = await writePrototypeAssets({
+      outputDir,
+      prototypesDir,
+      rawChunks,
+      pendingAssets: pendingPrototypeAssets,
+    });
+
     // Create manifest
     const manifest: Manifest = {
       version: '1.0.0',
@@ -262,6 +303,7 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
       totalSize: totalSize,
       chunkSize: chunkSizeBytes,
       chunks: chunks,
+      prototypeAssets,
     };
 
     // Write manifest
@@ -270,6 +312,9 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
     await writeJson(outputPath, manifest);
 
     logger.success(`Manifest created: ${outputPath}`);
+    if (prototypeAssets.length > 0) {
+      logger.info(`Prototype index: ${path.join(outputDir, 'prototype_index.json')}`);
+    }
     logger.json({
       status: 'success',
       totalFiles: inputFiles.length,
@@ -281,6 +326,7 @@ export async function scanCommand(options: ScanOptions, command: Command): Promi
       llmChunkingFallbackFiles,
       imageAssetsDetected,
       imageAssetsDescribed,
+      prototypeAssets: prototypeAssets.length,
       manifestPath: outputPath,
     });
 
@@ -527,7 +573,7 @@ function appendImageSummariesToChunk(content: string, imageSummaries: Record<str
     return content;
   }
 
-  const idMatches = content.match(/图片引用\s+((?:IMG|PDFIMG)\d{4})/g) || [];
+  const idMatches = content.match(/图片引用\s+([A-Z0-9_]+)/g) || [];
   const imageIds = Array.from(new Set(idMatches.map(item => item.replace(/.*\s+/, '').trim())));
   if (imageIds.length === 0) {
     return content;
@@ -548,6 +594,113 @@ function appendImageSummariesToChunk(content: string, imageSummaries: Record<str
   return `${content}\n\n### 图片语义补充\n${summaryLines.join('\n')}`;
 }
 
+async function writePrototypeAssets(input: {
+  outputDir: string;
+  prototypesDir: string;
+  rawChunks: Array<{ content: string; sourceFiles: string[]; title?: string }>;
+  pendingAssets: PrototypeAssetPending[];
+}): Promise<PrototypeAsset[]> {
+  const { outputDir, prototypesDir, rawChunks, pendingAssets } = input;
+  if (pendingAssets.length === 0) {
+    return [];
+  }
+
+  const prototypeAssets: PrototypeAsset[] = [];
+  for (const asset of pendingAssets) {
+    const ext = extFromMimeType(asset.mimeType);
+    const fileName = `${asset.id}.${ext}`;
+    const absolutePath = path.join(prototypesDir, fileName);
+    const written = await writeDataUriToFile(asset.dataUri, absolutePath);
+    if (!written) {
+      continue;
+    }
+    const sourceChunks = collectSourceChunks(rawChunks, asset.id);
+    prototypeAssets.push({
+      id: asset.id,
+      sourceFile: asset.sourceFile,
+      alt: asset.alt,
+      mimeType: asset.mimeType,
+      estimatedSize: asset.estimatedSize,
+      path: path.join('prototypes', fileName).replace(/\\/g, '/'),
+      summary: asset.summary,
+      sourceChunks,
+    });
+  }
+
+  const indexJsonPath = path.join(outputDir, 'prototype_index.json');
+  await writeJson(indexJsonPath, {
+    version: '1.0.0',
+    createdAt: new Date().toISOString(),
+    total: prototypeAssets.length,
+    assets: prototypeAssets,
+  });
+
+  const indexMarkdownPath = path.join(outputDir, 'prototype_index.md');
+  const lines: string[] = [
+    '# Prototype Index',
+    '',
+    `- Total: ${prototypeAssets.length}`,
+    '',
+    '| ID | Path | Source File | Chunks | Summary |',
+    '| --- | --- | --- | --- | --- |',
+  ];
+  for (const asset of prototypeAssets) {
+    lines.push(
+      `| ${asset.id} | \`${asset.path}\` | \`${path.basename(asset.sourceFile)}\` | ${asset.sourceChunks.join(', ') || '-'} | ${(asset.summary || '').replace(/\|/g, '\\|')} |`
+    );
+  }
+  await fs.writeFile(indexMarkdownPath, `${lines.join('\n')}\n`, 'utf-8');
+
+  return prototypeAssets;
+}
+
+function collectSourceChunks(
+  rawChunks: Array<{ content: string; sourceFiles: string[]; title?: string }>,
+  imageId: string
+): number[] {
+  const results: number[] = [];
+  for (let i = 0; i < rawChunks.length; i++) {
+    if (rawChunks[i].content.includes(imageId)) {
+      results.push(i);
+    }
+  }
+  return results;
+}
+
+function scopeImageId(fileIdx: number, imageId: string): string {
+  return `F${String(fileIdx + 1).padStart(3, '0')}_${imageId}`;
+}
+
+function replaceImageIds(content: string, idMapping: Map<string, string>): string {
+  let next = content;
+  for (const [fromId, toId] of idMapping.entries()) {
+    next = next.replace(new RegExp(`\\b${escapeRegExp(fromId)}\\b`, 'g'), toId);
+  }
+  return next;
+}
+
+function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function extFromMimeType(mimeType: string): string {
+  if (mimeType.includes('png')) return 'png';
+  if (mimeType.includes('jpeg') || mimeType.includes('jpg')) return 'jpg';
+  if (mimeType.includes('webp')) return 'webp';
+  if (mimeType.includes('gif')) return 'gif';
+  return 'img';
+}
+
+async function writeDataUriToFile(dataUri: string, filePath: string): Promise<boolean> {
+  const match = dataUri.match(/^data:image\/[a-zA-Z0-9.+-]+;base64,([A-Za-z0-9+/=]+)$/);
+  if (!match) {
+    return false;
+  }
+  const buffer = Buffer.from(match[1], 'base64');
+  await fs.writeFile(filePath, buffer);
+  return true;
+}
+
 function readStdin(): Promise<string> {
   return new Promise((resolve) => {
     let data = '';

package/src/services/llm.ts

@@ -36,19 +36,10 @@ export function getLLMConfig(): LLMConfig {
   };
 }
 
-export function getLLMConfigForPurpose(purpose: 'scan' | 'analyze' | 'vision' | 'default'): LLMConfig {
-  const base = getLLMConfig();
-  const purposeModelMap: Record<string, string | undefined> = {
-    scan: process.env.LLM_MODEL_SCAN,
-    analyze: process.env.LLM_MODEL_ANALYZE,
-    vision: process.env.LLM_MODEL_VISION,
-    default: process.env.LLM_MODEL,
-  };
-  const selectedModel = purposeModelMap[purpose] || base.model;
-  return {
-    ...base,
-    model: selectedModel,
-  };
+export function getLLMConfigForPurpose(_purpose: 'scan' | 'analyze' | 'vision' | 'default'): LLMConfig {
+  // Unified model strategy: always use LLM_MODEL.
+  // Keep this function for backward-compatible call sites.
+  return getLLMConfig();
 }
 
 export function validateLLMConfig(config: LLMConfig): void {
@@ -348,7 +339,7 @@ export async function describeEmbeddedImages(
 
   const visionConfig = {
     ...config,
-    model: getLLMConfigForPurpose('vision').model || config.model,
+    model: getLLMConfig().model || config.model,
   };
   validateLLMConfig(visionConfig);
   const maxImages = Math.max(0, parseEnvInt('LLM_IMAGE_MAX_PER_DOC', 12));

package/src/types.ts

@@ -10,6 +10,17 @@ export interface Chunk {
   endLine?: number;
 }
 
+export interface PrototypeAsset {
+  id: string;
+  sourceFile: string;
+  alt: string;
+  mimeType: string;
+  estimatedSize: number;
+  path: string;
+  summary?: string;
+  sourceChunks: number[];
+}
+
 export interface Manifest {
   version: string;
   createdAt: string;
@@ -17,6 +28,7 @@ export interface Manifest {
   totalSize: number;
   chunkSize: number;
   chunks: Chunk[];
+  prototypeAssets?: PrototypeAsset[];
 }
 
 export interface Feature {