autosnippet 2.0.2 → 2.4.0

package/lib/service/chat/tools.js

@@ -1,7 +1,7 @@
 /**
  * tools.js — ChatAgent 全部工具定义
  *
- * 33 个工具覆盖项目全部 AI 能力:
+ * 37 个工具覆盖项目全部 AI 能力:
  *
  * ┌─── 查询类 (8) ─────────────────────────────────┐
  * │  1. search_recipes       搜索 Recipe            │
@@ -53,6 +53,11 @@
  * │ 32. load_skill            加载 Agent Skill 文档   │
  * │ 33. bootstrap_knowledge   冷启动知识库初始化      │
  * └─────────────────────────────────────────────────────┘
+ * ┌─── 组合工具 (3) ───────────────────────────────────┐
+ * │ 34. analyze_code          Guard + Recipe 搜索      │
+ * │ 35. knowledge_overview    全局知识库概览           │
+ * │ 36. submit_with_check     查重 + 提交              │
+ * └─────────────────────────────────────────────────────┘
  */
 
 import fs from 'node:fs';
@@ -63,8 +68,11 @@ import Logger from '../../infrastructure/logging/Logger.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const PROJECT_ROOT = path.resolve(__dirname, '../../..');
 /** skills/ 目录绝对路径 */
-const SKILLS_DIR = path.resolve(__dirname, '../../../skills');
+const SKILLS_DIR = path.resolve(PROJECT_ROOT, 'skills');
+/** 项目级 skills 目录 */
+const PROJECT_SKILLS_DIR = path.resolve(PROJECT_ROOT, '.autosnippet', 'skills');
 
 // ────────────────────────────────────────────────────────────
 // 1. search_recipes
@@ -206,7 +214,24 @@ const searchKnowledge = {
       const searchEngine = ctx.container.get('searchEngine');
       const results = await searchEngine.search(query, { limit: topK });
       if (results && results.length > 0) {
-        return { source: 'searchEngine', results: results.slice(0, topK) };
+        const enriched = results.slice(0, topK).map((r, i) => ({
+          ...r,
+          reasoning: {
+            whyRelevant: r.score != null
+              ? `匹配分 ${(r.score * 100).toFixed(0)}%` + (r.matchType ? ` (${r.matchType})` : '')
+              : '语义相关',
+            rank: i + 1,
+          },
+        }));
+        const topScore = enriched[0]?.score ?? 0;
+        return {
+          source: 'searchEngine',
+          results: enriched,
+          _meta: {
+            confidence: topScore > 0.7 ? 'high' : topScore > 0.3 ? 'medium' : 'low',
+            hint: topScore < 0.3 ? '匹配度较低，结果可能不够相关。建议尝试更具体的查询词。' : null,
+          },
+        };
       }
     } catch { /* SearchEngine not available */ }
 
@@ -233,7 +258,7 @@ const searchKnowledge = {
       }
     } catch { /* RetrievalFunnel not available */ }
 
-    return { source: 'none', results: [], message: 'No search engine available' };
+    return { source: 'none', results: [], message: 'No search engine available', _meta: { confidence: 'none', hint: '搜索引擎不可用。请确认向量索引已构建（rebuild_index）。' } };
   },
 };
 
@@ -464,6 +489,13 @@ const checkDuplicate = {
       similar,
       hasDuplicate: similar.some(s => s.similarity >= 0.7),
       highestSimilarity: similar.length > 0 ? similar[0].similarity : 0,
+      _meta: {
+        confidence: similar.length === 0 ? 'none'
+          : similar[0].similarity >= 0.7 ? 'high' : 'low',
+        hint: similar.length === 0 ? '未发现相似 Recipe，可放心提交。'
+          : similar[0].similarity >= 0.7 ? '发现高度相似 Recipe，建议人工审核是否重复。'
+          : '有低相似度匹配，大概率不是重复。',
+      },
     };
   },
 };
