autosnippet 2.9.0 → 2.10.0

package/lib/domain/knowledge/values/Constraints.js

@@ -0,0 +1,125 @@
+/**
+ * Constraints — 约束值对象
+ *
+ * 包含 Guard 规则 (regex + ast)、边界约束、前置条件、副作用。
+ * Guard 规则预留 AST 类型，为语义规则做前瞻设计。
+ */
+export class Constraints {
+  constructor(props = {}) {
+    /** @type {Array<Guard>} Guard 规则列表 */
+    this.guards        = (props.guards || []).map(Constraints._normalizeGuard);
+    /** @type {string[]} 边界约束 */
+    this.boundaries    = props.boundaries    || [];
+    /** @type {string[]} 前置条件 */
+    this.preconditions = props.preconditions || [];
+    /** @type {string[]} 副作用 */
+    this.sideEffects   = props.side_effects  ?? props.sideEffects ?? [];
+  }
+
+  /**
+   * 从任意输入构造 Constraints
+   * @param {Constraints|Object|null} input
+   * @returns {Constraints}
+   */
+  static from(input) {
+    if (input instanceof Constraints) return input;
+    if (!input) return new Constraints();
+    return new Constraints(input);
+  }
+
+  /**
+   * 标准化 Guard 对象
+   * @param {Object} g
+   * @returns {Guard}
+   */
+  static _normalizeGuard(g) {
+    return {
+      id:             g.id             || null,
+      type:           g.type           || (g.ast_query ? 'ast' : 'regex'),
+      pattern:        g.pattern        || null,
+      ast_query:      g.ast_query      || null,
+      message:        g.message        || '',
+      severity:       g.severity       || 'warning',
+      fix_suggestion: g.fix_suggestion || null,
+    };
+  }
+
+  /**
+   * 获取 regex 类型的 Guard 规则
+   * @returns {Array<Guard>}
+   */
+  getRegexGuards() {
+    return this.guards.filter(g => g.type === 'regex' && g.pattern);
+  }
+
+  /**
+   * 获取 ast 类型的 Guard 规则
+   * @returns {Array<Guard>}
+   */
+  getAstGuards() {
+    return this.guards.filter(g => g.type === 'ast' && g.ast_query);
+  }
+
+  /**
+   * 添加 Guard 规则
+   * @param {Object} guard
+   * @returns {Constraints}
+   */
+  addGuard(guard) {
+    this.guards.push(Constraints._normalizeGuard(guard));
+    return this;
+  }
+
+  /**
+   * 是否有 Guard 规则
+   * @returns {boolean}
+   */
+  hasGuards() {
+    return this.guards.length > 0;
+  }
+
+  /**
+   * 是否为空
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.guards.length === 0 &&
+           this.boundaries.length === 0 &&
+           this.preconditions.length === 0 &&
+           this.sideEffects.length === 0;
+  }
+
+  /**
+   * 转换为 wire format JSON
+   */
+  toJSON() {
+    return {
+      guards:        this.guards,
+      boundaries:    this.boundaries,
+      preconditions: this.preconditions,
+      side_effects:  this.sideEffects,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Constraints}
+   */
+  static fromJSON(data) {
+    return Constraints.from(data);
+  }
+}
+
+/**
+ * @typedef {Object} Guard
+ * @property {?string} id          - Guard 唯一标识
+ * @property {'regex'|'ast'} type  - 类型
+ * @property {?string} pattern     - regex pattern (type=regex 时)
+ * @property {?Object} ast_query   - AST 查询 (type=ast 时)
+ * @property {string}  message     - 错误/警告消息
+ * @property {'error'|'warning'|'info'} severity - 严重级别
+ * @property {?string} fix_suggestion - 关联修复 Recipe 的 trigger
+ */
+
+export default Constraints;

package/lib/domain/knowledge/values/Content.js

@@ -0,0 +1,86 @@
+/**
+ * Content — 内容值对象
+ *
+ * 统一承载代码片段 (pattern) 或 Markdown 全文 (markdown)，
+ * 以及设计原理、实施步骤、代码变更、验证方式。
+ */
+export class Content {
+  constructor(props = {}) {
+    /** @type {string} 代码片段 */
+    this.pattern      = props.pattern      ?? '';
+    /** @type {string} Markdown 全文（与 pattern 二选一） */
+    this.markdown     = props.markdown     ?? '';
+    /** @type {string} 设计原理 */
+    this.rationale    = props.rationale    ?? '';
+    /** @type {Array<{title?:string, description?:string, code?:string}>} 实施步骤 */
+    this.steps        = props.steps        ?? [];
+    /** @type {Array<{file:string, before:string, after:string, explanation:string}>} 代码变更 */
+    this.codeChanges  = props.code_changes ?? props.codeChanges ?? [];
+    /** @type {?{method?:string, expected_result?:string, test_code?:string}} 验证方式 */
+    this.verification = props.verification ?? null;
+  }
+
+  /**
+   * 从任意输入构造 Content
+   * @param {Content|Object|null} input
+   * @returns {Content}
+   */
+  static from(input) {
+    if (input instanceof Content) return input;
+    if (!input) return new Content();
+    return new Content(input);
+  }
+
+  /**
+   * 从旧 Candidate 的 code + metadata 构建
+   * @param {string} code
+   * @param {Object} meta
+   * @returns {Content}
+   */
+  static fromLegacyCandidate(code, meta = {}) {
+    const isMarkdown = code && (
+      code.includes('— 项目特写') || /^#{1,3}\s/.test(code.trimStart())
+    );
+    return new Content({
+      pattern:      isMarkdown ? '' : (code || ''),
+      markdown:     isMarkdown ? code : '',
+      rationale:    meta.rationale || '',
+      steps:        meta.steps || [],
+      code_changes: meta.codeChanges || meta.code_changes || [],
+      verification: meta.verification || null,
+    });
+  }
+
+  /**
+   * 是否包含有效内容
+   * @returns {boolean}
+   */
+  hasContent() {
+    return !!(this.pattern || this.markdown || this.rationale || this.steps.length > 0);
+  }
+
+  /**
+   * 转换为 wire format JSON
+   */
+  toJSON() {
+    return {
+      pattern:      this.pattern,
+      markdown:     this.markdown,
+      rationale:    this.rationale,
+      steps:        this.steps,
+      code_changes: this.codeChanges,
+      verification: this.verification,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Content}
+   */
+  static fromJSON(data) {
+    return new Content(data);
+  }
+}
+
+export default Content;

package/lib/domain/knowledge/values/Quality.js

@@ -0,0 +1,93 @@
+/**
+ * Quality — 质量值对象
+ *
+ * 4 维度评分 + 综合分 + 等级。
+ */
+export class Quality {
+  constructor(props = {}) {
+    /** @type {number} 内容完整度 (0-1) */
+    this.completeness   = props.completeness   ?? 0;
+    /** @type {number} 项目适配度 (0-1) */
+    this.adaptation     = props.adaptation     ?? 0;
+    /** @type {number} 文档清晰度 (0-1) */
+    this.documentation  = props.documentation  ?? 0;
+    /** @type {number} 综合分 (0-1) */
+    this.overall        = props.overall        ?? 0;
+    /** @type {string} 等级 A-F */
+    this.grade          = props.grade          || Quality.calcGrade(this.overall);
+  }
+
+  /**
+   * 从任意输入构造 Quality
+   * @param {Quality|Object|null} input
+   * @returns {Quality}
+   */
+  static from(input) {
+    if (input instanceof Quality) return input;
+    return new Quality(input || {});
+  }
+
+  /**
+   * 从旧 Recipe quality 字段映射
+   * @param {Object} old { codeCompleteness, projectAdaptation, documentationClarity, overall }
+   * @returns {Quality}
+   */
+  static fromLegacyRecipe(old) {
+    if (!old) return new Quality();
+    return new Quality({
+      completeness:  old.codeCompleteness      ?? old.completeness  ?? 0,
+      adaptation:    old.projectAdaptation      ?? old.adaptation    ?? 0,
+      documentation: old.documentationClarity   ?? old.documentation ?? 0,
+      overall:       old.overall                ?? 0,
+    });
+  }
+
+  /**
+   * 从 3 维度计算综合分
+   * @returns {Quality}
+   */
+  recalculate() {
+    this.overall = Math.round(
+      ((this.completeness + this.adaptation + this.documentation) / 3) * 100
+    ) / 100;
+    this.grade = Quality.calcGrade(this.overall);
+    return this;
+  }
+
+  /**
+   * 根据分数计算等级
+   * @param {number} score 0-1
+   * @returns {string}
+   */
+  static calcGrade(score) {
+    if (score >= 0.9) return 'A';
+    if (score >= 0.75) return 'B';
+    if (score >= 0.6) return 'C';
+    if (score >= 0.4) return 'D';
+    return 'F';
+  }
+
+  /**
+   * 转换为 wire format JSON
+   */
+  toJSON() {
+    return {
+      completeness:  this.completeness,
+      adaptation:    this.adaptation,
+      documentation: this.documentation,
+      overall:       this.overall,
+      grade:         this.grade,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Quality}
+   */
+  static fromJSON(data) {
+    return Quality.from(data);
+  }
+}
+
+export default Quality;

package/lib/domain/knowledge/values/Reasoning.js

@@ -0,0 +1,69 @@
+/**
+ * Reasoning — 推理值对象（V3 统一版）
+ *
+ * 与旧 Candidate.Reasoning 逻辑一致，但 wire format 统一为 snake_case。
+ */
+export class Reasoning {
+  constructor(props = {}) {
+    /** @type {string} 为什么遵循标准 */
+    this.whyStandard    = props.why_standard    ?? props.whyStandard ?? '';
+    /** @type {string[]} 来源列表 */
+    this.sources        = props.sources         || [];
+    /** @type {number} 置信度 0-1 */
+    this.confidence     = props.confidence      ?? 0.7;
+    /** @type {Object.<string, number>} 质量信号 */
+    this.qualitySignals = props.quality_signals  ?? props.qualitySignals ?? {};
+    /** @type {string[]} 备选方案 */
+    this.alternatives   = props.alternatives    || [];
+  }
+
+  /**
+   * 从任意输入构造 Reasoning
+   * @param {Reasoning|Object|null} input
+   * @returns {Reasoning}
+   */
+  static from(input) {
+    if (input instanceof Reasoning) return input;
+    if (!input) return new Reasoning();
+    return new Reasoning(input);
+  }
+
+  /**
+   * 验证推理信息的完整性
+   * @returns {boolean}
+   */
+  isValid() {
+    return !!(
+      this.whyStandard?.trim() &&
+      Array.isArray(this.sources) &&
+      this.sources.length > 0 &&
+      typeof this.confidence === 'number' &&
+      this.confidence >= 0 &&
+      this.confidence <= 1
+    );
+  }
+
+  /**
+   * 转换为 wire format JSON (snake_case)
+   */
+  toJSON() {
+    return {
+      why_standard:    this.whyStandard,
+      sources:         this.sources,
+      confidence:      this.confidence,
+      quality_signals: this.qualitySignals,
+      alternatives:    this.alternatives,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Reasoning}
+   */
+  static fromJSON(data) {
+    return new Reasoning(data);
+  }
+}
+
+export default Reasoning;

package/lib/domain/knowledge/values/Relations.js

@@ -0,0 +1,168 @@
+/**
+ * Relations — 关系图值对象
+ *
+ * 统一为分桶结构（非扁平数组）。
+ * 每个桶存储 [{ target, description }] 格式的关系列表。
+ */
+
+/** 所有合法的关系桶名 (snake_case) */
+export const RELATION_BUCKETS = [
+  'inherits',       // 继承
+  'implements',     // 实现接口/协议
+  'calls',          // 调用
+  'depends_on',     // 依赖
+  'data_flow',      // 数据流向
+  'conflicts',      // 冲突
+  'extends',        // 扩展
+  'related',        // 弱关联
+  'alternative',    // 替代方案
+  'prerequisite',   // 前置条件
+  'deprecated_by',  // 被取代
+  'solves',         // 解决问题
+  'enforces',       // 强制约束
+  'references',     // 引用
+];
+
+/** camelCase → snake_case 桶名映射（兼容旧数据） */
+const LEGACY_BUCKET_MAP = {
+  dependsOn:    'depends_on',
+  dataFlow:     'data_flow',
+  deprecatedBy: 'deprecated_by',
+  dataFlowTo:   'data_flow',
+};
+
+export class Relations {
+  constructor(buckets = {}) {
+    /** @type {Object.<string, Array<{target:string, description:string}>>} */
+    this._b = {};
+    for (const k of RELATION_BUCKETS) {
+      // 同时尝试 snake_case 和 camelCase 的 key
+      const vals = buckets[k] || [];
+      this._b[k] = vals.map(r => ({
+        target:      r.target || '',
+        description: r.description || '',
+      }));
+    }
+    // 处理旧 camelCase key
+    for (const [legacy, canonical] of Object.entries(LEGACY_BUCKET_MAP)) {
+      if (buckets[legacy]?.length > 0) {
+        for (const r of buckets[legacy]) {
+          if (!this._b[canonical].some(x => x.target === r.target)) {
+            this._b[canonical].push({
+              target:      r.target || '',
+              description: r.description || '',
+            });
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * 从任意输入构造 Relations
+   * @param {Relations|Array|Object|null} input
+   * @returns {Relations}
+   */
+  static from(input) {
+    if (input instanceof Relations) return input;
+    if (!input) return new Relations();
+    // 扁平数组 → 自动分桶（兼容旧 Candidate relations）
+    if (Array.isArray(input)) return Relations.fromFlat(input);
+    return new Relations(input);
+  }
+
+  /**
+   * 从扁平数组 [{type, target, description}] 构建分桶
+   * @param {Array<{type:string, target:string, description?:string}>} arr
+   * @returns {Relations}
+   */
+  static fromFlat(arr) {
+    const buckets = {};
+    for (const rel of arr) {
+      const bucket = LEGACY_BUCKET_MAP[rel.type] || rel.type || 'related';
+      if (!buckets[bucket]) buckets[bucket] = [];
+      buckets[bucket].push({
+        target:      rel.target || '',
+        description: rel.description || '',
+      });
+    }
+    return new Relations(buckets);
+  }
+
+  /**
+   * 扁平视图（仅 Dashboard 渲染用）
+   * @returns {Array<{type:string, target:string, description:string}>}
+   */
+  toFlatArray() {
+    const result = [];
+    for (const [type, list] of Object.entries(this._b)) {
+      for (const r of list) {
+        result.push({ type, ...r });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 获取指定桶
+   * @param {string} type
+   * @returns {Array<{target:string, description:string}>}
+   */
+  getByType(type) {
+    return this._b[type] || [];
+  }
+
+  /**
+   * 是否为空
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return Object.values(this._b).every(l => l.length === 0);
+  }
+
+  /**
+   * 添加关系
+   * @param {string} type 桶名
+   * @param {string} target 目标
+   * @param {string} description
+   * @returns {Relations}
+   */
+  add(type, target, description = '') {
+    if (!this._b[type]) this._b[type] = [];
+    if (!this._b[type].some(r => r.target === target)) {
+      this._b[type].push({ target, description });
+    }
+    return this;
+  }
+
+  /**
+   * 移除关系
+   * @param {string} type 桶名
+   * @param {string} target 目标
+   * @returns {Relations}
+   */
+  remove(type, target) {
+    if (this._b[type]) {
+      this._b[type] = this._b[type].filter(r => r.target !== target);
+    }
+    return this;
+  }
+
+  /**
+   * 转换为 wire format JSON (分桶)
+   */
+  toJSON() {
+    return { ...this._b };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object|Array} data
+   * @returns {Relations}
+   */
+  static fromJSON(data) {
+    return Relations.from(data);
+  }
+}
+
+export default Relations;

package/lib/domain/knowledge/values/Stats.js

@@ -0,0 +1,87 @@
+/**
+ * Stats — 统计值对象
+ *
+ * 记录知识条目的使用统计：浏览、采用、应用、Guard 命中、搜索命中、权威分。
+ */
+export class Stats {
+  constructor(props = {}) {
+    /** @type {number} 浏览次数 */
+    this.views        = props.views        ?? 0;
+    /** @type {number} 采用次数 */
+    this.adoptions    = props.adoptions    ?? 0;
+    /** @type {number} 应用次数 */
+    this.applications = props.applications ?? 0;
+    /** @type {number} Guard 命中次数 */
+    this.guardHits    = props.guard_hits   ?? props.guardHits ?? 0;
+    /** @type {number} 搜索命中次数 */
+    this.searchHits   = props.search_hits  ?? props.searchHits ?? 0;
+    /** @type {number} 权威分 0-5 */
+    this.authority    = props.authority    ?? 0;
+  }
+
+  /**
+   * 从任意输入构造 Stats
+   * @param {Stats|Object|null} input
+   * @returns {Stats}
+   */
+  static from(input) {
+    if (input instanceof Stats) return input;
+    return new Stats(input || {});
+  }
+
+  /**
+   * 从旧 Recipe statistics 字段映射
+   * @param {Object} old
+   * @param {number} qualityOverall 用于初始化 authority
+   * @returns {Stats}
+   */
+  static fromLegacyRecipe(old, qualityOverall = 0) {
+    if (!old) return new Stats();
+    return new Stats({
+      views:        old.viewCount        ?? old.views        ?? 0,
+      adoptions:    old.adoptionCount    ?? old.adoptions    ?? 0,
+      applications: old.applicationCount ?? old.applications ?? 0,
+      guard_hits:   old.guardHitCount    ?? old.guardHits    ?? 0,
+      search_hits:  old.searchHits       ?? 0,
+      authority:    qualityOverall * 5,
+    });
+  }
+
+  /**
+   * 增加计数
+   * @param {'views'|'adoptions'|'applications'|'guardHits'|'searchHits'} counter
+   * @param {number} delta
+   * @returns {Stats}
+   */
+  increment(counter, delta = 1) {
+    if (counter in this && typeof this[counter] === 'number') {
+      this[counter] += delta;
+    }
+    return this;
+  }
+
+  /**
+   * 转换为 wire format JSON (snake_case)
+   */
+  toJSON() {
+    return {
+      views:        this.views,
+      adoptions:    this.adoptions,
+      applications: this.applications,
+      guard_hits:   this.guardHits,
+      search_hits:  this.searchHits,
+      authority:    this.authority,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Stats}
+   */
+  static fromJSON(data) {
+    return Stats.from(data);
+  }
+}
+
+export default Stats;

package/lib/domain/knowledge/values/index.js

@@ -0,0 +1,9 @@
+/**
+ * 值对象统一导出
+ */
+export { Content } from './Content.js';
+export { Relations, RELATION_BUCKETS } from './Relations.js';
+export { Constraints } from './Constraints.js';
+export { Reasoning } from './Reasoning.js';
+export { Quality } from './Quality.js';
+export { Stats } from './Stats.js';

package/lib/external/ai/AiProvider.js

@@ -174,6 +174,54 @@ export class AiProvider {
       ? `\n# Code Structure Analysis (AST)\nThe following is a Tree-sitter AST analysis of the project. Use this structural context to better understand class hierarchies, design patterns, and code quality when extracting recipes:\n\n${options.astContext.substring(0, 3000)}\n`
       : '';
 
+    // comprehensive 模式：全量分析整个文件，不跳过任何有意义的方法
+    if (options.comprehensive) {
+      return `# Role
+You are a ${langProfile.role} performing a **comprehensive full-file analysis**.
+
+# Goal
+Thoroughly analyze ALL code in "${targetName}" and create Recipe entries for **every significant method, function, or code block**.
+This is a full-file analysis — do NOT skip methods just because they seem "simple" or "standard".
+${skillSection}${astSection}
+
+# What to extract
+- **Every** complete method/function with 5+ lines of implementation
+- Initialization and configuration methods (init, viewDidLoad, setup, configure)
+- Event handlers and action methods
+- Data processing and business logic
+- Protocol/delegate implementations
+- ANY code block that a developer might reference, learn from, or reuse
+
+# Extraction Rules
+- Extract **BROADLY** — include all meaningful code units, not just "clever" or "novel" patterns
+- Each recipe must be a **complete, standalone** code unit with full signature and body
+- Preserve the file's actual code. Use \`<#placeholder#>\` ONLY for literal strings/values a developer would customize
+- Every recipe must be traceable to real code in the file. Do NOT invent code
+- Include relevant \`headers\` (import/require lines) that the code depends on
+- You **MUST** extract at least ONE recipe — every source file has something worth capturing
+
+${langProfile.extractionExamples}
+
+# Output (JSON Array)
+Each item:
+- title (string): Descriptive English name
+- summary_cn (string): Chinese description (2-3 sentences explaining what this code does)
+- summary_en (string): English description (2-3 sentences)
+- trigger (string): @shortcut
+- category: ${langProfile.categories}
+- language: "${langProfile.primaryLanguage}"
+- code (string): Complete function/method/class from the file
+- headers (string[]): Required import/require lines
+- tags (string[]): Search keywords
+- usageGuide_cn (string): "何时使用" + "关键要点" (2-3 lines)
+- usageGuide_en (string): "When to use" + "Key points" (2-3 lines)
+
+Return ONLY a JSON array. Do NOT return an empty array.
+
+Files Content:
+${files}`;
+    }
+
     return `# Role
 You are a ${langProfile.role} extracting production-quality reusable code patterns.