autosnippet 3.2.10 → 3.2.11

package/lib/service/agent/tools/knowledge-graph.js

@@ -1,112 +0,0 @@
-/**
- * knowledge-graph.js — 知识图谱类工具 (2)
- *
- * 10. check_duplicate     候选查重
- * 12. add_graph_edge      手动添加图谱边
- *
- * 注意: discover_relations 已删除。
- * 关系发现由 Agent LLM 直接推理完成，利用通用工具（search_knowledge, query_code_graph 等）。
- */
-
-import { findSimilarRecipes } from '../../candidate/SimilarityService.js';
-
-// ────────────────────────────────────────────────────────────
-// 10. check_duplicate
-// ────────────────────────────────────────────────────────────
-export const checkDuplicate = {
-  name: 'check_duplicate',
-  description:
-    '候选查重 — 检测候选代码是否与已有 Recipe 重复（基于标题/摘要/代码的 Jaccard 相似度）。',
-  parameters: {
-    type: 'object',
-    properties: {
-      candidate: { type: 'object', description: '候选对象 { title, summary, code, usageGuide }' },
-      candidateId: { type: 'string', description: '或提供候选 ID，从数据库读取' },
-      projectRoot: { type: 'string', description: '项目根目录（可选，默认当前项目）' },
-      threshold: { type: 'number', description: '相似度阈值，默认 0.5' },
-    },
-  },
-  handler: async (params, ctx) => {
-    let cand = params.candidate;
-    const projectRoot = params.projectRoot || ctx.projectRoot;
-    const threshold = params.threshold ?? 0.5;
-
-    // 如果提供 candidateId，从数据库读取条目信息
-    if (!cand && params.candidateId) {
-      try {
-        const knowledgeService = ctx.container.get('knowledgeService');
-        const found = await knowledgeService.get(params.candidateId);
-        if (found) {
-          const json = typeof found.toJSON === 'function' ? found.toJSON() : found;
-          cand = {
-            title: json.title || '',
-            summary: json.description || '',
-            code: json.content?.pattern || '',
-            usageGuide: '',
-          };
-        }
-      } catch {
-        /* ignore */
-      }
-    }
-
-    if (!cand) {
-      return { similar: [], message: 'No candidate provided' };
-    }
-
-    const similar = findSimilarRecipes(projectRoot, cand, {
-      threshold,
-      topK: 10,
-    });
-
-    return {
-      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，建议人工审核是否重复。'
-              : '有低相似度匹配，大概率不是重复。',
-      },
-    };
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 12. add_graph_edge
-// ────────────────────────────────────────────────────────────
-export const addGraphEdge = {
-  name: 'add_graph_edge',
-  description: '手动添加知识图谱关系边（从 A 到 B 的关系）。',
-  parameters: {
-    type: 'object',
-    properties: {
-      fromId: { type: 'string', description: '源节点 ID' },
-      fromType: { type: 'string', description: '源节点类型 (recipe/candidate)' },
-      toId: { type: 'string', description: '目标节点 ID' },
-      toType: { type: 'string', description: '目标节点类型 (recipe/candidate)' },
-      relation: {
-        type: 'string',
-        description:
-          '关系类型 (requires/extends/enforces/depends_on/inherits/implements/calls/prerequisite)',
-      },
-      weight: { type: 'number', description: '权重 0-1，默认 1.0' },
-    },
-    required: ['fromId', 'fromType', 'toId', 'toType', 'relation'],
-  },
-  handler: async (params, ctx) => {
-    const kgService = ctx.container.get('knowledgeGraphService');
-    return kgService.addEdge(
-      params.fromId,
-      params.fromType,
-      params.toId,
-      params.toType,
-      params.relation,
-      { weight: params.weight || 1.0, source: 'manual' }
-    );
-  },
-};

package/lib/service/agent/tools/lifecycle.js

@@ -1,488 +0,0 @@
-/**
- * lifecycle.js — 生命周期操作类工具 (11)
- *
- * 16.  submit_knowledge     提交候选项
- * 16b. save_document        保存开发文档
- * 17.  approve_candidate    批准候选
- * 18.  reject_candidate     驳回候选
- * 19.  publish_recipe       发布 Recipe
- * 20.  deprecate_recipe     弃用 Recipe
- * 21.  update_recipe        更新 Recipe
- * 22.  record_usage         记录使用
- * 23.  quality_score        质量评分
- * 24.  validate_candidate   候选校验
- * 25.  get_feedback_stats   反馈统计
- */
-
-import { UnifiedValidator } from '../../../shared/UnifiedValidator.js';
-import { getInternalAgentRequiredFields, getSystemInjectedFields } from '../../../shared/FieldSpec.js';
-import { checkDimensionType, DIMENSION_DISPLAY_GROUP } from './_shared.js';
-
-// ────────────────────────────────────────────────────────────
-// 16. submit_knowledge
-// ────────────────────────────────────────────────────────────
-export const submitCandidate = {
-  name: 'submit_knowledge',
-  description: '提交新的代码候选项到知识库审核队列。',
-  parameters: {
-    type: 'object',
-    properties: {
-      // ── 内容（V3 content 子对象） ──
-      content: {
-        type: 'object',
-        description:
-          '{ markdown: "项目特写 Markdown(≥200字)", pattern: "核心代码 3-8 行", rationale: "设计原理" }',
-      },
-
-      // ── 基本信息 ──
-      title: { type: 'string', description: '候选标题（中文 ≤20 字）' },
-      description: { type: 'string', description: '中文简述 ≤80 字，引用真实类名' },
-      tags: { type: 'array', items: { type: 'string' }, description: '标签列表' },
-
-      // ── Cursor 交付（AI 必填）──
-      trigger: { type: 'string', description: '@前缀 kebab-case 唯一标识符' },
-      kind: { type: 'string', enum: ['rule', 'pattern', 'fact'], description: '知识类型' },
-      topicHint: {
-        type: 'string',
-        enum: ['networking', 'ui', 'data', 'architecture', 'conventions'],
-        description: '主题分类',
-      },
-      whenClause: { type: 'string', description: '触发场景英文' },
-      doClause: { type: 'string', description: '正向指令英文祈使句 ≤60 tokens' },
-      dontClause: { type: 'string', description: "反向约束英文（不以 Don't 开头）" },
-      coreCode: { type: 'string', description: '3-8 行纯代码骨架，语法完整可复制' },
-
-      // ── 推理（必填） ──
-      reasoning: {
-        type: 'object',
-        description: '{ whyStandard: string, sources: string[], confidence: number } — 全部必填',
-      },
-
-      // ── V3 扩展字段 ──
-      scope: {
-        type: 'string',
-        enum: ['universal', 'project-specific', 'team-convention'],
-        description: '适用范围',
-      },
-      complexity: {
-        type: 'string',
-        enum: ['basic', 'intermediate', 'advanced'],
-        description: '复杂度',
-      },
-      headers: {
-        type: 'array',
-        items: { type: 'string' },
-        description: '依赖的 import/require 行（无 import 时传 []）',
-      },
-      knowledgeType: {
-        type: 'string',
-        description: '知识维度：code-pattern / architecture / best-practice 等',
-      },
-      usageGuide: { type: 'string', description: '使用指南 Markdown（### 章节格式）' },
-      sourceFile: { type: 'string', description: '来源文件相对路径' },
-    },
-    // FieldSpec 驱动: 内部 Agent 路径排除系统注入字段
-    required: getInternalAgentRequiredFields(),
-  },
-  handler: async (params, ctx) => {
-    const knowledgeService = ctx.container.get('knowledgeService');
-
-    // ── Bootstrap 维度类型校验 ──
-    const dimMeta = ctx._dimensionMeta;
-    if (dimMeta && ctx.source === 'system') {
-      const rejected = checkDimensionType(dimMeta, params, ctx.logger);
-      if (rejected) {
-        return rejected;
-      }
-
-      // 自动注入维度标签
-      if (!params.tags) {
-        params.tags = [];
-      }
-      if (!params.tags.includes(dimMeta.id)) {
-        params.tags.push(dimMeta.id);
-      }
-      if (!params.tags.includes('bootstrap')) {
-        params.tags.push('bootstrap');
-      }
-
-      // Bootstrap 模式: 将 category 覆盖为展示分组 ID
-      params._category = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
-
-      // ── UnifiedValidator 统一质量验证（替代 CandidateGuardrail） ──
-      const validator = ctx._validator || new UnifiedValidator({
-        existingTitles: ctx._submittedTitles || new Set(),
-        existingFingerprints: ctx._submittedPatterns || new Set(),
-      });
-      const validResult = validator.validate(params, {
-        mode: 'strict',
-        systemInjectedFields: getSystemInjectedFields(),
-      });
-      if (!validResult.pass) {
-        ctx.logger?.info(`[submit_knowledge] ✗ validator rejected: ${validResult.errors.join('; ')}`);
-        return {
-          status: 'rejected',
-          error: validResult.errors.join('\n'),
-          warnings: validResult.warnings,
-          hint: '请根据错误信息调整内容后重新提交。',
-        };
-      }
-      if (validResult.warnings.length > 0) {
-        ctx.logger?.debug(`[submit_knowledge] ⚠ warnings: ${validResult.warnings.join('; ')}`);
-      }
-    }
-
-    // ── 系统自动设置 ──
-    const systemFields = {
-      language: ctx._projectLanguage || '',
-      category: dimMeta ? DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id : 'general',
-      knowledgeType: dimMeta?.allowedKnowledgeTypes?.[0] || 'code-pattern',
-      source: ctx.source === 'system' ? 'bootstrap' : 'agent',
-    };
-
-    // ── 直传 → KnowledgeEntry ──
-    const reasoning = params.reasoning || { whyStandard: '', sources: ['agent'], confidence: 0.7 };
-    if (Array.isArray(reasoning.sources) && reasoning.sources.length === 0) {
-      reasoning.sources = ['agent'];
-    }
-
-    // V3 content 直透
-    const contentObj =
-      params.content && typeof params.content === 'object'
-        ? params.content
-        : { markdown: '', pattern: '' };
-
-    const data = {
-      ...systemFields,
-      title: params.title || '',
-      description: params.description || '',
-      tags: params.tags || [],
-      trigger: params.trigger || '',
-      kind: params.kind || 'pattern',
-      topicHint: params.topicHint || '',
-      whenClause: params.whenClause || '',
-      doClause: params.doClause || '',
-      dontClause: params.dontClause || '',
-      coreCode: contentObj.pattern || '',
-      content: contentObj,
-      reasoning,
-      // V3 扩展字段直透
-      scope: params.scope || '',
-      complexity: params.complexity || '',
-      headers: params.headers || [],
-      // 注意: sourceFile 由 KnowledgeFileWriter.persist() 自动设置，
-      // 不应从 AI params/reasoning.sources 取值（那是项目源文件路径，不是知识文件路径）
-      sourceFile: '',
-      // 7.3.9 agentNotes/aiInsight 注入
-      agentNotes: dimMeta
-        ? { dimensionId: dimMeta.id, outputType: dimMeta.outputType || 'candidate' }
-        : null,
-      aiInsight: reasoning.whyStandard || params.description || null,
-    };
-
-    if (dimMeta && ctx.source === 'system') {
-      const displayGroup = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
-      data.tags = [...new Set([...(data.tags || []), displayGroup])];
-    }
-
-    const saved = await knowledgeService.create(data, { userId: 'agent' });
-
-    // ── QualityScorer 自动评分 ──
-    try {
-      await knowledgeService.updateQuality(saved.id, { userId: 'agent' });
-    } catch {
-      /* best effort — 不阻塞创建流程 */
-    }
-
-    return saved;
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 16b. save_document — 保存开发文档到知识库
-// ────────────────────────────────────────────────────────────
-export const saveDocument = {
-  name: 'save_document',
-  description:
-    '保存开发文档到知识库（架构设计、排查报告、决策记录、调研笔记等）。仅需 title + markdown，无需 Cursor Delivery 字段。文档自动发布，可通过 autosnippet_search 检索。',
-  parameters: {
-    type: 'object',
-    properties: {
-      title: { type: 'string', description: '文档标题' },
-      markdown: { type: 'string', description: '文档 Markdown 全文' },
-      description: { type: 'string', description: '一句话摘要（可选）' },
-      tags: {
-        type: 'array',
-        items: { type: 'string' },
-        description: '标签: adr, debug-report, design-doc, research, performance 等',
-      },
-      scope: {
-        type: 'string',
-        enum: ['universal', 'project-specific'],
-        description: '适用范围（默认 project-specific）',
-      },
-    },
-    required: ['title', 'markdown'],
-  },
-  handler: async (params, ctx) => {
-    const knowledgeService = ctx.container.get('knowledgeService');
-
-    const data = {
-      title: params.title.trim(),
-      description: params.description || '',
-      knowledgeType: 'dev-document',
-      kind: 'fact',
-      source: 'agent',
-      scope: params.scope || 'project-specific',
-      tags: params.tags || [],
-      content: {
-        markdown: params.markdown,
-        pattern: '',
-      },
-      trigger: '',
-      doClause: '',
-      dontClause: '',
-      whenClause: '',
-      topicHint: '',
-      coreCode: '',
-      reasoning: {
-        whyStandard: 'Agent development document',
-        sources: ['agent'],
-        confidence: 0.8,
-      },
-    };
-
-    // ── UnifiedValidator 校验（自动检测 document 模式）──
-    const validator = new UnifiedValidator();
-    const vr = validator.validate(data, { skipUniqueness: true });
-    if (!vr.pass) {
-      return { error: true, message: `文档校验失败: ${vr.errors.join('; ')}` };
-    }
-
-    const saved = await knowledgeService.create(data, { userId: 'agent' });
-
-    // 自动发布（文档不需要人工审核）
-    try {
-      await knowledgeService.publish(saved.id, { userId: 'agent' });
-    } catch {
-      /* best effort */
-    }
-
-    return {
-      id: saved.id,
-      title: saved.title,
-      lifecycle: 'active',
-      knowledgeType: 'dev-document',
-      message: `文档「${saved.title}」已保存到知识库`,
-    };
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 17. approve_candidate
-// ────────────────────────────────────────────────────────────
-export const approveCandidate = {
-  name: 'approve_candidate',
-  description: '批准候选项（PENDING → APPROVED）。',
-  parameters: {
-    type: 'object',
-    properties: {
-      candidateId: { type: 'string', description: '候选 ID' },
-    },
-    required: ['candidateId'],
-  },
-  handler: async (params, ctx) => {
-    const knowledgeService = ctx.container.get('knowledgeService');
-    return knowledgeService.approve(params.candidateId, { userId: 'agent' });
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 18. reject_candidate
-// ────────────────────────────────────────────────────────────
-export const rejectCandidate = {
-  name: 'reject_candidate',
-  description: '驳回候选项并填写驳回理由。',
-  parameters: {
-    type: 'object',
-    properties: {
-      candidateId: { type: 'string', description: '候选 ID' },
-      reason: { type: 'string', description: '驳回理由' },
-    },
-    required: ['candidateId', 'reason'],
-  },
-  handler: async (params, ctx) => {
-    const knowledgeService = ctx.container.get('knowledgeService');
-    return knowledgeService.reject(params.candidateId, params.reason, { userId: 'agent' });
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 19. publish_recipe
-// ────────────────────────────────────────────────────────────
-export const publishRecipe = {
-  name: 'publish_recipe',
-  description: '发布 Recipe（DRAFT → ACTIVE）。',
-  parameters: {
-    type: 'object',
-    properties: {
-      recipeId: { type: 'string', description: 'Recipe ID' },
-    },
-    required: ['recipeId'],
-  },
-  handler: async (params, ctx) => {
-    const knowledgeService = ctx.container.get('knowledgeService');
-    return knowledgeService.publish(params.recipeId, { userId: 'agent' });
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 20. deprecate_recipe
-// ────────────────────────────────────────────────────────────
-export const deprecateRecipe = {
-  name: 'deprecate_recipe',
-  description: '弃用 Recipe 并填写弃用原因。',
-  parameters: {
-    type: 'object',
-    properties: {
-      recipeId: { type: 'string', description: 'Recipe ID' },
-      reason: { type: 'string', description: '弃用原因' },
-    },
-    required: ['recipeId', 'reason'],
-  },
-  handler: async (params, ctx) => {
-    const knowledgeService = ctx.container.get('knowledgeService');
-    return knowledgeService.deprecate(params.recipeId, params.reason, { userId: 'agent' });
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 21. update_recipe
-// ────────────────────────────────────────────────────────────
-export const updateRecipe = {
-  name: 'update_recipe',
-  description: '更新 Recipe 的指定字段（title/description/content/category/tags 等）。',
-  parameters: {
-    type: 'object',
-    properties: {
-      recipeId: { type: 'string', description: 'Recipe ID' },
-      updates: { type: 'object', description: '要更新的字段和值' },
-    },
-    required: ['recipeId', 'updates'],
-  },
-  handler: async (params, ctx) => {
-    const knowledgeService = ctx.container.get('knowledgeService');
-    return knowledgeService.update(params.recipeId, params.updates, { userId: 'agent' });
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 22. record_usage
-// ────────────────────────────────────────────────────────────
-export const recordUsage = {
-  name: 'record_usage',
-  description: '记录 Recipe 的使用（adoption 被采纳 / application 被应用）。',
-  parameters: {
-    type: 'object',
-    properties: {
-      recipeId: { type: 'string', description: 'Recipe ID' },
-      type: { type: 'string', description: 'adoption 或 application，默认 adoption' },
-    },
-    required: ['recipeId'],
-  },
-  handler: async (params, ctx) => {
-    const knowledgeService = ctx.container.get('knowledgeService');
-    const type = params.type || 'adoption';
-    await knowledgeService.incrementUsage(params.recipeId, type);
-    return { success: true, recipeId: params.recipeId, type };
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 23. quality_score
-// ────────────────────────────────────────────────────────────
-export const qualityScore = {
-  name: 'quality_score',
-  description:
-    'Recipe 质量评分 — 5 维度综合评估（完整性/格式/代码质量/元数据/互动），返回分数和等级(A-F)。',
-  parameters: {
-    type: 'object',
-    properties: {
-      recipeId: { type: 'string', description: 'Recipe ID（从数据库读取后评分）' },
-      recipe: {
-        type: 'object',
-        description: '或直接提供 Recipe 对象 { title, trigger, code, language, ... }',
-      },
-    },
-  },
-  handler: async (params, ctx) => {
-    const qualityScorer = ctx.container.get('qualityScorer');
-    let recipe = params.recipe;
-
-    if (!recipe && params.recipeId) {
-      const knowledgeService = ctx.container.get('knowledgeService');
-      try {
-        const entry = await knowledgeService.get(params.recipeId);
-        recipe = typeof entry.toJSON === 'function' ? entry.toJSON() : entry;
-      } catch {
-        return { error: `Knowledge entry '${params.recipeId}' not found` };
-      }
-    }
-    if (!recipe) {
-      return { error: 'Provide recipeId or recipe object' };
-    }
-
-    return qualityScorer.score(recipe);
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 24. validate_candidate
-// ────────────────────────────────────────────────────────────
-export const validateCandidate = {
-  name: 'validate_candidate',
-  description:
-    '候选校验 — 检查候选是否满足提交要求（必填字段/格式/质量），返回 errors 和 warnings。',
-  parameters: {
-    type: 'object',
-    properties: {
-      candidate: {
-        type: 'object',
-        description: '候选对象 { title, trigger, category, language, code, reasoning, ... }',
-      },
-    },
-    required: ['candidate'],
-  },
-  handler: async (params, ctx) => {
-    const validator = ctx.container.get('recipeCandidateValidator');
-    return validator.validate(params.candidate);
-  },
-};
-
-// ────────────────────────────────────────────────────────────
-// 25. get_feedback_stats
-// ────────────────────────────────────────────────────────────
-export const getFeedbackStats = {
-  name: 'get_feedback_stats',
-  description: '获取用户反馈统计 — 全局交互事件统计 + 热门 Recipe + 指定 Recipe 的详细反馈。',
-  parameters: {
-    type: 'object',
-    properties: {
-      recipeId: { type: 'string', description: '查询指定 Recipe 的反馈（可选）' },
-      topN: { type: 'number', description: '热门 Recipe 数量，默认 10' },
-    },
-  },
-  handler: async (params, ctx) => {
-    const feedbackCollector = ctx.container.get('feedbackCollector');
-    const result = {};
-
-    result.global = feedbackCollector.getGlobalStats();
-    result.topRecipes = feedbackCollector.getTopRecipes(params.topN || 10);
-
-    if (params.recipeId) {
-      result.recipeStats = feedbackCollector.getRecipeStats(params.recipeId);
-    }
-
-    return result;
-  },
-};