npm package: @jokeran/frontend-code-skimmer
Description: Frontend-Code-Skimmer: 不读全文，只看骨架；不搜字符，搜语义关联。支持 Vue2/Vue3/React Hooks
Latest version: 0.2.5

# Frontend-Code-Skimmer MCP

> 不读全文，只看骨架；不搜字符，搜语义关联。

AI 代码助手的智能代码索引引擎，支持 **Vue 2 / Vue 3 / React Hooks**。

## 解决什么问题？

- **7000 行大文件**：`skimmer_get_component_outline` 将其压缩为 60 行骨架，节省 95% Token
- **函数名拼写错误**：搜 `changeCash` 能找到 `changeCashValue`，自动提示 "cash 可能是 cache 的拼写错误"
- **不知道函数名**：`skimmer_find_by_behavior` 按行为搜索，搜 `storage` 直接列出所有操作 localStorage 的函数
- **同名函数串台**：`skimmer_find_symbol` / `skimmer_find_by_behavior` / `skimmer_get_call_graph` 支持 `file_path` 过滤
- **修改前评估影响**：`skimmer_get_blast_radius` 告诉你改一个函数会影响哪些地方
- **变量数据流追踪**：`skimmer_trace_data_lifecycle` 一次调用聚合声明、属性修改、参数传递、Storage 落点 4 个维度

## 10 个 MCP 工具

| 工具                             | 用途                                         |
| -------------------------------- | -------------------------------------------- |
| `skimmer_index_project`          | 初始化/更新代码索引                          |
| `skimmer_get_component_outline`  | ⭐ 获取文件骨架（极致 Token 节省）           |
| `skimmer_find_symbol`            | 智能符号搜索（支持拼写错误）                 |
| `skimmer_get_code_slice`         | 精准代码切片（只取一个函数）                 |
| `skimmer_trace_assignments`      | 变量赋值链路追踪（轻量，降级工具）           |
| `skimmer_trace_property_changes` | 对象属性修改追踪（轻量，降级工具）           |
| `skimmer_find_by_behavior`       | ⭐ 按行为标签搜索（绕过命名问题）            |
| `skimmer_trace_data_lifecycle`   | ⭐ 变量完整生命周期追踪（首选，一键聚合）    |
| `skimmer_get_call_graph`         | 函数调用关系图谱                             |
| `skimmer_get_blast_radius`       | 修改影响范围评估                             |
| `skimmer_get_project_overview`   | 项目整体概览                                 |

## 安装

```bash
git clone <this-repo>
cd frontend-code-skimmer
npm install
npm run build
```

## 配置（Cursor / Claude Desktop）

在 MCP 配置文件中添加（**不需要指定项目路径**）：

```json
{
  "mcpServers": {
    "frontend-code-skimmer": {
      "command": "node",
      "args": ["/path/to/frontend-code-skimmer/dist/index.js"],
      "autoApprove": ["skimmer_index_project", "skimmer_get_component_outline", "skimmer_find_symbol", "skimmer_get_code_slice", "skimmer_trace_assignments", "skimmer_trace_property_changes", "skimmer_find_by_behavior", "skimmer_trace_data_lifecycle", "skimmer_get_call_graph", "skimmer_get_blast_radius", "skimmer_get_project_overview"]
    }
  }
}
```

就这样，不需要任何 `env` 配置。项目路径在**每次工具调用时动态指定**。

### 多项目工作流

```
优先从编辑器工作区、已打开文件和当前上下文自动推断项目根目录绝对路径，填入 `project_path`（无需向用户追问）。

项目 A: skimmer_index_project({ project_path: "/work/project-a" })
项目 B: skimmer_index_project({ project_path: "/work/project-b" })

→ 两个项目的索引会同时缓存在内存中

→ 查项目 A:
   skimmer_get_component_outline({ project_path: "/work/project-a", file_path: "src/views/home.vue" })

→ 查项目 B:
   skimmer_find_symbol({ project_path: "/work/project-b", query: "handleSubmit" })

→ 省略 project_path 时，自动使用上次操作的项目：
   skimmer_find_symbol({ query: "handleSubmit" })  ← 自动用项目 B

→  强制全量重建索引（遇到意外异常或想重走流程时）
skimmer_index_project({ project_path: "/work/project-a", force: true })
```

