autosnippet 3.0.11 → 3.0.13

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

@@ -1,30 +1,138 @@
 /**
  * MCP Handlers — 知识浏览类 (V3: 使用 knowledgeService)
  * listByKind, listRecipes, getRecipe, recipeInsights, confirmUsage
+ *
+ * 投影原则：只交付 Agent 可操作的信号，不交付内部运营/审计数据。
+ *   - _projectItem   → list 列表摘要（精简 ~10 字段）
+ *   - _projectForAgent → get 详情（去除噪音 ~25 字段）
  */
 
 import { envelope } from '../envelope.js';
 
-/** 将 KnowledgeEntry 的 V3 字段投影为列表摘要 */
+// ─── 通用投影辅助 ────────────────────────────────────────────
+
+/**
+ * 构建 actionHint — "whenClause → doClause" 的一句话可操作摘要。
+ * Agent 在列表/搜索中即可判断是否需要深入获取该条目。
+ */
+function _buildActionHint(json) {
+  const doText = json.doClause || '';
+  const whenText = json.whenClause || '';
+  if (!doText && !whenText) return undefined;
+  return `${whenText ? `${whenText} → ` : ''}${doText}`.replace(/ → $/, '');
+}
+
+/**
+ * 只保留非空关系桶，压缩 Relations 输出体积。
+ */
+function _compactRelations(relations) {
+  if (!relations) return undefined;
+  const compact = {};
+  for (const [type, list] of Object.entries(relations)) {
+    if (Array.isArray(list) && list.length > 0) {
+      compact[type] = list;
+    }
+  }
+  return Object.keys(compact).length > 0 ? compact : undefined;
+}
+
+// ─── 列表投影 ────────────────────────────────────────────────
+
+/**
+ * 将 KnowledgeEntry 投影为列表摘要（精简版）
+ * 移除: quality, stats, scope, tags, knowledgeType, 重复的 status/statistics
+ * 新增: actionHint
+ */
 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 || '',
+    kind: json.kind,
+    language: json.language,
+    category: json.category,
     lifecycle: json.lifecycle,
+    complexity: json.complexity,
+    description: (json.description || '').slice(0, 120),
+    actionHint: _buildActionHint(json),
+  };
+}
+
+// ─── 详情投影 ────────────────────────────────────────────────
+
+/**
+ * 将 KnowledgeEntry 投影为 Agent 消费的详情格式。
+ *
+ * Tier 1（黄金字段）: trigger, doClause, dontClause, whenClause, coreCode, title, content.pattern, kind
+ * Tier 2（上下文）  : language, category, description, tags, rationale, steps, headers, reasoning.whyStandard
+ * Tier 3（去除噪音）: lifecycleHistory, autoApprovable, reviewedBy/At, sourceFile,
+ *                    publishedAt/By, headerPaths, includeHeaders, quality.*, stats.*,
+ *                    reasoning.sources/qualitySignals/alternatives, content.codeChanges/verification
+ */
+function _projectForAgent(json) {
+  // content 精简：保留 pattern/markdown/rationale/steps，去除 codeChanges/verification
+  const content = json.content
+    ? {
+        ...(json.content.pattern ? { pattern: json.content.pattern } : {}),
+        ...(json.content.markdown ? { markdown: json.content.markdown } : {}),
+        ...(json.content.rationale ? { rationale: json.content.rationale } : {}),
+        ...(json.content.steps?.length > 0 ? { steps: json.content.steps } : {}),
+      }
+    : undefined;
+
+  // reasoning 精简：仅保留 whyStandard + confidence
+  const reasoning = json.reasoning
+    ? {
+        ...(json.reasoning.whyStandard ? { whyStandard: json.reasoning.whyStandard } : {}),
+        ...(json.reasoning.confidence != null ? { confidence: json.reasoning.confidence } : {}),
+      }
+    : undefined;
+
+  // constraints 精简：仅保留 guards 和 sideEffects
+  const constraints =
+    json.constraints?.guards?.length > 0 || json.constraints?.sideEffects?.length > 0
+      ? {
+          ...(json.constraints.guards?.length > 0 ? { guards: json.constraints.guards } : {}),
+          ...(json.constraints.sideEffects?.length > 0
+            ? { sideEffects: json.constraints.sideEffects }
+            : {}),
+        }
+      : undefined;
+
+  return {
+    // ── 标识 ──
+    id: json.id,
+    title: json.title,
+    description: json.description,
+    trigger: json.trigger || '',
+
+    // ── 分类 ──
     kind: json.kind,
     language: json.language,
     category: json.category,
     knowledgeType: json.knowledgeType,
     complexity: json.complexity,
-    scope: json.scope,
-    tags: json.tags || [],
-    quality: json.quality || null,
-    stats: json.stats || null,
-    status: json.lifecycle,
-    statistics: json.stats,
+    tags: json.tags?.length > 0 ? json.tags : undefined,
+
+    // ── Agent 可操作指令（Tier 1 黄金字段） ──
+    whenClause: json.whenClause || undefined,
+    doClause: json.doClause || undefined,
+    dontClause: json.dontClause || undefined,
+    coreCode: json.coreCode || undefined,
+
+    // ── 内容 ──
+    content: content && Object.keys(content).length > 0 ? content : undefined,
+
+    // ── 上下文 ──
+    headers: json.headers?.length > 0 ? json.headers : undefined,
+    reasoning: reasoning && Object.keys(reasoning).length > 0 ? reasoning : undefined,
+
+    // ── 关系（仅非空桶） ──
+    relations: _compactRelations(json.relations),
+
+    // ── 约束（仅 guards + sideEffects） ──
+    constraints,
   };
 }
 
