autosnippet 2.6.0 → 2.7.1

package/lib/http/routes/recipes.js

@@ -8,27 +8,12 @@ import { asyncHandler } from '../middleware/errorHandler.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { NotFoundError, ValidationError } from '../../shared/errors/index.js';
 import Logger from '../../infrastructure/logging/Logger.js';
+import { getContext, safeInt } from '../utils/routeHelpers.js';
 
 const logger = Logger.getInstance();
 
 const router = express.Router();
 
-/** 从请求中提取操作上下文 */
-function getContext(req) {
-  return {
-    userId: req.headers['x-user-id'] || 'anonymous',
-    ip: req.ip,
-    userAgent: req.headers['user-agent'] || '',
-  };
-}
-
-/** 安全的整数解析 */
-function safeInt(value, defaultValue, min = 1, max = 1000) {
-  const parsed = parseInt(value, 10);
-  if (Number.isNaN(parsed)) return defaultValue;
-  return Math.max(min, Math.min(max, parsed));
-}
-
 /**
  * GET /api/v1/recipes
  * 获取 Recipe 列表（支持筛选和分页）
@@ -188,7 +173,9 @@ router.patch('/:id/publish', asyncHandler(async (req, res) => {
         });
       }
     }
-  } catch { /* Agent 不可用时不阻塞发布 */ }
+  } catch (err) {
+    logger.warn('Agent 不可用，跳过 discover_relations', { error: err.message });
+  }
 
   res.json({ success: true, data: result.data, requestId: result.requestId });
 }));

package/lib/http/routes/search.js

@@ -7,14 +7,11 @@ import express from 'express';
 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 { safeInt } from '../utils/routeHelpers.js';
 
 const router = express.Router();
-
-function safeInt(value, defaultValue, min = 1, max = 1000) {
-  const parsed = parseInt(value, 10);
-  if (Number.isNaN(parsed)) return defaultValue;
-  return Math.max(min, Math.min(max, parsed));
-}
+const logger = Logger.getInstance();
 
 /**
  * GET /api/v1/search
@@ -39,8 +36,8 @@ router.get('/', asyncHandler(async (req, res) => {
       const searchEngine = container.get('searchEngine');
       const result = await searchEngine.search(q, { type, limit, mode, groupByKind });
       return res.json({ success: true, data: result });
-    } catch {
-      // 降级到传统搜索
+    } catch (err) {
+      logger.warn('SearchEngine 搜索失败，降级到传统搜索', { mode, error: err.message });
     }
   }
 
@@ -52,7 +49,8 @@ router.get('/', asyncHandler(async (req, res) => {
     try {
       const recipeService = container.get('recipeService');
       results.recipes = await recipeService.searchRecipes(q, pagination);
-    } catch {
+    } catch (err) {
+      logger.warn('Recipe 搜索失败', { query: q, error: err.message });
       results.recipes = { items: [], total: 0 };
     }
   }
@@ -62,7 +60,8 @@ router.get('/', asyncHandler(async (req, res) => {
     try {
       const guardService = container.get('guardService');
       results.rules = await guardService.searchRules(q, pagination);
-    } catch {
+    } catch (err) {
+      logger.warn('Guard Rule 搜索失败', { query: q, error: err.message });
       results.rules = { items: [], total: 0 };
     }
   }
@@ -72,7 +71,8 @@ router.get('/', asyncHandler(async (req, res) => {
     try {
       const candidateService = container.get('candidateService');
       results.candidates = await candidateService.searchCandidates(q, pagination);
-    } catch {
+    } catch (err) {
+      logger.warn('Candidate 搜索失败', { query: q, error: err.message });
       results.candidates = { items: [], total: 0 };
     }
   }
@@ -216,14 +216,6 @@ router.get('/graph/stats', asyncHandler(async (req, res) => {
   res.json({ success: true, data: stats });
 }));
 
-/**
- * POST /api/v1/search/trigger-from-code
- * Xcode trigger 搜索模拟 (stub — 功能未完整实现)
- */
-router.post('/trigger-from-code', asyncHandler(async (req, res) => {
-  res.json({ success: true, data: { results: [], total: 0, triggered: false } });
-}));
-
 /**
  * POST /api/v1/search/context-aware
  * 上下文感知搜索

package/lib/http/routes/skills.js

@@ -40,6 +40,8 @@ router.get('/signal-status', asyncHandler(async (_req, res) => {
       running: true,
       mode: _signalCollector.getMode(),
       snapshot: _signalCollector.getSnapshot(),
+      // 返回 AI 的待处理建议，前端可直接展示
+      suggestions: (_signalCollector.getSnapshot().pendingSuggestions || []),
     },
   });
 }));

package/lib/http/routes/snippets.js

@@ -51,37 +51,4 @@ router.get('/:id', asyncHandler(async (req, res) => {
   res.json({ success: true, data: snippet });
 }));
 
-/**
- * POST /api/v1/snippets/install
- * 从全部 Recipe 生成并同步到 Xcode
- */
-router.post('/install', asyncHandler(async (req, res) => {
-  const container = getServiceContainer();
-  const snippetFactory = container.get('snippetFactory');
-  const snippetInstaller = container.get('snippetInstaller');
-  const recipeRepository = container.get('recipeRepository');
-
-  // 获取所有活跃 Recipe
-  const result = await recipeRepository.findWithPagination(
-    { status: 'active' },
-    { page: 1, pageSize: 9999 },
-  );
-  const recipes = (result?.data || result?.items || []).map(r => ({
-    id: r.id,
-    title: r.title,
-    trigger: r.trigger,
-    code: r.content?.pattern || '',
-    description: r.description || r.summaryCn || '',
-    language: r.language || 'swift',
-  }));
-
-  // 批量安装
-  const installResult = snippetInstaller.installFromRecipes(recipes);
-
-  res.json({
-    success: true,
-    data: installResult,
-  });
-}));
-
 export default router;