### 数据库存放位置

| 情况         | 数据库位置                                       |
| ------------ | ------------------------------------------------ |
| 项目目录可写 | `<项目根>/.frontend-code-skimmer-index.db`       |
| 项目只读     | `~/.frontend-code-skimmer/databases/<项目名>.db` |

## 环境变量（全部可选）

| 变量              | 说明                           | 默认值  |
| ----------------- | ------------------------------ | ------- |
| `LENS_PROJECT`    | 全局默认项目（可选）           | 无      |
| `LENS_AUTO_INDEX` | 启动时自动索引默认项目         | `false` |
| `LENS_DB`         | 自定义数据库路径（单项目场景） | 自动    |

## 使用示例

### 1. 首次使用

```
调用 skimmer_index_project → 等待索引完成（50个文件约 2 秒）
```

### 2. 快速了解组件

```
调用 skimmer_get_component_outline({ file_path: "src/views/apply/index.vue" })
→ 返回组件所有方法、状态、行为标签的骨架视图
```

### 3. 查找拼写错误的函数

```
调用 skimmer_find_symbol({ query: "changeCash" })
→ 找到 changeCashValue，提示 "cash 可能是 cache 的拼写错误"
→ 行为标签显示: [storage:localStorage.setItem]
```

### 4. 查找操作本地存储的函数

```
调用 skimmer_find_by_behavior({ category: "storage", operation: "setItem", file_path: "src/views/apply/index.vue" })
→ 列出所有写入 localStorage 的函数，带文件位置
```

### 5. ⭐ 变量完整数据流追踪（首选）

```
调用 skimmer_trace_data_lifecycle({
  variable: "storageParams",
  file_path: "src/views/apply/index.vue",
  storage_api: "localStorage",
  max_depth: 2
})
→ 一次返回 5 个维度：
  ① 声明 & 整体赋值（含来源分层：初始化/缓存回显/用户交互）
  ② 属性修改（object.prop = xxx，含别名展开）
  ③ 作为参数被传入的调用
  ④ template 绑定 / watch / computed / return 中的读取引用
  ⑤ Storage 落点追踪（自动顺着调用链打通到 localStorage 写入）
```

### 6. 追踪变量赋值与属性修改（轻量降级）

```
skimmer_trace_assignments({ variable: "changeResult", file_path: "src/views/apply/index.vue" })
skimmer_trace_property_changes({ object: "params", property: "receiveAdr", file_path: "src/views/apply/index.vue" })
```

说明：

- 绝大多数场景推荐优先用 `skimmer_trace_data_lifecycle`，上面两个工具仅在只需查看单一维度时使用。
- `skimmer_trace_assignments` 使用 **AST 优先**（正则兜底），可稳定识别 `this.xxx = ...`、`obj[prop] = ...` 等赋值。

### 7. 函数调用图谱 & 影响评估

```
skimmer_get_call_graph({ symbol_name: "saveToCache", direction: "both" })
skimmer_get_blast_radius({ symbol_name: "saveToCache" })
```

## 框架支持

| 框架  | 解析器                          | 支持的模式                         |
| ----- | ------------------------------- | ---------------------------------- |
| Vue 2 | `vue-template-compiler` + Acorn | Options API                        |
| Vue 3 | `@vue/compiler-sfc` + Acorn     | `<script setup>` + Composition API |
| React | Acorn + `acorn-jsx`             | 函数组件 + Hooks                   |

## 行为检测

自动识别以下 API 调用并打上标签：

- `storage`：localStorage / sessionStorage
- `network`：axios / fetch
- `router`：$router / useRouter / navigate
- `vuex`：$store / useStore / dispatch / commit
- `dom`：document / $refs / $nextTick
- `event`：$emit / EventBus
- `timer`：setTimeout / setInterval
- `i18n`：$t / useI18n