@lorrylurui/code-intelligence-mcp 1.0.1

package/README.md

@@ -0,0 +1,276 @@
+# Code Intelligence MCP (Minimal)
+
+最小可用的 Node MCP Server 框架，包含：
+
+- MCP Server（stdio）
+- Tool: `search_symbols`（支持 `semantic=true` 语义检索，Phase 5）
+- Tool: `get_symbol_detail`
+- Tool: `search_by_structure`
+- Tool: `reindex`
+- Tool: `recommend_component`
+- Prompt: `reusable-code-advisor`（与 Cursor Skill 同工作流，见 `src/prompts/reusableCodeAdvisorPrompt.ts`）
+- MySQL Repository（可选启用）
+- Cursor Skill：`reusable-code-advisor`（`.cursor/skills/reusable-code-advisor/`，未改动，与 MCP Prompt 并行维护）
+
+## 1) 安装
+
+```bash
+npm install
+```
+
+## 2) 环境变量
+
+复制 `.env.example` 为 `.env`。
+
+默认不强制连接 MySQL（未配置时走内存示例数据）。
+
+如果你要连接 MySQL，请设置：
+
+```env
+MYSQL_ENABLED=true
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=devpassword
+MYSQL_DATABASE=code_intelligence
+
+# Phase 5（可选）：句向量服务根 URL，与 `npm run embedding:dev` 默认端口一致
+# EMBEDDING_SERVICE_URL=http://127.0.0.1:8765
+```
+
+密码需与下方 Docker / 本机 MySQL 配置一致（文档示例里 `devpassword` 对应 Compose）。
+
+### 用 Docker 启动 MySQL（推荐本地开发）
+
+1. 安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)（或 Docker Engine + Compose 插件）。
+2. 在项目根目录执行：
+
+```bash
+npm run docker:up
+# 或：docker compose up -d
+```
+
+3. 首次启动会自动挂载 `sql/schema.sql` 到 `docker-entrypoint-initdb.d`，**创建库表**（仅**空数据卷**时执行一次）。
+4. 复制 `.env.example` 为 `.env`，设置 `MYSQL_ENABLED=true`，`MYSQL_PASSWORD` 与 `docker-compose.yml` 里 `MYSQL_ROOT_PASSWORD`（默认 `devpassword`）一致。
+5. 等待容器健康（约数十秒）：
+
+```bash
+docker compose ps
+```
+
+6. 再执行 `npm run index` 或启动 MCP。
+
+常用命令：
+
+| 命令                     | 说明                           |
+| ------------------------ | ------------------------------ |
+| `npm run docker:logs`    | 查看 MySQL 日志                |
+| `npm run docker:down`    | 停止容器（数据卷保留，库仍在） |
+| `docker compose down -v` | **删除卷**（清空库，慎用）     |
+
+**端口冲突**：若本机已有服务占用 `3306`，把 `docker-compose.yml` 里 `ports` 改为 `"3307:3306"`，并在 `.env` 设 `MYSQL_PORT=3307`。
+
+## 3) 初始化数据库（可选）
+
+- **已用上述 Docker 首次启动**：若卷为空，建表已由 `sql/schema.sql` 自动执行，一般无需再跑下面命令。
+- **本机 mysql 客户端 / 手动执行**：
+
+```bash
+mysql -u root -p code_intelligence < sql/schema.sql
+```
+
+## 4) 本地运行
+
+### 普通开发（热更新）
+
+```bash
+npm run dev
+```
+
+使用 `tsx watch`，改 `src/` 会自动重启；已关闭清屏（`--clear-screen=false`），并排除 `node_modules`、`dist`。
+
+### 接 Cursor MCP（不污染 stdout）
+
+MCP 走 **stdio**，协议数据必须在子进程的 **stdout** 上；若用 `npm run dev` 接 MCP，`npm` 或部分工具可能往 stdout 打杂讯，导致握手异常。
+
+推荐用 **专用脚本**：子进程只跑 `tsx src/index.ts`，**监听/重启日志只打到 stderr**。
+
+```bash
+npm run dev:mcp
+```
+
+**Cursor `mcp.json` 示例（推荐直接调 node，避免 npm）：**
+
+```json
+{
+    "mcpServers": {
+        "code-intelligence-mcp": {
+            "command": "node",
+            "args": ["/绝对路径/Intelligence-code/scripts/mcp-dev-watch.mjs"],
+            "cwd": "/绝对路径/Intelligence-code"
+        }
+    }
+}
+```
+
+也可继续用 `"command": "npm"`, `"args": ["run", "dev:mcp"]`，但部分环境下 npm 仍可能产生额外输出；若 tools 不稳定，请改用上面的 `node .../mcp-dev-watch.mjs`。
+
+### MCP Prompt（非 Cursor 客户端）
+
+服务器注册 Prompt **`reusable-code-advisor`**：客户端执行 `prompts/list` 可见；`prompts/get` 时可传可选参数 **`userRequest`**（用户当前需求或关键词），返回的消息正文与 Cursor Skill 工作流一致。  
+文案与 `.cursor/skills/reusable-code-advisor/SKILL.md` 正文需**手动同步**（见 `src/prompts/reusableCodeAdvisorPrompt.ts` 顶部注释）。
+
+在 **MCP Inspector** 中切换到 **Prompts** 面板即可选择并调试。
+
+## 5) Phase 2：代码索引（ts-morph + fast-glob → MySQL）
+
+1. **建表 / 迁移**
+    - 新库：执行 `sql/schema.sql`（已含 `(path, name)` 唯一索引，便于重复执行 `npm run index` 时 upsert）。
+    - 旧库若只有早期表结构：执行 `sql/migrations/002_symbols_unique_path_name.sql`（若已有重复 `path+name` 需先清理）。
+
+2. **配置 MySQL**（`.env` 中 `MYSQL_ENABLED=true` 等）。
+
+3. **跑索引**（日志在 stderr，不污染 MCP stdout）：
+
+```bash
+npm run index
+```
+
+可选环境变量（见 `.env.example`）：
+
+| 变量           | 含义                                    |
+| -------------- | --------------------------------------- |
+| `INDEX_ROOT`   | 工程根目录，默认当前工作目录            |
+| `INDEX_GLOB`   | 逗号分隔 glob，默认 `src/**/*.{ts,tsx}` |
+| `INDEX_IGNORE` | 额外忽略的 glob 片段（逗号分隔）        |
+
+**分类规则（首版启发式）**：`interface` / `type` → `type`；`.tsx` 且函数体含 JSX → `component`；路径或导出名含 `selector` → `selector`；其余导出函数 → `util`；`class` → `util`（可后续细化）。
+
+**常见错误 `ECONNREFUSED 127.0.0.1:3306`**：本机没有在该端口监听 MySQL。请先启动数据库服务（例如 macOS Homebrew：`brew services start mysql` / `mariadb`），或把 `.env` 里的 `MYSQL_HOST`、`MYSQL_PORT` 改成你实际使用的实例（含 Docker 映射端口）。索引脚本会先执行 `SELECT 1` 再扫描代码，避免库不可用时仍跑完解析。
+
+## 6) 后续演进建议
+
+- 新增 Tool：`list_dependencies`、`get_usage_stats`
+- Indexer：更细的 selector 识别、`export default` 命名、类组件等
+- Phase 5 语义检索已落地（见下文）；后续可换 pgvector / FAISS、更大模型
+
+## 8) Phase 3（增强）
+
+- `search_symbols` 已支持 `ranked` 参数（默认 `true`），返回 `score` 和 `reason`。
+- 新增 `search_by_structure`，可按 `fields`（匹配 `meta.props/params/properties/hooks`）检索。
+- 两个搜索 tool 的 ranking 已升级：除可读 `reason` 外，还返回结构化 `reasonDetail`（含各维度得分、权重和匹配方式），方便前端/Agent解释。
+
+示例：
+
+```json
+{
+    "fields": ["onChange", "value"],
+    "type": "component",
+    "limit": 10
+}
+```
+
+`reindex` 示例（Inspector / Agent 可直接调用，不用回终端）：
+
+```json
+{
+    "dryRun": false
+}
+```
+
+可选参数：
+
+- `projectRoot`: 指定索引根目录（默认 MCP 进程当前目录）
+- `globPatterns`: 自定义扫描 glob 列表
+- `ignore`: 额外忽略规则
+- `dryRun`: `true` 时只扫描，不写 MySQL
+
+## 9) Phase 4（Skill）
+
+- 新增 Skill Tool：`recommend_component`
+- 流程已落地：关键词搜索 -> 结构过滤（可选 `props`）-> ranking -> detail 补全 -> 返回 reason
+- 新增 Prompt：`recommend-component`（用于在支持 MCP Prompt 的客户端快速触发该流程）
+
+示例：
+
+```json
+{
+    "query": "带校验的表单组件",
+    "props": ["value", "onChange"],
+    "limit": 3
+}
+```
+
+## 10) Phase 5（语义检索，可选）
+
+1. **迁移**：若库是在增加 `embedding` 列之前创建的，执行：
+
+```bash
+mysql -u root -p code_intelligence < sql/migrations/003_add_embedding.sql
+```
+
+2. **Python 依赖**（建议虚拟环境；首次运行会下载模型权重，体积约数百 MB）：
+
+```bash
+cd embedding-service
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+3. **启动嵌入服务**（默认 `127.0.0.1:8765`）：
+
+```bash
+npm run embedding:dev
+```
+
+4. **`.env`** 增加 `EMBEDDING_SERVICE_URL=http://127.0.0.1:8765`，再执行 **`npm run index`** 或 MCP **`reindex`**（`dryRun=false`）写入向量。未配置 URL 时与 Phase 2 行为一致，不写入 `embedding`。
+
+5. **`search_symbols`**：传入 `semantic: true` 可做自然语言检索；可选 `limit`（默认 20）。返回中会含 `semanticSimilarity`（余弦相似度）。当前实现按 `usage_count` 取最多 3000 条有向量的候选再精排；超大规模仓库请改为 ANN。
+
+环境变量 **`EMBEDDING_MODEL`**（仅 Python）：覆盖默认的 `all-MiniLM-L6-v2`。
+
+## 7) VS Code 迁移
+
+迁移步骤见 `docs/vscode-mcp-migration.md`。
+
+# 使用说明
+
+Run with:
+
+````bash
+npx code-intelligence-mcp
+---
+
+### MCP 配置（核心）
+
+```md
+## MCP Config
+
+```json
+{
+  "mcpServers": {
+    "code-intelligence": {
+      "command": "npx",
+      "args": ["code-intelligence-mcp"]
+    }
+  }
+}
+---
+
+### 支持的 Tools Prompts
+
+```md
+## Tools
+
+- search_symbols
+- get_symbol_detail
+- search_by_structure
+- recommend_component
+- reindex
+
+## Prompts
+
+- recommend-component
+- reusable-code-advisor
+````

package/dist/cli/detect-duplicates.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+/**
+ * PR/CI 用重复实现检测（最小版）
+ *
+ * 策略：
+ * - 只分析 changed files 中可索引的导出代码块
+ * - 与库内同 type 的存量代码块做语义相似度（cosine）匹配
+ * - 对 component：要求 newProps 是 oldProps 的超集（或至少覆盖大部分）才判定为“重复/可合并”
+ *
+ * 输出：
+ * - duplicate-report.json
+ * - duplicate-report.md（中文，适合 PR 评论）
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import dotenv from 'dotenv';
+import { env, validateEnv } from '../config/env.js';
+import { getMySqlPool } from '../db/mysql.js';
+import { indexedRowToEmbedText } from '../indexer/embedText.js';
+import { indexProject } from '../indexer/indexProject.js';
+import { createEmbeddingClient, embedAll, } from '../services/embeddingClient.js';
+import { cosineSimilarity } from '../services/vectorMath.js';
+dotenv.config();
+function parseArgs(argv) {
+    const args = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const key = a.slice(2);
+        const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : 'true';
+        args.set(key, value);
+    }
+    return args;
+}
+function readLines(path) {
+    const raw = readFileSync(path, 'utf8');
+    return raw
+        .split(/\r?\n/g)
+        .map((l) => l.trim())
+        .filter(Boolean);
+}
+function uniqueLower(items) {
+    const out = [];
+    const seen = new Set();
+    for (const it of items) {
+        const k = it.trim();
+        if (!k)
+            continue;
+        const low = k.toLowerCase();
+        if (seen.has(low))
+            continue;
+        seen.add(low);
+        out.push(k);
+    }
+    return out;
+}
+function getMetaArray(meta, key) {
+    if (!meta)
+        return [];
+    const v = meta[key];
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === 'string');
+}
+function propsForRow(row) {
+    if (row.type !== 'component')
+        return [];
+    return uniqueLower(getMetaArray(row.meta, 'props'));
+}
+function coverageAndSuperset(newProps, oldProps) {
+    if (oldProps.length === 0) {
+        return { coverage: 1, isSuperset: true };
+    }
+    const newSet = new Set(newProps.map((p) => p.toLowerCase()));
+    let hit = 0;
+    for (const p of oldProps) {
+        if (newSet.has(p.toLowerCase()))
+            hit += 1;
+    }
+    const coverage = hit / oldProps.length;
+    const isSuperset = hit === oldProps.length;
+    return { coverage, isSuperset };
+}
+function toFixed4(n) {
+    return Number(n.toFixed(4));
+}
+function escapeMd(text) {
+    return text.replace(/\|/g, '\\|');
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const changedFilesPath = args.get('changed-files') ?? 'changed_files.txt';
+    const outJson = args.get('out-json') ?? 'duplicate-report.json';
+    const outMd = args.get('out-md') ?? 'duplicate-report.md';
+    const blockThreshold = Number(args.get('block-threshold') ??
+        process.env.DUPLICATE_BLOCK_THRESHOLD ??
+        '0.95');
+    const warnThreshold = Number(args.get('warn-threshold') ??
+        process.env.DUPLICATE_WARN_THRESHOLD ??
+        '0.85');
+    const propsCoverageThreshold = Number(args.get('props-coverage') ?? '1');
+    const candidateLimit = Number(args.get('candidate-limit') ?? '3000');
+    // Mock 模式：不连接真实服务，仅测试报告生成流程
+    const isMockMode = args.get('is-mock-mode') === 'true';
+    if (isMockMode) {
+        console.log('[duplicate-check] 🔧 Mock 模式：跳过 MySQL 和 embedding service');
+    }
+    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）。');
+        }
+    }
+    // Type narrowing for TS (pool is guaranteed non-null after guards above)
+    const mysqlPool = isMockMode ? null : getMySqlPool();
+    const projectRoot = resolve(process.cwd());
+    const changed = readLines(changedFilesPath)
+        .filter((p) => p.endsWith('.ts') || p.endsWith('.tsx'))
+        .filter((p) => !p.includes('/node_modules/') && !p.includes('/dist/'));
+    if (changed.length === 0) {
+        const empty = {
+            ok: true,
+            blockingCount: 0,
+            warningCount: 0,
+            maxSimilarity: 0,
+            findings: [],
+            note: '本次 PR 未包含可索引的 .ts/.tsx 变更文件。',
+        };
+        writeFileSync(outJson, JSON.stringify(empty, null, 2));
+        writeFileSync(outMd, '## 重复实现检测（CI）\n\n本次 PR 未包含可索引的 `.ts/.tsx` 变更文件。\n');
+        return;
+    }
+    // 1) 仅解析变更文件（通过传绝对路径给 indexProject.globPatterns）
+    const absPatterns = changed.map((p) => resolve(projectRoot, p).replace(/\\/g, '/'));
+    const rows = await indexProject({ projectRoot, globPatterns: absPatterns });
+    if (rows.length === 0) {
+        const empty = {
+            ok: true,
+            blockingCount: 0,
+            warningCount: 0,
+            maxSimilarity: 0,
+            findings: [],
+            note: '变更文件中未抽取到可索引导出代码块。',
+        };
+        writeFileSync(outJson, JSON.stringify(empty, null, 2));
+        writeFileSync(outMd, '## 重复实现检测（CI）\n\n变更文件中未抽取到可索引导出代码块。\n');
+        return;
+    }
+    // 2) 计算本次变更代码块 embedding（批量）或使用 mock
+    let vecs;
+    let client = null;
+    if (isMockMode) {
+        // Mock 模式：生成随机向量（维度 1024，与 embedding service 一致）
+        vecs = rows.map(() => Array.from({ length: 1024 }, () => Math.random() * 2 - 1));
+    }
+    else {
+        client = createEmbeddingClient(env.embeddingServiceUrl);
+        const texts = rows.map(indexedRowToEmbedText);
+        vecs = await embedAll(client, texts);
+    }
+    async function loadCandidates(type) {
+        if (isMockMode) {
+            // Mock 模式：返回空候选，模拟"无重复"的检测结果
+            return [];
+        }
+        if (!mysqlPool)
+            return [];
+        const [dbRows] = await mysqlPool.query(`
+        SELECT id, name, type, path, CAST(meta AS CHAR) AS meta, embedding
+        FROM symbols
+        WHERE type = ? AND embedding IS NOT NULL
+        ORDER BY usage_count DESC
+        LIMIT ?
+      `, [type, candidateLimit]);
+        const out = [];
+        for (const r of dbRows) {
+            let meta = null;
+            try {
+                meta = r.meta ? JSON.parse(r.meta) : null;
+            }
+            catch {
+                meta = null;
+            }
+            let emb = null;
+            try {
+                const parsed = typeof r.embedding === 'string'
+                    ? JSON.parse(r.embedding)
+                    : r.embedding;
+                if (Array.isArray(parsed)) {
+                    const nums = parsed.map((x) => Number(x));
+                    if (nums.every((n) => Number.isFinite(n)))
+                        emb = nums;
+                }
+            }
+            catch {
+                emb = null;
+            }
+            if (!emb)
+                continue;
+            out.push({
+                id: Number(r.id),
+                name: String(r.name),
+                type: r.type,
+                path: String(r.path),
+                meta,
+                embedding: emb,
+            });
+        }
+        return out;
+    }
+    const candidatesByType = new Map();
+    async function getCandidates(type) {
+        const cached = candidatesByType.get(type);
+        if (cached)
+            return cached;
+        const loaded = await loadCandidates(type);
+        candidatesByType.set(type, loaded);
+        return loaded;
+    }
+    const findings = [];
+    let maxSimilarity = 0;
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        const qv = vecs[i];
+        const cand = await getCandidates(row.type);
+        let best = null;
+        for (const c of cand) {
+            if (c.embedding.length !== qv.length)
+                continue;
+            const sim = cosineSimilarity(qv, c.embedding);
+            if (!best || sim > best.sim)
+                best = { c, sim };
+        }
+        if (!best)
+            continue;
+        const sim = best.sim;
+        if (sim > maxSimilarity)
+            maxSimilarity = sim;
+        // props 超集判定：仅对 component 生效；其它类型只用语义相似度。
+        const newProps = propsForRow(row);
+        const oldProps = best.c.type === 'component'
+            ? uniqueLower(getMetaArray(best.c.meta, 'props'))
+            : [];
+        const { coverage, isSuperset } = row.type === 'component'
+            ? coverageAndSuperset(newProps, oldProps)
+            : { coverage: 1, isSuperset: true };
+        const propsOk = row.type !== 'component'
+            ? true
+            : coverage >= propsCoverageThreshold;
+        const level = sim >= blockThreshold && propsOk && isSuperset
+            ? 'blocking'
+            : sim >= warnThreshold && propsOk && isSuperset
+                ? 'warning'
+                : null;
+        if (!level)
+            continue;
+        findings.push({
+            level,
+            symbol: {
+                name: row.name,
+                type: row.type,
+                path: row.path,
+                props: newProps,
+            },
+            bestMatch: {
+                id: best.c.id,
+                name: best.c.name,
+                type: best.c.type,
+                path: best.c.path,
+                similarity: toFixed4(sim),
+                props: oldProps,
+                propsCoverage: toFixed4(coverage),
+                propsIsSuperset: isSuperset,
+            },
+        });
+    }
+    const blockingCount = findings.filter((f) => f.level === 'blocking').length;
+    const warningCount = findings.filter((f) => f.level === 'warning').length;
+    // JSON 报告（供 workflow 读 blockingCount/maxSimilarity）
+    const report = {
+        ok: true,
+        mockMode: isMockMode,
+        blockingCount,
+        warningCount,
+        maxSimilarity: toFixed4(maxSimilarity),
+        thresholds: {
+            blockThreshold,
+            warnThreshold,
+            propsCoverageThreshold,
+            candidateLimit,
+        },
+        changedFiles: changed,
+        extractedSymbols: rows.map((r) => ({
+            name: r.name,
+            type: r.type,
+            path: r.path,
+        })),
+        findings,
+    };
+    writeFileSync(outJson, JSON.stringify(report, null, 2));
+    // 中文 Markdown（PR 评论）
+    const lines = [];
+    lines.push('## 重复实现检测（CI）');
+    if (isMockMode) {
+        lines.push('');
+        lines.push('> ⚠️ **Mock 模式**：本次检测未连接真实 MySQL/embedding service，结果仅供参考。');
+    }
+    lines.push('');
+    lines.push(`- 阻断（blocking）阈值：语义相似度 ≥ **${blockThreshold}** 且 **props 超集**`);
+    lines.push(`- 告警（warning）阈值：语义相似度 ≥ **${warnThreshold}** 且 **props 超集**`);
+    if (propsCoverageThreshold < 1) {
+        lines.push(`- props 覆盖阈值：覆盖率 ≥ **${propsCoverageThreshold}**（当前要求超集时仍会校验覆盖率）`);
+    }
+    lines.push('');
+    if (findings.length === 0) {
+        lines.push('未发现需要提示的重复实现候选。');
+        lines.push('');
+    }
+    else {
+        lines.push(`本次检测发现：**阻断 ${blockingCount}** 条，**告警 ${warningCount}** 条。`);
+        lines.push('');
+        lines.push('| 级别 | 新增/改动代码块 | 类型 | 最相似存量 | 相似度 | props 超集 | props 覆盖率 |');
+        lines.push('|---|---|---|---|---:|---:|---:|');
+        for (const f of findings) {
+            const newRef = `${escapeMd(f.symbol.name)} \\(${escapeMd(f.symbol.path)}\\)`;
+            const oldRef = `${escapeMd(f.bestMatch.name)} \\(${escapeMd(f.bestMatch.path)}\\)`;
+            lines.push(`| ${f.level === 'blocking' ? '阻断' : '告警'} | ${newRef} | ${f.symbol.type} | ${oldRef} | ${f.bestMatch.similarity} | ${f.bestMatch.propsIsSuperset ? '是' : '否'} | ${f.bestMatch.propsCoverage} |`);
+        }
+        lines.push('');
+        lines.push('### 处理建议');
+        lines.push('- **优先复用/扩展存量组件**：如果只是新增少量属性，建议把属性合并到存量组件并统一出口。');
+        lines.push('- **若确需新建**：请在 PR 描述中说明为什么不能复用（领域差异、历史包袱、兼容性约束等），并由 Owner 审核通过。');
+        lines.push('');
+    }
+    writeFileSync(outMd, lines.join('\n'));
+    // Exit code：有 blocking 则非 0（让 workflow fail）
+    if (blockingCount > 0) {
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error('[duplicate-check] failed:', err);
+    process.exit(2);
+});

package/dist/cli/index-codebase.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Phase 2 CLI：扫描代码库并写入 MySQL `symbols`（需 `MYSQL_ENABLED=true`）。
+ */
+import { resolve } from "node:path";
+import dotenv from "dotenv";
+import { runReindex } from "../services/reindex.js";
+dotenv.config();
+/**
+ * 入口：校验环境 → 连接池 → 按 `INDEX_*` 调用 `indexProject` → `upsertSymbols`。
+ * 进度与统计输出到 **stderr**，避免占用 stdout（与 MCP 混用时更安全）。
+ * 进程退出码：成功 `0`，无 MySQL 或异常 `1`。
+ */
+async function main() {
+    const projectRoot = resolve(process.env.INDEX_ROOT ?? process.cwd());
+    const globPatterns = process.env.INDEX_GLOB
+        ? process.env.INDEX_GLOB.split(",").map((s) => s.trim())
+        : undefined;
+    const ignore = process.env.INDEX_IGNORE
+        ? process.env.INDEX_IGNORE.split(",").map((s) => s.trim())
+        : undefined;
+    console.error(`[index] projectRoot=${projectRoot}`);
+    const result = await runReindex({ projectRoot, globPatterns, ignore, dryRun: false });
+    console.error(`[index] extracted ${result.extractedCount} symbol(s)`);
+    console.error(`[index] embeddings computed: ${result.embeddingsComputed}`);
+    console.error("[index] upserted into MySQL");
+}
+main().catch((err) => {
+    console.error("[index] failed:", err);
+    const anyErr = err;
+    if (anyErr.code === "ECONNREFUSED") {
+        const host = process.env.MYSQL_HOST ?? "127.0.0.1";
+        const port = process.env.MYSQL_PORT ?? "3306";
+        console.error(`[index] 原因: 无法连接 ${host}:${port}（连接被拒绝）。请先在本机启动 MySQL/MariaDB，或把 .env 里的 MYSQL_HOST / MYSQL_PORT 改成实际地址。macOS 可用 brew services start mysql 等方式启动。`);
+    }
+    else if (anyErr.code === "ER_ACCESS_DENIED_ERROR") {
+        console.error("[index] 原因: 用户名或密码错误，请检查 MYSQL_USER / MYSQL_PASSWORD。");
+    }
+    else if (anyErr.code === "ENOTFOUND" || anyErr.code === "ETIMEDOUT") {
+        console.error("[index] 原因: 网络不可达或超时，请检查 MYSQL_HOST 是否可解析、防火墙与安全组。");
+    }
+    process.exit(1);
+});

package/dist/config/env.js

@@ -0,0 +1,23 @@
+import dotenv from "dotenv";
+dotenv.config();
+const requiredWhenEnabled = ["MYSQL_HOST", "MYSQL_USER", "MYSQL_DATABASE"];
+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",
+    /** Phase 5：指向 Python FastAPI 嵌入服务根 URL，如 http://127.0.0.1:8765 */
+    embeddingServiceUrl: (process.env.EMBEDDING_SERVICE_URL ?? "").trim()
+};
+export function validateEnv() {
+    if (!env.mysqlEnabled) {
+        return;
+    }
+    for (const key of requiredWhenEnabled) {
+        if (!process.env[key]) {
+            throw new Error(`Missing environment variable: ${key}`);
+        }
+    }
+}