@lorrylurui/code-intelligence-mcp 1.1.15 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# Code Intelligence MCP (Minimal)
+# Code Intelligence MCP
 
 - MCP Server（stdio）
 - Tool: `search_symbols`
@@ -8,7 +8,6 @@
 - Tool: `recommend_component`
 - Tool: `incUsage`
 - Prompt: `reusable-code-advisor`
-- MySQL Repository（可选启用）
 - Cursor Skill：`reusable-code-advisor`（`.cursor/skills/reusable-code-advisor/`，
 
 ## 1) 配置mcp servers
@@ -32,5 +31,77 @@
 
 ## 3) 项目根目录环境变量
 
+<!-- 最小配置 1.表名 2.需要检索的文件路径和类型 -->
+
 MYSQL\*SYMBOLS_TABLE=frontend_collections_symbols
-INDEX_GLOB=interview-code-collection/\*\*/\_.{js,jsx,ts,tsx}
+INDEX_GLOB=xxx/\*\*/\_.{js,jsx,ts,tsx}
+
+# 待优化项
+
+修复优先级：
+✅8
+✅5
+✅134 done，但是第二层embedding需要优化，llm fallback太慢+漂移，也需要调整模型
+✅6
+✅27
+
+1.  meta里面有多个信息，哪些做结构化过滤，哪些做向量检索？
+    结论：ast normalizers后拼一个语义模板，用这个模板内容生成向量
+    ❓做法见qa-doc/semantic-phrase.md
+2.  对于 class类型，content字段保留关键方法或摘要，而不是完全为空
+    最新修改：content赋值为语义模板
+3.  category过于模糊，
+    这三层怎么做：category 优先使用规则和 embedding 分类，
+    LLM 只作为 fallback，避免不稳定和成本问题
+    ❓做法见qa-doc/category.md
+4.  type category meta.kind 字段是否多余了？type只有5个值，
+    type表达代码结构、category表达语义结构，kind？
+    type： function / component / hook / class / type / interface
+    category：最新的三层结构（还没实现，只有文档）
+    kind: 现在跟type重叠较多，建议弱化meta.kind → 只保留特殊情况：
+    ❓改造方法qa-doc/type-category-kind.md
+5.  在ci做增量索引时，把changed files,如果是1000+文件，性能爆炸，考虑用file hash 判断？embedding也没有优化缓存？
+    ❓见qa-doc/ci-hash-solution 方案：🥈 file hash + ast normalizer hash，新增semantic_hash
+    - CI 增量（git changed files 触发）
+      只需要 semantic_hash
+      file_hash 可省，因为文件必然变了
+    - 每日全量扫描
+      file_hash 用来跳过 AST 解析（CPU 优化）
+      semantic_hash 用来跳过 embedding（费用优化）
+      content_hash 删掉，职责完全被 semantic_hash 覆盖
+6.  大仓问题：
+    ❓big-repo.md
+    - ci embedding解耦，新增embedding_status, ci时，全量写入status='pending'-> ci finish
+    - ci如果检测到文件删除，则对被删除的代码块标记delete（这里需要新增字段）
+    - node+redis 消费写embedding job
+    - 对语义模板semantic_hash做向量缓存，semantic_hash相同即功能未变
+    - 大仓分片并行
+7.  content暂时用不到，但也不用删除，目前暴利截取4000字符需要优化：
+    content（降级为辅助字段）：✔ 不参与 embedding✔ 不参与排序✔ 不参与过滤✔ 用于：1. LLM改造建议 2.debug 3.future rerank
+    最简单：只存 signature
+    最优：content = {
+    signature: "function fetchData(url, options)",
+    snippet: "核心逻辑代码（<=300行）",
+    keyCalls: ["fetch", "cache"]
+    }
+8.  TopK???，首先去掉usage过滤，再做两次topk,1.根据余弦相似度选topk 2.对1的结果用现有的usage,updated_at等加权排序
+    ❓topK.md
+    现在：SQL过滤(type) → ORDER BY usage_count DESC LIMIT 3000→ embedding 相似度排序→ 取 top20
+    这个逻辑不对，导致query: "debounce function"，debounce 使用少 ❌ fetch 很热门 ✅，结果Top3000里全是 fetch / request， debounce 被过滤掉 ❌
+
+👉 优点：
+• 不阻塞 CI
+• 可扩展
+
+6. 大仓问题呢？
+
+# 简历里还没做的优化
+
+1. embedding基石 - 语义模板模板，使用ast数据拼装语义模板
+2. class的content为null
+3. category分层 1.规则 2.预设所有种类，使用embedding召回 3.llm兜底
+4. type meta.kind逻辑优化，现在太重叠了
+5. ci-hash-solution
+6. 大仓问题
+7. content优化
+8. ✅topk优化

