spec-agent 1.0.3

package/src/services/llm.ts

@@ -0,0 +1,857 @@
+import { Logger } from '../utils/logger';
+import { ChunkSummary, Feature, DataModel, Page, Api } from '../types';
+
+export interface LLMConfig {
+  apiKey: string;
+  baseUrl: string;
+  model: string;
+  maxTokens?: number;
+  temperature?: number;
+}
+
+export interface LLMResponse {
+  content: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export interface ImageUnderstandingInput {
+  id: string;
+  alt?: string;
+  mimeType?: string;
+  estimatedSize?: number;
+  dataUri: string;
+}
+
+export function getLLMConfig(): LLMConfig {
+  return {
+    apiKey: process.env.OPENAI_API_KEY || process.env.LLM_API_KEY || '',
+    baseUrl: process.env.OPENAI_BASE_URL || process.env.LLM_BASE_URL || 'https://api.openai.com/v1',
+    model: process.env.LLM_MODEL || 'gpt-4o-mini',
+    maxTokens: parseInt(process.env.LLM_MAX_TOKENS || '4000', 10),
+    temperature: parseFloat(process.env.LLM_TEMPERATURE || '0.3'),
+  };
+}
+
+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 validateLLMConfig(config: LLMConfig): void {
+  if (!config.apiKey) {
+    throw new Error(
+      'LLM API key not found. Please set one of:\n  - OPENAI_API_KEY\n  - LLM_API_KEY'
+    );
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function parseEnvInt(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) {
+    return fallback;
+  }
+  const parsed = parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function isRetriableStatus(status: number): boolean {
+  return [408, 409, 425, 429, 500, 502, 503, 504].includes(status);
+}
+
+function extractStatusFromErrorMessage(message: string): number | null {
+  const match = message.match(/LLM API error \((\d+)\):/);
+  if (!match) {
+    return null;
+  }
+  const status = parseInt(match[1], 10);
+  return Number.isFinite(status) ? status : null;
+}
+
+function shouldRetryError(error: unknown): boolean {
+  if (error instanceof Error) {
+    if (error.name === 'AbortError') {
+      return true;
+    }
+    const status = extractStatusFromErrorMessage(error.message);
+    if (status !== null) {
+      return isRetriableStatus(status);
+    }
+    const retryableText = [
+      'fetch failed',
+      'network',
+      'timeout',
+      'timed out',
+      'ECONNRESET',
+      'ETIMEDOUT',
+      'ENOTFOUND',
+      'EAI_AGAIN',
+    ];
+    return retryableText.some(text => error.message.includes(text));
+  }
+  return false;
+}
+
+export async function callLLM(
+  prompt: string,
+  config: LLMConfig,
+  logger?: Logger
+): Promise<LLMResponse> {
+  const url = `${config.baseUrl.replace(/\/$/, '')}/chat/completions`;
+  const maxRetries = Math.max(0, parseEnvInt('LLM_RETRIES', 2));
+  const timeoutMs = Math.max(5000, parseEnvInt('LLM_TIMEOUT_MS', 60000));
+  const retryDelayMs = Math.max(200, parseEnvInt('LLM_RETRY_DELAY_MS', 1200));
+  
+  if (logger) {
+    logger.debug(`Calling LLM: ${config.model} at ${config.baseUrl}`);
+  }
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${config.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: config.model,
+          messages: [
+            {
+              role: 'system',
+              content: 'You are a technical analyst specializing in extracting structured information from software requirement documents. Always respond with valid JSON.',
+            },
+            {
+              role: 'user',
+              content: prompt,
+            },
+          ],
+          max_tokens: config.maxTokens,
+          temperature: config.temperature,
+          response_format: { type: 'json_object' },
+        }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutHandle);
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`LLM API error (${response.status}): ${errorText}`);
+      }
+
+      const data = await response.json() as {
+        choices?: Array<{ message?: { content?: string } }>;
+        usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+      };
+
+      if (!data.choices?.[0]?.message?.content) {
+        throw new Error('Invalid LLM response format');
+      }
+
+      return {
+        content: data.choices[0].message.content,
+        usage: data.usage ? {
+          promptTokens: data.usage.prompt_tokens,
+          completionTokens: data.usage.completion_tokens,
+          totalTokens: data.usage.total_tokens,
+        } : undefined,
+      };
+    } catch (error) {
+      clearTimeout(timeoutHandle);
+      const canRetry = attempt < maxRetries && shouldRetryError(error);
+
+      if (canRetry) {
+        const delay = retryDelayMs * Math.pow(2, attempt);
+        if (logger) {
+          logger.warn(`LLM 请求失败，${delay}ms 后重试 (${attempt + 1}/${maxRetries})`);
+        }
+        await sleep(delay);
+        continue;
+      }
+
+      throw error instanceof Error ? error : new Error(String(error));
+    }
+  }
+
+  throw new Error('LLM request failed after retries');
+}
+
+async function callVisionLLM(
+  prompt: string,
+  imageDataUri: string,
+  config: LLMConfig,
+  logger?: Logger
+): Promise<string> {
+  const url = `${config.baseUrl.replace(/\/$/, '')}/chat/completions`;
+  const timeoutMs = Math.max(5000, parseEnvInt('LLM_TIMEOUT_MS', 60000));
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${config.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: config.model,
+        messages: [
+          {
+            role: 'system',
+            content: 'You are a multimodal analyst. Describe image content for requirement understanding. Keep it concise and factual.',
+          },
+          {
+            role: 'user',
+            content: [
+              { type: 'text', text: prompt },
+              { type: 'image_url', image_url: { url: imageDataUri } },
+            ],
+          },
+        ],
+        max_tokens: Math.min(config.maxTokens || 600, 600),
+        temperature: 0,
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Vision LLM API error (${response.status}): ${errorText}`);
+    }
+
+    const data = await response.json() as {
+      choices?: Array<{ message?: { content?: string } }>;
+    };
+    const text = data.choices?.[0]?.message?.content;
+    if (!text) {
+      throw new Error('Invalid vision LLM response format');
+    }
+    return text.trim();
+  } finally {
+    clearTimeout(timeoutHandle);
+    if (logger) {
+      logger.debug('Vision LLM request finished');
+    }
+  }
+}
+
+function parseImageDataUri(dataUri: string): { mimeType: string; base64: string } | null {
+  const match = dataUri.match(/^data:(image\/[a-zA-Z0-9.+-]+);base64,([A-Za-z0-9+/=]+)$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    mimeType: match[1],
+    base64: match[2],
+  };
+}
+
+async function compressImageDataUri(
+  dataUri: string,
+  maxImageBytes: number,
+  logger?: Logger
+): Promise<string | null> {
+  const parsed = parseImageDataUri(dataUri);
+  if (!parsed) {
+    return null;
+  }
+
+  const originalBuffer = Buffer.from(parsed.base64, 'base64');
+  if (originalBuffer.length <= maxImageBytes) {
+    return dataUri;
+  }
+
+  try {
+    const sharpImport = await import('sharp');
+    const sharpLib = (sharpImport as { default?: typeof import('sharp') }).default || (sharpImport as unknown as typeof import('sharp'));
+    const meta = await sharpLib(originalBuffer).metadata();
+    const baseWidth = meta.width || 1800;
+
+    for (let attempt = 0; attempt < 6; attempt++) {
+      const scale = Math.max(0.25, 1 - attempt * 0.15);
+      const targetWidth = Math.max(480, Math.floor(baseWidth * scale));
+      const quality = Math.max(35, 80 - attempt * 10);
+
+      const compressed = await sharpLib(originalBuffer)
+        .resize({ width: targetWidth, withoutEnlargement: true })
+        .jpeg({ quality, mozjpeg: true })
+        .toBuffer();
+
+      if (compressed.length <= maxImageBytes) {
+        if (logger) {
+          logger.info(`图片已压缩: ${originalBuffer.length} -> ${compressed.length} bytes`);
+        }
+        return `data:image/jpeg;base64,${compressed.toString('base64')}`;
+      }
+    }
+  } catch (error) {
+    if (logger) {
+      logger.warn(`图片压缩失败，使用原图: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  return null;
+}
+
+async function prepareImageForVision(
+  dataUri: string,
+  maxImageBytes: number,
+  logger?: Logger
+): Promise<{ dataUri: string; bytes: number } | null> {
+  const currentBytes = Buffer.byteLength(dataUri, 'utf-8');
+  if (currentBytes <= maxImageBytes) {
+    return { dataUri, bytes: currentBytes };
+  }
+
+  const compressed = await compressImageDataUri(dataUri, maxImageBytes, logger);
+  if (!compressed) {
+    return null;
+  }
+  const compressedBytes = Buffer.byteLength(compressed, 'utf-8');
+  if (compressedBytes > maxImageBytes) {
+    return null;
+  }
+
+  return { dataUri: compressed, bytes: compressedBytes };
+}
+
+export async function describeEmbeddedImages(
+  images: ImageUnderstandingInput[],
+  config: LLMConfig,
+  logger?: Logger
+): Promise<Record<string, string>> {
+  if (images.length === 0) {
+    return {};
+  }
+
+  const visionConfig = {
+    ...config,
+    model: getLLMConfigForPurpose('vision').model || config.model,
+  };
+  validateLLMConfig(visionConfig);
+  const maxImages = Math.max(0, parseEnvInt('LLM_IMAGE_MAX_PER_DOC', 12));
+  const maxImageBytes = Math.max(64 * 1024, parseEnvInt('LLM_IMAGE_MAX_BYTES', 2 * 1024 * 1024));
+  const selected = images.slice(0, maxImages);
+  const summaries: Record<string, string> = {};
+
+  for (const image of selected) {
+    const prepared = await prepareImageForVision(image.dataUri, maxImageBytes, logger);
+    if (!prepared) {
+      const imageBytes = Buffer.byteLength(image.dataUri, 'utf-8');
+      summaries[image.id] = `图片过大且压缩失败，跳过语义识别（${imageBytes} bytes > ${maxImageBytes} bytes）`;
+      if (logger) {
+        logger.warn(`图片 ${image.id} 超出大小限制，压缩后仍不可用`);
+      }
+      continue;
+    }
+
+    const prompt = [
+      '请阅读这张需求文档中的图片，并完成 OCR+语义理解。',
+      '输出要求：',
+      '1) 识别可见文字（如标题、字段、按钮、错误信息）',
+      '2) 识别界面/流程/图表要点',
+      '3) 推测它对应的业务功能',
+      '限制：最多 160 字。',
+      `上下文 alt: ${image.alt || '无'}`,
+      `图片ID: ${image.id}`,
+    ].join('\n');
+
+    try {
+      const rawSummary = await callVisionLLM(prompt, prepared.dataUri, visionConfig, logger);
+      summaries[image.id] = sanitizeImageSummary(rawSummary);
+    } catch (error) {
+      try {
+        const ocrFallback = await callVisionLLM(
+          `请只做 OCR，提取图片中的关键文字（最多120字）。图片ID: ${image.id}`,
+          prepared.dataUri,
+          visionConfig,
+          logger
+        );
+        summaries[image.id] = sanitizeImageSummary(`OCR兜底: ${ocrFallback}`);
+        if (logger) {
+          logger.warn(`图片 ${image.id} 语义理解失败，已使用 OCR 兜底`);
+        }
+      } catch (fallbackError) {
+        summaries[image.id] = `图片理解失败: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`;
+        if (logger) {
+          logger.warn(`图片 ${image.id} 理解失败，保留占位信息`);
+        }
+      }
+    }
+  }
+
+  return summaries;
+}
+
+function sanitizeImageSummary(raw: string): string {
+  if (!raw) return '';
+  const cleaned = raw
+    .replace(/#{1,6}\s*/g, '')
+    .replace(/\*\*/g, '')
+    .replace(/`/g, '')
+    .replace(/\r?\n+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  const noLongNoise = cleaned
+    .split(' ')
+    .filter(token => token.length <= 40)
+    .join(' ')
+    .trim();
+
+  if (noLongNoise.length <= 220) {
+    return noLongNoise;
+  }
+  return `${noLongNoise.slice(0, 220)}...`;
+}
+
+const ANALYSIS_PROMPT_TEMPLATE = `Analyze the following requirement document chunk and extract normalized, implementation-ready structured information.
+
+Focus Area: {focus}
+
+Document Chunk:
+---
+{content}
+---
+
+Extract the following information and return as JSON:
+
+{
+  "features": [
+    {
+      "id": "F001",
+      "name": "Feature name",
+      "description": "Detailed description",
+      "priority": "P0|P1|P2",
+      "dependencies": ["F002"]
+    }
+  ],
+  "dataModels": [
+    {
+      "name": "ModelName",
+      "fields": ["field1", "field2"],
+      "relationships": ["OtherModel"]
+    }
+  ],
+  "pages": [
+    {
+      "name": "PageName",
+      "route": "/path",
+      "components": ["Component1"]
+    }
+  ],
+  "apis": [
+    {
+      "method": "GET|POST|PUT|DELETE",
+      "path": "/api/endpoint",
+      "description": "What this API does"
+    }
+  ],
+  "businessRules": [
+    "Description of business rule 1",
+    "Description of business rule 2"
+  ]
+}
+
+Guidelines:
+- Only include information explicitly present in the document.
+- Prefer capability-level features (e.g. "客户开户"), not tiny UI actions.
+- Merge synonymous items in the same chunk. Do not output near-duplicates.
+- Feature names must be short canonical names, avoid prefixes/suffixes like "流程", "功能模块", "支持XX".
+- Dependencies should reference other feature IDs in the same output when explicit.
+- Mark priority based on explicit mentions (P0=critical, P1=important, P2=nice-to-have).
+- If a category has no items, return empty array.
+- Return pure JSON only.`;
+
+export async function analyzeChunkWithLLM(
+  chunkContent: string,
+  chunkId: number,
+  focus: string,
+  config: LLMConfig,
+  logger?: Logger
+): Promise<ChunkSummary> {
+  validateLLMConfig(config);
+
+  const prompt = ANALYSIS_PROMPT_TEMPLATE
+    .replace('{focus}', focus)
+    .replace('{content}', chunkContent);
+
+  const response = await callLLM(prompt, config, logger);
+  
+  let parsed: Partial<ChunkSummary>;
+  try {
+    parsed = JSON.parse(response.content);
+  } catch (e) {
+    throw new Error(`Failed to parse LLM response as JSON: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const normalizeFeatureName = (name: string): string => {
+    return (name || '')
+      .replace(/[\r\n]+/g, ' ')
+      .replace(/\s+/g, ' ')
+      .replace(/(功能模块|功能点|流程管理|流程|功能|模块)$/g, '')
+      .trim();
+  };
+
+  const dedupeByName = <T extends { name: string }>(items: T[]): T[] => {
+    const seen = new Set<string>();
+    const result: T[] = [];
+    for (const item of items) {
+      const key = normalizeFeatureName(item.name).toLowerCase();
+      if (!key || seen.has(key)) continue;
+      seen.add(key);
+      result.push({ ...item, name: normalizeFeatureName(item.name) });
+    }
+    return result;
+  };
+
+  // Validate and normalize the response
+  const summary: ChunkSummary = {
+    chunkId,
+    sourceFiles: [], // Will be filled by caller
+    size: '0B', // Will be filled by caller
+    features: dedupeByName((parsed.features || []).map((f: Partial<Feature>, idx: number) => ({
+      id: f.id || `F${String(chunkId * 100 + idx + 1).padStart(3, '0')}`,
+      name: f.name || 'Unnamed Feature',
+      description: f.description || '',
+      priority: (f.priority as Feature['priority']) || 'P2',
+      dependencies: f.dependencies || [],
+      sourceChunk: chunkId,
+    }))),
+    dataModels: (parsed.dataModels || []).map((m: Partial<DataModel>) => ({
+      name: m.name || 'UnnamedModel',
+      fields: m.fields || [],
+      relationships: m.relationships || [],
+      sourceChunk: chunkId,
+    })),
+    pages: (parsed.pages || []).map((p: Partial<Page>) => ({
+      name: p.name || 'UnnamedPage',
+      route: p.route || '/',
+      components: p.components || [],
+      sourceChunk: chunkId,
+    })),
+    apis: (parsed.apis || []).map((a: Partial<Api>) => ({
+      method: (a.method as Api['method']) || 'GET',
+      path: a.path || '/api/unknown',
+      description: a.description || '',
+      sourceChunk: chunkId,
+    })),
+    businessRules: parsed.businessRules || [],
+    extractedAt: new Date().toISOString(),
+    llmUsage: response.usage,
+  };
+
+  return summary;
+}
+
+// ============================================================================
+// LLM-Driven Document Structure Analysis
+// ============================================================================
+
+export interface DocumentSection {
+  id: string;
+  title: string;
+  level: number;
+  startLine: number;
+  endLine: number;
+  content: string;
+  suggestedGroup?: string;
+}
+
+export interface DocumentStructure {
+  title: string;
+  sections: DocumentSection[];
+  suggestedGroups: {
+    name: string;
+    sections: string[];
+    reason: string;
+  }[];
+}
+
+const STRUCTURE_ANALYSIS_PROMPT = `你是需求文档结构分析专家。请基于“带行号的文本”做结构切分。
+
+文档内容（每行格式为 "N|文本"，N 为原始行号）：
+---
+{content}
+---
+
+请返回 JSON：
+{
+  "title": "文档标题",
+  "sections": [
+    {
+      "id": "S001",
+      "title": "章节标题（无标题时可用语义命名）",
+      "level": 1,
+      "startLine": 1,
+      "endLine": 50,
+      "content": "章节摘要（<=200字）",
+      "suggestedGroup": "分组名称"
+    }
+  ],
+  "suggestedGroups": [
+    {
+      "name": "分组名称",
+      "sections": ["S001", "S002"],
+      "reason": "该分组的业务理由"
+    }
+  ]
+}
+
+要求：
+1. startLine/endLine 必须引用输入中的真实行号，且 startLine <= endLine。
+2. 即使没有标准 Markdown 标题，也要按语义主题划分章节。
+3. 章节尽量完整，不要把同一个业务点打散到多个章节。
+4. 若文本中存在目录、版本记录、附录，可作为单独分组。
+5. 返回严格 JSON，不要附加解释文字。`;
+
+const WINDOW_LINE_COUNT = 800;
+const WINDOW_OVERLAP = 40;
+
+function numberLines(lines: string[], startLine: number): string {
+  return lines
+    .map((line, idx) => `${startLine + idx}|${line}`)
+    .join('\n');
+}
+
+function normalizeSection(
+  section: Partial<DocumentSection>,
+  fallbackId: string,
+  minLine: number,
+  maxLine: number
+): DocumentSection {
+  const rawStart = typeof section.startLine === 'number' ? section.startLine : minLine;
+  const rawEnd = typeof section.endLine === 'number' ? section.endLine : rawStart;
+  const startLine = Math.max(minLine, Math.min(rawStart, maxLine));
+  const endLine = Math.max(startLine, Math.min(rawEnd, maxLine));
+
+  return {
+    id: section.id || fallbackId,
+    title: section.title || 'Untitled Section',
+    level: section.level || 1,
+    startLine,
+    endLine,
+    content: section.content || '',
+    suggestedGroup: section.suggestedGroup || '未分组',
+  };
+}
+
+function dedupeAndSortSections(sections: DocumentSection[]): DocumentSection[] {
+  const sorted = sections
+    .slice()
+    .sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine);
+
+  const result: DocumentSection[] = [];
+  for (const section of sorted) {
+    const last = result[result.length - 1];
+    if (!last) {
+      result.push(section);
+      continue;
+    }
+
+    // Skip near-duplicate segments from overlapping windows.
+    const sameRange = Math.abs(section.startLine - last.startLine) <= 2
+      && Math.abs(section.endLine - last.endLine) <= 2;
+    if (sameRange) {
+      continue;
+    }
+
+    result.push(section);
+  }
+  return result;
+}
+
+/**
+ * Use LLM to analyze document structure and suggest optimal chunking strategy
+ */
+export async function analyzeDocumentStructure(
+  content: string,
+  config: LLMConfig,
+  logger?: Logger
+): Promise<DocumentStructure> {
+  validateLLMConfig(config);
+  const lines = content.split('\n');
+  if (lines.length === 0) {
+    throw new Error('Document content is empty');
+  }
+
+  if (logger) {
+    logger.info(`使用 LLM 分析文档结构（总行数: ${lines.length}）...`);
+  }
+
+  const windowStarts: number[] = [];
+  if (lines.length <= WINDOW_LINE_COUNT) {
+    windowStarts.push(0);
+  } else {
+    const stride = WINDOW_LINE_COUNT - WINDOW_OVERLAP;
+    for (let start = 0; start < lines.length; start += stride) {
+      windowStarts.push(start);
+      if (start + WINDOW_LINE_COUNT >= lines.length) {
+        break;
+      }
+    }
+  }
+
+  const collectedSections: DocumentSection[] = [];
+  const collectedGroupReasons = new Map<string, string>();
+  let mergedTitle = 'Untitled Document';
+
+  for (let windowIdx = 0; windowIdx < windowStarts.length; windowIdx++) {
+    const start = windowStarts[windowIdx];
+    const end = Math.min(start + WINDOW_LINE_COUNT, lines.length);
+    const slice = lines.slice(start, end);
+    const numbered = numberLines(slice, start + 1);
+    const prompt = STRUCTURE_ANALYSIS_PROMPT.replace('{content}', numbered);
+
+    if (logger && windowStarts.length > 1) {
+      logger.info(`  分析窗口 ${windowIdx + 1}/${windowStarts.length}（行 ${start + 1}-${end}）`);
+    }
+
+    const response = await callLLM(prompt, config, logger);
+    let parsed: Partial<DocumentStructure>;
+    try {
+      parsed = JSON.parse(response.content);
+    } catch (e) {
+      throw new Error(`Failed to parse document structure: ${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    if (parsed.title && mergedTitle === 'Untitled Document') {
+      mergedTitle = parsed.title;
+    }
+
+    const normalizedSections = (parsed.sections || []).map((s: Partial<DocumentSection>, idx: number) =>
+      normalizeSection(
+        s,
+        `S${String(collectedSections.length + idx + 1).padStart(3, '0')}`,
+        start + 1,
+        end
+      )
+    );
+    collectedSections.push(...normalizedSections);
+
+    for (const group of parsed.suggestedGroups || []) {
+      if (group.name && group.reason && !collectedGroupReasons.has(group.name)) {
+        collectedGroupReasons.set(group.name, group.reason);
+      }
+    }
+  }
+
+  const sections = dedupeAndSortSections(collectedSections).map((section, idx) => ({
+    ...section,
+    id: `S${String(idx + 1).padStart(3, '0')}`,
+  }));
+
+  if (sections.length === 0) {
+    throw new Error('LLM returned no usable sections');
+  }
+
+  const groups = new Map<string, string[]>();
+  for (const section of sections) {
+    const groupName = section.suggestedGroup || '未分组';
+    if (!groups.has(groupName)) {
+      groups.set(groupName, []);
+    }
+    groups.get(groupName)!.push(section.id);
+  }
+
+  const suggestedGroups = Array.from(groups.entries()).map(([name, sectionIds]) => ({
+    name,
+    sections: sectionIds,
+    reason: collectedGroupReasons.get(name) || '语义相近章节分组',
+  }));
+
+  return {
+    title: mergedTitle,
+    sections,
+    suggestedGroups,
+  };
+}
+
+/**
+ * Split content based on LLM-analyzed structure
+ */
+export function splitByLLMStructure(
+  content: string,
+  structure: DocumentStructure,
+  maxChunkSize: number
+): Array<{ title: string; content: string; sections: string[] }> {
+  const lines = content.split('\n');
+  const chunks: Array<{ title: string; content: string; sections: string[] }> = [];
+
+  // Group sections by suggestedGroup
+  const groupMap = new Map<string, DocumentSection[]>();
+  
+  for (const section of structure.sections) {
+    const groupName = section.suggestedGroup || '未分组';
+    if (!groupMap.has(groupName)) {
+      groupMap.set(groupName, []);
+    }
+    groupMap.get(groupName)!.push(section);
+  }
+
+  // Create chunks from groups
+  for (const [groupName, sections] of groupMap) {
+    // Sort sections by startLine
+    sections.sort((a, b) => a.startLine - b.startLine);
+
+    let currentChunk: string[] = [];
+    let currentSections: string[] = [];
+    let currentSize = 0;
+
+    for (const section of sections) {
+      const sectionContent = lines
+        .slice(Math.max(0, section.startLine - 1), section.endLine)
+        .join('\n');
+      const sectionSize = Buffer.byteLength(sectionContent, 'utf-8');
+
+      // If adding this section would exceed max size, start new chunk
+      if (currentSize + sectionSize > maxChunkSize && currentChunk.length > 0) {
+        chunks.push({
+          title: groupName,
+          content: currentChunk.join('\n\n---\n\n'),
+          sections: [...currentSections],
+        });
+        currentChunk = [sectionContent];
+        currentSections = [section.id];
+        currentSize = sectionSize;
+      } else {
+        currentChunk.push(sectionContent);
+        currentSections.push(section.id);
+        currentSize += sectionSize;
+      }
+    }
+
+    // Don't forget the last chunk
+    if (currentChunk.length > 0) {
+      chunks.push({
+        title: groupName,
+        content: currentChunk.join('\n\n---\n\n'),
+        sections: [...currentSections],
+      });
+    }
+  }
+
+  return chunks;
+}