autosnippet 2.6.0 → 2.7.0

package/lib/service/candidate/CandidateService.js

@@ -154,6 +154,47 @@ export class CandidateService {
     }
   }
 
+  /**
+   * 删除候选项（DB + .md 文件）
+   */
+  async deleteCandidate(candidateId, context = {}) {
+    try {
+      const candidate = await this.candidateRepository.findById(candidateId);
+
+      // 先删 .md 文件（即使 DB 中不存在也尝试按 id 清理文件）
+      if (this.fileWriter && candidate) {
+        this.fileWriter.removeCandidate(candidate);
+      }
+
+      // 删除 DB 记录
+      const deleted = await this.candidateRepository.delete(candidateId);
+
+      // 审计日志
+      if (deleted) {
+        await this.auditLogger.log({
+          action: 'delete_candidate',
+          resource: `candidate:${candidateId}`,
+          actor: context.userId || 'system',
+          result: 'success',
+        });
+      }
+
+      this.logger.info('Candidate deleted', {
+        candidateId,
+        dbDeleted: deleted,
+        fileRemoved: !!candidate,
+      });
+
+      return deleted;
+    } catch (error) {
+      this.logger.error('Error deleting candidate', {
+        candidateId,
+        error: error.message,
+      });
+      throw error;
+    }
+  }
+
   /**
    * 驳回候选项
    */
@@ -543,6 +584,8 @@ export class CandidateService {
       throw new ValidationError('AI provider with chat capability is required');
     }
 
