autosnippet 2.19.0 → 2.19.2

package/lib/external/mcp/handlers/bootstrap.js

@@ -670,28 +670,86 @@ export async function bootstrapRefine(ctx, args) {
     onProgress?.('refine:item-started', { candidateId: entry.id, title: entry.title, current: processed, total: entries.length, progress: Math.round(((processed - 1) / entries.length) * 100) });
 
     try {
-      const prompt = `你是一位高级代码知识管理专家。请改进以下知识条目：
+      const before = {
+        title: entry.title || '',
+        description: entry.description || '',
+        pattern: entry.content?.pattern || '',
+        markdown: entry.content?.markdown || '',
+        rationale: entry.content?.rationale || '',
+        tags: entry.tags || [],
+        confidence: entry.reasoning?.confidence ?? 0.6,
+        relations: entry.relations || {},
+        aiInsight: entry.aiInsight || null,
+        agentNotes: entry.agentNotes || null,
+      };
+
+      const refineInstruction = args.userPrompt
+        ? args.userPrompt
+        : '请改善描述使其更专业简洁，补充高阶架构洞察，如缺少关联关系请推断补充';
+
+      const prompt = `你是一位高级代码知识管理专家。请改进以下知识条目。
+
+## ⭐ JSON key 规范（最高优先级）
+
+返回的 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）
+
+## 当前条目信息
+
+标题: ${before.title}
+类型: ${entry.knowledgeType || '未知'}
+语言: ${entry.language || '未知'}
+
+【description】摘要
+${before.description || '（空）'}
+
+【pattern】代码/标准用法
+${(before.pattern || '（空）').substring(0, 2000)}
 
-标题: ${entry.title}
-类型: ${entry.knowledgeType}
-语言: ${entry.language}
-描述: ${entry.description || ''}
-代码:
-\`\`\`
-${(entry.content?.pattern || '').substring(0, 2000)}
-\`\`\`
+【markdown】Markdown 文档
+${(before.markdown || '（空）').substring(0, 2000)}
+
+【rationale】设计原理
+${before.rationale || '（空）'}
+
+【tags】标签
+${JSON.stringify(before.tags)}
+
+【confidence】置信度
+${before.confidence}
+
+【relations】关联关系
+${JSON.stringify(before.relations)}
+
+【aiInsight】AI 洞察
+${before.aiInsight || '（空）'}
+
+【agentNotes】Agent 笔记
+${JSON.stringify(before.agentNotes || [])}
 
 同批次知识: ${allTitles.slice(0, 20).join(', ')}
-${args.userPrompt ? `用户补充: ${args.userPrompt}` : ''}
 
-请返回 JSON:
-{
-  "summary": "改进后的中文摘要",
-  "tags": ["建议标签"],
-  "relations": [{"target":"相关条目标题","relation":"depends_on|extends|related_to"}],
-  "confidence": 0.0-1.0,
-  "insight": "架构洞察（一句话）"
-}`;
+## 润色指令
+
+${refineInstruction}
+
+## 约束
+
+1. 只修改需要改进的字段，未涉及的必须原样返回。
+2. tags 采用合并策略（保留原有 + 补充新建议），不要删除已有标签。
+3. relations 为 object 格式，key 为关系类型（如 inherits/implements/calls/depends_on/extends/related），value 为 string[]。
+4. 每个 key 都必须存在，key 名称必须与上述完全一致。
+
+仅返回 JSON，不要添加任何其他文字或代码块标记。`;
 
       const parsed = await aiProvider.chatWithStructuredOutput(prompt, { temperature: 0.3 });
 
@@ -707,27 +765,86 @@ ${args.userPrompt ? `用户补充: ${args.userPrompt}` : ''}
         continue;
       }
 
+      // ─── key 别名归一化（与 candidates.js 保持一致） ───
+      const KEY_ALIASES = {
+        summary: 'description', desc: 'description',
+        content: 'pattern', design: 'rationale', designRationale: 'rationale',
+        markdownDoc: 'markdown', doc: 'markdown',
+        tag: 'tags', label: 'tags', labels: 'tags',
+        score: 'confidence',
+        ai_insight: 'aiInsight', insight: 'aiInsight', aiinsight: 'aiInsight',
+        agent_notes: 'agentNotes', notes: 'agentNotes', agentnotes: 'agentNotes',
+        relation: '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;
+        }
+      }
+      for (const k of VALID_KEYS) {
+        if (!(k in normalized)) normalized[k] = before[k];
+      }
+
       // 构建更新数据
       const updateData = {};
       let changed = false;
 
-      if (parsed.summary && parsed.summary !== entry.description) {
-        updateData.description = parsed.summary;
+      if (normalized.description != null && normalized.description !== before.description) {
+        updateData.description = normalized.description;
         changed = true;
       }
-      if (parsed.tags && Array.isArray(parsed.tags)) {
-        const merged = [...new Set([...(entry.tags || []), ...parsed.tags])];
-        if (merged.length > (entry.tags || []).length) {
+      // tags 采用合并策略
+      if (normalized.tags != null && Array.isArray(normalized.tags)) {
+        const merged = [...new Set([...(before.tags || []), ...normalized.tags])];
+        if (JSON.stringify(merged) !== JSON.stringify(before.tags)) {
           updateData.tags = merged;
           changed = true;
         }
       }
-      if (typeof parsed.confidence === 'number' && parsed.confidence !== 0.6) {
-        updateData.reasoning = { ...(entry.reasoning || {}), confidence: parsed.confidence };
+      if (typeof normalized.confidence === 'number' && normalized.confidence !== before.confidence) {
+        updateData.reasoning = { ...(entry.reasoning || {}), confidence: normalized.confidence };
+        changed = true;
+      }
+      if (normalized.aiInsight != null && normalized.aiInsight !== before.aiInsight) {
+        updateData.aiInsight = normalized.aiInsight;
         changed = true;
       }
-      if (parsed.insight) {
-        updateData.description = `${entry.description || ''}\n\n**AI Insight**: ${parsed.insight}`.trim();
+      if (normalized.agentNotes !== undefined) {
+        const newNotes = JSON.stringify(normalized.agentNotes);
+        if (newNotes !== JSON.stringify(before.agentNotes)) {
+          updateData.agentNotes = normalized.agentNotes;
+          changed = true;
+        }
+      }
+      if (normalized.relations !== undefined) {
+        const newRels = JSON.stringify(normalized.relations);
+        if (newRels !== JSON.stringify(before.relations)) {
+          updateData.relations = normalized.relations;
+          changed = true;
+        }
+      }
+      // content 嵌套写入
+      const contentPatch = { ...(entry.content || {}) };
+      let contentChanged = false;
+      if (normalized.pattern != null && normalized.pattern !== before.pattern) {
+        contentPatch.pattern = normalized.pattern;
+        contentChanged = true;
+      }
+      if (normalized.markdown != null && normalized.markdown !== before.markdown) {
+        contentPatch.markdown = normalized.markdown;
+        contentChanged = true;
+      }
+      if (normalized.rationale != null && normalized.rationale !== before.rationale) {
+        contentPatch.rationale = normalized.rationale;
+        contentChanged = true;
+      }
+      if (contentChanged) {
+        updateData.content = contentPatch;
         changed = true;
       }
 

package/lib/http/HttpServer.js

@@ -178,10 +178,11 @@ export class HttpServer {
     // Gateway 中间件 (注入 req.gw)
     this.app.use(gatewayMiddleware());
 
-    // 请求超时设置（AI 扫描类路由需要更长时间）
+    // 请求超时设置（AI 扫描类路由需要更长时间，SSE 流式路由需要更长时间）
     this.app.use((req, res, next) => {
       const isLongRunning = req.path.includes('/spm/scan') || req.path.includes('/spm/bootstrap') || req.path.includes('/extract/');
-      req.setTimeout(isLongRunning ? 600000 : 60000); // AI 扫描/冷启动 10分钟，其他 60秒
+      const isStreaming = req.path.includes('/stream') || req.path.includes('/events/');
+      req.setTimeout(isLongRunning ? 600000 : isStreaming ? 300000 : 60000); // AI 扫描 10分钟, SSE/EventSource 5分钟, 其他 60秒
       next();
     });
   }

package/lib/http/routes/ai.js

@@ -11,6 +11,7 @@ import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { createProvider } from '../../external/ai/AiFactory.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();
@@ -399,6 +400,137 @@ router.post('/env-config', asyncHandler(async (req, res) => {
   res.json({ success: true, data: result });
 }));
 
+// ═══════════════════════════════════════════════════════
+//  SSE Streaming — 流式对话（Session + EventSource 架构）
+// ═══════════════════════════════════════════════════════
+
+/**
+ * POST /api/v1/ai/chat/stream
+ * 启动 AI 对话流 — 创建 session，后台执行 ChatAgent，立即返回 sessionId
+ *
+ * 客户端拿到 sessionId 后通过 GET /chat/events/:sessionId (EventSource) 消费事件
+ *
+ * 协议事件（通过 session 缓冲 + EventSource 交付）:
+ *   step:start    — 新推理步骤开始 {step, maxSteps, phase}
+ *   step:end      — 推理步骤结束 {step}
+ *   tool:start    — 工具调用开始 {id, tool, args}
+ *   tool:end      — 工具调用结束 {tool, status, resultSize?, duration?, error?}
+ *   text:start    — 文本流开始 {id, role}
+ *   text:delta    — 文本分块 {id, delta}
+ *   text:end      — 文本流结束 {id}
+ *   stream:done   — 会话完成 {text, toolCalls, hasContext}
+ *   stream:error  — 会话错误 {message}
+ *
+ * Body: { prompt: string, history?: Array<{role,content}> }
+ * Response: { success: true, sessionId: string }
+ */
+router.post('/chat/stream', asyncHandler(async (req, res) => {
+  const { prompt, history = [] } = req.body;
+  if (!prompt) throw new ValidationError('prompt is required');
+
+  const chatAgent = getChatAgent();
+  const session = createStreamSession('chat');
+
+  logger.debug('SSE session created', { sessionId: session.sessionId });
+
+  // 立即返回 sessionId（不等待 ChatAgent 执行）
+  res.json({ success: true, sessionId: session.sessionId });
+
+  // 后台执行 ChatAgent — 事件通过 session.send() 缓冲
+  chatAgent.execute(prompt, {
+    history,
+    onProgress: (event) => session.send(event),
+  }).then(result => {
+    // text:start/delta/end 已由 ChatAgent.execute() 内部通过 onProgress 发送
+    session.end({
+      text: result.reply,
+      toolCalls: result.toolCalls || [],
+      hasContext: result.hasContext || false,
+    });
+    logger.debug('SSE session completed', { sessionId: session.sessionId, events: session.buffer.length });
+  }).catch(err => {
+    logger.warn('SSE session error', { sessionId: session.sessionId, error: err.message });
+    session.error(err.message);
+  });
+}));
+
+/**
+ * GET /api/v1/ai/chat/events/:sessionId
+ * EventSource SSE 端点 — 消费指定 session 的实时事件
+ *
+ * 流程:
+ *   1. 回放 session 缓冲区中已积累的所有事件
+ *   2. 如果 session 已完成 → 直接结束流
+ *   3. 否则订阅实时事件，直到 stream:done / stream:error
+ *
+ * 使用原生 EventSource API 消费（浏览器内置 SSE 支持，无缓冲问题）
+ */
+router.get('/chat/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);
+  }
+
+  /** 写入一个 SSE data 行 */
+  function writeEvent(event) {
+    if (res.writableEnded) return;
+    const line = `data: ${JSON.stringify(event)}\n\n`;
+    res.write(line);
+  }
+
+  // 1) 回放缓冲区
+  let isDone = false;
+  for (const event of session.buffer) {
+    writeEvent(event);
+    if (event.type === 'stream:done' || event.type === 'stream:error') {
+      isDone = true;
+    }
+  }
+
+  // 2) 如果已完成，直接关闭
+  if (isDone || session.completed) {
+    res.end();
+    return;
+  }
+
+  // 3) 订阅实时事件
+  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);
+  });
+});
+
 /**
  * GET /api/v1/ai/token-usage
  * 近 7 日 Token 消耗报告（按日 + 按来源 + 总计）