@lorrylurui/code-intelligence-mcp 1.1.14 → 1.2.0

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. 命令行参数（最高优先级）
@@ -10,19 +10,18 @@
 import { resolve } from 'node:path';
 import { loadProjectDotenv } from '../config/env.js';
 import { runReindex } from '../services/reindex.js';
-// dotenv.config();
 /**
  * 入口：加载第三方 .env → 校验环境 → 调用 runReindex。
  * 进度与统计输出到 **stderr**，避免占用 stdout。
  * 进程退出码：成功 `0`，无 MySQL 或异常 `1`。
  */
 async function main() {
-    // 2️ 确定项目根目录并加载第三方 .env（仅覆盖未定义的变量）
+    // 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] projectRoot=${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+/)
             .map((s) => s.trim())

package/dist/config/env.js

@@ -3,7 +3,6 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync, readFileSync } from 'node:fs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const projectRoot = __dirname;
 // 解析命令行参数 --key=value 格式，注入到 process.env
 for (const arg of process.argv) {
     const match = arg.match(/^--([A-Z_][A-Z0-9_]*)=(.+)$/);
@@ -11,11 +10,6 @@ for (const arg of process.argv) {
         process.env[match[1]] = match[2];
     }
 }
-// 加载本地 .env（外部传入的 env 已经在 process.env 中，override: false 不会覆盖它们）
-// dotenv.config({
-//     path: path.resolve(projectRoot, '.env'),
-//     override: false,
-// });
 // MCP Server 本地 .env 路径（固定指向项目根目录）
 const MCP_SERVER_ROOT = path.resolve(__dirname, '..', '..', './dist'); // MCP Server 根目录
 const MCP_SERVER_ENV_PATH = path.resolve(MCP_SERVER_ROOT, '.env');
@@ -28,9 +22,6 @@ dotenv.config({
  * 行为：优先使用第三方显式设置的值，否则保留 MCP Server 本地配置
  */
 export function loadProjectDotenv(projectRoot) {
-    // 始终确保 MCP Server 本地的 .env 被加载（补充加载，确保有默认值）
-    // if (existsSync(MCP_SERVER_ENV_PATH)) {
-    // }
     const envPath = path.resolve(projectRoot, '.env');
     if (!existsSync(envPath)) {
         return;
@@ -69,9 +60,6 @@ export function loadProjectDotenv(projectRoot) {
         }
     }
 }
-// 尝试从第三方项目目录加载 .env，按变量维度覆盖（只覆盖第三方明确配置的变量）
-// const clientProjectRoot = process.env.INDEX_ROOT || process.cwd();
-// loadProjectDotenv(clientProjectRoot);
 // 外部传入的 env 已在上一步保留，这里确保环境变量已正确设置
 for (const arg of process.argv) {
     const match = arg.match(/^--([A-Z_][A-Z0-9_]*)=(.+)$/);
@@ -84,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',
@@ -102,98 +88,13 @@ 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}`);
         }
     }
 }
-// import dotenv from 'dotenv';
-// import path from 'node:path';
-// import { fileURLToPath } from 'node:url';
-// import { existsSync, readFileSync } from 'node:fs';
-// const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// const projectRoot = path.resolve(__dirname, '../../');
-// // 解析命令行参数 --key=value 格式，注入到 process.env
-// for (const arg of process.argv) {
-//     const match = arg.match(/^--([A-Z_][A-Z0-9_]*)=(.+)$/);
-//     if (match) {
-//         process.env[match[1]] = match[2];
-//     }
-// }
-// // 加载本地 .env（外部传入的 env 已经在 process.env 中，override: false 不会覆盖它们）
-// dotenv.config({
-//     path: path.resolve(projectRoot, '.env'),
-//     override: false,
-// });
-// // 尝试从第三方项目目录加载 .env，按变量维度覆盖（只覆盖第三方明确配置的变量）
-// const clientProjectRoot = process.env.INDEX_ROOT || process.cwd();
-// const clientEnvPath = path.resolve(clientProjectRoot, '.env');
-// if (existsSync(clientEnvPath)) {
-//     console.error(
-//         `[Config] Merging .env from client project root: ${clientProjectRoot}`
-//     );
-//     // 手动解析第三方 .env，只覆盖其明确配置的变量
-//     const clientEnvContent = readFileSync(clientEnvPath, 'utf-8');
-//     for (const line of clientEnvContent.split('\n')) {
-//         const trimmed = line.trim();
-//         if (!trimmed || trimmed.startsWith('#')) continue;
-//         const eqIdx = trimmed.indexOf('=');
-//         if (eqIdx === -1) continue;
-//         const key = trimmed.slice(0, eqIdx).trim();
-//         const value = trimmed.slice(eqIdx + 1).trim();
-//         // 移除引号
-//         const cleanValue = value.replace(/^["']|["']$/g, '');
-//         if (key) {
-//             process.env[key] = cleanValue;
-//         }
-//     }
-// }
-// // 外部传入的 env 已在上一步保留，这里确保环境变量已正确设置
-// for (const arg of process.argv) {
-//     const match = arg.match(/^--([A-Z_][A-Z0-9_]*)=(.+)$/);
-//     if (match) {
-//         process.env[match[1]] = match[2];
-//     }
-// }
-// const requiredWhenEnabled = [
-//     'MYSQL_HOST',
-//     'MYSQL_USER',
-//     'MYSQL_DATABASE',
-// ] as const;
-// console.error(
-//     `[Config] MYSQL_ENABLED: ${process.env.MYSQL_ENABLED},
-//     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',
-//     mysqlPassword: process.env.MYSQL_PASSWORD ?? '',
-//     mysqlDatabase: process.env.MYSQL_DATABASE ?? 'code_intelligence',
-//     /** symbols 表名，可通过 MYSQL_SYMBOLS_TABLE 环境变量配置 */
-//     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(),
-// };
-// export function validateEnv(): void {
-//     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');
+}