@lorrylurui/code-intelligence-mcp 1.1.14 → 1.2.0

package/README.md

@@ -1,614 +1,107 @@
-# Code Intelligence MCP (Minimal)
-
-最小可用的 Node MCP Server 框架，包含：
+# Code Intelligence MCP
 
 - MCP Server（stdio）
-- Tool: `search_symbols`（支持 `semantic=true` 语义检索，Phase 5）
+- Tool: `search_symbols`
 - 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（推荐本地开发）
+- Tool: `incUsage`
+- Prompt: `reusable-code-advisor`
+- Cursor Skill：`reusable-code-advisor`（`.cursor/skills/reusable-code-advisor/`，
 
-1. 安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)（或 Docker Engine + Compose 插件）。
-2. 在项目根目录执行：
+## 1) 配置mcp servers
 
-```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
-```
-
-### 自定义表名（第三方项目集成）
-
-若需使用不同的表名，可通过环境变量配置：
-
-```bash
-# 设置自定义表名
-export MYSQL_SYMBOLS_TABLE=my_project_symbols
-
-# 然后server代码内部执行建表（表名会在代码中动态替换）
-mysql -u root -p code_intelligence -e "$(node -e \"import('./dist/db/schema.js').then(m => console.log(m.getSymbolsTableSQL()))\")"
-```
-
-或在 `.env` 中配置：
-
-```env
-MYSQL_SYMBOLS_TABLE=my_project_symbols
-```
-
-## 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
-- 脚本 cli 启动：npx code-intelligence-mcp（走mcp不执行）
-- 给项目做索引，运行：npx code-intelligence-index, 项目根目录取配置或者cwd（重要，首次以及后续需要时执行：新项目必须执行一次建表）
----
-
-### MCP 配置（核心）
-
-```md
-## MCP Config
-
-```json
 {
   "mcpServers": {
-    "code-intelligence": {
+    "code-intelligence-mcp": {
       "command": "npx",
-      "args": ["code-intelligence-mcp"]
+      "args": ["-y", "@lorrylurui/code-intelligence-mcp"]
     }
   }
 }
----
-
-### 支持的 Tools Prompts
-
-```md
-## Tools
-
-- search_symbols
-- get_symbol_detail
-- search_by_structure
-- recommend_component
-- reindex
-
-## Prompts
-
-- 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 查找 │  
- └────────────┴───────────────────────────────────────────────────┘
-
----
+```
 
-这就是完整详细的功能总结。如需补充其他细节请告诉我。
+## 2)配置流水线
+
+```
+    - uses: lorrylurui/code-intelligence-check@v1
+```
+
+## 3) 项目根目录环境变量
+
+<!-- 最小配置 1.表名 2.需要检索的文件路径和类型 -->
+
+MYSQL\*SYMBOLS_TABLE=frontend_collections_symbols
+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优化