autosnippet 2.1.0 → 2.5.0

package/lib/service/chat/ChatAgent.js

@@ -27,9 +27,12 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Logger from '../../infrastructure/logging/Logger.js';
 import { TaskPipeline } from './TaskPipeline.js';
+import { Memory } from './Memory.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SKILLS_DIR = path.resolve(__dirname, '../../../skills');
+const PROJECT_ROOT = path.resolve(__dirname, '../../..');
+const SKILLS_DIR = path.resolve(PROJECT_ROOT, 'skills');
+const SOUL_PATH = path.resolve(PROJECT_ROOT, 'SOUL.md');
 const MAX_ITERATIONS = 6;
 
 export class ChatAgent {
@@ -39,6 +42,10 @@ export class ChatAgent {
   #logger;
   /** @type {Map<string, TaskPipeline>} */
   #pipelines = new Map();
+  /** @type {string} 缓存的项目概况（每次 execute 刷新一次） */
+  #projectBriefingCache = '';
+  /** @type {Memory|null} 跨对话轻量记忆 */
+  #memory = null;
 
   /**
    * @param {object} opts
@@ -55,6 +62,12 @@ export class ChatAgent {
     /** 是否有 AI Provider（只读） */
     this.hasAI = !!aiProvider;
 
+    // 初始化跨对话记忆
+    try {
+      const projectRoot = container?.singletons?._projectRoot || process.cwd();
+      this.#memory = new Memory(projectRoot);
+    } catch { /* Memory init failed, degrade silently */ }
+
     // 注册内置 DAG 管线
     this.#registerBuiltinPipelines();
   }
@@ -71,6 +84,9 @@ export class ChatAgent {
    * @returns {Promise<{reply: string, toolCalls: Array, hasContext: boolean}>}
    */
   async execute(prompt, { history = [] } = {}) {
+    // 每次对话刷新项目概况（不是每轮 ReAct）
+    this.#projectBriefingCache = await this.#buildProjectBriefing();
+
     const toolSchemas = this.#toolRegistry.getToolSchemas();
     const systemPrompt = this.#buildSystemPrompt(toolSchemas);
 
@@ -97,11 +113,9 @@ export class ChatAgent {
 
       if (!action) {
         // 没有 Action → 最终回答
-        return {
-          reply: this.#cleanFinalAnswer(response),
-          toolCalls,
-          hasContext: toolCalls.length > 0,
-        };
+        const reply = this.#cleanFinalAnswer(response);
+        this.#extractMemory(prompt, reply);
+        return { reply, toolCalls, hasContext: toolCalls.length > 0 };
       }
 
       // 执行工具
@@ -141,8 +155,11 @@ export class ChatAgent {
       systemPrompt: '直接回答用户问题，不要再调用工具。',
     });
 
+    const finalReply = this.#cleanFinalAnswer(finalResponse);
+    this.#extractMemory(prompt, finalReply);
+
     return {
-      reply: this.#cleanFinalAnswer(finalResponse),
+      reply: finalReply,
       toolCalls,
       hasContext: toolCalls.length > 0,
     };
@@ -574,9 +591,18 @@ ${code.substring(0, 3000)}
       ? `\n## 可用 Skills\n通过 load_skill 工具按需加载领域知识文档，获取操作指南和最佳实践参考。\n\n| Skill | 说明 |\n|---|---|\n${skillList.map(s => `| ${s.name} | ${s.summary || '-'} |`).join('\n')}\n\n**场景 → Skill 推荐**：\n- 冷启动、初始化 → autosnippet-coldstart\n- 深度项目分析 → autosnippet-analysis\n- 候选生成 → autosnippet-candidates + autosnippet-create\n- 代码规范审计 → autosnippet-guard\n- Snippet 概念解释 → autosnippet-concepts\n- 生命周期管理 → autosnippet-lifecycle\n- Swift/ObjC/JS·TS 语言参考 → autosnippet-reference-{swift,objc,jsts}\n- 项目结构分析 → autosnippet-structure\n- 不确定该用哪个 → autosnippet-intent\n`
       : '';
 
-    return `你是 AutoSnippet 项目的统一 AI 中心。项目内所有 AI 推理和分析都通过你执行。
-你拥有 ${toolSchemas.length} 个工具覆盖知识库管理全链路：搜索、提交、审核、质量评估、Guard 检查、知识图谱、冷启动等。
+    // SOUL — AI 人格注入（如果 SOUL.md 存在）
+    let soulSection = '';
+    try {
+      if (fs.existsSync(SOUL_PATH)) {
+        soulSection = '\n' + fs.readFileSync(SOUL_PATH, 'utf-8').trim() + '\n';
+      }
+    } catch { /* SOUL.md not available */ }
 
+    return `${soulSection}
+你是 AutoSnippet 项目的统一 AI 中心。项目内所有 AI 推理和分析都通过你执行。
+你拥有 ${toolSchemas.length} 个工具覆盖知识库管理全链路：搜索、提交、审核、质量评估、Guard 检查、知识图谱、冷启动等。
+${this.#projectBriefingCache}${this.#memory?.toPromptSection() || ''}
 可用工具:
 
 ${toolDescriptions}
@@ -599,7 +625,9 @@ ${skillSection}
    - 候选创建/提交 → load_skill("autosnippet-candidates")
    - 代码规范/Guard → load_skill("autosnippet-guard")
    - 不确定做什么 → load_skill("autosnippet-intent")
-8. 你可以组合多个工具完成复杂任务（如：查重 → 提交 → 质量评分 → 知识图谱关联）。`;
+8. 你可以组合多个工具完成复杂任务（如：查重 → 提交 → 质量评分 → 知识图谱关联）。
+9. 当工具返回 _meta.confidence = "none" 时，告知用户无匹配并建议下一步，不要凭空编造。当 _meta.confidence = "low" 时，明确标注结果不确定性。
+10. 优先使用组合工具（analyze_code, knowledge_overview, submit_with_check）减少调用轮次。`;
   }
 
   /**
@@ -660,24 +688,39 @@ ${skillSection}
 
   /**
    * 列出可用的 Skills 及其摘要（用于系统提示词）
+   * 加载顺序: 内置 skills/ → 项目级 .autosnippet/skills/（同名覆盖）
    * @returns {{ name: string, summary: string }[]}
    */
   #listAvailableSkills() {
+    const skillMap = new Map();
+
+    // 1. 内置 Skills
+    this.#loadSkillsFromDir(SKILLS_DIR, skillMap);
+
+    // 2. 项目级 Skills（覆盖同名内置 Skill）
+    const projectSkillsDir = path.resolve(PROJECT_ROOT, '.autosnippet', 'skills');
+    this.#loadSkillsFromDir(projectSkillsDir, skillMap);
+
+    return Array.from(skillMap.values());
+  }
+
+  /**
+   * 从目录加载 Skills 到 Map
+   */
+  #loadSkillsFromDir(dir, skillMap) {
     try {
-      const dirs = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+      const dirs = fs.readdirSync(dir, { withFileTypes: true })
         .filter(d => d.isDirectory())
         .map(d => d.name);
-      return dirs.map(name => {
-        const skillPath = path.join(SKILLS_DIR, name, 'SKILL.md');
+      for (const name of dirs) {
+        const skillPath = path.join(dir, name, 'SKILL.md');
         let summary = '';
         try {
           const raw = fs.readFileSync(skillPath, 'utf-8');
-          // 从 frontmatter description 或首行 # 后提取摘要
           const fmMatch = raw.match(/^---[\s\S]*?description:\s*["']?(.+?)["']?\s*$/m);
           if (fmMatch) {
             summary = fmMatch[1];
           } else {
-            // fallback: 取首个非空非标题行
             const lines = raw.split('\n');
             for (const line of lines) {
               const trimmed = line.trim();
@@ -688,10 +731,88 @@ ${skillSection}
             }
           }
         } catch { /* SKILL.md not found */ }
-        return { name, summary };
-      });
+        skillMap.set(name, { name, summary });
+      }
+    } catch { /* directory not found */ }
+  }
+
+  /**
+   * 构建项目概况注入到系统提示词（每次 execute 刷新一次）
+   * 单次 SQL 聚合 < 5ms，静默降级
+   */
+  async #buildProjectBriefing() {
+    try {
+      const db = this.#container?.get('database');
+      if (!db) return '';
+      // knowledge_type → kind 映射:
+      //   rule: code-standard, code-style, best-practice, boundary-constraint
+      //   pattern: code-pattern, architecture, solution
+      //   fact: code-relation, inheritance, call-chain, data-flow, module-dependency
+      const stats = db.prepare(`
+        SELECT
+          (SELECT COUNT(*) FROM recipes) as recipeCount,
+          (SELECT COUNT(*) FROM recipes WHERE knowledge_type IN ('code-standard','code-style','best-practice','boundary-constraint')) as ruleCount,
+          (SELECT COUNT(*) FROM recipes WHERE knowledge_type IN ('code-pattern','architecture','solution')) as patternCount,
+          (SELECT COUNT(*) FROM recipes WHERE knowledge_type IN ('code-relation','inheritance','call-chain','data-flow','module-dependency')) as factCount,
+          (SELECT COUNT(*) FROM recipes WHERE knowledge_type = 'boundary-constraint') as guardRuleCount,
+          (SELECT COUNT(*) FROM candidates WHERE status='pending') as pendingCandidates,
+          (SELECT COUNT(*) FROM candidates) as totalCandidates
+      `).get();
+      if (!stats || stats.recipeCount === 0) {
+        return '\n## 项目状态\n⚠️ 知识库为空。建议先执行冷启动（bootstrap_knowledge）。\n';
+      }
+      let section = `\n## 项目状态\n- 知识库: ${stats.recipeCount} 条 Recipe（${stats.ruleCount || 0} rule / ${stats.patternCount || 0} pattern / ${stats.factCount || 0} fact）\n- Guard 规则: ${stats.guardRuleCount || 0} 条\n- 候选: ${stats.pendingCandidates} 条待审 / ${stats.totalCandidates} 条总计\n`;
+      if (stats.pendingCandidates > 10) {
+        section += `\n⚠️ 有 ${stats.pendingCandidates} 条候选积压，建议执行批量审核。\n`;
+      }
+      return section;
     } catch {
-      return [];
+      return ''; // DB 不可用时静默降级
+    }
+  }
+
+  /**
+   * 从用户消息中提取偏好/决策写入 Memory
+   * 使用正则匹配，不调 AI — 零延迟
+   */
+  #extractMemory(prompt, _reply) {
+    if (!this.#memory) return;
+    try {
+      const prefPatterns = [
+        /我们(项目|团队)?(不用|不使用|禁止|避免|偏好|习惯|规范是)/,
+        /以后(都|请|要)/,
+        /记住/,
+      ];
+      if (prefPatterns.some(p => p.test(prompt))) {
+        this.#memory.append({
+          type: 'preference',
+          content: prompt.substring(0, 200),
+          ttl: 30,
+        });
+      }
+    } catch { /* memory write failure is non-critical */ }
+  }
+
+  /**
+   * 事件驱动入口（P2 预留接口）
+   * @param {{ type: string, payload: object, source?: string }} event
+   */
+  async executeEvent(event) {
+    const { type, payload } = event;
+    const prompt = this.#eventToPrompt(type, payload);
+    return this.execute(prompt, { history: [] });
+  }
+
+  #eventToPrompt(type, payload) {
+    switch (type) {
+      case 'file_saved':
+        return `文件 ${payload.filePath} 刚被保存，变更了 ${payload.changedLines} 行。请分析是否有值得提取为 Recipe 的代码模式。如果有，说明原因；没有就说"无需操作"。`;
+      case 'candidate_backlog':
+        return `当前有 ${payload.count} 条候选积压（最早 ${payload.oldest}）。请按质量分类：哪些值得审核、哪些可以直接拒绝、哪些需要补充信息。`;
+      case 'scheduled_health':
+        return `请执行知识库健康检查：Recipe 覆盖率、过时标记、Guard 规则有效性。给出简要报告。`;
+      default:
+        return `事件: ${type}\n${JSON.stringify(payload)}`;
     }
   }
 

