autosnippet 2.8.3 → 2.10.0

package/lib/service/chat/tools.js

@@ -33,7 +33,7 @@
  * │ 17. generate_guard_rule  AI 生成 Guard 规则       │
  * └─────────────────────────────────────────────────────┘
  * ┌─── 生命周期操作类 (7) ─────────────────────────────┐
- * │ 18. submit_candidate     提交候选                │
+ * │ 18. submit_knowledge     提交候选                │
  * │ 19. approve_candidate    批准候选                │
  * │ 20. reject_candidate     驳回候选                │
  * │ 21. publish_recipe       发布 Recipe              │
@@ -123,30 +123,133 @@ function _scoreSearchLine(line) {
   return 0;
 }
 
+/**
+ * 收集项目文件列表 — 抽取为公用函数，供单次和批量搜索复用。
+ * 优先使用内存缓存（bootstrap 场景），否则从磁盘递归读取。
+ */
+async function _getProjectFiles(params, ctx) {
+  const { fileFilter } = params;
+  const projectRoot = ctx.projectRoot || process.cwd();
+
+  let extFilter = null;
+  if (fileFilter) {
+    const exts = fileFilter.split(',').map(e => e.trim().replace(/^\./, ''));
+    extFilter = new RegExp(`\\.(${exts.join('|')})$`, 'i');
+  }
+
+  const fileCache = ctx.fileCache || null;
+  let files;
+  let skippedThirdParty = 0;
+
+  if (fileCache && Array.isArray(fileCache)) {
+    files = fileCache.filter(f => {
+      const p = f.relativePath || f.path || '';
+      if (THIRD_PARTY_RE.test(p)) { skippedThirdParty++; return false; }
+      if (extFilter && !extFilter.test(p)) return false;
+      if (!SOURCE_EXT_RE.test(p)) return false;
+      return true;
+    });
+  } else {
+    files = [];
+    const MAX_FILE_SIZE = 512 * 1024;
+    const walk = (dir, relBase = '') => {
+      try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const relPath = relBase ? `${relBase}/${entry.name}` : entry.name;
+          const fullPath = path.join(dir, entry.name);
+          const isDir = entry.isDirectory() || (entry.isSymbolicLink() && (() => { try { return fs.statSync(fullPath).isDirectory(); } catch { return false; } })());
+          const isFile = entry.isFile() || (entry.isSymbolicLink() && (() => { try { return fs.statSync(fullPath).isFile(); } catch { return false; } })());
+          if (isDir) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'build') continue;
+            if (THIRD_PARTY_RE.test(relPath + '/')) { skippedThirdParty++; continue; }
+            walk(fullPath, relPath);
+          } else if (isFile) {
+            if (THIRD_PARTY_RE.test(relPath)) { skippedThirdParty++; continue; }
+            if (!SOURCE_EXT_RE.test(entry.name)) continue;
+            if (extFilter && !extFilter.test(entry.name)) continue;
+            try {
+              const stat = fs.statSync(fullPath);
+              if (stat.size > MAX_FILE_SIZE) continue;
+              const content = fs.readFileSync(fullPath, 'utf-8');
+              files.push({ relativePath: relPath, content, name: entry.name });
+            } catch { /* skip unreadable files */ }
+          }
+        }
+      } catch { /* skip inaccessible dirs */ }
+    };
+    walk(projectRoot);
+  }
+
+  return { files, skippedThirdParty };
+}
+
 const searchProjectCode = {
   name: 'search_project_code',
   description: '在用户项目源码中搜索指定模式。返回匹配的代码片段及上下文。' +
     '自动过滤三方库代码（Pods/Carthage/node_modules），优先返回实际使用行而非声明行。' +
-    '适用场景：验证代码模式存在性、查找更多项目示例、理解项目中某个 API 的用法。',
+    '适用场景：验证代码模式存在性、查找更多项目示例、理解项目中某个 API 的用法。' +
+    '批量搜索：传入 patterns 数组可一次搜索多个关键词（每个关键词独立返回结果），减少工具调用次数。',
   parameters: {
     type: 'object',
     properties: {
-      pattern:      { type: 'string', description: '搜索词或正则表达式' },
+      pattern:      { type: 'string', description: '搜索词或正则表达式（单个搜索时使用）' },
+      patterns:     { type: 'array', items: { type: 'string' }, description: '批量搜索：多个搜索词数组，如 ["methodA", "methodB", "classC"]。与 pattern 互斥，优先使用 patterns。' },
       isRegex:      { type: 'boolean', description: '是否为正则表达式，默认 false' },
       fileFilter:   { type: 'string', description: '文件扩展名过滤，如 ".m,.swift"' },
-      contextLines: { type: 'number', description: '匹配行前后的上下文行数，默认 5' },
-      maxResults:   { type: 'number', description: '最大返回结果数，默认 8' },
+      contextLines: { type: 'number', description: '匹配行前后的上下文行数，默认 3' },
+      maxResults:   { type: 'number', description: '每个 pattern 的最大返回结果数，默认 5' },
     },
-    required: ['pattern'],
+    required: [],
   },
   handler: async (params, ctx) => {
+    // ── 去重缓存初始化 ──
+    const state = ctx._sharedState || ctx;
+    if (!state._searchCache) state._searchCache = new Map();
+
+    // ── 批量模式：patterns 数组 ──
+    if (Array.isArray(params.patterns) && params.patterns.length > 0) {
+      const batchPatterns = params.patterns.slice(0, 10); // 最多 10 个
+      const batchResults = {};
+      let dedupCount = 0;
+      for (const p of batchPatterns) {
+        // 去重：已搜索过的 pattern 直接返回缓存
+        const cacheKey = `${p}|${params.isRegex || false}|${params.fileFilter || ''}`;
+        if (state._searchCache.has(cacheKey)) {
+          batchResults[p] = { ...state._searchCache.get(cacheKey), _cached: true };
+          dedupCount++;
+          continue;
+        }
+        const sub = await searchProjectCode.handler(
+          { ...params, pattern: p, patterns: undefined },
+          ctx,
+        );
+        const entry = { matches: sub.matches || [], total: sub.total || 0 };
+        state._searchCache.set(cacheKey, entry);
+        batchResults[p] = entry;
+      }
+      return {
+        batchResults,
+        patternsSearched: batchPatterns.length,
+        searchedFiles: (await _getProjectFiles(params, ctx)).files.length,
+        ...(dedupCount > 0 ? { _deduped: dedupCount, hint: `${dedupCount} 个 pattern 命中缓存，请避免重复搜索相同关键词。` } : {}),
+      };
+    }
+
     // 兼容 AI 传 "query" / "search" / "keyword" 替代 "pattern"
     const pattern = params.pattern || params.query || params.search || params.keyword || params.search_query;
-    const { isRegex = false, fileFilter, contextLines = 5, maxResults = 8 } = params;
+    const { isRegex = false, fileFilter, contextLines = 3, maxResults = 5 } = params;
     const projectRoot = ctx.projectRoot || process.cwd();
 
     if (!pattern || typeof pattern !== 'string') {
-      return { error: '参数错误: 请提供 pattern（搜索关键词或正则表达式）', matches: [], total: 0 };
+      return { error: '参数错误: 请提供 pattern（搜索关键词或正则表达式）或 patterns 数组', matches: [], total: 0 };
+    }
+
+    // ── 单 pattern 去重检查 ──
+    const cacheKey = `${pattern}|${params.isRegex || false}|${params.fileFilter || ''}`;
+    if (state._searchCache.has(cacheKey)) {
+      const cached = state._searchCache.get(cacheKey);
+      return { ...cached, _cached: true, hint: `⚠ 已搜索过 "${pattern}"，返回缓存结果。请搜索不同的关键词以获取新信息。` };
     }
 
     // 构建搜索正则
@@ -157,61 +260,7 @@ const searchProjectCode = {
       return { error: `Invalid pattern: ${err.message}`, matches: [], total: 0 };
     }
 
-    // 文件扩展名过滤
-    let extFilter = null;
-    if (fileFilter) {
-      const exts = fileFilter.split(',').map(e => e.trim().replace(/^\./, ''));
-      extFilter = new RegExp(`\\.(${exts.join('|')})$`, 'i');
-    }
-
-    // 收集文件列表 — 优先使用内存缓存（bootstrap 场景），否则从磁盘递归读取
-    const fileCache = ctx.fileCache || null;
-    let files;
-    let skippedThirdParty = 0;
-
-    if (fileCache && Array.isArray(fileCache)) {
-      // Bootstrap 场景: allFiles 已在内存
-      files = fileCache.filter(f => {
-        const p = f.relativePath || f.path || '';
-        if (THIRD_PARTY_RE.test(p)) { skippedThirdParty++; return false; }
-        if (extFilter && !extFilter.test(p)) return false;
-        if (!SOURCE_EXT_RE.test(p)) return false;
-        return true;
-      });
-    } else {
-      // Dashboard / SignalCollector 场景: 从磁盘递归读取
-      files = [];
-      const MAX_FILE_SIZE = 512 * 1024; // 512KB — 跳过超大文件
-      const walk = (dir, relBase = '') => {
-        try {
-          const entries = fs.readdirSync(dir, { withFileTypes: true });
-          for (const entry of entries) {
-            const relPath = relBase ? `${relBase}/${entry.name}` : entry.name;
-            const fullPath = path.join(dir, entry.name);
-            // 支持 symlink: 解析为目录或文件
-            const isDir = entry.isDirectory() || (entry.isSymbolicLink() && (() => { try { return fs.statSync(fullPath).isDirectory(); } catch { return false; } })());
-            const isFile = entry.isFile() || (entry.isSymbolicLink() && (() => { try { return fs.statSync(fullPath).isFile(); } catch { return false; } })());
-            if (isDir) {
-              // 跳过隐藏目录和常见无关目录
-              if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'build') continue;
-              if (THIRD_PARTY_RE.test(relPath + '/')) { skippedThirdParty++; continue; }
-              walk(fullPath, relPath);
-            } else if (isFile) {
-              if (THIRD_PARTY_RE.test(relPath)) { skippedThirdParty++; continue; }
-              if (!SOURCE_EXT_RE.test(entry.name)) continue;
-              if (extFilter && !extFilter.test(entry.name)) continue;
-              try {
-                const stat = fs.statSync(fullPath);
-                if (stat.size > MAX_FILE_SIZE) continue; // 跳过超大文件
-                const content = fs.readFileSync(fullPath, 'utf-8');
-                files.push({ relativePath: relPath, content, name: entry.name });
-              } catch { /* skip unreadable files */ }
-            }
-          }
-        } catch { /* skip inaccessible dirs */ }
-      };
-      walk(projectRoot);
-    }
+    const { files, skippedThirdParty } = await _getProjectFiles(params, ctx);
 
     // 搜索匹配
     const matches = [];
@@ -253,21 +302,25 @@ const searchProjectCode = {
     // 按 score 降序排列（实际使用行优先）
     matches.sort((a, b) => b.score - a.score);
 
-    return {
+    const result = {
       matches,
       total,
       searchedFiles: files.length,
       skippedThirdParty,
       ...((() => {
         // P2.2: 搜索超限提示 — 引导使用 AST 工具
-        const state = ctx._sharedState || ctx;
         state._searchCallCount = (state._searchCallCount || 0) + 1;
-        if (state._searchCallCount > 8 && ctx.source === 'system') {
+        if (state._searchCallCount > 12 && ctx.source === 'system') {
           return { hint: `💡 你已搜索 ${state._searchCallCount} 次。考虑使用 get_class_info / get_class_hierarchy / get_project_overview 获取结构化信息，效率更高。` };
         }
         return {};
       })()),
     };
+
+    // 缓存搜索结果
+    state._searchCache.set(cacheKey, { matches: result.matches, total: result.total });
+
+    return result;
   },
 };
 
@@ -277,18 +330,51 @@ const searchProjectCode = {
 const readProjectFile = {
   name: 'read_project_file',
   description: '读取项目中指定文件的内容（部分或全部）。' +
-    '通常在 search_project_code 找到匹配后使用，获取更完整的上下文。',
+    '通常在 search_project_code 找到匹配后使用，获取更完整的上下文。' +
+    '批量读取：传入 filePaths 数组可一次读取多个文件，减少工具调用次数。',
   parameters: {
     type: 'object',
     properties: {
-      filePath:   { type: 'string', description: '相对于项目根目录的文件路径' },
+      filePath:   { type: 'string', description: '相对于项目根目录的文件路径（单个文件时使用）' },
+      filePaths:  { type: 'array', items: { type: 'string' }, description: '批量读取：多个文件路径数组。与 filePath 互斥，优先使用 filePaths。' },
       startLine:  { type: 'number', description: '起始行号（1-based），默认 1' },
       endLine:    { type: 'number', description: '结束行号（1-based），默认文件末尾' },
-      maxLines:   { type: 'number', description: '最大返回行数，默认 200' },
+      maxLines:   { type: 'number', description: '最大返回行数，默认 200（批量模式下每个文件最多 100 行）' },
     },
-    required: ['filePath'],
+    required: [],
   },
   handler: async (params, ctx) => {
+    // ── 去重缓存初始化 ──
+    const state = ctx._sharedState || ctx;
+    if (!state._readCache) state._readCache = new Map();
+
+    // ── 批量模式：filePaths 数组 ──
+    if (Array.isArray(params.filePaths) && params.filePaths.length > 0) {
+      const batchPaths = params.filePaths.slice(0, 8); // 最多 8 个文件
+      const batchResults = {};
+      let dedupCount = 0;
+      for (const fp of batchPaths) {
+        const cacheKey = `${fp}|${params.startLine || 1}|${params.endLine || ''}|${params.maxLines || 100}`;
+        if (state._readCache.has(cacheKey)) {
+          batchResults[fp] = { ...state._readCache.get(cacheKey), _cached: true };
+          dedupCount++;
+          continue;
+        }
+        const sub = await readProjectFile.handler(
+          { ...params, filePath: fp, filePaths: undefined, maxLines: Math.min(params.maxLines || 100, 100) },
+          ctx,
+        );
+        const entry = sub.error ? { error: sub.error } : { content: sub.content, totalLines: sub.totalLines, language: sub.language };
+        state._readCache.set(cacheKey, entry);
+        batchResults[fp] = entry;
+      }
+      return {
+        batchResults,
+        filesRead: batchPaths.length,
+        ...(dedupCount > 0 ? { _deduped: dedupCount, hint: `${dedupCount} 个文件命中缓存，请避免重复读取相同文件。` } : {}),
+      };
+    }
+
     // 兼容各种参数名变体 (ToolRegistry 层已做 snake→camel 归一化,
     // 这里兜底处理漏网之鱼)
     const filePath = params.filePath || params.path || params.file_path || params.filepath || params.file || params.filename;
@@ -296,7 +382,13 @@ const readProjectFile = {
     const projectRoot = ctx.projectRoot || process.cwd();
 
     if (!filePath || typeof filePath !== 'string') {
-      return { error: '参数错误: 请提供 filePath（相对于项目根目录的文件路径）' };
+      return { error: '参数错误: 请提供 filePath（相对于项目根目录的文件路径）或 filePaths 数组' };
+    }
+
+    // ── 单文件去重检查 ──
+    const readCacheKey = `${filePath}|${startLine}|${params.endLine || ''}|${maxLines}`;
+    if (state._readCache.has(readCacheKey)) {
+      return { ...state._readCache.get(readCacheKey), _cached: true, hint: `⚠ 已读取过该文件相同行范围，返回缓存结果。如需其他行范围请指定不同的 startLine/endLine。` };
     }
 
     // 安全检查: 禁止路径遍历
@@ -349,7 +441,7 @@ const readProjectFile = {
     const langMap = { '.m': 'objectivec', '.mm': 'objectivec', '.h': 'objectivec', '.swift': 'swift', '.js': 'javascript', '.ts': 'typescript', '.py': 'python', '.java': 'java', '.kt': 'kotlin', '.go': 'go', '.rs': 'rust', '.rb': 'ruby' };
     const language = langMap[ext] || 'unknown';
 
-    return {
+    const readResult = {
       filePath,
       totalLines,
       startLine: start,
@@ -357,6 +449,11 @@ const readProjectFile = {
       content: selectedLines.join('\n'),
       language,
     };
+
+    // 缓存读取结果
+    state._readCache.set(readCacheKey, { content: readResult.content, totalLines, language });
+
+    return readResult;
   },
 };
 
@@ -756,19 +853,19 @@ const searchRecipes = {
     },
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
+    const knowledgeService = ctx.container.get('knowledgeService');
     const { keyword, category, language, knowledgeType, limit = 10 } = params;
 
     if (keyword) {
-      return recipeService.searchRecipes(keyword, { page: 1, pageSize: limit });
+      return knowledgeService.search(keyword, { page: 1, pageSize: limit });
     }
 
-    const filters = {};
+    const filters = { lifecycle: 'active' };
     if (category)      filters.category = category;
     if (language)      filters.language = language;
     if (knowledgeType) filters.knowledgeType = knowledgeType;
 
-    return recipeService.listRecipes(filters, { page: 1, pageSize: limit });
+    return knowledgeService.list(filters, { page: 1, pageSize: limit });
   },
 };
 
@@ -789,19 +886,20 @@ const searchCandidates = {
     },
   },
   handler: async (params, ctx) => {
-    const candidateService = ctx.container.get('candidateService');
+    const knowledgeService = ctx.container.get('knowledgeService');
     const { keyword, status, language, category, limit = 10 } = params;
 
     if (keyword) {
-      return candidateService.searchCandidates(keyword, { page: 1, pageSize: limit });
+      return knowledgeService.search(keyword, { page: 1, pageSize: limit });
     }
 
+    // V3: status 映射为 lifecycle
     const filters = {};
-    if (status)   filters.status = status;
+    if (status)   filters.lifecycle = status;
     if (language) filters.language = language;
     if (category) filters.category = category;
 
-    return candidateService.listCandidates(filters, { page: 1, pageSize: limit });
+    return knowledgeService.list(filters, { page: 1, pageSize: limit });
   },
 };
 
@@ -819,10 +917,13 @@ const getRecipeDetail = {
     required: ['recipeId'],
   },
   handler: async (params, ctx) => {
-    const recipeRepo = ctx.container.get('recipeRepository');
-    const recipe = await recipeRepo.findById(params.recipeId);
-    if (!recipe) return { error: `Recipe '${params.recipeId}' not found` };
-    return recipe;
+    const knowledgeService = ctx.container.get('knowledgeService');
+    try {
+      const entry = await knowledgeService.get(params.recipeId);
+      return typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+    } catch {
+      return { error: `Knowledge entry '${params.recipeId}' not found` };
+    }
   },
 };
 
@@ -834,13 +935,8 @@ const getProjectStats = {
   description: '获取项目知识库的整体统计：Recipe 数量/分类分布、候选项数量/状态分布、知识图谱节点/边数。',
   parameters: { type: 'object', properties: {} },
   handler: async (_params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    const candidateService = ctx.container.get('candidateService');
-
-    const [recipeStats, candidateStats] = await Promise.all([
-      recipeService.getRecipeStats(),
-      candidateService.getCandidateStats(),
-    ]);
+    const knowledgeService = ctx.container.get('knowledgeService');
+    const stats = await knowledgeService.getStats();
 
     // 尝试获取知识图谱统计
     let graphStats = null;
@@ -850,8 +946,7 @@ const getProjectStats = {
     } catch { /* KG not available */ }
 
     return {
-      recipes: recipeStats,
-      candidates: candidateStats,
+      knowledge: stats,
       knowledgeGraph: graphStats,
     };
   },
@@ -903,8 +998,9 @@ const searchKnowledge = {
     // 降级: RetrievalFunnel + 全量候选
     try {
       const funnel = ctx.container.get('retrievalFunnel');
-      const recipeRepo = ctx.container.get('recipeRepository');
-      const allRecipes = await recipeRepo.findAll?.() || [];
+      const knowledgeRepo = ctx.container.get('knowledgeRepository');
+      const allResult = await knowledgeRepo.findWithPagination({}, { page: 1, pageSize: 500 });
+      const allRecipes = allResult?.items || [];
 
       // 规范化为 funnel 输入格式
       const candidates = allRecipes.map(r => ({
@@ -991,7 +1087,7 @@ const extractRecipes = {
   },
   handler: async (params, ctx) => {
     if (!ctx.aiProvider) return { error: 'AI provider not available' };
-    const { targetName, files } = params;
+    const { targetName, files, comprehensive } = params;
 
     // 加载语言参考 Skill（如有），注入到 AI 提取 prompt
     let skillReference = null;
@@ -1027,6 +1123,7 @@ const extractRecipes = {
     const extractOpts = {};
     if (skillReference) extractOpts.skillReference = skillReference;
     if (astContext) extractOpts.astContext = astContext;
+    if (comprehensive) extractOpts.comprehensive = true;
 
     // 首选：使用当前 aiProvider
     try {
@@ -1072,12 +1169,10 @@ const enrichCandidate = {
   },
   handler: async (params, ctx) => {
     if (!ctx.aiProvider) return { error: 'AI provider not available' };
-    const candidateService = ctx.container.get('candidateService');
-    return candidateService.enrichCandidates(
-      params.candidateIds,
-      ctx.aiProvider,
-      { userId: 'agent' },
-    );
+    // V3: 使用 MCP handler enrichCandidates 的逻辑
+    const { enrichCandidates: enrichFn } = await import('../../external/mcp/handlers/candidate.js');
+    const result = await enrichFn(ctx, { candidateIds: params.candidateIds });
+    return result?.data || result;
   },
 };
 
@@ -1097,20 +1192,14 @@ const refineBootstrapCandidates = {
   },
   handler: async (params, ctx) => {
     if (!ctx.aiProvider) return { error: 'AI provider not available' };
-    const candidateService = ctx.container.get('candidateService');
-
-    // 接入 BootstrapTaskManager 双通道推送 refine:* 事件到前端
-    let onProgress = null;
-    try {
-      const taskManager = ctx.container.get('bootstrapTaskManager');
-      onProgress = (eventName, data) => taskManager.emitProgress(eventName, data);
-    } catch { /* optional: no realtime push */ }
-
-    return candidateService.refineBootstrapCandidates(
-      ctx.aiProvider,
-      { candidateIds: params.candidateIds, userPrompt: params.userPrompt, dryRun: params.dryRun, onProgress },
-      { userId: 'agent' },
-    );
+    // V3: 委托给 bootstrap handler 的 refine 逻辑
+    const { bootstrapRefine } = await import('../../external/mcp/handlers/bootstrap.js');
+    const result = await bootstrapRefine(ctx, {
+      candidateIds: params.candidateIds,
+      userPrompt: params.userPrompt,
+      dryRun: params.dryRun,
+    });
+    return result?.data || result;
   },
 };
 
@@ -1134,18 +1223,18 @@ const checkDuplicate = {
     const projectRoot = params.projectRoot || ctx.projectRoot;
     const threshold = params.threshold ?? 0.5;
 
-    // 如果提供 candidateId，从数据库读取候选信息
+    // 如果提供 candidateId，从数据库读取条目信息
     if (!cand && params.candidateId) {
       try {
-        const candidateRepo = ctx.container.get('candidateRepository');
-        const found = await candidateRepo.findById(params.candidateId);
+        const knowledgeService = ctx.container.get('knowledgeService');
+        const found = await knowledgeService.get(params.candidateId);
         if (found) {
-          const meta = found.metadata || {};
+          const json = typeof found.toJSON === 'function' ? found.toJSON() : found;
           cand = {
-            title: meta.title || '',
-            summary: meta.summary_cn || meta.summary || '',
-            code: found.code || '',
-            usageGuide: meta.usageGuide_cn || meta.usageGuide || '',
+            title: json.title || '',
+            summary: json.summary_cn || json.description || '',
+            code: json.content?.pattern || '',
+            usageGuide: json.usage_guide_cn || '',
           };
         }
       } catch { /* ignore */ }
@@ -1345,8 +1434,9 @@ const getRecommendations = {
     },
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    return recipeService.getRecommendations(params.limit || 10);
+    const knowledgeService = ctx.container.get('knowledgeService');
+    // V3: 推荐 = 活跃条目按使用量排序
+    return knowledgeService.list({ lifecycle: 'active' }, { page: 1, pageSize: params.limit || 10 });
   },
 };
 
@@ -1535,24 +1625,24 @@ const DIMENSION_DISPLAY_GROUP = {
 };
 
 // ────────────────────────────────────────────────────────────
-// Bootstrap 维度类型校验 — submit_candidate / submit_with_check 共用
+// Bootstrap 维度类型校验 — submit_knowledge / submit_with_check 共用
 // 基于 dimensionMeta 类型标注系统，而非关键词模糊匹配
 // ────────────────────────────────────────────────────────────
 
 /**
  * 基于维度元数据 (dimensionMeta) 检查提交是否合法
  * @param {{ id: string, outputType: 'candidate'|'skill'|'dual', allowedKnowledgeTypes: string[] }} dimensionMeta
- * @param {object} params - submit_candidate 的参数
+ * @param {object} params - submit_knowledge 的参数
  * @param {object} [logger]
  * @returns {{ status: string, reason: string } | null} 不合法返回 rejected，合法返回 null
  */
 function _checkDimensionType(dimensionMeta, params, logger) {
   // 1. Skill-only 维度不允许提交 Candidate
   if (dimensionMeta.outputType === 'skill') {
-    logger?.info(`[submit_candidate] ✗ rejected — dimension "${dimensionMeta.id}" is skill-only, cannot submit candidates`);
+    logger?.info(`[submit_knowledge] ✗ rejected — dimension "${dimensionMeta.id}" is skill-only, cannot submit candidates`);
     return {
       status: 'rejected',
-      reason: `当前维度 "${dimensionMeta.id}" 的输出类型为 skill-only，不允许调用 submit_candidate。请只在最终回复中提供 dimensionDigest JSON。`,
+      reason: `当前维度 "${dimensionMeta.id}" 的输出类型为 skill-only，不允许调用 submit_knowledge。请只在最终回复中提供 dimensionDigest JSON。`,
     };
   }
 
@@ -1561,7 +1651,7 @@ function _checkDimensionType(dimensionMeta, params, logger) {
   if (allowed.length > 0 && params.knowledgeType) {
     if (!allowed.includes(params.knowledgeType)) {
       const corrected = allowed[0];
-      logger?.warn(`[submit_candidate] knowledgeType "${params.knowledgeType}" → "${corrected}" (auto-corrected for dimension "${dimensionMeta.id}")`);
+      logger?.warn(`[submit_knowledge] knowledgeType "${params.knowledgeType}" → "${corrected}" (auto-corrected for dimension "${dimensionMeta.id}")`);
       params.knowledgeType = corrected;
     }
   }
@@ -1569,10 +1659,10 @@ function _checkDimensionType(dimensionMeta, params, logger) {
   return null;
 }
 
-// 16. submit_candidate
+// 16. submit_knowledge
 // ────────────────────────────────────────────────────────────
 const submitCandidate = {
-  name: 'submit_candidate',
+  name: 'submit_knowledge',
   description: '提交新的代码候选项到知识库审核队列。',
   parameters: {
     type: 'object',
@@ -1591,7 +1681,7 @@ const submitCandidate = {
     required: ['code', 'language', 'category', 'title'],
   },
   handler: async (params, ctx) => {
-    const candidateService = ctx.container.get('candidateService');
+    const knowledgeService = ctx.container.get('knowledgeService');
 
     // ── Bootstrap 维度类型校验 (基于 dimensionMeta 类型标注) ──
     const dimMeta = ctx._dimensionMeta;
@@ -1609,8 +1699,7 @@ const submitCandidate = {
         params.knowledgeType = dimMeta.allowedKnowledgeTypes[0];
       }
 
-      // Bootstrap 模式: 将 category 覆盖为展示分组 ID，确保前端按合并后的分组展示
-      // AI 可能填 "UI"/"Core" 等功能分类，但前端通过 BOOTSTRAP_DIM_LABELS 按展示分组分组
+      // Bootstrap 模式: 将 category 覆盖为展示分组 ID
       params.category = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
 
       // ── CandidateGuardrail 质量验证 (Bootstrap 模式) ──
@@ -1620,7 +1709,7 @@ const submitCandidate = {
       );
       const guardResult = guardrail.validate(params);
       if (!guardResult.valid) {
-        ctx.logger?.info(`[submit_candidate] ✗ guardrail rejected: ${guardResult.error}`);
+        ctx.logger?.info(`[submit_knowledge] ✗ guardrail rejected: ${guardResult.error}`);
         return {
           status: 'rejected',
           error: guardResult.error,
@@ -1629,11 +1718,10 @@ const submitCandidate = {
       }
     }
 
-    // 将所有顶层字段展开到 item — LLM 可能把 title/summary/tags 等
-    // 放在顶层而非 metadata 中（production prompt 指引）
+    // V3: 将顶层字段映射为 wire format
     const { code, language, category, source, reasoning, metadata, ...rest } = params;
 
-    // 防御性修复: AI 可能提交 reasoning.sources = [] 空数组，自动从 filePaths 补充
+    // 防御性修复: AI 可能提交 reasoning.sources = [] 空数组
     const finalReasoning = reasoning || { whyStandard: 'Submitted via ChatAgent', sources: ['agent'], confidence: 0.7 };
     if (Array.isArray(finalReasoning.sources) && finalReasoning.sources.length === 0) {
       const fallbackSources = params.filePaths || rest.filePaths;
@@ -1644,18 +1732,31 @@ const submitCandidate = {
       }
     }
 
-    const item = {
-      code,
-      language,
-      category,
-      ...rest,                     // 顶层扩展字段 (title, summary, knowledgeType, tags 等)
-      ...metadata,                 // metadata 对象 (如有)
-      reasoning: finalReasoning,
-    };
-    // Bootstrap 模式额外注入 targetName — 前端优先按 meta.targetName 分组
     const displayGroup = dimMeta ? (DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id) : null;
-    const extraMeta = (dimMeta && ctx.source === 'system') ? { targetName: displayGroup } : {};
-    return candidateService.createFromToolParams(item, source || 'agent', extraMeta, { userId: 'agent' });
+    const data = {
+      title:          rest.title || '',
+      description:    rest.summary || rest.description || '',
+      language:       language || '',
+      category:       category || 'general',
+      knowledge_type: rest.knowledgeType || 'code-pattern',
+      tags:           rest.tags || [],
+      summary_cn:     rest.summary || '',
+      source:         source || 'agent',
+      content: {
+        pattern:  code || '',
+        rationale: rest.rationale || '',
+      },
+      reasoning: {
+        why_standard: finalReasoning.whyStandard || finalReasoning.why_standard || 'Submitted via ChatAgent',
+        sources: finalReasoning.sources || ['agent'],
+        confidence: finalReasoning.confidence || 0.7,
+      },
+      ...(metadata || {}),
+    };
+    if (dimMeta && ctx.source === 'system' && displayGroup) {
+      data.tags = [...new Set([...(data.tags || []), displayGroup])];
+    }
+    return knowledgeService.create(data, { userId: 'agent' });
   },
 };
 
@@ -1673,8 +1774,8 @@ const approveCandidate = {
     required: ['candidateId'],
   },
   handler: async (params, ctx) => {
-    const candidateService = ctx.container.get('candidateService');
-    return candidateService.approveCandidate(params.candidateId, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.approve(params.candidateId, { userId: 'agent' });
   },
 };
 
@@ -1693,8 +1794,8 @@ const rejectCandidate = {
     required: ['candidateId', 'reason'],
   },
   handler: async (params, ctx) => {
-    const candidateService = ctx.container.get('candidateService');
-    return candidateService.rejectCandidate(params.candidateId, params.reason, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.reject(params.candidateId, params.reason, { userId: 'agent' });
   },
 };
 
@@ -1712,8 +1813,8 @@ const publishRecipe = {
     required: ['recipeId'],
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    return recipeService.publishRecipe(params.recipeId, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.publish(params.recipeId, { userId: 'agent' });
   },
 };
 
@@ -1732,8 +1833,8 @@ const deprecateRecipe = {
     required: ['recipeId', 'reason'],
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    return recipeService.deprecateRecipe(params.recipeId, params.reason, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.deprecate(params.recipeId, params.reason, { userId: 'agent' });
   },
 };
 
@@ -1752,8 +1853,8 @@ const updateRecipe = {
     required: ['recipeId', 'updates'],
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    return recipeService.updateRecipe(params.recipeId, params.updates, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.update(params.recipeId, params.updates, { userId: 'agent' });
   },
 };
 
@@ -1772,9 +1873,9 @@ const recordUsage = {
     required: ['recipeId'],
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
+    const knowledgeService = ctx.container.get('knowledgeService');
     const type = params.type || 'adoption';
-    await recipeService.incrementUsage(params.recipeId, type);
+    await knowledgeService.incrementUsage(params.recipeId, type);
     return { success: true, recipeId: params.recipeId, type };
   },
 };
@@ -1797,9 +1898,13 @@ const qualityScore = {
     let recipe = params.recipe;
 
     if (!recipe && params.recipeId) {
-      const recipeRepo = ctx.container.get('recipeRepository');
-      recipe = await recipeRepo.findById(params.recipeId);
-      if (!recipe) return { error: `Recipe '${params.recipeId}' not found` };
+      const knowledgeService = ctx.container.get('knowledgeService');
+      try {
+        const entry = await knowledgeService.get(params.recipeId);
+        recipe = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+      } catch {
+        return { error: `Knowledge entry '${params.recipeId}' not found` };
+      }
     }
     if (!recipe) return { error: 'Provide recipeId or recipe object' };
 
@@ -2113,13 +2218,8 @@ const knowledgeOverview = {
     const [statsResult, feedbackResult] = await Promise.all([
       (async () => {
         try {
-          const recipeService = ctx.container.get('recipeService');
-          const candidateService = ctx.container.get('candidateService');
-          const [rs, cs] = await Promise.all([
-            recipeService.getRecipeStats(),
-            candidateService.getCandidateStats(),
-          ]);
-          return { recipes: rs, candidates: cs };
+          const knowledgeService = ctx.container.get('knowledgeService');
+          return knowledgeService.getStats();
         } catch { return null; }
       })(),
       (async () => {
@@ -2132,8 +2232,7 @@ const knowledgeOverview = {
     ]);
 
     if (statsResult) {
-      result.recipes = statsResult.recipes;
-      result.candidates = statsResult.candidates;
+      result.knowledge = statsResult;
     }
 
     // 知识图谱统计
@@ -2159,7 +2258,7 @@ const knowledgeOverview = {
 // ────────────────────────────────────────────────────────────
 const submitWithCheck = {
   name: 'submit_with_check',
-  description: '安全提交候选：先执行查重检测，无重复则自动提交。如果发现高度相似 Recipe 则阻止并返回相似列表。一次调用完成 check_duplicate + submit_candidate。',
+  description: '安全提交候选：先执行查重检测，无重复则自动提交。如果发现高度相似 Recipe 则阻止并返回相似列表。一次调用完成 check_duplicate + submit_knowledge。',
   parameters: {
     type: 'object',
     properties: {
@@ -2176,7 +2275,7 @@ const submitWithCheck = {
     const { code, language, category, title, summary, threshold = 0.7 } = params;
     const projectRoot = ctx.projectRoot;
 
-    // ── Bootstrap 维度类型校验 (与 submit_candidate 共用逻辑) ──
+    // ── Bootstrap 维度类型校验 (与 submit_knowledge 共用逻辑) ──
     const dimMeta = ctx._dimensionMeta;
     if (dimMeta && ctx.source === 'system') {
       const rejected = _checkDimensionType(dimMeta, params, ctx.logger);
@@ -2214,28 +2313,33 @@ const submitWithCheck = {
       };
     }
 
-    // Step 2: 提交
+    // Step 2: 提交 (V3: 使用 knowledgeService.create)
     try {
-      const candidateService = ctx.container.get('candidateService');
+      const knowledgeService = ctx.container.get('knowledgeService');
       const { code: _c, language: _l, category: _cat, title: _t, summary: _s, threshold: _th, source: paramSource, reasoning: userReasoning, metadata, ...rest } = params;
-      const item = {
-        code,
-        language,
-        category,
-        ...rest,                     // 顶层扩展字段 (title, summary, knowledgeType, tags 等)
-        ...metadata,                 // metadata 对象 (如有)
-        title: title || '',
-        summary: summary || '',
-        reasoning: userReasoning || { whyStandard: 'Submitted via submit_with_check', sources: ['agent'], confidence: 0.7 },
+      const swcReasoning = userReasoning || { whyStandard: 'Submitted via submit_with_check', sources: ['agent'], confidence: 0.7 };
+      const data = {
+        title:          title || '',
+        description:    summary || '',
+        language:       language || '',
+        category:       category || 'general',
+        knowledge_type: rest.knowledgeType || 'code-pattern',
+        tags:           rest.tags || [],
+        summary_cn:     summary || '',
+        source:         paramSource || 'agent',
+        content: { pattern: code || '' },
+        reasoning: {
+          why_standard: swcReasoning.whyStandard || swcReasoning.why_standard || 'Submitted via submit_with_check',
+          sources: swcReasoning.sources || ['agent'],
+          confidence: swcReasoning.confidence || 0.7,
+        },
+        ...(metadata || {}),
       };
-      // Bootstrap 模式注入展示分组 targetName
-      const swcDisplayGroup = dimMeta ? (DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id) : null;
-      const swcExtraMeta = (dimMeta && ctx.source === 'system') ? { targetName: swcDisplayGroup } : {};
-      const created = await candidateService.createFromToolParams(item, paramSource || 'agent', swcExtraMeta, { userId: 'agent' });
+      const created = await knowledgeService.create(data, { userId: 'agent' });
 
       return {
         submitted: true,
-        candidate: created,
+        entry: typeof created.toJSON === 'function' ? created.toJSON() : created,
         similar: similar.length > 0 ? similar : [],
         _meta: {
           confidence: 'high',
@@ -2360,7 +2464,7 @@ const reviewMyOutput = {
   },
   handler: async (params, context) => {
     const submitted = (context._sessionToolCalls || []).filter(
-      tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check',
+      tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check',
     );
 
     if (submitted.length === 0) {