package/dist/cli/ci-index-cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * CI增量索引CLI：处理changed files和deleted files
+ *
+ * 用法：
+ * node src/cli/ci-index-cli.js --changed src/file1.ts,src/file2.ts --deleted src/old.ts --renamed src/old.ts:src/new.ts
+ */
+import { resolve } from 'node:path';
+import { loadProjectDotenv } from '../config/env.js';
+import { runIncrementalIndex } from './ci-index.js';
+async function main() {
+    const args = process.argv.slice(2);
+    const projectRoot = resolve(process.env.INDEX_ROOT ?? process.cwd());
+    loadProjectDotenv(projectRoot);
+    let changedFiles = [];
+    let deletedFiles = [];
+    let renamedFiles = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--changed' && i + 1 < args.length) {
+            changedFiles = args[i + 1]
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            i++;
+        }
+        else if (arg === '--deleted' && i + 1 < args.length) {
+            deletedFiles = args[i + 1]
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            i++;
+        }
+        else if (arg === '--renamed' && i + 1 < args.length) {
+            renamedFiles = args[i + 1]
+                .split(',')
+                .map((s) => {
+                const [from, to] = s.split(':');
+                return { from: from.trim(), to: to.trim() };
+            })
+                .filter((r) => r.from && r.to);
+            i++;
+        }
+    }
+    if (changedFiles.length === 0 &&
+        deletedFiles.length === 0 &&
+        renamedFiles.length === 0) {
+        console.error('Usage: node ci-index-cli.js --changed file1,file2 --deleted file3 --renamed old:new');
+        process.exit(1);
+    }
+    console.error(`[ci-index-cli] projectRoot=${projectRoot}`);
+    console.error(`[ci-index-cli] changed: ${changedFiles.join(', ')}`);
+    console.error(`[ci-index-cli] deleted: ${deletedFiles.join(', ')}`);
+    console.error(`[ci-index-cli] renamed: ${renamedFiles.map((r) => `${r.from}->${r.to}`).join(', ')}`);
+    await runIncrementalIndex({
+        projectRoot,
+        changedFiles,
+        deletedFiles,
+        renamedFiles,
+    });
+    console.error('[ci-index-cli] completed successfully');
+}
+main().catch((err) => {
+    console.error('[ci-index-cli] failed:', err);
+    process.exit(1);
+});

package/dist/cli/ci-index.js