@@ -86,7 +194,9 @@ export async function getRecipe(ctx, args) {
     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' } });
+  // Agent 投影：去除运营/审计/统计噪音，只交付可操作字段
+  const projected = _projectForAgent(json);
+  return envelope({ success: true, data: projected, meta: { tool: 'autosnippet_get_recipe' } });
 }
 
 export async function recipeInsights(ctx, args) {

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

@@ -25,8 +25,7 @@ export async function guardCheck(ctx, args) {
     });
   }
 
-  const db = ctx.container.get('database');
-  const engine = new GuardCheckEngine(db);
+  const engine = _getOrCreateEngine(ctx, GuardCheckEngine);
 
   // 注入 Enhancement Pack Guard 规则
   await _injectEnhancementGuardRules(engine, ctx);
@@ -77,8 +76,7 @@ export async function guardAuditFiles(ctx, args) {
   const scope = args.scope || 'project';
 
   const { GuardCheckEngine } = await import('../../../service/guard/GuardCheckEngine.js');
-  const db = ctx.container.get('database');
-  const engine = new GuardCheckEngine(db);
+  const engine = _getOrCreateEngine(ctx, GuardCheckEngine);
 
   // 注入 Enhancement Pack Guard 规则
   await _injectEnhancementGuardRules(engine, ctx);
@@ -207,8 +205,7 @@ export async function scanProject(ctx, args) {
   let guardAudit = null;
   try {
     const { GuardCheckEngine } = await import('../../../service/guard/GuardCheckEngine.js');
-    const db = ctx.container.get('database');
-    const engine = new GuardCheckEngine(db);
+    const engine = _getOrCreateEngine(ctx, GuardCheckEngine);
 
     // 注入 Enhancement Pack Guard 规则
     await _injectEnhancementGuardRules(engine, ctx);
@@ -278,11 +275,32 @@ export async function scanProject(ctx, args) {
 
 // ─── 内部辅助 ─────────────────────────────────────────────
 
+/**
+ * 获取 DI 容器中的 GuardCheckEngine 单例，回退到新建实例
+ * 优先复用 DI 单例以保持 externalRules / cache 的跨调用一致性
+ * @param {object} ctx - MCP context with container
+ * @param {Function} GuardCheckEngine - 引擎构造函数（用于回退）
+ * @returns {import('../../../service/guard/GuardCheckEngine.js').GuardCheckEngine}
+ */
+function _getOrCreateEngine(ctx, GuardCheckEngine) {
+  try {
+    const engine = ctx.container.get('guardCheckEngine');
+    if (engine) return engine;
+  } catch {
+    /* DI not registered — fall back to new instance */
+  }
+  const db = ctx.container.get('database');
+  return new GuardCheckEngine(db);
+}
+
 /**
  * 将 Enhancement Pack 的 Guard 规则注入 GuardCheckEngine
+ * 幂等 — 已注入的引擎直接跳过，避免每次请求重复加载 EnhancementRegistry
  * 静默失败 — Enhancement Pack 不可用不应阻断 Guard 审计
  */
 async function _injectEnhancementGuardRules(engine, ctx) {
+  // 幂等保护: 已注入则跳过
+  if (engine.isEpInjected?.()) return;
   try {
     const { initEnhancementRegistry } = await import('../../../core/enhancement/index.js');
     const enhReg = await initEnhancementRegistry();
@@ -303,6 +321,7 @@ async function _injectEnhancementGuardRules(engine, ctx) {
     if (allGuardRules.length > 0) {
       engine.injectExternalRules(allGuardRules);
     }
+    engine.markEpInjected?.();
   } catch {
     /* Enhancement registry not available — non-critical */
   }

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

@@ -6,6 +6,7 @@
  * 1. 通过 container.get('searchEngine') 获取 singleton 实例（含 vectorStore + aiProvider）
  * 2. 4 个工具各有差异化定位，不做简单 mode 包装
  * 3. 统一 responseTime、byKind 分组、kind 过滤
+ * 4. 投影原则：只交付 Agent 可操作的信号，去除内部排序信号
  */
 
 import { envelope } from '../envelope.js';
@@ -34,18 +35,6 @@ async function getFallbackEngine(ctx) {
   return new SearchEngine(db);
 }
 
-/**
- * items → byKind 分组
- */
-function groupByKind(items) {
-  const byKind = { rule: [], pattern: [], fact: [] };
-  for (const it of items) {
-    const kind = it.kind || it.metadata?.kind || 'pattern';
-    (byKind[kind] || byKind.pattern).push(it);
-  }
-  return byKind;
-}
-
 /**
  * 根据 kind 参数过滤 items
  */
@@ -56,6 +45,44 @@ function filterByKind(items, kind) {
   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 — 统合搜索入口 ─────────────────────
 
 /**
@@ -86,7 +113,9 @@ export async function search(ctx, args) {
   items = filterByKind(items, kind);
   items = items.slice(0, limit);
 
-  const byKind = groupByKind(items);
+  // Agent 投影：去除内部排序信号
+  const slimItems = items.map(_slimSearchItem);
+  const byKind = _slimGroupByKind(slimItems);
   const elapsed = Date.now() - t0;
 
   return envelope({
@@ -95,8 +124,8 @@ export async function search(ctx, args) {
       query,
       mode: actualMode,
       kind: kind === 'all' ? undefined : kind,
-      totalResults: items.length,
-      items,
+      totalResults: slimItems.length,
+      items: slimItems,
       byKind,
       kindCounts: {
         rule: byKind.rule.length,
@@ -136,18 +165,19 @@ export async function contextSearch(ctx, args) {
   });
 
   const items = (result?.items || []).slice(0, limit);
-  const byKind = groupByKind(items);
+  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,
+      items: slimItems,
       byKind,
       metadata: {
         responseTimeMs: elapsed,
-        totalResults: items.length,
+        totalResults: slimItems.length,
         kindCounts: {
           rule: byKind.rule.length,
           pattern: byKind.pattern.length,
@@ -183,7 +213,8 @@ export async function keywordSearch(ctx, args) {
 
   let items = result?.items || [];
   items = filterByKind(items, kind).slice(0, limit);
-  const byKind = groupByKind(items);
+  const slimItems = items.map(_slimSearchItem);
+  const byKind = _slimGroupByKind(slimItems);
   const elapsed = Date.now() - t0;
 
   return envelope({
@@ -192,8 +223,8 @@ export async function keywordSearch(ctx, args) {
       query,
       mode: 'keyword',
       kind: kind === 'all' ? undefined : kind,
-      totalResults: items.length,
-      items,
+      totalResults: slimItems.length,
+      items: slimItems,
       byKind,
       kindCounts: {
         rule: byKind.rule.length,
@@ -231,7 +262,8 @@ export async function semanticSearch(ctx, args) {
   let items = result?.items || [];
   const actualMode = result?.mode || 'semantic';
   items = filterByKind(items, kind).slice(0, limit);
-  const byKind = groupByKind(items);
+  const slimItems = items.map(_slimSearchItem);
+  const byKind = _slimGroupByKind(slimItems);
   const elapsed = Date.now() - t0;
 
   // 提示 AI Agent 当前实际模式
@@ -245,8 +277,8 @@ export async function semanticSearch(ctx, args) {
       kind: kind === 'all' ? undefined : kind,
       degraded,
       degradedReason: degraded ? 'vectorStore/aiProvider 不可用，已降级到 BM25' : undefined,
-      totalResults: items.length,
-      items,
+      totalResults: slimItems.length,
+      items: slimItems,
       byKind,
       kindCounts: {
         rule: byKind.rule.length,

package/lib/http/routes/guardRules.js

@@ -5,6 +5,7 @@
 
 import express from 'express';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
+import { LanguageService } from '../../shared/LanguageService.js';
 import { NotFoundError, ValidationError } from '../../shared/errors/index.js';
 import { asyncHandler } from '../middleware/errorHandler.js';
 import { getContext, safeInt } from '../utils/routeHelpers.js';
@@ -105,31 +106,22 @@ router.get(
     const allRules = [...mappedDbRules, ...builtInRules];
 
     // 获取当前项目检测到的语言列表，供前端按项目语言筛选
-    // discoverer ID → 对应的 guard 规则语言
-    const DISCOVERER_TO_GUARD_LANGS = {
-      spm: ['swift', 'objc'],
-      node: ['javascript', 'typescript'],
-      go: ['go'],
-      jvm: ['java', 'kotlin'],
-      python: ['python'],
-      dart: ['dart'],
-    };
+    // 使用 LanguageService 统一检测（支持 Discoverer + Monorepo 文件标记回退）
     let projectLanguages = [];
     try {
       const moduleService = container.get('moduleService');
+      await moduleService.load();
       const info = moduleService.getProjectInfo();
       const discovererIds = info.languages || [];
-      const langSet = new Set();
-      for (const did of discovererIds) {
-        for (const lang of DISCOVERER_TO_GUARD_LANGS[did] || []) {
-          langSet.add(lang);
-        }
-      }
-      projectLanguages = [...langSet];
+      projectLanguages = LanguageService.detectProjectLanguages(process.cwd(), { discovererIds });
     } catch {
-      /* moduleService not loaded yet */
+      // moduleService 不可用时纯文件扫描回退
+      projectLanguages = LanguageService.detectProjectLanguages(process.cwd());
     }
 
+    // Guard 内置规则中 objectivec 记为 'objc'，做向后兼容映射
+    projectLanguages = projectLanguages.map((l) => LanguageService.toGuardLangId(l));
+
     res.json({
       success: true,
       data: {

package/lib/injection/ServiceContainer.js

@@ -384,13 +384,19 @@ export class ServiceContainer {
       return this.singletons.knowledgeService;
     });
 
-    // GuardService (V3: uses knowledgeRepository)
+    // GuardService (V3: uses knowledgeRepository, delegates to GuardCheckEngine)
     this.register('guardService', () => {
       if (!this.singletons.guardService) {
         const knowledgeRepository = this.get('knowledgeRepository');
         const auditLogger = this.get('auditLogger');
         const gateway = this.get('gateway');
-        this.singletons.guardService = new GuardService(knowledgeRepository, auditLogger, gateway);
+        let guardCheckEngine = null;
+        try {
+          guardCheckEngine = this.get('guardCheckEngine');
+        } catch { /* engine not yet available */ }
+        this.singletons.guardService = new GuardService(knowledgeRepository, auditLogger, gateway, {
+          guardCheckEngine,
+        });
       }
       return this.singletons.guardService;
     });
@@ -434,7 +440,10 @@ export class ServiceContainer {
     this.register('guardCheckEngine', () => {
       if (!this.singletons.guardCheckEngine) {
         const database = this.get('database');
-        this.singletons.guardCheckEngine = new GuardCheckEngine(database);
+        const config = this.singletons._config || {};
+        this.singletons.guardCheckEngine = new GuardCheckEngine(database, {
+          guardConfig: config.guard || {},
+        });
       }
       return this.singletons.guardCheckEngine;
     });