@lorrylurui/code-intelligence-mcp 1.1.15 → 2.0.1

package/dist/indexer/tsAstNormalizer.js

@@ -0,0 +1,363 @@
+/**
+ * tsAstNormalizer.ts
+ * 对 ts-morph Node 做语义级标准化，生成 semantic_hash。
+ *
+ * 去掉：参数名、泛型参数名、函数体实现、空白格式、字面量值
+ * 保留：参数类型结构、返回类型、sideEffects、hooks
+ */
+import { createHash } from 'node:crypto';
+import { Node, SyntaxKind } from 'ts-morph';
+// ─────────────────────────────────────────────
+// 内置类型白名单：不替换为 $T
+// ─────────────────────────────────────────────
+const BUILTIN_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'void',
+    'null',
+    'undefined',
+    'never',
+    'unknown',
+    'any',
+    'object',
+    'symbol',
+    'bigint',
+    'Promise',
+    'Array',
+    'Record',
+    'Map',
+    'Set',
+    'WeakMap',
+    'WeakSet',
+    'Partial',
+    'Required',
+    'Readonly',
+    'Pick',
+    'Omit',
+    'Exclude',
+    'Extract',
+    'NonNullable',
+    'ReturnType',
+    'InstanceType',
+    'React',
+    'ReactNode',
+    'ReactElement',
+    'FC',
+    'MouseEvent',
+    'KeyboardEvent',
+    'ChangeEvent',
+    'HTMLElement',
+    'HTMLDivElement',
+    'HTMLInputElement',
+    'CSSProperties',
+    'RefObject',
+    'MutableRefObject',
+]);
+function normalizeTypeName(name) {
+    if (BUILTIN_TYPES.has(name))
+        return name;
+    if (/^T[A-Z]/.test(name) || (name.length === 1 && /[A-Z]/.test(name)))
+        return '$T';
+    return name;
+}
+function normalizeTypeString(typeStr) {
+    return typeStr
+        .replace(/\b([A-Z][A-Za-z0-9]*)\b/g, (match) => normalizeTypeName(match))
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// 从类型节点提取属性列表（递归处理嵌套对象）
+function extractPropertiesFromType(typeNode) {
+    const props = [];
+    // 处理 { a: string, b: number } 这种字面量对象类型
+    if (Node.isTypeLiteral(typeNode)) {
+        for (const member of typeNode.getMembers()) {
+            if (Node.isPropertySignature(member)) {
+                const name = member.getName();
+                const typeNode = member.getTypeNode();
+                const typeStr = typeNode
+                    ? normalizeTypeString(typeNode.getText())
+                    : '$unknown';
+                const optional = member.hasQuestionToken() ? '?' : '';
+                props.push(`${name}${optional}:${typeStr}`);
+            }
+        }
+    }
+    // 处理交叉类型 A & B
+    if (Node.isIntersectionTypeNode(typeNode)) {
+        for (const member of typeNode.getChildren()) {
+            if (Node.isTypeLiteral(member)) {
+                props.push(...extractPropertiesFromType(member));
+            }
+        }
+    }
+    return props;
+}
+// ─────────────────────────────────────────────
+// normalizeNode：递归遍历 AST，输出标准化字符串
+// ─────────────────────────────────────────────
+export function normalizeNode(node) {
+    const paramNames = new Map();
+    let paramIdx = 0;
+    function allocParam(name) {
+        if (!paramNames.has(name))
+            paramNames.set(name, `$p${paramIdx++}`);
+        return paramNames.get(name);
+    }
+    function visit(n) {
+        const kind = n.getKind();
+        // 函数体 → {}（不关心实现）
+        if (kind === SyntaxKind.Block)
+            return '{}';
+        // 参数：只保留类型，去参数名
+        if (Node.isParameterDeclaration(n)) {
+            const nameNode = n.getNameNode();
+            const typeNode = n.getTypeNode();
+            const typeStr = typeNode
+                ? normalizeTypeString(typeNode.getText())
+                : '$unknown';
+            const prefix = n.isRestParameter() ? '...' : '';
+            const suffix = n.hasInitializer() ? '=$default' : '';
+            // 解构参数：{ userId, options }: Config → {}:Config
+            if (Node.isObjectBindingPattern(nameNode) ||
+                Node.isArrayBindingPattern(nameNode)) {
+                return `${prefix}{}:${typeStr}${suffix}`;
+            }
+            allocParam(n.getName());
+            return `${prefix}$p:${typeStr}${suffix}`;
+        }
+        // 泛型参数：T / TData → $T
+        if (Node.isTypeParameterDeclaration(n)) {
+            const constraint = n.getConstraint();
+            return `$T${constraint ? ` extends ${normalizeTypeString(constraint.getText())}` : ''}`;
+        }
+        // 类型引用：标准化名称
+        if (Node.isTypeReference(n))
+            return normalizeTypeString(n.getText());
+        // JSX：只记录存在
+        if (Node.isJsxElement(n) || Node.isJsxSelfClosingElement(n))
+            return '<JSX/>';
+        // 字面量 → 占位符
+        if (kind === SyntaxKind.StringLiteral)
+            return '"$s"';
+        if (kind === SyntaxKind.NumericLiteral ||
+            kind === SyntaxKind.BigIntLiteral)
+            return '$n';
+        if (kind === SyntaxKind.TrueKeyword || kind === SyntaxKind.FalseKeyword)
+            return '$b';
+        const children = n.getChildren();
+        if (children.length === 0)
+            return n.getText();
+        return children.map(visit).join('');
+    }
+    return visit(node).replace(/\s+/g, ' ').trim();
+}
+function normalizeParameter(param, index) {
+    const typeNode = param.getTypeNode();
+    const typeStr = typeNode
+        ? normalizeTypeWithStructure(typeNode)
+        : '$unknown';
+    const prefix = param.isRestParameter() ? '...' : '';
+    const suffix = param.hasInitializer() ? '=$default' : '';
+    const nameNode = param.getNameNode();
+    // 解构参数：{ id, opts }: Config → { id: $d, opts: $d }:{id:xx, opts:xx}
+    if (Node.isObjectBindingPattern(nameNode) ||
+        Node.isArrayBindingPattern(nameNode)) {
+        const elements = nameNode.getElements();
+        const destrProps = [];
+        for (const el of elements) {
+            if (Node.isOmittedExpression(el))
+                continue;
+            const elAny = el;
+            const name = elAny.getName?.() ?? 'unknown';
+            // 检查是否有问号（可选属性）
+            const hasQ = el
+                .getChildren()
+                .some((c) => c.getKind() === SyntaxKind.QuestionToken);
+            // 检查是否有默认值，有则使用默认值的类型
+            const initializer = el.getInitializer();
+            let valueType;
+            if (initializer) {
+                // 用初始值表达式的类型
+                valueType = normalizeTypeWithStructure(initializer);
+            }
+            else {
+                valueType = '$d';
+            }
+            destrProps.push(`${name}${hasQ ? '?' : ''}:${valueType}`);
+        }
+        // 排序 key, 防止仅仅因为顺序不一样导致hash不稳定
+        destrProps.sort();
+        return `${prefix}{${destrProps.join(',')}}:${typeStr}${suffix}`;
+    }
+    return `${prefix}$p${index}:${typeStr}${suffix}`;
+}
+function normalizeTypeWithStructure(typeNode) {
+    // 如果是类型字面量 { name: string, age: number }
+    if (Node.isTypeLiteral(typeNode)) {
+        const props = typeNode
+            .getMembers()
+            .filter(Node.isPropertySignature)
+            .map((prop) => {
+            const propTypeNode = prop.getTypeNode();
+            const propType = propTypeNode
+                ? normalizeTypeWithStructure(propTypeNode)
+                : '$unknown';
+            return `${prop.getName()}${prop.hasQuestionToken() ? '?' : ''}:${propType}`;
+        });
+        return `{${props.join(',')}}`;
+    }
+    // 如果是类型引用（e.g. Param, Array<string>, Promise<User>）
+    if (Node.isTypeReference(typeNode)) {
+        const typeName = typeNode.getTypeName().getText();
+        // 优先处理泛型参数（不管是否在白名单中）
+        const typeArgs = typeNode.getTypeArguments();
+        if (typeArgs.length > 0) {
+            const normalizedArgs = typeArgs.map((arg) => normalizeTypeWithStructure(arg));
+            return `${typeName}<${normalizedArgs.join(',')}>`;
+        }
+        // 没有泛型参数时，检查是否是基础类型
+        if (BUILTIN_TYPES.has(typeName)) {
+            return typeName;
+        }
+        // 无泛型的类型引用，尝试解析实际类型
+        try {
+            const type = typeNode.getType();
+            const symbol = type.getSymbol();
+            if (symbol) {
+                const declarations = symbol.getDeclarations();
+                if (declarations.length > 0) {
+                    const decl = declarations[0];
+                    // 如果是接口声明，递归处理
+                    if (Node.isInterfaceDeclaration(decl)) {
+                        const props = decl.getProperties().map((prop) => {
+                            const propTypeNode = prop.getTypeNode();
+                            const propType = propTypeNode
+                                ? normalizeTypeWithStructure(propTypeNode)
+                                : '$unknown';
+                            return `${prop.getName()}${prop.hasQuestionToken() ? '?' : ''}:${propType}`;
+                        });
+                        return `{${props.join(',')}}`;
+                    }
+                    // 如果是类型别名
+                    if (Node.isTypeAliasDeclaration(decl)) {
+                        const aliasedType = decl.getTypeNode();
+                        if (aliasedType) {
+                            return normalizeTypeWithStructure(aliasedType);
+                        }
+                    }
+                }
+            }
+        }
+        catch (e) {
+            // 解析失败，回退到类型名
+        }
+        return typeName;
+    }
+    // 其他情况（联合类型、交叉类型、基础类型等）
+    return normalizeTypeString(typeNode.getText());
+}
+export function extractNormalizedSignature(node) {
+    // 函数声明 / 箭头函数 / 函数表达式
+    if (Node.isFunctionDeclaration(node) ||
+        Node.isArrowFunction(node) ||
+        Node.isFunctionExpression(node)) {
+        const typeParams = Node.isFunctionDeclaration(node)
+            ? node.getTypeParameters().map((tp) => normalizeNode(tp))
+            : [];
+        const params = node
+            .getParameters()
+            .sort()
+            .map((p, i) => normalizeParameter(p, i));
+        const retNode = node.getReturnTypeNode?.();
+        const returnType = retNode
+            ? normalizeTypeString(retNode.getText())
+            : '$inferred';
+        const tpStr = typeParams.length ? `<${typeParams.join(',')}>` : '';
+        return `fn${tpStr}(${params.join(',')})=>${returnType}`;
+    }
+    // 变量声明（const foo = () => {}）
+    if (Node.isVariableDeclaration(node)) {
+        const init = node.getInitializer();
+        if (init &&
+            (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+            return extractNormalizedSignature(init);
+        }
+        return normalizeNode(node);
+    }
+    // interface：提取所有属性，模板化名称
+    if (Node.isInterfaceDeclaration(node)) {
+        const props = node.getProperties().map((prop) => {
+            const typeNode = prop.getTypeNode();
+            const typeStr = typeNode
+                ? normalizeTypeString(typeNode.getText())
+                : '$unknown';
+            const optional = prop.hasQuestionToken() ? '?' : '';
+            return `${prop.getName()}${optional}:${typeStr}`;
+        });
+        const extendsClause = node.getExtends();
+        const extendsStr = extendsClause.length
+            ? ` extends ${extendsClause.map((e) => normalizeTypeString(e.getText())).join(',')}`
+            : '';
+        return `interface{${props.sort().join(';')}}${extendsStr}`;
+    }
+    // type alias（对象类型）：提取结构化信息
+    if (Node.isTypeAliasDeclaration(node)) {
+        const typeNode = node.getTypeNode();
+        if (typeNode) {
+            // 处理 type Foo = { ... }
+            const props = extractPropertiesFromType(typeNode);
+            if (props.length > 0) {
+                return `type{${props.sort().join(';')}}`;
+            }
+        }
+        return normalizeNode(node);
+    }
+    // class：只取方法签名列表
+    if (Node.isClassDeclaration(node)) {
+        const methods = node
+            .getMethods()
+            .sort()
+            .map((m) => {
+            const params = m
+                .getParameters()
+                .sort()
+                .map((p) => normalizeNode(p));
+            const retNode = m.getReturnTypeNode();
+            const ret = retNode
+                ? normalizeTypeString(retNode.getText())
+                : '$inferred';
+            return `${m.getName()}(${params.sort().join(',')})=>${ret}`;
+        });
+        return `class{${methods.join(';')}}`;
+    }
+    return normalizeNode(node);
+}
+// ─────────────────────────────────────────────
+// computeSemanticHash
+// 纳入：标准化签名 + name + type + description + sideEffects + hooks
+// 排除：参数名、实现、格式、callers/callees
+// ─────────────────────────────────────────────
+export function computeSemanticHash(row) {
+    const node = row.node || null;
+    const meta = row.meta || {};
+    const stable = {
+        name: row.name,
+        type: row.type,
+        description: row.description ?? null,
+        signature: node ? extractNormalizedSignature(node) : '',
+        sideEffects: [
+            ...(meta.sideEffects ?? []),
+        ].sort(),
+        hooks: [...(meta.hooks ?? [])].sort(),
+    };
+    const stableStr = JSON.stringify(stable);
+    return [createHash('sha256').update(stableStr).digest('hex'), stableStr];
+}
+// ─────────────────────────────────────────────
+// computeFileHash：对文件原始内容
+// ─────────────────────────────────────────────
+export function computeFileHash(fileContent) {
+    return createHash('sha256').update(fileContent).digest('hex');
+}

package/dist/prompts/reusableCodeAdvisorPrompt.js

@@ -7,7 +7,7 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 
 当用户需要可复用代码或实现类需求时，按顺序执行：
 
-1. 调用 search_symbols 检索候选，type 根据用户需求传（component/util/selector/type）
+1. 调用 search_symbols 检索候选，type 根据用户需求传（component/function/hook/class/type/interface）；描述功能意图时设置 semantic=true
 2. 如果用户指定了结构过滤条件（props/params/properties/hooks），额外调用 search_by_structure 做结构匹配
 3. 先 search_symbols(limit=20) 拉候选，再对 Top 3 调用 get_symbol_detail 做深度判断
 4. 若仅凭签名/摘要无法判断，对最相关的若干候选调用 get_symbol_detail 获取详情
@@ -16,7 +16,25 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
    - **API 是否简单**、入参是否合适
    - **依赖与副作用**风险
    - **复用安全性**（稳定性、耦合度、是否便于扩展）
-6. 给出**唯一首选**推荐，并说明理由
+6. 给出**唯一首选**推荐，并说明理由，同时使用 **AskUserQuestion** 工具，提供两个选项：
+   - 采纳推荐
+   - 取消
+7. 用户选择"采纳推荐"后，立即调用 inc_usage 工具记录该行为（symbolId 从搜索结果的 id 字段获取），不要遗漏此步骤。
+
+## 不适用场景
+
+以下情况不要调用搜索工具：
+- 用户只是问代码如何写（概念性问题），不需要检索已有实现
+- 用户明确说"新建一个"、"自己实现"、"不用已有的"
+- 查询过于通用（如只说"utils"），先与用户确认具体需求再搜索
+
+## 搜索结果判断
+
+根据 semanticSimilarity 决定推荐置信度：
+- **> 0.85**：高置信度，可直接推荐
+- **0.6 – 0.85**：中等置信度，需结合 description 和 get_symbol_detail 综合判断
+- **< 0.6**：低置信度，说明可能无合适实现，明确告知用户
+- **空结果**：明确说"未找到已有实现"，不要凭空推荐
 
 ## 回复结构
 
@@ -28,6 +46,7 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 - **理由：** 1～3 条要点
 - **其他候选：** 简要列出及取舍（同步标注副作用）
 - **用法提示：** 结合用户场景的最小集成说明
+- **是否采纳：** 展示两个选项：选项1. 采纳推荐  选项2. 取消。等待用户确认
 
 ## 约束
 
@@ -35,12 +54,6 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 - 若无合适代码块，明确说明，并给出最接近的选项及差距。
 - 推理简洁，面向落地实现。
 
-## 使用反馈
-
-当最终采纳了某个推荐代码块后，必须调用 inc_usage 工具记录采纳行为：
-“请调用 inc_usage({ symbolId: <选中的代码块 id> })”
-其中 symbolId 从 search_symbols 或 search_by_structure 返回结果的 id 字段获取。这条记录会用于后续排序优化。
-
 ## 更多示例
 
 与仓库内 \`.cursor/skills/reusable-code-advisor/examples.md\` 中的示例一致（在 Cursor 或本地打开该文件查看）。

package/dist/repositories/symbolRepository.js

@@ -1,7 +1,9 @@
 import { env } from '../config/env.js';
-import { getMySqlPool } from '../db/mysql.js';
+import { getPool } from '../db/postgres.js';
 import { createEmbeddingClient } from '../services/embeddingClient.js';
-import { cosineSimilarity } from '../services/vectorMath.js';
+import { SEARCHABLE_STATUS } from '../config/symbolStatus.js';
+const SIMILARITY_THRESHOLD = 0.5;
+const TOP_K = 20;
 const inMemorySymbols = [
     {
         id: 1,
@@ -18,7 +20,7 @@ const inMemorySymbols = [
     {
         id: 2,
         name: 'formatDate',
-        type: 'util',
+        type: 'function',
         category: 'date',
         path: 'src/utils/date.ts',
         description: 'Format date to YYYY-MM-DD',
@@ -39,6 +41,7 @@ function parseEmbedding(raw) {
     }
     if (typeof raw === 'string') {
         try {
+            // pgvector 返回 "[x1,x2,...]"，恰好是合法 JSON 数组
             const j = JSON.parse(raw);
             if (!Array.isArray(j))
                 return null;
@@ -82,7 +85,7 @@ function getMetaArray(meta, key) {
 export class SymbolRepository {
     pool;
     constructor() {
-        this.pool = getMySqlPool();
+        this.pool = getPool();
     }
     async search(query, type) {
         if (!this.pool) {
@@ -94,23 +97,27 @@ export class SymbolRepository {
                         (s.description ?? '').toLowerCase().includes(q)));
             });
         }
-        const params = [`%${query}%`];
+        const params = [
+            `%${query}%`,
+            SEARCHABLE_STATUS,
+        ];
         let sql = `
-      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
-      FROM ${env.mysqlSymbolsTable}
-      WHERE (name LIKE ? OR description LIKE ?)
+      SELECT id, name, type, category, path, description, content, meta::text AS meta, usage_count, created_at
+      FROM ${env.symbolsTable}
+      WHERE (name ILIKE $1 OR description ILIKE $1)
+        AND status = $2
     `;
-        params.push(`%${query}%`);
         if (type) {
-            sql += ' AND type = ?';
             params.push(type);
+            sql += ` AND type = $${params.length}`;
         }
         sql += ' ORDER BY usage_count DESC LIMIT 20';
-        const [rows] = await this.pool.query(sql, params);
+        const { rows } = await this.pool.query(sql, params);
         return rows.map((r) => mapRow(r));
     }
     /**
-     * Phase 5：对自然语言查询做向量检索，返回代码块与余弦相似度（已去掉 embedding 列便于 JSON 输出）。
+     * 语义向量检索：将 query 嵌入后用 pgvector <=> 运算符（cosine distance）在数据库内完成相似度排序。
+     * 不再需要在 Node 拉取全量向量做内存计算。
      */
     async searchSemanticHits(query, opts) {
         if (!env.embeddingServiceUrl) {
@@ -119,47 +126,47 @@ export class SymbolRepository {
         if (!this.pool) {
             return [];
         }
-        const candidateLimit = opts?.candidateLimit ?? 3000;
-        const limit = opts?.limit ?? 20;
-        const type = opts?.type;
+        const limit = opts?.limit ?? TOP_K;
         const client = createEmbeddingClient(env.embeddingServiceUrl);
         const [queryVec] = await client.embed([query.trim()]);
         if (!queryVec?.length) {
             throw new Error('查询向量为空');
         }
+        // pgvector 向量字面量格式：[x1,x2,...]
+        const vecLiteral = `[${queryVec.join(',')}]`;
+        const params = [vecLiteral, SEARCHABLE_STATUS];
+        // 1 - cosine_distance = cosine_similarity；多取一倍候选后在应用层过阈值
         let sql = `
-      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at, embedding
-      FROM ${env.mysqlSymbolsTable}
+      SELECT id, name, type, category, path, description, content, meta::text AS meta,
+             usage_count, created_at,
+             1 - (embedding <=> $1::vector) AS similarity
+      FROM ${env.symbolsTable}
       WHERE embedding IS NOT NULL
+        AND status = $2
     `;
-        const params = [];
-        if (type) {
-            sql += ' AND type = ?';
-            params.push(type);
+        if (opts?.type) {
+            params.push(opts.type);
+            sql += ` AND type = $${params.length}`;
         }
-        sql += ' ORDER BY usage_count DESC LIMIT ?';
-        params.push(candidateLimit);
-        const [rows] = await this.pool.query(sql, params);
-        const withVec = rows
-            .map((r) => mapRow(r, { includeEmbedding: true }))
-            .filter((s) => s.embedding && s.embedding.length === queryVec.length);
-        return withVec
-            .map((s) => {
-            const sim = cosineSimilarity(queryVec, s.embedding);
-            const { embedding: _, ...rest } = s;
-            return { symbol: rest, similarity: sim };
-        })
-            .sort((a, b) => b.similarity - a.similarity)
+        params.push(limit * 2); // 多取一倍以便 SIMILARITY_THRESHOLD 过滤后仍有足量结果
+        sql += ` ORDER BY embedding <=> $1::vector LIMIT $${params.length}`;
+        const { rows } = await this.pool.query(sql, params);
+        return rows
+            .map((r) => ({
+            symbol: mapRow(r),
+            similarity: Number(r.similarity),
+        }))
+            .filter((x) => x.similarity >= SIMILARITY_THRESHOLD)
             .slice(0, limit);
     }
     async getByName(name) {
         if (!this.pool) {
             return (inMemorySymbols.find((s) => s.name.toLowerCase() === name.toLowerCase()) ?? null);
         }
-        const [rows] = await this.pool.query(`
-      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
-      FROM ${env.mysqlSymbolsTable}
-      WHERE name = ?
+        const { rows } = await this.pool.query(`
+      SELECT id, name, type, category, path, description, content, meta::text AS meta, usage_count, created_at
+      FROM ${env.symbolsTable}
+      WHERE name = $1
       LIMIT 1
       `, [name]);
         if (rows.length === 0) {
@@ -180,8 +187,8 @@ export class SymbolRepository {
             }
             return false;
         }
-        const [result] = await this.pool.query(`UPDATE ${env.mysqlSymbolsTable} SET usage_count = usage_count + 1 WHERE id = ?`, [symbolId]);
-        return result.affectedRows > 0;
+        const result = await this.pool.query(`UPDATE ${env.symbolsTable} SET usage_count = usage_count + 1 WHERE id = $1`, [symbolId]);
+        return result.rowCount !== null && result.rowCount > 0;
     }
     async searchByStructure(fields, opts) {
         const normalized = fields.map((f) => f.trim()).filter(Boolean);
@@ -212,21 +219,21 @@ export class SymbolRepository {
         }
         const params = [];
         let sql = `
-      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
-      FROM ${env.mysqlSymbolsTable}
+      SELECT id, name, type, category, path, description, content, meta::text AS meta, usage_count, created_at
+      FROM ${env.symbolsTable}
       WHERE 1 = 1
     `;
         if (type) {
-            sql += ' AND type = ?';
             params.push(type);
+            sql += ` AND type = $${params.length}`;
         }
         if (category) {
-            sql += ' AND category LIKE ?';
             params.push(`%${category}%`);
+            sql += ` AND category ILIKE $${params.length}`;
         }
-        sql += ' ORDER BY usage_count DESC LIMIT ?';
         params.push(Math.max(limit * 5, 50));
-        const [rows] = await this.pool.query(sql, params);
+        sql += ` ORDER BY usage_count DESC LIMIT $${params.length}`;
+        const { rows } = await this.pool.query(sql, params);
         return rows
             .map((r) => mapRow(r))
             .filter(matchesAll)

package/dist/services/embeddingQueue.js

@@ -0,0 +1,57 @@
+/**
+ * BullMQ embedding 队列 producer。
+ *
+ * 去重策略：
+ * - 同一 CI run 内：ci-index.ts 用 new Set(hashes) 去重后再入队，Redis 层无需 jobId 去重
+ * - 跨 CI run 的向量缓存：由 worker 查询 DB（status=online AND semantic_hash=?）决定是否调 API
+ * - 不使用 jobId，避免 BullMQ completed 状态残留导致后续 run 任务被跳过
+ *
+ * CI 流程只负责 enqueue，worker 异步消费，CI 不阻塞。
+ * 调用方在进程退出前需调用 closeEmbeddingQueue() 释放连接。
+ */
+import { Queue } from 'bullmq';
+import { Redis } from 'ioredis';
+import { env } from '../config/env.js';
+let _queue = null;
+let _connection = null;
+function getQueue() {
+    if (!_queue) {
+        _connection = new Redis(env.redisUrl, {
+            maxRetriesPerRequest: null, // BullMQ required
+            enableReadyCheck: false,
+        });
+        _queue = new Queue('embedding', { connection: _connection });
+    }
+    return _queue;
+}
+/** 单个 semanticHash 入队 */
+export async function enqueueEmbedding(semanticHash, symbolsTable) {
+    await getQueue().add('embed', { semanticHash, symbolsTable: symbolsTable ?? env.symbolsTable }, {
+        attempts: 5,
+        backoff: { type: 'exponential', delay: 5_000 },
+    });
+}
+/**
+ * 批量入队（同一 CI run 内已由调用方 new Set 去重）。
+ * worker 消费时查 DB 决定是否真正调 embedding API。
+ */
+export async function enqueueEmbeddingBatch(semanticHashes, symbolsTable) {
+    const table = symbolsTable ?? env.symbolsTable;
+    const queue = getQueue();
+    const jobs = semanticHashes.map((hash) => ({
+        name: 'embed',
+        data: { semanticHash: hash, symbolsTable: table },
+        opts: {
+            attempts: 5,
+            backoff: { type: 'exponential', delay: 5_000 },
+        },
+    }));
+    await queue.addBulk(jobs);
+}
+/** 进程退出前关闭连接（CI 脚本必须调用，否则进程挂起） */
+export async function closeEmbeddingQueue() {
+    await _queue?.close();
+    await _connection?.quit();
+    _queue = null;
+    _connection = null;
+}