@@ -0,0 +1,80 @@
+// CI增量索引：处理changed files和deleted files
+import { env, loadProjectDotenv } from '../config/env.js';
+import { getMySqlPool } from '../db/mysql.js';
+import { indexProject } from '../indexer/indexProject.js';
+import { DEFAULT_STATUS_ON_UPSERT, SYMBOL_STATUS, } from '../config/symbolStatus.js';
+import { enqueueEmbeddingBatch, closeEmbeddingQueue, } from '../services/embeddingQueue.js';
+export async function runIncrementalIndex(opts) {
+    const { projectRoot, changedFiles, deletedFiles, renamedFiles = [] } = opts;
+    loadProjectDotenv(projectRoot);
+    const pool = getMySqlPool();
+    if (!pool) {
+        throw new Error('Failed to get MySQL pool');
+    }
+    const tableName = env.mysqlSymbolsTable;
+    // 1. 删除文件：标记 offline
+    for (const file of deletedFiles) {
+        await pool.query(`UPDATE ${tableName} SET status = ? WHERE path = ?`, [
+            SYMBOL_STATUS.OFFLINE,
+            file,
+        ]);
+        console.error(`[ci-index] marked offline: ${file}`);
+    }
+    // 2. 重命名文件：更新path
+    for (const { from, to } of renamedFiles) {
+        await pool.query(`UPDATE ${tableName} SET path = ? WHERE path = ?`, [
+            to,
+            from,
+        ]);
+        console.error(`[ci-index] renamed: ${from} -> ${to}`);
+    }
+    // 3. 变更/新增文件：重新索引并标记 pending
+    if (changedFiles.length > 0) {
+        const rows = await indexProject({
+            projectRoot,
+            globPatterns: changedFiles,
+        });
+        for (const row of rows) {
+            // 写入结构化数据，标记pending
+            await pool.query(`INSERT INTO ${tableName}
+                   (name, type, category, path, description, content, meta,
+                    file_hash, semantic_hash, status,
+                    usage_count, created_at, updated_at)
+                 VALUES (?, ?, ?, ?, ?, ?, CAST(? AS JSON), ?, ?, ?, 0, NOW(), NOW())
+                 ON DUPLICATE KEY UPDATE
+                   type             = VALUES(type),
+                   category         = VALUES(category),
+                   description      = VALUES(description),
+                   content          = VALUES(content),
+                   meta             = VALUES(meta),
+                   file_hash        = VALUES(file_hash),
+                   semantic_hash    = VALUES(semantic_hash),
+                   status           = ?,
+                   updated_at       = NOW()`, [
+                row.name,
+                row.type,
+                row.category ?? null,
+                row.path,
+                row.description ?? null,
+                row.content ?? null,
+                JSON.stringify(row.meta),
+                row.file_hash,
+                row.semantic_hash,
+                DEFAULT_STATUS_ON_UPSERT,
+                DEFAULT_STATUS_ON_UPSERT,
+            ]);
+            console.error(`[ci-index] indexed (pending): ${row.path}:${row.name}`);
+        }
+        // 批量入队：jobId = semanticHash，相同 hash 自动去重，1000 个符号可能只产生 N 个唯一 job
+        const hashes = [
+            ...new Set(rows.map((r) => r.semantic_hash).filter(Boolean)),
+        ];
+        if (hashes.length > 0) {
+            await enqueueEmbeddingBatch(hashes);
+            console.error(`[ci-index] enqueued ${hashes.length} unique semantic hashes for embedding`);
+        }
+    }
+    await closeEmbeddingQueue();
+    await pool.end();
+    console.error(`[ci-index] processed ${deletedFiles.length} deletions, ${renamedFiles.length} renames, ${changedFiles.length} changes`);
+}

package/dist/cli/detect-duplicates.js

@@ -109,8 +109,7 @@ async function main() {
         }
     }
     loadProjectDotenv(projectRoot);
-    console.error(`[duplicate-check] projectRoot=${projectRoot}, ` +
-        `MYSQL_ENABLED=${process.env.MYSQL_ENABLED}`);
+    console.error(`[duplicate-check] projectRoot=${projectRoot}, `);
     // 3️ 解析命令行参数
     const args = parseArgs(process.argv.slice(2));
     const changedFilesPath = args.get('changed-files') ?? 'changed_files.txt';
@@ -131,10 +130,6 @@ async function main() {
     }
     else {
         validateEnv();
-        const pool = getMySqlPool();
-        if (!pool || !env.mysqlEnabled) {
-            throw new Error('duplicate-check 需要 MYSQL_ENABLED=true 并可连接 MySQL。');
-        }
         if (!env.embeddingServiceUrl) {
             throw new Error('duplicate-check 需要 EMBEDDING_SERVICE_URL（embedding service）。');
         }

package/dist/cli/embedding-worker-cli.js

@@ -0,0 +1,35 @@
+/**
+ * embedding worker 进程入口。
+ *
+ * 本地启动：
+ *   npm run worker:embedding
+ *
+ * 大仓分片（多进程并行）：
+ *   WORKER_CONCURRENCY=10 npm run worker:embedding &
+ *   WORKER_CONCURRENCY=10 npm run worker:embedding &
+ *   # 启动 N 个进程，BullMQ 自动分配任务，无需手动分片
+ *
+ * 环境变量：
+ *   REDIS_URL           Redis 连接 URL（默认 redis://127.0.0.1:6379）
+ *   MYSQL_HOST / ...    MySQL 连接配置
+ *   EMBEDDING_SERVICE_URL  Python embedding 服务地址
+ *   WORKER_CONCURRENCY  单进程并发 job 数（默认 5）
+ *   WORKER_RPM_LIMIT    全局 RPM 上限（默认 100，跨所有 worker 进程）
+ *   PROJECT_ROOT        项目根目录，用于加载 .env（默认 cwd）
+ */
+import { loadProjectDotenv } from '../config/env.js';
+import { startEmbeddingWorker } from '../workers/embeddingWorker.js';
+const projectRoot = process.env.PROJECT_ROOT ?? process.cwd();
+loadProjectDotenv(projectRoot);
+const concurrency = Number(process.env.WORKER_CONCURRENCY ?? '5');
+const rpmLimit = Number(process.env.WORKER_RPM_LIMIT ?? '100');
+const worker = startEmbeddingWorker({ concurrency, rpmLimit });
+console.error(`[embedding-worker] started  concurrency=${concurrency}  rpm_limit=${rpmLimit}`);
+// 优雅关闭：等当前 job 执行完再退出
+for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, async () => {
+        console.error('[embedding-worker] shutting down…');
+        await worker.close();
+        process.exit(0);
+    });
+}

