autosnippet 3.0.1 → 3.0.2

package/lib/service/chat/tools.js

@@ -82,9 +82,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import Logger from '../../infrastructure/logging/Logger.js';
+import { LanguageService } from '../../shared/LanguageService.js';
 import { findSimilarRecipes } from '../candidate/SimilarityService.js';
 import { CandidateGuardrail } from './CandidateGuardrail.js';
-import Logger from '../../infrastructure/logging/Logger.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -103,23 +104,37 @@ const PROJECT_SKILLS_DIR = path.resolve(PROJECT_ROOT, '.autosnippet', 'skills');
 // ────────────────────────────────────────────────────────────
 
 /** 三方库路径识别（与 bootstrap/shared/third-party-filter.js 对齐） */
-const THIRD_PARTY_RE = /(?:^|\/)(?:Pods|Carthage|\.build\/checkouts|vendor|ThirdParty|External|Submodules|DerivedData|include|node_modules|build)\/|(?:^|\/)(?:Masonry|AFNetworking|SDWebImage|MJRefresh|MJExtension|YYKit|YYModel|Lottie|FLEX|IQKeyboardManager|MBProgressHUD|SVProgressHUD|SnapKit|Kingfisher|Alamofire|Moya|ReactiveObjC|ReactiveCocoa|RxSwift|RxCocoa|FMDB|Realm|Mantle|JSONModel|CocoaLumberjack|CocoaAsyncSocket|SocketRocket|GPUImage|FBSDKCore|FBSDKLogin|FlatBuffers|Protobuf|PromiseKit|Charts|Hero)\//i;
+const THIRD_PARTY_RE =
+  /(?:^|\/)(?:Pods|Carthage|\.build\/checkouts|vendor|ThirdParty|External|Submodules|DerivedData|include|node_modules|build)\/|(?:^|\/)(?:Masonry|AFNetworking|SDWebImage|MJRefresh|MJExtension|YYKit|YYModel|Lottie|FLEX|IQKeyboardManager|MBProgressHUD|SVProgressHUD|SnapKit|Kingfisher|Alamofire|Moya|ReactiveObjC|ReactiveCocoa|RxSwift|RxCocoa|FMDB|Realm|Mantle|JSONModel|CocoaLumberjack|CocoaAsyncSocket|SocketRocket|GPUImage|FBSDKCore|FBSDKLogin|FlatBuffers|Protobuf|PromiseKit|Charts|Hero)\//i;
 
 /** 源码文件扩展名 */
 const SOURCE_EXT_RE = /\.(m|mm|swift|h|c|cpp|js|ts|jsx|tsx|py|rb|java|kt|go|rs)$/i;
 
 /** 声明行识别 — 用于对匹配行打分（与 bootstrap/shared/scanner.js 对齐） */
