@lorrylurui/code-intelligence-mcp 1.0.7 → 1.0.8

package/README.md

@@ -156,11 +156,11 @@ npm run index
 
 可选环境变量（见 `.env.example`）：
 
-| 变量           | 含义                                             |
-| -------------- | ------------------------------------------------ |
-| `INDEX_ROOT`   | 工程根目录，默认当前工作目录                     |
-| `INDEX_GLOB`   | 空格分隔 glob，默认 `src/**/*.{ts,tsx}`         |
-| `INDEX_IGNORE` | 额外忽略的 glob 片段（空格分隔）                 |
+| 变量           | 含义                                    |
+| -------------- | --------------------------------------- |
+| `INDEX_ROOT`   | 工程根目录，默认当前工作目录            |
+| `INDEX_GLOB`   | 空格分隔 glob，默认 `src/**/*.{ts,tsx}` |
+| `INDEX_IGNORE` | 额外忽略的 glob 片段（空格分隔）        |
 
 **分类规则（首版启发式）**：`interface` / `type` → `type`；`.tsx` 且函数体含 JSX → `component`；路径或导出名含 `selector` → `selector`；其余导出函数 → `util`；`class` → `util`（可后续细化）。
 
@@ -293,3 +293,322 @@ Run with:
 - recommend-component
 - reusable-code-advisor
 ````
