autosnippet 3.0.0 → 3.0.2

package/lib/service/quality/FeedbackCollector.js

@@ -4,13 +4,13 @@
  * 持久化到 AutoSnippet/feedback.json（Git 友好）
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import pathGuard from '../../shared/PathGuard.js';
 
 export class FeedbackCollector {
   #feedbackPath;
-  #events;     // [{ type, recipeId, data, timestamp }]
+  #events; // [{ type, recipeId, data, timestamp }]
   #maxEvents;
 
   constructor(projectRoot, options = {}) {
@@ -49,15 +49,17 @@ export class FeedbackCollector {
    * @returns {{ views: number, clicks: number, copies: number, avgRating: number, feedbackCount: number }}
    */
   getRecipeStats(recipeId) {
-    const events = this.#events.filter(e => e.recipeId === recipeId);
-    const ratings = events.filter(e => e.type === 'rate' && e.data.rating).map(e => e.data.rating);
+    const events = this.#events.filter((e) => e.recipeId === recipeId);
+    const ratings = events
+      .filter((e) => e.type === 'rate' && e.data.rating)
+      .map((e) => e.data.rating);
 
     return {
-      views: events.filter(e => e.type === 'view').length,
-      clicks: events.filter(e => e.type === 'click').length,
-      copies: events.filter(e => e.type === 'copy' || e.type === 'insert').length,
+      views: events.filter((e) => e.type === 'view').length,
+      clicks: events.filter((e) => e.type === 'click').length,
+      copies: events.filter((e) => e.type === 'copy' || e.type === 'insert').length,
       avgRating: ratings.length > 0 ? ratings.reduce((a, b) => a + b, 0) / ratings.length : 0,
-      feedbackCount: events.filter(e => e.type === 'feedback').length,
+      feedbackCount: events.filter((e) => e.type === 'feedback').length,
       totalEvents: events.length,
     };
   }
@@ -73,7 +75,7 @@ export class FeedbackCollector {
     return {
       totalEvents: this.#events.length,
       byType,
-      uniqueRecipes: new Set(this.#events.map(e => e.recipeId)).size,
+      uniqueRecipes: new Set(this.#events.map((e) => e.recipeId)).size,
     };
   }
 
@@ -107,16 +109,22 @@ export class FeedbackCollector {
         const data = JSON.parse(readFileSync(this.#feedbackPath, 'utf-8'));
         return Array.isArray(data) ? data : data.events || [];
       }
-    } catch { /* silent */ }
+    } catch {
+      /* silent */
+    }
     return [];
   }
 
   #save() {
     try {
       const dir = dirname(this.#feedbackPath);
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
       writeFileSync(this.#feedbackPath, JSON.stringify(this.#events, null, 2));
-    } catch { /* silent */ }
+    } catch {
+      /* silent */
+    }
   }
 
   #migrateOldPath(projectRoot, internalDir) {
@@ -125,10 +133,14 @@ export class FeedbackCollector {
       if (existsSync(oldPath) && !existsSync(this.#feedbackPath)) {
         const content = readFileSync(oldPath, 'utf-8');
         const dir = dirname(this.#feedbackPath);
-        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        if (!existsSync(dir)) {
+          mkdirSync(dir, { recursive: true });
+        }
         writeFileSync(this.#feedbackPath, content);
         unlinkSync(oldPath);
       }
-    } catch { /* 迁移失败不阻断启动 */ }
+    } catch {
+      /* 迁移失败不阻断启动 */
+    }
   }
 }

package/lib/service/quality/QualityScorer.js

@@ -4,7 +4,7 @@
  * 每个维度评分 0-1，加权求和
  */
 
-import { QUALITY_WEIGHTS, QUALITY_GRADES, CODE_LENGTH } from '../../shared/constants.js';
+import { CODE_LENGTH, QUALITY_GRADES, QUALITY_WEIGHTS } from '../../shared/constants.js';
 
 const DEFAULT_WEIGHTS = QUALITY_WEIGHTS;
 
@@ -47,7 +47,7 @@ export class QualityScorer {
    * 批量评分
    */
   scoreBatch(recipes) {
-    return recipes.map(r => ({ recipe: r, ...this.score(r) }));
+    return recipes.map((r) => ({ recipe: r, ...this.score(r) }));
   }
 
   /**
@@ -64,10 +64,18 @@ export class QualityScorer {
    */
   #scoreCompleteness(r) {
     let s = 0;
-    if (r.title && r.title.trim()) s += 0.25;
-    if (r.trigger && r.trigger.trim()) s += 0.25;
-    if (r.code && r.code.trim().length > 5) s += 0.30;
-    if (r.usageGuide && r.usageGuide.trim()) s += 0.20;
+    if (r.title?.trim()) {
+      s += 0.25;
+    }
+    if (r.trigger?.trim()) {
+      s += 0.25;
+    }
+    if (r.code && r.code.trim().length > 5) {
+      s += 0.3;
+    }
+    if (r.usageGuide?.trim()) {
+      s += 0.2;
+    }
     return s;
   }
 
@@ -77,14 +85,29 @@ export class QualityScorer {
   #scoreFormat(r) {
     let s = 0;
     if (r.trigger) {
-      if (/^[a-zA-Z0-9_\-:.]+$/.test(r.trigger) && r.trigger.length >= 2 && r.trigger.length <= 64) {
+      if (
+        /^[a-zA-Z0-9_\-:.]+$/.test(r.trigger) &&
+        r.trigger.length >= 2 &&
+        r.trigger.length <= 64
+      ) {
         s += 0.5;
       } else if (r.trigger.length >= 2) {
         s += 0.25;
       }
     }
     if (r.language) {
-      const valid = new Set(['swift', 'objective-c', 'objc', 'javascript', 'typescript', 'python', 'c', 'cpp', 'shell', 'markdown']);
+      const valid = new Set([
+        'swift',
+        'objective-c',
+        'objc',
+        'javascript',
+        'typescript',
+        'python',
+        'c',
+        'cpp',
+        'shell',
+        'markdown',
+      ]);
       s += valid.has(r.language.toLowerCase()) ? 0.5 : 0.25;
     }
     return s;
@@ -94,22 +117,33 @@ export class QualityScorer {
    * 代码质量: 长度适中(0.3) + 无 TODO(0.2) + 有注释(0.3) + 有错误处理(0.2)
    */
   #scoreCodeQuality(r) {
-    if (!r.code) return 0;
+    if (!r.code) {
+      return 0;
+    }
     let s = 0;
     const code = r.code;
 
     // 长度适中
-    if (code.length >= CODE_LENGTH.MIN && code.length <= CODE_LENGTH.MAX) s += 0.3;
-    else if (code.length > CODE_LENGTH.MAX) s += 0.15;
+    if (code.length >= CODE_LENGTH.MIN && code.length <= CODE_LENGTH.MAX) {
+      s += 0.3;
+    } else if (code.length > CODE_LENGTH.MAX) {
+      s += 0.15;
+    }
 
     // 无 TODO/FIXME/HACK
-    if (!/\b(TODO|FIXME|HACK|XXX)\b/.test(code)) s += 0.2;
+    if (!/\b(TODO|FIXME|HACK|XXX)\b/.test(code)) {
+      s += 0.2;
+    }
 
     // 有注释
-    if (/\/\/|\/\*|#\s/.test(code)) s += 0.3;
+    if (/\/\/|\/\*|#\s/.test(code)) {
+      s += 0.3;
+    }
 
     // 有错误处理
-    if (/try|catch|throw|guard|if\s+let|do\s*\{|\.catch/.test(code)) s += 0.2;
+    if (/try|catch|throw|guard|if\s+let|do\s*\{|\.catch/.test(code)) {
+      s += 0.2;
+    }
 
     return s;
   }
@@ -119,9 +153,15 @@ export class QualityScorer {
    */
   #scoreMetadata(r) {
     let s = 0;
-    if (r.category && r.category.trim()) s += 0.35;
-    if ((r.tags && r.tags.length > 0) || (r.headers && r.headers.length > 0)) s += 0.35;
-    if (r.summary && r.summary.trim()) s += 0.30;
+    if (r.category?.trim()) {
+      s += 0.35;
+    }
+    if ((r.tags && r.tags.length > 0) || (r.headers && r.headers.length > 0)) {
+      s += 0.35;
+    }
+    if (r.summary?.trim()) {
+      s += 0.3;
+    }
     return s;
   }
 
@@ -130,9 +170,15 @@ export class QualityScorer {
    */
   #scoreEngagement(r) {
     let s = 0;
-    if (r.views && r.views > 0) s += Math.min(0.3, (r.views / 100) * 0.3);
-    if (r.clicks && r.clicks > 0) s += Math.min(0.3, (r.clicks / 50) * 0.3);
-    if (r.rating && r.rating > 0) s += (r.rating / 5) * 0.4;
+    if (r.views && r.views > 0) {
+      s += Math.min(0.3, (r.views / 100) * 0.3);
+    }
+    if (r.clicks && r.clicks > 0) {
+      s += Math.min(0.3, (r.clicks / 50) * 0.3);
+    }
+    if (r.rating && r.rating > 0) {
+      s += (r.rating / 5) * 0.4;
+    }
     return s;
   }
 
@@ -140,10 +186,18 @@ export class QualityScorer {
    * 分数转等级
    */
   #toGrade(score) {
-    if (score >= QUALITY_GRADES.A) return 'A';
-    if (score >= QUALITY_GRADES.B) return 'B';
-    if (score >= QUALITY_GRADES.C) return 'C';
-    if (score >= QUALITY_GRADES.D) return 'D';
+    if (score >= QUALITY_GRADES.A) {
+      return 'A';
+    }
+    if (score >= QUALITY_GRADES.B) {
+      return 'B';
+    }
+    if (score >= QUALITY_GRADES.C) {
+      return 'C';
+    }
+    if (score >= QUALITY_GRADES.D) {
+      return 'D';
+    }
     return 'F';
   }
 }

package/lib/service/recipe/RecipeCandidateValidator.js

@@ -1,26 +1,42 @@
 /**
- * RecipeCandidateValidator — Recipe 候选校验器
- * 验证候选 Recipe 是否满足最低字段要求
+ * RecipeCandidateValidator — Recipe 候选校验器 (V3)
+ *
+ * 验证候选是否满足 V3 结构化字段要求。
+ * 核心变更：用 content 对象替代旧版 code 字符串。
  */
 
-const REQUIRED_FIELDS = ['title', 'trigger', 'category', 'language', 'code'];
+import { LanguageService } from '../../shared/LanguageService.js';
+
+/* ── V3 必填字段 ── */
+const REQUIRED_FIELDS = [
+  'title',       // 中文简短标题
+  'trigger',     // @前缀 kebab-case
+  'category',    // View/Service/Tool/Model/Network/Storage/UI/Utility
+  'language',    // 编程语言标识
+  'kind',        // rule / pattern / fact
+  'doClause',    // 英文祈使句正向指令
+  'description', // 中文简述 ≤80字
+];
+
+/* ── 需要 content 子对象有内容 ── */
+const REQUIRED_CONTENT_FIELDS = ['pattern', 'markdown', 'rationale'];
 
 const VALID_CATEGORIES = new Set([
-  'swift', 'objc', 'javascript', 'typescript', 'python',
-  'swiftui', 'uikit', 'combine', 'concurrency', 'testing',
-  'networking', 'persistence', 'security', 'architecture',
-  'performance', 'debugging', 'general',
+  'view',
+  'service',
+  'tool',
+  'model',
+  'network',
+  'storage',
+  'ui',
+  'utility',
 ]);
 
-const VALID_LANGUAGES = new Set([
-  'swift', 'objective-c', 'objc', 'javascript', 'typescript',
-  'python', 'c', 'cpp', 'c++', 'shell', 'bash', 'markdown',
-]);
+const VALID_KINDS = new Set(['rule', 'pattern', 'fact']);
 
 export class RecipeCandidateValidator {
-
   /**
-   * 验证单个候选
+   * 验证单个候选（V3 结构）
    * @param {object} candidate
    * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
    */
@@ -32,55 +48,81 @@ export class RecipeCandidateValidator {
       return { valid: false, errors: ['候选为空或类型错误'], warnings: [] };
     }
 
-    // 必填字段
+    // ── V3 必填字段 ──
     for (const field of REQUIRED_FIELDS) {
-      if (!candidate[field] || (typeof candidate[field] === 'string' && !candidate[field].trim())) {
+      const val = candidate[field];
+      if (!val || (typeof val === 'string' && !val.trim())) {
         errors.push(`缺少必填字段: ${field}`);
       }
     }
 
-    // trigger 格式 — 建议以 as: 或 asd- 开头
+    // ── content 对象必须包含有效内容 ──
+    const content = candidate.content;
+    if (!content || typeof content !== 'object') {
+      errors.push('缺少必填字段: content（需为 { pattern, markdown, rationale } 对象）');
+    } else {
+      const hasPattern = !!(content.pattern && String(content.pattern).trim());
+      const hasMarkdown = !!(content.markdown && String(content.markdown).trim());
+      if (!hasPattern && !hasMarkdown) {
+        errors.push('content.pattern 或 content.markdown 至少需要一个非空');
+      }
+      if (!content.rationale || !String(content.rationale).trim()) {
+        errors.push('缺少必填字段: content.rationale（设计原理）');
+      }
+    }
+
+    // ── trigger 格式 ──
     if (candidate.trigger && typeof candidate.trigger === 'string') {
-      if (candidate.trigger.length < 2) errors.push('trigger 过短');
-      if (candidate.trigger.length > 64) errors.push('trigger 过长 (>64)');
-      if (!/^[a-zA-Z0-9_\-:.]+$/.test(candidate.trigger)) {
+      if (candidate.trigger.length < 2) {
+        errors.push('trigger 过短');
+      }
+      if (candidate.trigger.length > 64) {
+        errors.push('trigger 过长 (>64)');
+      }
+      if (!candidate.trigger.startsWith('@')) {
+        warnings.push('trigger 应以 @ 开头');
+      }
+      if (!/^@?[a-zA-Z0-9_\-:.]+$/.test(candidate.trigger)) {
         warnings.push('trigger 含特殊字符，建议仅使用字母/数字/下划线/连字符');
       }
     }
 
-    // category 合法性
-    if (candidate.category && !VALID_CATEGORIES.has(candidate.category.toLowerCase())) {
-      warnings.push(`category "${candidate.category}" 不在推荐列表中`);
+    // ── kind 合法性 ──
+    if (candidate.kind && !VALID_KINDS.has(candidate.kind)) {
+      errors.push(`kind "${candidate.kind}" 无效 — 必须为 rule/pattern/fact`);
     }
 
-    // language 合法性
-    if (candidate.language && !VALID_LANGUAGES.has(candidate.language.toLowerCase())) {
-      warnings.push(`language "${candidate.language}" 不在推荐列表中`);
+    // ── category 合法性 ──
+    if (candidate.category && !VALID_CATEGORIES.has(candidate.category.toLowerCase())) {
+      warnings.push(`category "${candidate.category}" 不在标准列表（View/Service/Tool/Model/Network/Storage/UI/Utility）`);
     }
 
-    // code 质量检查
-    if (candidate.code && typeof candidate.code === 'string') {
-      if (candidate.code.trim().length < 10) {
-        warnings.push('code 内容过短 (<10 字符)');
-      }
-      if (candidate.code.length > 50000) {
-        warnings.push('code 内容过长 (>50000 字符)，建议拆分');
+    // ── language 合法性 ──
+    if (candidate.language) {
+      const lang = candidate.language.toLowerCase();
+      if (!LanguageService.isKnownLang(lang) && lang !== 'objc' && lang !== 'markdown') {
+        warnings.push(`language "${candidate.language}" 不在已知语言列表`);
       }
     }
 
-    // 摘要/描述（非必填但建议）
-    if (!candidate.summary && !candidate.description) {
-      warnings.push('建议提供 summary 或 description');
+    // ── headers 必填 ──
+    if (!Array.isArray(candidate.headers)) {
+      errors.push('缺少必填字段: headers（需为 import 语句数组，无 import 时传 []）');
     }
 
-    // 标签
-    if (candidate.tags && !Array.isArray(candidate.tags)) {
-      warnings.push('tags 应为数组');
+    // ── knowledgeType 必填 ──
+    if (!candidate.knowledgeType || !String(candidate.knowledgeType).trim()) {
+      errors.push('缺少必填字段: knowledgeType');
     }
 
-    // 推理依据 (reasoning)
+    // ── usageGuide 必填 ──
+    if (!candidate.usageGuide || !String(candidate.usageGuide).trim()) {
+      errors.push('缺少必填字段: usageGuide（使用指南，### 章节格式）');
+    }
+
+    // ── 推理依据 (reasoning) 必填 ──
     if (!candidate.reasoning) {
-      warnings.push('缺少 reasoning（推理依据）— 需要 whyStandard + sources + confidence');
+      errors.push('缺少必填字段: reasoning（需包含 whyStandard + sources + confidence）');
     } else {
       if (!candidate.reasoning.whyStandard?.trim()) {
         errors.push('reasoning.whyStandard 不能为空');
@@ -88,11 +130,20 @@ export class RecipeCandidateValidator {
       if (!Array.isArray(candidate.reasoning.sources) || candidate.reasoning.sources.length === 0) {
         errors.push('reasoning.sources 至少包含一项来源');
       }
-      if (typeof candidate.reasoning.confidence !== 'number' || candidate.reasoning.confidence < 0 || candidate.reasoning.confidence > 1) {
+      if (
+        typeof candidate.reasoning.confidence !== 'number' ||
+        candidate.reasoning.confidence < 0 ||
+        candidate.reasoning.confidence > 1
+      ) {
         warnings.push('reasoning.confidence 应为 0-1 的数字');
       }
     }
 
+    // ── 标签 ──
+    if (candidate.tags && !Array.isArray(candidate.tags)) {
+      warnings.push('tags 应为数组');
+    }
+
     return {
       valid: errors.length === 0,
       errors,
@@ -137,9 +188,24 @@ export class RecipeCandidateValidator {
   }
 
   /**
-   * 获取有效语言列表
+   * 获取有效 kind 列表
+   */
+  getValidKinds() {
+    return [...VALID_KINDS];
+  }
+
+  /**
+   * 获取所有必填字段名列表
    */
-  getValidLanguages() {
-    return [...VALID_LANGUAGES];
+  getRequiredFields() {
+    return [
+      ...REQUIRED_FIELDS,
+      'content',
+      'content.rationale',
+      'headers',
+      'knowledgeType',
+      'usageGuide',
+      'reasoning',
+    ];
   }
 }