autosnippet 2.6.0 → 2.7.1

package/lib/external/ai/AiProvider.js

@@ -66,6 +66,53 @@ export class AiProvider {
     return true;
   }
 
+  /**
+   * 是否支持原生结构化函数调用（非文本解析）
+   * 子类（如 GoogleGeminiProvider）覆盖返回 true
+   * @returns {boolean}
+   */
+  get supportsNativeToolCalling() {
+    return false;
+  }
+
+  /**
+   * 带工具声明的结构化对话 — 原生函数调用 API
+   *
+   * 支持原生函数调用的 Provider（Gemini / OpenAI / Claude）覆盖此方法,
+   * 返回结构化 functionCall 而非文本，ChatAgent 据此跳过正则解析。
+   *
+   * 默认实现降级为 chat()，由 ChatAgent 进行文本解析。
+   *
+   * 统一消息格式 (Provider-Agnostic):
+   *   - { role: 'user', content: 'text' }
+   *   - { role: 'assistant', content: 'text or null', toolCalls: [{id, name, args}] }
+   *   - { role: 'tool', toolCallId: 'id', name: 'tool_name', content: 'result string' }
+   *
+   * @param {string} prompt — 用户消息（仅在 messages 为空时使用）
+   * @param {object} opts
+   * @param {Array} opts.messages — 统一格式消息历史
+   * @param {Array} opts.toolSchemas — [{name, description, parameters}]
+   * @param {string} opts.toolChoice — 'auto' | 'required' | 'none'
+   * @param {string} [opts.systemPrompt] — 系统指令
+   * @param {number} [opts.temperature=0.7]
+   * @param {number} [opts.maxTokens=8192]
+   * @returns {Promise<{text: string|null, functionCalls: Array<{id: string, name: string, args: object}>|null}>}
+   */
+  async chatWithTools(prompt, opts = {}) {
+    // 默认降级: 忽略 tools/toolChoice，走纯文本 chat()
+    const messages = opts.messages || [];
+    const history = messages
+      .filter(m => m.role === 'user' || m.role === 'assistant')
+      .map(m => ({ role: m.role === 'assistant' ? 'assistant' : 'user', content: m.content || '' }));
+    const text = await this.chat(prompt, {
+      history,
+      systemPrompt: opts.systemPrompt,
+      temperature: opts.temperature,
+      maxTokens: opts.maxTokens,
+    });
+    return { text, functionCalls: null };
+  }
+
   /**
    * 从源码文件批量提取 Recipe 结构（AI 驱动）
    * 默认实现使用 chat() + 标准提示词；子类可覆盖以使用专用 API
@@ -372,7 +419,7 @@ Do NOT overwrite fields that are already filled (listed under "Already filled").
 # Fields to Fill (only if missing)
 
 1. **rationale** (string): Why this pattern exists; what design intent or problem it solves. 2-3 sentences.
-2. **knowledgeType** (string): One of: "code-standard", "code-pattern", "architecture", "best-practice", "code-relation", "inheritance", "call-chain", "data-flow", "module-dependency", "boundary-constraint", "code-style", "solution".
+2. **knowledgeType** (string): One of: "code-standard", "code-pattern", "architecture", "best-practice", "code-relation", "inheritance", "call-chain", "data-flow", "module-dependency", "boundary-constraint", "code-style", "solution", "anti-pattern".
 3. **complexity** (string): "beginner" | "intermediate" | "advanced". Evaluate usage difficulty.
 4. **scope** (string): "universal" (reusable anywhere) | "project-specific" (specific to this project) | "target-specific" (specific to one module/target).
 5. **steps** (array): Implementation steps. Each: { "title": "Step N title", "description": "What to do", "code": "optional code" }.
@@ -592,35 +639,51 @@ ${items}`;
     for (let attempt = 0; attempt <= retries; attempt++) {
       try {
         const result = await fn();
-        // 成功 → 重置熔断器
+        // 成功 → 完全重置熔断器（包括冷却时间）
         this._circuitFailures = 0;
         this._circuitState = 'CLOSED';
+        this._circuitCooldownMs = 30_000; // 重置冷却时间
         return result;
       } catch (err) {
-        // 连接超时提示代理配置
-        if (err.cause?.code === 'UND_ERR_CONNECT_TIMEOUT' || err.code === 'UND_ERR_CONNECT_TIMEOUT') {
-          const hasProxy = process.env.ASD_AI_PROXY || process.env.HTTPS_PROXY || process.env.ALL_PROXY;
-          if (!hasProxy) {
-            err.message += ' — 💡 可能需要配置代理: export HTTPS_PROXY=http://127.0.0.1:7890';
-          }
+        // ── 综合判断是否为可重试的网络/服务端错误 ──
+        const causeCode = err.cause?.code || '';
+        // 网络级错误：无 HTTP status，底层连接失败
+        const isNetworkError = !err.status && (
+          err.message === 'fetch failed'
+          || err.code === 'ECONNRESET' || causeCode === 'ECONNRESET'
+          || err.code === 'ECONNREFUSED' || causeCode === 'ECONNREFUSED'
+          || err.code === 'ENOTFOUND' || causeCode === 'ENOTFOUND'
+          || err.code === 'ECONNABORTED' || causeCode === 'ECONNABORTED'
+          || err.code === 'ETIMEDOUT' || causeCode === 'ETIMEDOUT'
+          || err.code === 'UND_ERR_CONNECT_TIMEOUT' || causeCode === 'UND_ERR_CONNECT_TIMEOUT'
+          || err.code === 'UND_ERR_SOCKET' || causeCode === 'UND_ERR_SOCKET'
+        );
+        const isRetryable = err.status === 429 || err.status >= 500 || isNetworkError;
+
+        // 首次失败记录详细诊断（含 cause）
+        if (attempt === 0 && (isNetworkError || err.cause)) {
+          this._log?.('warn', `[_withRetry] ${err.message} — cause: ${err.cause?.message || causeCode || 'unknown'}`);
         }
-        const isRetryable = err.status === 429 || err.status === 503 || err.code === 'ECONNRESET';
+
         if (attempt >= retries || !isRetryable) {
-          // 累计熔断失败计数
-          this._circuitFailures = (this._circuitFailures || 0) + 1;
-          if (this._circuitFailures >= (this._circuitThreshold || 5)) {
-            this._circuitState = 'OPEN';
-            this._circuitOpenedAt = Date.now();
-            // 逐级递增冷却时间: 30s → 60s → 120s（最大 5 分钟）
-            this._circuitCooldownMs = Math.min(
-              (this._circuitCooldownMs || 15000) * 2,
-              300_000,
-            );
-            this._log?.('warn', `[CircuitBreaker] OPEN — ${this._circuitFailures} consecutive failures, cooldown ${this._circuitCooldownMs / 1000}s`);
+          // 只有服务端错误 / 网络错误才累计熔断计数
+          // 客户端错误 (4xx 非 429) 不应触发熔断 — 那是请求本身的问题
+          const isServerError = isNetworkError || err.status === 429 || err.status >= 500 || !err.status;
+          if (isServerError) {
+            this._circuitFailures = (this._circuitFailures || 0) + 1;
+            if (this._circuitFailures >= (this._circuitThreshold || 5)) {
+              this._circuitState = 'OPEN';
+              this._circuitOpenedAt = Date.now();
+              // 先用当前冷却值，再递增给下次: 30s → 60s → 120s（最大 5 分钟）
+              const cooldown = this._circuitCooldownMs || 30_000;
+              this._log?.('warn', `[CircuitBreaker] OPEN — ${this._circuitFailures} consecutive failures, cooldown ${cooldown / 1000}s`);
+              this._circuitCooldownMs = Math.min(cooldown * 2, 300_000);
+            }
           }
           throw err;
         }
         const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+        this._log?.('info', `[_withRetry] attempt ${attempt + 1} failed (${err.message}), retrying in ${Math.round(delay / 1000)}s…`);
         await new Promise(r => setTimeout(r, delay));
       }
     }

package/lib/external/ai/providers/ClaudeProvider.js

@@ -1,5 +1,10 @@
 /**
  * ClaudeProvider - Anthropic Claude AI 提供商
+ *
+ * v2: 支持原生 Function Calling（结构化工具调用）
+ *     - 使用 Anthropic Messages API 的 tools + tool_choice 参数
+ *     - 响应中的 tool_use content blocks → 结构化 functionCall
+ *     - tool_result content blocks 用于回传工具执行结果
  */
 
 import { AiProvider } from '../AiProvider.js';