+
+---
+
+Code Intelligence 功能完整总结
+
+项目定位
+
+智能代码推荐系统：解决日常团队开发中可复用逻辑（组件、样式、selectors、类型声明等）重复开发问题，提高代码复
+用率。
+
+一、系统架构
+
+┌─────────────────────────────────────────────────────────────────┐  
+│ MCP Client (Claude/Cursor) │  
+│ 用户提问 → 模型分析 → 返回结果 │
+└─────────────────────────────────────────────────────────────────┘  
+ │  
+ ▼  
+┌─────────────────────────────────────────────────────────────────┐  
+│ MCP Server (Node.js) │  
+├─────────────────────────────────────────────────────────────────┤  
+│ Tools (4个) │ Prompts (1个) │ DB Layer │  
+│ - search_symbols │ - reusable-code- │ - MySQL │  
+│ - get_symbol_detail │ advisor │ - embedding │  
+│ - search_by_struct │ │ │  
+│ - reindex │ │ │  
+└─────────────────────────────────────────────────────────────────┘  
+ │  
+ ▼  
+┌─────────────────────────────────────────────────────────────────┐  
+│ Indexer (源码解析) │  
+│ ts-ormorph (TS/TSX) + Babel (JS/JSX) │  
+└─────────────────────────────────────────────────────────────────┘  
+ │  
+ ▼  
+┌─────────────────────────────────────────────────────────────────┐  
+│ Embedding Service (Python FastAPI) │  
+│ 向量化 + 语义检索 │  
+└─────────────────────────────────────────────────────────────────┘
+
+二、MCP Server Tools（4个）
+
+1. search_symbols 通用检索
+
+功能：根据 query 和 type 进行语义搜索，对结果进行权重排序
+
+入参：  
+{  
+ query: string, // 搜索关键词  
+ type?: 'component' | 'util' | 'selector' | 'type', // 可选  
+ semantic?: boolean, // 是否启用语义搜索（需 embedding 服务）
+ranked?: boolean, // 是否排序，默认 true  
+ limit?: number, // 返回数量，默认 20  
+}
+
+权重排序算法（RANK_WEIGHTS）：  
+const RANK_WEIGHTS = {  
+ textMatch: 0.4, // 文本匹配度  
+ usage: 0.3, // 使用频率  
+ recency: 0.15, // 最近更新时间  
+ commonPath: 0.15, // common 路径偏好  
+}
+
+score = textScore _ 0.4 + usage _ 0.3 + recency _ 0.15 + commonPath _ 0.15
+
+难点：
+
+- 多维度权重调优
+- 文本匹配算法（模糊匹配 + 语义匹配）
+- 冷启动时无 embedding 向量fallback 到文本匹配
+
+---
+
+2. get_symbol_detail 获取详情
+
+功能：根据 name 获取代码块的完整信息
+
+入参：  
+ {  
+ name: string, // 代码块名称  
+ }
+
+返回：完整代码块信息包括 meta（props/params/properties/hooks）
+
+难点：需要从 MySQL 解析 JSON 格式的 meta 字段
+
+---
+
+3. search_by_structure 结构化搜索
+
+功能：通过结构化字段搜索代码块，适用于 API 形态查询
+
+入参：  
+ {  
+ fields: string[], // 结构字段，如 ['onChange', 'value']  
+ type?: 'component' | 'util' | 'selector' | 'type',  
+ category?: string, // 业务分类  
+ limit?: number,  
+ }
+
+匹配逻辑：匹配 symbol.meta 中的：
+
+- props - 组件 props
+- params - 函数参数
+- properties - 对象属性
+- hooks - React hooks
+
+难点：
+
+- 不支持 LLM 向量检索，需全表扫描 + 内存过滤
+- 需要在 MySQL 中存储 JSON 格式的 meta
+
+---
+
+4. reindex 重建索引
+
+功能：扫描源码目录，解析并写入 MySQL + 向量
+
+入参：  
+ {  
+ projectRoot?: string, // 项目根目录，默认 cwd  
+ globPatterns?: string[], // glob 模式，默认 ['**/*.{ts,tsx}']  
+ ignore?: string[], // 忽略目录  
+ dryRun?: boolean, // 仅预览不写入  
+ }
+
+处理流程：
+
+1. 收集文件（fast-glob）  
+   ↓
+2. 分离 TS/TSX 和 JS/JSX  
+   ↓
+3. TS/TSX：ts-ormorph 解析  
+   JS/JSX：Babel 解析  
+   ↓
+4. 提取 meta（props/params/properties/hooks）  
+   ↓
+5. 写入 MySQL  
+   ↓
+6. 写入 embedding 向量（可选）
+
+难点：
+
+- ts-ormorph：需要 tsconfig.json，不存在时用默认配置
+- Babel 解析：支持 JSX、TypeScript、装饰器等语法
+- meta 提取：
+    - extractFunctionMeta：提取函数参数、返回值类型
+    - extractHooksFromBody：提取 useState/useEffect 等
+    - extractInterfaceOrTypeMeta：提取接口属性
+- 路径推断 category：从路径智能推断业务分类（如 src/components/form/\* → form）
+- 忽略规则：node_modules、dist、build、.git、coverage、.next、.nuxt、.venv 等
+
+---
+
+三、MCP Prompt（1个）
+
+reusable-code-advisor 多工具编排
+
+功能：在实现需求时检索并推荐最合适的可复用代码
+
+工作流：
+
+1. 调用 search_symbols 检索候选，type 根据用户需求传（component/util/selector/type）
+2. 如果用户指定了结构过滤条件（props/params/properties/hooks），额外调用 search_by_structure 做结构匹配
+3. 先 search_symbols(limit=20) 拉候选，再对 Top 3 调用 get_symbol_detail 做深度判断
+4. 若仅凭签名/摘要无法判断，调用 get_symbol_detail 获取详情
+5. 从以下维度对比候选：
+    - 功能匹配度
+    - API 是否简单、入参是否合适
+    - 依赖与副作用风险
+    - 复用安全性（稳定性、耦合度、是否便于扩展）
+6. 给出唯一首选推荐，并说明理由
+
+返回格式：
+
+- 首选：<代码块名>
+- 理由：1～3 条要点
+- 其他候选：简要列出及取舍
+- 用法提示：结合用户场景的最小集成说明
+
+难点：多工具组合调用逻辑、意图判断
+
+---
+
+四、GitHub Actions（CI/CD 检测评论）
+
+1. duplicate-check 工作流
+
+功能：检测代码重复实现，在 PR/Commit 上自动评论
+
+触发条件：
+
+- push 到 main 分支
+- PR opened/synchronize/reopened
+
+工作流：
+
+1. 计算变更文件列表（git diff）
+2. 运行 detect-duplicates 脚本
+3. 生成报告（JSON + Markdown）
+4. 上传 artifact
+5. 评论到 PR 或 Commit
+
+评论逻辑：
+
+- PR 事件：直接评论到 PR
+- Push 事件：查找关联 PR 并评论，无关联则评论到 Commit
+
+发布为 GitHub Action：
+
+- 仓库：lorrylurui/code-intelligence-check
+- 第三方使用：
+- uses: lorrylurui/code-intelligence-check@v1  
+  with:  
+   is-mock-mode: 'true' # 无需 MySQL
+
+---
+
+五、Embedding Service（Python FastAPI）
+
+功能
+
+- 文本向量化：将查询和代码块转为向量（384维 MiniLM）
+- 语义检索：余弦相似度计算
+
+API
+
+POST /embed  
+ Body: { "texts": ["查询文本"] }  
+ Response: { "embeddings": [[0.1, 0.2, ...]] }
+
+GET /health
+
+---
+
+六、数据库设计
+
+symbols 表
+
+CREATE TABLE symbols (  
+ id INT AUTO_INCREMENT PRIMARY KEY,  
+ name VARCHAR(255) NOT NULL COMMENT '代码块名称',  
+ type ENUM('component', 'util', 'selector', 'type') NOT NULL COMMENT '类型',
+category VARCHAR(100) COMMENT '业务分类',  
+ path VARCHAR(500) NOT NULL COMMENT '文件路径',  
+ description TEXT COMMENT '描述/文档',  
+ content LONGTEXT COMMENT '完整代码内容',  
+ meta JSON COMMENT '结构化元信息：props/params/properties/hooks',  
+ usage_count INT DEFAULT 0 COMMENT '使用频率',  
+ embedding JSON NULL COMMENT '向量',  
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,  
+ INDEX idx_type (type),  
+ INDEX idx_category (category),  
+ INDEX idx_usage (usage_count DESC)  
+ );
+
+---
+
+七、环境配置
+
+环境变量
+
+┌───────────────────────┬──────────────┬───────────────────┐  
+ │ 变量 │ 说明 │ 默认值 │
+├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_ENABLED │ 启用 MySQL │ false │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_HOST │ MySQL 主机 │ - │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_PORT │ MySQL 端口 │ 3306 │
+├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_USER │ MySQL 用户 │ - │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_PASSWORD │ MySQL 密码 │ - │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_DATABASE │ 数据库名 │ code_intelligence │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_SYMBOLS_TABLE │ 表名 │ symbols │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ EMBEDDING_SERVICE_URL │ 向量服务 URL │ - │  
+ └───────────────────────┴──────────────┴───────────────────┘
+
+环境变量加载逻辑
+
+1. 加载本地 .env
+2. 加载第三方 .env（按变量维度覆盖，只覆盖第三方明确配置的变量）
+3. 命令行参数 --KEY=VALUE 优先级最高
+
+---
+
+八、技术难点总结
+
+┌────────────┬───────────────────────────────────────────────────┐  
+ │ 模块 │ 难点 │  
+ ├────────────┼───────────────────────────────────────────────────┤  
+ │ 权重排序 │ textMatch/usage/recency/commonPath 四维权重调优 │
+├────────────┼───────────────────────────────────────────────────┤  
+ │ TS 解析 │ ts-ormorph 需要 tsconfig.json，不存在时用默认配置 │  
+ ├────────────┼───────────────────────────────────────────────────┤  
+ │ JS 解析 │ Babel 支持 JSX/TS/装饰器等复杂语法 │  
+ ├────────────┼───────────────────────────────────────────────────┤  
+ │ Meta 提取 │ 函数/接口/类/hooks 的参数、返回值、类型解析 │  
+ ├────────────┼───────────────────────────────────────────────────┤  
+ │ 路径推断 │ 从文件路径智能推断业务分类（category） │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ 结构搜索 │ meta 存储为 JSON，全表扫描 + 内存过滤 │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ 向量检索 │ 向量生成、存储、余弦相似度计算 │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ 多工具编排 │ Prompt 中多 Tool 组合调用逻辑 │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ 环境加载 │ 本地/第三方 .env 按变量维度合并 │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ CI 评论 │ PR/Commit 评论逻辑、关联 PR 查找 │  
+ └────────────┴───────────────────────────────────────────────────┘
+
+---
+
+这就是完整详细的功能总结。如需补充其他细节请告诉我。

