@jokeran/frontend-code-skimmer 0.1.6

package/README.md

@@ -0,0 +1,179 @@
+# 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` 告诉你改一个函数会影响哪些地方
+
+## 13 个 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_api_calls`       | 网络 API 调用追踪                  |
+| `skimmer_get_call_graph`        | 函数调用关系图谱                   |
+| `skimmer_trace_key_flow`        | ⭐ 单工具 key 链路追踪             |
+| `skimmer_visualize_dataflow`    | 赋值+调用+落点合并视图             |
+| `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_api_calls", "skimmer_get_call_graph", "skimmer_trace_key_flow", "skimmer_visualize_dataflow", "skimmer_get_blast_radius", "skimmer_get_project_overview"]
+    }
+  }
+}
+```
+
+就这样，不需要任何 `env` 配置。项目路径在**每次工具调用时动态指定**。
+
+### 多项目工作流
+
+```
+项目 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
+```
+
+### 数据库存放位置
+
+| 情况         | 数据库位置                          |
+| ------------ | ----------------------------------- |
+| 项目目录可写 | `<项目根>/.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. 追踪某个 key 通过哪个调用链进入缓存
+
+```
+调用 skimmer_trace_key_flow({
+  key: "storageParams",
+  file_path: "src/views/apply/index.vue",
+  storage_api: "localStorage",
+  max_depth: 2
+})
+→ 一次返回：调用入口 + 下游方法链 + storage 落点
+```
+
+### 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_assignments` 已升级为 **AST 优先**（正则兜底），可更稳定识别 `this.xxx = ...`、`obj[prop] = ...` 等赋值。
+
+### 7. 追踪接口调用
+
+```
+skimmer_trace_api_calls({ file_path: "src/views/apply/index.vue", keyword: "/queryDetailForC" })
+```
+
+说明：
+- 支持识别封装网络调用（如 `this.aksCommonHandle(...)`、`xxxApi.request(...)`）并归类为 `network`。
+
+### 8. 数据流总览（轻量）
+
+```
+skimmer_visualize_dataflow({ variable: "storageParams", file_path: "src/views/apply/index.vue", max_depth: 2 })
+```
+
+## 框架支持
+
+| 框架  | 解析器                          | 支持的模式                         |
+| ----- | ------------------------------- | ---------------------------------- |
+| 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