@@ -696,6 +728,7 @@ const guardCheckCode = {
     try {
       const engine = ctx.container.get('guardCheckEngine');
       const violations = engine.checkCode(code, language || 'unknown', { scope });
+      // reasoning 已由 GuardCheckEngine.checkCode() 内置附加
       return { violationCount: violations.length, violations };
     } catch { /* not available */ }
 
@@ -1116,15 +1149,19 @@ const loadSkill = {
     required: ['skillName'],
   },
   handler: async (params) => {
-    const skillPath = path.join(SKILLS_DIR, params.skillName, 'SKILL.md');
+    // 项目级 Skills 优先（覆盖同名内置 Skill）
+    const projectSkillPath = path.join(PROJECT_SKILLS_DIR, params.skillName, 'SKILL.md');
+    const builtinSkillPath = path.join(SKILLS_DIR, params.skillName, 'SKILL.md');
+    const skillPath = fs.existsSync(projectSkillPath) ? projectSkillPath : builtinSkillPath;
     try {
       const content = fs.readFileSync(skillPath, 'utf8');
-      return { skillName: params.skillName, content };
+      const source = skillPath === projectSkillPath ? 'project' : 'builtin';
+      return { skillName: params.skillName, source, content };
     } catch {
-      const available = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
-        .filter(d => d.isDirectory())
-        .map(d => d.name);
-      return { error: `Skill "${params.skillName}" not found`, availableSkills: available };
+      const available = new Set();
+      try { fs.readdirSync(SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory()).forEach(d => available.add(d.name)); } catch {}
+      try { fs.readdirSync(PROJECT_SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory()).forEach(d => available.add(d.name)); } catch {}
+      return { error: `Skill "${params.skillName}" not found`, availableSkills: [...available] };
     }
   },
 };
