autosnippet 2.9.0 → 2.11.0

package/lib/service/cursor/CursorDeliveryPipeline.js

@@ -0,0 +1,279 @@
+/**
+ * CursorDeliveryPipeline — 4 通道交付主入口
+ *
+ * 读取知识库 → 筛选 + 分类 + 排序 + 压缩 → 写入 4 个 Cursor 通道
+ *
+ * 触发时机：
+ *   1. bootstrap 完成后自动触发
+ *   2. `asd cursor-rules` CLI 命令手动触发
+ *   3. Recipe 状态变更（pending → active）后触发
+ *   4. `asd upgrade` 时作为升级步骤执行
+ */
+
+import { KnowledgeCompressor } from './KnowledgeCompressor.js';
+import { TopicClassifier } from './TopicClassifier.js';
+import { RulesGenerator } from './RulesGenerator.js';
+import { SkillsSyncer } from './SkillsSyncer.js';
+import { estimateTokens, BUDGET } from './TokenBudget.js';
+import path from 'node:path';
+
+export class CursorDeliveryPipeline {
+  /**
+   * @param {Object} options
+   * @param {Object} options.knowledgeService - KnowledgeService 实例
+   * @param {string} options.projectRoot - 用户项目根目录
+   * @param {string} [options.projectName] - 项目名称
+   * @param {Object} [options.logger] - 日志器
+   */
+  constructor({ knowledgeService, projectRoot, projectName, logger }) {
+    this.knowledgeService = knowledgeService;
+    this.projectRoot = projectRoot;
+    this.projectName = projectName || this._inferProjectName(projectRoot);
+    this.logger = logger || console;
+
+    // 子模块
+    this.compressor = new KnowledgeCompressor();
+    this.topicClassifier = new TopicClassifier(this.projectName);
+    this.rulesGenerator = new RulesGenerator(projectRoot, this.projectName);
+    this.skillsSyncer = new SkillsSyncer(projectRoot, this.projectName, knowledgeService);
+  }
+
+  /**
+   * 完整交付流程 — 生成 4 通道 Cursor 消费物料
+   * @returns {Promise<{ channelA: Object, channelB: Object, channelC: Object, stats: Object }>}
+   */
+  async deliver() {
+    const startTime = Date.now();
+    const stats = {
+      channelA: { rulesCount: 0, tokensUsed: 0 },
+      channelB: { topicCount: 0, patternsCount: 0, totalTokens: 0 },
+      channelC: { synced: 0, skipped: 0, errors: 0 },
+      totalTokensUsed: 0,
+      duration: 0,
+    };
+
+    try {
+      // 1. 加载所有 active + pending 知识
+      const entries = await this._loadEntries();
+      this.logger.info?.(`[CursorDelivery] Loaded ${entries.length} knowledge entries`);
+
+      // 2. 分类：rules vs patterns vs facts
+      const { rules, patterns } = this._classify(entries);
+      this.logger.info?.(`[CursorDelivery] Classified: ${rules.length} rules, ${patterns.length} patterns`);
+
+      // 3. 清理旧的动态生成文件
+      this.rulesGenerator.cleanDynamicFiles();
+
+      // ── Channel A: Always-On Rules ──
+      const channelA = this._generateChannelA(rules);
+      stats.channelA = channelA;
+
+      // ── Channel B: Smart Rules (by topic) ──
+      const channelB = this._generateChannelB(patterns);
+      stats.channelB = channelB;
+
+      // ── Channel C: Skills Sync ──
+      const channelC = await this._generateChannelC();
+      stats.channelC = channelC;
+
+      // 统计
+      stats.totalTokensUsed = channelA.tokensUsed + channelB.totalTokens;
+      stats.duration = Date.now() - startTime;
+
+      this.logger.info?.(`[CursorDelivery] Done in ${stats.duration}ms — ` +
+        `A: ${channelA.rulesCount} rules (${channelA.tokensUsed} tokens), ` +
+        `B: ${channelB.topicCount} topics (${channelB.totalTokens} tokens), ` +
+        `C: ${channelC.synced} skills synced`);
+
+      return { channelA, channelB, channelC, stats };
+    } catch (error) {
+      this.logger.error?.(`[CursorDelivery] Error: ${error.message}`);
+      throw error;
+    }
+  }
+
+  // ─── 内部方法 ───────────────────────────────────────
+
+  /**
+   * 加载知识条目（active + high-confidence pending）
+   * @private
+   */
+  async _loadEntries() {
+    const allEntries = [];
+
+    // 加载 active
+    try {
+      const active = await this.knowledgeService.list(
+        { lifecycle: 'active' },
+        { page: 1, pageSize: 200 }
+      );
+      const activeItems = this._extractItems(active);
+      allEntries.push(...activeItems);
+    } catch (e) {
+      this.logger.warn?.(`[CursorDelivery] Failed to load active entries: ${e.message}`);
+    }
+
+    // 加载 pending（高置信度的也纳入）
+    try {
+      const pending = await this.knowledgeService.list(
+        { lifecycle: 'pending' },
+        { page: 1, pageSize: 200 }
+      );
+      const pendingItems = this._extractItems(pending);
+      // 过滤高置信度 pending（quality.confidence >= 0.7 或无 quality 字段）
+      const highConfPending = pendingItems.filter(e => {
+        const conf = e.quality?.confidence;
+        return conf === undefined || conf === null || conf >= 0.7;
+      });
+      allEntries.push(...highConfPending);
+    } catch (e) {
+      this.logger.warn?.(`[CursorDelivery] Failed to load pending entries: ${e.message}`);
+    }
+
+    return allEntries;
+  }
+
+  /**
+   * 从 KnowledgeService.list() 返回值提取条目数组
+   * @private
+   */
+  _extractItems(result) {
+    if (Array.isArray(result)) return result;
+    if (result?.items) return result.items;
+    if (result?.data) return result.data;
+    return [];
+  }
+
+  /**
+   * 按 kind 分类知识条目
+   * @private
+   */
+  _classify(entries) {
+    const rules = [], patterns = [], facts = [];
+    for (const entry of entries) {
+      if (entry.kind === 'rule') rules.push(entry);
+      else if (entry.kind === 'fact') facts.push(entry);
+      else patterns.push(entry);  // 无 kind 或 kind='pattern' → pattern
+    }
+    return { rules, patterns, facts };
+  }
+
+  /**
+   * 排序 — 质量分 + 统计使用量
+   * @private
+   */
+  _rank(entries) {
+    return [...entries].sort((a, b) => {
+      const scoreA = this._rankScore(a);
+      const scoreB = this._rankScore(b);
+      return scoreB - scoreA;
+    });
+  }
+
+  /**
+   * 计算排名分
+   * @private
+   */
+  _rankScore(entry) {
+    let score = 0;
+    score += (entry.quality?.confidence || 0.5) * 50;
+    score += (entry.quality?.authorityScore || 0) * 30;
+    score += Math.min(entry.stats?.useCount || 0, 10) * 2;
+    if (entry.lifecycle === 'active') score += 10;
+    return score;
+  }
+
+  /**
+   * Channel A 生成
+   * @private
+   */
+  _generateChannelA(rules) {
+    const topRules = this._rank(rules).slice(0, BUDGET.CHANNEL_A_MAX_RULES);
+    const ruleLines = this.compressor.compressToRuleLine(topRules);
+
+    if (ruleLines.length === 0) {
+      this.logger.info?.('[CursorDelivery] Channel A: No rules to generate');
+      return { rulesCount: 0, tokensUsed: 0, filePath: null };
+    }
+
+    const result = this.rulesGenerator.writeAlwaysOnRules(ruleLines);
+    this.logger.info?.(`[CursorDelivery] Channel A: ${result.rulesCount} rules → ${result.filePath}`);
+    return result;
+  }
+
+  /**
+   * Channel B 生成
+   * @private
+   */
+  _generateChannelB(patterns) {
+    const result = { topicCount: 0, patternsCount: 0, totalTokens: 0, topics: {} };
+
+    if (patterns.length === 0) {
+      this.logger.info?.('[CursorDelivery] Channel B: No patterns to generate');
+      return result;
+    }
+
+    // 按主题分组
+    const grouped = this.topicClassifier.group(patterns);
+
+    for (const [topic, topicPatterns] of Object.entries(grouped)) {
+      // 排序并取 Top N
+      const top = this._rank(topicPatterns).slice(0, BUDGET.CHANNEL_B_MAX_PATTERNS);
+
+      // 压缩为 When/Do/Don't
+      const compressed = this.compressor.compressToWhenDoDont(top);
+      if (compressed.length === 0) continue;
+
+      // 格式化为 Markdown
+      const body = this.compressor.formatWhenDoDont(compressed);
+
+      // 构建 description
+      const description = this.topicClassifier.buildDescription(topic, topicPatterns);
+
+      // 写入 .mdc
+      const writeResult = this.rulesGenerator.writeSmartRules(topic, body, description);
+
+      result.topicCount++;
+      result.patternsCount += compressed.length;
+      result.totalTokens += writeResult.tokensUsed;
+      result.topics[topic] = { patternsCount: compressed.length, tokensUsed: writeResult.tokensUsed };
+
+      this.logger.info?.(`[CursorDelivery] Channel B: ${topic} — ${compressed.length} patterns → ${writeResult.filePath}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Channel C 生成
+   * @private
+   */
+  async _generateChannelC() {
+    try {
+      const syncResult = await this.skillsSyncer.sync();
+      this.logger.info?.(
+        `[CursorDelivery] Channel C: ${syncResult.synced.length} synced, ` +
+        `${syncResult.skipped.length} skipped, ${syncResult.errors.length} errors`
+      );
+      return {
+        synced: syncResult.synced.length,
+        skipped: syncResult.skipped.length,
+        errors: syncResult.errors.length,
+        details: syncResult,
+      };
+    } catch (err) {
+      this.logger.error?.(`[CursorDelivery] Channel C error: ${err.message}`);
+      return { synced: 0, skipped: 0, errors: 1, details: { synced: [], skipped: [], errors: [err.message] } };
+    }
+  }
+
+  /**
+   * 从项目路径推断项目名称
+   * @private
+   */
+  _inferProjectName(projectRoot) {
+    return path.basename(projectRoot);
+  }
+}
+
+export default CursorDeliveryPipeline;

package/lib/service/cursor/KnowledgeCompressor.js

@@ -0,0 +1,87 @@
+/**
+ * KnowledgeCompressor — 知识条目压缩器（v2 无降级版）
+ *
+ * 将 KnowledgeEntry（含 AI 预计算字段）格式化为 Cursor 交付格式：
+ *   - Channel A: compressToRuleLine() → 一行式强制规则
+ *   - Channel B: compressToWhenDoDont() → When/Do/Don't + Template 格式
+ *
+ * 原则：只做格式化，无字段 = 不输出，不做启发式猜测。
+ */
+
+export class KnowledgeCompressor {
+
+  /**
+   * Channel A — 一行式规则
+   * @param {Array<Object>} entries - KnowledgeEntry 数组 (kind='rule')
+   * @returns {Array<string>}
+   */
+  compressToRuleLine(entries) {
+    return entries
+      .filter(e => e.doClause)                     // 无 doClause → 跳过，不猜
+      .map(e => {
+        let line = e.doClause;
+        if (e.dontClause) {
+          // AI 可能返回 "Don't ..." / "Do not ..." 开头，去掉冗余前缀
+          const stripped = e.dontClause.replace(/^(Don't|Do not|Never)\s+/i, '');
+          line += `. Do NOT ${stripped}`;
+        }
+        return `- ${line}.`;
+      });
+  }
+
+  /**
+   * Channel B — When/Do/Don't + Template
+   * @param {Array<Object>} entries - KnowledgeEntry 数组 (kind='pattern')
+   * @returns {Array<{ trigger: string, when: string, do: string, dont: string, template: string }>}
+   */
+  compressToWhenDoDont(entries) {
+    const seen = new Set();
+    return entries
+      .filter(e => e.trigger && e.whenClause && e.doClause)   // 缺任一 → 跳过
+      .map(e => {
+        let trigger = e.trigger.startsWith('@') ? e.trigger : `@${e.trigger}`;
+        // trigger 去重（AI 应保证唯一，但防御性检查）
+        if (seen.has(trigger)) {
+          let i = 2;
+          while (seen.has(`${trigger}-${i}`)) i++;
+          trigger = `${trigger}-${i}`;
+        }
+        seen.add(trigger);
+        return {
+          trigger,
+          when: e.whenClause,
+          do: e.doClause,
+          dont: e.dontClause || '',
+          template: e.coreCode || '',
+        };
+      });
+  }
+
+  /**
+   * 将 When/Do/Don't 结果格式化为 Markdown 字符串
+   * @param {Array<Object>} compressed - compressToWhenDoDont 输出
+   * @param {string} [language=''] - 代码围栏语言标识
+   * @returns {string}
+   */
+  formatWhenDoDont(compressed, language = '') {
+    const lang = language || '';
+    return compressed.map(item => {
+      const lines = [`### ${item.trigger}`];
+      lines.push(`- **When**: ${item.when}`);
+      lines.push(`- **Do**: ${item.do}`);
+      if (item.dont) {
+        const stripped = item.dont.replace(/^(Don't|Do not|Never)\s+/i, '');
+        lines.push(`- **Don't**: ${stripped}`);
+      }
+      if (item.template) {
+        lines.push('');
+        lines.push(`\`\`\`${lang}`);
+        lines.push(item.template);
+        lines.push('```');
+      }
+      return lines.join('\n');
+    }).join('\n\n');
+  }
+}
+
+export default KnowledgeCompressor;

package/lib/service/cursor/RulesGenerator.js

@@ -0,0 +1,168 @@
+/**
+ * RulesGenerator — .mdc 文件生成器
+ *
+ * 生成 Cursor Rules 格式的 .mdc 文件到 .cursor/rules/ 目录：
+ *   - Channel A: autosnippet-project-rules.mdc (alwaysApply: true)
+ *   - Channel B: autosnippet-patterns-{topic}.mdc (alwaysApply: false)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { estimateTokens, BUDGET } from './TokenBudget.js';
+
+export class RulesGenerator {
+  /**
+   * @param {string} projectRoot - 用户项目根目录
+   * @param {string} projectName - 项目名称（用于 description/标题）
+   */
+  constructor(projectRoot, projectName = 'Project') {
+    this.projectRoot = projectRoot;
+    this.projectName = projectName;
+    this.rulesDir = path.join(projectRoot, '.cursor', 'rules');
+  }
+
+  /**
+   * Channel A — 写入 Always-On Rules 文件
+   *
+   * @param {string[]} ruleLines - 一行式规则列表 (来自 KnowledgeCompressor.compressToRuleLine)
+   * @returns {{ filePath: string, tokensUsed: number, rulesCount: number }}
+   */
+  writeAlwaysOnRules(ruleLines) {
+    this._ensureDir();
+
+    // Token 预算控制
+    const kept = [];
+    let tokens = 0;
+    const headerFooterBudget = 100;
+    const ruleBudget = BUDGET.CHANNEL_A_MAX - headerFooterBudget;
+
+    for (const line of ruleLines) {
+      const lineTokens = estimateTokens(line);
+      if (tokens + lineTokens <= ruleBudget && kept.length < BUDGET.CHANNEL_A_MAX_RULES) {
+        kept.push(line);
+        tokens += lineTokens;
+      }
+    }
+
+    const content = this._renderChannelA(kept);
+    const filePath = path.join(this.rulesDir, 'autosnippet-project-rules.mdc');
+    fs.writeFileSync(filePath, content, 'utf8');
+
+    return {
+      filePath,
+      tokensUsed: estimateTokens(content),
+      rulesCount: kept.length,
+    };
+  }
+
+  /**
+   * Channel B — 写入 Smart Rules 文件（按主题）
+   *
+   * @param {string} topic - 主题名 (networking, ui, data, architecture, conventions, general)
+   * @param {string} compressedContent - 格式化后的 When/Do/Don't Markdown 内容
+   * @param {string} description - Agent 关联性判断用 description
+   * @returns {{ filePath: string, tokensUsed: number }}
+   */
+  writeSmartRules(topic, compressedContent, description) {
+    this._ensureDir();
+
+    // Token 预算控制
+    let body = compressedContent;
+    const totalTokens = estimateTokens(body) + estimateTokens(description) + 50;
+    if (totalTokens > BUDGET.CHANNEL_B_MAX_PER_FILE) {
+      // 截断尾部
+      const lines = body.split('\n');
+      const truncated = [];
+      let used = estimateTokens(description) + 50;
+      for (const line of lines) {
+        used += estimateTokens(line + '\n');
+        if (used <= BUDGET.CHANNEL_B_MAX_PER_FILE) {
+          truncated.push(line);
+        }
+      }
+      body = truncated.join('\n');
+    }
+
+    const content = this._renderChannelB(topic, body, description);
+    const fileName = `autosnippet-patterns-${topic}.mdc`;
+    const filePath = path.join(this.rulesDir, fileName);
+    fs.writeFileSync(filePath, content, 'utf8');
+
+    return {
+      filePath,
+      tokensUsed: estimateTokens(content),
+    };
+  }
+
+  /**
+   * 清理旧的动态生成文件
+   * 保留静态模板文件（autosnippet-conventions.mdc, autosnippet-skills.mdc）
+   */
+  cleanDynamicFiles() {
+    if (!fs.existsSync(this.rulesDir)) return;
+
+    const dynamicPrefixes = ['autosnippet-project-rules', 'autosnippet-patterns-'];
+    const files = fs.readdirSync(this.rulesDir);
+    for (const file of files) {
+      if (dynamicPrefixes.some(p => file.startsWith(p))) {
+        const filePath = path.join(this.rulesDir, file);
+        try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+      }
+    }
+  }
+
+  // ─── 渲染方法 ───────────────────────────────────────
+
+  /**
+   * @private
+   */
+  _renderChannelA(ruleLines) {
+    const desc = `${this.projectName} mandatory rules — coding constraints that must never be violated. Auto-generated by AutoSnippet.`;
+    const lines = [
+      '---',
+      `description: "${desc}"`,
+      'alwaysApply: true',
+      '---',
+      '',
+      `# ${this.projectName} — Mandatory Rules`,
+      '',
+      ...ruleLines,
+      '',
+      'For detailed patterns and recipes, AutoSnippet MCP tools are available:',
+      '- `autosnippet_search(query)` — search knowledge base',
+      '- `autosnippet_context_search(query)` — context-aware search with history',
+    ];
+    return lines.join('\n') + '\n';
+  }
+
+  /**
+   * @private
+   */
+  _renderChannelB(topic, body, description) {
+    const topicLabel = topic.charAt(0).toUpperCase() + topic.slice(1);
+    const lines = [
+      '---',
+      `description: "${description}"`,
+      'alwaysApply: false',
+      '---',
+      '',
+      `# ${topicLabel} Patterns`,
+      '',
+      body,
+      '',
+      `For full code examples: \`autosnippet_search("${topic}")\``,
+    ];
+    return lines.join('\n') + '\n';
+  }
+
+  /**
+   * @private
+   */
+  _ensureDir() {
+    if (!fs.existsSync(this.rulesDir)) {
+      fs.mkdirSync(this.rulesDir, { recursive: true });
+    }
+  }
+}
+
+export default RulesGenerator;