@@ -18,6 +23,13 @@ export class ClaudeProvider extends AiProvider {
     this.logger = Logger.getInstance();
   }
 
+  /**
+   * 是否支持原生结构化函数调用
+   */
+  get supportsNativeToolCalling() {
+    return true;
+  }
+
   async chat(prompt, context = {}) {
     const { history = [], temperature = 0.7, maxTokens = 4096 } = context;
     const messages = [];
@@ -39,6 +51,202 @@ export class ClaudeProvider extends AiProvider {
     return textBlock?.text || '';
   }
 
+  /**
+   * 带工具声明的结构化对话 — Anthropic Messages API Tool Use
+   *
+   * 接受统一消息格式，内部转换为 Anthropic Messages 格式。
+   *
+   * Anthropic 特殊之处:
+   *   - system prompt 是顶层 `system` 字段（非 message）
+   *   - assistant 消息的 content 是 content blocks 数组
+   *   - 工具结果通过 user 消息中的 tool_result blocks 传递
+   *   - tool_choice: {type: 'auto'|'any'|'tool'}（无 'none'，不传 tools 即可）
+   *
+   * @param {string} prompt — fallback prompt
+   * @param {object} opts — 统一参数
+   * @returns {Promise<{text: string|null, functionCalls: Array<{id, name, args}>|null}>}
+   */
+  async chatWithTools(prompt, opts = {}) {
+    const {
+      messages: unifiedMessages,
+      toolSchemas,
+      toolChoice = 'auto',
+      systemPrompt,
+      temperature = 0.7,
+      maxTokens = 4096,
+    } = opts;
+
+    // 统一消息 → Anthropic Messages 格式
+    const srcMessages = unifiedMessages?.length > 0
+      ? unifiedMessages
+      : [{ role: 'user', content: prompt }];
+
+    const messages = this.#convertMessages(srcMessages);
+
+    const body = {
+      model: this.model,
+      messages,
+      max_tokens: maxTokens,
+      temperature,
+    };
+
+    // system prompt → 顶层字段
+    if (systemPrompt) {
+      body.system = systemPrompt;
+    }
+
+    // 工具声明 + tool_choice
+    // toolChoice='none' 时不传 tools（Anthropic 没有 'none' tool_choice）
+    if (toolChoice !== 'none' && toolSchemas?.length > 0) {
+      body.tools = toolSchemas.map(s => ({
+        name: s.name,
+        description: s.description || '',
+        input_schema: s.parameters || { type: 'object', properties: {} },
+      }));
+
+      if (toolChoice === 'required') {
+        body.tool_choice = { type: 'any' };
+      } else {
+        body.tool_choice = { type: 'auto' };
+      }
+    }
+
+    const data = await this._post(`${CLAUDE_BASE}/messages`, body);
+    return this.#parseToolResponse(data);
+  }
+
+  // ─── 内部转换方法 ──────────────────────
+
+  /**
+   * 统一消息格式 → Anthropic Messages 格式
+   *
+   * - user → {role: 'user', content: 'text'}
+   * - assistant → {role: 'assistant', content: [{type:'text'}, {type:'tool_use'}...]}
+   * - tool → grouped into {role: 'user', content: [{type:'tool_result'}...]}
+   *
+   * Anthropic 要求消息交替 user/assistant。连续 tool results 合并为一个 user 消息。
+   * 连续同角色消息（如 L2/L3 压缩后的摘要）自动合并以避免 400 错误。
+   */
+  #convertMessages(messages) {
+    const result = [];
+
+    /**
+     * 推入 result，如果上一个 entry 同角色则合并 content
+     */
+    const pushOrMerge = (entry) => {
+      const last = result[result.length - 1];
+      if (last && last.role === entry.role) {
+        // Anthropic content 可以是 string 或 array
+        const lastContent = Array.isArray(last.content)
+          ? last.content
+          : [{ type: 'text', text: last.content || '' }];
+        const newContent = Array.isArray(entry.content)
+          ? entry.content
+          : [{ type: 'text', text: entry.content || '' }];
+        last.content = [...lastContent, ...newContent];
+      } else {
+        result.push(entry);
+      }
+    };
+
+    let i = 0;
+
+    while (i < messages.length) {
+      const msg = messages[i];
+
+      if (msg.role === 'user') {
+        pushOrMerge({ role: 'user', content: msg.content || '' });
+        i++;
+      } else if (msg.role === 'assistant') {
+        const content = [];
+        if (msg.content) content.push({ type: 'text', text: msg.content });
+        if (msg.toolCalls?.length > 0) {
+          for (const tc of msg.toolCalls) {
+            content.push({
+              type: 'tool_use',
+              id: tc.id,
+              name: tc.name,
+              input: tc.args || {},
+            });
+          }
+        }
+        pushOrMerge({
+          role: 'assistant',
+          content: content.length > 0 ? content : [{ type: 'text', text: '' }],
+        });
+        i++;
+      } else if (msg.role === 'tool') {
+        // 收集连续 tool results → 合并为一个 user 消息
+        const toolResults = [];
+        while (i < messages.length && messages[i].role === 'tool') {
+          toolResults.push({
+            type: 'tool_result',
+            tool_use_id: messages[i].toolCallId,
+            content: messages[i].content || '',
+          });
+          i++;
+        }
+        pushOrMerge({ role: 'user', content: toolResults });
+      } else {
+        i++; // skip unknown roles
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * 解析 Anthropic Messages API 响应 — 提取 tool_use 或 text
+   *
+   * Anthropic 返回格式:
+   *   content[]: { type: 'text', text } | { type: 'tool_use', id, name, input }
+   *   stop_reason: 'end_turn' | 'tool_use' | 'max_tokens'
+   */
+  #parseToolResponse(data) {
+    // 提取 token 用量 (Claude usage)
+    const usage = data?.usage
+      ? {
+          inputTokens: data.usage.input_tokens || 0,
+          outputTokens: data.usage.output_tokens || 0,
+          totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+        }
+      : null;
+
+    if (!data?.content?.length) {
+      return { text: '', functionCalls: null, usage };
+    }
+
+    const functionCalls = [];
+    const textParts = [];
+
+    for (const block of data.content) {
+      if (block.type === 'tool_use') {
+        functionCalls.push({
+          id: block.id,
+          name: block.name,
+          args: block.input || {},
+        });
+      } else if (block.type === 'text') {
+        textParts.push(block.text);
+      }
+    }
+
+    if (functionCalls.length > 0) {
+      this.logger.debug(`[Claude] native function calls: ${functionCalls.map(fc => fc.name).join(', ')}`);
+      return {
+        text: textParts.length > 0 ? textParts.join('\n') : null,
+        functionCalls,
+        usage,
+      };
+    }
+
+    return {
+      text: textParts.join('\n'),
+      functionCalls: null,
+      usage,
+    };
+  }
+
   async summarize(code) {
     const prompt = `请对以下代码生成结构化摘要，返回 JSON 格式 {title, description, language, patterns: [], keyAPIs: []}:\n\n${code}`;
     const text = await this.chat(prompt, { temperature: 0.3 });

package/lib/external/ai/providers/GoogleGeminiProvider.js

@@ -1,6 +1,10 @@
 /**
  * GoogleGeminiProvider - Google Gemini AI 提供商
  * 直接调用 REST API（不依赖 SDK）
+ *
+ * v3: 统一消息格式 — chatWithTools() 接受 Provider-Agnostic 消息
+ *     内部自动转换为 Gemini 原生 contents / functionDeclarations 格式
+ *     支持 toolChoice: 'auto' | 'required' | 'none'
  */
 
 import { AiProvider } from '../AiProvider.js';
@@ -18,9 +22,16 @@ export class GoogleGeminiProvider extends AiProvider {
     this.logger = Logger.getInstance();
   }
 
+  /**
+   * 是否支持原生结构化函数调用
+   */
+  get supportsNativeToolCalling() {
+    return true;
+  }
+
   async chat(prompt, context = {}) {
     return this._withRetry(async () => {
-      const { history = [], temperature = 0.7, maxTokens = 8192 } = context;
+      const { history = [], temperature = 0.7, maxTokens = 8192, systemPrompt } = context;
       const contents = [];
 
       for (const h of history) {
@@ -36,12 +47,247 @@ export class GoogleGeminiProvider extends AiProvider {
         },
       };
 
+      // systemInstruction 支持（chat 也可用 systemPrompt）
+      if (systemPrompt) {
+        body.systemInstruction = { parts: [{ text: systemPrompt }] };
+      }
+
       const url = `${GEMINI_BASE}/models/${this.model}:generateContent?key=${this.apiKey}`;
       const data = await this._post(url, body);
       return data?.candidates?.[0]?.content?.parts?.[0]?.text || '';
     });
   }
 
+  /**
+   * 带工具声明的结构化对话 — Gemini 原生 Function Calling
+   *
+   * 接受统一消息格式，内部转换为 Gemini 原生 contents 格式。
+   *
+   * @param {string} prompt — 未使用 messages 时的 fallback prompt
+   * @param {object} opts
+   * @param {Array}  opts.messages — 统一格式消息
+   * @param {Array}  opts.toolSchemas — [{name, description, parameters}]
+   * @param {string} opts.toolChoice — 'auto' | 'required' | 'none'
+   * @param {string} [opts.systemPrompt]
+   * @param {number} [opts.temperature=0.7]
+   * @param {number} [opts.maxTokens=8192]
+   * @returns {Promise<{text: string|null, functionCalls: Array<{id, name, args}>|null}>}
+   */
+  async chatWithTools(prompt, opts = {}) {
+    return this._withRetry(async () => {
+      const {
+        messages,
+        toolSchemas,
+        toolChoice = 'auto',
+        systemPrompt,
+        temperature = 0.7,
+        maxTokens = 8192,
+      } = opts;
+
+      // 统一消息 → Gemini contents
+      const contents = messages?.length > 0
+        ? this.#convertMessages(messages)
+        : [{ role: 'user', parts: [{ text: prompt }] }];
+
+      const body = {
+        contents,
+        generationConfig: {
+          temperature,
+          maxOutputTokens: maxTokens,
+        },
+      };
+
+      // 工具声明: 标准 schema → Gemini functionDeclarations
+      if (toolSchemas?.length > 0) {
+        body.tools = [{
+          functionDeclarations: toolSchemas.map(s => this.#toFunctionDeclaration(s)),
+        }];
+      }
+
+      // toolChoice → Gemini mode
+      body.toolConfig = {
+        functionCallingConfig: { mode: this.#toGeminiMode(toolChoice) },
+      };
+
+      // 系统指令
+      if (systemPrompt) {
+        body.systemInstruction = { parts: [{ text: systemPrompt }] };
+      }
+
+      const url = `${GEMINI_BASE}/models/${this.model}:generateContent?key=${this.apiKey}`;
+      const data = await this._post(url, body);
+
+      return this.#parseToolResponse(data);
+    });
+  }
+
+  // ─── 内部转换方法 ──────────────────────
+
+  /**
+   * 统一消息格式 → Gemini contents
+   * - user → {role: 'user', parts: [{text}]}
+   * - assistant → {role: 'model', parts: [{text}, {functionCall}...]}
+   * - tool → grouped into {role: 'user', parts: [{functionResponse}...]}
+   *
+   * Gemini 要求严格交替 user/model 角色。
+   * 连续同角色消息（如 L2/L3 压缩后的摘要）自动合并 parts 以避免 400 错误。
+   */
+  #convertMessages(messages) {
+    const contents = [];
+    let pendingToolResults = [];
+
+    /**
+     * 推入 contents，如果上一个 entry 同角色则合并 parts
+     */
+    const pushOrMerge = (entry) => {
+      const last = contents[contents.length - 1];
+      if (last && last.role === entry.role) {
+        last.parts.push(...entry.parts);
+      } else {
+        contents.push(entry);
+      }
+    };
+
+    for (const msg of messages) {
+      if (msg.role === 'tool') {
+        // 收集连续 tool results → 将在下一个非 tool 消息前或末尾 flush
+        pendingToolResults.push({
+          functionResponse: {
+            name: msg.name,
+            response: { result: msg.content || '' },
+          },
+        });
+        continue;
+      }
+
+      // Flush pending tool results before non-tool message
+      if (pendingToolResults.length > 0) {
+        pushOrMerge({ role: 'user', parts: pendingToolResults });
+        pendingToolResults = [];
+      }
+
+      if (msg.role === 'user') {
+        pushOrMerge({ role: 'user', parts: [{ text: msg.content || '' }] });
+      } else if (msg.role === 'assistant') {
+        const parts = [];
+        if (msg.content) parts.push({ text: msg.content });
+        if (msg.toolCalls?.length > 0) {
+          for (const tc of msg.toolCalls) {
+            parts.push({ functionCall: { name: tc.name, args: tc.args || {} } });
+          }
+        }
+        if (parts.length > 0) pushOrMerge({ role: 'model', parts });
+      }
+    }
+
+    // Flush remaining tool results
+    if (pendingToolResults.length > 0) {
+      pushOrMerge({ role: 'user', parts: pendingToolResults });
+    }
+
+    return contents;
+  }
+
+  /**
+   * toolChoice → Gemini mode
+   */
+  #toGeminiMode(toolChoice) {
+    switch (toolChoice) {
+      case 'required': return 'ANY';
+      case 'none':     return 'NONE';
+      default:         return 'AUTO';
+    }
+  }
+
+  /**
+   * 标准 tool schema → Gemini functionDeclaration
+   */
+  #toFunctionDeclaration(schema) {
+    return {
+      name: schema.name,
+      description: schema.description || '',
+      parameters: this.#sanitizeSchemaForGemini(schema.parameters),
+    };
+  }
+
+  /**
+   * 清理 JSON Schema 使之兼容 Gemini API 的 OpenAPI 子集
+   */
+  #sanitizeSchemaForGemini(schema) {
+    if (!schema || typeof schema !== 'object') {
+      return { type: 'object', properties: {} };
+    }
+
+    const cleaned = { ...schema };
+    if (!cleaned.type) cleaned.type = 'object';
+
+    if (cleaned.properties) {
+      const props = {};
+      for (const [key, val] of Object.entries(cleaned.properties)) {
+        const prop = { ...val };
+        delete prop.default;
+        delete prop.examples;
+        if (!prop.type) prop.type = 'string';
+        props[key] = prop;
+      }
+      cleaned.properties = props;
+    }
+
+    return cleaned;
+  }
+
+  /**
+   * 解析 Gemini API 响应 — 提取 functionCall 或 text
+   * 返回统一格式（含生成的 id）
+   */
+  #parseToolResponse(data) {
+    const content = data?.candidates?.[0]?.content;
+
+    // 提取 token 用量 (Gemini usageMetadata)
+    const usage = data?.usageMetadata
+      ? {
+          inputTokens: data.usageMetadata.promptTokenCount || 0,
+          outputTokens: data.usageMetadata.candidatesTokenCount || 0,
+          totalTokens: data.usageMetadata.totalTokenCount || 0,
+        }
+      : null;
+
+    if (!content || !content.parts || content.parts.length === 0) {
+      return { text: '', functionCalls: null, usage };
+    }
+
+    const functionCalls = [];
+    const textParts = [];
+    let fcIndex = 0;
+
+    for (const part of content.parts) {
+      if (part.functionCall) {
+        functionCalls.push({
+          id: `gemini_fc_${Date.now()}_${fcIndex++}`,
+          name: part.functionCall.name,
+          args: part.functionCall.args || {},
+        });
+      } else if (part.text) {
+        textParts.push(part.text);
+      }
+    }
+
+    if (functionCalls.length > 0) {
+      this.logger.debug(`[GeminiProvider] native function calls: ${functionCalls.map(fc => fc.name).join(', ')}`);
+      return {
+        text: textParts.length > 0 ? textParts.join('\n') : null,
+        functionCalls,
+        usage,
+      };
+    }
+
+    return {
+      text: textParts.join('\n'),
+      functionCalls: null,
+      usage,
+    };
+  }
+
   async summarize(code) {
     const prompt = `请对以下代码生成结构化摘要，返回 JSON 格式 {title, description, language, patterns: [], keyAPIs: []}:\n\n${code}`;
     const text = await this.chat(prompt, { temperature: 0.3 });