autosnippet 2.9.0 → 2.11.0

package/lib/service/chat/tools.js

@@ -33,7 +33,7 @@
  * │ 17. generate_guard_rule  AI 生成 Guard 规则       │
  * └─────────────────────────────────────────────────────┘
  * ┌─── 生命周期操作类 (7) ─────────────────────────────┐
- * │ 18. submit_candidate     提交候选                │
+ * │ 18. submit_knowledge     提交候选                │
  * │ 19. approve_candidate    批准候选                │
  * │ 20. reject_candidate     驳回候选                │
  * │ 21. publish_recipe       发布 Recipe              │
@@ -853,19 +853,19 @@ const searchRecipes = {
     },
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
+    const knowledgeService = ctx.container.get('knowledgeService');
     const { keyword, category, language, knowledgeType, limit = 10 } = params;
 
     if (keyword) {
-      return recipeService.searchRecipes(keyword, { page: 1, pageSize: limit });
+      return knowledgeService.search(keyword, { page: 1, pageSize: limit });
     }
 
-    const filters = {};
+    const filters = { lifecycle: 'active' };
     if (category)      filters.category = category;
     if (language)      filters.language = language;
     if (knowledgeType) filters.knowledgeType = knowledgeType;
 
-    return recipeService.listRecipes(filters, { page: 1, pageSize: limit });
+    return knowledgeService.list(filters, { page: 1, pageSize: limit });
   },
 };
 
@@ -886,19 +886,20 @@ const searchCandidates = {
     },
   },
   handler: async (params, ctx) => {
-    const candidateService = ctx.container.get('candidateService');
+    const knowledgeService = ctx.container.get('knowledgeService');
     const { keyword, status, language, category, limit = 10 } = params;
 
     if (keyword) {
-      return candidateService.searchCandidates(keyword, { page: 1, pageSize: limit });
+      return knowledgeService.search(keyword, { page: 1, pageSize: limit });
     }
 
+    // V3: status 映射为 lifecycle
     const filters = {};
-    if (status)   filters.status = status;
+    if (status)   filters.lifecycle = status;
     if (language) filters.language = language;
     if (category) filters.category = category;
 
-    return candidateService.listCandidates(filters, { page: 1, pageSize: limit });
+    return knowledgeService.list(filters, { page: 1, pageSize: limit });
   },
 };
 
@@ -916,10 +917,13 @@ const getRecipeDetail = {
     required: ['recipeId'],
   },
   handler: async (params, ctx) => {
-    const recipeRepo = ctx.container.get('recipeRepository');
-    const recipe = await recipeRepo.findById(params.recipeId);
-    if (!recipe) return { error: `Recipe '${params.recipeId}' not found` };
-    return recipe;
+    const knowledgeService = ctx.container.get('knowledgeService');
+    try {
+      const entry = await knowledgeService.get(params.recipeId);
+      return typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+    } catch {
+      return { error: `Knowledge entry '${params.recipeId}' not found` };
+    }
   },
 };
 