-const DECL_RE = /^\s*(@property\b|@interface\b|@protocol\b|@class\b|@synthesize\b|@dynamic\b|@end\b|NS_ASSUME_NONNULL|#import\b|#include\b|#define\b)/;
+const DECL_RE =
+  /^\s*(@property\b|@interface\b|@protocol\b|@class\b|@synthesize\b|@dynamic\b|@end\b|NS_ASSUME_NONNULL|#import\b|#include\b|#define\b)/;
 const TYPE_DECL_RE = /^\s*\w[\w<>*\s]+[\s*]+_?\w+\s*;$/;
 
 function _scoreSearchLine(line) {
   const t = line.trim();
-  if (DECL_RE.test(t)) return -2;
-  if (TYPE_DECL_RE.test(t)) return -1;
-  if (/^[-+]\s*\([^)]+\)\s*\w+[^{]*;\s*$/.test(t)) return -1;
-  if (/\[.*\w+.*\]/.test(t)) return 2;   // ObjC message send
-  if (/\w+\s*\(/.test(t)) return 2;       // function call
-  if (/\^\s*[{(]/.test(t)) return 1;      // block literal
+  if (DECL_RE.test(t)) {
+    return -2;
+  }
+  if (TYPE_DECL_RE.test(t)) {
+    return -1;
+  }
+  if (/^[-+]\s*\([^)]+\)\s*\w+[^{]*;\s*$/.test(t)) {
+    return -1;
+  }
+  if (/\[.*\w+.*\]/.test(t)) {
+    return 2; // ObjC message send
+  }
+  if (/\w+\s*\(/.test(t)) {
+    return 2; // function call
+  }
+  if (/\^\s*[{(]/.test(t)) {
+    return 1; // block literal
+  }
   return 0;
 }
 
@@ -133,7 +148,7 @@ async function _getProjectFiles(params, ctx) {
 
   let extFilter = null;
   if (fileFilter) {
-    const exts = fileFilter.split(',').map(e => e.trim().replace(/^\./, ''));
+    const exts = fileFilter.split(',').map((e) => e.trim().replace(/^\./, ''));
     extFilter = new RegExp(`\\.(${exts.join('|')})$`, 'i');
   }
 
@@ -142,11 +157,18 @@ async function _getProjectFiles(params, ctx) {
   let skippedThirdParty = 0;
 
   if (fileCache && Array.isArray(fileCache)) {
-    files = fileCache.filter(f => {
+    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;
+      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 {
@@ -158,25 +180,65 @@ async function _getProjectFiles(params, ctx) {
         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; } })());
+          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; }
+            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;
+            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;
+              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 unreadable files */
+            }
           }
         }
-      } catch { /* skip inaccessible dirs */ }
+      } catch {
+        /* skip inaccessible dirs */
+      }
     };
     walk(projectRoot);
   }
@@ -186,26 +248,34 @@ async function _getProjectFiles(params, ctx) {
 
 const searchProjectCode = {
   name: 'search_project_code',
-  description: '在用户项目源码中搜索指定模式。返回匹配的代码片段及上下文。' +
+  description:
+    '在用户项目源码中搜索指定模式。返回匹配的代码片段及上下文。' +
     '自动过滤三方库代码（Pods/Carthage/node_modules），优先返回实际使用行而非声明行。' +
     '适用场景：验证代码模式存在性、查找更多项目示例、理解项目中某个 API 的用法。' +
     '批量搜索：传入 patterns 数组可一次搜索多个关键词（每个关键词独立返回结果），减少工具调用次数。',
   parameters: {
     type: 'object',
     properties: {
-      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"' },
+      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: '匹配行前后的上下文行数，默认 3' },
-      maxResults:   { type: 'number', description: '每个 pattern 的最大返回结果数，默认 5' },
+      maxResults: { type: 'number', description: '每个 pattern 的最大返回结果数，默认 5' },
     },
     required: [],
   },
   handler: async (params, ctx) => {
     // ── 去重缓存初始化 ──
     const state = ctx._sharedState || ctx;
-    if (!state._searchCache) state._searchCache = new Map();
+    if (!state._searchCache) {
+      state._searchCache = new Map();
+    }
 
     // ── 批量模式：patterns 数组 ──
     if (Array.isArray(params.patterns) && params.patterns.length > 0) {
@@ -222,7 +292,7 @@ const searchProjectCode = {
         }
         const sub = await searchProjectCode.handler(
           { ...params, pattern: p, patterns: undefined },
-          ctx,
+          ctx
         );
         const entry = { matches: sub.matches || [], total: sub.total || 0 };
         state._searchCache.set(cacheKey, entry);
@@ -232,30 +302,46 @@ const searchProjectCode = {
         batchResults,
         patternsSearched: batchPatterns.length,
         searchedFiles: (await _getProjectFiles(params, ctx)).files.length,
-        ...(dedupCount > 0 ? { _deduped: dedupCount, hint: `${dedupCount} 个 pattern 命中缓存，请避免重复搜索相同关键词。` } : {}),
+        ...(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 = 3, maxResults = 5 } = params;
-    const projectRoot = ctx.projectRoot || process.cwd();
+    const pattern =
+      params.pattern || params.query || params.search || params.keyword || params.search_query;
+    const { isRegex = false, contextLines = 3, maxResults = 5 } = params;
+    const _projectRoot = ctx.projectRoot || process.cwd();
 
     if (!pattern || typeof pattern !== 'string') {
-      return { error: '参数错误: 请提供 pattern（搜索关键词或正则表达式）或 patterns 数组', 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}"，返回缓存结果。请搜索不同的关键词以获取新信息。` };
+      return {
+        ...cached,
+        _cached: true,
+        hint: `⚠ 已搜索过 "${pattern}"，返回缓存结果。请搜索不同的关键词以获取新信息。`,
+      };
     }
 
     // 构建搜索正则
     let searchRe;
     try {
-      searchRe = isRegex ? new RegExp(pattern, 'gi') : new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
+      searchRe = isRegex
+        ? new RegExp(pattern, 'gi')
+        : new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
     } catch (err) {
       return { error: `Invalid pattern: ${err.message}`, matches: [], total: 0 };
     }
@@ -267,17 +353,23 @@ const searchProjectCode = {
     let total = 0;
 
     for (const f of files) {
-      if (!f.content) continue;
+      if (!f.content) {
+        continue;
+      }
       // 快速预过滤
       searchRe.lastIndex = 0;
-      if (!searchRe.test(f.content)) continue;
+      if (!searchRe.test(f.content)) {
+        continue;
+      }
 
       const lines = f.content.split('\n');
       searchRe.lastIndex = 0;
 
       for (let i = 0; i < lines.length; i++) {
         searchRe.lastIndex = 0;
-        if (!searchRe.test(lines[i])) continue;
+        if (!searchRe.test(lines[i])) {
+          continue;
+        }
         total++;
 
         if (matches.length < maxResults) {
@@ -307,14 +399,16 @@ const searchProjectCode = {
       total,
       searchedFiles: files.length,
       skippedThirdParty,
-      ...((() => {
+      ...(() => {
         // P2.2: 搜索超限提示 — 引导使用 AST 工具
         state._searchCallCount = (state._searchCallCount || 0) + 1;
         if (state._searchCallCount > 12 && ctx.source === 'system') {
-          return { hint: `💡 你已搜索 ${state._searchCallCount} 次。考虑使用 get_class_info / get_class_hierarchy / get_project_overview 获取结构化信息，效率更高。` };
+          return {
+            hint: `💡 你已搜索 ${state._searchCallCount} 次。考虑使用 get_class_info / get_class_hierarchy / get_project_overview 获取结构化信息，效率更高。`,
+          };
         }
         return {};
-      })()),
+      })(),
     };
 
     // 缓存搜索结果
@@ -329,24 +423,34 @@ const searchProjectCode = {
 // ────────────────────────────────────────────────────────────
 const readProjectFile = {
   name: 'read_project_file',
-  description: '读取项目中指定文件的内容（部分或全部）。' +
+  description:
+    '读取项目中指定文件的内容（部分或全部）。' +
     '通常在 search_project_code 找到匹配后使用，获取更完整的上下文。' +
     '批量读取：传入 filePaths 数组可一次读取多个文件，减少工具调用次数。',
   parameters: {
     type: 'object',
     properties: {
-      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（批量模式下每个文件最多 100 行）' },
+      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（批量模式下每个文件最多 100 行）',
+      },
     },
     required: [],
   },
   handler: async (params, ctx) => {
     // ── 去重缓存初始化 ──
     const state = ctx._sharedState || ctx;
-    if (!state._readCache) state._readCache = new Map();
+    if (!state._readCache) {
+      state._readCache = new Map();
+    }
 
     // ── 批量模式：filePaths 数组 ──
     if (Array.isArray(params.filePaths) && params.filePaths.length > 0) {
@@ -361,23 +465,38 @@ const readProjectFile = {
           continue;
         }
         const sub = await readProjectFile.handler(
-          { ...params, filePath: fp, filePaths: undefined, maxLines: Math.min(params.maxLines || 100, 100) },
-          ctx,
+          {
+            ...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 };
+        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} 个文件命中缓存，请避免重复读取相同文件。` } : {}),
+        ...(dedupCount > 0
+          ? { _deduped: dedupCount, hint: `${dedupCount} 个文件命中缓存，请避免重复读取相同文件。` }
+          : {}),
       };
     }
 
     // 兼容各种参数名变体 (ToolRegistry 层已做 snake→camel 归一化,
     // 这里兜底处理漏网之鱼)
-    const filePath = params.filePath || params.path || params.file_path || params.filepath || params.file || params.filename;
+    const filePath =
+      params.filePath ||
+      params.path ||
+      params.file_path ||
+      params.filepath ||
+      params.file ||
+      params.filename;
     const { startLine = 1, maxLines = 200 } = params;
     const projectRoot = ctx.projectRoot || process.cwd();
 
@@ -388,7 +507,11 @@ const readProjectFile = {
     // ── 单文件去重检查 ──
     const readCacheKey = `${filePath}|${startLine}|${params.endLine || ''}|${maxLines}`;
     if (state._readCache.has(readCacheKey)) {
-      return { ...state._readCache.get(readCacheKey), _cached: true, hint: `⚠ 已读取过该文件相同行范围，返回缓存结果。如需其他行范围请指定不同的 startLine/endLine。` };
+      return {
+        ...state._readCache.get(readCacheKey),
+        _cached: true,
+        hint: `⚠ 已读取过该文件相同行范围，返回缓存结果。如需其他行范围请指定不同的 startLine/endLine。`,
+      };
     }
 
     // 安全检查: 禁止路径遍历
@@ -402,11 +525,14 @@ const readProjectFile = {
     let content = null;
 
     if (fileCache && Array.isArray(fileCache)) {
-      const cached = fileCache.find(f =>
-        (f.relativePath || f.path || '') === filePath ||
-        (f.relativePath || f.path || '') === normalized
+      const cached = fileCache.find(
+        (f) =>
+          (f.relativePath || f.path || '') === filePath ||
+          (f.relativePath || f.path || '') === normalized
       );
-      if (cached) content = cached.content;
+      if (cached) {
+        content = cached.content;
+      }
     }
 
     // 降级: 从磁盘读取
@@ -438,8 +564,7 @@ const readProjectFile = {
 
     // 推断语言
     const ext = path.extname(filePath).toLowerCase();
-    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';
+    const language = LanguageService.langFromExt(ext);
 
     const readResult = {
       filePath,
@@ -462,14 +587,18 @@ const readProjectFile = {
 // ────────────────────────────────────────────────────────────
 const listProjectStructure = {
   name: 'list_project_structure',
-  description: '列出项目目录结构和文件统计信息。不读取文件内容，只返回目录树和元数据。' +
+  description:
+    '列出项目目录结构和文件统计信息。不读取文件内容，只返回目录树和元数据。' +
     '适用场景：了解项目整体布局、识别关键目录、规划探索路径。',
   parameters: {
     type: 'object',
     properties: {
-      directory:    { type: 'string', description: '相对于项目根目录的子目录路径，默认根目录' },
-      depth:        { type: 'number', description: '目录展开深度，默认 3' },
-      includeStats: { type: 'boolean', description: '是否包含文件统计（语言分布、行数），默认 true' },
+      directory: { type: 'string', description: '相对于项目根目录的子目录路径，默认根目录' },
+      depth: { type: 'number', description: '目录展开深度，默认 3' },
+      includeStats: {
+        type: 'boolean',
+        description: '是否包含文件统计（语言分布、行数），默认 true',
+      },
     },
   },
   handler: async (params, ctx) => {
@@ -491,33 +620,36 @@ const listProjectStructure = {
     const treeLines = [];
     const stats = { totalFiles: 0, totalDirs: 0, byLanguage: {}, totalLines: 0 };
 
-    const LANG_MAP = {
-      '.m': 'Objective-C', '.mm': 'Objective-C++', '.h': 'Header',
-      '.swift': 'Swift', '.js': 'JavaScript', '.ts': 'TypeScript',
-      '.jsx': 'JSX', '.tsx': 'TSX', '.py': 'Python', '.java': 'Java',
-      '.kt': 'Kotlin', '.go': 'Go', '.rs': 'Rust', '.rb': 'Ruby',
-      '.c': 'C', '.cpp': 'C++',
-    };
-
     const walk = (dir, relBase, currentDepth, prefix) => {
-      if (currentDepth > depth) return;
+      if (currentDepth > depth) {
+        return;
+      }
       let entries;
-      try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
-      catch { return; }
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
 
       // 排序: 目录在前，文件在后
       entries.sort((a, b) => {
         const aIsDir = a.isDirectory();
         const bIsDir = b.isDirectory();
-        if (aIsDir !== bIsDir) return aIsDir ? -1 : 1;
+        if (aIsDir !== bIsDir) {
+          return aIsDir ? -1 : 1;
+        }
         return a.name.localeCompare(b.name);
       });
 
       // 过滤隐藏和三方
-      entries = entries.filter(e => {
-        if (e.name.startsWith('.')) return false;
+      entries = entries.filter((e) => {
+        if (e.name.startsWith('.')) {
+          return false;
+        }
         const rel = relBase ? `${relBase}/${e.name}` : e.name;
-        if (THIRD_PARTY_RE.test(rel + '/')) return false;
+        if (THIRD_PARTY_RE.test(`${rel}/`)) {
+          return false;
+        }
         return true;
       });
 
@@ -532,7 +664,11 @@ const listProjectStructure = {
         if (entry.isDirectory()) {
           // 计算子文件数
           let childCount = 0;
-          try { childCount = fs.readdirSync(fullPath).length; } catch { /* skip */ }
+          try {
+            childCount = fs.readdirSync(fullPath).length;
+          } catch {
+            /* skip */
+          }
           treeLines.push(`${prefix}${connector}${entry.name}/ (${childCount})`);
           stats.totalDirs++;
           walk(fullPath, rel, currentDepth + 1, childPrefix);
@@ -549,10 +685,12 @@ const listProjectStructure = {
                 lineCount = content.split('\n').length;
                 stats.totalLines += lineCount;
               }
-            } catch { /* skip */ }
+            } catch {
+              /* skip */
+            }
           }
-          const lang = LANG_MAP[ext];
-          if (lang) {
+          const lang = LanguageService.displayNameFromExt(ext);
+          if (lang !== ext) {
             stats.byLanguage[lang] = (stats.byLanguage[lang] || 0) + 1;
           }
           const sizeLabel = size > 1024 ? `${(size / 1024).toFixed(0)}KB` : `${size}B`;
@@ -580,31 +718,67 @@ const listProjectStructure = {
 /** 语言相关的声明提取正则 */
 const SUMMARY_EXTRACTORS = {
   objectivec: {
-    imports:      /^\s*(#import\s+.+|#include\s+.+|@import\s+\w+;)/gm,
-    declarations: /^\s*(@interface\s+\w+[\s:(].*|@protocol\s+\w+[\s<(].*|@implementation\s+\w+|typedef\s+(?:NS_ENUM|NS_OPTIONS)\s*\([^)]+\)\s*\{?)/gm,
-    methods:      /^\s*[-+]\s*\([^)]+\)\s*[^;{]+/gm,
-    properties:   /^\s*@property\s*\([^)]*\)\s*[^;]+;/gm,
+    imports: /^\s*(#import\s+.+|#include\s+.+|@import\s+\w+;)/gm,
+    declarations:
+      /^\s*(@interface\s+\w+[\s:(].*|@protocol\s+\w+[\s<(].*|@implementation\s+\w+|typedef\s+(?:NS_ENUM|NS_OPTIONS)\s*\([^)]+\)\s*\{?)/gm,
+    methods: /^\s*[-+]\s*\([^)]+\)\s*[^;{]+/gm,
+    properties: /^\s*@property\s*\([^)]*\)\s*[^;]+;/gm,
   },
   swift: {
-    imports:      /^\s*import\s+\w+/gm,
-    declarations: /^\s*(?:open|public|internal|fileprivate|private|final)?\s*(?:class|struct|enum|protocol|actor|extension)\s+\w+[^{]*/gm,
-    methods:      /^\s*(?:open|public|internal|fileprivate|private|override|static|class)?\s*func\s+\w+[^{]*/gm,
-    properties:   /^\s*(?:open|public|internal|fileprivate|private|static|class|lazy)?\s*(?:var|let)\s+\w+\s*:\s*[^={\n]+/gm,
+    imports: /^\s*import\s+\w+/gm,
+    declarations:
+      /^\s*(?:open|public|internal|fileprivate|private|final)?\s*(?:class|struct|enum|protocol|actor|extension)\s+\w+[^{]*/gm,
+    methods:
+      /^\s*(?:open|public|internal|fileprivate|private|override|static|class)?\s*func\s+\w+[^{]*/gm,
+    properties:
+      /^\s*(?:open|public|internal|fileprivate|private|static|class|lazy)?\s*(?:var|let)\s+\w+\s*:\s*[^={\n]+/gm,
   },
   javascript: {
-    imports:      /^\s*(?:import\s+.+from\s+['"].+['"]|const\s+\{?\s*\w+.*\}?\s*=\s*require\s*\(.+\))/gm,
+    imports: /^\s*(?:import\s+.+from\s+['"].+['"]|const\s+\{?\s*\w+.*\}?\s*=\s*require\s*\(.+\))/gm,
     declarations: /^\s*(?:export\s+)?(?:default\s+)?(?:class|function|const|let|var)\s+\w+/gm,
-    methods:      /^\s*(?:async\s+)?(?:static\s+)?(?:get\s+|set\s+)?(?:#?\w+)\s*\([^)]*\)\s*\{/gm,
+    methods: /^\s*(?:async\s+)?(?:static\s+)?(?:get\s+|set\s+)?(?:#?\w+)\s*\([^)]*\)\s*\{/gm,
   },
   typescript: {
-    imports:      /^\s*import\s+.+from\s+['"].+['"]/gm,
-    declarations: /^\s*(?:export\s+)?(?:default\s+)?(?:class|interface|type|enum|function|const|let|var|abstract\s+class)\s+\w+/gm,
-    methods:      /^\s*(?:async\s+)?(?:static\s+)?(?:public|private|protected)?\s*(?:get\s+|set\s+)?(?:#?\w+)\s*\([^)]*\)\s*[:{]/gm,
+    imports: /^\s*import\s+.+from\s+['"].+['"]/gm,
+    declarations:
+      /^\s*(?:export\s+)?(?:default\s+)?(?:class|interface|type|enum|function|const|let|var|abstract\s+class)\s+\w+/gm,
+    methods:
+      /^\s*(?:async\s+)?(?:static\s+)?(?:public|private|protected)?\s*(?:get\s+|set\s+)?(?:#?\w+)\s*\([^)]*\)\s*[:{]/gm,
   },
   python: {
-    imports:      /^\s*(?:import\s+\w+|from\s+\w+\s+import\s+.+)/gm,
+    imports: /^\s*(?:import\s+\w+|from\s+\w+\s+import\s+.+)/gm,
     declarations: /^\s*class\s+\w+[^:]*:/gm,
-    methods:      /^\s*(?:async\s+)?def\s+\w+\s*\([^)]*\)/gm,
+    methods: /^\s*(?:async\s+)?def\s+\w+\s*\([^)]*\)/gm,
+  },
+  go: {
+    imports: /^\s*(?:import\s+"[^"]+"|import\s+\w+\s+"[^"]+")/gm,
+    declarations:
+      /^\s*(?:type\s+\w+\s+(?:struct|interface|func)\b.*)/gm,
+    methods:
+      /^\s*func\s+(?:\(\s*\w+\s+\*?\w+\s*\)\s+)?\w+\s*\([^)]*\)[^{]*/gm,
+  },
+  java: {
+    imports: /^\s*import\s+(?:static\s+)?[\w.]+\*?;/gm,
+    declarations:
+      /^\s*(?:public|private|protected)?\s*(?:abstract|final|static)?\s*(?:class|interface|enum|record|@interface)\s+\w+/gm,
+    methods:
+      /^\s*(?:public|private|protected)?\s*(?:abstract|static|final|synchronized|default)?\s*(?:<[^>]+>\s+)?\w[\w<>\[\],\s]*\s+\w+\s*\([^)]*\)/gm,
+  },
+  kotlin: {
+    imports: /^\s*import\s+[\w.]+/gm,
+    declarations:
+      /^\s*(?:open|abstract|data|sealed|inner|value|inline)?\s*(?:class|interface|object|enum\s+class|fun\s+interface)\s+\w+/gm,
+    methods:
+      /^\s*(?:override\s+)?(?:suspend\s+)?(?:fun|val|var)\s+(?:<[^>]+>\s+)?\w+/gm,
+  },
+  dart: {
+    imports: /^\s*import\s+['"][^'"]+['"];?/gm,
+    declarations:
+      /^\s*(?:abstract\s+|sealed\s+)?(?:class|mixin|extension|enum|typedef)\s+\w+[^{]*/gm,
+    methods:
+      /^\s*(?:@override\s+)?(?:static\s+)?(?:Future|Stream|void|\w[\w<>?]*)?\s+\w+\s*\([^)]*\)/gm,
+    properties:
+      /^\s*(?:static\s+)?(?:final\s+|late\s+|const\s+)?(?:\w[\w<>?]*)\s+\w+\s*[;=]/gm,
   },
 };
 // Alias variants
@@ -614,7 +788,8 @@ SUMMARY_EXTRACTORS.tsx = SUMMARY_EXTRACTORS.typescript;
 
 const getFileSummary = {
   name: 'get_file_summary',
-  description: '获取文件的结构摘要（导入、声明、方法签名），不包含实现代码。' +
+  description:
+    '获取文件的结构摘要（导入、声明、方法签名），不包含实现代码。' +
     '比 read_project_file 更轻量，适合快速了解文件角色和 API。',
   parameters: {
     type: 'object',
@@ -642,11 +817,14 @@ const getFileSummary = {
     let content = null;
 
     if (fileCache && Array.isArray(fileCache)) {
-      const cached = fileCache.find(f =>
-        (f.relativePath || f.path || '') === filePath ||
-        (f.relativePath || f.path || '') === normalized
+      const cached = fileCache.find(
+        (f) =>
+          (f.relativePath || f.path || '') === filePath ||
+          (f.relativePath || f.path || '') === normalized
       );
-      if (cached) content = cached.content;
+      if (cached) {
+        content = cached.content;
+      }
     }
 
     if (content === null) {
@@ -663,8 +841,7 @@ const getFileSummary = {
 
     // 推断语言
     const ext = path.extname(filePath).toLowerCase();
-    const langMap = { '.m': 'objectivec', '.mm': 'objectivec++', '.h': 'objectivec', '.swift': 'swift', '.js': 'javascript', '.ts': 'typescript', '.jsx': 'jsx', '.tsx': 'tsx', '.py': 'python', '.java': 'unknown', '.kt': 'unknown', '.go': 'unknown', '.rs': 'unknown', '.rb': 'unknown' };
-    const language = langMap[ext] || 'unknown';
+    const language = LanguageService.langFromExt(ext);
     const extractor = SUMMARY_EXTRACTORS[language];
 
     const result = {
@@ -694,10 +871,18 @@ const getFileSummary = {
       return matches;
     };
 
-    if (extractor.imports)      result.imports      = extract(extractor.imports);
-    if (extractor.declarations) result.declarations = extract(extractor.declarations);
-    if (extractor.methods)      result.methods      = extract(extractor.methods).slice(0, 50); // 限制数量
-    if (extractor.properties)   result.properties   = extract(extractor.properties).slice(0, 30);
+    if (extractor.imports) {
+      result.imports = extract(extractor.imports);
+    }
+    if (extractor.declarations) {
+      result.declarations = extract(extractor.declarations);
+    }
+    if (extractor.methods) {
+      result.methods = extract(extractor.methods).slice(0, 50); // 限制数量
+    }
+    if (extractor.properties) {
+      result.properties = extract(extractor.properties).slice(0, 30);
+    }
 
     return result;
   },
@@ -708,14 +893,15 @@ const getFileSummary = {
 // ────────────────────────────────────────────────────────────
 const semanticSearchCode = {
   name: 'semantic_search_code',
-  description: '在知识库中进行语义搜索。使用自然语言描述你要查找的代码模式或概念，' +
+  description:
+    '在知识库中进行语义搜索。使用自然语言描述你要查找的代码模式或概念，' +
     '返回语义最相关的知识条目。比关键词搜索更适合模糊/概念性查询。' +
     '示例: "网络请求的错误处理策略"、"线程安全的单例实现"',
   parameters: {
     type: 'object',
     properties: {
-      query:    { type: 'string', description: '自然语言搜索查询' },
-      topK:     { type: 'number', description: '返回结果数量，默认 5' },
+      query: { type: 'string', description: '自然语言搜索查询' },
+      topK: { type: 'number', description: '返回结果数量，默认 5' },
       category: { type: 'string', description: '按分类过滤 (View/Service/Network/Model 等)' },
       language: { type: 'string', description: '按语言过滤 (swift/objectivec 等)' },
     },
@@ -734,18 +920,23 @@ const semanticSearchCode = {
     let searchEngine = null;
     try {
       searchEngine = ctx.container?.get('searchEngine');
-    } catch { /* not available */ }
+    } catch {
+      /* not available */
+    }
 
     if (!searchEngine) {
       // 尝试获取 VectorStore 直接搜索
       let vectorStore = null;
       try {
         vectorStore = ctx.container?.get('vectorStore');
-      } catch { /* not available */ }
+      } catch {
+        /* not available */
+      }
 
       if (!vectorStore) {
         return {
-          error: '语义搜索不可用: SearchEngine 和 VectorStore 均未初始化。可使用 search_project_code 进行关键词搜索替代。',
+          error:
+            '语义搜索不可用: SearchEngine 和 VectorStore 均未初始化。可使用 search_project_code 进行关键词搜索替代。',
           fallbackTool: 'search_project_code',
         };
       }
@@ -754,20 +945,26 @@ const semanticSearchCode = {
       let aiProvider = null;
       try {
         aiProvider = ctx.container?.get('aiProvider');
-      } catch { /* not available */ }
+      } catch {
+        /* not available */
+      }
 
       if (!aiProvider || typeof aiProvider.generateEmbedding !== 'function') {
         // 向量搜索需要 embedding，降级到关键词匹配
         const filter = {};
-        if (category) filter.category = category;
-        if (language) filter.language = language;
+        if (category) {
+          filter.category = category;
+        }
+        if (language) {
+          filter.language = language;
+        }
 
         const results = await vectorStore.hybridSearch([], query, { topK, filter });
         return {
           mode: 'keyword-fallback',
           query,
           message: 'AI Provider 不支持 embedding，已降级到关键词匹配',
-          results: results.map(r => ({
+          results: results.map((r) => ({
             id: r.item.id,
             content: (r.item.content || '').slice(0, 500),
             score: Math.round(r.score * 100) / 100,
@@ -780,14 +977,18 @@ const semanticSearchCode = {
       try {
         const embedding = await aiProvider.generateEmbedding(query);
         const filter = {};
-        if (category) filter.category = category;
-        if (language) filter.language = language;
+        if (category) {
+          filter.category = category;
+        }
+        if (language) {
+          filter.language = language;
+        }
 
         const results = await vectorStore.hybridSearch(embedding, query, { topK, filter });
         return {
           mode: 'vector',
           query,
-          results: results.map(r => ({
+          results: results.map((r) => ({
             id: r.item.id,
             content: (r.item.content || '').slice(0, 500),
             score: Math.round(r.score * 100) / 100,
@@ -811,8 +1012,12 @@ const semanticSearchCode = {
       const actualMode = result?.mode || 'bm25';
 
       // 应用过滤
-      if (category) items = items.filter(i => (i.category || '').toLowerCase() === category.toLowerCase());
-      if (language) items = items.filter(i => (i.language || '').toLowerCase() === language.toLowerCase());
+      if (category) {
+        items = items.filter((i) => (i.category || '').toLowerCase() === category.toLowerCase());
+      }
+      if (language) {
+        items = items.filter((i) => (i.language || '').toLowerCase() === language.toLowerCase());
+      }
       items = items.slice(0, topK);
 
       return {
@@ -820,7 +1025,7 @@ const semanticSearchCode = {
         query,
         degraded: actualMode !== 'semantic',
         totalResults: items.length,
-        results: items.map(item => ({
+        results: items.map((item) => ({
           id: item.id,
           title: item.title || '',
           content: (item.content || item.description || '').slice(0, 500),
@@ -841,15 +1046,22 @@ const semanticSearchCode = {
 // ────────────────────────────────────────────────────────────
 const searchRecipes = {
   name: 'search_recipes',
-  description: '搜索知识库中的 Recipe（代码片段/最佳实践/架构模式）。支持关键词搜索和按分类/语言/类型筛选。',
+  description:
+    '搜索知识库中的 Recipe（代码片段/最佳实践/架构模式）。支持关键词搜索和按分类/语言/类型筛选。',
   parameters: {
     type: 'object',
     properties: {
-      keyword:       { type: 'string', description: '搜索关键词' },
-      category:      { type: 'string', description: '分类过滤 (View/Service/Tool/Model/Network/Storage/UI/Utility)' },
-      language:      { type: 'string', description: '编程语言过滤 (swift/objectivec/typescript 等)' },
-      knowledgeType: { type: 'string', description: '知识类型过滤 (code-standard/code-pattern/architecture/best-practice 等)' },
-      limit:         { type: 'number', description: '返回数量上限，默认 10' },
+      keyword: { type: 'string', description: '搜索关键词' },
+      category: {
+        type: 'string',
+        description: '分类过滤 (View/Service/Tool/Model/Network/Storage/UI/Utility)',
+      },
+      language: { type: 'string', description: '编程语言过滤 (swift/objectivec/typescript 等)' },
+      knowledgeType: {
+        type: 'string',
+        description: '知识类型过滤 (code-standard/code-pattern/architecture/best-practice 等)',
+      },
+      limit: { type: 'number', description: '返回数量上限，默认 10' },
     },
   },
   handler: async (params, ctx) => {
@@ -861,9 +1073,15 @@ const searchRecipes = {
     }
 
     const filters = { lifecycle: 'active' };
-    if (category)      filters.category = category;
-    if (language)      filters.language = language;
-    if (knowledgeType) filters.knowledgeType = knowledgeType;
+    if (category) {
+      filters.category = category;
+    }
+    if (language) {
+      filters.language = language;
+    }
+    if (knowledgeType) {
+      filters.knowledgeType = knowledgeType;
+    }
 
     return knowledgeService.list(filters, { page: 1, pageSize: limit });
   },
@@ -878,11 +1096,11 @@ const searchCandidates = {
   parameters: {
     type: 'object',
     properties: {
-      keyword:  { type: 'string', description: '搜索关键词' },
-      status:   { type: 'string', description: '状态过滤 (pending/approved/rejected/applied)' },
+      keyword: { type: 'string', description: '搜索关键词' },
+      status: { type: 'string', description: '状态过滤 (pending/approved/rejected/applied)' },
       language: { type: 'string', description: '编程语言过滤' },
       category: { type: 'string', description: '分类过滤' },
-      limit:    { type: 'number', description: '返回数量上限，默认 10' },
+      limit: { type: 'number', description: '返回数量上限，默认 10' },
     },
   },
   handler: async (params, ctx) => {
@@ -895,9 +1113,15 @@ const searchCandidates = {
 
     // V3: status 映射为 lifecycle
     const filters = {};
-    if (status)   filters.lifecycle = status;
-    if (language) filters.language = language;
-    if (category) filters.category = category;
+    if (status) {
+      filters.lifecycle = status;
+    }
+    if (language) {
+      filters.language = language;
+    }
+    if (category) {
+      filters.category = category;
+    }
 
     return knowledgeService.list(filters, { page: 1, pageSize: limit });
   },
@@ -932,7 +1156,8 @@ const getRecipeDetail = {
 // ────────────────────────────────────────────────────────────
 const getProjectStats = {
   name: 'get_project_stats',
-  description: '获取项目知识库的整体统计：Recipe 数量/分类分布、候选项数量/状态分布、知识图谱节点/边数。',
+  description:
+    '获取项目知识库的整体统计：Recipe 数量/分类分布、候选项数量/状态分布、知识图谱节点/边数。',
   parameters: { type: 'object', properties: {} },
   handler: async (_params, ctx) => {
     const knowledgeService = ctx.container.get('knowledgeService');
@@ -943,7 +1168,9 @@ const getProjectStats = {
     try {
       const kgService = ctx.container.get('knowledgeGraphService');
       graphStats = kgService.getStats();
-    } catch { /* KG not available */ }
+    } catch {
+      /* KG not available */
+    }
 
     return {
       knowledge: stats,
@@ -962,7 +1189,7 @@ const searchKnowledge = {
     type: 'object',
     properties: {
       query: { type: 'string', description: '搜索查询' },
-      topK:  { type: 'number', description: '返回结果数，默认 5' },
+      topK: { type: 'number', description: '返回结果数，默认 5' },
     },
     required: ['query'],
   },
@@ -977,9 +1204,10 @@ const searchKnowledge = {
         const enriched = results.slice(0, topK).map((r, i) => ({
           ...r,
           reasoning: {
-            whyRelevant: r.score != null
-              ? `匹配分 ${(r.score * 100).toFixed(0)}%` + (r.matchType ? ` (${r.matchType})` : '')
-              : '语义相关',
+            whyRelevant:
+              r.score != null
+                ? `匹配分 ${(r.score * 100).toFixed(0)}%${r.matchType ? ` (${r.matchType})` : ''}`
+                : '语义相关',
             rank: i + 1,
           },
         }));
@@ -993,7 +1221,9 @@ const searchKnowledge = {
           },
         };
       }
-    } catch { /* SearchEngine not available */ }
+    } catch {
+      /* SearchEngine not available */
+    }
 
     // 降级: RetrievalFunnel + 全量候选
     try {
@@ -1003,7 +1233,7 @@ const searchKnowledge = {
       const allRecipes = allResult?.items || [];
 
       // 规范化为 funnel 输入格式
-      const candidates = allRecipes.map(r => ({
+      const candidates = allRecipes.map((r) => ({
         id: r.id,
         title: r.title,
         content: r.content || r.code || '',
@@ -1017,9 +1247,19 @@ const searchKnowledge = {
         const results = await funnel.execute(query, candidates, {});
         return { source: 'retrievalFunnel', results: results.slice(0, topK) };
       }
-    } catch { /* RetrievalFunnel not available */ }
+    } catch {
+      /* RetrievalFunnel not available */
+    }
 
-    return { source: 'none', results: [], message: 'No search engine available', _meta: { confidence: 'none', hint: '搜索引擎不可用。请确认向量索引已构建（rebuild_index）。' } };
+    return {
+      source: 'none',
+      results: [],
+      message: 'No search engine available',
+      _meta: {
+        confidence: 'none',
+        hint: '搜索引擎不可用。请确认向量索引已构建（rebuild_index）。',
+      },
+    };
   },
 };
 
@@ -1033,7 +1273,11 @@ const getRelatedRecipes = {
     type: 'object',
     properties: {
       recipeId: { type: 'string', description: 'Recipe ID' },
-      relation: { type: 'string', description: '关系类型过滤 (requires/extends/enforces/depends_on/inherits/implements/calls/prerequisite)，不传则返回全部关系' },
+      relation: {
+        type: 'string',
+        description:
+          '关系类型过滤 (requires/extends/enforces/depends_on/inherits/implements/calls/prerequisite)，不传则返回全部关系',
+      },
     },
     required: ['recipeId'],
   },
@@ -1060,13 +1304,15 @@ const summarizeCode = {
   parameters: {
     type: 'object',
     properties: {
-      code:     { type: 'string', description: '代码内容' },
+      code: { type: 'string', description: '代码内容' },
       language: { type: 'string', description: '编程语言' },
     },
     required: ['code'],
   },
   handler: async (params, ctx) => {
-    if (!ctx.aiProvider) return { error: 'AI provider not available' };
+    if (!ctx.aiProvider) {
+      return { error: 'AI provider not available' };
+    }
     return ctx.aiProvider.summarize(params.code, params.language);
   },
 };
@@ -1076,17 +1322,27 @@ const summarizeCode = {
 // ────────────────────────────────────────────────────────────
 const extractRecipes = {
   name: 'extract_recipes',
-  description: '从源码文件中批量提取可复用的 Recipe 结构（代码标准、设计模式、最佳实践）。支持自动 provider fallback。',
+  description:
+    '从源码文件中批量提取可复用的 Recipe 结构（代码标准、设计模式、最佳实践）。支持自动 provider fallback。',
   parameters: {
     type: 'object',
     properties: {
       targetName: { type: 'string', description: 'SPM Target / 模块名称' },
-      files:      { type: 'array',  items: { type: 'object', properties: { name: { type: 'string' }, content: { type: 'string' } } }, description: '文件数组 [{name, content}]' },
+      files: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: { name: { type: 'string' }, content: { type: 'string' } },
+        },
+        description: '文件数组 [{name, content}]',
+      },
     },
     required: ['targetName', 'files'],
   },
   handler: async (params, ctx) => {
-    if (!ctx.aiProvider) return { error: 'AI provider not available' };
+    if (!ctx.aiProvider) {
+      return { error: 'AI provider not available' };
+    }
     const { targetName, files, comprehensive } = params;
 
     // 加载语言参考 Skill（如有），注入到 AI 提取 prompt
@@ -1097,20 +1353,22 @@ const extractRecipes = {
       const primaryLang = langProfile?.primaryLanguage;
       if (primaryLang) {
         const skillCtx = loadBootstrapSkills(primaryLang);
-        skillReference = skillCtx.languageSkill
-          ? skillCtx.languageSkill.substring(0, 2000)
-          : null;
+        skillReference = skillCtx.languageSkill ? skillCtx.languageSkill.substring(0, 2000) : null;
       }
-    } catch { /* Skills not available, proceed without */ }
+    } catch {
+      /* Skills not available, proceed without */
+    }
 
     // AST 代码结构分析（如可用），注入到 AI 提取 prompt
     let astContext = null;
     try {
-      const { analyzeProject, generateContextForAgent, isAvailable } = await import('../../../core/AstAnalyzer.js');
+      const { analyzeProject, generateContextForAgent, isAvailable } = await import(
+        '../../../core/AstAnalyzer.js'
+      );
       if (isAvailable()) {
         const sourceFiles = files
-          .filter(f => /\.(m|mm|h|swift|js|ts|jsx|tsx)$/.test(f.name || ''))
-          .map(f => ({ path: f.name, source: f.content }));
+          .filter((f) => /\.(m|mm|h|swift|js|ts|jsx|tsx)$/.test(f.name || ''))
+          .map((f) => ({ path: f.name, source: f.content }));
         if (sourceFiles.length > 0) {
           const langProfile2 = ctx.aiProvider._detectLanguageProfile?.(files);
           const lang = langProfile2?.primaryLanguage === 'swift' ? 'swift' : 'objc';
@@ -1118,12 +1376,20 @@ const extractRecipes = {
           astContext = generateContextForAgent(summary);
         }
       }
-    } catch { /* AST not available, proceed without */ }
+    } catch {
+      /* AST not available, proceed without */
+    }
 
     const extractOpts = {};
-    if (skillReference) extractOpts.skillReference = skillReference;
-    if (astContext) extractOpts.astContext = astContext;
-    if (comprehensive) extractOpts.comprehensive = true;
+    if (skillReference) {
+      extractOpts.skillReference = skillReference;
+    }
+    if (astContext) {
+      extractOpts.astContext = astContext;
+    }
+    if (comprehensive) {
+      extractOpts.comprehensive = true;
+    }
 
     // 首选：使用当前 aiProvider
     let recipes;
@@ -1145,23 +1411,41 @@ const extractRecipes = {
               fallbackUsed = fbName;
               recovered = true;
               break;
-            } catch { /* next fallback */ }
+            } catch {
+              /* next fallback */
+            }
           }
         }
-      } catch { /* AiFactory not available */ }
-      if (!recovered) throw primaryErr;
+      } catch {
+        /* AiFactory not available */
+      }
+      if (!recovered) {
+        throw primaryErr;
+      }
     }
 
-    if (!Array.isArray(recipes)) recipes = [];
+    if (!Array.isArray(recipes)) {
+      recipes = [];
+    }
     if (recipes.length === 0) {
-      ctx.logger?.warn?.(`[extract_recipes] AI returned 0 recipes for ${targetName} (${files.length} files)`);
+      ctx.logger?.warn?.(
+        `[extract_recipes] AI returned 0 recipes for ${targetName} (${files.length} files)`
+      );
     }
 
     // ── V3 直透：AI 已输出完整 V3 结构，仅做来源标记 + 程序化评分/标签 ──
     let qualityScorer = null;
     let recipeExtractor = null;
-    try { qualityScorer = ctx.container?.get?.('qualityScorer'); } catch { /* not available */ }
-    try { recipeExtractor = ctx.container?.get?.('recipeExtractor'); } catch { /* not available */ }
+    try {
+      qualityScorer = ctx.container?.get?.('qualityScorer');
+    } catch {
+      /* not available */
+    }
+    try {
+      recipeExtractor = ctx.container?.get?.('recipeExtractor');
+    } catch {
+      /* not available */
+    }
 
     for (const recipe of recipes) {
       // 来源 & 生命周期（非 AI 职责）
@@ -1173,15 +1457,23 @@ const extractRecipes = {
       if (recipeExtractor && codeText) {
         try {
           const extracted = recipeExtractor.extractFromContent(
-            codeText, `${recipe.title || 'unknown'}.${recipe.language || 'swift'}`, ''
+            codeText,
+            `${recipe.title || 'unknown'}.${recipe.language || 'unknown'}`,
+            ''
           );
           if (extracted.semanticTags?.length > 0) {
             recipe.tags = [...new Set([...(recipe.tags || []), ...extracted.semanticTags])];
           }
-          if ((!recipe.category || recipe.category === 'Utility') && extracted.category && extracted.category !== 'general') {
+          if (
+            (!recipe.category || recipe.category === 'Utility') &&
+            extracted.category &&
+            extracted.category !== 'general'
+          ) {
             recipe.category = extracted.category;
           }
-        } catch { /* best effort */ }
+        } catch {
+          /* best effort */
+        }
       }
 
       // QualityScorer 评分 → quality 结构化
@@ -1195,12 +1487,16 @@ const extractRecipes = {
             overall: scoreResult.score ?? 0,
             grade: scoreResult.grade || '',
           };
-        } catch { /* best effort */ }
+        } catch {
+          /* best effort */
+        }
       }
     }
 
     const result = { targetName, extracted: recipes.length, recipes };
-    if (fallbackUsed) result.fallbackUsed = fallbackUsed;
+    if (fallbackUsed) {
+      result.fallbackUsed = fallbackUsed;
+    }
     return result;
   },
 };
@@ -1210,16 +1506,23 @@ const extractRecipes = {
 // ────────────────────────────────────────────────────────────
 const enrichCandidate = {
   name: 'enrich_candidate',
-  description: '① 结构补齐 — 自动填充缺失的结构性语义字段（rationale/knowledgeType/complexity/scope/steps/constraints）。批量处理，只填空不覆盖。建议在 refine_bootstrap_candidates 之前执行。',
+  description:
+    '① 结构补齐 — 自动填充缺失的结构性语义字段（rationale/knowledgeType/complexity/scope/steps/constraints）。批量处理，只填空不覆盖。建议在 refine_bootstrap_candidates 之前执行。',
   parameters: {
     type: 'object',
     properties: {
-      candidateIds: { type: 'array', items: { type: 'string' }, description: '候选 ID 列表 (最多 20 个)' },
+      candidateIds: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '候选 ID 列表 (最多 20 个)',
+      },
     },
     required: ['candidateIds'],
   },
   handler: async (params, ctx) => {
-    if (!ctx.aiProvider) return { error: 'AI provider not available' };
+    if (!ctx.aiProvider) {
+      return { error: 'AI provider not available' };
+    }
     // V3: 使用 MCP handler enrichCandidates 的逻辑
     const { enrichCandidates: enrichFn } = await import('../../external/mcp/handlers/candidate.js');
     const result = await enrichFn(ctx, { candidateIds: params.candidateIds });
@@ -1232,17 +1535,27 @@ const enrichCandidate = {
 // ────────────────────────────────────────────────────────────
 const refineBootstrapCandidates = {
   name: 'refine_bootstrap_candidates',
-  description: '② 内容润色 — 逐条精炼 Bootstrap 候选的内容质量：改善 summary、补充架构 insight、推断 relations 关联、调整 confidence、丰富 tags。建议在 enrich_candidate 之后执行。',
+  description:
+    '② 内容润色 — 逐条精炼 Bootstrap 候选的内容质量：改善 summary、补充架构 insight、推断 relations 关联、调整 confidence、丰富 tags。建议在 enrich_candidate 之后执行。',
   parameters: {
     type: 'object',
     properties: {
-      candidateIds: { type: 'array', items: { type: 'string' }, description: '指定候选 ID 列表（可选，默认全部 bootstrap 候选）' },
-      userPrompt: { type: 'string', description: '用户自定义润色提示词，指导 AI 润色方向（如“侧重描述线程安全注意事项”）' },
+      candidateIds: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '指定候选 ID 列表（可选，默认全部 bootstrap 候选）',
+      },
+      userPrompt: {
+        type: 'string',
+        description: '用户自定义润色提示词，指导 AI 润色方向（如“侧重描述线程安全注意事项”）',
+      },
       dryRun: { type: 'boolean', description: '仅预览 AI 润色结果，不写入数据库' },
     },
   },
   handler: async (params, ctx) => {
-    if (!ctx.aiProvider) return { error: 'AI provider not available' };
+    if (!ctx.aiProvider) {
+      return { error: 'AI provider not available' };
+    }
     // V3: 委托给 bootstrap handler 的 refine 逻辑
     const { bootstrapRefine } = await import('../../external/mcp/handlers/bootstrap.js');
     const result = await bootstrapRefine(ctx, {
@@ -1259,14 +1572,15 @@ const refineBootstrapCandidates = {
 // ────────────────────────────────────────────────────────────
 const checkDuplicate = {
   name: 'check_duplicate',
-  description: '候选查重 — 检测候选代码是否与已有 Recipe 重复（基于标题/摘要/代码的 Jaccard 相似度）。',
+  description:
+    '候选查重 — 检测候选代码是否与已有 Recipe 重复（基于标题/摘要/代码的 Jaccard 相似度）。',
   parameters: {
     type: 'object',
     properties: {
-      candidate:   { type: 'object', description: '候选对象 { title, summary, code, usageGuide }' },
+      candidate: { type: 'object', description: '候选对象 { title, summary, code, usageGuide }' },
       candidateId: { type: 'string', description: '或提供候选 ID，从数据库读取' },
       projectRoot: { type: 'string', description: '项目根目录（可选，默认当前项目）' },
-      threshold:   { type: 'number', description: '相似度阈值，默认 0.5' },
+      threshold: { type: 'number', description: '相似度阈值，默认 0.5' },
     },
   },
   handler: async (params, ctx) => {
@@ -1288,10 +1602,14 @@ const checkDuplicate = {
             usageGuide: '',
           };
         }
-      } catch { /* ignore */ }
+      } catch {
+        /* ignore */
+      }
     }
 
-    if (!cand) return { similar: [], message: 'No candidate provided' };
+    if (!cand) {
+      return { similar: [], message: 'No candidate provided' };
+    }
 
     const similar = findSimilarRecipes(projectRoot, cand, {
       threshold,
@@ -1300,14 +1618,16 @@ const checkDuplicate = {
 
     return {
       similar,
-      hasDuplicate: similar.some(s => s.similarity >= 0.7),
+      hasDuplicate: similar.some((s) => s.similarity >= 0.7),
       highestSimilarity: similar.length > 0 ? similar[0].similarity : 0,
       _meta: {
-        confidence: similar.length === 0 ? 'none'
-          : similar[0].similarity >= 0.7 ? 'high' : 'low',
-        hint: similar.length === 0 ? '未发现相似 Recipe，可放心提交。'
-          : similar[0].similarity >= 0.7 ? '发现高度相似 Recipe，建议人工审核是否重复。'
-          : '有低相似度匹配，大概率不是重复。',
+        confidence: similar.length === 0 ? 'none' : similar[0].similarity >= 0.7 ? 'high' : 'low',
+        hint:
+          similar.length === 0
+            ? '未发现相似 Recipe，可放心提交。'
+            : similar[0].similarity >= 0.7
+              ? '发现高度相似 Recipe，建议人工审核是否重复。'
+              : '有低相似度匹配，大概率不是重复。',
       },
     };
   },
@@ -1318,7 +1638,8 @@ const checkDuplicate = {
 // ────────────────────────────────────────────────────────────
 const discoverRelations = {
   name: 'discover_relations',
-  description: 'AI 知识图谱关系发现 — 分析 Recipe 对之间的潜在关系（requires/extends/enforces/calls 等），并自动写入知识图谱。',
+  description:
+    'AI 知识图谱关系发现 — 分析 Recipe 对之间的潜在关系（requires/extends/enforces/calls 等），并自动写入知识图谱。',
   parameters: {
     type: 'object',
     properties: {
@@ -1327,30 +1648,55 @@ const discoverRelations = {
         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' } } },
+            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} }]',
+        description:
+          'Recipe 对数组 [{ a: {id, title, category, code}, b: {id, title, category, code} }]',
       },
       dryRun: { type: 'boolean', description: '仅分析不写入，默认 false' },
     },
     required: ['recipePairs'],
   },
   handler: async (params, ctx) => {
-    if (!ctx.aiProvider) return { error: 'AI provider not available' };
+    if (!ctx.aiProvider) {
+      return { error: 'AI provider not available' };
+    }
 
     const { recipePairs, dryRun = false } = params;
-    if (!recipePairs || recipePairs.length === 0) return { relations: [] };
+    if (!recipePairs || recipePairs.length === 0) {
+      return { relations: [] };
+    }
 
     // 构建 LLM prompt
-    const pairsText = recipePairs.map((p, i) => `
+    const pairsText = recipePairs
+      .map(
+        (p, i) => `
 --- Pair #${i + 1} ---
 Recipe A [${p.a.id}]: ${p.a.title} (${p.a.category}/${p.a.language || ''})
 ${p.a.code ? `Code: ${p.a.code.substring(0, 300)}` : ''}
 
 Recipe B [${p.b.id}]: ${p.b.title} (${p.b.category}/${p.b.language || ''})
-${p.b.code ? `Code: ${p.b.code.substring(0, 300)}` : ''}`).join('\n');
+${p.b.code ? `Code: ${p.b.code.substring(0, 300)}` : ''}`
+      )
+      .join('\n');
 
     const prompt = `# Role
 You are a Software Architect analyzing relationships between code recipes (knowledge units).
@@ -1379,7 +1725,9 @@ Return ONLY a JSON array. No markdown, no extra text. Return [] if no relationsh
 ${pairsText}`;
 
     const parsed = await ctx.aiProvider.chatWithStructuredOutput(prompt, {
-      openChar: '[', closeChar: ']', temperature: 0.2,
+      openChar: '[',
+      closeChar: ']',
+      temperature: 0.2,
     });
     const relations = Array.isArray(parsed) ? parsed : [];
 
@@ -1389,21 +1737,22 @@ ${pairsText}`;
         const kgService = ctx.container.get('knowledgeGraphService');
         for (const rel of relations) {
           if (rel.from_id && rel.to_id && rel.relation && rel.relation !== 'none') {
-            kgService.addEdge(
-              rel.from_id, 'recipe',
-              rel.to_id, 'recipe',
-              rel.relation,
-              { confidence: rel.confidence || 0.5, reason: rel.reason || '', source: 'ai-discovery' },
-            );
+            kgService.addEdge(rel.from_id, 'recipe', rel.to_id, 'recipe', rel.relation, {
+              confidence: rel.confidence || 0.5,
+              reason: rel.reason || '',
+              source: 'ai-discovery',
+            });
           }
         }
-      } catch { /* KG not available */ }
+      } catch {
+        /* KG not available */
+      }
     }
 
     return {
       analyzed: recipePairs.length,
-      relations: relations.filter(r => r.relation !== 'none'),
-      written: dryRun ? 0 : relations.filter(r => r.relation !== 'none').length,
+      relations: relations.filter((r) => r.relation !== 'none'),
+      written: dryRun ? 0 : relations.filter((r) => r.relation !== 'none').length,
     };
   },
 };
@@ -1417,22 +1766,28 @@ const addGraphEdge = {
   parameters: {
     type: 'object',
     properties: {
-      fromId:   { type: 'string', description: '源节点 ID' },
+      fromId: { type: 'string', description: '源节点 ID' },
       fromType: { type: 'string', description: '源节点类型 (recipe/candidate)' },
-      toId:     { type: 'string', description: '目标节点 ID' },
-      toType:   { type: 'string', description: '目标节点类型 (recipe/candidate)' },
-      relation: { type: 'string', description: '关系类型 (requires/extends/enforces/depends_on/inherits/implements/calls/prerequisite)' },
-      weight:   { type: 'number', description: '权重 0-1，默认 1.0' },
+      toId: { type: 'string', description: '目标节点 ID' },
+      toType: { type: 'string', description: '目标节点类型 (recipe/candidate)' },
+      relation: {
+        type: 'string',
+        description:
+          '关系类型 (requires/extends/enforces/depends_on/inherits/implements/calls/prerequisite)',
+      },
+      weight: { type: 'number', description: '权重 0-1，默认 1.0' },
     },
     required: ['fromId', 'fromType', 'toId', 'toType', 'relation'],
   },
   handler: async (params, ctx) => {
     const kgService = ctx.container.get('knowledgeGraphService');
     return kgService.addEdge(
-      params.fromId, params.fromType,
-      params.toId, params.toType,
+      params.fromId,
+      params.fromType,
+      params.toId,
+      params.toType,
       params.relation,
-      { weight: params.weight || 1.0, source: 'manual' },
+      { weight: params.weight || 1.0, source: 'manual' }
     );
   },
 };
@@ -1464,16 +1819,21 @@ const listGuardRules = {
       const guardService = ctx.container.get('guardService');
       const dbRules = await guardService.listRules({}, { page: 1, pageSize: limit });
       results.push(...(dbRules.data || dbRules.items || []));
-    } catch { /* not available */ }
+    } catch {
+      /* not available */
+    }
 
     // 内置规则
     if (includeBuiltIn) {
       try {
         const guardCheckEngine = ctx.container.get('guardCheckEngine');
-        const builtIn = guardCheckEngine.getRules(language || null)
-          .filter(r => r.source === 'built-in');
+        const builtIn = guardCheckEngine
+          .getRules(language || null)
+          .filter((r) => r.source === 'built-in');
         results.push(...builtIn);
-      } catch { /* not available */ }
+      } catch {
+        /* not available */
+      }
     }
 
     return { total: results.length, rules: results.slice(0, limit) };
@@ -1495,7 +1855,10 @@ const getRecommendations = {
   handler: async (params, ctx) => {
     const knowledgeService = ctx.container.get('knowledgeService');
     // V3: 推荐 = 活跃条目按使用量排序
-    return knowledgeService.list({ lifecycle: 'active' }, { page: 1, pageSize: params.limit || 10 });
+    return knowledgeService.list(
+      { lifecycle: 'active' },
+      { page: 1, pageSize: params.limit || 10 }
+    );
   },
 };
 
@@ -1513,17 +1876,27 @@ const aiTranslate = {
     },
   },
   handler: async (params, ctx) => {
-    if (!ctx.aiProvider) return { error: 'AI provider not available' };
+    if (!ctx.aiProvider) {
+      return { error: 'AI provider not available' };
+    }
     const { summary, usageGuide } = params;
-    if (!summary && !usageGuide) return { summaryEn: '', usageGuideEn: '' };
+    if (!summary && !usageGuide) {
+      return { summaryEn: '', usageGuideEn: '' };
+    }
 
-    const systemPrompt = 'You are a technical translator. Translate from Chinese to English. Keep technical terms unchanged. Return ONLY valid JSON: { "summaryEn": "...", "usageGuideEn": "..." }.';
+    const systemPrompt =
+      'You are a technical translator. Translate from Chinese to English. Keep technical terms unchanged. Return ONLY valid JSON: { "summaryEn": "...", "usageGuideEn": "..." }.';
     const parts = [];
-    if (summary) parts.push(`summary: ${summary}`);
-    if (usageGuide) parts.push(`usageGuide: ${usageGuide}`);
+    if (summary) {
+      parts.push(`summary: ${summary}`);
+    }
+    if (usageGuide) {
+      parts.push(`usageGuide: ${usageGuide}`);
+    }
 
     const parsed = await ctx.aiProvider.chatWithStructuredOutput(parts.join('\n'), {
-      systemPrompt, temperature: 0.2,
+      systemPrompt,
+      temperature: 0.2,
     });
     return parsed || { summaryEn: summary || '', usageGuideEn: usageGuide || '' };
   },
@@ -1538,9 +1911,9 @@ const guardCheckCode = {
   parameters: {
     type: 'object',
     properties: {
-      code:     { type: 'string', description: '待检查的源代码' },
+      code: { type: 'string', description: '待检查的源代码' },
       language: { type: 'string', description: '编程语言 (swift/objc/javascript 等)' },
-      scope:    { type: 'string', description: '检查范围 (file/target/project)，默认 file' },
+      scope: { type: 'string', description: '检查范围 (file/target/project)，默认 file' },
     },
     required: ['code'],
   },
@@ -1553,7 +1926,9 @@ const guardCheckCode = {
       const violations = engine.checkCode(code, language || 'unknown', { scope });
       // reasoning 已由 GuardCheckEngine.checkCode() 内置附加
       return { violationCount: violations.length, violations };
-    } catch { /* not available */ }
+    } catch {
+      /* not available */
+    }
 
     // 降级到 GuardService.checkCode（仅 DB 规则）
     try {
@@ -1575,7 +1950,7 @@ const queryViolations = {
   parameters: {
     type: 'object',
     properties: {
-      file:  { type: 'string', description: '按文件路径过滤' },
+      file: { type: 'string', description: '按文件路径过滤' },
       limit: { type: 'number', description: '返回数量，默认 20' },
       statsOnly: { type: 'boolean', description: '仅返回统计数据，默认 false' },
     },
@@ -1605,15 +1980,20 @@ const generateGuardRule = {
   parameters: {
     type: 'object',
     properties: {
-      description: { type: 'string', description: '规则描述（例如 "禁止在主线程使用同步网络请求"）' },
-      language:    { type: 'string', description: '目标语言 (swift/objc 等)' },
-      severity:    { type: 'string', description: '严重程度 (error/warning/info)，默认 warning' },
-      autoCreate:  { type: 'boolean', description: '是否自动创建到数据库，默认 false' },
+      description: {
+        type: 'string',
+        description: '规则描述（例如 "禁止在主线程使用同步网络请求"）',
+      },
+      language: { type: 'string', description: '目标语言 (swift/objc 等)' },
+      severity: { type: 'string', description: '严重程度 (error/warning/info)，默认 warning' },
+      autoCreate: { type: 'boolean', description: '是否自动创建到数据库，默认 false' },
     },
     required: ['description'],
   },
   handler: async (params, ctx) => {
-    if (!ctx.aiProvider) return { error: 'AI provider not available' };
+    if (!ctx.aiProvider) {
+      return { error: 'AI provider not available' };
+    }
     const { description, language = 'swift', severity = 'warning', autoCreate = false } = params;
 
     const prompt = `Generate a Guard rule for this requirement:
@@ -1636,7 +2016,9 @@ Return ONLY valid JSON:
 }`;
 
     const rule = await ctx.aiProvider.chatWithStructuredOutput(prompt, { temperature: 0.2 });
-    if (!rule) return { error: 'Failed to parse AI response' };
+    if (!rule) {
+      return { error: 'Failed to parse AI response' };
+    }
 
     // 验证正则表达式
     try {
@@ -1649,13 +2031,16 @@ Return ONLY valid JSON:
     if (autoCreate && rule.name && rule.pattern) {
       try {
         const guardService = ctx.container.get('guardService');
-        const created = await guardService.createRule({
-          name: rule.name,
-          description: rule.description || description,
-          pattern: rule.pattern,
-          languages: rule.languages || [language],
-          severity: rule.severity || severity,
-        }, { userId: 'agent' });
+        const created = await guardService.createRule(
+          {
+            name: rule.name,
+            description: rule.description || description,
+            pattern: rule.pattern,
+            languages: rule.languages || [language],
+            severity: rule.severity || severity,
+          },
+          { userId: 'agent' }
+        );
         return { rule, created: true, recipeId: created.id };
       } catch (err) {
         return { rule, created: false, error: err.message };
@@ -1672,15 +2057,15 @@ Return ONLY valid JSON:
 // ────────────────────────────────────────────────────────────
 
 const DIMENSION_DISPLAY_GROUP = {
-  'architecture':        'architecture',        // → 架构与设计
-  'code-pattern':        'architecture',        // → 架构与设计
-  'project-profile':     'architecture',        // → 架构与设计
-  'best-practice':       'best-practice',       // → 规范与实践
-  'code-standard':       'best-practice',       // → 规范与实践
+  architecture: 'architecture', // → 架构与设计
+  'code-pattern': 'architecture', // → 架构与设计
+  'project-profile': 'architecture', // → 架构与设计
+  'best-practice': 'best-practice', // → 规范与实践
+  'code-standard': 'best-practice', // → 规范与实践
   'event-and-data-flow': 'event-and-data-flow', // → 事件与数据流
-  'objc-deep-scan':      'objc-deep-scan',      // → 深度扫描
-  'category-scan':       'objc-deep-scan',      // → 深度扫描
-  'agent-guidelines':    'agent-guidelines',    // skill-only
+  'objc-deep-scan': 'objc-deep-scan', // → 深度扫描
+  'category-scan': 'objc-deep-scan', // → 深度扫描
+  'agent-guidelines': 'agent-guidelines', // skill-only
 };
 
 // ────────────────────────────────────────────────────────────
@@ -1698,7 +2083,9 @@ const DIMENSION_DISPLAY_GROUP = {
 function _checkDimensionType(dimensionMeta, params, logger) {
   // 1. Skill-only 维度不允许提交 Candidate
   if (dimensionMeta.outputType === 'skill') {
-    logger?.info(`[submit_knowledge] ✗ 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_knowledge。请只在最终回复中提供 dimensionDigest JSON。`,
@@ -1710,7 +2097,9 @@ function _checkDimensionType(dimensionMeta, params, logger) {
   if (allowed.length > 0 && params.knowledgeType) {
     if (!allowed.includes(params.knowledgeType)) {
       const corrected = allowed[0];
-      logger?.warn(`[submit_knowledge] 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;
     }
   }
@@ -1727,31 +2116,55 @@ const submitCandidate = {
     type: 'object',
     properties: {
       // ── 内容（V3 content 子对象） ──
-      content:       { type: 'object', description: '{ markdown: "项目特写 Markdown", pattern: "核心代码 3-8 行" }' },
+      content: {
+        type: 'object',
+        description: '{ markdown: "项目特写 Markdown(≥200字)", pattern: "核心代码 3-8 行", rationale: "设计原理" }',
+      },
 
       // ── 基本信息 ──
-      title:         { type: 'string', description: '候选标题' },
-      description:   { type: 'string', description: '中文简述 ≤80 字，引用真实类名' },
-      tags:          { type: 'array', items: { type: 'string' }, description: '标签列表' },
+      title: { type: 'string', description: '候选标题（中文 ≤20 字）' },
+      description: { type: 'string', description: '中文简述 ≤80 字，引用真实类名' },
+      tags: { type: 'array', items: { type: 'string' }, description: '标签列表' },
 
       // ── Cursor 交付（AI 必填）──
-      trigger:       { type: 'string', description: '@前缀 kebab-case 唯一标识符' },
-      kind:          { type: 'string', enum: ['rule', 'pattern', 'fact'], description: '知识类型' },
-      topicHint:     { type: 'string', enum: ['networking', 'ui', 'data', 'architecture', 'conventions'], description: '主题分类' },
-      whenClause:    { type: 'string', description: '触发场景英文' },
-      doClause:      { type: 'string', description: '正向指令英文祈使句 ≤60 tokens' },
-      dontClause:    { type: 'string', description: '反向约束英文（不以 Don\'t 开头）' },
+      trigger: { type: 'string', description: '@前缀 kebab-case 唯一标识符' },
+      kind: { type: 'string', enum: ['rule', 'pattern', 'fact'], description: '知识类型' },
+      topicHint: {
+        type: 'string',
+        enum: ['networking', 'ui', 'data', 'architecture', 'conventions'],
+        description: '主题分类',
+      },
+      whenClause: { type: 'string', description: '触发场景英文' },
+      doClause: { type: 'string', description: '正向指令英文祈使句 ≤60 tokens' },
+      dontClause: { type: 'string', description: "反向约束英文（不以 Don't 开头）" },
 
-      // ── 推理 ──
-      reasoning:     { type: 'object', description: '{ whyStandard: string, sources: string[], confidence: number }' },
+      // ── 推理（必填） ──
+      reasoning: {
+        type: 'object',
+        description: '{ whyStandard: string, sources: string[], confidence: number } — 全部必填',
+      },
 
       // ── V3 扩展字段 ──
-      scope:         { type: 'string', enum: ['universal', 'project-specific', 'team-convention'], description: '适用范围' },
-      complexity:    { type: 'string', enum: ['basic', 'intermediate', 'advanced'], description: '复杂度' },
-      headers:       { type: 'array', items: { type: 'string' }, description: '依赖的 import/require 行' },
-      sourceFile:    { type: 'string', description: '来源文件相对路径' },
+      scope: {
+        type: 'string',
+        enum: ['universal', 'project-specific', 'team-convention'],
+        description: '适用范围',
+      },
+      complexity: {
+        type: 'string',
+        enum: ['basic', 'intermediate', 'advanced'],
+        description: '复杂度',
+      },
+      headers: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '依赖的 import/require 行（无 import 时传 []）',
+      },
+      knowledgeType: { type: 'string', description: '知识维度：code-pattern / architecture / best-practice 等' },
+      usageGuide: { type: 'string', description: '使用指南 Markdown（### 章节格式）' },
+      sourceFile: { type: 'string', description: '来源文件相对路径' },
     },
-    required: ['content', 'title', 'trigger', 'kind', 'doClause'],
+    required: ['content', 'title', 'trigger', 'kind', 'doClause', 'description', 'headers', 'reasoning'],
   },
   handler: async (params, ctx) => {
     const knowledgeService = ctx.container.get('knowledgeService');
@@ -1760,21 +2173,26 @@ const submitCandidate = {
     const dimMeta = ctx._dimensionMeta;
     if (dimMeta && ctx.source === 'system') {
       const rejected = _checkDimensionType(dimMeta, params, ctx.logger);
-      if (rejected) return rejected;
+      if (rejected) {
+        return rejected;
+      }
 
       // 自动注入维度标签
-      if (!params.tags) params.tags = [];
-      if (!params.tags.includes(dimMeta.id)) params.tags.push(dimMeta.id);
-      if (!params.tags.includes('bootstrap')) params.tags.push('bootstrap');
+      if (!params.tags) {
+        params.tags = [];
+      }
+      if (!params.tags.includes(dimMeta.id)) {
+        params.tags.push(dimMeta.id);
+      }
+      if (!params.tags.includes('bootstrap')) {
+        params.tags.push('bootstrap');
+      }
 
       // Bootstrap 模式: 将 category 覆盖为展示分组 ID
       params._category = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
 
       // ── CandidateGuardrail 质量验证 ──
-      const guardrail = new CandidateGuardrail(
-        ctx._submittedTitles || new Set(),
-        dimMeta,
-      );
+      const guardrail = new CandidateGuardrail(ctx._submittedTitles || new Set(), dimMeta, ctx._submittedPatterns || new Set());
       const guardResult = guardrail.validate(params);
       if (!guardResult.valid) {
         ctx.logger?.info(`[submit_knowledge] ✗ guardrail rejected: ${guardResult.error}`);
@@ -1788,10 +2206,10 @@ const submitCandidate = {
 
     // ── 系统自动设置 ──
     const systemFields = {
-      language:      ctx._projectLanguage || '',
-      category:      dimMeta ? (DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id) : 'general',
+      language: ctx._projectLanguage || '',
+      category: dimMeta ? DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id : 'general',
       knowledgeType: dimMeta?.allowedKnowledgeTypes?.[0] || 'code-pattern',
-      source:        ctx.source === 'system' ? 'bootstrap' : 'agent',
+      source: ctx.source === 'system' ? 'bootstrap' : 'agent',
     };
 
     // ── 直传 → KnowledgeEntry ──
@@ -1801,39 +2219,42 @@ const submitCandidate = {
     }
 
     // V3 content 直透
-    const contentObj = params.content && typeof params.content === 'object'
-      ? params.content
-      : { markdown: '', pattern: '' };
+    const contentObj =
+      params.content && typeof params.content === 'object'
+        ? params.content
+        : { markdown: '', pattern: '' };
 
     const data = {
       ...systemFields,
-      title:       params.title || '',
+      title: params.title || '',
       description: params.description || '',
-      tags:        params.tags || [],
-      trigger:     params.trigger || '',
-      kind:        params.kind || 'pattern',
-      topicHint:   params.topicHint || '',
-      whenClause:  params.whenClause || '',
-      doClause:    params.doClause || '',
-      dontClause:  params.dontClause || '',
-      coreCode:    contentObj.pattern || '',
-      content:     contentObj,
+      tags: params.tags || [],
+      trigger: params.trigger || '',
+      kind: params.kind || 'pattern',
+      topicHint: params.topicHint || '',
+      whenClause: params.whenClause || '',
+      doClause: params.doClause || '',
+      dontClause: params.dontClause || '',
+      coreCode: contentObj.pattern || '',
+      content: contentObj,
       reasoning,
       // V3 扩展字段直透
-      scope:       params.scope || '',
-      complexity:  params.complexity || '',
-      headers:     params.headers || [],
+      scope: params.scope || '',
+      complexity: params.complexity || '',
+      headers: params.headers || [],
       // sourceFile: 优先取 params，Bootstrap 回退从 reasoning.sources 推断
-      sourceFile:  params.sourceFile
-                     || (Array.isArray(reasoning.sources) && reasoning.sources.length > 0
-                         && reasoning.sources[0] !== 'agent'
-                         ? reasoning.sources[0]
-                         : ''),
+      sourceFile:
+        params.sourceFile ||
+        (Array.isArray(reasoning.sources) &&
+        reasoning.sources.length > 0 &&
+        reasoning.sources[0] !== 'agent'
+          ? reasoning.sources[0]
+          : ''),
       // 7.3.9 agentNotes/aiInsight 注入
-      agentNotes:  dimMeta
-                     ? { dimensionId: dimMeta.id, outputType: dimMeta.outputType || 'candidate' }
-                     : null,
-      aiInsight:   reasoning.whyStandard || params.description || null,
+      agentNotes: dimMeta
+        ? { dimensionId: dimMeta.id, outputType: dimMeta.outputType || 'candidate' }
+        : null,
+      aiInsight: reasoning.whyStandard || params.description || null,
     };
 
     if (dimMeta && ctx.source === 'system') {
@@ -1846,7 +2267,9 @@ const submitCandidate = {
     // ── QualityScorer 自动评分 ──
     try {
       await knowledgeService.updateQuality(saved.id, { userId: 'agent' });
-    } catch { /* best effort — 不阻塞创建流程 */ }
+    } catch {
+      /* best effort — 不阻塞创建流程 */
+    }
 
     return saved;
   },
@@ -1857,15 +2280,24 @@ const submitCandidate = {
 // ────────────────────────────────────────────────────────────
 const saveDocument = {
   name: 'save_document',
-  description: '保存开发文档到知识库（架构设计、排查报告、决策记录、调研笔记等）。仅需 title + markdown，无需 Cursor Delivery 字段。文档自动发布，可通过 autosnippet_search 检索。',
+  description:
+    '保存开发文档到知识库（架构设计、排查报告、决策记录、调研笔记等）。仅需 title + markdown，无需 Cursor Delivery 字段。文档自动发布，可通过 autosnippet_search 检索。',
   parameters: {
     type: 'object',
     properties: {
-      title:       { type: 'string', description: '文档标题' },
-      markdown:    { type: 'string', description: '文档 Markdown 全文' },
+      title: { type: 'string', description: '文档标题' },
+      markdown: { type: 'string', description: '文档 Markdown 全文' },
       description: { type: 'string', description: '一句话摘要（可选）' },
-      tags:        { type: 'array', items: { type: 'string' }, description: '标签: adr, debug-report, design-doc, research, performance 等' },
-      scope:       { type: 'string', enum: ['universal', 'project-specific'], description: '适用范围（默认 project-specific）' },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '标签: adr, debug-report, design-doc, research, performance 等',
+      },
+      scope: {
+        type: 'string',
+        enum: ['universal', 'project-specific'],
+        description: '适用范围（默认 project-specific）',
+      },
     },
     required: ['title', 'markdown'],
   },
@@ -1873,27 +2305,27 @@ const saveDocument = {
     const knowledgeService = ctx.container.get('knowledgeService');
 
     const data = {
-      title:         params.title.trim(),
-      description:   params.description || '',
+      title: params.title.trim(),
+      description: params.description || '',
       knowledgeType: 'dev-document',
-      kind:          'fact',
-      source:        'agent',
-      scope:         params.scope || 'project-specific',
-      tags:          params.tags || [],
+      kind: 'fact',
+      source: 'agent',
+      scope: params.scope || 'project-specific',
+      tags: params.tags || [],
       content: {
         markdown: params.markdown,
-        pattern:  '',
+        pattern: '',
       },
-      trigger:    '',
-      doClause:   '',
+      trigger: '',
+      doClause: '',
       dontClause: '',
       whenClause: '',
-      topicHint:  '',
-      coreCode:   '',
+      topicHint: '',
+      coreCode: '',
       reasoning: {
         whyStandard: 'Agent development document',
-        sources:     ['agent'],
-        confidence:  0.8,
+        sources: ['agent'],
+        confidence: 0.8,
       },
     };
 
@@ -1902,14 +2334,16 @@ const saveDocument = {
     // 自动发布（文档不需要人工审核）
     try {
       await knowledgeService.publish(saved.id, { userId: 'agent' });
-    } catch { /* best effort */ }
+    } catch {
+      /* best effort */
+    }
 
     return {
-      id:            saved.id,
-      title:         saved.title,
-      lifecycle:     'active',
+      id: saved.id,
+      title: saved.title,
+      lifecycle: 'active',
       knowledgeType: 'dev-document',
-      message:       `文档「${saved.title}」已保存到知识库`,
+      message: `文档「${saved.title}」已保存到知识库`,
     };
   },
 };
@@ -1943,7 +2377,7 @@ const rejectCandidate = {
     type: 'object',
     properties: {
       candidateId: { type: 'string', description: '候选 ID' },
-      reason:      { type: 'string', description: '驳回理由' },
+      reason: { type: 'string', description: '驳回理由' },
     },
     required: ['candidateId', 'reason'],
   },
@@ -1982,7 +2416,7 @@ const deprecateRecipe = {
     type: 'object',
     properties: {
       recipeId: { type: 'string', description: 'Recipe ID' },
-      reason:   { type: 'string', description: '弃用原因' },
+      reason: { type: 'string', description: '弃用原因' },
     },
     required: ['recipeId', 'reason'],
   },
@@ -2002,7 +2436,7 @@ const updateRecipe = {
     type: 'object',
     properties: {
       recipeId: { type: 'string', description: 'Recipe ID' },
-      updates:  { type: 'object', description: '要更新的字段和值' },
+      updates: { type: 'object', description: '要更新的字段和值' },
     },
     required: ['recipeId', 'updates'],
   },
@@ -2022,7 +2456,7 @@ const recordUsage = {
     type: 'object',
     properties: {
       recipeId: { type: 'string', description: 'Recipe ID' },
-      type:     { type: 'string', description: 'adoption 或 application，默认 adoption' },
+      type: { type: 'string', description: 'adoption 或 application，默认 adoption' },
     },
     required: ['recipeId'],
   },
@@ -2039,12 +2473,16 @@ const recordUsage = {
 // ────────────────────────────────────────────────────────────
 const qualityScore = {
   name: 'quality_score',
-  description: 'Recipe 质量评分 — 5 维度综合评估（完整性/格式/代码质量/元数据/互动），返回分数和等级(A-F)。',
+  description:
+    'Recipe 质量评分 — 5 维度综合评估（完整性/格式/代码质量/元数据/互动），返回分数和等级(A-F)。',
   parameters: {
     type: 'object',
     properties: {
       recipeId: { type: 'string', description: 'Recipe ID（从数据库读取后评分）' },
-      recipe:   { type: 'object', description: '或直接提供 Recipe 对象 { title, trigger, code, language, ... }' },
+      recipe: {
+        type: 'object',
+        description: '或直接提供 Recipe 对象 { title, trigger, code, language, ... }',
+      },
     },
   },
   handler: async (params, ctx) => {
@@ -2060,7 +2498,9 @@ const qualityScore = {
         return { error: `Knowledge entry '${params.recipeId}' not found` };
       }
     }
-    if (!recipe) return { error: 'Provide recipeId or recipe object' };
+    if (!recipe) {
+      return { error: 'Provide recipeId or recipe object' };
+    }
 
     return qualityScorer.score(recipe);
   },
@@ -2071,11 +2511,15 @@ const qualityScore = {
 // ────────────────────────────────────────────────────────────
 const validateCandidate = {
   name: 'validate_candidate',
-  description: '候选校验 — 检查候选是否满足提交要求（必填字段/格式/质量），返回 errors 和 warnings。',
+  description:
+    '候选校验 — 检查候选是否满足提交要求（必填字段/格式/质量），返回 errors 和 warnings。',
   parameters: {
     type: 'object',
     properties: {
-      candidate: { type: 'object', description: '候选对象 { title, trigger, category, language, code, reasoning, ... }' },
+      candidate: {
+        type: 'object',
+        description: '候选对象 { title, trigger, category, language, code, reasoning, ... }',
+      },
     },
     required: ['candidate'],
   },
@@ -2095,7 +2539,7 @@ const getFeedbackStats = {
     type: 'object',
     properties: {
       recipeId: { type: 'string', description: '查询指定 Recipe 的反馈（可选）' },
-      topN:     { type: 'number', description: '热门 Recipe 数量，默认 10' },
+      topN: { type: 'number', description: '热门 Recipe 数量，默认 10' },
     },
   },
   handler: async (params, ctx) => {
@@ -2139,7 +2583,8 @@ const graphImpactAnalysis = {
 // ────────────────────────────────────────────────────────────
 const rebuildIndex = {
   name: 'rebuild_index',
-  description: '向量索引重建 — 重新扫描 Recipe 文件并更新向量索引（用于索引过期或新增大量 Recipe 后）。',
+  description:
+    '向量索引重建 — 重新扫描 Recipe 文件并更新向量索引（用于索引过期或新增大量 Recipe 后）。',
   parameters: {
     type: 'object',
     properties: {
@@ -2162,17 +2607,24 @@ const queryAuditLog = {
   parameters: {
     type: 'object',
     properties: {
-      action: { type: 'string', description: '按操作类型过滤 (create_candidate/approve_candidate/create_guard_rule 等)' },
-      actor:  { type: 'string', description: '按操作者过滤' },
-      limit:  { type: 'number', description: '返回数量，默认 20' },
+      action: {
+        type: 'string',
+        description: '按操作类型过滤 (create_candidate/approve_candidate/create_guard_rule 等)',
+      },
+      actor: { type: 'string', description: '按操作者过滤' },
+      limit: { type: 'number', description: '返回数量，默认 20' },
     },
   },
   handler: async (params, ctx) => {
     const auditLogger = ctx.container.get('auditLogger');
     const { action, actor, limit = 20 } = params;
 
-    if (actor) return auditLogger.getByActor(actor, limit);
-    if (action) return auditLogger.getByAction(action, limit);
+    if (actor) {
+      return auditLogger.getByActor(actor, limit);
+    }
+    if (action) {
+      return auditLogger.getByAction(action, limit);
+    }
     return auditLogger.getStats();
   },
 };
@@ -2182,11 +2634,15 @@ const queryAuditLog = {
 // ────────────────────────────────────────────────────────────
 const loadSkill = {
   name: 'load_skill',
-  description: '加载指定的 Agent Skill 文档，获取领域操作指南和最佳实践参考。可用于冷启动指南 (autosnippet-coldstart)、语言参考 (autosnippet-reference-swift/objc/jsts) 等。',
+  description:
+    '加载指定的 Agent Skill 文档，获取领域操作指南和最佳实践参考。可用于冷启动指南 (autosnippet-coldstart)、语言参考 (autosnippet-reference-swift/objc/jsts/python/java/kotlin/go) 等。',
   parameters: {
     type: 'object',
     properties: {
-      skillName: { type: 'string', description: 'Skill 目录名（如 autosnippet-coldstart, autosnippet-reference-swift 等）' },
+      skillName: {
+        type: 'string',
+        description: 'Skill 目录名（如 autosnippet-coldstart, autosnippet-reference-swift, autosnippet-reference-go 等）',
+      },
     },
     required: ['skillName'],
   },
@@ -2201,8 +2657,16 @@ const loadSkill = {
       return { skillName: params.skillName, source, content };
     } catch {
       const available = new Set();
-      try { fs.readdirSync(SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory()).forEach(d => available.add(d.name)); } catch {}
-      try { fs.readdirSync(PROJECT_SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory()).forEach(d => available.add(d.name)); } catch {}
+      try {
+        fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+          .filter((d) => d.isDirectory())
+          .forEach((d) => available.add(d.name));
+      } catch {}
+      try {
+        fs.readdirSync(PROJECT_SKILLS_DIR, { withFileTypes: true })
+          .filter((d) => d.isDirectory())
+          .forEach((d) => available.add(d.name));
+      } catch {}
       return { error: `Skill "${params.skillName}" not found`, availableSkills: [...available] };
     }
   },
@@ -2213,14 +2677,18 @@ const loadSkill = {
 // ────────────────────────────────────────────────────────────
 const createSkillTool = {
   name: 'create_skill',
-  description: '创建项目级 Skill 文档，写入 AutoSnippet/skills/<name>/SKILL.md。Skill 是 Agent 的领域知识增强文档。创建后自动更新编辑器索引。',
+  description:
+    '创建项目级 Skill 文档，写入 AutoSnippet/skills/<name>/SKILL.md。Skill 是 Agent 的领域知识增强文档。创建后自动更新编辑器索引。',
   parameters: {
     type: 'object',
     properties: {
-      name:        { type: 'string', description: 'Skill 名称（kebab-case，如 my-auth-guide），3-64 字符' },
+      name: {
+        type: 'string',
+        description: 'Skill 名称（kebab-case，如 my-auth-guide），3-64 字符',
+      },
       description: { type: 'string', description: 'Skill 一句话描述（写入 frontmatter）' },
-      content:     { type: 'string', description: 'Skill 正文内容（Markdown 格式，不含 frontmatter）' },
-      overwrite:   { type: 'boolean', description: '如果同名 Skill 已存在，是否覆盖（默认 false）' },
+      content: { type: 'string', description: 'Skill 正文内容（Markdown 格式，不含 frontmatter）' },
+      overwrite: { type: 'boolean', description: '如果同名 Skill 已存在，是否覆盖（默认 false）' },
     },
     required: ['name', 'description', 'content'],
   },
@@ -2229,7 +2697,11 @@ const createSkillTool = {
     // 根据 ChatAgent 的 source 推断 createdBy
     const createdBy = ctx?.source === 'system' ? 'system-ai' : 'user-ai';
     const raw = createSkill(null, { ...params, createdBy });
-    try { return JSON.parse(raw); } catch { return { success: false, error: raw }; }
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return { success: false, error: raw };
+    }
   },
 };
 
@@ -2238,7 +2710,8 @@ const createSkillTool = {
 // ────────────────────────────────────────────────────────────
 const suggestSkills = {
   name: 'suggest_skills',
-  description: '基于项目使用模式分析，推荐创建 Skill。分析 Guard 违规频率、Memory 偏好积累、Recipe 分布缺口、候选积压率。返回推荐列表（含 name/description/rationale/priority），可据此直接调用 create_skill 创建。',
+  description:
+    '基于项目使用模式分析，推荐创建 Skill。分析 Guard 违规频率、Memory 偏好积累、Recipe 分布缺口、候选积压率。返回推荐列表（含 name/description/rationale/priority），可据此直接调用 create_skill 创建。',
   parameters: {
     type: 'object',
     properties: {},
@@ -2258,14 +2731,18 @@ const suggestSkills = {
 // ────────────────────────────────────────────────────────────
 const bootstrapKnowledgeTool = {
   name: 'bootstrap_knowledge',
-  description: '冷启动知识库初始化（纯启发式，不使用 AI）: SPM Target 扫描 → 依赖图谱 → Guard 审计 → 9 维度 Candidate 自动创建。支持 Skill 增强维度定义。产出为初稿候选，后续由 DAG pipeline 自动编排 AI 增强（enrich → refine）。',
+  description:
+    '冷启动知识库初始化（纯启发式，不使用 AI）: SPM Target 扫描 → 依赖图谱 → Guard 审计 → 9 维度 Candidate 自动创建。支持 Skill 增强维度定义。产出为初稿候选，后续由 DAG pipeline 自动编排 AI 增强（enrich → refine）。',
   parameters: {
     type: 'object',
     properties: {
       maxFiles: { type: 'number', description: '最大扫描文件数，默认 500' },
       skipGuard: { type: 'boolean', description: '是否跳过 Guard 审计，默认 false' },
       contentMaxLines: { type: 'number', description: '每文件读取最大行数，默认 120' },
-      loadSkills: { type: 'boolean', description: '是否加载 Skills 增强维度定义（推荐开启），默认 true' },
+      loadSkills: {
+        type: 'boolean',
+        description: '是否加载 Skills 增强维度定义（推荐开启），默认 true',
+      },
     },
   },
   handler: async (params, ctx) => {
@@ -2278,7 +2755,7 @@ const bootstrapKnowledgeTool = {
         skipGuard: params.skipGuard || false,
         contentMaxLines: params.contentMaxLines || 120,
         loadSkills: params.loadSkills ?? true,
-      },
+      }
     );
     // bootstrapKnowledge 返回 envelope JSON string，解析提取 data
     const parsed = typeof result === 'string' ? JSON.parse(result) : result;
@@ -2295,11 +2772,12 @@ const bootstrapKnowledgeTool = {
 // ────────────────────────────────────────────────────────────
 const analyzeCode = {
   name: 'analyze_code',
-  description: '综合分析一段代码：Guard 规范检查 + 相关 Recipe 搜索。一次调用完成完整分析，减少多轮工具调用。',
+  description:
+    '综合分析一段代码：Guard 规范检查 + 相关 Recipe 搜索。一次调用完成完整分析，减少多轮工具调用。',
   parameters: {
     type: 'object',
     properties: {
-      code:     { type: 'string', description: '待分析的源码' },
+      code: { type: 'string', description: '待分析的源码' },
       language: { type: 'string', description: '编程语言 (swift/objc/javascript 等)' },
       filePath: { type: 'string', description: '文件路径（可选，用于上下文）' },
     },
@@ -2321,7 +2799,9 @@ const analyzeCode = {
             const guardService = ctx.container.get('guardService');
             const matches = await guardService.checkCode(code, { language });
             return { violationCount: matches.length, violations: matches };
-          } catch { return { violationCount: 0, violations: [] }; }
+          } catch {
+            return { violationCount: 0, violations: [] };
+          }
         }
       })(),
       (async () => {
@@ -2331,7 +2811,9 @@ const analyzeCode = {
           const query = code.substring(0, 200).replace(/\n/g, ' ');
           const rawResults = await searchEngine.search(query, { limit: 5 });
           return { results: rawResults || [], total: rawResults?.length || 0 };
-        } catch { return { results: [], total: 0 }; }
+        } catch {
+          return { results: [], total: 0 };
+        }
       })(),
     ]);
 
@@ -2356,7 +2838,8 @@ const analyzeCode = {
 // ────────────────────────────────────────────────────────────
 const knowledgeOverview = {
   name: 'knowledge_overview',
-  description: '一次性获取知识库全貌：各类型 Recipe 分布 + 候选状态 + 知识图谱概况 + 质量概览。比分别调用 get_project_stats + search_recipes 更高效。',
+  description:
+    '一次性获取知识库全貌：各类型 Recipe 分布 + 候选状态 + 知识图谱概况 + 质量概览。比分别调用 get_project_stats + search_recipes 更高效。',
   parameters: {
     type: 'object',
     properties: {
@@ -2374,14 +2857,20 @@ const knowledgeOverview = {
         try {
           const knowledgeService = ctx.container.get('knowledgeService');
           return knowledgeService.getStats();
-        } catch { return null; }
+        } catch {
+          return null;
+        }
       })(),
       (async () => {
-        if (!includeTopRecipes) return null;
+        if (!includeTopRecipes) {
+          return null;
+        }
         try {
           const feedbackCollector = ctx.container.get('feedbackCollector');
           return feedbackCollector.getTopRecipes(limit);
-        } catch { return null; }
+        } catch {
+          return null;
+        }
       })(),
     ]);
 
@@ -2393,9 +2882,13 @@ const knowledgeOverview = {
     try {
       const kgService = ctx.container.get('knowledgeGraphService');
       result.knowledgeGraph = kgService.getStats();
-    } catch { /* KG not available */ }
+    } catch {
+      /* KG not available */
+    }
 
-    if (feedbackResult) result.topRecipes = feedbackResult;
+    if (feedbackResult) {
+      result.topRecipes = feedbackResult;
+    }
 
     const recipeCount = result.recipes?.total || result.recipes?.count || 0;
     result._meta = {
@@ -2412,22 +2905,29 @@ const knowledgeOverview = {
 // ────────────────────────────────────────────────────────────
 const submitWithCheck = {
   name: 'submit_with_check',
-  description: '安全提交候选：先执行查重检测，无重复则自动提交。一次调用完成 check_duplicate + submit_knowledge。',
+  description:
+    '安全提交候选：先执行查重检测，无重复则自动提交。一次调用完成 check_duplicate + submit_knowledge。',
   parameters: {
     type: 'object',
     properties: {
-      content:    { type: 'object', description: '{ markdown: "项目特写 Markdown", pattern: "核心代码 3-8 行" }' },
-      title:      { type: 'string', description: '候选标题' },
-      description:{ type: 'string', description: '中文简述 ≤80 字' },
-      trigger:    { type: 'string', description: '@前缀 kebab-case 唯一标识符' },
-      kind:       { type: 'string', enum: ['rule', 'pattern', 'fact'] },
-      topicHint:  { type: 'string', enum: ['networking', 'ui', 'data', 'architecture', 'conventions'] },
+      content: {
+        type: 'object',
+        description: '{ markdown: "项目特写 Markdown", pattern: "核心代码 3-8 行，必须语法完整（括号配对、不能以 } 开头或 { 结尾）" }',
+      },
+      title: { type: 'string', description: '候选标题' },
+      description: { type: 'string', description: '中文简述 ≤80 字' },
+      trigger: { type: 'string', description: '@前缀 kebab-case 唯一标识符' },
+      kind: { type: 'string', enum: ['rule', 'pattern', 'fact'] },
+      topicHint: {
+        type: 'string',
+        enum: ['networking', 'ui', 'data', 'architecture', 'conventions'],
+      },
       whenClause: { type: 'string', description: '触发场景英文' },
-      doClause:   { type: 'string', description: '正向指令英文' },
+      doClause: { type: 'string', description: '正向指令英文' },
       dontClause: { type: 'string', description: '反向约束英文' },
-      tags:       { type: 'array', items: { type: 'string' } },
-      reasoning:  { type: 'object', description: '{ whyStandard, sources, confidence }' },
-      threshold:  { type: 'number', description: '相似度阈值，默认 0.7' },
+      tags: { type: 'array', items: { type: 'string' } },
+      reasoning: { type: 'object', description: '{ whyStandard, sources, confidence }' },
+      threshold: { type: 'number', description: '相似度阈值，默认 0.7' },
     },
     required: ['content', 'title', 'trigger', 'kind', 'doClause'],
   },
@@ -2438,21 +2938,34 @@ const submitWithCheck = {
     const dimMeta = ctx._dimensionMeta;
     if (dimMeta && ctx.source === 'system') {
       const rejected = _checkDimensionType(dimMeta, params, ctx.logger);
-      if (rejected) return rejected;
+      if (rejected) {
+        return rejected;
+      }
 
-      if (!params.tags) params.tags = [];
-      if (!params.tags.includes(dimMeta.id)) params.tags.push(dimMeta.id);
-      if (!params.tags.includes('bootstrap')) params.tags.push('bootstrap');
+      if (!params.tags) {
+        params.tags = [];
+      }
+      if (!params.tags.includes(dimMeta.id)) {
+        params.tags.push(dimMeta.id);
+      }
+      if (!params.tags.includes('bootstrap')) {
+        params.tags.push('bootstrap');
+      }
     }
 
     // Step 1: 查重
     const threshold = params.threshold || 0.7;
-    const contentObj2 = params.content && typeof params.content === 'object'
-      ? params.content
-      : { markdown: '', pattern: '' };
-    const cand = { title: params.title || '', summary: params.description || '', code: contentObj2.markdown || contentObj2.pattern || '' };
+    const contentObj2 =
+      params.content && typeof params.content === 'object'
+        ? params.content
+        : { markdown: '', pattern: '' };
+    const cand = {
+      title: params.title || '',
+      summary: params.description || '',
+      code: contentObj2.markdown || contentObj2.pattern || '',
+    };
     const similar = findSimilarRecipes(projectRoot, cand, { threshold: 0.5, topK: 5 });
-    const hasDuplicate = similar.some(s => s.similarity >= threshold);
+    const hasDuplicate = similar.some((s) => s.similarity >= threshold);
 
     if (hasDuplicate) {
       return {
@@ -2470,28 +2983,32 @@ const submitWithCheck = {
     // Step 2: 提交 — 委托给 submit_knowledge handler
     try {
       const knowledgeService = ctx.container.get('knowledgeService');
-      const reasoning = params.reasoning || { whyStandard: '', sources: ['agent'], confidence: 0.7 };
+      const reasoning = params.reasoning || {
+        whyStandard: '',
+        sources: ['agent'],
+        confidence: 0.7,
+      };
 
       const systemFields = {
-        language:      ctx._projectLanguage || '',
-        category:      dimMeta ? (DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id) : 'general',
+        language: ctx._projectLanguage || '',
+        category: dimMeta ? DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id : 'general',
         knowledgeType: dimMeta?.allowedKnowledgeTypes?.[0] || 'code-pattern',
-        source:        ctx.source === 'system' ? 'bootstrap' : 'agent',
+        source: ctx.source === 'system' ? 'bootstrap' : 'agent',
       };
 
       const data = {
         ...systemFields,
-        title:       params.title || '',
+        title: params.title || '',
         description: params.description || '',
-        tags:        params.tags || [],
-        trigger:     params.trigger || '',
-        kind:        params.kind || 'pattern',
-        topicHint:   params.topicHint || '',
-        whenClause:  params.whenClause || '',
-        doClause:    params.doClause || '',
-        dontClause:  params.dontClause || '',
-        coreCode:    contentObj2.pattern || '',
-        content:     contentObj2,
+        tags: params.tags || [],
+        trigger: params.trigger || '',
+        kind: params.kind || 'pattern',
+        topicHint: params.topicHint || '',
+        whenClause: params.whenClause || '',
+        doClause: params.doClause || '',
+        dontClause: params.dontClause || '',
+        coreCode: contentObj2.pattern || '',
+        content: contentObj2,
         reasoning,
       };
 
@@ -2503,9 +3020,10 @@ const submitWithCheck = {
         similar: similar.length > 0 ? similar : [],
         _meta: {
           confidence: 'high',
-          hint: similar.length > 0
-            ? `已提交，但有 ${similar.length} 个低相似度匹配。`
-            : '已提交，无重复风险。',
+          hint:
+            similar.length > 0
+              ? `已提交，但有 ${similar.length} 个低相似度匹配。`
+              : '已提交，无重复风险。',
         },
       };
     } catch (err) {
@@ -2540,12 +3058,14 @@ const getToolDetails = {
   },
   handler: async ({ toolName }, context) => {
     const registry = context.container?.get('toolRegistry');
-    if (!registry) return { error: 'ToolRegistry not available' };
+    if (!registry) {
+      return { error: 'ToolRegistry not available' };
+    }
 
     const schemas = registry.getToolSchemas();
-    const found = schemas.find(t => t.name === toolName);
+    const found = schemas.find((t) => t.name === toolName);
     if (!found) {
-      const allNames = schemas.map(t => t.name);
+      const allNames = schemas.map((t) => t.name);
       return {
         error: `Tool "${toolName}" not found`,
         availableTools: allNames,
@@ -2563,7 +3083,8 @@ const getToolDetails = {
 // ─── 元工具: 任务规划 ───────────────────────────────────
 const planTask = {
   name: 'plan_task',
-  description: '分析当前任务并制定结构化执行计划。在开始复杂任务前调用此工具可提高执行效率和决策质量。输出将记录到日志供审计,但不会改变实际执行流程。',
+  description:
+    '分析当前任务并制定结构化执行计划。在开始复杂任务前调用此工具可提高执行效率和决策质量。输出将记录到日志供审计,但不会改变实际执行流程。',
   parameters: {
     type: 'object',
     properties: {
@@ -2611,7 +3132,8 @@ const planTask = {
 // ─── 元工具: 自我质量审查 ───────────────────────────────
 const reviewMyOutput = {
   name: 'review_my_output',
-  description: '回查本次会话中已提交的候选,检查质量红线是否满足。包括: 项目特写风格、description 泛化措辞、代码示例来源标注、Cursor 交付字段完整性等。返回通过/问题列表。建议在提交完所有候选后调用一次进行自检。',
+  description:
+    '回查本次会话中已提交的候选,检查质量红线是否满足。包括: 项目特写风格、description 泛化措辞、代码示例来源标注、Cursor 交付字段完整性等。返回通过/问题列表。建议在提交完所有候选后调用一次进行自检。',
   parameters: {
     type: 'object',
     properties: {
@@ -2624,7 +3146,7 @@ const reviewMyOutput = {
   },
   handler: async (params, context) => {
     const submitted = (context._sessionToolCalls || []).filter(
-      tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check',
+      (tc) => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check'
     );
 
     if (submitted.length === 0) {
@@ -2653,7 +3175,10 @@ const reviewMyOutput = {
         candidateIssues.push('特写缺少代码示例，应包含基本用法代码');
       }
       // 去掉代码块后，剩余描述性文字应足够
-      const proseLength = markdown.replace(/```[\s\S]*?```/g, '').replace(/[#>\-*`\n]/g, '').trim().length;
+      const proseLength = markdown
+        .replace(/```[\s\S]*?```/g, '')
+        .replace(/[#>\-*`\n]/g, '')
+        .trim().length;
       if (proseLength < 50) {
         candidateIssues.push('特写缺少项目特点描述，应融合基本用法和项目特点');
       }
@@ -2665,7 +3190,9 @@ const reviewMyOutput = {
 
       // 检查 4: description 过短
       if (description.length < 15) {
-        candidateIssues.push(`description 过短 (${description.length} 字), 应≥15字并包含具体类名和数字`);
+        candidateIssues.push(
+          `description 过短 (${description.length} 字), 应≥15字并包含具体类名和数字`
+        );
       }
 
       // 检查 5: content.markdown 过短（可能是空壳）
@@ -2680,14 +3207,24 @@ const reviewMyOutput = {
       }
 
       // 检查 7: Cursor 交付字段
-      if (!p.trigger) candidateIssues.push('缺少 trigger 字段');
-      if (!p.doClause) candidateIssues.push('缺少 doClause 字段');
-      if (!p.kind) candidateIssues.push('缺少 kind 字段');
+      if (!p.trigger) {
+        candidateIssues.push('缺少 trigger 字段');
+      }
+      if (!p.doClause) {
+        candidateIssues.push('缺少 doClause 字段');
+      }
+      if (!p.kind) {
+        candidateIssues.push('缺少 kind 字段');
+      }
 
       if (candidateIssues.length > 0) {
         issues.push({ title, issues: candidateIssues });
       }
-      checked.push({ title, passed: candidateIssues.length === 0, issueCount: candidateIssues.length });
+      checked.push({
+        title,
+        passed: candidateIssues.length === 0,
+        issueCount: candidateIssues.length,
+      });
     }
 
     if (issues.length === 0) {
@@ -2699,7 +3236,7 @@ const reviewMyOutput = {
     }
 
     const issueLines = issues.flatMap(({ title, issues: iss }) =>
-      iss.map(i => `• "${title}": ${i}`),
+      iss.map((i) => `• "${title}": ${i}`)
     );
 
     return {
@@ -2735,7 +3272,8 @@ function _getProjectGraph(ctx) {
 // ────────────────────────────────────────────────────────────
 const getProjectOverview = {
   name: 'get_project_overview',
-  description: '获取项目的整体结构概览：文件统计、模块列表、入口点、类/协议/Category 数量。' +
+  description:
+    '获取项目的整体结构概览：文件统计、模块列表、入口点、类/协议/Category 数量。' +
     '适用场景：了解项目规模和架构布局，规划探索路径。',
   parameters: {
     type: 'object',
@@ -2743,7 +3281,9 @@ const getProjectOverview = {
   },
   handler: async (_params, ctx) => {
     const graph = _getProjectGraph(ctx);
-    if (!graph) return 'AST 分析不可用 — ProjectGraph 未构建。请检查 tree-sitter 是否已安装。';
+    if (!graph) {
+      return 'AST 分析不可用 — ProjectGraph 未构建。请检查 tree-sitter 是否已安装。';
+    }
 
     const o = graph.getOverview();
     const lines = [
@@ -2772,7 +3312,8 @@ const getProjectOverview = {
 // ────────────────────────────────────────────────────────────
 const getClassHierarchy = {
   name: 'get_class_hierarchy',
-  description: '查看指定类的继承链（向上到根类）和直接子类列表。' +
+  description:
+    '查看指定类的继承链（向上到根类）和直接子类列表。' +
     '传入 className 查看指定类，不传则返回项目中所有根类及其子树。',
   parameters: {
     type: 'object',
@@ -2782,28 +3323,31 @@ const getClassHierarchy = {
   },
   handler: async (params, ctx) => {
     const graph = _getProjectGraph(ctx);
-    if (!graph) return 'AST 分析不可用 — ProjectGraph 未构建。';
+    if (!graph) {
+      return 'AST 分析不可用 — ProjectGraph 未构建。';
+    }
 
     const className = params.className || params.class_name;
     if (className) {
       const chain = graph.getInheritanceChain(className);
       const subs = graph.getSubclasses(className);
-      if (chain.length === 0) return `未找到类 ${className}`;
+      if (chain.length === 0) {
+        return `未找到类 ${className}`;
+      }
 
-      const lines = [
-        `🔗 ${className} 继承链:`,
-        `  ${chain.join(' → ')}`,
-      ];
+      const lines = [`🔗 ${className} 继承链:`, `  ${chain.join(' → ')}`];
       if (subs.length > 0) {
         lines.push(``, `直接子类 (${subs.length}):`);
-        for (const s of subs) lines.push(`  ├── ${s}`);
+        for (const s of subs) {
+          lines.push(`  ├── ${s}`);
+        }
       }
       return lines.join('\n');
     }
 
     // 全量: 找出所有根类 (没有父类或父类不在项目中的类)
     const allClasses = graph.getAllClassNames();
-    const roots = allClasses.filter(c => {
+    const roots = allClasses.filter((c) => {
       const chain = graph.getInheritanceChain(c);
       return chain.length <= 1 || !allClasses.includes(chain[1]);
     });
@@ -2815,9 +3359,13 @@ const getClassHierarchy = {
       for (const d of descendants.slice(0, 5)) {
         lines.push(`    └── ${d}`);
       }
-      if (descendants.length > 5) lines.push(`    ... 还有 ${descendants.length - 5} 个`);
+      if (descendants.length > 5) {
+        lines.push(`    ... 还有 ${descendants.length - 5} 个`);
+      }
+    }
+    if (roots.length > 30) {
+      lines.push(`... 还有 ${roots.length - 30} 棵树`);
     }
-    if (roots.length > 30) lines.push(`... 还有 ${roots.length - 30} 棵树`);
     return lines.join('\n');
   },
 };
@@ -2837,11 +3385,15 @@ const getClassInfo = {
   },
   handler: async (params, ctx) => {
     const graph = _getProjectGraph(ctx);
-    if (!graph) return 'AST 分析不可用 — ProjectGraph 未构建。';
+    if (!graph) {
+      return 'AST 分析不可用 — ProjectGraph 未构建。';
+    }
 
     const className = params.className || params.class_name;
     const info = graph.getClassInfo(className);
-    if (!info) return `未找到类 "${className}"。可以使用 get_project_overview 查看项目中的所有类。`;
+    if (!info) {
+      return `未找到类 "${className}"。可以使用 get_project_overview 查看项目中的所有类。`;
+    }
 
     const chain = graph.getInheritanceChain(className);
     const cats = graph.getCategoryExtensions(className);
@@ -2867,8 +3419,8 @@ const getClassInfo = {
 
     if (info.methods.length > 0) {
       lines.push(``, `── 方法 (${info.methods.length}) ──`);
-      const classMethods = info.methods.filter(m => m.isClassMethod);
-      const instanceMethods = info.methods.filter(m => !m.isClassMethod);
+      const classMethods = info.methods.filter((m) => m.isClassMethod);
+      const instanceMethods = info.methods.filter((m) => !m.isClassMethod);
       for (const m of classMethods) {
         const cx = m.complexity > 3 ? ` [复杂度:${m.complexity}]` : '';
         lines.push(`  + ${m.selector} → ${m.returnType}${cx}`);
@@ -2882,14 +3434,16 @@ const getClassInfo = {
     if (cats.length > 0) {
       lines.push(``, `── Category 扩展 (${cats.length}) ──`);
       for (const cat of cats) {
-        const methodNames = cat.methods.map(m => m.selector).join(', ');
+        const methodNames = cat.methods.map((m) => m.selector).join(', ');
         lines.push(`  ${info.name}(${cat.categoryName}) — ${cat.filePath} — [${methodNames}]`);
       }
     }
 
     if (subs.length > 0) {
       lines.push(``, `── 直接子类 (${subs.length}) ──`);
-      for (const s of subs) lines.push(`  ${s}`);
+      for (const s of subs) {
+        lines.push(`  ${s}`);
+      }
     }
 
     return lines.join('\n');
@@ -2911,16 +3465,17 @@ const getProtocolInfo = {
   },
   handler: async (params, ctx) => {
     const graph = _getProjectGraph(ctx);
-    if (!graph) return 'AST 分析不可用 — ProjectGraph 未构建。';
+    if (!graph) {
+      return 'AST 分析不可用 — ProjectGraph 未构建。';
+    }
 
     const protocolName = params.protocolName || params.protocol_name;
     const info = graph.getProtocolInfo(protocolName);
-    if (!info) return `未找到协议 "${protocolName}"。可以使用 get_project_overview 查看项目中的所有协议。`;
+    if (!info) {
+      return `未找到协议 "${protocolName}"。可以使用 get_project_overview 查看项目中的所有协议。`;
+    }
 
-    const lines = [
-      `📋 @protocol ${info.name}`,
-      `文件: ${info.filePath}:${info.line}`,
-    ];
+    const lines = [`📋 @protocol ${info.name}`, `文件: ${info.filePath}:${info.line}`];
 
     if (info.inherits.length > 0) {
       lines.push(`继承: <${info.inherits.join(', ')}>`);
@@ -2942,7 +3497,9 @@ const getProtocolInfo = {
 
     if (info.conformers.length > 0) {
       lines.push(``, `── 遵循者 (${info.conformers.length}) ──`);
-      for (const c of info.conformers) lines.push(`  ${c}`);
+      for (const c of info.conformers) {
+        lines.push(`  ${c}`);
+      }
     } else {
       lines.push(``, `⚠️ 暂未发现遵循此协议的类`);
     }
@@ -2960,14 +3517,16 @@ const getMethodOverrides = {
   parameters: {
     type: 'object',
     properties: {
-      className:  { type: 'string', description: '定义该方法的基类名 (必填)' },
+      className: { type: 'string', description: '定义该方法的基类名 (必填)' },
       methodName: { type: 'string', description: '方法名或 selector (必填)' },
     },
     required: ['className', 'methodName'],
   },
   handler: async (params, ctx) => {
     const graph = _getProjectGraph(ctx);
-    if (!graph) return 'AST 分析不可用 — ProjectGraph 未构建。';
+    if (!graph) {
+      return 'AST 分析不可用 — ProjectGraph 未构建。';
+    }
 
     const className = params.className || params.class_name;
     const methodName = params.methodName || params.method_name;
@@ -2977,9 +3536,7 @@ const getMethodOverrides = {
       return `"${className}.${methodName}" 没有在任何子类中被覆写。`;
     }
 
-    const lines = [
-      `🔀 ${className}.${methodName} 的覆写 (${overrides.length} 处):`,
-    ];
+    const lines = [`🔀 ${className}.${methodName} 的覆写 (${overrides.length} 处):`];
     for (const o of overrides) {
       const cx = o.method.complexity > 3 ? ` [复杂度:${o.method.complexity}]` : '';
       lines.push(`  ${o.className} — ${o.filePath}:${o.method.line}${cx}`);
@@ -2993,21 +3550,29 @@ const getMethodOverrides = {
 // ────────────────────────────────────────────────────────────
 const getCategoryMap = {
   name: 'get_category_map',
-  description: '获取指定类或整个项目的 ObjC Category 扩展映射。Category 是 ObjC 的核心模式，了解它有助于发现功能划分。',
+  description:
+    '获取指定类或整个项目的 ObjC Category 扩展映射。Category 是 ObjC 的核心模式，了解它有助于发现功能划分。',
   parameters: {
     type: 'object',
     properties: {
-      className: { type: 'string', description: '类名 — 可选, 不填则返回整个项目中有 Category 的类列表' },
+      className: {
+        type: 'string',
+        description: '类名 — 可选, 不填则返回整个项目中有 Category 的类列表',
+      },
     },
   },
   handler: async (params, ctx) => {
     const graph = _getProjectGraph(ctx);
-    if (!graph) return 'AST 分析不可用 — ProjectGraph 未构建。';
+    if (!graph) {
+      return 'AST 分析不可用 — ProjectGraph 未构建。';
+    }
 
     const className = params.className || params.class_name;
     if (className) {
       const cats = graph.getCategoryExtensions(className);
-      if (cats.length === 0) return `"${className}" 没有 Category 扩展。`;
+      if (cats.length === 0) {
+        return `"${className}" 没有 Category 扩展。`;
+      }
 
       const lines = [`📂 ${className} 的 Category 扩展 (${cats.length}):`];
       for (const cat of cats) {
@@ -3025,18 +3590,22 @@ const getCategoryMap = {
     // 全量概览
     const allClasses = graph.getAllClassNames();
     const withCats = allClasses
-      .map(c => ({ name: c, cats: graph.getCategoryExtensions(c) }))
-      .filter(x => x.cats.length > 0)
+      .map((c) => ({ name: c, cats: graph.getCategoryExtensions(c) }))
+      .filter((x) => x.cats.length > 0)
       .sort((a, b) => b.cats.length - a.cats.length);
 
-    if (withCats.length === 0) return '项目中没有发现 Category 扩展。';
+    if (withCats.length === 0) {
+      return '项目中没有发现 Category 扩展。';
+    }
 
     const lines = [`📂 项目 Category 概览 (${withCats.length} 个类有 Category):`];
     for (const { name, cats } of withCats.slice(0, 30)) {
-      const catNames = cats.map(c => c.categoryName).join(', ');
+      const catNames = cats.map((c) => c.categoryName).join(', ');
       lines.push(`  ${name} — ${cats.length} 个: (${catNames})`);
     }
-    if (withCats.length > 30) lines.push(`... 还有 ${withCats.length - 30} 个类`);
+    if (withCats.length > 30) {
+      lines.push(`... 还有 ${withCats.length - 30} 个类`);
+    }
     return lines.join('\n');
   },
 };
@@ -3047,7 +3616,8 @@ const getCategoryMap = {
 
 const getPreviousAnalysis = {
   name: 'get_previous_analysis',
-  description: '获取前序维度的分析摘要。在 bootstrap 中，每个维度可能有前面维度的分析结果可用。' +
+  description:
+    '获取前序维度的分析摘要。在 bootstrap 中，每个维度可能有前面维度的分析结果可用。' +
     '调用此工具可以获取之前维度产出的候选标题、设计决策等上下文，避免重复分析。' +
     '注意: 只有在你认为前序上下文对当前任务有帮助时才调用。',
   parameters: {
@@ -3062,7 +3632,9 @@ const getPreviousAnalysis = {
     }
 
     const prev = meta.previousAnalysis;
-    if (typeof prev === 'string') return prev;
+    if (typeof prev === 'string') {
+      return prev;
+    }
 
     // 格式化前序分析
     const lines = ['📋 前序维度分析摘要:'];
@@ -3092,7 +3664,8 @@ const getPreviousAnalysis = {
 // ────────────────────────────────────────────────────────────
 const noteFinding = {
   name: 'note_finding',
-  description: '记录一个关键发现到工作记忆的 Scratchpad。在分析过程中发现重要模式、设计决策或事实时调用。' +
+  description:
+    '记录一个关键发现到工作记忆的 Scratchpad。在分析过程中发现重要模式、设计决策或事实时调用。' +
     '这些发现会在上下文窗口压缩后依然保留，确保分析后期不会遗忘早期重要发现。' +
     '建议在发现关键架构模式、核心类职责、重要设计约束时调用。',
   parameters: {
@@ -3100,7 +3673,8 @@ const noteFinding = {
     properties: {
       finding: {
         type: 'string',
-        description: '关键发现描述 (≤150 字)。应是具体、可验证的陈述，例如 "BDNetworkManager 使用单例模式，所有请求通过其发起"',
+        description:
+          '关键发现描述 (≤150 字)。应是具体、可验证的陈述，例如 "BDNetworkManager 使用单例模式，所有请求通过其发起"',
       },
       evidence: {
         type: 'string',
@@ -3135,7 +3709,8 @@ const noteFinding = {
 // ────────────────────────────────────────────────────────────
 const getPreviousEvidence = {
   name: 'get_previous_evidence',
-  description: '获取前序维度对特定文件/类/模式的分析证据。避免重复搜索和读取已经被其他维度分析过的内容。' +
+  description:
+    '获取前序维度对特定文件/类/模式的分析证据。避免重复搜索和读取已经被其他维度分析过的内容。' +
     '当你要搜索某个类名或文件时，先调用此工具看前序维度是否已有发现。',
   parameters: {
     type: 'object',
@@ -3157,10 +3732,7 @@ const getPreviousEvidence = {
       return '没有前序维度的证据可用。';
     }
 
-    const results = episodicMemory.searchEvidence(
-      params.query,
-      params.dimId || undefined
-    );
+    const results = episodicMemory.searchEvidence(params.query, params.dimId || undefined);
 
     if (results.length === 0) {
       return `没有找到与 "${params.query}" 相关的前序证据。建议自行搜索。`;
@@ -3169,7 +3741,9 @@ const getPreviousEvidence = {
     const lines = [`📋 前序维度证据 (匹配 "${params.query}", ${results.length} 条):`];
     for (const r of results.slice(0, 8)) {
       lines.push(`  📄 ${r.filePath}`);
-      lines.push(`     [${r.evidence.dimId}] [${r.evidence.importance || 5}/10] ${r.evidence.finding}`);
+      lines.push(
+        `     [${r.evidence.dimId}] [${r.evidence.importance || 5}/10] ${r.evidence.finding}`
+      );
     }
     if (results.length > 8) {
       lines.push(`  …还有 ${results.length - 8} 条证据`);
@@ -3183,15 +3757,25 @@ const getPreviousEvidence = {
 // ────────────────────────────────────────────────────────────
 const queryCodeGraph = {
   name: 'query_code_graph',
-  description: '查询代码实体图谱 (Code Entity Graph)。可查询类继承链、协议遵循者、实体搜索、影响分析等。' +
+  description:
+    '查询代码实体图谱 (Code Entity Graph)。可查询类继承链、协议遵循者、实体搜索、影响分析等。' +
     '图谱包含从 AST 提取的类、协议、Category、模块、设计模式及其关系。',
   parameters: {
     type: 'object',
     properties: {
       action: {
         type: 'string',
-        enum: ['search', 'inheritance_chain', 'descendants', 'conformances', 'impact', 'topology', 'entity_edges'],
-        description: '查询动作: search=搜索实体, inheritance_chain=继承链, descendants=子类/遵循者, conformances=协议遵循, impact=影响分析, topology=拓扑概览, entity_edges=实体的所有边',
+        enum: [
+          'search',
+          'inheritance_chain',
+          'descendants',
+          'conformances',
+          'impact',
+          'topology',
+          'entity_edges',
+        ],
+        description:
+          '查询动作: search=搜索实体, inheritance_chain=继承链, descendants=子类/遵循者, conformances=协议遵循, impact=影响分析, topology=拓扑概览, entity_edges=实体的所有边',
       },
       entity_id: {
         type: 'string',
@@ -3213,7 +3797,9 @@ const queryCodeGraph = {
     try {
       const { CodeEntityGraph } = await import('./../../service/knowledge/CodeEntityGraph.js');
       const db = ctx?.container?.get('database');
-      if (!db) return '代码实体图谱不可用: 数据库未初始化';
+      if (!db) {
+        return '代码实体图谱不可用: 数据库未初始化';
+      }
 
       const projectRoot = ctx?.projectRoot || process.env.ASD_PROJECT_DIR || '';
       const ceg = new CodeEntityGraph(db, { projectRoot });
@@ -3225,24 +3811,32 @@ const queryCodeGraph = {
             type: params.entity_type,
             limit: 15,
           });
-          if (results.length === 0) return `未找到匹配 "${params.entity_id}" 的代码实体。`;
+          if (results.length === 0) {
+            return `未找到匹配 "${params.entity_id}" 的代码实体。`;
+          }
           const lines = [`🔍 代码实体搜索 "${params.entity_id}" (${results.length} 条):`];
           for (const e of results) {
-            lines.push(`  • ${e.entityType}: \`${e.name}\`${e.filePath ? ` (${e.filePath}:${e.line || '?'})` : ''}${e.superclass ? ` → ${e.superclass}` : ''}`);
+            lines.push(
+              `  • ${e.entityType}: \`${e.name}\`${e.filePath ? ` (${e.filePath}:${e.line || '?'})` : ''}${e.superclass ? ` → ${e.superclass}` : ''}`
+            );
           }
           return lines.join('\n');
         }
 
         case 'inheritance_chain': {
           const chain = ceg.getInheritanceChain(params.entity_id, maxDepth);
-          if (chain.length <= 1) return `\`${params.entity_id}\` 没有已知的继承关系。`;
+          if (chain.length <= 1) {
+            return `\`${params.entity_id}\` 没有已知的继承关系。`;
+          }
           return `📐 继承链: \`${chain.join(' → ')}\``;
         }
 
         case 'descendants': {
           const type = params.entity_type || 'class';
           const desc = ceg.getDescendants(params.entity_id, type, maxDepth);
-          if (desc.length === 0) return `\`${params.entity_id}\` 没有已知的子类/遵循者。`;
+          if (desc.length === 0) {
+            return `\`${params.entity_id}\` 没有已知的子类/遵循者。`;
+          }
           const lines = [`📊 ${params.entity_id} 的后代 (${desc.length}):`];
           for (const d of desc.slice(0, 20)) {
             lines.push(`  ${'  '.repeat(d.depth - 1)}└─ \`${d.id}\` (${d.type}, ${d.relation})`);
@@ -3252,14 +3846,18 @@ const queryCodeGraph = {
 
         case 'conformances': {
           const protos = ceg.getConformances(params.entity_id);
-          if (protos.length === 0) return `\`${params.entity_id}\` 没有已知的协议遵循。`;
-          return `📋 \`${params.entity_id}\` 遵循: ${protos.map(p => '`' + p + '`').join(', ')}`;
+          if (protos.length === 0) {
+            return `\`${params.entity_id}\` 没有已知的协议遵循。`;
+          }
+          return `📋 \`${params.entity_id}\` 遵循: ${protos.map((p) => `\`${p}\``).join(', ')}`;
         }
 
         case 'impact': {
           const type = params.entity_type || 'class';
           const impact = ceg.getImpactRadius(params.entity_id, type, maxDepth);
-          if (impact.length === 0) return `修改 \`${params.entity_id}\` 没有检测到直接影响。`;
+          if (impact.length === 0) {
+            return `修改 \`${params.entity_id}\` 没有检测到直接影响。`;
+          }
           const lines = [`⚡ 修改 \`${params.entity_id}\` 的影响范围 (${impact.length}):`];
           for (const i of impact.slice(0, 20)) {
             lines.push(`  ${'  '.repeat(i.depth - 1)}⬆ \`${i.id}\` (${i.type}, via ${i.relation})`);
@@ -3269,7 +3867,9 @@ const queryCodeGraph = {
 
         case 'topology': {
           const topo = ceg.getTopology();
-          if (topo.totalEntities === 0) return '代码实体图谱为空。需先执行 Bootstrap。';
+          if (topo.totalEntities === 0) {
+            return '代码实体图谱为空。需先执行 Bootstrap。';
+          }
           const lines = ['📈 代码实体图谱概览:'];
           lines.push('  实体:');
           for (const [type, count] of Object.entries(topo.entities)) {
@@ -3289,7 +3889,9 @@ const queryCodeGraph = {
           const type = params.entity_type || 'class';
           const edges = ceg.getEntityEdges(params.entity_id, type);
           const total = edges.outgoing.length + edges.incoming.length;
-          if (total === 0) return `\`${params.entity_id}\` 没有已知的图谱边。`;
+          if (total === 0) {
+            return `\`${params.entity_id}\` 没有已知的图谱边。`;
+          }
           const lines = [`🔗 \`${params.entity_id}\` 的关系 (${total} 条):`];
           if (edges.outgoing.length > 0) {
             lines.push('  出边:');