+    const onProgress = typeof options.onProgress === 'function' ? options.onProgress : null;
+
     // 1. 收集候选
     let candidates;
     if (options.candidateIds?.length) {
@@ -564,6 +607,12 @@ export class CandidateService {
       return { refined: 0, total: 0, errors: [], results: [] };
     }
 
+    // 通知：润色开始
+    onProgress?.('refine:started', {
+      total: candidates.length,
+      candidateIds: candidates.map(c => c.id),
+    });
+
     // 2. 收集同批次标题列表（供 AI 推断关系）
     const allTitles = candidates.map(c => (c.metadata || {}).title || '').filter(Boolean);
 
@@ -571,22 +620,46 @@ export class CandidateService {
     const results = [];
     const errors = [];
     let refined = 0;
+    let processed = 0;
 
     for (const candidate of candidates) {
+      processed++;
+      const title = (candidate.metadata || {}).title || '';
+
+      // 通知：开始处理当前候选
+      onProgress?.('refine:item-started', {
+        candidateId: candidate.id,
+        title,
+        current: processed,
+        total: candidates.length,
+        progress: Math.round(((processed - 1) / candidates.length) * 100),
+      });
+
       try {
         const meta = { ...(candidate.metadata || {}) };
-        const title = meta.title || '';
         const prompt = this._buildRefinePrompt(candidate, allTitles, options.userPrompt);
         const response = await aiProvider.chat(prompt, { temperature: 0.3 });
         const parsed = aiProvider.extractJSON(response, '{', '}');
 
         if (!parsed) {
           errors.push({ id: candidate.id, title, error: 'AI returned no valid JSON' });
+          onProgress?.('refine:item-failed', {
+            candidateId: candidate.id, title,
+            error: 'AI returned no valid JSON',
+            current: processed, total: candidates.length,
+            progress: Math.round((processed / candidates.length) * 100),
+          });
           continue;
         }
 
         if (options.dryRun) {
           results.push({ id: candidate.id, title, preview: parsed });
+          onProgress?.('refine:item-completed', {
+            candidateId: candidate.id, title, refined: false,
+            current: processed, total: candidates.length,
+            progress: Math.round((processed / candidates.length) * 100),
+            refinedSoFar: refined,
+          });
           continue;
         }
 
@@ -624,9 +697,16 @@ export class CandidateService {
           }
         }
 
-        // 更新 code（如果 AI 改写了文档）
+        // 更新 code（如果 AI 改写了文档 — 增强校验防止截断/片段代码/类型变更）
         let newCode = candidate.code;
-        if (parsed.code && parsed.code.length > 50 && parsed.code !== candidate.code) {
+        const origCode = candidate.code || '';
+        const origLen = origCode.length;
+        const isOrigMarkdown = /^---\s*\n/.test(origCode) || /^#\s+/.test(origCode) || (origCode.match(/^#{1,3}\s+/gm) || []).length >= 2;
+        const isNewMarkdown = parsed.code && (/^---\s*\n/.test(parsed.code) || /^#\s+/.test(parsed.code) || (parsed.code.match(/^#{1,3}\s+/gm) || []).length >= 2);
+        const codeTypeChanged = !isOrigMarkdown && isNewMarkdown;
+        if (parsed.code && parsed.code.length > 50 && parsed.code !== candidate.code
+          && parsed.code.length >= origLen * 0.4  // 不能太短（防止 AI 返回截断片段）
+          && !codeTypeChanged) {                   // 不允许源代码 → Markdown 类型变更
           newCode = parsed.code;
           changed = true;
         }
@@ -645,11 +725,39 @@ export class CandidateService {
         }
 
         results.push({ id: candidate.id, title, refined: changed, fields: Object.keys(parsed) });
+
+        // 通知：当前候选完成
+        onProgress?.('refine:item-completed', {
+          candidateId: candidate.id,
+          title,
+          refined: changed,
+          current: processed,
+          total: candidates.length,
+          progress: Math.round((processed / candidates.length) * 100),
+          refinedSoFar: refined,
+        });
       } catch (err) {
         errors.push({ id: candidate.id, title: (candidate.metadata || {}).title, error: err.message });
+
+        // 通知：当前候选失败
+        onProgress?.('refine:item-failed', {
+          candidateId: candidate.id,
+          title,
+          error: err.message,
+          current: processed,
+          total: candidates.length,
+          progress: Math.round((processed / candidates.length) * 100),
+        });
       }
     }
 
+    // 通知：全部完成
+    onProgress?.('refine:completed', {
+      total: candidates.length,
+      refined,
+      failed: errors.length,
+    });
+
     // 4. 审计
     await this.auditLogger.log({
       action: 'refine_bootstrap_candidates',
@@ -669,10 +777,47 @@ export class CandidateService {
   _buildRefinePrompt(candidate, allTitles, userPrompt = '') {
     const meta = candidate.metadata || {};
     const otherTitles = allTitles.filter(t => t !== meta.title).map(t => `  - ${t}`).join('\n');
+    const code = (candidate.code || '');
+
+    // ── 检测 code 字段是源代码还是 Markdown 文档 ──
+    const isMarkdownDoc = /^---\s*\n/.test(code)                   // frontmatter
+      || /^#\s+/.test(code)                                        // 以 # 标题开头
+      || (code.match(/^#{1,3}\s+/gm) || []).length >= 2;           // 含 ≥2 个 Markdown 标题
+    const codeContentType = isMarkdownDoc ? 'markdown-document' : 'source-code';
+
+    // ── 用户指令段落 ──
+    let userSection = '';
+    if (userPrompt) {
+      userSection = `
+# User Instructions (HIGHEST PRIORITY — STRICTLY follow these)
+${userPrompt}
+
+## Scope Restriction
+- ONLY modify fields that are DIRECTLY related to the user instruction above.
+- Do NOT touch or return any field that the user did not ask to change.
+- For example, if user says "增加使用案例", ONLY return the field where usage examples belong (e.g. "code" for markdown docs, or "agentNotes" for source-code candidates). Do NOT return "summary", "confidence", "tags", "insight", or "relations" unless explicitly requested.
+- If you are unsure which field a user instruction maps to, prefer "agentNotes" or "code" (for markdown docs).
+`;
+    }
 
-    const userSection = userPrompt
-      ? `\n# User Instructions (IMPORTANT — follow these with highest priority)\n${userPrompt}\n`
-      : '';
+    // ── code 字段的任务描述根据内容类型而不同 ──
+    let codeTask;
+    if (codeContentType === 'source-code') {
+      codeTask = `7. **code**: The content field contains RAW SOURCE CODE (not a Markdown document).
+   - Do NOT convert source code into a Markdown document — that breaks the candidate.
+   - If the user asks to add usage examples, documentation notes or explanations,
+     put them in "agentNotes" (array of strings) instead of modifying "code".
+   - Only modify "code" if the user explicitly asks to change the source code itself
+     (e.g. fix a bug, add comments, refactor). Return the COMPLETE source code.
+   - If no code change is needed, OMIT this field entirely.`;
+    } else {
+      codeTask = `7. **code**: The content field is a Markdown document.
+   - If improvements are needed, return the COMPLETE improved Markdown document.
+   - CRITICAL: You MUST return the ENTIRE document content, including ALL sections.
+   - Do NOT return only source code fragments or partial snippets.
+   - The code blocks inside the Markdown should contain PURE source code.
+   - If no code improvement is needed, OMIT this field entirely.`;
+    }
 
     return `# Role
 You are a senior software architect refining a Bootstrap knowledge candidate.\n${userSection}
@@ -683,10 +828,11 @@ Category: ${candidate.category || 'bootstrap'}
 Language: ${candidate.language || 'unknown'}
 Summary: ${meta.summary || '(none)'}
 Tags: ${(meta.tags || []).join(', ')}
+Content Type: ${codeContentType}
 
-## Content (Markdown document)
+## Content
 \`\`\`
-${(candidate.code || '').substring(0, 3000)}
+${code.substring(0, 3000)}
 \`\`\`
 
 # Sibling Candidates (same bootstrap batch)
@@ -699,10 +845,10 @@ ${otherTitles || '(none)'}
 4. **relations**: Array of cross-references to sibling candidates: [{ "type": "DEPENDS_ON|EXTENDS|RELATED|CONFLICTS|ENFORCES|PREREQUISITE", "target": "<exact title from siblings>", "description": "<why>" }]
 5. **confidence**: Float 0-1 rating of this candidate's value (0.3=low, 0.6=medium, 0.9=high)
 6. **tags**: Additional relevant tags (array of strings, optional)
-7. **code**: If the Markdown document can be improved, return the full improved version. Otherwise omit this field.
+${codeTask}
 
 # Output
-Return a single JSON object with the fields above. Only include fields you want to change.
+Return a single JSON object. Only include fields you want to change.${userPrompt ? '\nREMINDER: Only return fields DIRECTLY related to the user instruction. Omit all others!' : ''}
 Do NOT wrap in markdown code blocks. Return raw JSON only.`;
   }
 

package/lib/service/chat/AnalystAgent.js

@@ -0,0 +1,216 @@
+/**
+ * AnalystAgent.js — v3.0 分析者 Agent
+ *
+ * 职责:
+ * - 使用 AST 工具 + 文件搜索工具自由探索代码库
+ * - 输出自然语言分析结果 (无格式约束)
+ * - 不提交候选、不关心格式
+ *
+ * 设计哲学:
+ * "给 AI 一个任务描述和一套好工具，让它像资深工程师一样自由探索代码库。"
+ *
+ * @module AnalystAgent
+ */
+
+import { buildAnalysisReport, analysisQualityGate, buildRetryPrompt } from './HandoffProtocol.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+
+// ──────────────────────────────────────────────────────────────────
+// System Prompt — Analyst 专用 (~100 tokens)
+// ──────────────────────────────────────────────────────────────────
+
+const ANALYST_SYSTEM_PROMPT = `你是一名高级软件架构师，正在分析一个代码项目。
+使用提供的工具深入探索代码结构，理解设计决策背后的原因。
+输出你的分析发现，包括具体的文件路径和代码位置。
+不需要任何特定格式，用自然语言描述你的理解即可。
+尽可能多地使用工具来获取准确信息，不要猜测。`;
+
+// ──────────────────────────────────────────────────────────────────
+// Analyst 可用工具白名单 — 只做探索，不做提交
+// ──────────────────────────────────────────────────────────────────
+
+const ANALYST_TOOLS = [
+  // AST 结构化分析
+  'get_project_overview',
+  'get_class_hierarchy',
+  'get_class_info',
+  'get_protocol_info',
+  'get_method_overrides',
+  'get_category_map',
+  // 文件访问
+  'search_project_code',
+  'read_project_file',
+  'list_project_structure',
+  'get_file_summary',
+  'semantic_search_code',
+  // 前序上下文 (可选)
+  'get_previous_analysis',
+];
+
+// ──────────────────────────────────────────────────────────────────
+// Analyst 预算 — 自由探索，不需要 PhaseRouter
+// ──────────────────────────────────────────────────────────────────
+
+const ANALYST_BUDGET = {
+  maxIterations: 20,
+  searchBudget: 15,       // 探索为主，给更多搜索预算
+  searchBudgetGrace: 10,
+  maxSubmits: 0,          // Analyst 不提交候选
+  softSubmitLimit: 0,
+  idleRoundsToExit: 3,
+};
+
+// ──────────────────────────────────────────────────────────────────
+// 维度 Prompt 模板
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * 构建 Analyst Prompt
+ * @param {object} dimConfig — 维度配置 { id, label, guide, focusAreas }
+ * @param {object} projectInfo — { name, lang, fileCount }
+ * @returns {string}
+ */
+function buildAnalystPrompt(dimConfig, projectInfo) {
+  const parts = [];
+
+  // §1 任务描述
+  parts.push(`分析项目 ${projectInfo.name} (${projectInfo.lang}, ${projectInfo.fileCount} 个文件) 的 ${dimConfig.label}。`);
+
+  // §2 维度指引
+  if (dimConfig.guide) {
+    parts.push(dimConfig.guide);
+  }
+
+  // §3 探索焦点
+  if (dimConfig.focusAreas?.length > 0) {
+    parts.push(`重点关注:\n${dimConfig.focusAreas.map(f => `- ${f}`).join('\n')}`);
+  }
+
+  // §4 输出要求
+  const outputType = dimConfig.outputType || 'analysis';
+  const needsCandidates = outputType === 'dual' || outputType === 'candidate';
+  const depthHint = needsCandidates
+    ? '你的分析将被转化为知识候选，请确保每个发现都有足够的代码证据和文件引用。目标: 发现 3-5 个独立的知识点。'
+    : '';
+
+  parts.push(`请将分析组织成结构化段落，包含:
+1. 在哪些文件/类中发现 (写出具体文件路径)
+2. 具体的实现方式和代码特征
+3. 为什么选择这种方式（设计意图）
+4. 统计数据 (如数量、占比)
+
+每个关键发现用编号列表呈现，引用 3 个以上具体文件。
+${depthHint}
+重要: 务必使用 read_project_file 阅读代码确认，不要假设文件存在。引用的每个文件路径都必须是你亲眼看到的。`);
+
+  // §5 前序上下文提示
+  parts.push('可以调用 get_previous_analysis 获取前序维度的分析结果，避免重复分析。');
+
+  return parts.join('\n\n');
+}
+
+// ──────────────────────────────────────────────────────────────────
+// AnalystAgent 类
+// ──────────────────────────────────────────────────────────────────
+
+export class AnalystAgent {
+  /** @type {import('./ChatAgent.js').ChatAgent} */
+  #chatAgent;
+
+  /** @type {import('../../core/ast/ProjectGraph.js').default} */
+  #projectGraph;
+
+  /** @type {import('../../infrastructure/logging/Logger.js').default} */
+  #logger;
+
+  /** @type {number} Gate 最大重试次数 */
+  #maxRetries;
+
+  /**
+   * @param {object} chatAgent — ChatAgent 实例
+   * @param {object} [projectGraph] — ProjectGraph 实例
+   * @param {object} [options]
+   * @param {number} [options.maxRetries=1] — Gate 失败最大重试次数
+   */
+  constructor(chatAgent, projectGraph = null, options = {}) {
+    this.#chatAgent = chatAgent;
+    this.#projectGraph = projectGraph;
+    this.#logger = Logger.getInstance();
+    this.#maxRetries = options.maxRetries ?? 1;
+  }
+
+  /**
+   * 分析指定维度
+   *
+   * @param {object} dimConfig — 维度配置 { id, label, guide, focusAreas }
+   * @param {object} projectInfo — { name, lang, fileCount }
+   * @param {object} [options]
+   * @param {string} [options.sessionId] — Bootstrap session ID
+   * @returns {Promise<import('./HandoffProtocol.js').AnalysisReport>}
+   */
+  async analyze(dimConfig, projectInfo, options = {}) {
+    const dimId = dimConfig.id;
+    const prompt = buildAnalystPrompt(dimConfig, projectInfo);
+
+    this.#logger.info(`[AnalystAgent] ▶ analyzing dimension "${dimId}" — prompt ${prompt.length} chars`);
+
+    let retries = 0;
+    let lastReport = null;
+
+    while (retries <= this.#maxRetries) {
+      const execPrompt = retries === 0
+        ? prompt
+        : prompt + '\n\n' + buildRetryPrompt(lastReport?._gateReason || 'Analysis too short');
+
+      try {
+        const result = await this.#chatAgent.execute(execPrompt, {
+          source: 'system',
+          conversationId: options.sessionId ? `analyst-${options.sessionId}-${dimId}` : undefined,
+          budget: ANALYST_BUDGET,
+          systemPromptOverride: ANALYST_SYSTEM_PROMPT,
+          allowedTools: ANALYST_TOOLS,
+          disablePhaseRouter: true,
+          temperature: 0.4,
+          dimensionMeta: {
+            id: dimId,
+            outputType: 'analysis',
+            allowedKnowledgeTypes: dimConfig.allowedKnowledgeTypes || [],
+          },
+        });
+
+        // 构建 AnalysisReport
+        const report = buildAnalysisReport(result, dimId, this.#projectGraph);
+
+        // 质量门控 — 传入 outputType 以调整门槛
+        const gate = analysisQualityGate(report, { outputType: dimConfig.outputType || 'analysis' });
+        if (gate.pass) {
+          this.#logger.info(`[AnalystAgent] ✅ dimension "${dimId}" — ${report.analysisText.length} chars, ${report.referencedFiles.length} files referenced, ${report.metadata.toolCallCount} tool calls`);
+          return report;
+        }
+
+        this.#logger.warn(`[AnalystAgent] ⚠ Gate failed for "${dimId}": ${gate.reason} (action=${gate.action})`);
+
+        if (gate.action === 'degrade') {
+          // 直接降级 — 不重试
+          report._gateResult = gate;
+          return report;
+        }
+
+        // retry
+        lastReport = report;
+        lastReport._gateReason = gate.reason;
+        retries++;
+      } catch (err) {
+        this.#logger.error(`[AnalystAgent] ❌ dimension "${dimId}" error: ${err.message}`);
+        // 返回空 report
+        return buildAnalysisReport({ reply: '', toolCalls: [] }, dimId, this.#projectGraph);
+      }
+    }
+
+    // 重试耗尽 — 返回最后一次结果
+    this.#logger.warn(`[AnalystAgent] Retries exhausted for "${dimId}" — returning last report`);
+    return lastReport || buildAnalysisReport({ reply: '', toolCalls: [] }, dimId, this.#projectGraph);
+  }
+}
+
+export default AnalystAgent;

package/lib/service/chat/CandidateGuardrail.js

@@ -0,0 +1,134 @@
+/**
+ * CandidateGuardrail.js — Producer 产出的候选验证链
+ *
+ * 三层验证:
+ * 1. 结构验证 — 必填字段、内容长度、knowledgeType 约束
+ * 2. 去重验证 — 标题不重复
+ * 3. 质量启发式 — 包含代码引用、项目特定内容
+ *
+ * @module CandidateGuardrail
+ */
+
+export class CandidateGuardrail {
+  /** @type {Set<string>} 已提交标题 (小写) */
+  #globalTitles;
+
+  /** @type {object} 维度配置 */
+  #dimensionConfig;
+
+  /**
+   * @param {Set<string>} globalTitles — 全局已提交标题集合 (小写)
+   * @param {object} dimensionConfig — { allowedKnowledgeTypes, id, outputType }
+   */
+  constructor(globalTitles, dimensionConfig) {
+    this.#globalTitles = globalTitles;
+    this.#dimensionConfig = dimensionConfig;
+  }
+
+  /**
+   * 验证候选结构
+   * @param {object} candidate — submit_candidate 工具参数
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  validateStructure(candidate) {
+    // 必填字段检查
+    const required = ['title', 'code'];
+    for (const field of required) {
+      if (!candidate[field] || String(candidate[field]).trim().length === 0) {
+        return { valid: false, error: `缺少必填字段: ${field}` };
+      }
+    }
+
+    // 内容长度检查 — 「项目特写」需要足够的代码和描述
+    const content = candidate.code || '';
+    if (content.length < 200) {
+      return { valid: false, error: `内容过短 (${content.length} 字符, 最少 200)。请包含代码片段和项目上下文描述，而非一句话概括。` };
+    }
+
+    // knowledgeType 约束
+    const allowed = this.#dimensionConfig.allowedKnowledgeTypes;
+    if (allowed?.length > 0 && candidate.knowledgeType) {
+      if (!allowed.includes(candidate.knowledgeType)) {
+        return { valid: false, error: `knowledgeType "${candidate.knowledgeType}" 不在允许列表: [${allowed}]` };
+      }
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * 验证去重
+   * @param {object} candidate
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  validateUniqueness(candidate) {
+    const normalizedTitle = (candidate.title || '').toLowerCase().trim();
+    if (this.#globalTitles.has(normalizedTitle)) {
+      return { valid: false, error: `标题重复: "${candidate.title}"` };
+    }
+    return { valid: true };
+  }
+
+  /**
+   * 质量启发式检查
+   * @param {object} candidate
+   * @returns {{ valid: boolean, error?: string, warning?: string }}
+   */
+  validateQuality(candidate) {
+    const content = candidate.code || '';
+
+    // 检查是否包含代码引用或文件路径
+    const hasCodeBlock = /```[\s\S]*?```/.test(content) || /\.(m|h|swift|js|ts)(:\d+)?/.test(content);
+    const hasSourceRef = /\(来源[:：]/.test(content) || /\bFileName\b/.test(content) === false && /[A-Z]\w+\.(m|h|swift|java|kt|js|ts)/.test(content);
+
+    if (!hasCodeBlock && !hasSourceRef) {
+      return { valid: false, error: '内容缺少代码片段或文件引用 — 请用 read_project_file 获取代码后再提交，「项目特写」必须包含真实代码' };
+    }
+
+    // 检查是否是 Skill 摘要式内容（一行式描述、无代码、无结构）
+    const lines = content.split('\n').filter(l => l.trim().length > 0);
+    if (lines.length <= 2 && !hasCodeBlock) {
+      return { valid: false, error: `内容过于简单 (仅 ${lines.length} 行) — 请包含代码片段、设计意图和项目上下文，不要只写一句话概括` };
+    }
+
+    // 检查是否是通用知识而非项目特定
+    const genericPatterns = [
+      /^(Singleton|Factory|Observer|MVC|MVVM) (pattern|模式)$/i,
+    ];
+    const title = candidate.title || '';
+    if (genericPatterns.some(p => p.test(title.trim()))) {
+      return { valid: false, error: `标题过于通用: "${title}" — 请加上项目特定的上下文` };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * 完整验证链
+   * @param {object} candidate
+   * @returns {{ valid: boolean, error?: string, warning?: string }}
+   */
+  validate(candidate) {
+    const structureResult = this.validateStructure(candidate);
+    if (!structureResult.valid) return structureResult;
+
+    const uniqueResult = this.validateUniqueness(candidate);
+    if (!uniqueResult.valid) return uniqueResult;
+
+    const qualityResult = this.validateQuality(candidate);
+    // 质量问题返回 warning 但不阻止提交
+    if (!qualityResult.valid) return qualityResult;
+
+    return { valid: true, warning: qualityResult.warning };
+  }
+
+  /**
+   * 记录已提交标题（提交成功后调用）
+   * @param {string} title
+   */
+  recordTitle(title) {
+    this.#globalTitles.add((title || '').toLowerCase().trim());
+  }
+}
+
+export default CandidateGuardrail;