@@ -931,13 +935,8 @@ const getProjectStats = {
   description: '获取项目知识库的整体统计：Recipe 数量/分类分布、候选项数量/状态分布、知识图谱节点/边数。',
   parameters: { type: 'object', properties: {} },
   handler: async (_params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    const candidateService = ctx.container.get('candidateService');
-
-    const [recipeStats, candidateStats] = await Promise.all([
-      recipeService.getRecipeStats(),
-      candidateService.getCandidateStats(),
-    ]);
+    const knowledgeService = ctx.container.get('knowledgeService');
+    const stats = await knowledgeService.getStats();
 
     // 尝试获取知识图谱统计
     let graphStats = null;
@@ -947,8 +946,7 @@ const getProjectStats = {
     } catch { /* KG not available */ }
 
     return {
-      recipes: recipeStats,
-      candidates: candidateStats,
+      knowledge: stats,
       knowledgeGraph: graphStats,
     };
   },
@@ -1000,15 +998,16 @@ const searchKnowledge = {
     // 降级: RetrievalFunnel + 全量候选
     try {
       const funnel = ctx.container.get('retrievalFunnel');
-      const recipeRepo = ctx.container.get('recipeRepository');
-      const allRecipes = await recipeRepo.findAll?.() || [];
+      const knowledgeRepo = ctx.container.get('knowledgeRepository');
+      const allResult = await knowledgeRepo.findWithPagination({}, { page: 1, pageSize: 500 });
+      const allRecipes = allResult?.items || [];
 
       // 规范化为 funnel 输入格式
       const candidates = allRecipes.map(r => ({
         id: r.id,
         title: r.title,
         content: r.content || r.code || '',
-        description: r.description || r.summary_cn || '',
+        description: r.description || '',
         language: r.language,
         category: r.category,
         trigger: r.trigger || '',
@@ -1088,7 +1087,7 @@ const extractRecipes = {
   },
   handler: async (params, ctx) => {
     if (!ctx.aiProvider) return { error: 'AI provider not available' };
-    const { targetName, files } = params;
+    const { targetName, files, comprehensive } = params;
 
     // 加载语言参考 Skill（如有），注入到 AI 提取 prompt
     let skillReference = null;
@@ -1124,17 +1123,16 @@ const extractRecipes = {
     const extractOpts = {};
     if (skillReference) extractOpts.skillReference = skillReference;
     if (astContext) extractOpts.astContext = astContext;
+    if (comprehensive) extractOpts.comprehensive = true;
 
     // 首选：使用当前 aiProvider
+    let recipes;
+    let fallbackUsed;
     try {
-      const recipes = await ctx.aiProvider.extractRecipes(targetName, files, extractOpts);
-      const count = Array.isArray(recipes) ? recipes.length : 0;
-      if (count === 0) {
-        ctx.logger?.warn?.(`[extract_recipes] AI returned 0 recipes for ${targetName} (${files.length} files)`);
-      }
-      return { targetName, extracted: count, recipes: Array.isArray(recipes) ? recipes : [] };
+      recipes = await ctx.aiProvider.extractRecipes(targetName, files, extractOpts);
     } catch (primaryErr) {
       // 尝试 fallback（如果 AiFactory 可用）
+      let recovered = false;
       try {
         const aiFactory = ctx.container?.singletons?._aiFactory;
         if (aiFactory?.isGeoOrProviderError?.(primaryErr)) {
@@ -1143,14 +1141,67 @@ const extractRecipes = {
           for (const fbName of fallbacks) {
             try {
               const fbProvider = aiFactory.createProvider({ provider: fbName });
-              const recipes = await fbProvider.extractRecipes(targetName, files, extractOpts);
-              return { targetName, extracted: Array.isArray(recipes) ? recipes.length : 0, recipes: Array.isArray(recipes) ? recipes : [], fallbackUsed: fbName };
+              recipes = await fbProvider.extractRecipes(targetName, files, extractOpts);
+              fallbackUsed = fbName;
+              recovered = true;
+              break;
             } catch { /* next fallback */ }
           }
         }
-      } catch { /* AiFactory not available, rethrow original */ }
-      throw primaryErr;
+      } catch { /* AiFactory not available */ }
+      if (!recovered) throw primaryErr;
     }
+
+    if (!Array.isArray(recipes)) recipes = [];
+    if (recipes.length === 0) {
+      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 */ }
+
+    for (const recipe of recipes) {
+      // 来源 & 生命周期（非 AI 职责）
+      recipe.source = recipe.source || 'ai-scan';
+      recipe.lifecycle = recipe.lifecycle || 'pending';
+
+      // RecipeExtractor 语义标签增强（程序化补充，不替代 AI tags）
+      const codeText = recipe.content?.pattern || '';
+      if (recipeExtractor && codeText) {
+        try {
+          const extracted = recipeExtractor.extractFromContent(
+            codeText, `${recipe.title || 'unknown'}.${recipe.language || 'swift'}`, ''
+          );
+          if (extracted.semanticTags?.length > 0) {
+            recipe.tags = [...new Set([...(recipe.tags || []), ...extracted.semanticTags])];
+          }
+          if ((!recipe.category || recipe.category === 'Utility') && extracted.category && extracted.category !== 'general') {
+            recipe.category = extracted.category;
+          }
+        } catch { /* best effort */ }
+      }
+
+      // QualityScorer 评分 → quality 结构化
+      if (qualityScorer) {
+        try {
+          const scoreResult = qualityScorer.score(recipe);
+          recipe.quality = {
+            completeness: 0,
+            adaptation: 0,
+            documentation: 0,
+            overall: scoreResult.score ?? 0,
+            grade: scoreResult.grade || '',
+          };
+        } catch { /* best effort */ }
+      }
+    }
+
+    const result = { targetName, extracted: recipes.length, recipes };
+    if (fallbackUsed) result.fallbackUsed = fallbackUsed;
+    return result;
   },
 };
 
@@ -1169,12 +1220,10 @@ const enrichCandidate = {
   },
   handler: async (params, ctx) => {
     if (!ctx.aiProvider) return { error: 'AI provider not available' };
-    const candidateService = ctx.container.get('candidateService');
-    return candidateService.enrichCandidates(
-      params.candidateIds,
-      ctx.aiProvider,
-      { userId: 'agent' },
-    );
+    // V3: 使用 MCP handler enrichCandidates 的逻辑
+    const { enrichCandidates: enrichFn } = await import('../../external/mcp/handlers/candidate.js');
+    const result = await enrichFn(ctx, { candidateIds: params.candidateIds });
+    return result?.data || result;
   },
 };
 
@@ -1194,20 +1243,14 @@ const refineBootstrapCandidates = {
   },
   handler: async (params, ctx) => {
     if (!ctx.aiProvider) return { error: 'AI provider not available' };
-    const candidateService = ctx.container.get('candidateService');
-
-    // 接入 BootstrapTaskManager 双通道推送 refine:* 事件到前端
-    let onProgress = null;
-    try {
-      const taskManager = ctx.container.get('bootstrapTaskManager');
-      onProgress = (eventName, data) => taskManager.emitProgress(eventName, data);
-    } catch { /* optional: no realtime push */ }
-
-    return candidateService.refineBootstrapCandidates(
-      ctx.aiProvider,
-      { candidateIds: params.candidateIds, userPrompt: params.userPrompt, dryRun: params.dryRun, onProgress },
-      { userId: 'agent' },
-    );
+    // V3: 委托给 bootstrap handler 的 refine 逻辑
+    const { bootstrapRefine } = await import('../../external/mcp/handlers/bootstrap.js');
+    const result = await bootstrapRefine(ctx, {
+      candidateIds: params.candidateIds,
+      userPrompt: params.userPrompt,
+      dryRun: params.dryRun,
+    });
+    return result?.data || result;
   },
 };
 
@@ -1231,18 +1274,18 @@ const checkDuplicate = {
     const projectRoot = params.projectRoot || ctx.projectRoot;
     const threshold = params.threshold ?? 0.5;
 
-    // 如果提供 candidateId，从数据库读取候选信息
+    // 如果提供 candidateId，从数据库读取条目信息
     if (!cand && params.candidateId) {
       try {
-        const candidateRepo = ctx.container.get('candidateRepository');
-        const found = await candidateRepo.findById(params.candidateId);
+        const knowledgeService = ctx.container.get('knowledgeService');
+        const found = await knowledgeService.get(params.candidateId);
         if (found) {
-          const meta = found.metadata || {};
+          const json = typeof found.toJSON === 'function' ? found.toJSON() : found;
           cand = {
-            title: meta.title || '',
-            summary: meta.summary_cn || meta.summary || '',
-            code: found.code || '',
-            usageGuide: meta.usageGuide_cn || meta.usageGuide || '',
+            title: json.title || '',
+            summary: json.description || '',
+            code: json.content?.pattern || '',
+            usageGuide: '',
           };
         }
       } catch { /* ignore */ }
@@ -1442,8 +1485,9 @@ const getRecommendations = {
     },
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    return recipeService.getRecommendations(params.limit || 10);
+    const knowledgeService = ctx.container.get('knowledgeService');
+    // V3: 推荐 = 活跃条目按使用量排序
+    return knowledgeService.list({ lifecycle: 'active' }, { page: 1, pageSize: params.limit || 10 });
   },
 };
 
@@ -1463,16 +1507,16 @@ const aiTranslate = {
   handler: async (params, ctx) => {
     if (!ctx.aiProvider) return { error: 'AI provider not available' };
     const { summary, usageGuide } = params;
-    if (!summary && !usageGuide) return { summary_en: '', usageGuide_en: '' };
+    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: { "summary_en": "...", "usageGuide_en": "..." }.';
+    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}`);
 
     const raw = await ctx.aiProvider.chat(parts.join('\n'), { systemPrompt, temperature: 0.2 });
     const parsed = ctx.aiProvider.extractJSON(raw, '{', '}');
-    return parsed || { summary_en: summary || '', usageGuide_en: usageGuide || '' };
+    return parsed || { summaryEn: summary || '', usageGuideEn: usageGuide || '' };
   },
 };
 
@@ -1632,24 +1676,24 @@ const DIMENSION_DISPLAY_GROUP = {
 };
 
 // ────────────────────────────────────────────────────────────
-// Bootstrap 维度类型校验 — submit_candidate / submit_with_check 共用
+// Bootstrap 维度类型校验 — submit_knowledge / submit_with_check 共用
 // 基于 dimensionMeta 类型标注系统，而非关键词模糊匹配
 // ────────────────────────────────────────────────────────────
 
 /**
  * 基于维度元数据 (dimensionMeta) 检查提交是否合法
  * @param {{ id: string, outputType: 'candidate'|'skill'|'dual', allowedKnowledgeTypes: string[] }} dimensionMeta
- * @param {object} params - submit_candidate 的参数
+ * @param {object} params - submit_knowledge 的参数
  * @param {object} [logger]
  * @returns {{ status: string, reason: string } | null} 不合法返回 rejected，合法返回 null
  */
 function _checkDimensionType(dimensionMeta, params, logger) {
   // 1. Skill-only 维度不允许提交 Candidate
   if (dimensionMeta.outputType === 'skill') {
-    logger?.info(`[submit_candidate] ✗ rejected — dimension "${dimensionMeta.id}" is skill-only, cannot submit candidates`);
+    logger?.info(`[submit_knowledge] ✗ rejected — dimension "${dimensionMeta.id}" is skill-only, cannot submit candidates`);
     return {
       status: 'rejected',
-      reason: `当前维度 "${dimensionMeta.id}" 的输出类型为 skill-only，不允许调用 submit_candidate。请只在最终回复中提供 dimensionDigest JSON。`,
+      reason: `当前维度 "${dimensionMeta.id}" 的输出类型为 skill-only，不允许调用 submit_knowledge。请只在最终回复中提供 dimensionDigest JSON。`,
     };
   }
 
@@ -1658,7 +1702,7 @@ function _checkDimensionType(dimensionMeta, params, logger) {
   if (allowed.length > 0 && params.knowledgeType) {
     if (!allowed.includes(params.knowledgeType)) {
       const corrected = allowed[0];
-      logger?.warn(`[submit_candidate] knowledgeType "${params.knowledgeType}" → "${corrected}" (auto-corrected for dimension "${dimensionMeta.id}")`);
+      logger?.warn(`[submit_knowledge] knowledgeType "${params.knowledgeType}" → "${corrected}" (auto-corrected for dimension "${dimensionMeta.id}")`);
       params.knowledgeType = corrected;
     }
   }
@@ -1666,93 +1710,137 @@ function _checkDimensionType(dimensionMeta, params, logger) {
   return null;
 }
 
-// 16. submit_candidate
+// 16. submit_knowledge
 // ────────────────────────────────────────────────────────────
 const submitCandidate = {
-  name: 'submit_candidate',
+  name: 'submit_knowledge',
   description: '提交新的代码候选项到知识库审核队列。',
   parameters: {
     type: 'object',
     properties: {
-      code:          { type: 'string', description: '代码内容（项目特写风格 Markdown: 描述和代码交织）' },
-      language:      { type: 'string', description: '编程语言 (objectivec/swift/java/kotlin 等)' },
-      category:      { type: 'string', description: '分类 (View/Service/Tool/Model/Network/Storage/UI/Utility/Core)' },
-      title:         { type: 'string', description: '候选标题，如 "[Bootstrap] best-practice/单例模式"' },
-      summary:       { type: 'string', description: '≤80字精准摘要，引用真实类名和数字' },
-      tags:          { type: 'array', items: { type: 'string' }, description: '标签列表，如 ["bootstrap", "singleton"]' },
-      knowledgeType: { type: 'string', description: '知识类型: best-practice / code-pattern / architecture / convention' },
-      source:        { type: 'string', description: '来源 (bootstrap/agent/mcp)，默认 agent' },
-      reasoning:     { type: 'object', description: '推理依据 { whyStandard: string, sources: string[], confidence: number }' },
-      metadata:      { type: 'object', description: '其他元数据 (不常用，优先使用上面的顶层字段)' },
+      // ── 内容（V3 content 子对象） ──
+      content:       { type: 'object', description: '{ markdown: "项目特写 Markdown", pattern: "核心代码 3-8 行" }' },
+
+      // ── 基本信息 ──
+      title:         { type: 'string', description: '候选标题' },
+      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 开头）' },
+
+      // ── 推理 ──
+      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: '来源文件相对路径' },
     },
-    required: ['code', 'language', 'category', 'title'],
+    required: ['content', 'title', 'trigger', 'kind', 'doClause'],
   },
   handler: async (params, ctx) => {
-    const candidateService = ctx.container.get('candidateService');
+    const knowledgeService = ctx.container.get('knowledgeService');
 
-    // ── Bootstrap 维度类型校验 (基于 dimensionMeta 类型标注) ──
+    // ── Bootstrap 维度类型校验 ──
     const dimMeta = ctx._dimensionMeta;
     if (dimMeta && ctx.source === 'system') {
       const rejected = _checkDimensionType(dimMeta, params, ctx.logger);
       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');
 
-      // 自动补充 knowledgeType（AI 未填时用维度默认值）
-      if (!params.knowledgeType && dimMeta.allowedKnowledgeTypes?.length > 0) {
-        params.knowledgeType = dimMeta.allowedKnowledgeTypes[0];
-      }
-
-      // Bootstrap 模式: 将 category 覆盖为展示分组 ID，确保前端按合并后的分组展示
-      // AI 可能填 "UI"/"Core" 等功能分类，但前端通过 BOOTSTRAP_DIM_LABELS 按展示分组分组
-      params.category = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
+      // Bootstrap 模式: 将 category 覆盖为展示分组 ID
+      params._category = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
 
-      // ── CandidateGuardrail 质量验证 (Bootstrap 模式) ──
+      // ── CandidateGuardrail 质量验证 ──
       const guardrail = new CandidateGuardrail(
         ctx._submittedTitles || new Set(),
         dimMeta,
       );
       const guardResult = guardrail.validate(params);
       if (!guardResult.valid) {
-        ctx.logger?.info(`[submit_candidate] ✗ guardrail rejected: ${guardResult.error}`);
+        ctx.logger?.info(`[submit_knowledge] ✗ guardrail rejected: ${guardResult.error}`);
         return {
           status: 'rejected',
           error: guardResult.error,
-          hint: '请根据错误信息调整内容后重新提交。候选的 code 字段必须是「项目特写」风格，包含代码片段和项目上下文。',
+          hint: '请根据错误信息调整内容后重新提交。',
         };
       }
     }
 
-    // 将所有顶层字段展开到 item — LLM 可能把 title/summary/tags 等
-    // 放在顶层而非 metadata 中（production prompt 指引）
-    const { code, language, category, source, reasoning, metadata, ...rest } = params;
+    // ── 系统自动设置 ──
+    const systemFields = {
+      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',
+    };
 
-    // 防御性修复: AI 可能提交 reasoning.sources = [] 空数组，自动从 filePaths 补充
-    const finalReasoning = reasoning || { whyStandard: 'Submitted via ChatAgent', sources: ['agent'], confidence: 0.7 };
-    if (Array.isArray(finalReasoning.sources) && finalReasoning.sources.length === 0) {
-      const fallbackSources = params.filePaths || rest.filePaths;
-      if (Array.isArray(fallbackSources) && fallbackSources.length > 0) {
-        finalReasoning.sources = fallbackSources;
-      } else {
-        finalReasoning.sources = ['agent'];
-      }
+    // ── 直传 → KnowledgeEntry ──
+    const reasoning = params.reasoning || { whyStandard: '', sources: ['agent'], confidence: 0.7 };
+    if (Array.isArray(reasoning.sources) && reasoning.sources.length === 0) {
+      reasoning.sources = ['agent'];
+    }
+
+    // V3 content 直透
+    const contentObj = params.content && typeof params.content === 'object'
+      ? params.content
+      : { markdown: '', pattern: '' };
+
+    const data = {
+      ...systemFields,
+      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,
+      reasoning,
+      // V3 扩展字段直透
+      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]
+                         : ''),
+      // 7.3.9 agentNotes/aiInsight 注入
+      agentNotes:  dimMeta
+                     ? { dimensionId: dimMeta.id, outputType: dimMeta.outputType || 'candidate' }
+                     : null,
+      aiInsight:   reasoning.whyStandard || params.description || null,
+    };
+
+    if (dimMeta && ctx.source === 'system') {
+      const displayGroup = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
+      data.tags = [...new Set([...(data.tags || []), displayGroup])];
     }
 
-    const item = {
-      code,
-      language,
-      category,
-      ...rest,                     // 顶层扩展字段 (title, summary, knowledgeType, tags 等)
-      ...metadata,                 // metadata 对象 (如有)
-      reasoning: finalReasoning,
-    };
-    // Bootstrap 模式额外注入 targetName — 前端优先按 meta.targetName 分组
-    const displayGroup = dimMeta ? (DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id) : null;
-    const extraMeta = (dimMeta && ctx.source === 'system') ? { targetName: displayGroup } : {};
-    return candidateService.createFromToolParams(item, source || 'agent', extraMeta, { userId: 'agent' });
+    const saved = await knowledgeService.create(data, { userId: 'agent' });
+
+    // ── QualityScorer 自动评分 ──
+    try {
+      await knowledgeService.updateQuality(saved.id, { userId: 'agent' });
+    } catch { /* best effort — 不阻塞创建流程 */ }
+
+    return saved;
   },
 };
 
@@ -1770,8 +1858,8 @@ const approveCandidate = {
     required: ['candidateId'],
   },
   handler: async (params, ctx) => {
-    const candidateService = ctx.container.get('candidateService');
-    return candidateService.approveCandidate(params.candidateId, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.approve(params.candidateId, { userId: 'agent' });
   },
 };
 
@@ -1790,8 +1878,8 @@ const rejectCandidate = {
     required: ['candidateId', 'reason'],
   },
   handler: async (params, ctx) => {
-    const candidateService = ctx.container.get('candidateService');
-    return candidateService.rejectCandidate(params.candidateId, params.reason, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.reject(params.candidateId, params.reason, { userId: 'agent' });
   },
 };
 
@@ -1809,8 +1897,8 @@ const publishRecipe = {
     required: ['recipeId'],
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    return recipeService.publishRecipe(params.recipeId, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.publish(params.recipeId, { userId: 'agent' });
   },
 };
 
@@ -1829,8 +1917,8 @@ const deprecateRecipe = {
     required: ['recipeId', 'reason'],
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    return recipeService.deprecateRecipe(params.recipeId, params.reason, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.deprecate(params.recipeId, params.reason, { userId: 'agent' });
   },
 };
 
@@ -1849,8 +1937,8 @@ const updateRecipe = {
     required: ['recipeId', 'updates'],
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
-    return recipeService.updateRecipe(params.recipeId, params.updates, { userId: 'agent' });
+    const knowledgeService = ctx.container.get('knowledgeService');
+    return knowledgeService.update(params.recipeId, params.updates, { userId: 'agent' });
   },
 };
 
@@ -1869,9 +1957,9 @@ const recordUsage = {
     required: ['recipeId'],
   },
   handler: async (params, ctx) => {
-    const recipeService = ctx.container.get('recipeService');
+    const knowledgeService = ctx.container.get('knowledgeService');
     const type = params.type || 'adoption';
-    await recipeService.incrementUsage(params.recipeId, type);
+    await knowledgeService.incrementUsage(params.recipeId, type);
     return { success: true, recipeId: params.recipeId, type };
   },
 };
@@ -1894,9 +1982,13 @@ const qualityScore = {
     let recipe = params.recipe;
 
     if (!recipe && params.recipeId) {
-      const recipeRepo = ctx.container.get('recipeRepository');
-      recipe = await recipeRepo.findById(params.recipeId);
-      if (!recipe) return { error: `Recipe '${params.recipeId}' not found` };
+      const knowledgeService = ctx.container.get('knowledgeService');
+      try {
+        const entry = await knowledgeService.get(params.recipeId);
+        recipe = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+      } catch {
+        return { error: `Knowledge entry '${params.recipeId}' not found` };
+      }
     }
     if (!recipe) return { error: 'Provide recipeId or recipe object' };
 
@@ -2210,13 +2302,8 @@ const knowledgeOverview = {
     const [statsResult, feedbackResult] = await Promise.all([
       (async () => {
         try {
-          const recipeService = ctx.container.get('recipeService');
-          const candidateService = ctx.container.get('candidateService');
-          const [rs, cs] = await Promise.all([
-            recipeService.getRecipeStats(),
-            candidateService.getCandidateStats(),
-          ]);
-          return { recipes: rs, candidates: cs };
+          const knowledgeService = ctx.container.get('knowledgeService');
+          return knowledgeService.getStats();
         } catch { return null; }
       })(),
       (async () => {
@@ -2229,8 +2316,7 @@ const knowledgeOverview = {
     ]);
 
     if (statsResult) {
-      result.recipes = statsResult.recipes;
-      result.candidates = statsResult.candidates;
+      result.knowledge = statsResult;
     }
 
     // 知识图谱统计
@@ -2256,45 +2342,45 @@ const knowledgeOverview = {
 // ────────────────────────────────────────────────────────────
 const submitWithCheck = {
   name: 'submit_with_check',
-  description: '安全提交候选：先执行查重检测，无重复则自动提交。如果发现高度相似 Recipe 则阻止并返回相似列表。一次调用完成 check_duplicate + submit_candidate。',
+  description: '安全提交候选：先执行查重检测，无重复则自动提交。一次调用完成 check_duplicate + submit_knowledge。',
   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' },
+      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: '正向指令英文' },
+      dontClause: { type: 'string', description: '反向约束英文' },
+      tags:       { type: 'array', items: { type: 'string' } },
+      reasoning:  { type: 'object', description: '{ whyStandard, sources, confidence }' },
+      threshold:  { type: 'number', description: '相似度阈值，默认 0.7' },
     },
-    required: ['code', 'language', 'category'],
+    required: ['content', 'title', 'trigger', 'kind', 'doClause'],
   },
   handler: async (params, ctx) => {
-    const { code, language, category, title, summary, threshold = 0.7 } = params;
     const projectRoot = ctx.projectRoot;
 
-    // ── Bootstrap 维度类型校验 (与 submit_candidate 共用逻辑) ──
+    // ── Bootstrap 维度类型校验 ──
     const dimMeta = ctx._dimensionMeta;
     if (dimMeta && ctx.source === 'system') {
       const rejected = _checkDimensionType(dimMeta, params, ctx.logger);
       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');
-
-      // 自动补充 knowledgeType（AI 未填时用维度默认值）
-      if (!params.knowledgeType && dimMeta.allowedKnowledgeTypes?.length > 0) {
-        params.knowledgeType = dimMeta.allowedKnowledgeTypes[0];
-      }
-
-      // 覆盖 category 为展示分组
-      params.category = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
     }
 
     // Step 1: 查重
-    const cand = { title: title || '', summary: summary || '', code };
+    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 similar = findSimilarRecipes(projectRoot, cand, { threshold: 0.5, topK: 5 });
     const hasDuplicate = similar.some(s => s.similarity >= threshold);
 
@@ -2306,38 +2392,49 @@ const submitWithCheck = {
         highestSimilarity: similar[0]?.similarity || 0,
         _meta: {
           confidence: 'high',
-          hint: `发现高度相似 Recipe（相似度 ${(similar[0]?.similarity * 100).toFixed(0)}%），已阻止提交。请人工审核。`,
+          hint: `发现高度相似 Recipe（相似度 ${(similar[0]?.similarity * 100).toFixed(0)}%），已阻止提交。`,
         },
       };
     }
 
-    // Step 2: 提交
+    // Step 2: 提交 — 委托给 submit_knowledge handler
     try {
-      const candidateService = ctx.container.get('candidateService');
-      const { code: _c, language: _l, category: _cat, title: _t, summary: _s, threshold: _th, source: paramSource, reasoning: userReasoning, metadata, ...rest } = params;
-      const item = {
-        code,
-        language,
-        category,
-        ...rest,                     // 顶层扩展字段 (title, summary, knowledgeType, tags 等)
-        ...metadata,                 // metadata 对象 (如有)
-        title: title || '',
-        summary: summary || '',
-        reasoning: userReasoning || { whyStandard: 'Submitted via submit_with_check', sources: ['agent'], confidence: 0.7 },
+      const knowledgeService = ctx.container.get('knowledgeService');
+      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',
+        knowledgeType: dimMeta?.allowedKnowledgeTypes?.[0] || 'code-pattern',
+        source:        ctx.source === 'system' ? 'bootstrap' : 'agent',
+      };
+
+      const data = {
+        ...systemFields,
+        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,
+        reasoning,
       };
-      // Bootstrap 模式注入展示分组 targetName
-      const swcDisplayGroup = dimMeta ? (DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id) : null;
-      const swcExtraMeta = (dimMeta && ctx.source === 'system') ? { targetName: swcDisplayGroup } : {};
-      const created = await candidateService.createFromToolParams(item, paramSource || 'agent', swcExtraMeta, { userId: 'agent' });
+
+      const created = await knowledgeService.create(data, { userId: 'agent' });
 
       return {
         submitted: true,
-        candidate: created,
+        entry: typeof created.toJSON === 'function' ? created.toJSON() : created,
         similar: similar.length > 0 ? similar : [],
         _meta: {
           confidence: 'high',
           hint: similar.length > 0
-            ? `已提交，但有 ${similar.length} 个低相似度匹配，大概率不是重复。`
+            ? `已提交，但有 ${similar.length} 个低相似度匹配。`
             : '已提交，无重复风险。',
         },
       };
@@ -2444,7 +2541,7 @@ const planTask = {
 // ─── 元工具: 自我质量审查 ───────────────────────────────
 const reviewMyOutput = {
   name: 'review_my_output',
-  description: '回查本次会话中已提交的候选,检查质量红线是否满足。包括: 项目特写风格、summary 泛化措辞、代码示例来源标注等。返回通过/问题列表。建议在提交完所有候选后调用一次进行自检。',
+  description: '回查本次会话中已提交的候选,检查质量红线是否满足。包括: 项目特写风格、description 泛化措辞、代码示例来源标注、Cursor 交付字段完整性等。返回通过/问题列表。建议在提交完所有候选后调用一次进行自检。',
   parameters: {
     type: 'object',
     properties: {
@@ -2457,7 +2554,7 @@ const reviewMyOutput = {
   },
   handler: async (params, context) => {
     const submitted = (context._sessionToolCalls || []).filter(
-      tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check',
+      tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check',
     );
 
     if (submitted.length === 0) {
@@ -2469,48 +2566,54 @@ const reviewMyOutput = {
 
     for (const tc of submitted) {
       const p = tc.params || {};
-      const code = p.code || '';
+      const contentObj3 = p.content && typeof p.content === 'object' ? p.content : {};
+      const markdown = contentObj3.markdown || '';
       const title = p.title || '';
-      const summary = p.summary || '';
+      const description = p.description || '';
       const candidateIssues = [];
 
       // 检查 1: 项目特写后缀
-      if (!title.includes('— 项目特写') && !code.includes('— 项目特写')) {
+      if (!title.includes('— 项目特写') && !markdown.includes('— 项目特写')) {
         candidateIssues.push('缺少 "— 项目特写" 后缀');
       }
 
       // 检查 2: 项目特写融合叙事质量 — 必须同时包含代码和描述性文字
-      const hasCodeBlock = /```[\s\S]*?```/.test(code);
+      const hasCodeBlock = /```[\s\S]*?```/.test(markdown);
       if (!hasCodeBlock) {
         candidateIssues.push('特写缺少代码示例，应包含基本用法代码');
       }
       // 去掉代码块后，剩余描述性文字应足够
-      const proseLength = code.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('特写缺少项目特点描述，应融合基本用法和项目特点');
       }
 
-      // 检查 3: summary 泛化措辞
-      if (/本模块|该文件|这个类|该项目/.test(summary)) {
-        candidateIssues.push('summary 使用了泛化措辞,应引用具体类名和数字');
+      // 检查 3: description 泛化措辞
+      if (/本模块|该文件|这个类|该项目/.test(description)) {
+        candidateIssues.push('description 使用了泛化措辞,应引用具体类名和数字');
       }
 
-      // 检查 4: summary 过短
-      if (summary.length < 15) {
-        candidateIssues.push(`summary 过短 (${summary.length} 字), 应≥15字并包含具体类名和数字`);
+      // 检查 4: description 过短
+      if (description.length < 15) {
+        candidateIssues.push(`description 过短 (${description.length} 字), 应≥15字并包含具体类名和数字`);
       }
 
-      // 检查 5: code 过短（可能是空壳）
-      if (code.length < 200) {
-        candidateIssues.push(`code 文档过短 (${code.length} 字), 可能缺少实质内容`);
+      // 检查 5: content.markdown 过短（可能是空壳）
+      if (markdown.length < 200) {
+        candidateIssues.push(`content.markdown 文档过短 (${markdown.length} 字), 可能缺少实质内容`);
       }
 
       // 检查 6: 代码示例来源
-      const hasSourceAnnotation = /\([^)]*\.\w+[^)]*:\d+\)|\([^)]*\.\w+[^)]*\)/.test(code);
+      const hasSourceAnnotation = /\([^)]*\.\w+[^)]*:\d+\)|\([^)]*\.\w+[^)]*\)/.test(markdown);
       if (hasCodeBlock && !hasSourceAnnotation) {
         candidateIssues.push('代码示例可能缺少来源文件标注 (建议标注 "来源: FileName.m:行号")');
       }
 
+      // 检查 7: Cursor 交付字段
+      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 });
       }