autosnippet 2.9.0 → 2.11.0

package/lib/service/cursor/SkillsSyncer.js

@@ -0,0 +1,268 @@
+/**
+ * SkillsSyncer — AutoSnippet Skills to .cursor/skills/ 同步器
+ *
+ * Channel C: 将 AutoSnippet/skills/ 下的项目级 SKILL.md 同步到
+ * .cursor/skills/autosnippet-{name}/ 目录，适配 Cursor Agent Skills 标准格式。
+ *
+ * 同时为每个 Skill 生成 references/RECIPES.md（相关 Recipe 摘要）。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 技能名称映射：AutoSnippet/skills/ → .cursor/skills/
+ * AutoSnippet/skills/ 下面是 bootstrap 动态生成的项目级 skills，
+ * 如 project-architecture/, project-code-standard/ 等。
+ */
+const SKILL_NAME_MAP = {
+  'project-architecture': 'autosnippet-architecture',
+  'project-code-standard': 'autosnippet-code-standard',
+  'project-profile': 'autosnippet-profile',
+  'project-agent-guidelines': 'autosnippet-guidelines',
+  'project-event-and-data-flow': 'autosnippet-data-flow',
+  'project-code-pattern': 'autosnippet-code-pattern',
+  'project-objc-deep-scan': 'autosnippet-objc-deep-scan',
+  'project-category-scan': 'autosnippet-category-scan',
+  'project-best-practice': 'autosnippet-best-practice',
+};
+
+/**
+ * 用途描述模板（英文，Cursor 优先）
+ */
+const SKILL_DESC_MAP = {
+  'autosnippet-architecture': 'Architecture patterns, module boundaries, and dependency rules for {project}. Use when creating new modules, reviewing architecture, or understanding dependencies.',
+  'autosnippet-code-standard': 'Coding standards and style conventions for {project}. Use when writing new code, reviewing formatting, or enforcing naming conventions.',
+  'autosnippet-profile': 'Project overview and profile for {project}. Use when needing background on the project, its tech stack, or structure.',
+  'autosnippet-guidelines': 'Agent interaction guidelines for {project}. Use when understanding how to work with this specific project.',
+  'autosnippet-data-flow': 'Event and data flow patterns for {project}. Use when working with events, state management, or data pipelines.',
+  'autosnippet-code-pattern': 'Common code patterns and idioms for {project}. Use when implementing features following project conventions.',
+  'autosnippet-objc-deep-scan': 'Objective-C deep scan results for {project}. Use when working with Objective-C code, method swizzling, or runtime features.',
+  'autosnippet-category-scan': 'Category and extension analysis for {project}. Use when working with categories or finding existing utility methods.',
+  'autosnippet-best-practice': 'Best practices and proven patterns for {project}. Use when making design decisions or code review.',
+};
+
+export class SkillsSyncer {
+  /**
+   * @param {string} projectRoot - 用户项目根目录
+   * @param {string} projectName - 项目名称
+   * @param {Object} [knowledgeService] - 可选，用于生成 references/RECIPES.md
+   */
+  constructor(projectRoot, projectName = 'Project', knowledgeService = null) {
+    this.projectRoot = projectRoot;
+    this.projectName = projectName;
+    this.knowledgeService = knowledgeService;
+    this.sourceDir = path.join(projectRoot, 'AutoSnippet', 'skills');
+    this.targetDir = path.join(projectRoot, '.cursor', 'skills');
+  }
+
+  /**
+   * 执行完整同步流程
+   * @returns {{ synced: string[], skipped: string[], errors: string[] }}
+   */
+  async sync() {
+    const result = { synced: [], skipped: [], errors: [] };
+
+    // 检查源目录是否存在
+    if (!fs.existsSync(this.sourceDir)) {
+      return result;
+    }
+
+    // 扫描源目录
+    const skillDirs = fs.readdirSync(this.sourceDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+
+    for (const dirName of skillDirs) {
+      try {
+        const sourceSkillPath = path.join(this.sourceDir, dirName, 'SKILL.md');
+        if (!fs.existsSync(sourceSkillPath)) {
+          result.skipped.push(dirName);
+          continue;
+        }
+
+        const targetName = SKILL_NAME_MAP[dirName] || `autosnippet-${dirName.replace(/^project-/, '')}`;
+        const targetSkillDir = path.join(this.targetDir, targetName);
+
+        // 创建目标目录
+        fs.mkdirSync(targetSkillDir, { recursive: true });
+
+        // 读取源 SKILL.md
+        const sourceContent = fs.readFileSync(sourceSkillPath, 'utf8');
+
+        // 转换格式
+        const targetContent = this._convertSkillMd(sourceContent, targetName, dirName);
+
+        // 写入目标 SKILL.md
+        fs.writeFileSync(path.join(targetSkillDir, 'SKILL.md'), targetContent, 'utf8');
+
+        // 生成 references/RECIPES.md
+        await this._generateRecipes(targetSkillDir, dirName);
+
+        result.synced.push(targetName);
+      } catch (err) {
+        result.errors.push(`${dirName}: ${err.message}`);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * 转换 SKILL.md 格式 — 从 AutoSnippet 格式到 Cursor Agent Skills 标准
+   * @private
+   */
+  _convertSkillMd(source, targetName, sourceDirName) {
+    // 提取原始内容（去掉 frontmatter）
+    const bodyMatch = source.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+    const body = bodyMatch ? bodyMatch[1].trim() : source.trim();
+
+    // 获取描述
+    const descTemplate = SKILL_DESC_MAP[targetName] || `Knowledge and patterns from {project}. Use when working with ${sourceDirName.replace(/^project-/, '')} related code.`;
+    const description = descTemplate.replace(/\{project\}/g, this.projectName);
+
+    // 构建 Cursor 标准格式
+    const dimensionLabel = sourceDirName.replace(/^project-/, '').replace(/-/g, ' ');
+    const lines = [
+      '---',
+      `name: ${targetName}`,
+      `description: "${description}"`,
+      '---',
+      '',
+      `# ${this._capitalizeWords(dimensionLabel)} — ${this.projectName}`,
+      '',
+      'Use this skill when:',
+      ...this._generateUseCases(sourceDirName),
+      '',
+      '## Instructions',
+      '',
+      body,
+      '',
+      '## Deeper Knowledge',
+      '',
+      `For detailed recipes and code examples:`,
+      `- \`autosnippet_search("${dimensionLabel}")\``,
+      '',
+      '## Referenced Files',
+      '',
+      'See `references/RECIPES.md` for related recipe summaries.',
+    ];
+    return lines.join('\n') + '\n';
+  }
+
+  /**
+   * 生成 references/RECIPES.md
+   * @private
+   */
+  async _generateRecipes(targetSkillDir, sourceDirName) {
+    const refsDir = path.join(targetSkillDir, 'references');
+    fs.mkdirSync(refsDir, { recursive: true });
+
+    // 如果有 knowledgeService，查询该维度的 recipes
+    let recipes = [];
+    if (this.knowledgeService) {
+      try {
+        const dimension = sourceDirName.replace(/^project-/, '');
+        const result = await this.knowledgeService.list(
+          { lifecycle: 'active', category: dimension },
+          { page: 1, pageSize: 50 }
+        );
+        recipes = result?.items || result?.data || [];
+        if (Array.isArray(result)) recipes = result;
+      } catch {
+        // 忽略查询错误
+      }
+    }
+
+    // 生成 RECIPES.md
+    const dimensionLabel = sourceDirName.replace(/^project-/, '').replace(/-/g, ' ');
+    const lines = [
+      `# ${this._capitalizeWords(dimensionLabel)} Recipes`,
+      '',
+    ];
+
+    if (recipes.length > 0) {
+      lines.push('| Title | Trigger | Summary |');
+      lines.push('|---|---|---|');
+      for (const entry of recipes.slice(0, 20)) {
+        const title = (entry.title || '').replace(/\|/g, '/');
+        const trigger = entry.trigger || '-';
+        const summary = (entry.summaryCn || entry.description || '').replace(/\|/g, '/').slice(0, 80);
+        lines.push(`| ${title} | ${trigger} | ${summary} |`);
+      }
+    } else {
+      lines.push('No recipes available yet. Run `asd bootstrap` to generate knowledge.');
+    }
+
+    lines.push('');
+    lines.push(`For full content, use: \`autosnippet_search("${dimensionLabel}")\``);
+
+    fs.writeFileSync(path.join(refsDir, 'RECIPES.md'), lines.join('\n') + '\n', 'utf8');
+  }
+
+  /**
+   * 生成使用场景列表
+   * @private
+   */
+  _generateUseCases(sourceDirName) {
+    const casesMap = {
+      'project-architecture': [
+        '- Creating new modules, services, or managers',
+        '- Reviewing architectural decisions',
+        '- Understanding module boundaries and dependency rules',
+      ],
+      'project-code-standard': [
+        '- Writing new code and need to follow coding standards',
+        '- Reviewing code formatting and naming conventions',
+        '- Setting up new files with proper structure',
+      ],
+      'project-profile': [
+        '- Need background on the project and tech stack',
+        '- Understanding the overall project structure',
+        '- Onboarding or getting project context',
+      ],
+      'project-agent-guidelines': [
+        '- Understanding project-specific workflow requirements',
+        '- Following project conventions for AI-assisted coding',
+      ],
+      'project-event-and-data-flow': [
+        '- Working with events, notifications, or callbacks',
+        '- Implementing data flow or state management',
+        '- Understanding how data moves through the system',
+      ],
+      'project-code-pattern': [
+        '- Implementing features using project conventions',
+        '- Looking for common code patterns and idioms',
+        '- Need a code template for a typical operation',
+      ],
+      'project-objc-deep-scan': [
+        '- Working with Objective-C runtime features',
+        '- Understanding method swizzling or hook registries',
+        '- Modifying sensitive Objective-C code',
+      ],
+      'project-category-scan': [
+        '- Looking for existing utility methods',
+        '- Working with categories or extensions',
+        '- Avoiding duplicate implementations',
+      ],
+      'project-best-practice': [
+        '- Making design decisions',
+        '- Code review and quality improvements',
+        '- Choosing between implementation approaches',
+      ],
+    };
+    return casesMap[sourceDirName] || [
+      '- Working with code related to this dimension',
+      '- Need guidance on project-specific patterns',
+    ];
+  }
+
+  /**
+   * @private
+   */
+  _capitalizeWords(str) {
+    return str.replace(/\b\w/g, c => c.toUpperCase());
+  }
+}
+
+export default SkillsSyncer;

package/lib/service/cursor/TokenBudget.js

@@ -0,0 +1,58 @@
+/**
+ * TokenBudget — Token 预算控制
+ *
+ * 简易 token 估算器（1 token ≈ 4 chars for English, 2 chars for CJK），
+ * 用于确保 .mdc 文件不超出 Cursor 上下文预算。
+ */
+
+/** 默认预算配置 */
+export const BUDGET = {
+  CHANNEL_A_MAX: 400,        // Always-On Rules 最大 token
+  CHANNEL_B_MAX_PER_FILE: 750, // Smart Rules 每个主题文件最大 token
+  CHANNEL_B_MAX_PATTERNS: 5, // Smart Rules 每个主题最多模式数
+  CHANNEL_A_MAX_RULES: 8,    // Always-On Rules 最多规则数
+};
+
+/**
+ * 估算文本 token 数
+ * 简易算法：英文按 4 chars/token，CJK 按 2 chars/token
+ * @param {string} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  if (!text) return 0;
+  let tokens = 0;
+  for (const ch of text) {
+    // CJK Unified Ideographs + common CJK ranges
+    if (ch.charCodeAt(0) > 0x2e80) {
+      tokens += 0.5; // ~2 chars per token for CJK
+    } else {
+      tokens += 0.25; // ~4 chars per token for English
+    }
+  }
+  return Math.ceil(tokens);
+}
+
+/**
+ * 按 token 预算截断内容行
+ * @param {string[]} lines - 内容行
+ * @param {number} budget - token 上限
+ * @returns {{ kept: string[], dropped: number, tokensUsed: number }}
+ */
+export function truncateToTokenBudget(lines, budget) {
+  const kept = [];
+  let tokensUsed = 0;
+  let dropped = 0;
+
+  for (const line of lines) {
+    const lineTokens = estimateTokens(line);
+    if (tokensUsed + lineTokens <= budget) {
+      kept.push(line);
+      tokensUsed += lineTokens;
+    } else {
+      dropped++;
+    }
+  }
+
+  return { kept, dropped, tokensUsed };
+}

package/lib/service/cursor/TopicClassifier.js

@@ -0,0 +1,141 @@
+/**
+ * TopicClassifier — 按主题分组 KnowledgeEntry
+ *
+ * 将 kind='pattern' 的知识条目按主题分组，用于 Channel B（Smart Rules）。
+ * 每个主题对应一个 .mdc 文件，设 alwaysApply: false + 丰富的 description。
+ */
+
+/**
+ * 主题定义
+ * - dimensions: 关联的 bootstrap 维度
+ * - keywords: 用于匹配 entry 分类的关键词
+ * - descriptionKeywords: 用于 .mdc description 字段的关键词（Agent 关联性判断依据）
+ */
+const TOPIC_MAP = {
+  networking: {
+    dimensions: ['event-and-data-flow'],
+    descriptionKeywords: 'network, HTTP, API, request, response, URL, fetch, socket, REST, download, upload, error handling, retry, timeout',
+  },
+  ui: {
+    dimensions: ['code-pattern'],
+    descriptionKeywords: 'view, controller, UI, layout, animation, cell, table, collection, button, scroll, navigation, auto layout, gesture, storyboard',
+  },
+  data: {
+    dimensions: ['code-pattern', 'architecture'],
+    descriptionKeywords: 'model, storage, database, cache, CoreData, Realm, SQLite, keychain, UserDefaults, JSON, parsing, serialization, persistence',
+  },
+  architecture: {
+    dimensions: ['architecture', 'best-practice'],
+    descriptionKeywords: 'singleton, delegate, factory, observer, protocol, manager, service, dependency injection, module, MVVM, MVC, coordinator, router, design pattern',
+  },
+  conventions: {
+    dimensions: ['code-standard'],
+    descriptionKeywords: 'naming, format, style, import, header, prefix, convention, documentation, file organization, constants, enum, typedef, pragma mark',
+  },
+};
+
+export class TopicClassifier {
+  /**
+   * @param {string} projectName - 项目名称
+   */
+  constructor(projectName = 'Project') {
+    this.projectName = projectName;
+  }
+
+  /**
+   * 将 patterns 按主题分组
+   * @param {Array<Object>} entries - KnowledgeEntry 数组 (kind='pattern')
+   * @returns {Object<string, Array<Object>>} { topic: [entries] }
+   */
+  group(entries) {
+    const grouped = {};
+    const unmatched = [];
+
+    for (const entry of entries) {
+      const topic = this._classifyEntry(entry);
+      if (topic) {
+        if (!grouped[topic]) grouped[topic] = [];
+        grouped[topic].push(entry);
+      } else {
+        unmatched.push(entry);
+      }
+    }
+
+    // 未匹配的归入 'general' — 但只在有内容时
+    if (unmatched.length > 0) {
+      grouped.general = unmatched;
+    }
+
+    return grouped;
+  }
+
+  /**
+   * 为主题构建 description — Agent 判断关联性的唯一依据
+   * @param {string} topic
+   * @param {Array<Object>} entries
+   * @returns {string}
+   */
+  buildDescription(topic, entries) {
+    const topicDef = TOPIC_MAP[topic];
+    const baseKeywords = topicDef
+      ? topicDef.descriptionKeywords
+      : entries.map(e => (e.title || '')).filter(Boolean).join(', ');
+
+    // 从 entries 提取额外关键词
+    const entryKeywords = entries
+      .map(e => this._extractKeywords(e))
+      .flat()
+      .filter(Boolean);
+    const unique = [...new Set(entryKeywords)].slice(0, 10);
+    const extra = unique.length > 0 ? `, ${unique.join(', ')}` : '';
+
+    return `${this._topicLabel(topic)} patterns for ${this.projectName} — ${baseKeywords}${extra}. Use when writing or reviewing ${this._topicLabel(topic).toLowerCase()}-related code.`;
+  }
+
+  /**
+   * 分类单个 entry 到主题 — 直读 AI 预计算的 topicHint
+   * @private
+   */
+  _classifyEntry(entry) {
+    return entry.topicHint || null;    // AI 没给 → null → 归入 general
+  }
+
+  /**
+   * 从 entry 提取关键词
+   * @private
+   */
+  _extractKeywords(entry) {
+    const text = (entry.title || '') + ' ' + (entry.description || '');
+    // 提取英文关键词（3+ 字母）
+    const words = text.match(/[a-zA-Z]{3,}/g) || [];
+    const filtered = words
+      .map(w => w.toLowerCase())
+      .filter(w => !STOP_WORDS.has(w));
+    return [...new Set(filtered)].slice(0, 5);
+  }
+
+  /**
+   * @private
+   */
+  _topicLabel(topic) {
+    const labels = {
+      networking: 'Networking',
+      ui: 'UI',
+      data: 'Data',
+      architecture: 'Architecture',
+      conventions: 'Conventions',
+      general: 'General',
+    };
+    return labels[topic] || topic.charAt(0).toUpperCase() + topic.slice(1);
+  }
+}
+
+/** @type {Set<string>} */
+const STOP_WORDS = new Set([
+  'the', 'and', 'for', 'this', 'that', 'with', 'from', 'use', 'using',
+  'when', 'not', 'all', 'are', 'has', 'have', 'been', 'will', 'can',
+  'should', 'must', 'may', 'each', 'which', 'their', 'your', 'its',
+  'project', 'code', 'file', 'class', 'method', 'function', 'bootstrap',
+]);
+
+export default TopicClassifier;

package/lib/service/guard/GuardCheckEngine.js

@@ -237,18 +237,24 @@ export class GuardCheckEngine {
   getRules(language = null) {
     let rules = [];
 
-    // 从数据库加载自定义规则（kind='rule' 的 Recipe，覆盖 code-standard/code-style/best-practice/boundary-constraint）
+    // 从数据库加载自定义规则
+    // 优先从 knowledge_entries 表查询（V3），回退到 recipes 表（V2）
     try {
       const now = Date.now();
       if (!this._customRulesCache || now - this._cacheTime > this._cacheTTL) {
-        const rows = this.db.prepare(
-          `SELECT id, title, description, language, scope, constraints_json
-           FROM recipes WHERE (kind = 'rule' OR knowledge_type = 'boundary-constraint') AND status = 'active'`
-        ).all();
+        let rows = [];
+        try {
+          rows = this.db.prepare(
+            `SELECT id, title, description, language, scope, constraints
+             FROM knowledge_entries
+             WHERE (kind = 'rule' OR knowledgeType = 'boundary-constraint')
+               AND lifecycle = 'active'`
+          ).all();
+        } catch { /* table may not exist */ }
         this._customRulesCache = rows.map(r => {
           let guards = [];
           try {
-            const constraints = JSON.parse(r.constraints_json || '{}');
+            const constraints = JSON.parse(r.constraints || '{}');
             guards = constraints.guards || [];
           } catch { /* ignore */ }
           // Each guard entry becomes a rule
@@ -267,7 +273,7 @@ export class GuardCheckEngine {
       }
       rules.push(...this._customRulesCache);
     } catch {
-      // recipes table or knowledge_type column may not exist
+      // table or column may not exist
     }
 
     // 合并内置规则（不覆盖同名数据库规则）
@@ -377,9 +383,16 @@ export class GuardCheckEngine {
         hitMap.set(v.ruleId, count + 1);
       }
 
-      const updateStmt = this.db.prepare(
-        `UPDATE recipes SET guard_hit_count = guard_hit_count + ?, updated_at = ? WHERE id = ?`
-      );
+      let updateStmt;
+      try {
+        updateStmt = this.db.prepare(
+          `UPDATE knowledge_entries
+           SET stats = json_set(COALESCE(stats, '{}'), '$.guardHits',
+                 COALESCE(json_extract(stats, '$.guardHits'), 0) + ?),
+               updatedAt = ?
+           WHERE id = ?`
+        );
+      } catch { /* table may not exist */ }
       const now = Math.floor(Date.now() / 1000);
 
       for (const [ruleId, count] of hitMap) {
@@ -464,6 +477,9 @@ export class GuardCheckEngine {
 
   /**
    * 批量文件审计
+   * @param {Array<{path: string, content: string}>} files
+   * @param {object} options - {scope: 'file'|'target'|'project'}
+   * @returns {{files, summary, crossFileViolations}}
    */
   auditFiles(files, options = {}) {
     const results = [];
@@ -477,8 +493,14 @@ export class GuardCheckEngine {
       totalErrors += result.summary.errors;
     }
 
+    // ── 跨文件检查 ──
+    const crossFileViolations = this._runCrossFileChecks(files);
+    totalViolations += crossFileViolations.length;
+    totalErrors += crossFileViolations.filter(v => v.severity === 'error').length;
+
     return {
       files: results,
+      crossFileViolations,
       summary: {
         filesChecked: results.length,
         totalViolations,
@@ -488,6 +510,73 @@ export class GuardCheckEngine {
     };
   }
 
+  /**
+   * 跨文件检查 — 需要多文件上下文才能发现的问题
+   * @param {Array<{path: string, content: string}>} files
+   * @returns {Array<{ruleId, message, severity, locations}>}
+   */
+  _runCrossFileChecks(files) {
+    const violations = [];
+
+    // ── ObjC Category 跨文件重名检查 ──
+    // 收集所有文件中的 @interface ClassName(CategoryName) 声明
+    const categoryMap = new Map(); // key: "ClassName(CategoryName)" → [{filePath, line, snippet}]
+    const categoryRegex = /@interface\s+(\w+)\s*\(\s*(\w+)\s*\)/g;
+
+    for (const { path: filePath, content } of files) {
+      const ext = filePath.split('.').pop()?.toLowerCase();
+      if (ext !== 'm' && ext !== 'mm' && ext !== 'h') continue;
+
+      const lines = content.split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        categoryRegex.lastIndex = 0;
+        let m;
+        while ((m = categoryRegex.exec(lines[i])) !== null) {
+          const key = `${m[1]}(${m[2]})`;
+          if (!categoryMap.has(key)) categoryMap.set(key, []);
+          categoryMap.get(key).push({
+            filePath,
+            line: i + 1,
+            snippet: lines[i].trim().slice(0, 120),
+          });
+        }
+      }
+    }
+
+    // .h 和 .m 成对出现是正常的（声明 + 实现），只有同类型文件重名才是问题
+    // 或者超过 2 处声明就一定有问题
+    for (const [key, locations] of categoryMap) {
+      if (locations.length <= 1) continue;
+
+      // 按文件扩展名分组: .h 和 .m/.mm 各一个是合法的
+      const hFiles = locations.filter(l => l.filePath.endsWith('.h'));
+      const mFiles = locations.filter(l => !l.filePath.endsWith('.h'));
+
+      // 同类型文件中有多个声明 → 重名冲突
+      const hasDuplicateH = hFiles.length > 1;
+      const hasDuplicateM = mFiles.length > 1;
+      // 超过 2 处总声明（如 3 个文件都声明了同一个 Category）→ 一定有问题
+      const tooMany = locations.length > 2;
+
+      if (hasDuplicateH || hasDuplicateM || tooMany) {
+        // 收集冲突的那些位置
+        const conflictLocations = tooMany ? locations
+          : hasDuplicateH && hasDuplicateM ? locations
+          : hasDuplicateH ? hFiles
+          : mFiles;
+
+        violations.push({
+          ruleId: 'objc-cross-file-duplicate-category',
+          message: `Category ${key} 在 ${conflictLocations.length} 个文件中重复声明，可能导致方法覆盖或未定义行为`,
+          severity: 'warning',
+          locations: conflictLocations,
+        });
+      }
+    }
+
+    return violations;
+  }
+
   /**
    * 清除规则缓存
    */