autosnippet 3.0.0 → 3.0.2

package/lib/http/routes/candidates.js

@@ -4,10 +4,10 @@
  */
 
 import express from 'express';
-import { asyncHandler } from '../middleware/errorHandler.js';
+import Logger from '../../infrastructure/logging/Logger.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { ValidationError } from '../../shared/errors/index.js';
-import Logger from '../../infrastructure/logging/Logger.js';
+import { asyncHandler } from '../middleware/errorHandler.js';
 import { createStreamSession, getStreamSession } from '../utils/sse-sessions.js';
 
 const router = express.Router();
@@ -20,127 +20,137 @@ const logger = Logger.getInstance();
  * 对若干候选条目进行 AI 语义字段补全
  * Body: { candidateIds: string[] }
  */
-router.post('/enrich', asyncHandler(async (req, res) => {
-  const { candidateIds } = req.body;
-  if (!Array.isArray(candidateIds) || candidateIds.length === 0) {
-    throw new ValidationError('candidateIds array is required and must not be empty');
-  }
-  if (candidateIds.length > 20) {
-    throw new ValidationError('Max 20 candidates per enrichment call');
-  }
-
-  const container = getServiceContainer();
-  const knowledgeService = container.get('knowledgeService');
-  const aiProvider = container.get('aiProvider');
-
-  // 收集候选条目
-  const candidates = [];
-  for (const id of candidateIds) {
-    try {
-      const entry = await knowledgeService.get(id);
-      if (entry) {
-        const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
-        candidates.push({
-          id: json.id,
-          title: json.title,
-          language: json.language,
-          category: json.category,
-          description: json.description,
-          code: json.content?.pattern || '',
-          rationale: json.content?.rationale,
-          knowledgeType: json.knowledgeType,
-          complexity: json.complexity,
-          scope: json.scope,
-          steps: json.content?.steps,
-          constraints: json.constraints,
-        });
-      }
-    } catch (err) {
-      logger.warn(`enrich: failed to load candidate ${id}`, { error: err.message });
+router.post(
+  '/enrich',
+  asyncHandler(async (req, res) => {
+    const { candidateIds } = req.body;
+    if (!Array.isArray(candidateIds) || candidateIds.length === 0) {
+      throw new ValidationError('candidateIds array is required and must not be empty');
+    }
+    if (candidateIds.length > 20) {
+      throw new ValidationError('Max 20 candidates per enrichment call');
     }
-  }
 
-  if (candidates.length === 0) {
-    return res.json({ success: true, data: { enriched: 0, total: 0, results: [] } });
-  }
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const aiProvider = container.get('aiProvider');
 
-  let enrichedCount = 0;
-  const results = [];
+    // 收集候选条目
+    const candidates = [];
+    for (const id of candidateIds) {
+      try {
+        const entry = await knowledgeService.get(id);
+        if (entry) {
+          const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+          candidates.push({
+            id: json.id,
+            title: json.title,
+            language: json.language,
+            category: json.category,
+            description: json.description,
+            code: json.content?.pattern || '',
+            rationale: json.content?.rationale,
+            knowledgeType: json.knowledgeType,
+            complexity: json.complexity,
+            scope: json.scope,
+            steps: json.content?.steps,
+            constraints: json.constraints,
+          });
+        }
+      } catch (err) {
+        logger.warn(`enrich: failed to load candidate ${id}`, { error: err.message });
+      }
+    }
 
-  if (aiProvider) {
-    let enriched = [];
-    try {
-      enriched = await aiProvider.enrichCandidates(candidates);
-    } catch (err) {
-      logger.warn('AI enrichCandidates failed', { error: err.message });
+    if (candidates.length === 0) {
+      return res.json({ success: true, data: { enriched: 0, total: 0, results: [] } });
     }
 
-    for (const item of enriched) {
-      // 安全的 index 映射：AI 未返回 index 时根据数组位置推断
-      const idx = typeof item.index === 'number' ? item.index : enriched.indexOf(item);
-      const cand = candidates[idx];
-      if (!cand) continue;
+    let enrichedCount = 0;
+    const results = [];
 
+    if (aiProvider) {
+      let enriched = [];
       try {
-        const updateData = {};
-        let changed = false;
-
-        // content 嵌套字段（rationale / steps）共用一次 DB 读取
-        const needsContentMerge = (item.rationale && !cand.rationale) ||
-                                  (item.steps && (!cand.steps || cand.steps.length === 0));
-        let contentBase = null;
-        if (needsContentMerge) {
-          const entry = await knowledgeService.get(cand.id);
-          const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
-          contentBase = { ...(json.content || {}) };
-        }
+        enriched = await aiProvider.enrichCandidates(candidates);
+      } catch (err) {
+        logger.warn('AI enrichCandidates failed', { error: err.message });
+      }
 
-        if (item.rationale && !cand.rationale) {
-          contentBase.rationale = item.rationale;
-          changed = true;
-        }
-        if (item.steps && (!cand.steps || cand.steps.length === 0)) {
-          contentBase.steps = item.steps;
-          changed = true;
-        }
-        if (contentBase && changed) {
-          updateData.content = contentBase;
+      for (const item of enriched) {
+        // 安全的 index 映射：AI 未返回 index 时根据数组位置推断
+        const idx = typeof item.index === 'number' ? item.index : enriched.indexOf(item);
+        const cand = candidates[idx];
+        if (!cand) {
+          continue;
         }
 
-        if (item.knowledgeType && !cand.knowledgeType) {
-          updateData.knowledgeType = item.knowledgeType;
-          changed = true;
-        }
-        if (item.complexity && !cand.complexity) {
-          updateData.complexity = item.complexity;
-          changed = true;
-        }
-        if (item.scope && !cand.scope) {
-          updateData.scope = item.scope;
-          changed = true;
-        }
-        if (item.constraints && !cand.constraints?.preconditions?.length) {
-          updateData.constraints = item.constraints;
-          changed = true;
-        }
+        try {
+          const updateData = {};
+          let changed = false;
+
+          // content 嵌套字段（rationale / steps）共用一次 DB 读取
+          const needsContentMerge =
+            (item.rationale && !cand.rationale) ||
+            (item.steps && (!cand.steps || cand.steps.length === 0));
+          let contentBase = null;
+          if (needsContentMerge) {
+            const entry = await knowledgeService.get(cand.id);
+            const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+            contentBase = { ...(json.content || {}) };
+          }
 
-        if (changed) {
-          await knowledgeService.update(cand.id, updateData, { userId: 'dashboard-enrich' });
-          enrichedCount++;
+          if (item.rationale && !cand.rationale) {
+            contentBase.rationale = item.rationale;
+            changed = true;
+          }
+          if (item.steps && (!cand.steps || cand.steps.length === 0)) {
+            contentBase.steps = item.steps;
+            changed = true;
+          }
+          if (contentBase && changed) {
+            updateData.content = contentBase;
+          }
+
+          if (item.knowledgeType && !cand.knowledgeType) {
+            updateData.knowledgeType = item.knowledgeType;
+            changed = true;
+          }
+          if (item.complexity && !cand.complexity) {
+            updateData.complexity = item.complexity;
+            changed = true;
+          }
+          if (item.scope && !cand.scope) {
+            updateData.scope = item.scope;
+            changed = true;
+          }
+          if (item.constraints && !cand.constraints?.preconditions?.length) {
+            updateData.constraints = item.constraints;
+            changed = true;
+          }
+
+          if (changed) {
+            await knowledgeService.update(cand.id, updateData, { userId: 'dashboard-enrich' });
+            enrichedCount++;
+          }
+          results.push({
+            id: cand.id,
+            enriched: changed,
+            filledFields: Object.keys(item).filter((k) => k !== 'index'),
+          });
+        } catch (err) {
+          logger.warn(`enrich: failed to update candidate ${cand.id}`, { error: err.message });
+          results.push({ id: cand.id, enriched: false, filledFields: [], error: err.message });
         }
-        results.push({ id: cand.id, enriched: changed, filledFields: Object.keys(item).filter(k => k !== 'index') });
-      } catch (err) {
-        logger.warn(`enrich: failed to update candidate ${cand.id}`, { error: err.message });
-        results.push({ id: cand.id, enriched: false, filledFields: [], error: err.message });
       }
     }
-  }
 
-  res.json({
-    success: true,
-    data: { enriched: enrichedCount, total: candidates.length, results },
-  });
-}));
+    res.json({
+      success: true,
+      data: { enriched: enrichedCount, total: candidates.length, results },
+    });
+  })
+);
 
 /* ═══ Bootstrap 内容润色 ═════════════════════════════════ */
 
@@ -149,21 +159,24 @@ router.post('/enrich', asyncHandler(async (req, res) => {
  * AI 内容润色（适用于 Bootstrap 产出的批量候选）
  * Body: { candidateIds?: string[], userPrompt?: string, dryRun?: boolean }
  */
-router.post('/bootstrap-refine', asyncHandler(async (req, res) => {
-  const { candidateIds, userPrompt, dryRun } = req.body;
+router.post(
+  '/bootstrap-refine',
+  asyncHandler(async (req, res) => {
+    const { candidateIds, userPrompt, dryRun } = req.body;
 
-  const container = getServiceContainer();
+    const container = getServiceContainer();
 
-  // 复用 MCP handler 的 bootstrapRefine 逻辑
-  const { bootstrapRefine } = await import('../../external/mcp/handlers/bootstrap.js');
-  const ctx = { container, logger };
-  const result = await bootstrapRefine(ctx, { candidateIds, userPrompt, dryRun });
+    // 复用 MCP handler 的 bootstrapRefine 逻辑
+    const { bootstrapRefine } = await import('../../external/mcp/handlers/bootstrap.js');
+    const ctx = { container, logger };
+    const result = await bootstrapRefine(ctx, { candidateIds, userPrompt, dryRun });
 
-  // envelope 返回 { success, data, meta, ... }，直接取 data
-  const data = result?.data ?? { refined: 0, total: 0, errors: [], results: [] };
+    // envelope 返回 { success, data, meta, ... }，直接取 data
+    const data = result?.data ?? { refined: 0, total: 0, errors: [], results: [] };
 
-  res.json({ success: true, data });
-}));
+    res.json({ success: true, data });
+  })
+);
 
 /* ═══ 对话式润色 — 工具函数 ═══════════════════════════════ */
 
@@ -281,27 +294,63 @@ function buildUpdateFromRefineResult(before, parsed) {
   // ─── key 别名归一化：AI 可能返回不精确的 key，统一映射到标准 key ───
   const KEY_ALIASES = {
     // description 别名
-    summary: 'description', desc: 'description', 摘要: 'description', 描述: 'description',
+    summary: 'description',
+    desc: 'description',
+    摘要: 'description',
+    描述: 'description',
     // pattern 别名
-    content: 'pattern', designPattern: 'pattern',
-    内容: 'pattern', 代码: 'pattern', 标准用法: 'pattern',
+    content: 'pattern',
+    designPattern: 'pattern',
+    内容: 'pattern',
+    代码: 'pattern',
+    标准用法: 'pattern',
     // markdown 别名
-    markdownDoc: 'markdown', Markdown文档: 'markdown', 文档: 'markdown', doc: 'markdown',
+    markdownDoc: 'markdown',
+    Markdown文档: 'markdown',
+    文档: 'markdown',
+    doc: 'markdown',
     // rationale 别名
-    design: 'rationale', 设计原理: 'rationale', 原理: 'rationale', design_rationale: 'rationale', designRationale: 'rationale',
+    design: 'rationale',
+    设计原理: 'rationale',
+    原理: 'rationale',
+    design_rationale: 'rationale',
+    designRationale: 'rationale',
     // tags 别名
-    tag: 'tags', label: 'tags', labels: 'tags', 标签: 'tags',
+    tag: 'tags',
+    label: 'tags',
+    labels: 'tags',
+    标签: 'tags',
     // confidence 别名
-    score: 'confidence', 置信度: 'confidence', 评分: 'confidence',
+    score: 'confidence',
+    置信度: 'confidence',
+    评分: 'confidence',
     // aiInsight 别名
-    ai_insight: 'aiInsight', insight: 'aiInsight', aiinsight: 'aiInsight', 洞察: 'aiInsight',
+    ai_insight: 'aiInsight',
+    insight: 'aiInsight',
+    aiinsight: 'aiInsight',
+    洞察: 'aiInsight',
     // agentNotes 别名
-    agent_notes: 'agentNotes', notes: 'agentNotes', agentnotes: 'agentNotes', 笔记: 'agentNotes',
+    agent_notes: 'agentNotes',
+    notes: 'agentNotes',
+    agentnotes: 'agentNotes',
+    笔记: 'agentNotes',
     // relations 别名
-    relation: 'relations', 关联: 'relations', 关联关系: 'relations',
+    relation: 'relations',
+    关联: 'relations',
+    关联关系: 'relations',
   };
 
-  const VALID_KEYS = new Set(['description', 'pattern', 'markdown', 'rationale', 'tags', 'confidence', 'aiInsight', 'agentNotes', 'relations']);
+  const VALID_KEYS = new Set([
+    'description',
+    'pattern',
+    'markdown',
+    'rationale',
+    'tags',
+    'confidence',
+    'aiInsight',
+    'agentNotes',
+    'relations',
+  ]);
   const normalized = {};
 
   for (const [key, value] of Object.entries(parsed)) {
@@ -317,7 +366,9 @@ function buildUpdateFromRefineResult(before, parsed) {
 
   // 确保未返回的字段保留 before 值
   for (const k of VALID_KEYS) {
-    if (!(k in normalized)) normalized[k] = before[k];
+    if (!(k in normalized)) {
+      normalized[k] = before[k];
+    }
   }
 
   const after = { ...before };
@@ -389,38 +440,49 @@ function buildUpdateFromRefineResult(before, parsed) {
  * 直接用用户提示词调用 AI 润色，返回 before/after 对比
  * Body: { candidateId: string, userPrompt: string }
  */
-router.post('/refine-preview', asyncHandler(async (req, res) => {
-  const { candidateId, userPrompt } = req.body;
-  if (!candidateId) throw new ValidationError('candidateId is required');
-  if (!userPrompt || !userPrompt.trim()) throw new ValidationError('userPrompt is required');
-
-  const container = getServiceContainer();
-  const knowledgeService = container.get('knowledgeService');
-  const aiProvider = container.get('aiProvider');
-  if (!aiProvider) throw new ValidationError('AI provider not configured');
-
-  const entry = await knowledgeService.get(candidateId);
-  if (!entry) throw new ValidationError('Candidate not found');
-  const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
-  const before = extractBeforeFields(json);
-
-  const prompt = buildRefinePrompt(before, userPrompt.trim());
-  const parsed = await aiProvider.chatWithStructuredOutput(prompt, { temperature: 0.3 });
-
-  if (!parsed) {
-    return res.json({
-      success: true,
-      data: { candidateId, before, after: before, preview: {} },
-    });
-  }
+router.post(
+  '/refine-preview',
+  asyncHandler(async (req, res) => {
+    const { candidateId, userPrompt } = req.body;
+    if (!candidateId) {
+      throw new ValidationError('candidateId is required');
+    }
+    if (!userPrompt || !userPrompt.trim()) {
+      throw new ValidationError('userPrompt is required');
+    }
 
-  const { after } = buildUpdateFromRefineResult(before, parsed);
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const aiProvider = container.get('aiProvider');
+    if (!aiProvider) {
+      throw new ValidationError('AI provider not configured');
+    }
 
-  res.json({
-    success: true,
-    data: { candidateId, before, after, preview: parsed },
-  });
-}));
+    const entry = await knowledgeService.get(candidateId);
+    if (!entry) {
+      throw new ValidationError('Candidate not found');
+    }
+    const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+    const before = extractBeforeFields(json);
+
+    const prompt = buildRefinePrompt(before, userPrompt.trim());
+    const parsed = await aiProvider.chatWithStructuredOutput(prompt, { temperature: 0.3 });
+
+    if (!parsed) {
+      return res.json({
+        success: true,
+        data: { candidateId, before, after: before, preview: {} },
+      });
+    }
+
+    const { after } = buildUpdateFromRefineResult(before, parsed);
+
+    res.json({
+      success: true,
+      data: { candidateId, before, after, preview: parsed },
+    });
+  })
+);
 
 /* ═══ 对话式润色 — 流式预览 (SSE) ═══════════════════════ */
 
@@ -436,110 +498,144 @@ router.post('/refine-preview', asyncHandler(async (req, res) => {
  *
  * Body: { candidateId: string, userPrompt: string }
  */
-router.post('/refine-preview-stream', asyncHandler(async (req, res) => {
-  const { candidateId, userPrompt } = req.body;
-  if (!candidateId) throw new ValidationError('candidateId is required');
-  if (!userPrompt || !userPrompt.trim()) throw new ValidationError('userPrompt is required');
-
-  const container = getServiceContainer();
-  const knowledgeService = container.get('knowledgeService');
-  const aiProvider = container.get('aiProvider');
-  if (!aiProvider) throw new ValidationError('AI provider not configured');
-
-  const entry = await knowledgeService.get(candidateId);
-  if (!entry) throw new ValidationError('Candidate not found');
-  const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
-  const before = extractBeforeFields(json);
-
-  // ─── Session + EventSource 架构 ───
-  const session = createStreamSession('refine');
-  const prompt = buildRefinePrompt(before, userPrompt.trim());
-
-  // 立即返回 sessionId
-  res.json({ sessionId: session.sessionId });
-
-  // 异步执行 AI 润色，通过 session 推送进度事件
-  setImmediate(async () => {
-    try {
-      // 进度事件: AI 调用开始
-      session.send({ type: 'data:progress', stage: 'ai_calling', message: 'AI 润色中...' });
-
-      // 定时进度心跳 — AI 调用是阻塞的，前端需要看到动态变化
-      const progressMsgs = [
-        { delay: 3000,  stage: 'analyzing',    message: '正在分析候选内容...' },
-        { delay: 8000,  stage: 'generating',   message: '正在生成润色建议...' },
-        { delay: 16000, stage: 'thinking',     message: 'AI 深度分析中...' },
-        { delay: 28000, stage: 'almost_done',  message: '即将完成，请稍候...' },
-      ];
-      const progressTimers = [];
-      let aiDone = false;
-      for (const pm of progressMsgs) {
-        const t = setTimeout(() => {
-          if (!aiDone) session.send({ type: 'data:progress', stage: pm.stage, message: pm.message });
-        }, pm.delay);
-        progressTimers.push(t);
-      }
-      // 超过 35 秒后每 15 秒报一次耗时
-      const longTimer = setInterval(() => {
-        if (aiDone) return;
-        const elapsed = Math.round((Date.now() - session.createdAt) / 1000);
-        session.send({ type: 'data:progress', stage: 'waiting', message: `AI 仍在处理中 (${elapsed}s)...` });
-      }, 15_000);
-      const longTimerStart = setTimeout(() => {}, 35_000); // placeholder
-      progressTimers.push(longTimerStart);
-
-      function clearProgressTimers() {
-        aiDone = true;
-        for (const t of progressTimers) clearTimeout(t);
-        clearInterval(longTimer);
-      }
+router.post(
+  '/refine-preview-stream',
+  asyncHandler(async (req, res) => {
+    const { candidateId, userPrompt } = req.body;
+    if (!candidateId) {
+      throw new ValidationError('candidateId is required');
+    }
+    if (!userPrompt || !userPrompt.trim()) {
+      throw new ValidationError('userPrompt is required');
+    }
 
-      // 使用 chatWithStructuredOutput 获取可靠的 JSON 结果（非流式），120 秒超时
-      let parsed;
-      try {
-        parsed = await Promise.race([
-          aiProvider.chatWithStructuredOutput(prompt, { temperature: 0.3 }),
-          new Promise((_, reject) => setTimeout(() => reject(new Error('AI refine timeout (120s)')), 120_000)),
-        ]);
-      } finally {
-        clearProgressTimers();
-      }
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const aiProvider = container.get('aiProvider');
+    if (!aiProvider) {
+      throw new ValidationError('AI provider not configured');
+    }
+
+    const entry = await knowledgeService.get(candidateId);
+    if (!entry) {
+      throw new ValidationError('Candidate not found');
+    }
+    const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+    const before = extractBeforeFields(json);
 
-      if (parsed) {
-        // 进度事件: 构建 diff
-        session.send({ type: 'data:progress', stage: 'building_diff', message: '生成修改对比...' });
+    // ─── Session + EventSource 架构 ───
+    const session = createStreamSession('refine');
+    const prompt = buildRefinePrompt(before, userPrompt.trim());
 
-        const { after } = buildUpdateFromRefineResult(before, parsed);
-        session.end({ candidateId, before, after, preview: parsed });
-      } else {
-        // 结构化输出失败，回退到 chat() 重试
-        session.send({ type: 'data:progress', stage: 'fallback', message: 'AI 正在重新生成...' });
-        const fullText = await aiProvider.chat(prompt, { temperature: 0.3 });
+    // 立即返回 sessionId
+    res.json({ sessionId: session.sessionId });
 
-        let fallbackParsed = null;
-        try {
-          const jsonStr = fullText.replace(/^```(?:json)?\s*\n?/m, '').replace(/\n?```\s*$/m, '').trim();
-          fallbackParsed = JSON.parse(jsonStr);
-        } catch {
-          const match = fullText.match(/\{[\s\S]*\}/);
-          if (match) {
-            try { fallbackParsed = JSON.parse(match[0]); } catch { /* ignore */ }
+    // 异步执行 AI 润色，通过 session 推送进度事件
+    setImmediate(async () => {
+      try {
+        // 进度事件: AI 调用开始
+        session.send({ type: 'data:progress', stage: 'ai_calling', message: 'AI 润色中...' });
+
+        // 定时进度心跳 — AI 调用是阻塞的，前端需要看到动态变化
+        const progressMsgs = [
+          { delay: 3000, stage: 'analyzing', message: '正在分析候选内容...' },
+          { delay: 8000, stage: 'generating', message: '正在生成润色建议...' },
+          { delay: 16000, stage: 'thinking', message: 'AI 深度分析中...' },
+          { delay: 28000, stage: 'almost_done', message: '即将完成，请稍候...' },
+        ];
+        const progressTimers = [];
+        let aiDone = false;
+        for (const pm of progressMsgs) {
+          const t = setTimeout(() => {
+            if (!aiDone) {
+              session.send({ type: 'data:progress', stage: pm.stage, message: pm.message });
+            }
+          }, pm.delay);
+          progressTimers.push(t);
+        }
+        // 超过 35 秒后每 15 秒报一次耗时
+        const longTimer = setInterval(() => {
+          if (aiDone) {
+            return;
           }
+          const elapsed = Math.round((Date.now() - session.createdAt) / 1000);
+          session.send({
+            type: 'data:progress',
+            stage: 'waiting',
+            message: `AI 仍在处理中 (${elapsed}s)...`,
+          });
+        }, 15_000);
+        const longTimerStart = setTimeout(() => {}, 35_000); // placeholder
+        progressTimers.push(longTimerStart);
+
+        function clearProgressTimers() {
+          aiDone = true;
+          for (const t of progressTimers) {
+            clearTimeout(t);
+          }
+          clearInterval(longTimer);
+        }
+
+        // 使用 chatWithStructuredOutput 获取可靠的 JSON 结果（非流式），120 秒超时
+        let parsed;
+        try {
+          parsed = await Promise.race([
+            aiProvider.chatWithStructuredOutput(prompt, { temperature: 0.3 }),
+            new Promise((_, reject) =>
+              setTimeout(() => reject(new Error('AI refine timeout (120s)')), 120_000)
+            ),
+          ]);
+        } finally {
+          clearProgressTimers();
         }
 
-        if (fallbackParsed) {
-          const { after } = buildUpdateFromRefineResult(before, fallbackParsed);
-          session.end({ candidateId, before, after, preview: fallbackParsed });
+        if (parsed) {
+          // 进度事件: 构建 diff
+          session.send({
+            type: 'data:progress',
+            stage: 'building_diff',
+            message: '生成修改对比...',
+          });
+
+          const { after } = buildUpdateFromRefineResult(before, parsed);
+          session.end({ candidateId, before, after, preview: parsed });
         } else {
-          session.end({ candidateId, before, after: before, preview: null, rawText: fullText });
+          // 结构化输出失败，回退到 chat() 重试
+          session.send({ type: 'data:progress', stage: 'fallback', message: 'AI 正在重新生成...' });
+          const fullText = await aiProvider.chat(prompt, { temperature: 0.3 });
+
+          let fallbackParsed = null;
+          try {
+            const jsonStr = fullText
+              .replace(/^```(?:json)?\s*\n?/m, '')
+              .replace(/\n?```\s*$/m, '')
+              .trim();
+            fallbackParsed = JSON.parse(jsonStr);
+          } catch {
+            const match = fullText.match(/\{[\s\S]*\}/);
+            if (match) {
+              try {
+                fallbackParsed = JSON.parse(match[0]);
+              } catch {
+                /* ignore */
+              }
+            }
+          }
+
+          if (fallbackParsed) {
+            const { after } = buildUpdateFromRefineResult(before, fallbackParsed);
+            session.end({ candidateId, before, after, preview: fallbackParsed });
+          } else {
+            session.end({ candidateId, before, after: before, preview: null, rawText: fullText });
+          }
         }
+      } catch (err) {
+        logger.warn('SSE refine-preview stream error', { error: err.message });
+        session.error(err.message, 'REFINE_ERROR');
       }
-    } catch (err) {
-      logger.warn('SSE refine-preview stream error', { error: err.message });
-      session.error(err.message, 'REFINE_ERROR');
-    }
-  });
-}));
+    });
+  })
+);
 
 /**
  * GET /api/v1/candidates/refine-preview/events/:sessionId
@@ -566,7 +662,9 @@ router.get('/refine-preview/events/:sessionId', (req, res) => {
   }
 
   function writeEvent(event) {
-    if (res.writableEnded) return;
+    if (res.writableEnded) {
+      return;
+    }
     res.write(`data: ${JSON.stringify(event)}\n\n`);
   }
 
@@ -618,79 +716,91 @@ router.get('/refine-preview/events/:sessionId', (req, res) => {
  * 若未提供 preview 则 fallback 重新调用 AI。
  * Body: { candidateId: string, userPrompt?: string, preview?: object }
  */
-router.post('/refine-apply', asyncHandler(async (req, res) => {
-  const { candidateId, userPrompt, preview } = req.body;
-  if (!candidateId) throw new ValidationError('candidateId is required');
-
-  const container = getServiceContainer();
-  const knowledgeService = container.get('knowledgeService');
-
-  const entry = await knowledgeService.get(candidateId);
-  if (!entry) throw new ValidationError('Candidate not found');
-  const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
-  const before = extractBeforeFields(json);
-
-  // 优先使用前端传回的 preview（与预览阶段完全一致），否则重新调 AI
-  let parsed = preview || null;
-  if (!parsed) {
-    if (!userPrompt || !userPrompt.trim()) {
-      throw new ValidationError('Either preview or userPrompt is required');
+router.post(
+  '/refine-apply',
+  asyncHandler(async (req, res) => {
+    const { candidateId, userPrompt, preview } = req.body;
+    if (!candidateId) {
+      throw new ValidationError('candidateId is required');
     }
-    const aiProvider = container.get('aiProvider');
-    if (!aiProvider) throw new ValidationError('AI provider not configured');
-    const prompt = buildRefinePrompt(before, userPrompt.trim());
-    parsed = await aiProvider.chatWithStructuredOutput(prompt, { temperature: 0.3 });
-  }
 
-  if (!parsed) {
-    return res.json({
-      success: true,
-      data: { refined: 0, total: 1, candidate: json },
-    });
-  }
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
 
-  const { after, updateData, changed } = buildUpdateFromRefineResult(before, parsed);
-
-  if (changed) {
-    // 处理需要嵌套写入的字段
-    const finalUpdate = { ...updateData };
-    delete finalUpdate._patternChanged;
-    delete finalUpdate._confidenceChanged;
-    delete finalUpdate._markdownChanged;
-    delete finalUpdate._rationaleChanged;
-
-    const contentPatch = { ...(json.content || {}) };
-    let contentChanged = false;
-    if (updateData._patternChanged != null) {
-      contentPatch.pattern = updateData._patternChanged;
-      contentChanged = true;
-    }
-    if (updateData._markdownChanged != null) {
-      contentPatch.markdown = updateData._markdownChanged;
-      contentChanged = true;
+    const entry = await knowledgeService.get(candidateId);
+    if (!entry) {
+      throw new ValidationError('Candidate not found');
     }
-    if (updateData._rationaleChanged != null) {
-      contentPatch.rationale = updateData._rationaleChanged;
-      contentChanged = true;
-    }
-    if (contentChanged) {
-      finalUpdate.content = contentPatch;
+    const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+    const before = extractBeforeFields(json);
+
+    // 优先使用前端传回的 preview（与预览阶段完全一致），否则重新调 AI
+    let parsed = preview || null;
+    if (!parsed) {
+      if (!userPrompt || !userPrompt.trim()) {
+        throw new ValidationError('Either preview or userPrompt is required');
+      }
+      const aiProvider = container.get('aiProvider');
+      if (!aiProvider) {
+        throw new ValidationError('AI provider not configured');
+      }
+      const prompt = buildRefinePrompt(before, userPrompt.trim());
+      parsed = await aiProvider.chatWithStructuredOutput(prompt, { temperature: 0.3 });
     }
-    if (updateData._confidenceChanged != null) {
-      finalUpdate.reasoning = { ...(json.reasoning || {}), confidence: updateData._confidenceChanged };
+
+    if (!parsed) {
+      return res.json({
+        success: true,
+        data: { refined: 0, total: 1, candidate: json },
+      });
     }
 
-    await knowledgeService.update(candidateId, finalUpdate, { userId: 'dashboard-refine' });
-  }
+    const { updateData, changed } = buildUpdateFromRefineResult(before, parsed);
+
+    if (changed) {
+      // 处理需要嵌套写入的字段
+      const finalUpdate = { ...updateData };
+      delete finalUpdate._patternChanged;
+      delete finalUpdate._confidenceChanged;
+      delete finalUpdate._markdownChanged;
+      delete finalUpdate._rationaleChanged;
+
+      const contentPatch = { ...(json.content || {}) };
+      let contentChanged = false;
+      if (updateData._patternChanged != null) {
+        contentPatch.pattern = updateData._patternChanged;
+        contentChanged = true;
+      }
+      if (updateData._markdownChanged != null) {
+        contentPatch.markdown = updateData._markdownChanged;
+        contentChanged = true;
+      }
+      if (updateData._rationaleChanged != null) {
+        contentPatch.rationale = updateData._rationaleChanged;
+        contentChanged = true;
+      }
+      if (contentChanged) {
+        finalUpdate.content = contentPatch;
+      }
+      if (updateData._confidenceChanged != null) {
+        finalUpdate.reasoning = {
+          ...(json.reasoning || {}),
+          confidence: updateData._confidenceChanged,
+        };
+      }
 
-  // 返回更新后的条目
-  const updated = changed ? await knowledgeService.get(candidateId) : entry;
-  const updatedJson = typeof updated?.toJSON === 'function' ? updated.toJSON() : updated;
+      await knowledgeService.update(candidateId, finalUpdate, { userId: 'dashboard-refine' });
+    }
 
-  res.json({
-    success: true,
-    data: { refined: changed ? 1 : 0, total: 1, candidate: updatedJson },
-  });
-}));
+    // 返回更新后的条目
+    const updated = changed ? await knowledgeService.get(candidateId) : entry;
+    const updatedJson = typeof updated?.toJSON === 'function' ? updated.toJSON() : updated;
+
+    res.json({
+      success: true,
+      data: { refined: changed ? 1 : 0, total: 1, candidate: updatedJson },
+    });
+  })
+);
 
 export default router;