autosnippet 2.6.0 → 2.7.0

package/lib/service/chat/HandoffProtocol.js

@@ -0,0 +1,180 @@
+/**
+ * HandoffProtocol.js — Analyst → Producer 交接协议
+ *
+ * 职责:
+ * 1. 从 Analyst 执行结果构建 AnalysisReport
+ * 2. 质量门控: 判断分析是否足够深入
+ * 3. 提供重试提示构建
+ *
+ * @module HandoffProtocol
+ */
+
+// ──────────────────────────────────────────────────────────────────
+// AnalysisReport 构建
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * 从 Analyst 的执行结果构建 AnalysisReport
+ *
+ * @param {object} analystResult — ChatAgent.execute() 返回值
+ * @param {string} analystResult.reply — Analyst 的自然语言分析文本
+ * @param {Array} analystResult.toolCalls — 工具调用记录
+ * @param {string} dimensionId — 维度 ID
+ * @param {object} [projectGraph] — ProjectGraph 实例 (用于从 className 反查文件路径)
+ * @returns {AnalysisReport}
+ */
+export function buildAnalysisReport(analystResult, dimensionId, projectGraph = null) {
+  const referencedFiles = new Set();
+  const searchQueries = [];
+  const classesExplored = [];
+
+  for (const call of (analystResult.toolCalls || [])) {
+    const tool = call.tool || call.name;
+    const args = call.params || call.args || {};
+    const result = call.result;
+
+    switch (tool) {
+      case 'read_project_file':
+        if (args.filePath) referencedFiles.add(args.filePath);
+        break;
+      case 'search_project_code':
+        if (args.pattern || args.query) searchQueries.push(args.pattern || args.query);
+        // 从搜索结果中提取文件路径
+        if (typeof result === 'string') {
+          const fileMatches = result.match(/(?:^|\n)([\w/.-]+\.[mhswift]+)(?::\d+)?/g);
+          if (fileMatches) {
+            for (const m of fileMatches) {
+              const clean = m.trim().replace(/:\d+$/, '').replace(/^\n/, '');
+              if (clean.length > 2 && clean.length < 120) referencedFiles.add(clean);
+            }
+          }
+        }
+        break;
+      case 'get_class_info':
+        if (args.className) {
+          classesExplored.push(args.className);
+          // 从 ProjectGraph 反查文件路径
+          if (projectGraph) {
+            const info = projectGraph.getClassInfo(args.className);
+            if (info?.filePath) referencedFiles.add(info.filePath);
+          }
+        }
+        break;
+      case 'get_protocol_info':
+        if (args.protocolName && projectGraph) {
+          const info = projectGraph.getProtocolInfo(args.protocolName);
+          if (info?.filePath) referencedFiles.add(info.filePath);
+        }
+        break;
+      case 'get_file_summary':
+        if (args.filePath) referencedFiles.add(args.filePath);
+        break;
+    }
+  }
+
+  // 从分析文本中提取文件路径
+  const text = analystResult.reply || '';
+  const textFileRefs = text.match(/[\w/.-]+\.[mhswift]+/g);
+  if (textFileRefs) {
+    for (const f of textFileRefs) {
+      if (f.length > 2 && f.length < 120 && /\.[mhswift]+$/.test(f)) {
+        referencedFiles.add(f);
+      }
+    }
+  }
+
+  return {
+    analysisText: text,
+    referencedFiles: [...referencedFiles],
+    searchQueries,
+    classesExplored,
+    dimensionId,
+    metadata: {
+      iterations: analystResult.toolCalls?.length || 0,
+      toolCallCount: analystResult.toolCalls?.length || 0,
+    },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────
+// 质量门控 (Gate)
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * 分析质量门控 — 判断 Analyst 的输出是否足够好
+ *
+ * @param {AnalysisReport} report
+ * @param {object} [options]
+ * @param {string} [options.outputType] — 'analysis' | 'dual' | 'candidate'
+ * @returns {{ pass: boolean, reason?: string, action?: 'retry' | 'degrade' }}
+ */
+export function analysisQualityGate(report, options = {}) {
+  const needsCandidates = options.outputType === 'dual' || options.outputType === 'candidate';
+  // 需要产出候选的维度要求更高门槛
+  const minChars = needsCandidates ? 400 : 200;
+  const minFileRefs = needsCandidates ? 3 : 2;
+
+  // 规则 1: 最少字符数 — 分析太短说明未充分探索
+  if (report.analysisText.length < minChars) {
+    return { pass: false, reason: 'Analysis too short', action: 'retry' };
+  }
+
+  // 规则 2: 最少引用文件数 — 未引用文件说明未看代码
+  if (report.referencedFiles.length < minFileRefs) {
+    return { pass: false, reason: 'Too few file references', action: 'retry' };
+  }
+
+  // 规则 3: 检测"拒绝回答"模式
+  const refusalPatterns = [
+    /I cannot|I'm unable|I don't have access/i,
+    /无法分析|无法访问|没有足够/,
+  ];
+  if (refusalPatterns.some(p => p.test(report.analysisText))) {
+    return { pass: false, reason: 'Agent refused to analyze', action: 'degrade' };
+  }
+
+  // 规则 4: 内容实质性检查 — 有结构化内容或足够多的探索
+  // v3.1: 放宽条件 — tool calling 模式下 AI 往往不输出 markdown 格式
+  // 只要分析足够长且引用了足够多的文件，就认为有实质性内容
+  const hasStructure = /#{1,3}\s/.test(report.analysisText) ||
+                       /\d+\.\s/.test(report.analysisText) ||
+                       /[-•]\s/.test(report.analysisText) ||
+                       /[：:].+\n/.test(report.analysisText) ||
+                       report.analysisText.length >= 500 ||
+                       (report.referencedFiles.length >= 3 && report.analysisText.length >= 200);
+  if (!hasStructure) {
+    return { pass: false, reason: 'Analysis lacks structure', action: 'retry' };
+  }
+
+  return { pass: true };
+}
+
+/**
+ * 构建重试提示 — Gate 失败时给 Analyst 的追加指令
+ *
+ * @param {string} reason — Gate 失败原因
+ * @returns {string}
+ */
+export function buildRetryPrompt(reason) {
+  const hints = {
+    'Analysis too short': '你的分析不够深入。请使用更多工具（get_class_info、read_project_file、search_project_code）查看实际代码，输出至少 500 字的分析。',
+    'Too few file references': '你的分析缺少代码引用。请使用 get_class_info 和 read_project_file 查看至少 3 个相关文件，并在分析中引用具体文件和行号。',
+    'Analysis lacks structure': '请将分析组织成结构化的段落，使用编号列表或标题来区分不同的发现。每个发现应包含具体的文件路径和代码位置。',
+  };
+
+  return hints[reason] || '请更深入地分析代码，引用至少 3 个具体文件，每个发现都要有代码证据。';
+}
+
+// ──────────────────────────────────────────────────────────────────
+// 类型定义 (JSDoc)
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} AnalysisReport
+ * @property {string} analysisText — Analyst 的完整回复文本
+ * @property {string[]} referencedFiles — 从 toolCalls 中提取的已引用文件路径
+ * @property {string[]} searchQueries — 从 toolCalls 中提取的搜索查询
+ * @property {string[]} classesExplored — 从 toolCalls 中提取的已查看类名
+ * @property {string} dimensionId — 维度 ID
+ * @property {object} metadata — { iterations, toolCallCount }
+ */

package/lib/service/chat/ProducerAgent.js

@@ -0,0 +1,240 @@
+/**
+ * ProducerAgent.js — v3.0 生产者 Agent
+ *
+ * 职责:
+ * - 将 Analyst 的分析文本转换为结构化的 submit_candidate 调用
+ * - 遵循 PROJECT_SNAPSHOT_STYLE_GUIDE 格式
+ * - 使用 read_project_file 获取代码片段
+ * - CandidateGuardrail 验证每次提交
+ *
+ * 设计哲学:
+ * "像编辑把记者的手稿变成标准格式的文章。"
+ *
+ * @module ProducerAgent
+ */
+
+import Logger from '../../infrastructure/logging/Logger.js';
+
+// ──────────────────────────────────────────────────────────────────
+// System Prompt — Producer 专用 (~150 tokens)
+// ──────────────────────────────────────────────────────────────────
+
+const PRODUCER_SYSTEM_PROMPT = `你是知识管理专家。你会收到一段代码分析文本，需要将其中的知识点转化为结构化的知识候选。
+
+核心原则: 分析文本已经包含了所有发现，你的唯一工作是将它们格式化为 submit_candidate 调用。
+
+每个候选必须:
+1. 有清晰的标题 (描述知识点的核心，使用项目真实类名)
+2. 有项目特写风格的正文 (结合代码展示)
+3. 标注相关文件路径
+4. 选择正确的 knowledgeType (必须是维度约束中允许的类型)
+
+工作流程:
+1. 阅读分析文本，识别每个独立的知识点/发现
+2. 对每个知识点，用 read_project_file 获取关键代码片段（读取 30-80 行，不要只读 5 行头部）
+3. 立刻调用 submit_candidate 提交
+4. 重复直到分析中的所有知识点都已提交
+
+关键规则:
+- 分析中的每个要点/段落都应转化为至少一个候选
+- read_project_file 时读取足够多的行数（startLine + maxLines 至少 30 行）
+- reasoning.sources 必须是非空数组，填写相关文件路径如 ["FileName.m"]
+- 如果分析提到了 3 个模式，就应该提交 3 个候选，不要合并
+- 禁止: 不要搜索新文件、不要做额外分析，专注于格式化和提交
+
+容错规则:
+- 如果 read_project_file 返回"文件不存在"或错误，不要重试同一文件的其他路径变体
+- 文件读取失败时，直接使用分析文本中已有的代码和描述来提交候选
+- 永远不要因为文件读取失败而跳过知识点 — 分析文本已经包含足够信息
+- 先提交候选，再考虑是否需要读取更多代码（提交优先于验证）`;
+
+// ──────────────────────────────────────────────────────────────────
+// Producer 可用工具白名单 — 只做格式化和提交
+// ──────────────────────────────────────────────────────────────────
+
+const PRODUCER_TOOLS = [
+  'submit_candidate',
+  'submit_with_check',
+  'read_project_file',
+];
+
+// ──────────────────────────────────────────────────────────────────
+// Producer 预算 — 格式化任务，迭代更少
+// ──────────────────────────────────────────────────────────────────
+
+const PRODUCER_BUDGET = {
+  maxIterations: 15,
+  searchBudget: 4,
+  searchBudgetGrace: 3,
+  maxSubmits: 10,
+  softSubmitLimit: 10,
+  idleRoundsToExit: 3,
+};
+
+// ──────────────────────────────────────────────────────────────────
+// 项目特写风格指南 (只注入一次到 Producer)
+// ──────────────────────────────────────────────────────────────────
+
+const STYLE_GUIDE = `# 「项目特写」写作要求
+
+submit_candidate 的 code 字段必须是「项目特写」。
+
+## 什么是「项目特写」
+将一种技术的**基本用法**与**本项目的具体特征**融合为一体。
+
+## 四大核心内容
+1. **项目选择了什么** — 采用了哪种写法/模式/约定
+2. **为什么这样选** — 统计分布、占比、历史决策
+3. **项目禁止什么** — 反模式、已废弃写法
+4. **新代码怎么写** — 可直接复制使用的代码模板 + 来源标注 (来源: FileName.m:行号)
+
+## 格式要求
+- 标题使用项目真实类名/前缀，不用占位名
+- 代码来源标注: (来源: FileName.m:行号)
+- 不要纯代码罗列，必须有项目上下文`;
+
+// ──────────────────────────────────────────────────────────────────
+// Prompt 构建
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * 构建 Producer Prompt
+ *
+ * @param {import('./HandoffProtocol.js').AnalysisReport} analysisReport
+ * @param {object} dimConfig — { id, label, allowedKnowledgeTypes, outputType }
+ * @param {object} projectInfo — { name }
+ * @returns {string}
+ */
+function buildProducerPrompt(analysisReport, dimConfig, projectInfo) {
+  const parts = [];
+
+  // §1 任务描述
+  parts.push(`将以下对 ${projectInfo.name} 项目 "${dimConfig.label}" 维度的分析，转化为知识候选:`);
+
+  // §2 分析内容
+  parts.push(`---\n${analysisReport.analysisText}\n---`);
+
+  // §3 引用文件
+  if (analysisReport.referencedFiles.length > 0) {
+    parts.push(`分析中引用的关键文件: ${analysisReport.referencedFiles.join(', ')}`);
+  }
+
+  // §4 维度约束
+  parts.push(`维度约束:
+- dimensionId: ${dimConfig.id}
+- 允许的 knowledgeType: ${(dimConfig.allowedKnowledgeTypes || []).join(', ') || '(all)'}
+- category: ${dimConfig.id}`);
+
+  // §5 写作指南 (只注入一次)
+  parts.push(STYLE_GUIDE);
+
+  // §6 提交要求
+  parts.push(`要求:
+1. 每个独立的知识点单独提交为一个候选 — 目标: 至少 3 个候选
+2. 先使用分析中已有的代码片段直接提交候选; 仅在需要更多代码上下文时才用 read_project_file
+3. filePaths 填写分析中提到的相关文件路径
+4. summary 概括该知识点的核心价值
+5. reasoning 中 sources 必须非空，填写来源文件名如 ["FileName.m"]，confidence 填 0.7~0.9
+6. 不要跳过任何分析中提到的知识点
+7. 如果 read_project_file 失败（文件不存在），直接用分析文本内容提交，不要重试其他路径`);
+
+  return parts.join('\n\n');
+}
+
+// ──────────────────────────────────────────────────────────────────
+// ProducerAgent 类
+// ──────────────────────────────────────────────────────────────────
+
+export class ProducerAgent {
+  /** @type {import('./ChatAgent.js').ChatAgent} */
+  #chatAgent;
+
+  /** @type {import('../../infrastructure/logging/Logger.js').default} */
+  #logger;
+
+  /**
+   * @param {object} chatAgent — ChatAgent 实例
+   */
+  constructor(chatAgent) {
+    this.#chatAgent = chatAgent;
+    this.#logger = Logger.getInstance();
+  }
+
+  /**
+   * 将分析报告转化为候选
+   *
+   * @param {import('./HandoffProtocol.js').AnalysisReport} analysisReport — Analyst 产出
+   * @param {object} dimConfig — 维度配置
+   * @param {object} projectInfo — { name, lang, fileCount }
+   * @param {object} [options]
+   * @param {string} [options.sessionId]
+   * @param {object} [options.budget] — 覆盖默认预算
+   * @returns {Promise<ProducerResult>}
+   */
+  async produce(analysisReport, dimConfig, projectInfo, options = {}) {
+    const dimId = dimConfig.id;
+
+    // 分析文本为空时直接跳过
+    if (!analysisReport.analysisText || analysisReport.analysisText.length < 50) {
+      this.#logger.warn(`[ProducerAgent] ⚠ empty analysis for "${dimId}" — skipping`);
+      return { candidateCount: 0, toolCalls: [], reply: '' };
+    }
+
+    const prompt = buildProducerPrompt(analysisReport, dimConfig, projectInfo);
+    this.#logger.info(`[ProducerAgent] ▶ producing candidates for "${dimId}" — prompt ${prompt.length} chars`);
+
+    const budget = options.budget
+      ? { ...PRODUCER_BUDGET, ...options.budget }
+      : { ...PRODUCER_BUDGET };
+
+    try {
+      const result = await this.#chatAgent.execute(prompt, {
+        source: 'system',
+        conversationId: options.sessionId ? `producer-${options.sessionId}-${dimId}` : undefined,
+        budget,
+        systemPromptOverride: PRODUCER_SYSTEM_PROMPT,
+        allowedTools: PRODUCER_TOOLS,
+        disablePhaseRouter: true,
+        temperature: 0.3,
+        dimensionMeta: {
+          id: dimId,
+          outputType: dimConfig.outputType || 'candidate',
+          allowedKnowledgeTypes: dimConfig.allowedKnowledgeTypes || [],
+        },
+      });
+
+      // 统计提交 (区分成功/失败)
+      const submitCalls = (result.toolCalls || []).filter(
+        tc => (tc.tool || tc.name) === 'submit_candidate' || (tc.tool || tc.name) === 'submit_with_check'
+      );
+      const successCount = submitCalls.filter(tc => {
+        const res = tc.result;
+        if (!res) return true; // 无结果信息默认成功
+        if (typeof res === 'string') return !res.includes('rejected') && !res.includes('error');
+        return res.status !== 'rejected' && res.status !== 'error';
+      }).length;
+      const rejectedCount = submitCalls.length - successCount;
+
+      this.#logger.info(`[ProducerAgent] ✅ dimension "${dimId}" — ${successCount} candidates created (${rejectedCount} rejected), ${result.toolCalls?.length || 0} total tool calls`);
+
+      return {
+        candidateCount: successCount,
+        rejectedCount,
+        toolCalls: result.toolCalls || [],
+        reply: result.reply || '',
+      };
+    } catch (err) {
+      this.#logger.error(`[ProducerAgent] ❌ dimension "${dimId}" error: ${err.message}`);
+      return { candidateCount: 0, toolCalls: [], reply: '' };
+    }
+  }
+}
+
+/**
+ * @typedef {object} ProducerResult
+ * @property {number} candidateCount
+ * @property {Array} toolCalls
+ * @property {string} reply
+ */
+
+export default ProducerAgent;

