autosnippet 2.8.3 → 2.10.0

package/lib/external/mcp/handlers/browse.js

@@ -1,65 +1,70 @@
 /**
- * MCP Handlers — 知识浏览类
- * listByKind, listRecipes, getRecipe, recipeInsights, complianceReport, confirmUsage
+ * MCP Handlers — 知识浏览类 (V3: 使用 knowledgeService)
+ * listByKind, listRecipes, getRecipe, recipeInsights, confirmUsage
  */
 
 import { envelope } from '../envelope.js';
 
+/** 将 KnowledgeEntry 的 V3 字段投影为列表摘要 */
+function _projectItem(r) {
+  const json = typeof r.toJSON === 'function' ? r.toJSON() : r;
+  return {
+    id: json.id, title: json.title, description: json.description,
+    trigger: json.trigger || '', lifecycle: json.lifecycle, kind: json.kind,
+    language: json.language, category: json.category,
+    knowledge_type: json.knowledge_type, complexity: json.complexity,
+    scope: json.scope, tags: json.tags || [],
+    quality: json.quality || null, stats: json.stats || null,
+    // 兼容旧字段名
+    status: json.lifecycle, knowledgeType: json.knowledge_type,
+    statistics: json.stats,
+  };
+}
+
 export async function listByKind(ctx, kind, args) {
-  const recipeService = ctx.container.get('recipeService');
+  const ks = ctx.container.get('knowledgeService');
   const filters = { kind };
-  if (args.status) filters.status = args.status;
-  if (args.language) filters.language = args.language;
-  if (args.category) filters.category = args.category;
-  const result = await recipeService.listRecipes(filters, { page: 1, pageSize: args.limit || 20 });
-  const items = (result?.data || result?.items || []).map(r => ({
-    id: r.id, title: r.title || r.name, description: r.description,
-    trigger: r.trigger || '', status: r.status, language: r.language, category: r.category,
-    knowledgeType: r.knowledgeType, kind: r.kind,
-    complexity: r.complexity, scope: r.scope, tags: r.tags || [],
-    quality: r.quality || null, statistics: r.statistics || null,
-  }));
+  if (args.language)  filters.language  = args.language;
+  if (args.category)  filters.category  = args.category;
+  const result = await ks.list(filters, { page: 1, pageSize: args.limit || 20 });
+  const items = (result?.data || []).map(_projectItem);
   return envelope({ success: true, data: { kind, count: items.length, total: result?.pagination?.total || items.length, items }, meta: { tool: `autosnippet_list_${kind}s` } });
 }
 
 export async function listRecipes(ctx, args) {
-  const recipeService = ctx.container.get('recipeService');
+  const ks = ctx.container.get('knowledgeService');
   const filters = {};
-  if (args.kind) filters.kind = args.kind;
-  if (args.language) filters.language = args.language;
-  if (args.category) filters.category = args.category;
-  if (args.knowledgeType) filters.knowledgeType = args.knowledgeType;
-  if (args.status) filters.status = args.status;
-  if (args.complexity) filters.complexity = args.complexity;
-  const result = await recipeService.listRecipes(filters, { page: 1, pageSize: args.limit || 20 });
-  const items = (result?.data || result?.items || []).map(r => ({
-    id: r.id, title: r.title, description: r.description,
-    trigger: r.trigger || '', status: r.status, language: r.language, category: r.category,
-    kind: r.kind, knowledgeType: r.knowledgeType, complexity: r.complexity,
-    scope: r.scope, tags: r.tags,
-    quality: r.quality, statistics: r.statistics,
-  }));
+  if (args.kind)           filters.kind          = args.kind;
+  if (args.language)       filters.language       = args.language;
+  if (args.category)       filters.category       = args.category;
+  if (args.knowledgeType)  filters.knowledgeType  = args.knowledgeType;
+  if (args.complexity)     filters.complexity     = args.complexity;
+  if (args.status)         filters.lifecycle      = args.status;
+  const result = await ks.list(filters, { page: 1, pageSize: args.limit || 20 });
+  const items = (result?.data || []).map(_projectItem);
   return envelope({ success: true, data: { count: items.length, total: result?.pagination?.total || items.length, items }, meta: { tool: 'autosnippet_list_recipes' } });
 }
 
 export async function getRecipe(ctx, args) {
   if (!args.id) throw new Error('id is required');
-  const recipeService = ctx.container.get('recipeService');
-  const recipe = await recipeService.getRecipe(args.id);
-  if (!recipe) throw new Error(`Recipe not found: ${args.id}`);
-  return envelope({ success: true, data: recipe, meta: { tool: 'autosnippet_get_recipe' } });
+  const ks = ctx.container.get('knowledgeService');
+  const entry = await ks.get(args.id);
+  if (!entry) throw new Error(`Knowledge entry not found: ${args.id}`);
+  const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
+  return envelope({ success: true, data: json, meta: { tool: 'autosnippet_get_recipe' } });
 }
 
 export async function recipeInsights(ctx, args) {
   if (!args.id) throw new Error('id is required');
-  const recipeService = ctx.container.get('recipeService');
-  const recipe = await recipeService.getRecipe(args.id);
-  if (!recipe) throw new Error(`Recipe not found: ${args.id}`);
+  const ks = ctx.container.get('knowledgeService');
+  const entry = await ks.get(args.id);
+  if (!entry) throw new Error(`Knowledge entry not found: ${args.id}`);
+  const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
 
   // 聚合关系摘要
   const relationsSummary = {};
-  if (recipe.relations) {
-    for (const [type, targets] of Object.entries(recipe.relations)) {
+  if (json.relations) {
+    for (const [type, targets] of Object.entries(json.relations)) {
       if (Array.isArray(targets) && targets.length > 0) {
         relationsSummary[type] = targets.length;
       }
@@ -68,8 +73,8 @@ export async function recipeInsights(ctx, args) {
 
   // 约束条件概览
   const constraintsSummary = {};
-  if (recipe.constraints) {
-    for (const [type, items] of Object.entries(recipe.constraints)) {
+  if (json.constraints) {
+    for (const [type, items] of Object.entries(json.constraints)) {
       if (Array.isArray(items) && items.length > 0) {
         constraintsSummary[type] = items;
       }
@@ -77,43 +82,42 @@ export async function recipeInsights(ctx, args) {
   }
 
   const insights = {
-    id: recipe.id,
-    title: recipe.title,
-    trigger: recipe.trigger || '',
-    kind: recipe.kind,
-    status: recipe.status,
-    language: recipe.language,
-    category: recipe.category,
-    knowledgeType: recipe.knowledgeType,
+    id: json.id,
+    title: json.title,
+    trigger: json.trigger || '',
+    kind: json.kind,
+    lifecycle: json.lifecycle,
+    language: json.language,
+    category: json.category,
+    knowledge_type: json.knowledge_type,
     quality: {
-      overall: recipe.quality?.overall ?? null,
-      codeCompleteness: recipe.quality?.codeCompleteness ?? null,
-      projectAdaptation: recipe.quality?.projectAdaptation ?? null,
-      documentationClarity: recipe.quality?.documentationClarity ?? null,
+      overall: json.quality?.overall ?? null,
+      completeness: json.quality?.completeness ?? null,
+      adaptation: json.quality?.adaptation ?? null,
+      documentation: json.quality?.documentation ?? null,
     },
-    statistics: {
-      adoptionCount: recipe.statistics?.adoptionCount ?? 0,
-      applicationCount: recipe.statistics?.applicationCount ?? 0,
-      guardHitCount: recipe.statistics?.guardHitCount ?? 0,
-      viewCount: recipe.statistics?.viewCount ?? 0,
-      successCount: recipe.statistics?.successCount ?? 0,
-      feedbackScore: recipe.statistics?.feedbackScore ?? 0,
+    stats: {
+      adoptions: json.stats?.adoptions ?? 0,
+      applications: json.stats?.applications ?? 0,
+      guard_hits: json.stats?.guard_hits ?? 0,
+      views: json.stats?.views ?? 0,
+      search_hits: json.stats?.search_hits ?? 0,
     },
     content: {
-      hasPattern: !!recipe.content?.pattern,
-      hasRationale: !!recipe.content?.rationale,
-      hasMarkdown: !!recipe.content?.markdown,
-      stepsCount: recipe.content?.steps?.length ?? 0,
-      codeChangesCount: recipe.content?.codeChanges?.length ?? 0,
+      hasPattern: !!json.content?.pattern,
+      hasRationale: !!json.content?.rationale,
+      hasMarkdown: !!json.content?.markdown,
+      stepsCount: json.content?.steps?.length ?? 0,
+      codeChangesCount: json.content?.code_changes?.length ?? 0,
     },
     relations: relationsSummary,
     constraints: constraintsSummary,
-    tags: recipe.tags || [],
-    complexity: recipe.complexity,
-    scope: recipe.scope,
-    createdBy: recipe.createdBy,
-    createdAt: recipe.createdAt,
-    updatedAt: recipe.updatedAt,
+    tags: json.tags || [],
+    complexity: json.complexity,
+    scope: json.scope,
+    created_by: json.created_by,
+    created_at: json.created_at,
+    updated_at: json.updated_at,
   };
 
   return envelope({ success: true, data: insights, meta: { tool: 'autosnippet_recipe_insights' } });
@@ -121,11 +125,11 @@ export async function recipeInsights(ctx, args) {
 
 export async function confirmUsage(ctx, args) {
   if (!args.recipeId) throw new Error('recipeId is required');
-  const recipeService = ctx.container.get('recipeService');
+  const ks = ctx.container.get('knowledgeService');
   const usageType = args.usageType || 'adoption';
   const feedback = args.feedback || null;
 
-  await recipeService.incrementUsage(args.recipeId, usageType, {
+  await ks.incrementUsage(args.recipeId, usageType, {
     feedback,
     actor: 'mcp_user',
   });
@@ -146,7 +150,7 @@ export async function confirmUsage(ctx, args) {
   return envelope({
     success: true,
     data: { recipeId: args.recipeId, usageType, feedback },
-    message: `已记录 Recipe ${args.recipeId} 的${usageType === 'adoption' ? '采纳' : '应用'}`,
+    message: `已记录使用 ${args.recipeId} 的${usageType === 'adoption' ? '采纳' : '应用'}`,
     meta: { tool: 'autosnippet_confirm_usage' },
   });
 }

package/lib/external/mcp/handlers/candidate.js

@@ -1,60 +1,12 @@
 /**
- * MCP Handlers — 候选提交 & 校验 & AI 补全
- * validateCandidate, checkDuplicate, submitSingle, submitBatch, submitDrafts, enrichCandidates
- * + 辅助: buildReasoning, _createCandidateItem
+ * MCP Handlers — 候选校验 & 字段诊断 (V3: 使用 knowledgeService)
+ * validateCandidate, checkDuplicate, enrichCandidates
+ *
+ * 注意: submitSingle, submitBatch, submitDrafts 已移至 V3 knowledge handlers
+ *       (autosnippet_submit_knowledge / submit_knowledge_batch / knowledge_lifecycle)
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
 import { envelope } from '../envelope.js';
-import * as Paths from '../../../infrastructure/config/Paths.js';
-import { checkRecipeReadiness } from '../../../shared/RecipeReadinessChecker.js';
-
-// ─── 辅助方法 ──────────────────────────────────────────────
-
-/**
- * 从工具参数构建 Reasoning 值对象数据。
- * Agent 必须提供 reasoning.whyStandard / sources / confidence。
- */
-export function buildReasoning(obj) {
-  const r = obj.reasoning;
-  if (!r || !r.whyStandard) return {};
-  return {
-    whyStandard: r.whyStandard,
-    sources: Array.isArray(r.sources) ? r.sources : [],
-    confidence: typeof r.confidence === 'number' ? r.confidence : 0.7,
-    qualitySignals: r.qualitySignals || {},
-    alternatives: Array.isArray(r.alternatives) ? r.alternatives : [],
-  };
-}
-
-/**
- * 统一创建候选的内部方法 — 委托到 CandidateService.createFromToolParams()
- * 保留此函数作为 MCP handler 层的快捷入口，保持向后兼容。
- */
-async function _createCandidateItem(candidateService, item, source, extraMeta = {}) {
-  return candidateService.createFromToolParams(item, source, extraMeta, { userId: 'external_agent' });
-}
-
-// ─── 限流检查 ──────────────────────────────────────────────
-
-// Recipe-Ready 检查已提取到 lib/shared/RecipeReadinessChecker.js
-// 旧私有函数 _checkRecipeReadiness 已移除，统一使用 checkRecipeReadiness
-
-async function _checkRateLimit(toolName, clientId) {
-  const { checkRecipeSave } = await import('../../../http/middleware/RateLimiter.js');
-  const projectRoot = process.cwd();
-  const limitCheck = checkRecipeSave(projectRoot, clientId || process.env.USER || 'mcp-client');
-  if (!limitCheck.allowed) {
-    return envelope({
-      success: false,
-      message: `提交过于频繁，请 ${limitCheck.retryAfter}s 后再试。`,
-      errorCode: 'RATE_LIMIT',
-      meta: { tool: toolName },
-    });
-  }
-  return null; // passed
-}
 
 // ─── 校验 & 去重 ───────────────────────────────────────────
 
@@ -88,13 +40,13 @@ export async function validateCandidate(ctx, args) {
   if (!c.steps && !c.codeChanges) suggestions.push({ field: 'steps', value: '[{title, description, code}]' });
 
   // Layer 5: 约束与关系
-  if (!c.constraints) suggestions.push({ field: 'constraints', value: '{boundaries[], preconditions[], sideEffects[], guards[]}' });
+  if (!c.constraints) suggestions.push({ field: 'constraints', value: '{boundaries[], preconditions[], side_effects[], guards[]}' });
 
   // Reasoning 推理依据
   if (!c.reasoning) {
     errors.push('缺少 reasoning（推理依据 — whyStandard + sources + confidence）');
   } else {
-    if (!c.reasoning.whyStandard?.trim()) errors.push('reasoning.whyStandard 不能为空');
+    if (!c.reasoning.whyStandard?.trim() && !c.reasoning.why_standard?.trim()) errors.push('reasoning.whyStandard 不能为空');
     if (!Array.isArray(c.reasoning.sources) || c.reasoning.sources.length === 0) errors.push('reasoning.sources 至少包含一项来源');
     if (typeof c.reasoning.confidence !== 'number' || c.reasoning.confidence < 0 || c.reasoning.confidence > 1) warnings.push('reasoning.confidence 应为 0-1 的数字');
   }
@@ -104,6 +56,7 @@ export async function validateCandidate(ctx, args) {
 }
 
 export async function checkDuplicate(ctx, args) {
+  // SimilarityService 直接读磁盘 .md 文件，不依赖 Repository
   const { findSimilarRecipes } = await import('../../../service/candidate/SimilarityService.js');
   const projectRoot = process.env.ASD_PROJECT_DIR || process.cwd();
   const similar = findSimilarRecipes(projectRoot, args.candidate, {
@@ -113,211 +66,8 @@ export async function checkDuplicate(ctx, args) {
   return envelope({ success: true, data: { similar }, meta: { tool: 'autosnippet_check_duplicate' } });
 }
 
-// ─── 提交 ──────────────────────────────────────────────────
-
-export async function submitSingle(ctx, args) {
-  // 限流
-  const blocked = await _checkRateLimit('autosnippet_submit_candidate', args.clientId);
-  if (blocked) return blocked;
-
-  const candidateService = ctx.container.get('candidateService');
-  const result = await _createCandidateItem(
-    candidateService, args, args.source || 'mcp',
-  );
-
-  // Recipe-Ready 诊断
-  const readiness = checkRecipeReadiness(args);
-  const data = { ...result };
-  if (!readiness.ready) {
-    data.recipeReadyHints = {
-      ready: false,
-      missingFields: readiness.missing,
-      suggestions: readiness.suggestions,
-      hint: '请补全以上字段后重新提交，或调用 autosnippet_enrich_candidates 进行完整性诊断',
-    };
-  }
-
-  return envelope({ success: true, data, meta: { tool: 'autosnippet_submit_candidate' } });
-}
-
-export async function submitBatch(ctx, args) {
-  if (!args.targetName || !Array.isArray(args.items) || args.items.length === 0) {
-    throw new Error('需要 targetName 与 items（非空数组）');
-  }
-
-  // 限流
-  const blocked = await _checkRateLimit('autosnippet_submit_candidates', args.clientId);
-  if (blocked) return blocked;
-
-  // 去重
-  let items = args.items;
-  if (args.deduplicate !== false) {
-    const { aggregateCandidates } = await import('../../../service/candidate/CandidateAggregator.js');
-    const result = aggregateCandidates(items);
-    items = result.items;
-  }
-
-  // 逐条提交
-  const candidateService = ctx.container.get('candidateService');
-  const source = args.source || 'cursor-scan';
-  let count = 0;
-  const itemErrors = [];
-  for (let i = 0; i < items.length; i++) {
-    try {
-      await _createCandidateItem(candidateService, items[i], source, { targetName: args.targetName });
-      count++;
-    } catch (err) {
-      itemErrors.push({ index: i, title: items[i].title || '(untitled)', error: err.message });
-    }
-  }
-
-  const data = { count, total: items.length, targetName: args.targetName };
-  if (itemErrors.length > 0) data.errors = itemErrors;
-
-  // Recipe-Ready 统计
-  const notReady = items.filter(it => !checkRecipeReadiness(it).ready);
-  if (notReady.length > 0) {
-    // 汇总所有缺失字段（去重）
-    const allMissing = [...new Set(notReady.flatMap(it => checkRecipeReadiness(it).missing))];
-    data.recipeReadyHints = {
-      notReadyCount: notReady.length,
-      totalCount: items.length,
-      commonMissingFields: allMissing,
-      hint: `${notReady.length}/${items.length} 条候选缺少 Recipe 必要字段（${allMissing.join(', ')}），请补全后重新提交或调用 autosnippet_enrich_candidates 查漏`,
-    };
-  }
-
-  return envelope({ success: true, data, message: `已提交 ${count}/${items.length} 条候选，请在 Dashboard Candidates 页审核。`, meta: { tool: 'autosnippet_submit_candidates' } });
-}
-
-export async function submitDrafts(ctx, args) {
-  const { RecipeParser } = await import('../../../service/recipe/RecipeParser.js');
-
-  const projectRoot = process.cwd();
-  const parser = new RecipeParser();
-  const paths = Array.isArray(args.filePaths) ? args.filePaths : [args.filePaths].filter(Boolean);
-  if (paths.length === 0) throw new Error('filePaths 不能为空');
-
-  // 限流
-  const blocked = await _checkRateLimit('autosnippet_submit_draft_recipes', args.clientId);
-  if (blocked) return blocked;
-
-  const recipes = [];
-  const parseErrors = [];
-  const successFiles = [];
-
-  for (const fp of paths) {
-    try {
-      const absPath = path.isAbsolute(fp) ? fp : path.join(projectRoot, fp);
-      // 禁止操作知识库目录
-      const kbDir = Paths.getKnowledgeBaseDirName(projectRoot);
-      const rel = path.relative(projectRoot, absPath);
-      if (rel.startsWith(kbDir + '/') || rel.startsWith(kbDir + path.sep)) {
-        parseErrors.push(`🚫 ${fp} — 禁止操作知识库目录 ${kbDir}/`);
-        continue;
-      }
-      if (!fs.existsSync(absPath)) { parseErrors.push(`❌ 文件不存在: ${fp}`); continue; }
-
-      const content = fs.readFileSync(absPath, 'utf8');
-      let parsed = [];
-      if (parser.isCompleteRecipe(content)) {
-        const r = parser.parse(content);
-        if (r) parsed.push(r);
-      } else {
-        parsed = parser.parseAll(content).filter(Boolean);
-      }
-      if (parsed.length === 0 && parser.isIntroOnly(content)) {
-        const r = parser.parse(content); // intro-only still parseable for frontmatter
-        if (r) parsed.push(r);
-      }
-
-      // 校验
-      const { RecipeCandidateValidator } = await import('../../../service/recipe/RecipeCandidateValidator.js');
-      const validator = new RecipeCandidateValidator();
-      const valid = [];
-      for (const item of parsed) {
-        const result = validator.validate(item);
-        if (!result.errors || result.errors.length === 0) {
-          valid.push(item);
-        } else {
-          parseErrors.push(`❌ ${path.basename(fp)}: ${result.errors.join('; ')}`);
-        }
-      }
-      if (valid.length > 0) {
-        recipes.push(...valid.map(r => ({ ...r, _sourceFile: absPath })));
-        successFiles.push({ path: absPath, count: valid.length, name: path.basename(absPath) });
-      }
-    } catch (err) {
-      parseErrors.push(`❌ ${path.basename(fp)}: ${err.message}`);
-    }
-  }
-
-  if (recipes.length === 0) {
-    return envelope({ success: false, message: `未能解析出有效 Recipe。${parseErrors.join('\n')}`, errorCode: 'PARSE_FAILED', meta: { tool: 'autosnippet_submit_draft_recipes' } });
-  }
-
-  // 逐条提交 — 使用 _createCandidateItem 统一路径
-  const candidateService = ctx.container.get('candidateService');
-  const source = args.source || 'copilot-draft';
-  let count = 0;
-  const submitErrors = [];
-  for (const item of recipes) {
-    try {
-      // 将 RecipeParser 的字段映射到 candidate 通用字段
-      const normalized = {
-        code: item.code || '',
-        language: item.language || '',
-        category: item.category || 'general',
-        title: item.title || '',
-        summary: item.summary || item.summary_cn || '',
-        summary_cn: item.summary_cn || item.summary || '',
-        summary_en: item.summary_en || '',
-        description: item.description || item.summary_en || '',
-        trigger: item.trigger || '',
-        usageGuide: item.usageGuide || item.usageGuide_cn || '',
-        usageGuide_cn: item.usageGuide_cn || item.usageGuide || '',
-        usageGuide_en: item.usageGuide_en || '',
-        headers: item.headers || [],
-        rationale: item.rationale || '',
-        knowledgeType: item.knowledgeType || 'code-pattern',
-        tags: item.tags || [],
-        sourceFile: item._sourceFile || '',
-        // 草稿不含 reasoning — _createCandidateItem 会自动生成默认值
-      };
-      await _createCandidateItem(candidateService, normalized, source, { targetName: args.targetName || '_draft' });
-      count++;
-    } catch (err) {
-      submitErrors.push({ title: item.title || '(untitled)', error: err.message });
-    }
-  }
-
-  // 删除成功文件
-  const deleted = [];
-  if (args.deleteAfterSubmit && count > 0) {
-    for (const f of successFiles) {
-      try { fs.unlinkSync(f.path); deleted.push(f.name); } catch { /* ignore */ }
-    }
-  }
-
-  let msg = `已提交 ${count}/${recipes.length} 条 Recipe 候选（target: ${args.targetName || '_draft'}）。`;
-  if (deleted.length > 0) msg += ` 已删除草稿: ${deleted.join(', ')}。`;
-  if (parseErrors.length > 0) msg += `\n⚠️ 解析失败:\n${parseErrors.join('\n')}`;
-  if (submitErrors.length > 0) msg += `\n⚠️ 提交失败:\n${submitErrors.map(e => `  ${e.title}: ${e.error}`).join('\n')}`;
-
-  const data = { count, total: recipes.length, targetName: args.targetName || '_draft', deleted };
-  if (submitErrors.length > 0) data.errors = submitErrors;
-  return envelope({ success: true, data, message: msg, meta: { tool: 'autosnippet_submit_draft_recipes' } });
-}
-
 // ─── 语义字段缺失诊断（无 AI 依赖） ──────────────────────────
 
-/**
- * enrichCandidates — 诊断候选的语义字段缺失情况
- *
- * 设计原则：MCP 调用方是外部 AI Agent，不需要项目内置 AI 补全。
- * 本工具仅做「字段完整性检查」，返回每个候选缺失了哪些语义字段，
- * Agent 据此自行补全后调用 submit_candidates 更新。
- */
 export async function enrichCandidates(ctx, args) {
   const ids = args.candidateIds;
   if (!Array.isArray(ids) || ids.length === 0) {
@@ -327,18 +77,17 @@ export async function enrichCandidates(ctx, args) {
     throw new Error('Max 20 candidates per enrichment call');
   }
 
-  const candidateService = ctx.container.get('candidateService');
-  if (!candidateService) throw new Error('CandidateService not available');
+  const knowledgeService = ctx.container.get('knowledgeService');
+  if (!knowledgeService) throw new Error('KnowledgeService not available');
 
-  const SEMANTIC_KEYS = ['rationale', 'knowledgeType', 'complexity', 'scope', 'steps', 'constraints'];
-  // Recipe-Ready 必填字段（category/trigger/summary*/headers 等）
+  const SEMANTIC_KEYS = ['content.rationale', 'knowledge_type', 'complexity', 'scope', 'content.steps', 'constraints'];
   const RECIPE_READY_KEYS = [
     { key: 'category', check: v => v && ['View','Service','Tool','Model','Network','Storage','UI','Utility'].includes(v), hint: 'category 必须为 8 标准值之一' },
     { key: 'trigger', check: v => v && v.startsWith('@'), hint: 'trigger 必须以 @ 开头' },
-    { key: 'summary', check: v => !!v, hint: '中文摘要（summary / summary_cn）' },
+    { key: 'summary_cn', check: v => !!v, hint: '中文摘要' },
     { key: 'summary_en', check: v => !!v, hint: '英文摘要' },
     { key: 'headers', check: v => Array.isArray(v) && v.length > 0, hint: '完整 import 语句数组' },
-    { key: 'usageGuide', check: v => !!v, hint: '使用指南（Markdown ### 章节）' },
+    { key: 'usage_guide_cn', check: v => !!v, hint: '使用指南（Markdown）' },
   ];
 
   const results = [];
@@ -346,29 +95,31 @@ export async function enrichCandidates(ctx, args) {
   let needsRecipeFields = 0;
   for (const id of ids) {
     try {
-      const candidate = await candidateService.candidateRepository.findById(id);
-      if (!candidate) {
+      const entry = await knowledgeService.get(id);
+      if (!entry) {
         results.push({ id, found: false, missingFields: [], recipeReadyMissing: [] });
         continue;
       }
-      const meta = candidate.metadata || {};
+      const json = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
 
       // 语义字段检查
       const missing = [];
-      for (const key of SEMANTIC_KEYS) {
-        const val = meta[key];
+      for (const keyPath of SEMANTIC_KEYS) {
+        const parts = keyPath.split('.');
+        let val = json;
+        for (const p of parts) { val = val?.[p]; }
         if (val === undefined || val === null || val === '' ||
             (typeof val === 'string' && val.trim() === '') ||
             (Array.isArray(val) && val.length === 0) ||
             (typeof val === 'object' && !Array.isArray(val) && Object.keys(val).length === 0)) {
-          missing.push(key);
+          missing.push(keyPath);
         }
       }
 
       // Recipe-Ready 字段检查
       const recipeReadyMissing = [];
       for (const { key, check, hint } of RECIPE_READY_KEYS) {
-        const val = key === 'category' ? candidate.category : meta[key];
+        const val = json[key];
         if (!check(val)) {
           recipeReadyMissing.push({ field: key, hint });
         }
@@ -377,8 +128,10 @@ export async function enrichCandidates(ctx, args) {
       results.push({
         id,
         found: true,
-        title: meta.title || '',
-        language: candidate.language,
+        title: json.title || '',
+        language: json.language,
+        lifecycle: json.lifecycle,
+        kind: json.kind,
         missingFields: missing,
         recipeReadyMissing,
         complete: missing.length === 0 && recipeReadyMissing.length === 0,
@@ -397,10 +150,10 @@ export async function enrichCandidates(ctx, args) {
       needsEnrichment,
       needsRecipeFields,
       fullyComplete: ids.length - Math.max(needsEnrichment, needsRecipeFields),
-      candidates: results,
+      entries: results,
       hint: (needsEnrichment > 0 || needsRecipeFields > 0)
-        ? '请 Agent 根据 missingFields（语义）和 recipeReadyMissing（Recipe 必填）自行补全后重新提交'
-        : '所有候选字段完整，可直接审核为 Recipe',
+        ? '请 Agent 根据 missingFields（语义）和 recipeReadyMissing（必填）自行补全后重新提交'
+        : '所有条目字段完整',
     },
     meta: { tool: 'autosnippet_enrich_candidates' },
   });

package/lib/external/mcp/handlers/guard.js

@@ -89,6 +89,7 @@ export async function guardAuditFiles(ctx, args) {
         violations: f.violations,
         summary: f.summary,
       })),
+      ...(result.crossFileViolations?.length ? { crossFileViolations: result.crossFileViolations } : {}),
     },
     meta: { tool: 'autosnippet_guard_audit_files' },
   });
@@ -187,6 +188,7 @@ export async function scanProject(ctx, args) {
           violations: f.violations,
           summary: f.summary,
         })),
+        ...(guardAudit.crossFileViolations?.length ? { crossFileViolations: guardAudit.crossFileViolations } : {}),
       } : null,
     },
     meta: { tool: 'autosnippet_scan_project' },