autosnippet 2.19.0 → 2.19.2

package/lib/http/routes/candidates.js

@@ -8,6 +8,7 @@ import { asyncHandler } from '../middleware/errorHandler.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { ValidationError } from '../../shared/errors/index.js';
 import Logger from '../../infrastructure/logging/Logger.js';
+import { createStreamSession, getStreamSession } from '../utils/sse-sessions.js';
 
 const router = express.Router();
 const logger = Logger.getInstance();
@@ -67,24 +68,45 @@ router.post('/enrich', asyncHandler(async (req, res) => {
   const results = [];
 
   if (aiProvider) {
+    let enriched = [];
     try {
-      const enriched = await aiProvider.enrichCandidates(candidates);
-      for (const item of enriched) {
-        const idx = item.index ?? 0;
-        const cand = candidates[idx];
-        if (!cand) continue;
+      enriched = await aiProvider.enrichCandidates(candidates);
+    } catch (err) {
+      logger.warn('AI enrichCandidates failed', { error: err.message });
+    }
+
+    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;
 
+      try {
         const updateData = {};
         let changed = false;
 
-        if (item.rationale && !cand.rationale) {
-          updateData['content.rationale'] = item.rationale;
-          // 需要合并到 content 对象
+        // 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;
-          updateData.content = { ...(json.content || {}), rationale: item.rationale };
+          contentBase = { ...(json.content || {}) };
+        }
+
+        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;
@@ -97,12 +119,6 @@ router.post('/enrich', asyncHandler(async (req, res) => {
           updateData.scope = item.scope;
           changed = true;
         }
-        if (item.steps && (!cand.steps || cand.steps.length === 0)) {
-          const entry = await knowledgeService.get(cand.id);
-          const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
-          updateData.content = { ...(json.content || {}), ...(updateData.content || {}), steps: item.steps };
-          changed = true;
-        }
         if (item.constraints && !cand.constraints?.preconditions?.length) {
           updateData.constraints = item.constraints;
           changed = true;
@@ -113,9 +129,10 @@ router.post('/enrich', asyncHandler(async (req, res) => {
           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 });
       }
-    } catch (err) {
-      logger.warn('AI enrichCandidates failed', { error: err.message });
     }
   }
 
@@ -142,9 +159,8 @@ router.post('/bootstrap-refine', asyncHandler(async (req, res) => {
   const ctx = { container, logger };
   const result = await bootstrapRefine(ctx, { candidateIds, userPrompt, dryRun });
 
-  const data = result?.data || result?.content?.[0]?.text
-    ? JSON.parse(result.content[0].text)?.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 });
 }));
@@ -160,6 +176,8 @@ function extractBeforeFields(json) {
     title: json.title || '',
     description: json.description || '',
     pattern: json.content?.pattern || '',
+    markdown: json.content?.markdown || '',
+    rationale: json.content?.rationale || '',
     tags: json.tags || [],
     confidence: json.reasoning?.confidence ?? 0.6,
     relations: json.relations || {},
@@ -177,41 +195,63 @@ function extractBeforeFields(json) {
 function buildRefinePrompt(before, userPrompt) {
   return `你是一位知识库条目润色助手。你必须**严格按照用户指令**修改知识条目。
 
-## 可修改字段（字段名 → UI 名称）
+## ⭐ JSON key 规范（最高优先级）
 
-| JSON key      | UI 标签   | 说明                     |
-|---------------|-----------|--------------------------|
-| description   | 摘要       | 条目的简要概述             |
-| pattern       | 内容文档 / 设计原理 | 条目的详细内容、代码模式、设计原理 |
-| tags          | 标签       | 分类标签数组               |
-| confidence    | 置信度     | 0.0-1.0 的评分            |
-| aiInsight     | AI 洞察    | AI 生成的架构洞察           |
-| agentNotes    | Agent 笔记 | Agent 生成的笔记           |
-| relations     | 关联关系   | 与其他条目的关系            |
+返回的 JSON 必须且只能使用以下 9 个 key，大小写必须完全一致：
+
+  description  → 摘要（string）
+  pattern      → 代码/标准用法（string）
+  markdown     → Markdown 文档（string）
+  rationale    → 设计原理（string）
+  tags         → 标签（string[]）
+  confidence   → 置信度（number 0.0–1.0）
+  aiInsight    → AI 洞察（string | null）
+  agentNotes   → Agent 笔记（string[] | null）
+  relations    → 关联关系（object）
+
+禁止使用其他 key。不允许用 content/summary/insight/notes/title 等替代名。
+
+## 字段与 UI 子标题的对应关系
+
+用户输入的指令可能使用 UI 上显示的子标题名称，对应规则如下：
+- “摘要”“描述” → description
+- “代码”“标准用法”“代码/标准用法” → pattern
+- “Markdown 文档”“markdown” → markdown
+- “设计原理”“原理” → rationale
+- “标签” → tags
+- “AI 洞察” → aiInsight
+- “Agent 笔记” → agentNotes
+- “关联关系” → relations
 
 ## 当前条目信息
 
 标题: ${before.title}
 
-【摘要 / description】
+【description】摘要
 ${before.description || '（空）'}
 
-【内容文档 / pattern】
+【pattern】代码/标准用法
 ${(before.pattern || '（空）').substring(0, 3000)}
 
-【标签 / tags】
+【markdown】Markdown 文档
+${(before.markdown || '（空）').substring(0, 3000)}
+
+【rationale】设计原理
+${before.rationale || '（空）'}
+
+【tags】标签
 ${JSON.stringify(before.tags)}
 
-【置信度 / confidence】
+【confidence】置信度
 ${before.confidence}
 
-【关联关系 / relations】
+【relations】关联关系
 ${JSON.stringify(before.relations)}
 
-【AI 洞察 / aiInsight】
+【aiInsight】AI 洞察
 ${before.aiInsight || '（空）'}
 
-【Agent 笔记 / agentNotes】
+【agentNotes】Agent 笔记
 ${JSON.stringify(before.agentNotes || [])}
 
 ## 用户指令
@@ -220,74 +260,121 @@ ${userPrompt}
 
 ## 严格约束
 
-1. **只修改用户指令明确提到的字段**。用户说"设计原理"或"内容"指 pattern 字段，说"摘要"或"描述"指 description 字段。
-2. **未提及的字段必须原样返回**，不得做任何改写、改善、优化或翻译。
-3. 如果你不确定用户指的是哪个字段，优先修改 pattern（内容文档）。
-
-请返回 JSON（所有字段都必须包含）：
-{
-  "description": "原样或修改后的摘要",
-  "pattern": "原样或修改后的内容文档",
-  "tags": ["原样或修改后的标签数组"],
-  "confidence": 原样或修改后的数字,
-  "aiInsight": "原样或修改后的AI洞察 或 null",
-  "agentNotes": ["原样或修改后的笔记数组"] 或 null,
-  "relations": {原样或修改后的关联关系}
-}
+1. **只修改用户指令涉及的字段**。参考上方“字段与 UI 子标题的对应关系”识别用户指的是哪个字段。
+2. **未涉及的字段必须原样返回**，不得做任何改写、改善、优化或翻译。
+3. 如果不确定用户指的是哪个字段，优先修改 description（摘要）、pattern（代码）、markdown（文档）、rationale（设计原理）。
+4. **翻译/语言转换类指令**（如“翻译为中文”): 翻译 description、pattern、markdown、rationale、aiInsight、agentNotes 等文本字段，但 tags/relations/confidence 保持原样。
+5. **tags 和 relations** 只在用户明确提及“标签”或“关联”时才修改，其他情况一律原样返回。
+
+## 输出格式
 
-仅返回 JSON，不要添加其他文字。`;
+返回严格符合以下结构的 JSON，不要添加任何其他文字或代码块标记：
+{"description": "...", "pattern": "...", "markdown": "...", "rationale": "...", "tags": [...], "confidence": 0.6, "aiInsight": "...or null", "agentNotes": ["..."] or null, "relations": {...}}
+
+每个 key 都必须存在，key 名称必须与上述完全一致。`;
 }
 
 /**
  * 将 AI 返回的润色结果合并到 before 上生成 after，并构造 knowledgeService.update() 所需的 updateData
  */
 function buildUpdateFromRefineResult(before, parsed) {
+  // ─── key 别名归一化：AI 可能返回不精确的 key，统一映射到标准 key ───
+  const KEY_ALIASES = {
+    // description 别名
+    summary: 'description', desc: 'description', 摘要: 'description', 描述: 'description',
+    // pattern 别名
+    content: 'pattern', designPattern: 'pattern',
+    内容: 'pattern', 代码: 'pattern', 标准用法: 'pattern',
+    // markdown 别名
+    markdownDoc: 'markdown', Markdown文档: 'markdown', 文档: 'markdown', doc: 'markdown',
+    // rationale 别名
+    design: 'rationale', 设计原理: 'rationale', 原理: 'rationale', design_rationale: 'rationale', designRationale: 'rationale',
+    // tags 别名
+    tag: 'tags', label: 'tags', labels: 'tags', 标签: 'tags',
+    // confidence 别名
+    score: 'confidence', 置信度: 'confidence', 评分: 'confidence',
+    // aiInsight 别名
+    ai_insight: 'aiInsight', insight: 'aiInsight', aiinsight: 'aiInsight', 洞察: 'aiInsight',
+    // agentNotes 别名
+    agent_notes: 'agentNotes', notes: 'agentNotes', agentnotes: 'agentNotes', 笔记: 'agentNotes',
+    // relations 别名
+    relation: 'relations', 关联: 'relations', 关联关系: '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)) {
+    if (VALID_KEYS.has(key)) {
+      normalized[key] = value;
+    } else {
+      const mapped = KEY_ALIASES[key] || KEY_ALIASES[key.toLowerCase()];
+      if (mapped && !(mapped in normalized)) {
+        normalized[mapped] = value;
+      }
+    }
+  }
+
+  // 确保未返回的字段保留 before 值
+  for (const k of VALID_KEYS) {
+    if (!(k in normalized)) normalized[k] = before[k];
+  }
+
   const after = { ...before };
   const updateData = {};
   let changed = false;
 
-  if (parsed.description != null && parsed.description !== before.description) {
-    after.description = parsed.description;
-    updateData.description = parsed.description;
+  if (normalized.description != null && normalized.description !== before.description) {
+    after.description = normalized.description;
+    updateData.description = normalized.description;
     changed = true;
   }
-  if (parsed.pattern != null && parsed.pattern !== before.pattern) {
-    after.pattern = parsed.pattern;
-    // pattern 需要写入 content.pattern
-    updateData._patternChanged = parsed.pattern;
+  if (normalized.pattern != null && normalized.pattern !== before.pattern) {
+    after.pattern = normalized.pattern;
+    updateData._patternChanged = normalized.pattern;
     changed = true;
   }
-  if (parsed.tags != null && Array.isArray(parsed.tags)) {
-    const newTags = JSON.stringify(parsed.tags);
+  if (normalized.markdown != null && normalized.markdown !== before.markdown) {
+    after.markdown = normalized.markdown;
+    updateData._markdownChanged = normalized.markdown;
+    changed = true;
+  }
+  if (normalized.rationale != null && normalized.rationale !== before.rationale) {
+    after.rationale = normalized.rationale;
+    updateData._rationaleChanged = normalized.rationale;
+    changed = true;
+  }
+  if (normalized.tags != null && Array.isArray(normalized.tags)) {
+    const newTags = JSON.stringify(normalized.tags);
     if (newTags !== JSON.stringify(before.tags)) {
-      after.tags = parsed.tags;
-      updateData.tags = parsed.tags;
+      after.tags = normalized.tags;
+      updateData.tags = normalized.tags;
       changed = true;
     }
   }
-  if (typeof parsed.confidence === 'number' && parsed.confidence !== before.confidence) {
-    after.confidence = parsed.confidence;
-    updateData._confidenceChanged = parsed.confidence;
+  if (typeof normalized.confidence === 'number' && normalized.confidence !== before.confidence) {
+    after.confidence = normalized.confidence;
+    updateData._confidenceChanged = normalized.confidence;
     changed = true;
   }
-  if (parsed.aiInsight !== undefined && parsed.aiInsight !== before.aiInsight) {
-    after.aiInsight = parsed.aiInsight;
-    updateData.aiInsight = parsed.aiInsight;
+  if (normalized.aiInsight !== undefined && normalized.aiInsight !== before.aiInsight) {
+    after.aiInsight = normalized.aiInsight;
+    updateData.aiInsight = normalized.aiInsight;
     changed = true;
   }
-  if (parsed.agentNotes !== undefined) {
-    const newNotes = JSON.stringify(parsed.agentNotes);
+  if (normalized.agentNotes !== undefined) {
+    const newNotes = JSON.stringify(normalized.agentNotes);
     if (newNotes !== JSON.stringify(before.agentNotes)) {
-      after.agentNotes = parsed.agentNotes;
-      updateData.agentNotes = parsed.agentNotes;
+      after.agentNotes = normalized.agentNotes;
+      updateData.agentNotes = normalized.agentNotes;
       changed = true;
     }
   }
-  if (parsed.relations !== undefined) {
-    const newRels = JSON.stringify(parsed.relations);
+  if (normalized.relations !== undefined) {
+    const newRels = JSON.stringify(normalized.relations);
     if (newRels !== JSON.stringify(before.relations)) {
-      after.relations = parsed.relations;
-      updateData.relations = parsed.relations;
+      after.relations = normalized.relations;
+      updateData.relations = normalized.relations;
       changed = true;
     }
   }
@@ -335,6 +422,194 @@ router.post('/refine-preview', asyncHandler(async (req, res) => {
   });
 }));
 
+/* ═══ 对话式润色 — 流式预览 (SSE) ═══════════════════════ */
+
+/**
+ * POST /api/v1/candidates/refine-preview-stream
+ * 润色预览 — 统一 SSE 协议，使用 chatWithStructuredOutput 获取可靠结构化结果
+ *
+ * 不再流式推送 JSON 碎片。改为：
+ *   stream:start        — 会话开始
+ *   data:progress       — AI 润色进度（前端展示进度条/加载动画）
+ *   stream:done         — 完成，携带 before/after/preview
+ *   stream:error        — 错误
+ *
+ * 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);
+      }
+
+      // 使用 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 (parsed) {
+        // 进度事件: 构建 diff
+        session.send({ type: 'data:progress', stage: 'building_diff', message: '生成修改对比...' });
+
+        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 });
+
+        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');
+    }
+  });
+}));
+
+/**
+ * GET /api/v1/candidates/refine-preview/events/:sessionId
+ * EventSource SSE 端点 — 消费润色预览进度事件
+ *
+ * 复用 scan/events 相同的 SSE 交付模式：回放缓冲 → 订阅实时 → 心跳保活
+ */
+router.get('/refine-preview/events/:sessionId', (req, res) => {
+  const session = getStreamSession(req.params.sessionId);
+  if (!session) {
+    return res.status(404).json({ success: false, error: 'Session not found or expired' });
+  }
+
+  // ─── SSE Headers ───
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  res.setHeader('X-Accel-Buffering', 'no');
+  res.flushHeaders();
+
+  if (res.socket) {
+    res.socket.setNoDelay(true);
+    res.socket.setTimeout(0);
+  }
+
+  function writeEvent(event) {
+    if (res.writableEnded) return;
+    res.write(`data: ${JSON.stringify(event)}\n\n`);
+  }
+
+  // 1) 回放缓冲区
+  let isDone = false;
+  for (const event of session.buffer) {
+    writeEvent(event);
+    if (event.type === 'stream:done' || event.type === 'stream:error') {
+      isDone = true;
+    }
+  }
+
+  if (isDone || session.completed) {
+    res.end();
+    return;
+  }
+
+  // 2) 订阅实时事件
+  const unsubscribe = session.on((event) => {
+    writeEvent(event);
+    if (event.type === 'stream:done' || event.type === 'stream:error') {
+      unsubscribe();
+      clearInterval(heartbeat);
+      res.end();
+    }
+  });
+
+  // 心跳保活 (每 15 秒)
+  const heartbeat = setInterval(() => {
+    if (res.writableEnded) {
+      clearInterval(heartbeat);
+      return;
+    }
+    res.write(`: ping ${Date.now()}\n\n`);
+  }, 15_000);
+
+  // 客户端断开连接时清理
+  res.on('close', () => {
+    unsubscribe();
+    clearInterval(heartbeat);
+  });
+});
+
 /* ═══ 对话式润色 — 应用 ══════════════════════════════════ */
 
 /**
@@ -381,9 +656,25 @@ router.post('/refine-apply', asyncHandler(async (req, res) => {
     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) {
-      finalUpdate.content = { ...(json.content || {}), pattern: updateData._patternChanged };
+      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 };