package/lib/http/routes/spm.js

@@ -198,23 +198,24 @@ router.post('/scan-project', asyncHandler(async (req, res) => {
 
 /**
  * POST /api/v1/spm/bootstrap
- * 冷启动：结构收集 + 9 维度 Candidate 创建
+ * 冷启动：快速骨架 + 异步逐维度填充（v5）
  *
- * 分离式执行策略（避免前端超时）：
- *   ① 同步阶段: bootstrap_knowledge（SPM 扫描 + AST + Skill 增强 + 候选创建）→ 立即返回
- *   ② 异步阶段: enrich + refine（AI 结构补齐 + 内容润色）→ 后台执行
+ * 执行策略：
+ *   ① 同步阶段: Phase 1-4（文件收集 + AST + SPM + Guard + 骨架响应）→ 立即返回
+ *   ② 异步阶段: Phase 5/5.5（逐维度提取 + Candidate/Skill 创建）→ 后台逐一执行
+ *   ③ 进度推送: 通过 Socket.io 实时推送每个维度的完成状态
  *
- * 前端立即获得候选列表，AI 增强在后台完成后候选会自动更新。
+ * 前端立即获得骨架 + 任务清单，每个维度完成后通过 Socket.io 推送更新。
  */
 router.post('/bootstrap', asyncHandler(async (req, res) => {
-  const { maxFiles, skipGuard, contentMaxLines, autoRefine } = req.body || {};
+  const { maxFiles, skipGuard, contentMaxLines } = req.body || {};
 
   const container = getServiceContainer();
   const chatAgent = container.get('chatAgent');
 
-  logger.info('Bootstrap cold start initiated (split mode: sync + async AI)');
+  logger.info('Bootstrap cold start initiated (v5: async fill mode)');
 
-  // ── 同步阶段: 快速执行启发式 bootstrap（~1s）──
+  // ── 同步阶段: 快速执行 Phase 1-4 → 返回骨架 ──
   const bootstrapResult = await chatAgent.executeTool('bootstrap_knowledge', {
     maxFiles: maxFiles || 500,
     skipGuard: skipGuard || false,
@@ -222,69 +223,42 @@ router.post('/bootstrap', asyncHandler(async (req, res) => {
     loadSkills: true,
   });
 
-  // 立即返回启发式结果给前端
-  const responseData = {
-    ...bootstrapResult,
-    aiEnhancement: 'pending',  // 告知前端 AI 增强正在后台进行
-  };
-
+  // 立即返回骨架结果给前端
   res.json({
     success: true,
-    data: responseData,
+    data: {
+      ...bootstrapResult,
+      asyncFill: true,     // 告知前端：内容正在异步填充中
+    },
   });
 
-  // ── 异步阶段: 后台 AI 增强（enrich + refine）不阻塞响应 ──
-  const shouldRefine = (autoRefine ?? true) && chatAgent.hasAI;
-  const created = bootstrapResult?.bootstrapCandidates?.created || 0;
-  if (shouldRefine && created > 0) {
-    setImmediate(async () => {
-      try {
-        logger.info(`[Bootstrap] Background AI enhancement starting for ${created} candidates`);
-
-        // enrich: 结构补齐
-        const candidateIds = bootstrapResult?.bootstrapCandidates?.ids
-          || bootstrapResult?.bootstrapCandidates?.candidateIds;
-        if (Array.isArray(candidateIds) && candidateIds.length > 0) {
-          try {
-            await chatAgent.executeTool('enrich_candidate', { candidateIds });
-            logger.info(`[Bootstrap] Background enrich done for ${candidateIds.length} candidates`);
-          } catch (e) {
-            logger.warn(`[Bootstrap] Background enrich failed (non-fatal): ${e.message}`);
-          }
-        }
-
-        // loadSkill + refine: AI 内容润色
-        try {
-          let userPrompt = '';
-          // 加载 Skill 内容
-          const loaded = bootstrapResult?.skillsLoaded || [];
-          const skillName = loaded.find(s => s.startsWith('autosnippet-reference-')) || 'autosnippet-coldstart';
-          try {
-            const skillResult = await chatAgent.executeTool('load_skill', { skillName });
-            if (skillResult?.content) {
-              userPrompt = `请参考以下业界最佳实践标准润色候选，确保 summary 精准、tags 丰富、confidence 合理:\n${skillResult.content.substring(0, 3000)}`;
-            }
-          } catch { /* skill load failed, proceed without */ }
-
-          // AST 上下文注入
-          if (bootstrapResult?.astContext) {
-            userPrompt += `\n\n# 项目代码结构分析 (Tree-sitter AST)\n${bootstrapResult.astContext.substring(0, 2000)}`;
-          }
+  // 注意：Phase 5/5.5 异步填充已在 bootstrapKnowledge() 内部通过 setImmediate 启动
+  // 进度通过 BootstrapTaskManager → Socket.io 推送到前端
+}));
 
-          await chatAgent.executeTool('refine_bootstrap_candidates', {
-            userPrompt: userPrompt || undefined,
-          });
-          logger.info(`[Bootstrap] Background refine done`);
-        } catch (e) {
-          logger.warn(`[Bootstrap] Background refine failed (non-fatal): ${e.message}`);
-        }
+/**
+ * GET /api/v1/spm/bootstrap/status
+ * 查询当前 bootstrap 异步填充进度
+ *
+ * 返回当前 session 的任务状态列表，供前端轮询（Socket.io 不可用时的 fallback）
+ */
+router.get('/bootstrap/status', asyncHandler(async (req, res) => {
+  const container = getServiceContainer();
 
-        logger.info('[Bootstrap] Background AI enhancement completed');
-      } catch (e) {
-        logger.error(`[Bootstrap] Background AI enhancement error: ${e.message}`);
-      }
+  // 从容器获取 BootstrapTaskManager（正式 DI 注册）
+  let taskManager = null;
+  try { taskManager = container.get('bootstrapTaskManager'); } catch { /* not registered */ }
+  if (!taskManager) {
+    return res.json({
+      success: true,
+      data: { status: 'idle', message: 'No bootstrap task manager initialized' },
     });
   }
+
+  res.json({
+    success: true,
+    data: taskManager.getSessionStatus(),
+  });
 }));
 
 export default router;

package/lib/http/utils/routeHelpers.js

@@ -0,0 +1,31 @@
+/**
+ * 路由共用工具函数
+ * 提取自各路由文件中的重复实现
+ */
+
+/**
+ * 从请求中提取操作上下文（用户身份、IP、UA）
+ * @param {import('express').Request} req
+ * @returns {{ userId: string, ip: string, userAgent: string }}
+ */
+export function getContext(req) {
+  return {
+    userId: req.headers['x-user-id'] || 'anonymous',
+    ip: req.ip,
+    userAgent: req.headers['user-agent'] || '',
+  };
+}
+
+/**
+ * 安全的整数解析（带范围约束）
+ * @param {*} value     待解析值
+ * @param {number} defaultValue  解析失败时的默认值
+ * @param {number} [min=1]       最小值
+ * @param {number} [max=1000]    最大值
+ * @returns {number}
+ */
+export function safeInt(value, defaultValue, min = 1, max = 1000) {
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed)) return defaultValue;
+  return Math.max(min, Math.min(max, parsed));
+}

package/lib/infrastructure/config/Paths.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import fs from 'node:fs';
+import pathGuard from '../../shared/PathGuard.js';
 
 /**
  * Paths — 项目路径解析工具
@@ -14,6 +15,8 @@ const USER_HOME = process.env.HOME || process.env.USERPROFILE || '';
 /** 确保目录存在（静默处理异常） */
 function ensureDir(dirPath) {
   try {
+    // 双层路径安全检查 — 阻止在项目允许范围外创建文件夹
+    pathGuard.assertProjectWriteSafe(dirPath);
     if (!fs.existsSync(dirPath)) {
       fs.mkdirSync(dirPath, { recursive: true });
     }
@@ -94,6 +97,14 @@ export function getContextIndexPath(projectRoot) {
   return ensureDir(path.join(getContextStoragePath(projectRoot), 'index'));
 }
 
+/**
+ * 项目级 Skills 目录 = knowledgePath/skills
+ * Skills 放在知识库目录下跟随项目走（Git-tracked，用户可见）
+ */
+export function getProjectSkillsPath(projectRoot) {
+  return ensureDir(path.join(getProjectKnowledgePath(projectRoot), 'skills'));
+}
+
 /**
  * Recipes 目录
  * 优先使用 rootSpec.recipes.dir / rootSpec.skills.dir（兼容旧配置）
@@ -114,6 +125,7 @@ export default {
   getProjectKnowledgePath,
   getProjectSpecPath,
   getProjectInternalDataPath,
+  getProjectSkillsPath,
   getContextStoragePath,
   getContextIndexPath,
   getProjectRecipesPath,

package/lib/infrastructure/database/DatabaseConnection.js

@@ -2,6 +2,7 @@ import Database from 'better-sqlite3';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import pathGuard from '../../shared/PathGuard.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -20,9 +21,13 @@ export class DatabaseConnection {
    */
   async connect() {
     const dbPath = this.config.path;
+
+    // 路径安全检查 — 防止 DB 文件创建到项目允许范围外
+    const resolvedDbPath = path.resolve(dbPath);
+    pathGuard.assertProjectWriteSafe(resolvedDbPath);
     
     // 确保数据目录存在
-    const dbDir = path.dirname(dbPath);
+    const dbDir = path.dirname(resolvedDbPath);
     if (!fs.existsSync(dbDir)) {
       fs.mkdirSync(dbDir, { recursive: true });
     }

package/lib/infrastructure/logging/Logger.js

@@ -2,9 +2,91 @@ import winston from 'winston';
 import path from 'path';
 import fs from 'fs';
 
+// ChatAgent 相关标签 — 终端高亮显示
+const AGENT_TAGS = ['ChatAgent', 'ToolRegistry', 'SignalCollector', 'SkillAdvisor', 'CircuitBreaker', 'EventAggregator'];
+const MUTED_PREFIXES = ['HTTP Request', 'Tool registered:', '📊 性能统计已更新'];
+
+// ANSI 颜色常量 — 保证深色终端可读性
+const C = {
+  reset:   '\x1b[0m',
+  dim:     '\x1b[2m',       // 真正的 dim（用于次要信息）
+  bold:    '\x1b[1m',
+  // 前景色 — 使用亮色变体，深色终端更清晰
+  gray:    '\x1b[37m',      // 白色（替代 90 暗灰）
+  cyan:    '\x1b[96m',      // 亮青
+  green:   '\x1b[92m',      // 亮绿
+  yellow:  '\x1b[93m',      // 亮黄
+  red:     '\x1b[91m',      // 亮红
+  magenta: '\x1b[95m',      // 亮洋红
+  blue:    '\x1b[94m',      // 亮蓝
+  dimGray: '\x1b[2;37m',    // dim 白色 — 比 90 在深色背景上更可读
+};
+
+const LEVEL_COLORS = {
+  error: C.red,
+  warn:  C.yellow,
+  info:  C.green,
+  debug: C.blue,
+};
+
+/**
+ * 精简 Console 格式
+ * - ChatAgent 相关日志: 高亮 cyan/magenta，显示完整信息
+ * - warn/error: 醒目颜色完整显示
+ * - HTTP 日志: 精简并降低视觉权重
+ * - 其他 info/debug: 一行精简格式
+ */
+const compactConsoleFormat = winston.format.printf(({ level, message, timestamp, ...meta }) => {
+  const ts = new Date(timestamp).toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' });
+  const rawLevel = level.replace(/\u001b\[\d+m/g, ''); // 去 ANSI
+  const lc = LEVEL_COLORS[rawLevel] || C.gray;
+
+  // 静音高频噪音日志
+  if (rawLevel === 'info' && MUTED_PREFIXES.some(p => message.startsWith(p))) {
+    return ''; // 返回空字符串会被 winston 跳过
+  }
+
+  // 判断是否为 Agent 相关日志
+  const isAgentLog = AGENT_TAGS.some(tag => message.includes(tag) || message.startsWith(`[${tag}]`));
+
+  if (isAgentLog) {
+    // ChatAgent 日志 — 高亮显示
+    const metaStr = Object.keys(meta).length > 0
+      ? ' ' + JSON.stringify(meta, null, 0).replace(/"/g, '').replace(/,/g, ', ')
+      : '';
+    return `${C.cyan}${ts}${C.reset} ${C.magenta}⚡ ${message}${C.reset}${metaStr ? `${C.dimGray}${metaStr}${C.reset}` : ''}`;
+  }
+
+  // HTTP 请求日志 — 精简格式，降低视觉权重
+  if (message === 'HTTP' && meta.method) {
+    const { method, path: reqPath, statusCode, duration } = meta;
+    const status = Number(statusCode);
+    const sc = status >= 500 ? C.red : status >= 400 ? C.yellow : C.dimGray;
+    const dur = parseInt(duration) > 1000 ? `${C.yellow}${duration}${C.reset}` : `${C.dimGray}${duration}${C.reset}`;
+    return `${C.dimGray}${ts}${C.reset} ${lc}${rawLevel}${C.reset} ${C.dimGray}${method}${C.reset} ${C.gray}${reqPath}${C.reset} ${sc}${statusCode}${C.reset} ${dur}`;
+  }
+
+  if (rawLevel === 'warn') {
+    const metaStr = Object.keys(meta).length > 0 ? ' ' + JSON.stringify(meta) : '';
+    return `${C.gray}${ts}${C.reset} ${C.yellow}${C.bold}warn${C.reset} ${C.yellow}${message}${C.reset}${metaStr ? `${C.dimGray}${metaStr}${C.reset}` : ''}`;
+  }
+
+  if (rawLevel === 'error') {
+    const metaStr = Object.keys(meta).length > 0 ? ' ' + JSON.stringify(meta) : '';
+    return `${C.gray}${ts}${C.reset} ${C.red}${C.bold}error${C.reset} ${C.red}${message}${C.reset}${metaStr ? `${C.dimGray}${metaStr}${C.reset}` : ''}`;
+  }
+
+  // 普通 info/debug — 精简一行，但保证可读
+  return `${C.dimGray}${ts}${C.reset} ${lc}${rawLevel}${C.reset} ${C.gray}${message}${C.reset}`;
+});
+
 /**
  * Logger - 统一日志系统
  *
+ * 环境变量:
+ *   ASD_LOG_LEVEL — 覆盖日志级别 (debug/info/warn/error)
+ *   ASD_MCP_MODE=1 — MCP 模式下禁用 Console transport
+ *
  * MCP 模式（ASD_MCP_MODE=1）下 Console transport 输出到 stderr 并禁用彩色，
  * 避免污染 stdout JSON-RPC 通道。
  */
@@ -21,6 +103,7 @@ export class Logger {
       }
 
       const isMcpMode = process.env.ASD_MCP_MODE === '1';
+      const logLevel = process.env.ASD_LOG_LEVEL || config.level || 'info';
       const transports = [];
 
       // Console transport — MCP 模式下完全禁用（任何 stderr 输出都会被 Cursor 标记为 [error]）
@@ -29,8 +112,8 @@ export class Logger {
           new winston.transports.Console({
             stderrLevels: ['error', 'warn', 'info', 'debug'],
             format: winston.format.combine(
-              winston.format.colorize(),
-              winston.format.simple()
+              winston.format.timestamp(),
+              compactConsoleFormat,
             ),
           })
         );
@@ -55,7 +138,7 @@ export class Logger {
       }
 
       this.instance = winston.createLogger({
-        level: config.level || 'info',
+        level: logLevel,
         format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
         transports,
       });

package/lib/infrastructure/realtime/RealtimeService.js

@@ -129,11 +129,8 @@ export class RealtimeService {
    * 广播通用事件
    */
   broadcastEvent(eventName, data) {
-    this.io.to('notifications').emit(eventName, {
-      type: eventName,
-      ...data,
-      timestamp: Date.now(),
-    });
+    // 直接透传 data（不包装 type/timestamp），保持与前端 hook 期望的数据结构一致
+    this.io.to('notifications').emit(eventName, data);
   }
 
   /**

package/lib/infrastructure/vector/JsonVectorAdapter.js

@@ -7,6 +7,7 @@
 import { VectorStore } from './VectorStore.js';
 import { writeFileSync, readFileSync, mkdirSync, existsSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import pathGuard from '../../shared/PathGuard.js';
 
 export class JsonVectorAdapter extends VectorStore {
   #indexPath;
@@ -22,7 +23,15 @@ export class JsonVectorAdapter extends VectorStore {
   }
 
   async init() {
-    await this.#load();
+    this.#load();
+  }
+
+  /**
+   * 同步初始化 — 供 ServiceContainer 懒加载工厂使用
+   * （#load 本身就是同步的 readFileSync，无需 await）
+   */
+  initSync() {
+    this.#load();
   }
 
   async upsert(item) {
@@ -132,6 +141,21 @@ export class JsonVectorAdapter extends VectorStore {
     return scored;
   }
 
+  /**
+   * query() — SearchEngine / RetrievalFunnel 使用的向量搜索别名
+   * 接口: query(vector, topK) → Array<{ id, similarity, metadata }>
+   */
+  async query(queryVector, topK = 10) {
+    const results = await this.searchVector(queryVector, { topK });
+    return results.map(r => ({
+      id: r.item.id,
+      similarity: r.score,
+      score: r.score,
+      content: r.item.content,
+      metadata: r.item.metadata || {},
+    }));
+  }
+
   async searchByFilter(filter) {
     return this.#applyFilter([...this.#data.values()], filter);
   }
@@ -215,6 +239,7 @@ export class JsonVectorAdapter extends VectorStore {
     if (!this.#dirty) return;
     try {
       const dir = dirname(this.#indexPath);
+      pathGuard.assertProjectWriteSafe(dir);
       if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
       const items = [...this.#data.values()];
       writeFileSync(this.#indexPath, JSON.stringify(items, null, 2));

package/lib/injection/ServiceContainer.js

@@ -51,8 +51,13 @@ import { ChatAgent } from '../service/chat/ChatAgent.js';
 import { ALL_TOOLS } from '../service/chat/tools.js';
 import { SkillHooks } from '../service/skills/SkillHooks.js';
 
+// ─── v3.0: AST ProjectGraph ──────────────────────────
+import ProjectGraph from '../core/ast/ProjectGraph.js';
+
 // ─── P3: Infrastructure ──────────────────────────────
 import { EventBus } from '../infrastructure/event/EventBus.js';
+import { BootstrapTaskManager } from '../service/bootstrap/BootstrapTaskManager.js';
+import { getRealtimeService as _getRealtimeService } from '../infrastructure/realtime/RealtimeService.js';
 
 /**
  * DependencyInjection 容器
@@ -208,6 +213,19 @@ export class ServiceContainer {
       }
       return this.singletons.eventBus;
     });
+
+    // BootstrapTaskManager（冷启动异步任务管理器 — 单例）
+    this.register('bootstrapTaskManager', () => {
+      if (!this.singletons.bootstrapTaskManager) {
+        const eventBus = this.get('eventBus');
+        // 延迟 getter: RealtimeService 在 HTTP server 启动后才可用，CLI 模式下不可用
+        const getRS = () => {
+          try { return _getRealtimeService(); } catch { return null; }
+        };
+        this.singletons.bootstrapTaskManager = new BootstrapTaskManager({ eventBus, getRealtimeService: getRS });
+      }
+      return this.singletons.bootstrapTaskManager;
+    });
   }
 
   /**
@@ -340,11 +358,13 @@ export class ServiceContainer {
       return this.singletons.retrievalFunnel;
     });
 
-    // JsonVectorAdapter
+    // JsonVectorAdapter（同步构造 + 同步 init — 从磁盘 JSON 加载历史向量数据）
     this.register('vectorStore', () => {
       if (!this.singletons.vectorStore) {
         const projectRoot = this.singletons._projectRoot || process.cwd();
-        this.singletons.vectorStore = new JsonVectorAdapter(projectRoot);
+        const store = new JsonVectorAdapter(projectRoot);
+        store.initSync();  // 从磁盘加载已有 vector_index.json
+        this.singletons.vectorStore = store;
       }
       return this.singletons.vectorStore;
     });
@@ -481,6 +501,12 @@ export class ServiceContainer {
       return this.singletons.toolRegistry;
     });
 
+    // ProjectGraph (v3.0 AST 结构图 — 懒初始化，首次 get 时构建)
+    this.register('projectGraph', () => {
+      // 返回已构建的实例；需要外部先调用 buildProjectGraph() 构建
+      return this.singletons.projectGraph || null;
+    });
+
     // AI Provider（供 MCP handler / ChatAgent / 任意服务层使用）
     this.register('aiProvider', () => this.singletons.aiProvider || null);
 
@@ -537,6 +563,33 @@ export class ServiceContainer {
   getServiceNames() {
     return Object.keys(this.services);
   }
+
+  /**
+   * 构建 ProjectGraph (v3.0 AST 结构图)
+   * 应在 bootstrap 流程开始前调用一次
+   * @param {string} projectRoot 项目根目录
+   * @param {object} [options] 传递给 ProjectGraph.build() 的选项
+   * @returns {Promise<import('../core/ast/ProjectGraph.js').default|null>}
+   */
+  async buildProjectGraph(projectRoot, options = {}) {
+    if (this.singletons.projectGraph) {
+      return this.singletons.projectGraph;
+    }
+    try {
+      const graph = await ProjectGraph.build(projectRoot, options);
+      this.singletons.projectGraph = graph;
+      const overview = graph.getOverview();
+      this.logger.info(
+        `[ServiceContainer] ProjectGraph built: ${overview.totalClasses} classes, ` +
+        `${overview.totalProtocols} protocols, ${overview.totalCategories} categories ` +
+        `(${overview.buildTimeMs}ms)`
+      );
+      return graph;
+    } catch (err) {
+      this.logger.warn(`[ServiceContainer] ProjectGraph build failed: ${err.message}`);
+      return null;
+    }
+  }
 }
 
 let containerInstance = null;