@jokeran/frontend-code-skimmer 0.2.6 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +96 -34
  2. package/dist/index.js +336 -147
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -12,25 +12,44 @@ AI 代码助手的智能代码索引引擎，支持 **Vue 2 / Vue 3 / React Hook
12
12
  - **同名函数串台**：`skimmer_find_symbol` / `skimmer_find_by_behavior` / `skimmer_get_call_graph` 支持 `file_path` 过滤
13
13
  - **修改前评估影响**：`skimmer_get_blast_radius` 告诉你改一个函数会影响哪些地方
14
14
  - **变量数据流追踪**：`skimmer_trace_data_lifecycle` 一次调用聚合声明、属性修改、参数传递、Storage 落点 4 个维度
15
+ - **索引过期行号偏移**：`skimmer_get_component_outline` 和 `skimmer_get_code_slice` 会自动检测索引是否过期并给出警告
15
16
 
16
- ## 10 个 MCP 工具
17
+ ## 12 个 MCP 工具
17
18
 
18
19
  | 工具 | 用途 |
19
20
  | -------------------------------- | -------------------------------------------- |
20
- | `skimmer_index_project` | 初始化/更新代码索引 |
21
- | `skimmer_get_component_outline` | ⭐ 获取文件骨架（极致 Token 节省） |
22
- | `skimmer_find_symbol` | 智能符号搜索（支持拼写错误） |
23
- | `skimmer_get_code_slice` | 精准代码切片（只取一个函数） |
24
- | `skimmer_trace_assignments` | 变量赋值链路追踪（轻量，降级工具） |
25
- | `skimmer_trace_property_changes` | 对象属性修改追踪（轻量，降级工具） |
21
+ | `skimmer_index_project` | 初始化/更新代码索引（支持 `force: true` 全量重建） |
22
+ | `skimmer_get_component_outline` | ⭐ 获取文件骨架（极致 Token 节省，自动检测索引过期） |
23
+ | `skimmer_find_symbol` | 智能符号搜索（精确 → FTS5 → Levenshtein 三层，支持拼写错误） |
24
+ | `skimmer_get_code_slice` | 精准代码切片（只取一个函数，自动检测行号偏移） |
25
+ | `skimmer_trace_assignments` | 变量赋值链路追踪（轻量降级工具，AST 优先） |
26
+ | `skimmer_trace_property_changes` | 对象属性修改追踪（轻量降级工具） |
26
27
  | `skimmer_find_by_behavior` | ⭐ 按行为标签搜索（绕过命名问题） |
27
- | `skimmer_trace_data_lifecycle` | ⭐ 变量完整生命周期追踪（首选，一键聚合） |
28
- | `skimmer_get_call_graph` | 函数调用关系图谱 |
28
+ | `skimmer_trace_data_lifecycle` | ⭐ 变量完整生命周期追踪（首选，一键聚合 5 维度） |
29
+ | `skimmer_get_call_graph` | 函数调用关系图谱（支持 callers / callees / both） |
29
30
  | `skimmer_get_blast_radius` | 修改影响范围评估 |
30
- | `skimmer_get_project_overview` | 项目整体概览 |
31
+ | `skimmer_index_health` | 索引健康检查（索引文件数、符号数、watcher 状态、DB 大小） |
32
+ | `skimmer_get_project_overview` | 项目整体概览（文件数、符号数、框架分布） |
31
33
 
32
34
  ## 安装
33
35
 
