autosnippet 3.2.10 → 3.2.12

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

@@ -1,381 +0,0 @@
-/**
- * MCP Handlers — V3 知识条目提交 & 生命周期
- * submitKnowledge, submitKnowledgeBatch, knowledgeLifecycle
- */
-
-import { UnifiedValidator } from '../../../shared/UnifiedValidator.js';
-import { getRequiredFieldsDescription } from '../../../shared/FieldSpec.js';
-import { envelope } from '../envelope.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'
- *   - RecipeExtractor 语义标签（程序化）
- *   - 其余 V3 字段由 Cursor 生成，缺失即留空（KnowledgeEntry 构造函数填默认值）
- *
- * 注意: QualityScorer 评分已统一为 KnowledgeService.create() 后置执行 (R9)。
- * _enrichToV3 不再内联 QualityScorer，避免外部路径双重评分。
- */
-function _enrichToV3(args, container) {
-  const data = { ...args };
-
-  // 来源标记（非 Cursor 职责）
-  if (!data.source) {
-    data.source = 'mcp';
-  }
-
-  // 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 || 'unknown'}`,
-          ''
-        );
-        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 诊断 — 使用 UnifiedValidator (统一门控)
-  const validator = new UnifiedValidator();
-  const validation = validator.validate(args, { skipUniqueness: true });
-
-  const data = {
-    id: entry.id,
-    lifecycle: entry.lifecycle,
-    title: entry.title,
-    kind: entry.kind,
-  };
-
-  if (!validation.pass) {
-    data.recipeReadyHints = {
-      ready: false,
-      missingFields: validation.errors,
-      suggestions: validation.warnings,
-    };
-  } else if (validation.warnings.length > 0) {
-    data.recipeReadyHints = {
-      ready: true,
-      missingFields: [],
-      suggestions: validation.warnings,
-    };
-  }
-
-  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 = [];
-  const rejectedItems = [];
-  const successIds = []; // 成功入库的 recipe ID 列表，供 dimension_complete 使用
-
-  // UnifiedValidator — 统一前置校验
-  const validator = new UnifiedValidator();
-
-  // v2: 获取 BootstrapSession tracker（静默降级）
-  let session = null;
-  let currentDimId = null;
-  try {
-    const sessionManager = ctx.container.get('bootstrapSessionManager');
-    session = sessionManager?.getSession?.();
-    if (session?.submissionTracker) {
-      const progress = session.getProgress();
-      // 优先使用 Agent 显式传递的 dimensionId，其次推断 remainingDimIds[0]
-      currentDimId = args.dimensionId || progress.remainingDimIds[0] || args.target_name || 'unknown';
-    }
-  } catch { /* best effort */ }
-
-  for (let i = 0; i < items.length; i++) {
-    // ── 严格前置校验：缺少必要字段的条目直接拒绝，不入库 ──
-    const validation = validator.validate(items[i], { skipUniqueness: false });
-    if (!validation.pass) {
-      rejectedItems.push({
-        index: i,
-        title: items[i].title || '(untitled)',
-        missingFields: validation.errors,
-        suggestions: validation.warnings,
-      });
-      // v2: 记录拒绝到 tracker
-      if (session?.submissionTracker && currentDimId) {
-        try {
-          session.submissionTracker.recordRejection(
-            currentDimId, items[i].title || '(untitled)', validation.errors.join(', '));
-        } catch { /* best effort */ }
-      }
-      // 记录标题/指纹供后续去重检测
-      validator.recordSubmission(items[i].title, items[i].content?.pattern);
-      continue;
-    }
-
-    try {
-      const itemData = _enrichToV3({ ...items[i], source }, ctx.container);
-      const entry = await service.create(itemData, { userId: 'mcp' });
-      count++;
-      successIds.push(entry.id);
-      // 记录标题/指纹供后续去重检测
-      validator.recordSubmission(items[i].title, items[i].content?.pattern);
-      // v2: 记录成功提交到 tracker
-      if (session?.submissionTracker && currentDimId && entry?.id) {
-        try {
-          session.submissionTracker.recordSubmission(currentDimId, items[i], entry.id);
-        } catch { /* best effort */ }
-      }
-    } 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 (successIds.length > 0) {
-    data.ids = successIds; // recipe ID 列表，供 dimension_complete 的 submittedRecipeIds 使用
-  }
-  if (itemErrors.length > 0) {
-    data.errors = itemErrors;
-  }
-
-  // 被拒绝的条目：告知 Agent 需补齐哪些字段
-  if (rejectedItems.length > 0) {
-    const allMissing = [...new Set(rejectedItems.flatMap((it) => it.missingFields))];
-    data.rejectedItems = rejectedItems;
-    data.rejectedSummary = {
-      rejectedCount: rejectedItems.length,
-      totalCount: items.length,
-      commonMissingFields: allMissing,
-      message: `${rejectedItems.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' },
-  });
-}
-
-// ─── 内部辅助 ──────────────────────────────────────────────
-
-/**
- * 保存开发文档 (autosnippet_save_document)
- *
- * 精简入口：仅需 title + markdown。
- * 自动设置 knowledgeType='dev-document', kind='fact', source='agent'。
- * 不走 RecipeReadiness 检查（文档无需 doClause/trigger）。
- * 支持 autoApprove — 文档直接进入 active 状态。
- */
-export async function saveDocument(ctx, args) {
-  if (!args.title || !args.title.trim()) {
-    throw new Error('title 必填');
-  }
-  if (!args.markdown || !args.markdown.trim()) {
-    throw new Error('markdown 必填');
-  }
-
-  // 限流
-  const blocked = await _checkRateLimit('autosnippet_save_document', args.client_id);
-  if (blocked) {
-    return blocked;
-  }
-
-  const service = ctx.container.get('knowledgeService');
-
-  const data = {
-    title: args.title.trim(),
-    description: args.description || '',
-    knowledgeType: 'dev-document',
-    kind: 'fact',
-    source: args.source || 'agent',
-    scope: args.scope || 'project-specific',
-    tags: args.tags || [],
-    content: {
-      markdown: args.markdown,
-      pattern: '',
-    },
-    // 文档不需要 Cursor Delivery 字段
-    trigger: '',
-    doClause: '',
-    dontClause: '',
-    whenClause: '',
-    topicHint: '',
-    coreCode: '',
-    // 基础推理
-    reasoning: {
-      whyStandard: 'Agent development document — preserved for team knowledge',
-      sources: ['agent'],
-      confidence: 0.8,
-    },
-  };
-
-  // ── UnifiedValidator 校验（自动检测 document 模式）──
-  const validator = new UnifiedValidator();
-  const vr = validator.validate(data, { skipUniqueness: true });
-  if (!vr.pass) {
-    throw new Error(`文档校验失败: ${vr.errors.join('; ')}`);
-  }
-
-  const entry = await service.create(data, { userId: 'mcp' });
-
-  // 自动发布（dev-document 不需要人工审核）
-  try {
-    await service.publish(entry.id, { userId: 'mcp' });
-  } catch {
-    // 发布失败保持 pending — 非阻塞
-  }
-
-  return envelope({
-    success: true,
-    data: {
-      id: entry.id,
-      lifecycle: 'active',
-      title: entry.title,
-      kind: 'fact',
-      knowledgeType: 'dev-document',
-    },
-    message: `文档「${entry.title}」已保存到知识库。`,
-    meta: { tool: 'autosnippet_save_document' },
-  });
-}
-
-// ─── 内部辅助 ──────────────────────────────────────────────
-
-// ─── (已删除: _toReadinessInput — 统一使用 UnifiedValidator) ──

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

@@ -1,291 +0,0 @@
-/**
- * MCP Handlers — 搜索类
- * search, contextSearch, keywordSearch, semanticSearch
- *
- * 设计原则：
- * 1. 通过 container.get('searchEngine') 获取 singleton 实例（含 vectorStore + aiProvider）
- * 2. 4 个工具各有差异化定位，不做简单 mode 包装
- * 3. 统一 responseTime、byKind 分组、kind 过滤
- * 4. 投影原则：只交付 Agent 可操作的信号，去除内部排序信号
- */
-
-import { envelope } from '../envelope.js';
-
-// ─── 工具函数 ────────────────────────────────────────────────
-
-/**
- * 获取 SearchEngine singleton（带 vectorStore + aiProvider）
- * 避免每次调用 new SearchEngine(db) —— 那样没有向量能力、每次重建索引
- */
-function getSearchEngine(ctx) {
-  try {
-    return ctx.container.get('searchEngine');
-  } catch {
-    // 降级：直接创建基础实例（无向量能力）
-    return null;
-  }
-}
-
-/**
- * 降级创建 SearchEngine（仅在 container 无法提供时）
- */
-async function getFallbackEngine(ctx) {
-  const { SearchEngine } = await import('../../../service/search/SearchEngine.js');
-  const db = ctx.container.get('database');
-  return new SearchEngine(db);
-}
-
-/**
- * 根据 kind 参数过滤 items
- */
-function filterByKind(items, kind) {
-  if (!kind || kind === 'all') {
-    return items;
-  }
-  return items.filter((it) => (it.kind || it.metadata?.kind || 'pattern') === kind);
-}
-
-/**
- * 搜索结果投影 — 去除内部排序信号，只保留 Agent 可操作字段。
- *
- * 移除: type(=recipe, 冗余), status(已 filter), updatedAt, createdAt, difficulty,
- *       tags, usageCount, authorityScore, qualityScore, headers, moduleName, content(巨大)
- * 新增: actionHint (whenClause → doClause 一句话摘要)
- */
-function _slimSearchItem(item) {
-  const doText = item.doClause || '';
-  const whenText = item.whenClause || '';
-  const actionHint =
-    doText || whenText
-      ? `${whenText ? `${whenText} → ` : ''}${doText}`.replace(/ → $/, '')
-      : undefined;
-  return {
-    id: item.id,
-    title: item.title,
-    trigger: item.trigger || '',
-    kind: item.kind || 'pattern',
-    language: item.language || '',
-    score: item.score,
-    description: (item.description || '').slice(0, 120),
-    actionHint,
-  };
-}
-
-/**
- * items → slim byKind 分组
- */
-function _slimGroupByKind(items) {
-  const byKind = { rule: [], pattern: [], fact: [] };
-  for (const it of items) {
-    const kind = it.kind || 'pattern';
-    (byKind[kind] || byKind.pattern).push(it);
-  }
-  return byKind;
-}
-
-// ─── 1. autosnippet_search — 统合搜索入口 ─────────────────────
-
-/**
- * 智能统合搜索 —— 支持 auto/keyword/bm25/semantic 四种模式
- *
- * mode=auto（默认）时，同时执行 BM25 + semantic，融合去重取分数最高者。
- * 支持 kind 过滤（rule/pattern/fact）和 byKind 自动分组。
- */
-export async function search(ctx, args) {
-  const t0 = Date.now();
-  const engine = getSearchEngine(ctx) || (await getFallbackEngine(ctx));
-  const query = args.query;
-  const limit = args.limit || 10;
-  const kind = args.kind || args.type || 'all';
-  const mode = args.mode || 'auto';
-
-  // 统一调用 SearchEngine（auto 模式内置 BM25+semantic 融合去重 + Ranking Pipeline）
-  const result = await engine.search(query, {
-    mode,
-    limit: kind !== 'all' ? limit * 2 : limit,
-    rank: true,
-    groupByKind: true,
-  });
-  let items = result?.items || [];
-  const actualMode = result?.mode || mode;
-
-  // kind 过滤
-  items = filterByKind(items, kind);
-  items = items.slice(0, limit);
-
-  // Agent 投影：去除内部排序信号
-  const slimItems = items.map(_slimSearchItem);
-  const byKind = _slimGroupByKind(slimItems);
-  const elapsed = Date.now() - t0;
-
-  return envelope({
-    success: true,
-    data: {
-      query,
-      mode: actualMode,
-      kind: kind === 'all' ? undefined : kind,
-      totalResults: slimItems.length,
-      items: slimItems,
-      byKind,
-      kindCounts: {
-        rule: byKind.rule.length,
-        pattern: byKind.pattern.length,
-        fact: byKind.fact.length,
-      },
-    },
-    meta: { tool: 'autosnippet_search', responseTimeMs: elapsed },
-  });
-}
-
-// ─── 2. autosnippet_context_search — 智能上下文搜索 ────────────
-
-/**
- * 智能上下文搜索 —— SearchEngine 内置 Ranking Pipeline
- *
- * 设计原则：MCP 调用方是外部 AI Agent，意图识别由 Agent 自行完成。
- * 本工具聚焦数据检索：BM25 召回 + CoarseRanker + MultiSignalRanker + 上下文加成
- *
- * 特色：byKind 分组、个性化推荐、会话连续性
- */
-export async function contextSearch(ctx, args) {
-  const t0 = Date.now();
-  const engine = getSearchEngine(ctx) || (await getFallbackEngine(ctx));
-  const limit = args.limit ?? 5;
-
-  const result = await engine.search(args.query, {
-    mode: 'bm25',
-    limit,
-    rank: true,
-    groupByKind: true,
-    context: {
-      intent: 'search',
-      language: args.language,
-      sessionHistory: args.sessionHistory || [],
-    },
-  });
-
-  const items = (result?.items || []).slice(0, limit);
-  const slimItems = items.map(_slimSearchItem);
-  const byKind = _slimGroupByKind(slimItems);
-  const elapsed = Date.now() - t0;
-  const source = result?.ranked ? 'search-engine+ranking' : 'search-engine';
-
-  return envelope({
-    success: true,
-    data: {
-      items: slimItems,
-      byKind,
-      metadata: {
-        responseTimeMs: elapsed,
-        totalResults: slimItems.length,
-        kindCounts: {
-          rule: byKind.rule.length,
-          pattern: byKind.pattern.length,
-          fact: byKind.fact.length,
-        },
-      },
-    },
-    meta: { tool: 'autosnippet_context_search', source, responseTimeMs: elapsed },
-  });
-}
-
-// ─── 3. autosnippet_keyword_search — SQL LIKE 精确匹配 ─────────
-
-/**
- * 纯关键词精确匹配 —— SQL LIKE 查询，适合已知函数名/类名/变量名。
- * 与 search/semantic_search 的 BM25/向量搜索互补：
- * - keyword_search 对精确字符串（ObjC 方法名、类名前缀）最快最准
- * - search 对模糊查询更好（BM25 词频权重）
- * - semantic_search 对自然语言意图最好（向量相似度）
- */
-export async function keywordSearch(ctx, args) {
-  const t0 = Date.now();
-  const engine = getSearchEngine(ctx) || (await getFallbackEngine(ctx));
-  const query = args.query;
-  const limit = args.limit || 10;
-  const kind = args.kind || 'all';
-
-  const result = await engine.search(query, {
-    mode: 'keyword',
-    limit,
-    groupByKind: true,
-  });
-
-  let items = result?.items || [];
-  items = filterByKind(items, kind).slice(0, limit);
-  const slimItems = items.map(_slimSearchItem);
-  const byKind = _slimGroupByKind(slimItems);
-  const elapsed = Date.now() - t0;
-
-  return envelope({
-    success: true,
-    data: {
-      query,
-      mode: 'keyword',
-      kind: kind === 'all' ? undefined : kind,
-      totalResults: slimItems.length,
-      items: slimItems,
-      byKind,
-      kindCounts: {
-        rule: byKind.rule.length,
-        pattern: byKind.pattern.length,
-        fact: byKind.fact.length,
-      },
-    },
-    meta: { tool: 'autosnippet_keyword_search', responseTimeMs: elapsed },
-  });
-}
-
-// ─── 4. autosnippet_semantic_search — 向量语义搜索 ──────────────
-
-/**
- * 向量语义搜索 —— 基于 embedding 的相似度检索。
- * 通过 container singleton 的 SearchEngine（含 vectorStore + aiProvider）执行真正的向量搜索。
- * 如果向量引擎不可用会自动降级到 BM25，并在 actualMode 标注。
- *
- * kind 过滤 + byKind 分组一致性。
- */
-export async function semanticSearch(ctx, args) {
-  const t0 = Date.now();
-  const engine = getSearchEngine(ctx) || (await getFallbackEngine(ctx));
-  const query = args.query;
-  const limit = args.limit || 10;
-  const kind = args.kind || 'all';
-
-  const result = await engine.search(query, {
-    mode: 'semantic',
-    limit: limit * 2,
-    rank: true,
-    groupByKind: true,
-  });
-
-  let items = result?.items || [];
-  const actualMode = result?.mode || 'semantic';
-  items = filterByKind(items, kind).slice(0, limit);
-  const slimItems = items.map(_slimSearchItem);
-  const byKind = _slimGroupByKind(slimItems);
-  const elapsed = Date.now() - t0;
-
-  // 提示 AI Agent 当前实际模式
-  const degraded = actualMode !== 'semantic';
-
-  return envelope({
-    success: true,
-    data: {
-      query,
-      mode: actualMode,
-      kind: kind === 'all' ? undefined : kind,
-      degraded,
-      degradedReason: degraded ? 'vectorStore/aiProvider 不可用，已降级到 BM25' : undefined,
-      totalResults: slimItems.length,
-      items: slimItems,
-      byKind,
-      kindCounts: {
-        rule: byKind.rule.length,
-        pattern: byKind.pattern.length,
-        fact: byKind.fact.length,
-      },
-    },
-    meta: { tool: 'autosnippet_semantic_search', responseTimeMs: elapsed },
-  });
-}