@@ -1166,6 +1203,199 @@ const bootstrapKnowledgeTool = {
 // 导出全部工具
 // ────────────────────────────────────────────────────────────
 
+// ────────────────────────────────────────────────────────────
+// 34. analyze_code — 组合工具 (Guard + Recipe 搜索)
+// ────────────────────────────────────────────────────────────
+const analyzeCode = {
+  name: 'analyze_code',
+  description: '综合分析一段代码：Guard 规范检查 + 相关 Recipe 搜索。一次调用完成完整分析，减少多轮工具调用。',
+  parameters: {
+    type: 'object',
+    properties: {
+      code:     { type: 'string', description: '待分析的源码' },
+      language: { type: 'string', description: '编程语言 (swift/objc/javascript 等)' },
+      filePath: { type: 'string', description: '文件路径（可选，用于上下文）' },
+    },
+    required: ['code'],
+  },
+  handler: async (params, ctx) => {
+    const { code, language, filePath } = params;
+    const results = {};
+
+    // 并行执行 Guard 检查 + Recipe 搜索
+    const [guardResult, searchResult] = await Promise.all([
+      (async () => {
+        try {
+          const engine = ctx.container.get('guardCheckEngine');
+          const violations = engine.checkCode(code, language || 'unknown', { scope: 'file' });
+          return { violationCount: violations.length, violations };
+        } catch {
+          try {
+            const guardService = ctx.container.get('guardService');
+            const matches = await guardService.checkCode(code, { language });
+            return { violationCount: matches.length, violations: matches };
+          } catch { return { violationCount: 0, violations: [] }; }
+        }
+      })(),
+      (async () => {
+        try {
+          const searchEngine = ctx.container.get('searchEngine');
+          // 取代码首段作为搜索词
+          const query = code.substring(0, 200).replace(/\n/g, ' ');
+          const rawResults = await searchEngine.search(query, { limit: 5 });
+          return { results: rawResults || [], total: rawResults?.length || 0 };
+        } catch { return { results: [], total: 0 }; }
+      })(),
+    ]);
+
+    results.guard = guardResult;
+    results.relatedRecipes = searchResult;
+    results.filePath = filePath || '(inline)';
+
+    const hasFindings = guardResult.violationCount > 0 || searchResult.total > 0;
+    results._meta = {
+      confidence: hasFindings ? 'high' : 'low',
+      hint: hasFindings
+        ? `已完成 Guard 检查（${guardResult.violationCount} 个违规）+ Recipe 搜索（${searchResult.total} 条匹配）。`
+        : '未发现 Guard 违规，也未找到相关 Recipe。可能需要先冷启动知识库。',
+    };
+
+    return results;
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+// 35. knowledge_overview — 组合工具 (一次获取全部类型的 Recipe 统计)
+// ────────────────────────────────────────────────────────────
+const knowledgeOverview = {
+  name: 'knowledge_overview',
+  description: '一次性获取知识库全貌：各类型 Recipe 分布 + 候选状态 + 知识图谱概况 + 质量概览。比分别调用 get_project_stats + search_recipes 更高效。',
+  parameters: {
+    type: 'object',
+    properties: {
+      includeTopRecipes: { type: 'boolean', description: '是否包含热门 Recipe 列表，默认 true' },
+      limit: { type: 'number', description: '每类返回数量，默认 5' },
+    },
+  },
+  handler: async (params, ctx) => {
+    const { includeTopRecipes = true, limit = 5 } = params;
+    const result = {};
+
+    // 并行获取统计 + 可选的热门列表
+    const [statsResult, feedbackResult] = await Promise.all([
+      (async () => {
+        try {
+          const recipeService = ctx.container.get('recipeService');
+          const candidateService = ctx.container.get('candidateService');
+          const [rs, cs] = await Promise.all([
+            recipeService.getRecipeStats(),
+            candidateService.getCandidateStats(),
+          ]);
+          return { recipes: rs, candidates: cs };
+        } catch { return null; }
+      })(),
+      (async () => {
+        if (!includeTopRecipes) return null;
+        try {
+          const feedbackCollector = ctx.container.get('feedbackCollector');
+          return feedbackCollector.getTopRecipes(limit);
+        } catch { return null; }
+      })(),
+    ]);
+
+    if (statsResult) {
+      result.recipes = statsResult.recipes;
+      result.candidates = statsResult.candidates;
+    }
+
+    // 知识图谱统计
+    try {
+      const kgService = ctx.container.get('knowledgeGraphService');
+      result.knowledgeGraph = kgService.getStats();
+    } catch { /* KG not available */ }
+
+    if (feedbackResult) result.topRecipes = feedbackResult;
+
+    const recipeCount = result.recipes?.total || result.recipes?.count || 0;
+    result._meta = {
+      confidence: recipeCount > 0 ? 'high' : 'none',
+      hint: recipeCount === 0 ? '知识库为空，建议先执行冷启动（bootstrap_knowledge）。' : null,
+    };
+
+    return result;
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+// 36. submit_with_check — 组合工具 (查重 + 提交)
+// ────────────────────────────────────────────────────────────
+const submitWithCheck = {
+  name: 'submit_with_check',
+  description: '安全提交候选：先执行查重检测，无重复则自动提交。如果发现高度相似 Recipe 则阻止并返回相似列表。一次调用完成 check_duplicate + submit_candidate。',
+  parameters: {
+    type: 'object',
+    properties: {
+      code:     { type: 'string', description: '代码内容' },
+      language: { type: 'string', description: '编程语言' },
+      category: { type: 'string', description: '分类 (View/Service/Tool/Model 等)' },
+      title:    { type: 'string', description: '候选标题' },
+      summary:  { type: 'string', description: '摘要' },
+      threshold: { type: 'number', description: '相似度阈值，默认 0.7' },
+    },
+    required: ['code', 'language', 'category'],
+  },
+  handler: async (params, ctx) => {
+    const { code, language, category, title, summary, threshold = 0.7 } = params;
+    const projectRoot = ctx.projectRoot;
+
+    // Step 1: 查重
+    const cand = { title: title || '', summary: summary || '', code };
+    const similar = findSimilarRecipes(projectRoot, cand, { threshold: 0.5, topK: 5 });
+    const hasDuplicate = similar.some(s => s.similarity >= threshold);
+
+    if (hasDuplicate) {
+      return {
+        submitted: false,
+        reason: 'duplicate_blocked',
+        similar,
+        highestSimilarity: similar[0]?.similarity || 0,
+        _meta: {
+          confidence: 'high',
+          hint: `发现高度相似 Recipe（相似度 ${(similar[0]?.similarity * 100).toFixed(0)}%），已阻止提交。请人工审核。`,
+        },
+      };
+    }
+
+    // Step 2: 提交
+    try {
+      const candidateService = ctx.container.get('candidateService');
+      const item = {
+        code,
+        language,
+        category,
+        title: title || '',
+        summary_cn: summary || '',
+        reasoning: { whyStandard: 'Submitted via submit_with_check', sources: ['agent'], confidence: 0.7 },
+      };
+      const created = await candidateService.createFromToolParams(item, 'agent', {}, { userId: 'agent' });
+
+      return {
+        submitted: true,
+        candidate: created,
+        similar: similar.length > 0 ? similar : [],
+        _meta: {
+          confidence: 'high',
+          hint: similar.length > 0
+            ? `已提交，但有 ${similar.length} 个低相似度匹配，大概率不是重复。`
+            : '已提交，无重复风险。',
+        },
+      };
+    } catch (err) {
+      return { submitted: false, reason: 'submit_error', error: err.message };
+    }
+  },
+};
+
 export const ALL_TOOLS = [
   // 查询类 (8)
   searchRecipes,
@@ -1209,6 +1439,10 @@ export const ALL_TOOLS = [
   // Skills & Bootstrap (2)
   loadSkill,
   bootstrapKnowledgeTool,
+  // 组合工具 (3) — 减少 ReAct 轮次
+  analyzeCode,
+  knowledgeOverview,
+  submitWithCheck,
 ];
 
 export default ALL_TOOLS;

package/lib/service/guard/GuardCheckEngine.js

@@ -351,7 +351,15 @@ export class GuardCheckEngine {
     // 跟踪 Guard 命中次数（回写 Recipe 统计）
     this.trackGuardHits(violations);
 
-    return violations;
+    // ── Reasoning Enrichment: 推理信息跟随数据流动 ──
+    return violations.map(v => ({
+      ...v,
+      reasoning: {
+        whatViolated: v.ruleId,
+        whyItMatters: v.message,
+        suggestedFix: v.suggestedFix || null,
+      },
+    }));
   }
 
   /**

package/lib/service/knowledge/KnowledgeGraphService.js

@@ -145,15 +145,19 @@ export class KnowledgeGraphService {
   /**
    * 获取图谱整体统计
    */
-  getStats() {
-    const edgeCount = this.db.prepare(`SELECT COUNT(*) as total FROM knowledge_edges`).get();
+  /**
+   * @param {string} [nodeType] 过滤节点类型（如 'recipe'），为空则返回全部
+   */
+  getStats(nodeType) {
+    const typeFilter = nodeType ? ` WHERE from_type = '${nodeType}' AND to_type = '${nodeType}'` : '';
+    const edgeCount = this.db.prepare(`SELECT COUNT(*) as total FROM knowledge_edges${typeFilter}`).get();
     const byRelation = this.db.prepare(
-      `SELECT relation, COUNT(*) as count FROM knowledge_edges GROUP BY relation`
+      `SELECT relation, COUNT(*) as count FROM knowledge_edges${typeFilter} GROUP BY relation`
     ).all();
     const byType = this.db.prepare(
-      `SELECT from_type as type, COUNT(DISTINCT from_id) as count FROM knowledge_edges GROUP BY from_type
+      `SELECT from_type as type, COUNT(DISTINCT from_id) as count FROM knowledge_edges${typeFilter} GROUP BY from_type
        UNION
-       SELECT to_type as type, COUNT(DISTINCT to_id) as count FROM knowledge_edges GROUP BY to_type`
+       SELECT to_type as type, COUNT(DISTINCT to_id) as count FROM knowledge_edges${typeFilter} GROUP BY to_type`
     ).all();
 
     return {
@@ -166,11 +170,18 @@ export class KnowledgeGraphService {
   /**
    * 获取全量边（供 Dashboard 图谱可视化）
    * @param {number} [limit=500] 最大返回条数
+   * @param {string} [nodeType] 过滤节点类型（如 'recipe'），为空则返回全部
    */
-  getAllEdges(limit = 500) {
-    const rows = this.db.prepare(
-      `SELECT * FROM knowledge_edges ORDER BY updated_at DESC LIMIT ?`
-    ).all(limit);
+  getAllEdges(limit = 500, nodeType) {
+    let sql, params;
+    if (nodeType) {
+      sql = `SELECT * FROM knowledge_edges WHERE from_type = ? AND to_type = ? ORDER BY updated_at DESC LIMIT ?`;
+      params = [nodeType, nodeType, limit];
+    } else {
+      sql = `SELECT * FROM knowledge_edges ORDER BY updated_at DESC LIMIT ?`;
+      params = [limit];
+    }
+    const rows = this.db.prepare(sql).all(...params);
     return rows.map(this._mapEdge);
   }
 

package/lib/service/recipe/RecipeService.js

@@ -27,6 +27,7 @@ export class RecipeService {
     this.gateway = gateway;
     this._knowledgeGraphService = knowledgeGraphService || null;
     this._fileWriter = options.fileWriter || null;
+    this._skillHooks = options.skillHooks || null;
     this.logger = Logger.getInstance();
   }
 
@@ -110,6 +111,13 @@ export class RecipeService {
         title: created.title,
       });
 
+      // ── SkillHooks: onRecipeCreated (fire-and-forget) ──
+      if (this._skillHooks) {
+        this._skillHooks.run('onRecipeCreated', created, {
+          userId: context.userId,
+        }).catch(err => this.logger.warn('SkillHook onRecipeCreated error', { error: err.message }));
+      }
+
       return created;
     } catch (error) {
       this.logger.error('Error creating recipe', {

package/lib/service/skills/SkillHooks.js

@@ -0,0 +1,126 @@
+/**
+ * SkillHooks — Skill 生命周期钩子管理器
+ *
+ * 每个 Skill 目录可以包含一个 hooks.js 文件，导出生命周期回调。
+ * SkillHooks 在启动时扫描并注册所有钩子，在特定事件发生时按序调用。
+ *
+ * 支持的钩子:
+ *   - onCandidateSubmit(candidate, ctx) → { block?: boolean, reason?: string }
+ *   - onRecipeCreated(recipe, ctx) → void
+ *   - onGuardCheck(violation, ctx) → violation (可修改)
+ *   - onBootstrapComplete(stats, ctx) → void
+ *
+ * 加载顺序: 内置 skills/ → 项目级 .autosnippet/skills/（同名覆盖）
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Logger from '../../infrastructure/logging/Logger.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, '../../..');
+const SKILLS_DIR = path.resolve(PROJECT_ROOT, 'skills');
+const PROJECT_SKILLS_DIR = path.resolve(PROJECT_ROOT, '.autosnippet', 'skills');
+
+const HOOK_NAMES = [
+  'onCandidateSubmit',
+  'onRecipeCreated',
+  'onGuardCheck',
+  'onBootstrapComplete',
+];
+
+export class SkillHooks {
+  constructor() {
+    this.logger = Logger.getInstance();
+    /** @type {Map<string, Function[]>} hookName → [handler, ...] */
+    this.hooks = new Map(HOOK_NAMES.map(n => [n, []]));
+  }
+
+  /**
+   * 扫描 skills 目录，加载所有 hooks.js
+   * 项目级 hooks 覆盖同名内置 hooks
+   */
+  async load() {
+    const loaded = new Map(); // skillName → hooks module
+
+    // 1. 内置 skills
+    await this.#loadFromDir(SKILLS_DIR, loaded);
+
+    // 2. 项目级 skills（覆盖同名）
+    await this.#loadFromDir(PROJECT_SKILLS_DIR, loaded);
+
+    // 3. 注册所有钩子
+    for (const [skillName, mod] of loaded) {
+      for (const hookName of HOOK_NAMES) {
+        if (typeof mod[hookName] === 'function') {
+          this.hooks.get(hookName).push(mod[hookName]);
+          this.logger.debug(`SkillHook registered: ${skillName}.${hookName}`);
+        }
+      }
+    }
+
+    const totalHooks = [...this.hooks.values()].reduce((s, a) => s + a.length, 0);
+    if (totalHooks > 0) {
+      this.logger.info(`SkillHooks: loaded ${totalHooks} hooks from ${loaded.size} skills`);
+    }
+  }
+
+  /**
+   * 触发钩子 — 按注册顺序调用
+   *
+   * @param {string} hookName
+   * @param  {...any} args
+   * @returns {Promise<any>} 最后一个返回值（用于 blocking hooks 如 onCandidateSubmit）
+   */
+  async run(hookName, ...args) {
+    const handlers = this.hooks.get(hookName);
+    if (!handlers || handlers.length === 0) return undefined;
+
+    let result;
+    for (const handler of handlers) {
+      try {
+        result = await handler(...args);
+        // 如果是 blocking hook 且返回 block=true，立即中断
+        if (result?.block) return result;
+      } catch (err) {
+        this.logger.warn(`SkillHook error in ${hookName}`, { error: err.message });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 检查是否有任何钩子注册
+   */
+  has(hookName) {
+    const handlers = this.hooks.get(hookName);
+    return handlers && handlers.length > 0;
+  }
+
+  // ─── Internal ──────────────────────────────────────────
+
+  async #loadFromDir(dir, loaded) {
+    let dirs;
+    try {
+      dirs = fs.readdirSync(dir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name);
+    } catch {
+      return; // 目录不存在
+    }
+
+    for (const name of dirs) {
+      const hooksPath = path.join(dir, name, 'hooks.js');
+      if (!fs.existsSync(hooksPath)) continue;
+      try {
+        const mod = await import(hooksPath);
+        loaded.set(name, mod.default || mod);
+      } catch (err) {
+        this.logger.warn(`SkillHooks: failed to load ${name}/hooks.js`, { error: err.message });
+      }
+    }
+  }
+}
+
+export default SkillHooks;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosnippet",
-  "version": "2.0.2",
+  "version": "2.4.0",
   "description": "AutoSnippet - 连接开发者、AI 与项目知识库的工具",
   "type": "module",
   "main": "lib/bootstrap.js",

package/scripts/init-db.js

@@ -25,14 +25,13 @@ async function main() {
     console.log('  - Gateway:', components.gateway ? '✓' : '✗');
     console.log('  - Permission Manager:', components.permissionManager ? '✓' : '✗');
     console.log('  - Audit Logger:', components.auditLogger ? '✓' : '✗');
-    console.log('  - Session Manager:', components.sessionManager ? '✓' : '✗');
 
     // 显示宪法信息
     const constitutionInfo = components.constitution.toJSON();
     console.log('\n📜 Constitution:');
     console.log('  - Version:', constitutionInfo.version);
     console.log('  - Effective Date:', constitutionInfo.effectiveDate);
-    console.log('  - Priorities:', constitutionInfo.priorities.length);
+    console.log('  - Rules:', (constitutionInfo.rules || []).length);
     console.log('  - Roles:', constitutionInfo.roles.length);
 
     await bootstrap.shutdown();