autosnippet 3.2.7 → 3.2.9

package/lib/core/ast/lang-typescript.js

@@ -4,8 +4,13 @@
  *
  * 提取: class, interface, type alias, enum, function, method, property, import, export
  * 模式检测: Singleton, Factory, Observer, React Hook/Component, Middleware, Decorator
+ *
+ * Phase 5: 新增 ImportRecord 结构化导入 + extractCallSites 调用点提取
  */
 
+import { ImportRecord } from '../analysis/ImportRecord.js';
+import { extractCallSitesTS } from '../analysis/CallSiteExtractor.js';
+
 function walkTypeScript(root, ctx) {
   _walkTSNode(root, ctx, null);
 }
@@ -20,7 +25,9 @@ function _walkTSNode(node, ctx, parentClassName) {
           (c) => c.type === 'string' || c.type === 'string_fragment'
         );
         if (source) {
-          ctx.imports.push(source.text.replace(/^['"]|['"]$/g, ''));
+          const importPath = source.text.replace(/^['"]|['"]$/g, '');
+          const importMeta = _parseImportClause(child);
+          ctx.imports.push(new ImportRecord(importPath, importMeta));
         }
         break;
       }
@@ -123,6 +130,12 @@ function _walkTSClassBody(body, ctx, className) {
       case 'method_definition': {
         const m = _parseTSMethod(child, className);
         ctx.methods.push(m);
+
+        // Phase 5.3: Extract constructor parameter properties (DI pattern)
+        if (m.name === 'constructor') {
+          const constructorProps = _extractTSConstructorProperties(child, className);
+          ctx.properties.push(...constructorProps);
+        }
         break;
       }
 
@@ -287,15 +300,111 @@ function _parseTSProperty(node, className) {
   const isStatic = node.text.trimStart().startsWith('static');
   const isReadonly = node.text.includes('readonly');
 
+  // Phase 5.3: Extract type annotation for DI/RTA resolution
+  const typeAnnotation = _extractTypeAnnotation(node);
+
+  // Phase 5.3: Extract decorators on properties (e.g. @Inject)
+  const decorators = [];
+  for (const child of node.namedChildren) {
+    if (child.type === 'decorator') {
+      decorators.push(child.text);
+    }
+  }
+
   return {
     name,
     className,
     isStatic,
     isReadonly,
+    typeAnnotation,
+    decorators: decorators.length > 0 ? decorators : undefined,
     line: node.startPosition.row + 1,
   };
 }
 
+/**
+ * Phase 5.3: Extract type name from a type_annotation node
+ * Handles: type_identifier, generic_type, nested_type_identifier, union_type
+ * Strips generics: UserRepo<T> → UserRepo
+ *
+ * @param {object} parentNode — AST node that may contain a type_annotation child
+ * @returns {string|null}
+ */
+function _extractTypeAnnotation(parentNode) {
+  const typeAnnotNode = parentNode.namedChildren.find((c) => c.type === 'type_annotation');
+  if (!typeAnnotNode) return null;
+
+  const typeNode = typeAnnotNode.namedChildren.find(
+    (c) =>
+      c.type === 'type_identifier' ||
+      c.type === 'generic_type' ||
+      c.type === 'nested_type_identifier'
+  );
+  if (!typeNode) return null;
+
+  // Strip generics: Repository<User> → Repository
+  const text = typeNode.text;
+  const bracketIdx = text.indexOf('<');
+  return bracketIdx > 0 ? text.slice(0, bracketIdx) : text;
+}
+
+/**
+ * Phase 5.3: Extract constructor parameter properties (TypeScript DI pattern)
+ *
+ * TypeScript shorthand: constructor(private userRepo: UserRepo)
+ * creates a class property `userRepo` with type `UserRepo`
+ *
+ * @param {object} constructorNode — method_definition node with name "constructor"
+ * @param {string} className
+ * @returns {Array} — property objects
+ */
+function _extractTSConstructorProperties(constructorNode, className) {
+  const properties = [];
+  const params = constructorNode.namedChildren.find((c) => c.type === 'formal_parameters');
+  if (!params) return properties;
+
+  for (const param of params.namedChildren) {
+    if (param.type !== 'required_parameter' && param.type !== 'optional_parameter') continue;
+
+    // Check for accessibility modifier (public, private, protected) or readonly
+    // These turn constructor params into class properties
+    const hasAccessibility = param.namedChildren.some(
+      (c) => c.type === 'accessibility_modifier' || c.type === 'override_modifier'
+    );
+    const hasReadonly = param.text.includes('readonly');
+
+    if (!hasAccessibility && !hasReadonly) continue; // Not a property declaration
+
+    const nameNode = param.namedChildren.find((c) => c.type === 'identifier');
+    const name = nameNode?.text;
+    if (!name) continue;
+
+    // Extract type annotation
+    const typeAnnotation = _extractTypeAnnotation(param);
+
+    // Extract decorators on parameter (e.g. @Inject)
+    const decorators = [];
+    for (const child of param.namedChildren) {
+      if (child.type === 'decorator') {
+        decorators.push(child.text);
+      }
+    }
+
+    properties.push({
+      name,
+      className,
+      isStatic: false,
+      isReadonly: hasReadonly,
+      typeAnnotation,
+      isConstructorParam: true,
+      decorators: decorators.length > 0 ? decorators : undefined,
+      line: param.startPosition.row + 1,
+    });
+  }
+
+  return properties;
+}
+
 function _parseTSVariableDecl(node, ctx, parentClassName) {
   for (const child of node.namedChildren) {
     if (child.type === 'variable_declarator') {
@@ -315,9 +424,187 @@ function _parseTSVariableDecl(node, ctx, parentClassName) {
           line: child.startPosition.row + 1,
           kind: 'definition',
         });
+        continue;
+      }
+
+      // CJS require(): const x = require('path') / const { a, b } = require('path')
+      // Dynamic import(): const mod = await import('./module')
+      const callNode = child.namedChildren.find((c) => c.type === 'call_expression');
+      if (callNode) {
+        const requireImport = _parseCJSRequire(callNode, child);
+        if (requireImport) {
+          ctx.imports.push(requireImport);
+          continue;
+        }
+        const dynamicImport = _parseDynamicImport(callNode, child);
+        if (dynamicImport) {
+          ctx.imports.push(dynamicImport);
+          continue;
+        }
+      }
+      // await import() — await wraps the call_expression
+      const awaitNode = child.namedChildren.find((c) => c.type === 'await_expression');
+      if (awaitNode) {
+        const awaitedCall = awaitNode.namedChildren.find((c) => c.type === 'call_expression');
+        if (awaitedCall) {
+          const dynamicImport = _parseDynamicImport(awaitedCall, child);
+          if (dynamicImport) {
+            ctx.imports.push(dynamicImport);
+          }
+        }
+      }
+    }
+  }
+}
+
+// ── TS/JS Import 解析 ──
+
+/**
+ * 从 import_statement 节点解析导入子句的结构化信息
+ *
+ * @param {TreeSitterNode} importNode — import_statement 节点
+ * @returns {{ symbols: string[], kind: string, alias: string|null, isTypeOnly: boolean }}
+ */
+function _parseImportClause(importNode) {
+  const symbols = [];
+  let kind = 'side-effect';
+  let alias = null;
+  let isTypeOnly = false;
+
+  // 检查 type-only import: import type { ... }
+  if (importNode.text.trimStart().startsWith('import type')) {
+    isTypeOnly = true;
+  }
+
+  for (const child of importNode.namedChildren) {
+    if (child.type === 'import_clause') {
+      for (const clauseChild of child.namedChildren) {
+        if (clauseChild.type === 'identifier') {
+          // default import: import Foo from '...'
+          symbols.push(clauseChild.text);
+          kind = 'default';
+        } else if (clauseChild.type === 'named_imports') {
+          // named imports: import { A, B as C } from '...'
+          kind = 'named';
+          for (const specifier of clauseChild.namedChildren) {
+            if (specifier.type === 'import_specifier') {
+              // 收集 specifier 中的所有 identifier / type_identifier
+              const identifiers = specifier.namedChildren.filter(
+                (c) => c.type === 'identifier' || c.type === 'type_identifier'
+              );
+              // import { A as B } → identifiers = [A, B] → push B (本地名)
+              // import { A }     → identifiers = [A]     → push A
+              if (identifiers.length > 0) {
+                symbols.push(identifiers[identifiers.length - 1].text);
+              }
+            }
+          }
+        } else if (clauseChild.type === 'namespace_import') {
+          // namespace import: import * as M from '...'
+          kind = 'namespace';
+          symbols.push('*');
+          const aliasNode = clauseChild.namedChildren.find((c) => c.type === 'identifier');
+          if (aliasNode) {
+            alias = aliasNode.text;
+          }
+        }
+      }
+    }
+  }
+
+  return { symbols, kind, alias, isTypeOnly };
+}
+
+/**
+ * 解析 CJS require() 调用: const x = require('path') / const { a, b } = require('path')
+ *
+ * @param {TreeSitterNode} callNode — call_expression 节点
+ * @param {TreeSitterNode} declaratorNode — variable_declarator 节点 (包含 lhs 绑定)
+ * @returns {ImportRecord|null}
+ */
+function _parseCJSRequire(callNode, declaratorNode) {
+  // 检查 callee 是否为 'require'
+  const callee = callNode.namedChildren[0];
+  if (!callee || callee.type !== 'identifier' || callee.text !== 'require') return null;
+
+  // 提取 require 参数中的路径字符串
+  const args = callNode.namedChildren.find((c) => c.type === 'arguments');
+  if (!args || args.namedChildCount === 0) return null;
+
+  const firstArg = args.namedChildren[0];
+  if (!firstArg || (firstArg.type !== 'string' && firstArg.type !== 'template_string')) return null;
+
+  const importPath = firstArg.text.replace(/^['"`]|['"`]$/g, '');
+  if (!importPath) return null;
+
+  // 解析 lhs 绑定模式
+  const lhs = declaratorNode.namedChildren[0]; // identifier or object_pattern
+  if (!lhs) return new ImportRecord(importPath, { symbols: [], kind: 'side-effect' });
+
+  if (lhs.type === 'identifier') {
+    // const express = require('express') → namespace import
+    return new ImportRecord(importPath, {
+      symbols: ['*'],
+      kind: 'namespace',
+      alias: lhs.text,
+    });
+  }
+
+  if (lhs.type === 'object_pattern') {
+    // const { readFile, writeFile } = require('fs')
+    const symbols = [];
+    for (const prop of lhs.namedChildren) {
+      if (prop.type === 'shorthand_property_identifier_pattern' || prop.type === 'shorthand_property_identifier') {
+        symbols.push(prop.text);
+      } else if (prop.type === 'pair_pattern' || prop.type === 'pair') {
+        // { readFile: rf } → 使用本地名 rf
+        const identifiers = prop.namedChildren.filter((c) => c.type === 'identifier');
+        if (identifiers.length > 0) {
+          symbols.push(identifiers[identifiers.length - 1].text);
+        }
       }
     }
+    return new ImportRecord(importPath, {
+      symbols: symbols.length > 0 ? symbols : ['*'],
+      kind: symbols.length > 0 ? 'named' : 'namespace',
+    });
   }
+
+  // 其他 lhs 模式 (如数组解构), 作为 side-effect 处理
+  return new ImportRecord(importPath, { symbols: [], kind: 'side-effect' });
+}
+
+/**
+ * 解析动态 import() 表达式: const mod = await import('./module')
+ *
+ * @param {TreeSitterNode} callNode — call_expression 节点
+ * @param {TreeSitterNode} declaratorNode — variable_declarator 节点
+ * @returns {ImportRecord|null}
+ */
+function _parseDynamicImport(callNode, declaratorNode) {
+  // 动态 import() 在 tree-sitter 中解析为 call_expression, callee 是 'import'
+  const callee = callNode.namedChildren[0];
+  if (!callee) return null;
+  // tree-sitter 可能将 import() 解析为 identifier('import') 或 special node
+  if (callee.text !== 'import') return null;
+
+  const args = callNode.namedChildren.find((c) => c.type === 'arguments');
+  if (!args || args.namedChildCount === 0) return null;
+
+  const firstArg = args.namedChildren[0];
+  if (!firstArg || (firstArg.type !== 'string' && firstArg.type !== 'template_string')) return null;
+
+  const importPath = firstArg.text.replace(/^['"`]|['"`]$/g, '');
+  if (!importPath) return null;
+
+  const lhs = declaratorNode?.namedChildren?.[0];
+  const alias = lhs?.type === 'identifier' ? lhs.text : null;
+
+  return new ImportRecord(importPath, {
+    symbols: ['*'],
+    kind: 'dynamic',
+    alias,
+  });
 }
 
 // ── TS/JS 模式检测 ──
@@ -477,6 +764,7 @@ export const plugin = {
   getGrammar,
   walk: walkTypeScript,
   detectPatterns: detectTSPatterns,
+  extractCallSites: extractCallSitesTS,
   extensions: ['.ts'],
 };
 
@@ -493,5 +781,6 @@ export const tsxPlugin = {
   getGrammar: getTsxGrammar,
   walk: walkTypeScript,
   detectPatterns: detectTSPatterns,
+  extractCallSites: extractCallSitesTS,
   extensions: ['.tsx'],
 };

package/lib/core/discovery/index.js

@@ -11,7 +11,7 @@ import { JvmDiscoverer } from './JvmDiscoverer.js';
 import { NodeDiscoverer } from './NodeDiscoverer.js';
 import { PythonDiscoverer } from './PythonDiscoverer.js';
 import { RustDiscoverer } from './RustDiscoverer.js';
-import { SpmDiscoverer } from './SpmDiscoverer.js';
+import { SpmDiscoverer } from '../../platform/ios/spm/SpmDiscoverer.js';
 
 /** @type {DiscovererRegistry|null} */
 let _registry = null;
@@ -53,4 +53,4 @@ export { NodeDiscoverer } from './NodeDiscoverer.js';
 export { ProjectDiscoverer } from './ProjectDiscoverer.js';
 export { PythonDiscoverer } from './PythonDiscoverer.js';
 export { RustDiscoverer } from './RustDiscoverer.js';
-export { SpmDiscoverer } from './SpmDiscoverer.js';
+export { SpmDiscoverer } from '../../platform/ios/spm/SpmDiscoverer.js';

package/lib/external/ai/AiProvider.js

@@ -20,6 +20,51 @@ export class AiProvider {
     this._circuitThreshold = config.circuitThreshold || 5; // 触发熔断的连续失败次数
     this._circuitOpenedAt = 0; // 熔断打开时间
     this._circuitCooldownMs = 30_000; // 初始冷却 30 秒
+
+    // ── Provider 级全局并发闸门 + 429 冷却窗 ──
+    this._maxConcurrency = Math.max(1, Number(config.maxConcurrency || process.env.ASD_AI_MAX_CONCURRENCY || 4));
+    this._activeRequests = 0;
+    this._requestQueue = [];
+    this._rateLimitedUntil = 0;
+  }
+
+  async _acquireRequestSlot() {
+    if (this._activeRequests < this._maxConcurrency) {
+      this._activeRequests += 1;
+      return;
+    }
+    await new Promise((resolve) => this._requestQueue.push(resolve));
+    this._activeRequests += 1;
+  }
+
+  _releaseRequestSlot() {
+    this._activeRequests = Math.max(0, this._activeRequests - 1);
+    const next = this._requestQueue.shift();
+    if (next) {
+      next();
+    }
+  }
+
+  async _waitForRateLimitWindow() {
+    const waitMs = (this._rateLimitedUntil || 0) - Date.now();
+    if (waitMs > 0) {
+      await new Promise((r) => setTimeout(r, waitMs));
+    }
+  }
+
+  _setRateLimitWindow(waitMs) {
+    const safeWait = Math.max(0, Number(waitMs) || 0);
+    if (safeWait <= 0) {
+      return;
+    }
+    const until = Date.now() + safeWait;
+    if (until > (this._rateLimitedUntil || 0)) {
+      this._rateLimitedUntil = until;
+      this._log?.(
+        'warn',
+        `[RateLimit] ${this.name} enters cooldown ${Math.round(safeWait / 1000)}s (global)`
+      );
+    }
   }
 
   /**
@@ -81,9 +126,9 @@ export class AiProvider {
    * 带工具声明的结构化对话 — 原生函数调用 API
    *
    * 支持原生函数调用的 Provider（Gemini / OpenAI / Claude）覆盖此方法,
-   * 返回结构化 functionCall 而非文本，ChatAgent 据此跳过正则解析。
+   * 返回结构化 functionCall 而非文本，AgentRuntime 据此跳过正则解析。
    *
-   * 默认实现降级为 chat()，由 ChatAgent 进行文本解析。
+   * 默认实现降级为 chat()，由 AgentRuntime 进行文本解析。
    *
    * 统一消息格式 (Provider-Agnostic):
    *   - { role: 'user', content: 'text' }
@@ -150,35 +195,6 @@ export class AiProvider {
     return this.extractJSON(response, openChar, closeChar);
   }
 
-  /**
-   * 从源码文件批量提取 Recipe 结构（AI 驱动）
-   * 默认实现使用 chat() + 标准提示词；子类可覆盖以使用专用 API
-   * @param {string} targetName - SPM Target 名称
-   * @param {Array<{name:string,content:string}>} filesContent
-   * @param {object} [options] - 可选参数
-   * @returns {Promise<Array<object>>}
-   */
-  async extractRecipes(targetName, filesContent, options = {}) {
-    const prompt = this._buildExtractPrompt(targetName, filesContent, options);
-    const parsed = await this.chatWithStructuredOutput(prompt, {
-      openChar: '[',
-      closeChar: ']',
-      temperature: 0.3,
-      maxTokens: 32768,
-    });
-    if (!Array.isArray(parsed)) {
-      this._log(
-        'warn',
-        `[extractRecipes] structured output parse failed for target: ${targetName}`
-      );
-      return [];
-    }
-    if (parsed.length === 0) {
-      this._log('info', `[extractRecipes] AI returned empty array for target: ${targetName}`);
-    }
-    return parsed;
-  }
-
   /**
    * 内部日志辅助（子类可通过 this.logger 覆盖）
    */
@@ -193,147 +209,6 @@ export class AiProvider {
     }
   }
 
-  /**
-   * 构建 extractRecipes 标准提示词（语言自适应 + Skill 增强）
-   */
-  _buildExtractPrompt(targetName, filesContent, options = {}) {
-    const files = filesContent.map((f) => `--- FILE: ${f.name} ---\n${f.content}`).join('\n\n');
-
-    // 检测文件主要语言
-    const langProfile = this._detectLanguageProfile(filesContent);
-
-    // AST 代码结构分析注入 — 帮助 AI 理解继承体系、设计模式、代码规模
-    const astSection = options.astContext
-      ? `\n# Code Structure Analysis (AST)\nThe following is a Tree-sitter AST analysis of the project. Use this structural context to better understand class hierarchies, design patterns, and code quality when extracting recipes:\n\n${options.astContext.substring(0, 3000)}\n`
-      : '';
-
-    // 用户语言偏好 — 控制 AI 输出人类可读字段的语言
-    const langInstruction = this._buildLangInstruction(options.lang);
-
-    // comprehensive 模式：全量分析整个文件，不跳过任何有意义的方法
-    if (options.comprehensive) {
-      return `# Role
-You are a ${langProfile.role} performing a **comprehensive full-file analysis**.
-
-# Goal
-Thoroughly analyze ALL code in "${targetName}" and create Recipe entries for **every significant method, function, or code block**.
-This is a full-file analysis — do NOT skip methods just because they seem "simple" or "standard".
-${astSection}
-
-# What to extract
-- **Every** complete method/function with 5+ lines of implementation
-- Initialization and configuration methods (init, viewDidLoad, setup, configure)
-- Event handlers and action methods
-- Data processing and business logic
-- Protocol/delegate implementations
-- ANY code block that a developer might reference, learn from, or reuse
-
-# Extraction Rules
-- Extract **BROADLY** — include all meaningful code units, not just "clever" or "novel" patterns
-- Each recipe must be a **complete, standalone** code unit with full signature and body
-- Put the complete code in \`content.pattern\`, and a meaningful project writeup in \`content.markdown\`
-- Preserve the file's actual code. Use \`<#placeholder#>\` ONLY for literal strings/values a developer would customize
-- Every recipe must be traceable to real code in the file. Do NOT invent code
-- Include relevant \`headers\` (import/require lines) that the code depends on
-- You **MUST** extract at least ONE recipe — every source file has something worth capturing
-- For each recipe, provide a concise \`doClause\` (imperative sentence) and a \`topicHint\` group label
-
-${langProfile.extractionExamples}
-
-# Output (JSON Array)
-Each item MUST use the following V3 KnowledgeEntry structure:
-- title (string): Descriptive English name
-- description (string): 2-3 sentences explaining what this code does, written as a project-specific guide
-- trigger (string): @shortcut (kebab-case, e.g. "@url-parser")
-- kind (string): "rule" | "pattern" | "fact" — rule = always-do/never-do, pattern = reusable recipe with code, fact = reference info
-- knowledgeType (string): "code-pattern" | "architecture" | "best-practice" | "code-standard" | "code-relation" | "data-flow" | "event-and-data-flow" | "module-dependency" | "boundary-constraint" | "code-style" | "solution" | "anti-pattern"
-- complexity (string): "basic" | "intermediate" | "advanced"
-- scope (string): "universal" | "project-specific" | "team-convention"
-- category: ${langProfile.categories}
-- language: "${langProfile.primaryLanguage}"
-- content (object): { "pattern": "<complete function/method/class from the file>", "markdown": "<project-specific writeup: what this pattern does, when to use it, key design decisions>", "rationale": "<why this pattern is designed this way — design trade-offs, alternatives considered>" }
-- reasoning (object): { "whyStandard": "<why this is a standard/best-practice worth following>", "sources": ["<source file names>"], "confidence": <0.0-1.0> }
-- headers (string[]): Required import/require lines
-- tags (string[]): Search keywords
-- doClause (string): One-sentence imperative: what to do (e.g. "Use dependency injection via constructor")
-- dontClause (string): What NOT to do (e.g. "Don't instantiate services with new directly")
-- whenClause (string): When this pattern applies (e.g. "When creating a new ViewController subclass")
-- topicHint (string): Group label for related patterns (e.g. "Networking", "UI-Layout", "Error-Handling")
-- coreCode (string): Minimal 3-10 line code skeleton that captures the essence. Must be syntactically complete — balanced brackets/parentheses, never start with } or ) and never end with { or (
-- usageGuide (string): ### 章节格式使用指南 — 描述何时使用此模式、步骤和注意事项
-- constraints (object, optional): { "preconditions": ["<conditions that must be true before using this pattern>"], "sideEffects": ["<observable side effects of using this code>"], "boundaries": ["<usage limitations or scope restrictions>"] }
-- aiInsight (string, optional): One-sentence concise insight — the single most important takeaway about this code pattern
-
-IMPORTANT: content.pattern must contain the COMPLETE source code. content.markdown must be a meaningful project-specific writeup, NOT just a copy of description. content.rationale must explain WHY this pattern is designed this way. reasoning.whyStandard must explain WHY this pattern matters.
-${langInstruction}
-Return ONLY a JSON array. Do NOT return an empty array.
-
-Files Content:
-${files}`;
-    }
-
-    return `# Role
-You are a ${langProfile.role} extracting production-quality reusable code patterns.
-
-# Goal
-Extract meaningful, complete code patterns from "${targetName}". Each recipe must provide real value to a developer.
-${astSection}
-
-# What makes a GOOD recipe
-- A **complete function/method** or **logical code block** (10-40 lines typically), NOT individual statements
-- Code that demonstrates a **real design pattern**: ${langProfile.patternExamples}
-- Code that a developer would actually **copy-paste and adapt** for a new feature
-
-# What makes a BAD recipe (AVOID these)
-- Trivial 2-3 line snippets like just a single assignment or import
-- Overly generic code that doesn't reflect the file's actual logic
-- Breaking a single function into multiple tiny recipes
-
-# Extraction Strategy
-For each function/method/class in the file, ask: "Would a developer benefit from having this as a reusable template?" If yes, extract the **complete unit** with its full body.
-
-${langProfile.extractionExamples}
-
-# Rules
-1. \`content.pattern\` must contain a **complete function/method or logical unit** — include the signature and full body
-2. \`content.markdown\` must be a meaningful project-specific writeup explaining what this code does and when to use it
-3. Preserve the file's actual code. Use \`<#placeholder#>\` ONLY for literal strings/values a developer would customize
-4. Every recipe must be traceable to real code in the file. Do NOT invent code
-5. Include relevant \`headers\` (import/require lines) that the code depends on
-6. Every recipe must have a concise \`doClause\` and a \`topicHint\` group label
-
-# Output (JSON Array)
-Each item MUST use the following V3 KnowledgeEntry structure:
-- title (string): Descriptive English name
-- description (string): 2-3 sentences explaining what this code does, written as a project-specific guide
-- trigger (string): @shortcut (kebab-case, e.g. "@url-parser")
-- kind (string): "rule" | "pattern" | "fact" — rule = always-do/never-do, pattern = reusable recipe with code, fact = reference info
-- knowledgeType (string): "code-pattern" | "architecture" | "best-practice" | "code-standard" | "code-relation" | "data-flow" | "event-and-data-flow" | "module-dependency" | "boundary-constraint" | "code-style" | "solution" | "anti-pattern"
-- complexity (string): "basic" | "intermediate" | "advanced"
-- scope (string): "universal" | "project-specific" | "team-convention"
-- category: ${langProfile.categories}
-- language: "${langProfile.primaryLanguage}"
-- content (object): { "pattern": "<complete function/method/class from the file>", "markdown": "<project-specific writeup: what this pattern does, when to use it, key design decisions>", "rationale": "<why this pattern is designed this way — design trade-offs, alternatives considered>" }
-- reasoning (object): { "whyStandard": "<why this is a standard/best-practice worth following>", "sources": ["<source file names>"], "confidence": <0.0-1.0> }
-- headers (string[]): Required import/require lines
-- tags (string[]): Search keywords
-- doClause (string): One-sentence imperative: what to do (e.g. "Use dependency injection via constructor")
-- dontClause (string): What NOT to do (e.g. "Don't instantiate services with new directly")
-- whenClause (string): When this pattern applies (e.g. "When creating a new ViewController subclass")
-- topicHint (string): Group label (e.g. "Networking", "UI-Layout")
-- coreCode (string): Minimal 3-10 line code skeleton that captures the essence. Must be syntactically complete — balanced brackets/parentheses, never start with } or ) and never end with { or (
-- usageGuide (string): ### 章节格式使用指南 — 描述何时使用此模式、步骤和注意事项
-- constraints (object, optional): { "preconditions": ["<conditions that must be true before using this pattern>"], "sideEffects": ["<observable side effects of using this code>"], "boundaries": ["<usage limitations or scope restrictions>"] }
-- aiInsight (string, optional): One-sentence concise insight — the single most important takeaway about this code pattern
-
-IMPORTANT: content.pattern must contain the COMPLETE source code. content.markdown must be a meaningful project-specific writeup, NOT just a copy of description. content.rationale must explain WHY this pattern is designed this way. reasoning.whyStandard must explain WHY this pattern matters.
-${langInstruction}
-Return ONLY a JSON array. If no meaningful patterns found, return [].
-
-Files Content:
-${files}`;
-  }
-
   /**
    * 根据用户语言偏好生成输出语言指令
    * @param {string} [lang] - 语言代码，如 'zh', 'en'
@@ -856,7 +731,12 @@ ${items}`;
     }
 
     for (let attempt = 0; attempt <= retries; attempt++) {
+      let slotAcquired = false;
       try {
+        await this._waitForRateLimitWindow();
+        await this._acquireRequestSlot();
+        slotAcquired = true;
+
         const result = await fn();
         // 成功 → 完全重置熔断器（包括冷却时间）
         this._circuitFailures = 0;
@@ -886,6 +766,16 @@ ${items}`;
             causeCode === 'UND_ERR_SOCKET');
         const isRetryable = err.status === 429 || err.status >= 500 || isNetworkError;
 
+        // 429：触发 provider 级冷却窗，抑制并发重试风暴
+        if (err.status === 429) {
+          const retryAfterMs = Number(err.retryAfterMs || 0);
+          const adaptiveCooldown = Math.max(
+            retryAfterMs,
+            Math.round(baseDelay * 2 ** attempt * 1.5 + Math.random() * 1000)
+          );
+          this._setRateLimitWindow(adaptiveCooldown);
+        }
+
         // 首次失败记录详细诊断（含 cause）
         if (attempt === 0 && (isNetworkError || err.cause)) {
           this._log?.(
@@ -921,6 +811,10 @@ ${items}`;
           `[_withRetry] attempt ${attempt + 1} failed (${err.message}), retrying in ${Math.round(delay / 1000)}s…`
         );
         await new Promise((r) => setTimeout(r, delay));
+      } finally {
+        if (slotAcquired) {
+          this._releaseRequestSlot();
+        }
       }
     }
   }