package/lib/service/chat/Memory.js

@@ -0,0 +1,104 @@
+/**
+ * Memory — 跨对话轻量记忆
+ *
+ * 设计:
+ * - JSONL 文件存储，每行一条记忆
+ * - 支持 TTL 自动过期
+ * - 上限 maxEntries，超出时截断旧条目
+ * - 读写均做静默降级（Memory 是增强，不是核心路径）
+ *
+ * 记忆类型:
+ * - preference: 用户偏好（"我们不用 singleton"、"以后用 DI"）
+ * - decision:   关键决策（"Network 模块审核通过"）
+ * - context:    项目上下文（"主语言是 Swift，使用 SPM"）
+ *
+ * 文件路径: .autosnippet/memory.jsonl
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class Memory {
+  #filePath;
+  #maxEntries;
+
+  /**
+   * @param {string} projectRoot — 用户项目根目录
+   * @param {object} [opts]
+   * @param {number} [opts.maxEntries=50] — 最大记忆条数
+   */
+  constructor(projectRoot, { maxEntries = 50 } = {}) {
+    this.#filePath = path.join(projectRoot, '.autosnippet', 'memory.jsonl');
+    this.#maxEntries = maxEntries;
+  }
+
+  /**
+   * 读取最近 N 条记忆，过滤过期项
+   * @param {number} [limit=20]
+   * @returns {{ ts: string, type: string, content: string, ttl?: number }[]}
+   */
+  load(limit = 20) {
+    try {
+      if (!fs.existsSync(this.#filePath)) return [];
+      const raw = fs.readFileSync(this.#filePath, 'utf-8').trim();
+      if (!raw) return [];
+      const lines = raw.split('\n').filter(Boolean);
+      const now = Date.now();
+      return lines
+        .map(l => { try { return JSON.parse(l); } catch { return null; } })
+        .filter(Boolean)
+        .filter(m => !m.ttl || (now - new Date(m.ts).getTime()) < m.ttl * 86400000)
+        .slice(-limit);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * 追加一条记忆
+   * @param {{ type: string, content: string, ttl?: number }} entry
+   */
+  append(entry) {
+    try {
+      const dir = path.dirname(this.#filePath);
+      fs.mkdirSync(dir, { recursive: true });
+      const line = JSON.stringify({ ts: new Date().toISOString(), ...entry });
+      fs.appendFileSync(this.#filePath, line + '\n', 'utf-8');
+      this.#compact();
+    } catch { /* write failure non-critical */ }
+  }
+
+  /**
+   * 生成供系统提示词的记忆摘要
+   * @returns {string}
+   */
+  toPromptSection() {
+    const memories = this.load();
+    if (memories.length === 0) return '';
+    const lines = memories.map(m => `- [${m.type}] ${m.content}`).join('\n');
+    return `\n## 历史记忆\n以下是之前对话中积累的项目偏好和决策，请参考：\n${lines}\n`;
+  }
+
+  /**
+   * 当前记忆条数
+   */
+  get size() {
+    return this.load(this.#maxEntries).length;
+  }
+
+  /**
+   * 超过 maxEntries 时截断旧条目
+   */
+  #compact() {
+    try {
+      const raw = fs.readFileSync(this.#filePath, 'utf-8').trim();
+      if (!raw) return;
+      const lines = raw.split('\n').filter(Boolean);
+      if (lines.length > this.#maxEntries) {
+        fs.writeFileSync(this.#filePath, lines.slice(-this.#maxEntries).join('\n') + '\n', 'utf-8');
+      }
+    } catch { /* ignore */ }
+  }
+}
+
+export default Memory;

package/lib/service/chat/tools.js

@@ -1,7 +1,7 @@
 /**
  * tools.js — ChatAgent 全部工具定义
  *
- * 33 个工具覆盖项目全部 AI 能力:
+ * 37 个工具覆盖项目全部 AI 能力:
  *
  * ┌─── 查询类 (8) ─────────────────────────────────┐
  * │  1. search_recipes       搜索 Recipe            │
@@ -53,6 +53,11 @@
  * │ 32. load_skill            加载 Agent Skill 文档   │
  * │ 33. bootstrap_knowledge   冷启动知识库初始化      │
  * └─────────────────────────────────────────────────────┘
+ * ┌─── 组合工具 (3) ───────────────────────────────────┐
+ * │ 34. analyze_code          Guard + Recipe 搜索      │
+ * │ 35. knowledge_overview    全局知识库概览           │
+ * │ 36. submit_with_check     查重 + 提交              │
+ * └─────────────────────────────────────────────────────┘
  */
 
 import fs from 'node:fs';
@@ -63,8 +68,11 @@ import Logger from '../../infrastructure/logging/Logger.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const PROJECT_ROOT = path.resolve(__dirname, '../../..');
 /** skills/ 目录绝对路径 */
-const SKILLS_DIR = path.resolve(__dirname, '../../../skills');
+const SKILLS_DIR = path.resolve(PROJECT_ROOT, 'skills');
+/** 项目级 skills 目录 */
+const PROJECT_SKILLS_DIR = path.resolve(PROJECT_ROOT, '.autosnippet', 'skills');
 
 // ────────────────────────────────────────────────────────────
 // 1. search_recipes
@@ -206,7 +214,24 @@ const searchKnowledge = {
       const searchEngine = ctx.container.get('searchEngine');
       const results = await searchEngine.search(query, { limit: topK });
       if (results && results.length > 0) {
-        return { source: 'searchEngine', results: results.slice(0, topK) };
+        const enriched = results.slice(0, topK).map((r, i) => ({
+          ...r,
+          reasoning: {
+            whyRelevant: r.score != null
+              ? `匹配分 ${(r.score * 100).toFixed(0)}%` + (r.matchType ? ` (${r.matchType})` : '')
+              : '语义相关',
+            rank: i + 1,
+          },
+        }));
+        const topScore = enriched[0]?.score ?? 0;
+        return {
+          source: 'searchEngine',
+          results: enriched,
+          _meta: {
+            confidence: topScore > 0.7 ? 'high' : topScore > 0.3 ? 'medium' : 'low',
+            hint: topScore < 0.3 ? '匹配度较低，结果可能不够相关。建议尝试更具体的查询词。' : null,
+          },
+        };
       }
     } catch { /* SearchEngine not available */ }
 
@@ -233,7 +258,7 @@ const searchKnowledge = {
       }
     } catch { /* RetrievalFunnel not available */ }
 
-    return { source: 'none', results: [], message: 'No search engine available' };
+    return { source: 'none', results: [], message: 'No search engine available', _meta: { confidence: 'none', hint: '搜索引擎不可用。请确认向量索引已构建（rebuild_index）。' } };
   },
 };
 
@@ -464,6 +489,13 @@ const checkDuplicate = {
       similar,
       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，建议人工审核是否重复。'
+          : '有低相似度匹配，大概率不是重复。',
+      },
     };
   },
 };
@@ -696,6 +728,7 @@ const guardCheckCode = {
     try {
       const engine = ctx.container.get('guardCheckEngine');
       const violations = engine.checkCode(code, language || 'unknown', { scope });
+      // reasoning 已由 GuardCheckEngine.checkCode() 内置附加
       return { violationCount: violations.length, violations };
     } catch { /* not available */ }
 
@@ -1116,15 +1149,19 @@ const loadSkill = {
     required: ['skillName'],
   },
   handler: async (params) => {
-    const skillPath = path.join(SKILLS_DIR, params.skillName, 'SKILL.md');
+    // 项目级 Skills 优先（覆盖同名内置 Skill）
+    const projectSkillPath = path.join(PROJECT_SKILLS_DIR, params.skillName, 'SKILL.md');
+    const builtinSkillPath = path.join(SKILLS_DIR, params.skillName, 'SKILL.md');
+    const skillPath = fs.existsSync(projectSkillPath) ? projectSkillPath : builtinSkillPath;
     try {
       const content = fs.readFileSync(skillPath, 'utf8');
-      return { skillName: params.skillName, content };
+      const source = skillPath === projectSkillPath ? 'project' : 'builtin';
+      return { skillName: params.skillName, source, content };
     } catch {
-      const available = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
-        .filter(d => d.isDirectory())
-        .map(d => d.name);
-      return { error: `Skill "${params.skillName}" not found`, availableSkills: available };
+      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 {}
+      return { error: `Skill "${params.skillName}" not found`, availableSkills: [...available] };
     }
   },
 };
@@ -1166,6 +1203,199 @@ const bootstrapKnowledgeTool = {
 // 导出全部工具
 // ────────────────────────────────────────────────────────────
 
+// ────────────────────────────────────────────────────────────
+// 34. analyze_code — 组合工具 (Guard + Recipe 搜索)
+// ────────────────────────────────────────────────────────────
+const analyzeCode = {
+  name: 'analyze_code',
+  description: '综合分析一段代码：Guard 规范检查 + 相关 Recipe 搜索。一次调用完成完整分析，减少多轮工具调用。',
+  parameters: {
+    type: 'object',
+    properties: {
+      code:     { type: 'string', description: '待分析的源码' },
+      language: { type: 'string', description: '编程语言 (swift/objc/javascript 等)' },
+      filePath: { type: 'string', description: '文件路径（可选，用于上下文）' },
+    },
+    required: ['code'],
+  },
+  handler: async (params, ctx) => {
+    const { code, language, filePath } = params;
+    const results = {};
+
+    // 并行执行 Guard 检查 + Recipe 搜索
+    const [guardResult, searchResult] = await Promise.all([
+      (async () => {
+        try {
+          const engine = ctx.container.get('guardCheckEngine');
+          const violations = engine.checkCode(code, language || 'unknown', { scope: 'file' });
+          return { violationCount: violations.length, violations };
+        } catch {
+          try {
+            const guardService = ctx.container.get('guardService');
+            const matches = await guardService.checkCode(code, { language });
+            return { violationCount: matches.length, violations: matches };
+          } catch { return { violationCount: 0, violations: [] }; }
+        }
+      })(),
+      (async () => {
+        try {
+          const searchEngine = ctx.container.get('searchEngine');
+          // 取代码首段作为搜索词
+          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 }; }
+      })(),
+    ]);
+
+    results.guard = guardResult;
+    results.relatedRecipes = searchResult;
+    results.filePath = filePath || '(inline)';
+
+    const hasFindings = guardResult.violationCount > 0 || searchResult.total > 0;
+    results._meta = {
+      confidence: hasFindings ? 'high' : 'low',
+      hint: hasFindings
+        ? `已完成 Guard 检查（${guardResult.violationCount} 个违规）+ Recipe 搜索（${searchResult.total} 条匹配）。`
+        : '未发现 Guard 违规，也未找到相关 Recipe。可能需要先冷启动知识库。',
+    };
+
+    return results;
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+// 35. knowledge_overview — 组合工具 (一次获取全部类型的 Recipe 统计)
+// ────────────────────────────────────────────────────────────
+const knowledgeOverview = {
+  name: 'knowledge_overview',
+  description: '一次性获取知识库全貌：各类型 Recipe 分布 + 候选状态 + 知识图谱概况 + 质量概览。比分别调用 get_project_stats + search_recipes 更高效。',
+  parameters: {
+    type: 'object',
+    properties: {
+      includeTopRecipes: { type: 'boolean', description: '是否包含热门 Recipe 列表，默认 true' },
+      limit: { type: 'number', description: '每类返回数量，默认 5' },
+    },
+  },
+  handler: async (params, ctx) => {
+    const { includeTopRecipes = true, limit = 5 } = params;
+    const result = {};
+
+    // 并行获取统计 + 可选的热门列表
+    const [statsResult, feedbackResult] = await Promise.all([
+      (async () => {
+        try {
+          const recipeService = ctx.container.get('recipeService');
+          const candidateService = ctx.container.get('candidateService');
+          const [rs, cs] = await Promise.all([
+            recipeService.getRecipeStats(),
+            candidateService.getCandidateStats(),
+          ]);
+          return { recipes: rs, candidates: cs };
+        } catch { return null; }
+      })(),
+      (async () => {
+        if (!includeTopRecipes) return null;
+        try {
+          const feedbackCollector = ctx.container.get('feedbackCollector');
+          return feedbackCollector.getTopRecipes(limit);
+        } catch { return null; }
+      })(),
+    ]);
+
+    if (statsResult) {
+      result.recipes = statsResult.recipes;
+      result.candidates = statsResult.candidates;
+    }
+
+    // 知识图谱统计
+    try {
+      const kgService = ctx.container.get('knowledgeGraphService');
+      result.knowledgeGraph = kgService.getStats();
+    } catch { /* KG not available */ }
+
+    if (feedbackResult) result.topRecipes = feedbackResult;
+
+    const recipeCount = result.recipes?.total || result.recipes?.count || 0;
+    result._meta = {
+      confidence: recipeCount > 0 ? 'high' : 'none',
+      hint: recipeCount === 0 ? '知识库为空，建议先执行冷启动（bootstrap_knowledge）。' : null,
+    };
+
+    return result;
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+// 36. submit_with_check — 组合工具 (查重 + 提交)
+// ────────────────────────────────────────────────────────────
+const submitWithCheck = {
+  name: 'submit_with_check',
+  description: '安全提交候选：先执行查重检测，无重复则自动提交。如果发现高度相似 Recipe 则阻止并返回相似列表。一次调用完成 check_duplicate + submit_candidate。',
+  parameters: {
+    type: 'object',
+    properties: {
+      code:     { type: 'string', description: '代码内容' },
+      language: { type: 'string', description: '编程语言' },
+      category: { type: 'string', description: '分类 (View/Service/Tool/Model 等)' },
+      title:    { type: 'string', description: '候选标题' },
+      summary:  { type: 'string', description: '摘要' },
+      threshold: { type: 'number', description: '相似度阈值，默认 0.7' },
+    },
+    required: ['code', 'language', 'category'],
+  },
+  handler: async (params, ctx) => {
+    const { code, language, category, title, summary, threshold = 0.7 } = params;
+    const projectRoot = ctx.projectRoot;
+
+    // Step 1: 查重
+    const cand = { title: title || '', summary: summary || '', code };
+    const similar = findSimilarRecipes(projectRoot, cand, { threshold: 0.5, topK: 5 });
+    const hasDuplicate = similar.some(s => s.similarity >= threshold);
+
+    if (hasDuplicate) {
+      return {
+        submitted: false,
+        reason: 'duplicate_blocked',
+        similar,
+        highestSimilarity: similar[0]?.similarity || 0,
+        _meta: {
+          confidence: 'high',
+          hint: `发现高度相似 Recipe（相似度 ${(similar[0]?.similarity * 100).toFixed(0)}%），已阻止提交。请人工审核。`,
+        },
+      };
+    }
+
+    // Step 2: 提交
+    try {
+      const candidateService = ctx.container.get('candidateService');
+      const item = {
+        code,
+        language,
+        category,
+        title: title || '',
+        summary_cn: summary || '',
+        reasoning: { whyStandard: 'Submitted via submit_with_check', sources: ['agent'], confidence: 0.7 },
+      };
+      const created = await candidateService.createFromToolParams(item, 'agent', {}, { userId: 'agent' });
+
+      return {
+        submitted: true,
+        candidate: created,
+        similar: similar.length > 0 ? similar : [],
+        _meta: {
+          confidence: 'high',
+          hint: similar.length > 0
+            ? `已提交，但有 ${similar.length} 个低相似度匹配，大概率不是重复。`
+            : '已提交，无重复风险。',
+        },
+      };
+    } catch (err) {
+      return { submitted: false, reason: 'submit_error', error: err.message };
+    }
+  },
+};
+
 export const ALL_TOOLS = [
   // 查询类 (8)
   searchRecipes,
@@ -1209,6 +1439,10 @@ export const ALL_TOOLS = [
   // Skills & Bootstrap (2)
   loadSkill,
   bootstrapKnowledgeTool,
+  // 组合工具 (3) — 减少 ReAct 轮次
+  analyzeCode,
+  knowledgeOverview,
+  submitWithCheck,
 ];
 
 export default ALL_TOOLS;