package/dist/cli/index-codebase.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Phase 2 CLI：扫描代码库并写入 MySQL `symbols`（需 `MYSQL_ENABLED=true`）。
+ * Phase 2 CLI：扫描代码库并写入 MySQL `symbols`。
  *
  * 环境变量加载顺序：
  * 1. 命令行参数（最高优先级）
@@ -16,10 +16,11 @@ import { runReindex } from '../services/reindex.js';
  * 进程退出码：成功 `0`，无 MySQL 或异常 `1`。
  */
 async function main() {
+    // const projectRoot = resolve(process.env.INDEX_ROOT ?? process.cwd());
+    loadProjectDotenv(resolve(process.env.INDEX_ROOT ?? process.cwd()));
     const projectRoot = resolve(process.env.INDEX_ROOT ?? process.cwd());
-    loadProjectDotenv(projectRoot);
-    console.error(`[index] MYSQL_ENABLED=${process.env.MYSQL_ENABLED}, ` +
-        `MYSQL_HOST=${process.env.MYSQL_HOST}` +
+    console.error(projectRoot, process.env.INDEX_ROOT);
+    console.error(`MYSQL_HOST=${process.env.MYSQL_HOST}` +
         `[index] projectRoot=${projectRoot}`);
     const globPatterns = process.env.INDEX_GLOB
         ? process.env.INDEX_GLOB.split(/\s+/)

package/dist/config/env.js

@@ -72,15 +72,13 @@ const requiredWhenEnabled = [
     'MYSQL_USER',
     'MYSQL_DATABASE',
 ];
-console.error(`[Config] MYSQL_ENABLED: ${process.env.MYSQL_ENABLED},
-    MYSQL_HOST: ${process.env.MYSQL_HOST},
+console.error(`[Config] MYSQL_HOST: ${process.env.MYSQL_HOST},
     MYSQL_USER: ${process.env.MYSQL_USER},
     MYSQL_DATABASE: ${process.env.MYSQL_DATABASE},
     EMBEDDING_SERVICE_URL: ${process.env.EMBEDDING_SERVICE_URL},
     MYSQL_SYMBOLS_TABLE: ${process.env.MYSQL_SYMBOLS_TABLE}
     `);
 export const env = {
-    mysqlEnabled: process.env.MYSQL_ENABLED === 'true',
     mysqlHost: process.env.MYSQL_HOST ?? '127.0.0.1',
     mysqlPort: Number(process.env.MYSQL_PORT ?? '3306'),
     mysqlUser: process.env.MYSQL_USER ?? 'root',
@@ -90,11 +88,10 @@ export const env = {
     mysqlSymbolsTable: process.env.MYSQL_SYMBOLS_TABLE ?? 'symbols',
     /** Phase 5：指向 Python FastAPI 嵌入服务根 URL，如 http://127.0.0.1:8765 */
     embeddingServiceUrl: (process.env.EMBEDDING_SERVICE_URL ?? '').trim(),
+    /** Redis 连接 URL，供 BullMQ embedding worker 使用 */
+    redisUrl: process.env.REDIS_URL ?? 'redis://127.0.0.1:6379',
 };
 export function validateEnv() {
-    if (!env.mysqlEnabled) {
-        return;
-    }
     for (const key of requiredWhenEnabled) {
         if (!process.env[key]) {
             throw new Error(`Missing environment variable: ${key}`);

package/dist/config/symbolStatus.js

@@ -0,0 +1,8 @@
+export const SYMBOL_STATUS = {
+    OFFLINE: 0,
+    PENDING: 1,
+    ONLINE: 2,
+    ERROR: 3,
+};
+export const DEFAULT_STATUS_ON_UPSERT = SYMBOL_STATUS.PENDING;
+export const SEARCHABLE_STATUS = SYMBOL_STATUS.ONLINE;

package/dist/db/mysql.js

@@ -1,10 +1,7 @@
-import mysql from "mysql2/promise";
-import { env } from "../config/env.js";
+import mysql from 'mysql2/promise';
+import { env } from '../config/env.js';
 let pool = null;
 export function getMySqlPool() {
-    if (!env.mysqlEnabled) {
-        return null;
-    }
     if (!pool) {
         pool = mysql.createPool({
             host: env.mysqlHost,
@@ -13,7 +10,7 @@ export function getMySqlPool() {
             password: env.mysqlPassword,
             database: env.mysqlDatabase,
             waitForConnections: true,
-            connectionLimit: 10
+            connectionLimit: 10,
         });
     }
     return pool;

package/dist/db/schema.js

@@ -2,13 +2,14 @@
  * 动态生成数据库表结构 SQL，表名可通过环境变量配置
  */
 import { env } from '../config/env.js';
+import { DEFAULT_STATUS_ON_UPSERT } from '../config/symbolStatus.js';
 /** 获取 symbols 表的建表 SQL */
 export function getSymbolsTableSQL() {
     const tableName = env.mysqlSymbolsTable;
     return `CREATE TABLE IF NOT EXISTS ${tableName} (
   id INT PRIMARY KEY AUTO_INCREMENT,
   name VARCHAR(255) NOT NULL,
-  type ENUM('component', 'util', 'selector', 'type') NOT NULL,
+  type ENUM('component', 'function', 'type', 'class', 'interface', 'hook') NOT NULL,
   category VARCHAR(255) NULL,
   path TEXT NOT NULL,
   description TEXT NULL,
@@ -20,7 +21,13 @@ export function getSymbolsTableSQL() {
   updated_user VARCHAR(255) NOT NULL DEFAULT 'LorryIsLuRui',
   created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
   updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  UNIQUE KEY uk_symbols_path_name (path(512), name(255))
+  file_hash VARCHAR(64) NULL COMMENT '文件内容 SHA256',
+  semantic_hash VARCHAR(64) NULL COMMENT 'normalized AST 语义模板 SHA256',
+  status TINYINT NOT NULL DEFAULT ${DEFAULT_STATUS_ON_UPSERT} COMMENT '状态: 0-offline(删除), 1-pending(待处理), 2-online(可用), 3-error(错误)',
+  UNIQUE KEY uk_symbols_path_name (path(512), name(255)),
+  INDEX idx_file_hash (file_hash),
+  INDEX idx_semantic_hash (semantic_hash),
+  INDEX idx_status (status)
 )`;
 }
 /** 获取所有建表 SQL（可一次性执行） */

package/dist/indexer/astNormalizer.js

@@ -0,0 +1,201 @@
+/**
+ * astNormalizer.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();
+}
+// ─────────────────────────────────────────────
+// 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();
+}
+// ─────────────────────────────────────────────
+// extractNormalizedSignature：从声明节点提取标准化签名
+// ─────────────────────────────────────────────
+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().map((p) => normalizeNode(p));
+        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 / type alias
+    if (Node.isInterfaceDeclaration(node) ||
+        Node.isTypeAliasDeclaration(node)) {
+        return normalizeNode(node);
+    }
+    // class：只取方法签名列表
+    if (Node.isClassDeclaration(node)) {
+        const methods = node.getMethods().map((m) => {
+            const params = m.getParameters().map((p) => normalizeNode(p));
+            const retNode = m.getReturnTypeNode();
+            const ret = retNode
+                ? normalizeTypeString(retNode.getText())
+                : '$inferred';
+            return `${m.getName()}(${params.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(),
+    };
+    return createHash('sha256').update(JSON.stringify(stable)).digest('hex');
+}
+// ─────────────────────────────────────────────
+// computeFileHash：对文件原始内容
+// ─────────────────────────────────────────────
+export function computeFileHash(fileContent) {
+    return createHash('sha256').update(fileContent).digest('hex');
+}