autosnippet 2.19.0 → 2.19.2

package/lib/http/routes/spm.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();
@@ -177,6 +178,148 @@ router.post('/scan', asyncHandler(async (req, res) => {
   });
 }));
 
+// ── 流式 Target 扫描（SSE Session + EventSource 架构） ─────────
+
+/**
+ * POST /api/v1/spm/scan/stream
+ * 创建流式扫描会话，后台异步执行 AI 扫描
+ *
+ * 协议事件（通过 SSE session 缓冲 + EventSource 交付）:
+ *   scan:started       — 扫描启动
+ *   scan:files-loaded   — 文件列表就绪，含 files[] + count
+ *   scan:reading        — 读取文件内容中
+ *   scan:ai-extracting  — AI 提取开始（耗时阶段）
+ *   scan:enriching      — 后处理阶段
+ *   scan:completed      — 最终结果 {recipes, scannedFiles, recipeCount, fileCount}
+ *   scan:error          — 发生错误
+ *   stream:done         — 会话结束标记
+ */
+router.post('/scan/stream', asyncHandler(async (req, res) => {
+  const { target, targetName, options = {} } = req.body;
+
+  if (!target && !targetName) {
+    throw new ValidationError('target object or targetName is required');
+  }
+
+  const container = getServiceContainer();
+  const spmService = container.get('spmService');
+
+  let resolvedTarget = target;
+  if (!resolvedTarget && targetName) {
+    const targets = await spmService.listTargets();
+    resolvedTarget = targets.find(t => t.name === targetName);
+    if (!resolvedTarget) {
+      return res.status(404).json({
+        success: false,
+        error: { code: 'NOT_FOUND', message: `Target not found: ${targetName}` },
+      });
+    }
+  }
+
+  // 创建 SSE session
+  const session = createStreamSession('scan');
+  const tName = resolvedTarget.name || targetName;
+
+  // 立即返回 sessionId
+  res.json({ sessionId: session.sessionId });
+
+  // 异步执行扫描，通过 session 推送进度事件
+  setImmediate(async () => {
+    try {
+      logger.info('SPM stream scan started', { target: tName, sessionId: session.sessionId });
+      const result = await spmService.scanTarget(resolvedTarget, {
+        ...options,
+        onProgress(event) {
+          session.send(event);
+        },
+      });
+
+      // 发送最终结果
+      session.send({
+        type: 'scan:result',
+        recipes: result.recipes || [],
+        scannedFiles: result.scannedFiles || [],
+        message: result.message || '',
+        recipeCount: (result.recipes || []).length,
+        fileCount: (result.scannedFiles || []).length,
+      });
+      session.end();
+    } catch (err) {
+      logger.error('SPM stream scan failed', { target: tName, error: err.message });
+      session.error(err.message, 'SCAN_ERROR');
+    }
+  });
+}));
+
+/**
+ * GET /api/v1/spm/scan/events/:sessionId
+ * EventSource SSE 端点 — 消费扫描进度事件
+ *
+ * 复用 chat/events 相同的 SSE 交付模式：回放缓冲 → 订阅实时 → 心跳保活
+ */
+router.get('/scan/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);
+  });
+});
+
 /**
  * POST /api/v1/spm/scan-project
  * 全项目扫描：AI 提取候选 + Guard 审计

package/lib/http/utils/sse-sessions.js

@@ -0,0 +1,114 @@
+/**
+ * SSE Session Manager — 基于 EventSource 的流式会话管理
+ *
+ * 架构:
+ *   POST /chat/stream → 创建 session + 后台执行 ChatAgent → 返回 { sessionId }
+ *   GET  /chat/events/:sessionId → EventSource 端点, 回放缓冲事件 + 实时推送
+ *
+ * 为什么不用 fetch + ReadableStream:
+ *   Chrome/Safari 的 fetch() streaming 会缓冲初始响应体（~1-4KB），导致小体积
+ *   SSE 事件滞留在缓冲区中不被交付给 ReadableStream reader。
+ *   原生 EventSource API 是浏览器专门为 SSE 优化的消费者，不受此限制。
+ *
+ * @module lib/http/utils/sse-sessions
+ */
+
+import { EventEmitter } from 'events';
+
+/** @type {Map<string, StreamSession>} */
+const _sessions = new Map();
+
+/** Session 自动清理 TTL (5 分钟) */
+const SESSION_TTL = 5 * 60 * 1000;
+
+/** 完成后保留时间 (60 秒, 供客户端重连回放) */
+const COMPLETED_KEEP = 60 * 1000;
+
+/**
+ * 创建一个 stream session
+ *
+ * @param {'chat'|'refine'} scene 场景标识
+ * @returns {StreamSession}
+ */
+export function createStreamSession(scene) {
+  const sessionId = `ss_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+  const emitter = new EventEmitter();
+  emitter.setMaxListeners(20);
+
+  const session = {
+    sessionId,
+    scene,
+    /** @type {Array<object>} 事件缓冲区（供 EventSource 连接后回放） */
+    buffer: [],
+    /** 会话是否已结束 */
+    completed: false,
+    createdAt: Date.now(),
+
+    /**
+     * 缓冲 + 广播一个事件
+     * @param {object} event — 必须包含 type 字段
+     */
+    send(event) {
+      const payload = { ...event, ts: event.ts || Date.now() };
+      session.buffer.push(payload);
+      emitter.emit('event', payload);
+    },
+
+    /**
+     * 标记会话完成，发送 stream:done
+     * @param {object} [donePayload={}]
+     */
+    end(donePayload = {}) {
+      if (session.completed) return;
+      const payload = { type: 'stream:done', ts: Date.now(), ...donePayload };
+      session.buffer.push(payload);
+      emitter.emit('event', payload);
+      session.completed = true;
+      // 完成后保留一段时间供客户端重连
+      const keepTimer = setTimeout(() => _sessions.delete(sessionId), COMPLETED_KEEP);
+      if (keepTimer.unref) keepTimer.unref();
+    },
+
+    /**
+     * 标记会话错误，发送 stream:error
+     * @param {string} message
+     * @param {string} [code]
+     */
+    error(message, code) {
+      if (session.completed) return;
+      const payload = { type: 'stream:error', ts: Date.now(), message, code };
+      session.buffer.push(payload);
+      emitter.emit('event', payload);
+      session.completed = true;
+      const keepTimer = setTimeout(() => _sessions.delete(sessionId), COMPLETED_KEEP);
+      if (keepTimer.unref) keepTimer.unref();
+    },
+
+    /**
+     * 订阅实时事件
+     * @param {(event: object) => void} handler
+     * @returns {() => void} unsubscribe 函数
+     */
+    on(handler) {
+      emitter.on('event', handler);
+      return () => emitter.removeListener('event', handler);
+    },
+  };
+
+  _sessions.set(sessionId, session);
+
+  // 硬性 TTL: 无论是否完成，5 分钟后强制清理
+  const ttlTimer = setTimeout(() => _sessions.delete(sessionId), SESSION_TTL);
+  if (ttlTimer.unref) ttlTimer.unref();
+
+  return session;
+}
+
+/**
+ * 获取已有的 session
+ * @param {string} sessionId
+ * @returns {StreamSession|undefined}
+ */
+export function getStreamSession(sessionId) {
+  return _sessions.get(sessionId);
+}

package/lib/http/utils/sse.js

@@ -0,0 +1,128 @@
+/**
+ * SSE (Server-Sent Events) 会话工具模块
+ *
+ * 提供统一的 SSE 连接管理：headers 设置、心跳保活、安全写入、生命周期事件。
+ * 所有 SSE 端点共用此模块，确保协议一致性。
+ *
+ * @module lib/http/utils/sse
+ */
+
+/**
+ * 创建 SSE 会话 — 统一设置 headers、心跳、安全写入
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {'chat'|'refine'} scene — 场景标识
+ * @returns {{ send, end, error, isDisconnected, sessionId }}
+ */
+export function createSSESession(req, res, scene) {
+  // ─── 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();
+
+  // ─── 禁用 Nagle 算法，确保 SSE 小包即时发送 ───
+  if (res.socket) {
+    res.socket.setNoDelay(true);
+    res.socket.setTimeout(0);
+  }
+
+  let disconnected = false;
+
+  // 注意：必须监听 res.on('close') 而非 req.on('close')。
+  // 在 Node.js 20 中，IncomingMessage (req) 的 'close' 事件在请求体被消费后即触发，
+  // 而 ServerResponse (res) 的 'close' 事件仅在底层 socket 关闭时触发（即客户端真正断开连接）。
+  res.on('close', () => {
+    disconnected = true;
+  });
+
+  const sessionId = Math.random().toString(36).slice(2, 10);
+
+  /** 安全写入一段 SSE 数据 */
+  function _write(data) {
+    if (disconnected || res.writableEnded) return false;
+    try {
+      return res.write(data);
+    } catch {
+      disconnected = true;
+      return false;
+    }
+  }
+
+  // ─── 心跳 (每 15 秒发送 SSE 注释保活) ───
+  const heartbeat = setInterval(() => {
+    _write(`: ping ${Date.now()}\n\n`);
+  }, 15_000);
+
+  // ─── 发送 stream:start ───
+  const startPayload = JSON.stringify({ type: 'stream:start', ts: Date.now(), sessionId, scene });
+  _write(`data: ${startPayload}\n\n`);
+
+  // ─── 性能跟踪 ───
+  const metrics = {
+    startTime: Date.now(),
+    eventCount: 0,
+    totalBytes: 0,
+    firstTextDeltaTime: 0,
+  };
+
+  return {
+    /**
+     * 发送一个 SSE 事件
+     * @param {object} event — 必须包含 type 字段
+     */
+    send(event) {
+      if (disconnected || res.writableEnded) return;
+      const payload = JSON.stringify({ ...event, ts: event.ts || Date.now() });
+      _write(`data: ${payload}\n\n`);
+      metrics.eventCount++;
+      metrics.totalBytes += payload.length;
+      if (event.type === 'text:delta' && !metrics.firstTextDeltaTime) {
+        metrics.firstTextDeltaTime = Date.now();
+      }
+    },
+
+    /**
+     * 正常结束流 — 发送 stream:done 并关闭连接
+     * @param {object} [donePayload={}] — done 事件携带的额外数据
+     */
+    end(donePayload = {}) {
+      clearInterval(heartbeat);
+      if (disconnected || res.writableEnded) return;
+      const payload = JSON.stringify({ type: 'stream:done', ts: Date.now(), ...donePayload });
+      _write(`data: ${payload}\n\n`);
+      res.end();
+    },
+
+    /**
+     * 发送错误并结束流
+     * @param {string} message
+     * @param {string} [code]
+     */
+    error(message, code) {
+      clearInterval(heartbeat);
+      if (disconnected || res.writableEnded) return;
+      const payload = JSON.stringify({ type: 'stream:error', ts: Date.now(), message, code });
+      _write(`data: ${payload}\n\n`);
+      res.end();
+    },
+
+    /** 是否已断开 */
+    get isDisconnected() { return disconnected; },
+
+    /** 会话 ID */
+    sessionId,
+
+    /** 获取性能指标 */
+    get metrics() {
+      return {
+        ...metrics,
+        endTime: Date.now(),
+        duration: Date.now() - metrics.startTime,
+        ttft: metrics.firstTextDeltaTime ? metrics.firstTextDeltaTime - metrics.startTime : null,
+      };
+    },
+  };
+}

package/lib/service/chat/ChatAgent.js

@@ -174,6 +174,8 @@ export class ChatAgent {
     workingMemory,              // WorkingMemory 实例 (由 orchestrator 注入)
     episodicMemory,             // EpisodicMemory 实例 (跨维度情景记忆)
     toolResultCache,            // ToolResultCache 实例 (跨维度工具结果缓存)
+    // v5.1: SSE 流式进度回调
+    onProgress,                 // (event: {type, ...}) => void — 实时推送思考/工具/回答事件
   } = {}) {
     this.#currentSource = source;
     this.#currentTokenUsage = { input: 0, output: 0 };
@@ -208,8 +210,22 @@ export class ChatAgent {
       systemPromptOverride, allowedTools, disablePhaseRouter, temperatureOverride,
       projectLanguage,
       workingMemory, episodicMemory, toolResultCache,
+      onProgress,
     });
 
+    // SSE: 推送最终回答（分块模拟流式）
+    if (onProgress && result.reply) {
+      const textId = `ans_${Date.now()}`;
+      onProgress({ type: 'text:start', id: textId, role: 'answer' });
+      // 分块推送：每 ~20 字符一块，模拟逐 token 打字效果
+      const CHUNK = 20;
+      const text = result.reply;
+      for (let i = 0; i < text.length; i += CHUNK) {
+        onProgress({ type: 'text:delta', id: textId, delta: text.slice(i, i + CHUNK) });
+      }
+      onProgress({ type: 'text:end', id: textId });
+    }
+
     // 持久化 assistant 回复
     if (conversationId && this.#conversations) {
       this.#conversations.append(conversationId, { role: 'assistant', content: result.reply });
@@ -271,6 +287,8 @@ export class ChatAgent {
     projectLanguage,
     // v4.0: Agent Memory 集成
     workingMemory, episodicMemory, toolResultCache,
+    // v5.1: SSE 流式进度回调
+    onProgress,
   }) {
     const isSystem = source === 'system';
     const isSkillOnly = dimensionMeta?.outputType === 'skill';
@@ -489,7 +507,11 @@ export class ChatAgent {
       let aiResult;
       try {
         const messages = ctx.toMessages();
-        this.#logger.info(`[ChatAgent] 🔄 iteration ${currentIter}/${maxIter} — phase=${phaseRouter?.phase || 'user'}, ${messages.length} msgs, toolChoice=${currentChoice}, tokens~${ctx.estimateTokens()}`);
+        const currentPhase = phaseRouter?.phase || 'user';
+        this.#logger.info(`[ChatAgent] 🔄 iteration ${currentIter}/${maxIter} — phase=${currentPhase}, ${messages.length} msgs, toolChoice=${currentChoice}, tokens~${ctx.estimateTokens()}`);
+
+        // SSE: 推送步骤开始
+        onProgress?.({ type: 'step:start', step: currentIter, maxSteps: maxIter, phase: currentPhase });
 
         aiResult = await this.#aiProvider.chatWithTools(prompt, {
           messages,
@@ -545,6 +567,7 @@ export class ChatAgent {
             break;
           }
           reasoning.afterRound();
+          onProgress?.({ type: 'step:end', step: currentIter });
           return {
             reply: `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`,
             toolCalls,
@@ -592,6 +615,9 @@ export class ChatAgent {
           const toolStartTime = Date.now();
           this.#logger.info(`[ChatAgent] 🔧 ${fc.name}(${JSON.stringify(fc.args).substring(0, 100)})`);
 
+          // SSE: 推送工具调用开始
+          onProgress?.({ type: 'tool:start', id: `tc_${fc.name}_${Date.now()}`, tool: fc.name, args: fc.args });
+
           let toolResult;
           let cacheHit = false;
 
@@ -624,9 +650,15 @@ export class ChatAgent {
               const toolDuration = Date.now() - toolStartTime;
               const resultSize = typeof toolResult === 'string' ? toolResult.length : JSON.stringify(toolResult).length;
               this.#logger.info(`[ChatAgent] 🔧 done: ${fc.name} → ${resultSize} chars in ${toolDuration}ms`);
+
+              // SSE: 推送工具调用完成
+              onProgress?.({ type: 'tool:end', tool: fc.name, status: 'ok', resultSize, duration: toolDuration });
             } catch (toolErr) {
               this.#logger.warn(`[ChatAgent] 🔧 FAILED: ${fc.name} — ${toolErr.message}`);
               toolResult = { error: `tool "${fc.name}" failed: ${toolErr.message}` };
+
+              // SSE: 推送工具调用失败
+              onProgress?.({ type: 'tool:end', tool: fc.name, status: 'error', error: toolErr.message, duration: Date.now() - toolStartTime });
             }
           }
 
@@ -812,10 +844,14 @@ export class ChatAgent {
           }
         }
 
+        // SSE: 步骤结束
+        onProgress?.({ type: 'step:end', step: currentIter });
         continue;
       }
 
       // ── 文字回答 ──
+      // SSE: 文字回答意味着步骤结束
+      onProgress?.({ type: 'step:end', step: currentIter });
       // 空响应重试（Gemini 偶发）
       if (!aiResult.text && isSystem && consecutiveEmptyResponses < 2) {
         consecutiveEmptyResponses++;

package/lib/service/chat/tools.js

@@ -1081,7 +1081,7 @@ const extractRecipes = {
     type: 'object',
     properties: {
       targetName: { type: 'string', description: 'SPM Target / 模块名称' },
-      files:      { type: 'array',  description: '文件数组 [{name, content}]' },
+      files:      { type: 'array',  items: { type: 'object', properties: { name: { type: 'string' }, content: { type: 'string' } } }, description: '文件数组 [{name, content}]' },
     },
     required: ['targetName', 'files'],
   },
@@ -1214,7 +1214,7 @@ const enrichCandidate = {
   parameters: {
     type: 'object',
     properties: {
-      candidateIds: { type: 'array', description: '候选 ID 列表 (最多 20 个)' },
+      candidateIds: { type: 'array', items: { type: 'string' }, description: '候选 ID 列表 (最多 20 个)' },
     },
     required: ['candidateIds'],
   },
@@ -1236,7 +1236,7 @@ const refineBootstrapCandidates = {
   parameters: {
     type: 'object',
     properties: {
-      candidateIds: { type: 'array', description: '指定候选 ID 列表（可选，默认全部 bootstrap 候选）' },
+      candidateIds: { type: 'array', items: { type: 'string' }, description: '指定候选 ID 列表（可选，默认全部 bootstrap 候选）' },
       userPrompt: { type: 'string', description: '用户自定义润色提示词，指导 AI 润色方向（如“侧重描述线程安全注意事项”）' },
       dryRun: { type: 'boolean', description: '仅预览 AI 润色结果，不写入数据库' },
     },
@@ -1324,6 +1324,13 @@ const discoverRelations = {
     properties: {
       recipePairs: {
         type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            a: { type: 'object', properties: { id: { type: 'string' }, title: { type: 'string' }, category: { type: 'string' }, code: { type: 'string' } } },
+            b: { type: 'object', properties: { id: { type: 'string' }, title: { type: 'string' }, category: { type: 'string' }, code: { type: 'string' } } },
+          },
+        },
         description: 'Recipe 对数组 [{ a: {id, title, category, code}, b: {id, title, category, code} }]',
       },
       dryRun: { type: 'boolean', description: '仅分析不写入，默认 false' },

package/lib/service/spm/SpmService.js

@@ -8,7 +8,7 @@ import { PackageSwiftParser } from './PackageSwiftParser.js';
 import { DependencyGraph } from './DependencyGraph.js';
 import { PolicyEngine } from './PolicyEngine.js';
 import { GraphCache } from '../../infrastructure/cache/GraphCache.js';
-import { dirname, relative, sep, resolve as pathResolve } from 'node:path';
+import { basename as _pathBasename, dirname, relative, sep, resolve as pathResolve } from 'node:path';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 
 export class SpmService {
@@ -809,14 +809,24 @@ export class SpmService {
    */
   async scanTarget(target, options = {}) {
     const targetName = typeof target === 'string' ? target : target?.name;
+    /** @type {((event: {type: string, [key:string]: any}) => void) | undefined} */
+    const onProgress = options.onProgress;
 
     // 1. 获取源文件列表
+    onProgress?.({ type: 'scan:started', targetName });
     const fileList = await this.getTargetFiles(target);
     if (!fileList || fileList.length === 0) {
       return { recipes: [], scannedFiles: [], message: `No source files found for target: ${targetName}` };
     }
 
+    const scannedFilesMeta = fileList.map(f => {
+      const filePath = typeof f === 'string' ? f : f.path;
+      return { name: _pathBasename(filePath), path: f.relativePath || _pathBasename(filePath) };
+    });
+    onProgress?.({ type: 'scan:files-loaded', files: scannedFilesMeta, count: fileList.length });
+
     // 2. 读取文件内容
+    onProgress?.({ type: 'scan:reading', count: fileList.length });
     const { readFileSync } = await import('fs');
     const { basename, resolve } = await import('path');
     const files = fileList.map(f => {
@@ -841,6 +851,7 @@ export class SpmService {
       return { recipes: [], scannedFiles, message: 'AI provider not configured. Please set ASD_AI_PROVIDER.' };
     }
 
+    onProgress?.({ type: 'scan:ai-extracting', fileCount: files.length, targetName });
     const AI_EXTRACT_TIMEOUT = 120_000; // 2 分钟 AI 提取超时
     let recipes;
     try {
@@ -922,12 +933,14 @@ export class SpmService {
     }
 
     // 4. 工具增强：语义标准化 + 标签 + 评分
+    onProgress?.({ type: 'scan:enriching', recipeCount: recipes.length });
     this._enrichRecipes(recipes);
 
     const result = { recipes, scannedFiles };
     if (recipes.length === 0) {
       result.message = `AI extraction returned 0 recipes for ${targetName} (${files.length} files analyzed)`;
     }
+    onProgress?.({ type: 'scan:completed', recipeCount: recipes.length, fileCount: scannedFiles.length });
     return result;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosnippet",
-  "version": "2.19.0",
+  "version": "2.19.2",
   "description": "AutoSnippet - 连接开发者、AI 与项目知识库的工具",
   "type": "module",
   "main": "lib/bootstrap.js",