package/dist/indexer/indexProject.js

@@ -167,6 +167,7 @@ export async function indexProject(opts) {
     const ignore = [...DEFAULT_IGNORE, ...(opts.ignore ?? [])];
     console.error(`[indexProject] patterns: ${patterns.join(', ')}`);
     const files = await fg(patterns, {
+        // 根据pattern收集文件列表，支持绝对路径和相对路径（相对于projectRoot），并自动排除node_modules、dist等常见目录。
         absolute: true,
         ignore,
         onlyFiles: true,

package/dist/prompts/reusableCodeAdvisorPrompt.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-const REUSABLE_CODE_ADVISOR_DESCRIPTION = '在实现需求时检索并推荐最合适的可复用代码代码块（函数/类/模块等）。在用户要求复用现有代码、询问是否已有组件/函数/服务、或要在多个代码块中选最优时使用。';
+const REUSABLE_CODE_ADVISOR_DESCRIPTION = '在实现需求时检索并推荐最合适的可复用代码代码块（组件/函数/类/模块等）。在用户要求复用现有代码、询问是否已有组件/函数/服务、或要在多个代码块中选最优时使用。';
 /** 与 SKILL.md 中 `# 可复用代码推荐` 起至约束、示例说明为止的正文一致（无 YAML frontmatter）。 */
 const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 
@@ -7,16 +7,16 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 
 当用户需要可复用代码或实现类需求时，按顺序执行：
 
-1. 先判断意图：若意图是“组件推荐”（如推荐表单组件、弹窗组件、列表组件等），优先调用 \`recommend_component\`；否则走通用多工具流程。
-2. 通用多工具流程中，先调用 \`search_symbols\` 检索可能满足需求的候选代码块；query 用短英文/关键词（如 formInput），需要限定类型时再加 type（如 component），不要用整句中文。
-3. 执行细则：先 \`search_symbols(limit=20)\` 拉候选，再对 Top 3 调用 \`get_symbol_detail\` 做深度判断。
-4. 若仅凭签名/摘要无法判断，对最相关的若干候选调用 \`get_symbol_detail\` 获取详情。
+1. 调用 search_symbols 检索候选，type 根据用户需求传（component/util/selector/type）
+2. 如果用户指定了结构过滤条件（props/params/properties/hooks），额外调用 search_by_structure 做结构匹配
+3. 先 search_symbols(limit=20) 拉候选，再对 Top 3 调用 get_symbol_detail 做深度判断
+4. 若仅凭签名/摘要无法判断，对最相关的若干候选调用 get_symbol_detail 获取详情
 5. 从以下维度对比候选：
    - 与用户需求的**功能匹配度**
    - **API 是否简单**、入参是否合适
    - **依赖与副作用**风险
    - **复用安全性**（稳定性、耦合度、是否便于扩展）
-6. 给出**唯一首选**推荐，并说明理由。
+6. 给出**唯一首选**推荐，并说明理由
 
 ## 回复结构
 

package/dist/server/createServer.js

@@ -1,10 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { registerRecommendComponentPrompt } from "../prompts/recommendComponentPrompt.js";
 import { registerReusableCodeAdvisorPrompt } from "../prompts/reusableCodeAdvisorPrompt.js";
 import { SymbolRepository } from "../repositories/symbolRepository.js";
 import { createSearchSymbolsTool } from "../tools/searchSymbols.js";
 import { createGetSymbolDetailTool } from "../tools/getSymbolDetail.js";
-import { createRecommendComponentTool } from "../tools/recommendComponent.js";
 import { createReindexTool } from "../tools/reindex.js";
 import { createSearchByStructureTool } from "../tools/searchByStructure.js";
 export function createServer() {
@@ -19,11 +17,8 @@ export function createServer() {
     server.tool(detailTool.name, detailTool.description, detailTool.inputSchema, detailTool.handler);
     const structureTool = createSearchByStructureTool(repository);
     server.tool(structureTool.name, structureTool.description, structureTool.inputSchema, structureTool.handler);
-    const recommendTool = createRecommendComponentTool(repository);
-    server.tool(recommendTool.name, recommendTool.description, recommendTool.inputSchema, recommendTool.handler);
     const reindexTool = createReindexTool();
     server.tool(reindexTool.name, reindexTool.description, reindexTool.inputSchema, reindexTool.handler);
-    registerRecommendComponentPrompt(server);
     registerReusableCodeAdvisorPrompt(server);
     return server;
 }

package/dist/services/embeddingClient.js

@@ -1,28 +1,27 @@
 export function createEmbeddingClient(baseUrl) {
-    const root = baseUrl.replace(/\/$/, "");
+    const root = baseUrl.replace(/\/$/, '');
     return {
         async embed(texts) {
             if (texts.length === 0)
                 return [];
             const res = await fetch(`${root}/embed`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ texts }),
-                signal: AbortSignal.timeout(180_000)
+                signal: AbortSignal.timeout(180_000),
             });
             if (!res.ok) {
-                const t = await res.text().catch(() => "");
-                throw new Error(`embedding service HTTP ${res.status}${t ? `: ${t.slice(0, 200)}` : ""}`);
+                const t = await res.text().catch(() => '');
+                throw new Error(`embedding service HTTP ${res.status}${t ? `: ${t.slice(0, 200)}` : ''}`);
             }
             const data = (await res.json());
             if (!data.embeddings || !Array.isArray(data.embeddings)) {
-                throw new Error("embedding service returned invalid JSON (missing embeddings)");
+                throw new Error('embedding service returned invalid JSON (missing embeddings)');
             }
             return data.embeddings;
-        }
+        },
     };
 }
-/** Chunked embed to avoid huge request bodies. */
 export async function embedAll(client, texts, chunkSize = 48) {
     const out = [];
     for (let i = 0; i < texts.length; i += chunkSize) {

package/dist/services/vectorMath.js

@@ -1,4 +1,4 @@
-/** Cosine similarity for equal-length numeric vectors. */
+// 计算两个向量的余弦相似度，返回值在 -1 到 1 之间，1 表示完全相似，0 表示不相关，-1 表示完全相反。
 export function cosineSimilarity(a, b) {
     if (a.length === 0 || b.length !== a.length)
         return 0;

package/dist/tools/recommendComponent.js

@@ -8,7 +8,23 @@ export const recommendComponentInput = z.object({
 export function createRecommendComponentTool(repository) {
     return {
         name: "recommend_component",
-        description: "基于关键词检索 + 可选结构过滤 + 排序 + 详情补全，推荐最合适的可复用组件。",
+        description: `推荐最合适的可复用组件。
+
+工作流（自动完成，无需关心内部细节）：
+1. 关键词检索：根据 query 在 component 类型中搜索候选
+2. 结构过滤：如果传了 props 参数，按结构匹配进一步过滤
+3. 语义排序：对候选进行语义相似度排序
+4. 详情补全：获取 Top 结果的完整代码详情
+5. 返回推荐：输出 Top N 结果及评分、理由
+
+输入参数：
+- query：搜索关键词，如 "form"、"modal"、"table"
+- props（可选）：结构过滤所需的 props，如 ["onChange", "value"]
+- limit（可选）：返回数量，默认 3，最大 20
+
+输出：
+- results 数组，每项包含 name、path、score、reason、detail
+- 如果没有合适结果，会返回最接近的候选并说明差距`,
         inputSchema: recommendComponentInput.shape,
         handler: async (input) => {
             const result = await recommendComponent(input.query, repository, {

package/dist/tools/searchByStructure.js

@@ -1,25 +1,25 @@
 // 按结构字段检索（匹配 meta.props / meta.params / meta.properties / meta.hooks）
-import { z } from "zod";
-import { rankSymbols } from "../services/ranking.js";
+import { z } from 'zod';
+import { rankSymbols } from '../services/ranking.js';
 export const searchByStructureInput = z.object({
     fields: z.array(z.string().min(1)).min(1),
-    type: z.enum(["component", "util", "selector", "type"]).optional(),
+    type: z.enum(['component', 'util', 'selector', 'type']).optional(),
     category: z.string().optional(),
     limit: z.number().int().min(1).max(100).optional().default(20),
-    ranked: z.boolean().optional().default(true)
+    ranked: z.boolean().optional().default(true),
 });
 export function createSearchByStructureTool(repository) {
     return {
-        name: "search_by_structure",
-        description: "Search symbols by structured fields like props/params/properties/hooks. Use for API-shape queries.",
+        name: 'search_by_structure',
+        description: '通过结构化字段（如 props/params/properties/hooks）搜索代码块，适用于 API 形态的查询。',
         inputSchema: searchByStructureInput.shape,
         handler: async (input) => {
             const rows = await repository.searchByStructure(input.fields, {
                 type: input.type,
                 category: input.category,
-                limit: input.limit
+                limit: input.limit,
             });
-            const query = input.fields.join(" ");
+            const query = input.fields.join(' ');
             const resultRows = input.ranked
                 ? rankSymbols(query, rows).map((item) => ({
                     name: item.symbol.name,
@@ -31,7 +31,7 @@ export function createSearchByStructureTool(repository) {
                     score: item.score,
                     reason: item.reason.summary,
                     reasonDetail: item.reason,
-                    meta: item.symbol.meta
+                    meta: item.symbol.meta,
                 }))
                 : rows.map((r) => ({
                     name: r.name,
@@ -40,16 +40,16 @@ export function createSearchByStructureTool(repository) {
                     path: r.path,
                     description: r.description,
                     usageCount: r.usageCount,
-                    meta: r.meta
+                    meta: r.meta,
                 }));
             return {
                 content: [
                     {
-                        type: "text",
-                        text: JSON.stringify(resultRows, null, 2)
-                    }
-                ]
+                        type: 'text',
+                        text: JSON.stringify(resultRows, null, 2),
+                    },
+                ],
             };
-        }
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lorrylurui/code-intelligence-mcp",
-    "version": "1.0.7",
+    "version": "1.0.8",
     "private": false,
     "description": "MCP server 提供仓库内可复用代码块（ts/tsx/js/jsx/css/less）的索引和查询能力，支持基于代码上下文的智能推荐。",
     "type": "module",