package/lib/service/chat/ToolRegistry.js

@@ -12,6 +12,38 @@
 
 import Logger from '../../infrastructure/logging/Logger.js';
 
+/**
+ * AI 模型常见的参数命名变体 → schema 标准名映射
+ * 覆盖 Gemini / GPT / DeepSeek / Claude 常见偏好
+ */
+const PARAM_ALIASES = {
+  // read_project_file 变体
+  file:          'filePath',
+  filename:      'filePath',
+  file_name:     'filePath',
+  filepath:      'filePath',
+  file_path:     'filePath',
+  path:          'filePath',
+  // search_project_code 变体
+  query:         'pattern',
+  search:        'pattern',
+  keyword:       'pattern',
+  search_query:  'pattern',
+  search_text:   'pattern',
+  regex:         'pattern',
+  // 通用变体
+  is_regex:      'isRegex',
+  file_filter:   'fileFilter',
+  context_lines: 'contextLines',
+  max_results:   'maxResults',
+  start_line:    'startLine',
+  end_line:      'endLine',
+  max_lines:     'maxLines',
+  candidate_id:  'candidateId',
+  recipe_id:     'recipeId',
+  skill_name:    'skillName',
+};
+
 export class ToolRegistry {
   #tools = new Map();
   #logger;
@@ -32,7 +64,6 @@ export class ToolRegistry {
     const { name, description, handler, parameters = {} } = toolDef;
     if (!name || !handler) throw new Error('Tool must have name and handler');
     this.#tools.set(name, { name, description, parameters, handler });
-    this.#logger.debug(`Tool registered: ${name}`);
   }
 
   /**
@@ -41,14 +72,18 @@ export class ToolRegistry {
    */
   registerAll(defs) {
     for (const def of defs) this.register(def);
+    this.#logger.info(`[ToolRegistry] ${defs.length} tools registered`);
   }
 
   /**
    * 获取工具定义（不含 handler，给 LLM prompt 使用）
+   * @param {string[]} [allowedTools] — 限制返回的工具列表（不传则返回全部）
+   * @returns {Array<{name: string, description: string, parameters: object}>}
    */
-  getToolSchemas() {
+  getToolSchemas(allowedTools) {
     const schemas = [];
-    for (const [, tool] of this.#tools) {
+    for (const [name, tool] of this.#tools) {
+      if (allowedTools && !allowedTools.includes(name)) continue;
       schemas.push({
         name: tool.name,
         description: tool.description,
@@ -69,9 +104,13 @@ export class ToolRegistry {
     const tool = this.#tools.get(name);
     if (!tool) throw new Error(`Tool '${name}' not found`);
 
-    this.#logger.debug(`Tool execute: ${name}`, { params: Object.keys(params) });
+    // 参数归一化: AI 可能用 snake_case / 不同命名传参，
+    // 将其映射到 tool schema 中定义的 camelCase 参数名
+    const normalized = this.#normalizeParams(params, tool.parameters);
+
+    this.#logger.debug(`Tool execute: ${name}`, { params: Object.keys(normalized) });
     try {
-      const result = await tool.handler(params, context);
+      const result = await tool.handler(normalized, context);
       return result;
     } catch (err) {
       this.#logger.error(`Tool '${name}' failed`, { error: err.message });
@@ -79,6 +118,59 @@ export class ToolRegistry {
     }
   }
 
+  /**
+   * 参数归一化 — 将 AI 传来的 snake_case / 变体参数名映射到 schema 定义名
+   *
+   * 例: AI 传 { file_path: "x.m" } → schema 定义 filePath → 归一化为 { filePath: "x.m" }
+   *     AI 传 { file: "x.m" }      → schema 定义 filePath → 通过别名表匹配
+   *
+   * 策略:
+   *   1. schema 中已有的 key → 保留不动
+   *   2. snake_case → camelCase 自动转换
+   *   3. 常用别名表兜底
+   */
+  #normalizeParams(params, schema) {
+    if (!params || typeof params !== 'object') return params || {};
+    const properties = schema?.properties || {};
+    const schemaKeys = new Set(Object.keys(properties));
+    if (schemaKeys.size === 0) return params;
+
+    const result = {};
+    const unmatched = [];
+
+    for (const [key, value] of Object.entries(params)) {
+      // 1. 精确匹配 — 已在 schema 中
+      if (schemaKeys.has(key)) {
+        result[key] = value;
+        continue;
+      }
+
+      // 2. snake_case → camelCase 转换
+      const camelKey = key.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+      if (schemaKeys.has(camelKey)) {
+        result[camelKey] = value;
+        continue;
+      }
+
+      // 3. 常用别名映射
+      const aliased = PARAM_ALIASES[key];
+      if (aliased && schemaKeys.has(aliased)) {
+        result[aliased] = value;
+        continue;
+      }
+
+      // 4. 无匹配 — 保留原样（handler 可能有自定义处理）
+      result[key] = value;
+      unmatched.push(key);
+    }
+
+    if (unmatched.length > 0) {
+      this.#logger.debug(`[ToolRegistry] param normalization: unmatched keys [${unmatched.join(', ')}]`);
+    }
+
+    return result;
+  }
+
   /**
    * 检查工具是否存在
    */
@@ -86,6 +178,58 @@ export class ToolRegistry {
     return this.#tools.has(name);
   }
 
+  /**
+   * 转换为 Gemini functionDeclarations 格式
+   * 供 GoogleGeminiProvider.chatWithTools() 使用
+   *
+   * @param {string[]} [allowedTools] — 限制可用工具列表（不传则返回全部）
+   * @returns {Array<{name: string, description: string, parameters: object}>}
+   */
+  toFunctionDeclarations(allowedTools) {
+    const result = [];
+    for (const [name, tool] of this.#tools) {
+      if (allowedTools && !allowedTools.includes(name)) continue;
+      result.push({
+        name: tool.name,
+        description: tool.description || '',
+        parameters: this.#sanitizeSchemaForGemini(tool.parameters),
+      });
+    }
+    return result;
+  }
+
+  /**
+   * 清理 JSON Schema 使之兼容 Gemini API 的 OpenAPI 子集
+   * Gemini API 不支持某些 JSON Schema 扩展语法
+   */
+  #sanitizeSchemaForGemini(schema) {
+    if (!schema || typeof schema !== 'object') {
+      return { type: 'object', properties: {} };
+    }
+
+    const cleaned = { ...schema };
+
+    // 确保 type 存在
+    if (!cleaned.type) cleaned.type = 'object';
+
+    // 递归清理 properties
+    if (cleaned.properties) {
+      const props = {};
+      for (const [key, val] of Object.entries(cleaned.properties)) {
+        const prop = { ...val };
+        // 移除 Gemini 不支持的字段
+        delete prop.default;
+        delete prop.examples;
+        // 确保 type 存在
+        if (!prop.type) prop.type = 'string';
+        props[key] = prop;
+      }
+      cleaned.properties = props;
+    }
+
+    return cleaned;
+  }
+
   /**
    * 获取所有工具名
    */