36
+ ### 方式一：npx 直接使用（推荐）
37
+
38
+ 无需克隆仓库，直接在 MCP 配置中使用：
39
+
40
+ ```json
41
+ {
42
+ "mcpServers": {
43
+ "frontend-code-skimmer": {
44
+ "command": "npx",
45
+ "args": ["-y", "@jokeran/frontend-code-skimmer"]
46
+ }
47
+ }
48
+ }
49
+ ```
50
+
51
+ ### 方式二：本地克隆构建
52
+
34
53
  ```bash
35
54
  git clone <this-repo>
36
55
  cd frontend-code-skimmer
@@ -40,7 +59,28 @@ npm run build
40
59
 
41
60
  ## 配置（Cursor / Claude Desktop）
42
61
 
43
- 在 MCP 配置文件中添加（**不需要指定项目路径**）：
62
+ ### npx 安装（推荐）
63
+
64
+ ```json
65
+ {
66
+ "mcpServers": {
67
+ "frontend-code-skimmer": {
68
+ "command": "npx",
69
+ "args": ["-y", "@jokeran/frontend-code-skimmer"],
70
+ "autoApprove": [
71
+ "skimmer_index_project", "skimmer_get_component_outline",
72
+ "skimmer_find_symbol", "skimmer_get_code_slice",
73
+ "skimmer_trace_assignments", "skimmer_trace_property_changes",
74
+ "skimmer_find_by_behavior", "skimmer_trace_data_lifecycle",
75
+ "skimmer_get_call_graph", "skimmer_get_blast_radius",
76
+ "skimmer_index_health", "skimmer_get_project_overview"
77
+ ]
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ ### 本地构建安装
44
84
 
45
85
  ```json
46
86
  {
@@ -48,23 +88,30 @@ npm run build
48
88
  "frontend-code-skimmer": {
49
89
  "command": "node",
50
90
  "args": ["/path/to/frontend-code-skimmer/dist/index.js"],
51
- "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"]
91
+ "autoApprove": [
92
+ "skimmer_index_project", "skimmer_get_component_outline",
93
+ "skimmer_find_symbol", "skimmer_get_code_slice",
94
+ "skimmer_trace_assignments", "skimmer_trace_property_changes",
95
+ "skimmer_find_by_behavior", "skimmer_trace_data_lifecycle",
96
+ "skimmer_get_call_graph", "skimmer_get_blast_radius",
97
+ "skimmer_index_health", "skimmer_get_project_overview"
98
+ ]
52
99
  }
53
100
  }
54
101
  }
55
102
  ```
56
103
 
57
- 就这样，不需要任何 `env` 配置。项目路径在**每次工具调用时动态指定**。
104
+ 不需要任何 `env` 配置。项目路径在**每次工具调用时动态指定**。
58
105
 
59
106
  ### 多项目工作流
60
107
 
61
108
  ```
62
- 优先从编辑器工作区、已打开文件和当前上下文自动推断项目根目录绝对路径，填入 `project_path`（无需向用户追问）。
109
+ 优先从编辑器工作区、已打开文件和当前上下文自动推断项目根目录绝对路径，填入 project_path（无需向用户追问）。
63
110
 
64
111
  项目 A: skimmer_index_project({ project_path: "/work/project-a" })
65
112
  项目 B: skimmer_index_project({ project_path: "/work/project-b" })
66
113
 
67
- → 两个项目的索引会同时缓存在内存中
114
+ → 两个项目的索引同时缓存（最多 8 个项目，LRU 淘汰）
68
115
 
69
116
  → 查项目 A:
70
117
  skimmer_get_component_outline({ project_path: "/work/project-a", file_path: "src/views/home.vue" })
@@ -73,40 +120,45 @@ npm run build
73
120
  skimmer_find_symbol({ project_path: "/work/project-b", query: "handleSubmit" })
74
121
 
75
122
  → 省略 project_path 时，自动使用上次操作的项目：
76
- skimmer_find_symbol({ query: "handleSubmit" }) ← 自动用项目 B
123
+ skimmer_find_symbol({ query: "handleSubmit" })
77
124
 
78
- → 强制全量重建索引（遇到意外异常或想重走流程时）
79
- skimmer_index_project({ project_path: "/work/project-a", force: true })
125
+ → 文件修改后强制全量重建索引：
126
+ skimmer_index_project({ project_path: "/work/project-a", force: true })
80
127
  ```
81
128
 
82
129
  ### 数据库存放位置
83
130
 
84
- | 情况 | 数据库位置 |
85
- | ------------ | ------------------------------------------------ |
86
- | 项目目录可写 | `<项目根>/.frontend-code-skimmer-index.db` |
87
- | 项目只读 | `~/.frontend-code-skimmer/databases/<项目名>.db` |
131
+ | 情况 | 数据库位置 |
132
+ | ------------ | ----------------------------------------------------------------- |
133
+ | 项目目录可写 | `<项目根>/.agent/skimmer_find_symbol/.skimmer-index.db` |
134
+ | 项目只读 | `~/.frontend-code-skimmer/databases/<hash>_<path尾部>.db` |
135
+ | 自定义路径 | `SKIMMER_DB` 环境变量指定的路径（仅单项目场景有效） |
88
136
 
89
137
  ## 环境变量（全部可选）
90
138
 
91
- | 变量 | 说明 | 默认值 |
92
- | ----------------- | ------------------------------ | ------- |
93
- | `LENS_PROJECT` | 全局默认项目（可选） | 无 |
94
- | `LENS_AUTO_INDEX` | 启动时自动索引默认项目 | `false` |
95
- | `LENS_DB` | 自定义数据库路径（单项目场景） | 自动 |
139
+ | 变量 | 说明 | 默认值 |
140
+ | -------------------------- | ------------------------------------------- | ------- |
141
+ | `SKIMMER_PROJECT` | 全局默认项目路径 | 无 |
142
+ | `SKIMMER_AUTO_INDEX` | 启动时自动索引默认项目（需配合上一项使用） | `false` |
143
+ | `SKIMMER_DB` | 自定义数据库路径（仅单项目场景有效） | 自动 |
144
+ | `SKIMMER_MAX_OPEN_PROJECTS`| 最大同时打开的项目数（LRU 淘汰） | `8` |
145
+ | `SKIMMER_DB_IDLE_MINUTES` | 项目空闲多久后自动关闭数据库连接（分钟） | `30` |
146
+ | `SKIMMER_DB_TTL_DAYS` | 全局缓存数据库的 TTL（天），过期自动清理 | `14` |
96
147
 
97
148
  ## 使用示例
98
149
 
99
150
  ### 1. 首次使用
100
151
 
101
152
  ```
102
- 调用 skimmer_index_project → 等待索引完成（50个文件约 2 秒）
153
+ 调用 skimmer_index_project → 等待索引完成（50 个文件约 2 秒）
103
154
  ```
104
155
 
105
156
  ### 2. 快速了解组件
106
157
 
107
158
  ```
108
159
  调用 skimmer_get_component_outline({ file_path: "src/views/apply/index.vue" })
109
- → 返回组件所有方法、状态、行为标签的骨架视图
160
+ → 返回组件所有方法、状态、行为标签的骨架视图（7000 行 → 60 行）
161
+ → 若文件在索引后被修改，自动输出 ⚠️ [索引已过期] 警告并提示重建
110
162
  ```
111
163
 
112
164
  ### 3. 查找拼写错误的函数
@@ -160,13 +212,23 @@ skimmer_get_call_graph({ symbol_name: "saveToCache", direction: "both" })
160
212
  skimmer_get_blast_radius({ symbol_name: "saveToCache" })
161
213
  ```
162
214
 
215
+ ### 8. 索引行号不准怎么办？
216
+
217
+ 行号偏移的根本原因是索引未及时更新。排查步骤：
218
+
219
+ 1. `skimmer_get_component_outline` 返回 `⚠️ [索引已过期]` → 立即执行第 2 步
220
+ 2. `skimmer_get_code_slice` 返回 `⚠️ [行号偏移]` → 说明代码切片位置不对
221
+ 3. 强制重建：`skimmer_index_project({ project_path: "...", force: true })`
222
+
223
+ > v0.2.7 起：增量索引同时校验 **mtime + 文件大小**，解决部分编辑器不更新 mtime 导致的漏检问题。
224
+
163
225
  ## 框架支持
164
226
 
165
- | 框架 | 解析器 | 支持的模式 |
166
- | ----- | ------------------------------- | ---------------------------------- |
167
- | Vue 2 | `vue-template-compiler` + Acorn | Options API |
168
- | Vue 3 | `@vue/compiler-sfc` + Acorn | `<script setup>` + Composition API |
169
- | React | Acorn + `acorn-jsx` | 函数组件 + Hooks |
227
+ | 框架 | SFC 分离 | AST 解析 | 支持的模式 |
228
+ | ----- | ------------------------ | -------------------- | ----------------------------------- |
229
+ | Vue 2 | `vue-template-compiler` | `@babel/parser` | Options API |
230
+ | Vue 3 | `@vue/compiler-sfc` | `@babel/parser` | `<script setup>` + Composition API |
231
+ | React | — | `@babel/parser` + JSX| 函数组件 + Hooks |
170
232
 
171
233
  ## 行为检测
172
234