autosnippet 2.9.0 → 2.11.0

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
-}
 
 // ─── 校验 & 去重 ───────────────────────────────────────────
 
@@ -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,15 @@ 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', 'knowledgeType', '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_en', check: v => !!v, hint: '英文摘要' },
+    { key: 'description', check: v => !!v, hint: '知识条目描述' },
     { key: 'headers', check: v => Array.isArray(v) && v.length > 0, hint: '完整 import 语句数组' },
-    { key: 'usageGuide', check: v => !!v, hint: '使用指南（Markdown ### 章节）' },
   ];
 
   const results = [];
@@ -346,29 +93,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 +126,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 +148,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' },

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

@@ -0,0 +1,267 @@
+/**
+ * MCP Handlers — V3 知识条目提交 & 生命周期
+ * submitKnowledge, submitKnowledgeBatch, knowledgeLifecycle
+ */
+
+import { envelope } from '../envelope.js';
+import { checkRecipeReadiness } from '../../../shared/RecipeReadinessChecker.js';
+
+// ─── 限流 ──────────────────────────────────────────────────
+
+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;
+}
+
+// ─── V3 字段增强 ────────────────────────────────────────────
+
+/**
+ * 将 MCP wire format 增强为 V3 KnowledgeEntry 数据：
+ *   - 确保 source 为 'mcp'
+ *   - QualityScorer 评分（程序化）
+ *   - RecipeExtractor 语义标签（程序化）
+ *   - 其余 V3 字段由 Cursor 生成，缺失即留空（KnowledgeEntry 构造函数填默认值）
+ */
+function _enrichToV3(args, container) {
+  const data = { ...args };
+
+  // 来源标记（非 Cursor 职责）
+  if (!data.source) data.source = 'mcp';
+
+  // QualityScorer 评分（程序化）
+  try {
+    const qualityScorer = container?.get?.('qualityScorer');
+    if (qualityScorer) {
+      const codeForScore = data.content?.pattern || data.content?.markdown || '';
+      const scoreResult = qualityScorer.score({
+        ...data,
+        code: codeForScore,
+      });
+      data.quality = {
+        completeness: 0,
+        adaptation: 0,
+        documentation: 0,
+        overall: scoreResult.score ?? 0,
+        grade: scoreResult.grade || '',
+      };
+    }
+  } catch { /* best effort */ }
+
+  // RecipeExtractor 语义标签（程序化）
+  try {
+    const recipeExtractor = container?.get?.('recipeExtractor');
+    if (recipeExtractor) {
+      const codeForTags = data.content?.pattern || '';
+      if (codeForTags) {
+        const extracted = recipeExtractor.extractFromContent(
+          codeForTags, `${data.title || 'unknown'}.${data.language || 'swift'}`, ''
+        );
+        if (extracted.semanticTags?.length > 0) {
+          data.tags = [...new Set([...(data.tags || []), ...extracted.semanticTags])];
+        }
+        if ((!data.category || data.category === 'Utility') && extracted.category && extracted.category !== 'general') {
+          data.category = extracted.category;
+        }
+      }
+    }
+  } catch { /* best effort */ }
+
+  return data;
+}
+
+// ─── V3 wire format → KnowledgeService.create() ────────────
+
+/**
+ * 单条知识提交 (autosnippet_submit_knowledge)
+ *
+ * MCP wire format → V3 增强 → KnowledgeService.create()
+ * 增强包括：source='mcp'、reasoning 默认值、Delivery 字段补齐、QualityScorer、语义标签。
+ */
+export async function submitKnowledge(ctx, args) {
+  // 限流
+  const blocked = await _checkRateLimit('autosnippet_submit_knowledge', args.client_id);
+  if (blocked) return blocked;
+
+  const service = ctx.container.get('knowledgeService');
+
+  // V3 字段增强
+  const enrichedData = _enrichToV3(args, ctx.container);
+
+  const entry = await service.create(enrichedData, { userId: 'mcp' });
+
+  // Recipe-Ready 诊断（兼容旧格式）
+  const readinessInput = _toReadinessInput(args);
+  const readiness = checkRecipeReadiness(readinessInput);
+
+  const data = {
+    id: entry.id,
+    lifecycle: entry.lifecycle,
+    title: entry.title,
+    kind: entry.kind,
+  };
+
+  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_knowledge' },
+  });
+}
+
+/**
+ * 批量知识提交 (autosnippet_submit_knowledge_batch)
+ */
+export async function submitKnowledgeBatch(ctx, args) {
+  if (!args.target_name || !Array.isArray(args.items) || args.items.length === 0) {
+    throw new Error('需要 target_name 与 items（非空数组）');
+  }
+
+  // 限流
+  const blocked = await _checkRateLimit('autosnippet_submit_knowledge_batch', args.client_id);
+  if (blocked) return blocked;
+
+  // 去重（可选）
+  let items = args.items;
+  if (args.deduplicate !== false) {
+    try {
+      const { aggregateCandidates } = await import('../../../service/candidate/CandidateAggregator.js');
+      // 对 title 字段做去重
+      const readinessItems = items.map(it => ({
+        ...it,
+        code: it.content?.pattern || it.code || '',
+      }));
+      const result = aggregateCandidates(readinessItems);
+      // 保留原始 items 顺序中去重后的
+      if (result.items && result.items.length < items.length) {
+        const titles = new Set(result.items.map(it => it.title));
+        items = items.filter(it => titles.has(it.title));
+      }
+    } catch {
+      // CandidateAggregator 加载失败时降级：不去重
+    }
+  }
+
+  const service = ctx.container.get('knowledgeService');
+  const source = args.source || 'cursor-scan';
+  let count = 0;
+  const itemErrors = [];
+
+  for (let i = 0; i < items.length; i++) {
+    try {
+      const itemData = _enrichToV3({ ...items[i], source }, ctx.container);
+      await service.create(itemData, { userId: 'mcp' });
+      count++;
+    } catch (err) {
+      itemErrors.push({ index: i, title: items[i].title || '(untitled)', error: err.message });
+    }
+  }
+
+  const data = { count, total: items.length, targetName: args.target_name };
+  if (itemErrors.length > 0) data.errors = itemErrors;
+
+  // Recipe-Ready 统计
+  const notReady = items.filter(it => !checkRecipeReadiness(_toReadinessInput(it)).ready);
+  if (notReady.length > 0) {
+    const allMissing = [...new Set(notReady.flatMap(it => checkRecipeReadiness(_toReadinessInput(it)).missing))];
+    data.recipeReadyHints = {
+      notReadyCount: notReady.length,
+      totalCount: items.length,
+      commonMissingFields: allMissing,
+      hint: `${notReady.length}/${items.length} 条知识条目缺少必要字段（${allMissing.join(', ')}），请补全后重新提交`,
+    };
+  }
+
+  return envelope({
+    success: true,
+    data,
+    message: `已提交 ${count}/${items.length} 条知识条目。`,
+    meta: { tool: 'autosnippet_submit_knowledge_batch' },
+  });
+}
+
+/**
+ * 知识条目生命周期操作 (autosnippet_knowledge_lifecycle)
+ *
+ * 简化为 3 状态: pending / active / deprecated
+ * 外部 Agent 允许 reactivate（废弃 → 待审核）；发布/废弃由开发者在 Dashboard 操作
+ * 外部 Agent 也可以通过 submitKnowledge / submitKnowledgeBatch 提交新条目（→ pending）
+ */
+const MCP_ALLOWED_LIFECYCLE_ACTIONS = new Set(['reactivate']);
+
+export async function knowledgeLifecycle(ctx, args) {
+  const { id, action } = args;
+  if (!id || !action) {
+    throw new Error('需要 id 和 action');
+  }
+
+  if (!MCP_ALLOWED_LIFECYCLE_ACTIONS.has(action)) {
+    throw new Error(
+      `[PERMISSION_DENIED] 外部 Agent 不允许执行 "${action}" 操作，仅支持: reactivate。发布、废弃等操作请在 Dashboard 中完成。提交新知识请使用 autosnippet_submit_knowledge 工具。`
+    );
+  }
+
+  const service = ctx.container.get('knowledgeService');
+  const context = { userId: 'mcp' };
+
+  const entry = await service.reactivate(id, context);
+
+  return envelope({
+    success: true,
+    data: {
+      id: entry.id,
+      lifecycle: entry.lifecycle,
+      title: entry.title,
+      action,
+    },
+    meta: { tool: 'autosnippet_knowledge_lifecycle' },
+  });
+}
+
+// ─── 内部辅助 ──────────────────────────────────────────────
+
+/**
+ * V3 wire format → RecipeReadinessChecker 兼容格式
+ */
+function _toReadinessInput(args) {
+  return {
+    title: args.title,
+    code: args.content?.pattern || args.code || '',
+    language: args.language,
+    category: args.category,
+    trigger: args.trigger,
+    description: args.description,
+    headers: args.headers,
+    reasoning: args.reasoning ? {
+      whyStandard: args.reasoning.whyStandard,
+      sources: args.reasoning.sources,
+      confidence: args.reasoning.confidence,
+    } : undefined,
+    knowledgeType: args.knowledgeType,
+    complexity: args.complexity,
+    // Cursor Delivery 字段
+    kind: args.kind,
+    doClause: args.doClause,
+    dontClause: args.dontClause,
+    whenClause: args.whenClause,
+    topicHint: args.topicHint,
+    coreCode: args.coreCode,
+  };
+}