@jokeran/frontend-code-skimmer 0.4.7 → 0.4.9
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.
- package/README.md +367 -322
- package/dist/index.js +172 -150
- package/package.json +51 -50
package/README.md
CHANGED
|
@@ -1,322 +1,367 @@
|
|
|
1
|
-
# Frontend-Code-Skimmer MCP
|
|
2
|
-
|
|
3
|
-
> 不读全文，只看骨架；不搜字符，搜语义关联。
|
|
4
|
-
|
|
5
|
-
AI 代码助手的智能代码索引引擎，面向 **Vue 2 / Vue 3 / React / 纯 TS/JS 工具模块** 的结构化检索与影响分析场景。
|
|
6
|
-
|
|
7
|
-
当前版本的能力重点：
|
|
8
|
-
|
|
9
|
-
- 支持 Vue 2、Vue 3、React 组件/模块索引
|
|
10
|
-
- `precision_mode="precise"` 支持 **JS / JSX / TS / TSX** 的跨文件 import/export 精确绑定
|
|
11
|
-
- 对 **纯 TS/JS 工具类模块** 提供基础符号提取（class / method / function / constant）
|
|
12
|
-
- `skimmer_index_health` 可显示**真实失败文件与错误信息**，便于排障
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
| `
|
|
35
|
-
| `
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
- **
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
"
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
"
|
|
113
|
-
"
|
|
114
|
-
"
|
|
115
|
-
"
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
###
|
|
125
|
-
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
###
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
→
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
###
|
|
198
|
-
|
|
199
|
-
```
|
|
200
|
-
调用
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
})
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
```
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
1
|
+
# Frontend-Code-Skimmer MCP
|
|
2
|
+
|
|
3
|
+
> 不读全文，只看骨架；不搜字符，搜语义关联。
|
|
4
|
+
|
|
5
|
+
AI 代码助手的智能代码索引引擎，面向 **Vue 2 / Vue 3 / React / 纯 TS/JS 工具模块** 的结构化检索与影响分析场景。
|
|
6
|
+
|
|
7
|
+
当前版本的能力重点：
|
|
8
|
+
|
|
9
|
+
- 支持 Vue 2、Vue 3、React 组件/模块索引
|
|
10
|
+
- `precision_mode="precise"` 支持 **JS / JSX / TS / TSX** 的跨文件 import/export 精确绑定
|
|
11
|
+
- 对 **纯 TS/JS 工具类模块** 提供基础符号提取（class / method / function / constant）
|
|
12
|
+
- `skimmer_index_health` 可显示**真实失败文件与错误信息**，便于排障
|
|
13
|
+
- `skimmer_search_snippets` 已支持 **query intent 分类 + snippet-first 排序 + 业务文件优先**
|
|
14
|
+
|
|
15
|
+
## 解决什么问题？
|
|
16
|
+
|
|
17
|
+
- **7000 行大文件**：`skimmer_get_component_outline` 将其压缩为 60 行骨架，节省 95% Token
|
|
18
|
+
- **自然语言第一跳太吵**：`skimmer_search_snippets` 直接返回高相关代码片段，避免先猜函数名再二跳读文件
|
|
19
|
+
- **API 查询先落到 util 包装层**：`skimmer_search_snippets` 会优先抬升 `views/pages/features` 等业务实现，压低 `config/utils/helpers` 这类通用封装
|
|
20
|
+
- **函数名拼写错误**：搜 `changeCash` 能找到 `changeCashValue`，自动提示 "cash 可能是 cache 的拼写错误"
|
|
21
|
+
- **不知道函数名**：`skimmer_find_by_behavior` 按行为搜索，搜 `storage` 直接列出所有操作 localStorage 的函数
|
|
22
|
+
- **同名函数串台**：`skimmer_find_symbol` / `skimmer_find_by_behavior` / `skimmer_get_call_graph` 支持 `file_path` 过滤
|
|
23
|
+
- **修改前评估影响**：`skimmer_get_blast_radius` 告诉你改一个函数会影响哪些地方
|
|
24
|
+
- **变量数据流追踪**：`skimmer_trace_data_lifecycle` 一次调用聚合声明、属性修改、参数传递、Storage 落点 4 个维度
|
|
25
|
+
- **索引过期行号偏移**：`skimmer_get_component_outline` 和 `skimmer_get_code_slice` 会自动检测索引是否过期并给出警告
|
|
26
|
+
- **纯 TS/JS 工具类模块也能审**：支持提取 class、method、top-level function、const，适合 parser / indexer / cache / CLI / MCP 工具模块
|
|
27
|
+
- **跨文件 import 关系误判少**：precise 模式会识别本地 shadowing，import 名在局部作用域被参数/变量遮蔽时不会误标为精确边
|
|
28
|
+
- **索引坏了怎么查**：`skimmer_index_health` 可直接看到失败文件数量、最近失败文件和错误摘要
|
|
29
|
+
|
|
30
|
+
## 12 个 MCP 工具
|
|
31
|
+
|
|
32
|
+
| 工具 | 用途 |
|
|
33
|
+
| -------------------------------- | -------------------------------------------- |
|
|
34
|
+
| `skimmer_index_project` | 初始化/更新代码索引（支持 `force: true` 全量重建） |
|
|
35
|
+
| `skimmer_get_component_outline` | ⭐ 获取文件骨架（极致 Token 节省，自动检测索引过期） |
|
|
36
|
+
| `skimmer_find_symbol` | 智能符号搜索（精确 → FTS5 → Levenshtein 三层，支持拼写错误） |
|
|
37
|
+
| `skimmer_search_snippets` | ⭐ 代码片段搜索（snippet-first，适合自然语言第一跳） |
|
|
38
|
+
| `skimmer_get_code_slice` | 精准代码切片（只取一个函数，自动检测行号偏移） |
|
|
39
|
+
| `skimmer_trace_assignments` | 变量赋值链路追踪（轻量降级工具，AST 优先） |
|
|
40
|
+
| `skimmer_trace_property_changes` | 对象属性修改追踪（轻量降级工具） |
|
|
41
|
+
| `skimmer_find_by_behavior` | ⭐ 按行为标签搜索（绕过命名问题） |
|
|
42
|
+
| `skimmer_trace_data_lifecycle` | ⭐ 变量完整生命周期追踪（首选，一键聚合 5 维度） |
|
|
43
|
+
| `skimmer_get_call_graph` | 函数调用关系图谱（支持 callers / callees / both） |
|
|
44
|
+
| `skimmer_get_blast_radius` | 修改影响范围评估 |
|
|
45
|
+
| `skimmer_index_health` | 索引健康检查（索引文件/符号/关系/行为、失败文件、watcher、DB 大小） |
|
|
46
|
+
| `skimmer_get_project_overview` | 项目整体概览（文件数、符号数、框架分布） |
|
|
47
|
+
|
|
48
|
+
## 最近增强 / 稳定性说明
|
|
49
|
+
|
|
50
|
+
- **JSX precise 生效**：precise 模式不再局限于 `ts/tsx`，现在会对 `js/jsx/ts/tsx` 模块做跨文件 import/export 绑定增强
|
|
51
|
+
- **re-export / barrel 链扩散更完整**：`selective_precise=true` 会把 `re-export` 也纳入依赖签名和反向依赖扩散，barrel 变更不再只重算当前文件
|
|
52
|
+
- **local shadowing 保护**：若 import 名在函数局部被参数或变量重新声明，会保留 heuristic，避免把本地变量误判成跨文件精确调用
|
|
53
|
+
- **工具类模块覆盖增强**：新增 Tooling TS/JS Parser，能抽取 class、class method、top-level function、constant 等基础符号
|
|
54
|
+
- **index health 更真实**：索引失败文件会持久化，`skimmer_index_health` 可查看最近失败文件和错误，而不是只看总量
|
|
55
|
+
- **snippet 搜索引入 query intent**：区分 `symbol_like / behavior_like / api_like / natural_language`，工具输出会直接显示意图，便于调权和排障
|
|
56
|
+
- **业务文件优先排序**：对 `views/pages/features/modules` 等业务文件加分，对 `config/utils/helpers/lib/shared` 等通用封装降权；在真实 Vue2 项目中，`localStorage setItem` 已可优先命中业务页实现而不是 `mUtils.js`
|
|
57
|
+
- **评测集已固化**：仓库内有固定 snippet 回归测试，外部真实项目可通过 `eval/snippet-suites/*.json` + `npm run eval:snippet` 一键复跑
|
|
58
|
+
|
|
59
|
+
## 安装
|
|
60
|
+
|
|
61
|
+
### 方式一：npx 直接使用（推荐）
|
|
62
|
+
|
|
63
|
+
无需克隆仓库，直接在 MCP 配置中使用：
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"mcpServers": {
|
|
68
|
+
"frontend-code-skimmer": {
|
|
69
|
+
"command": "npx",
|
|
70
|
+
"args": ["-y", "@jokeran/frontend-code-skimmer"]
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### 方式二：本地克隆构建
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
git clone <this-repo>
|
|
80
|
+
cd frontend-code-skimmer
|
|
81
|
+
npm install
|
|
82
|
+
npm run build
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### 方式三：运行 snippet 评测集（开发调权用）
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
# 仓库内固定评测集
|
|
89
|
+
npm test
|
|
90
|
+
|
|
91
|
+
# 真实项目回归（以 apply-claim 为例）
|
|
92
|
+
npm run eval:snippet -- --project /Users/anshunli1/jd/workSpace/jdGit/apply-claim --suite ./eval/snippet-suites/apply-claim.json
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
说明：
|
|
96
|
+
|
|
97
|
+
- `npm test` 会跑固定 fixture 评测集，适合日常开发时快速防回归
|
|
98
|
+
- `npm run eval:snippet` 用于真实项目相关性回归，适合调权、改 query 规则、评估业务文件优先是否生效
|
|
99
|
+
- `eval/snippet-suites/*.json` 只属于研发保障设施，不参与运行时主链路
|
|
100
|
+
|
|
101
|
+
## 配置（Cursor / Claude Desktop）
|
|
102
|
+
|
|
103
|
+
### npx 安装（推荐）
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"mcpServers": {
|
|
108
|
+
"frontend-code-skimmer": {
|
|
109
|
+
"command": "npx",
|
|
110
|
+
"args": ["-y", "@jokeran/frontend-code-skimmer"],
|
|
111
|
+
"autoApprove": [
|
|
112
|
+
"skimmer_index_project", "skimmer_get_component_outline",
|
|
113
|
+
"skimmer_find_symbol", "skimmer_search_snippets", "skimmer_get_code_slice",
|
|
114
|
+
"skimmer_trace_assignments", "skimmer_trace_property_changes",
|
|
115
|
+
"skimmer_find_by_behavior", "skimmer_trace_data_lifecycle",
|
|
116
|
+
"skimmer_get_call_graph", "skimmer_get_blast_radius",
|
|
117
|
+
"skimmer_index_health", "skimmer_get_project_overview"
|
|
118
|
+
]
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### 本地构建安装
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"mcpServers": {
|
|
129
|
+
"frontend-code-skimmer": {
|
|
130
|
+
"command": "node",
|
|
131
|
+
"args": ["/path/to/frontend-code-skimmer/dist/index.js"],
|
|
132
|
+
"autoApprove": [
|
|
133
|
+
"skimmer_index_project", "skimmer_get_component_outline",
|
|
134
|
+
"skimmer_find_symbol", "skimmer_search_snippets", "skimmer_get_code_slice",
|
|
135
|
+
"skimmer_trace_assignments", "skimmer_trace_property_changes",
|
|
136
|
+
"skimmer_find_by_behavior", "skimmer_trace_data_lifecycle",
|
|
137
|
+
"skimmer_get_call_graph", "skimmer_get_blast_radius",
|
|
138
|
+
"skimmer_index_health", "skimmer_get_project_overview"
|
|
139
|
+
]
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
不需要任何 `env` 配置。项目路径在**每次工具调用时动态指定**。
|
|
146
|
+
|
|
147
|
+
### 多项目工作流
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
优先从编辑器工作区、已打开文件和当前上下文自动推断项目根目录绝对路径，填入 project_path（无需向用户追问）。
|
|
151
|
+
|
|
152
|
+
项目 A: skimmer_index_project({ project_path: "/work/project-a" })
|
|
153
|
+
项目 B: skimmer_index_project({ project_path: "/work/project-b" })
|
|
154
|
+
|
|
155
|
+
→ 两个项目的索引同时缓存（最多 8 个项目，LRU 淘汰）
|
|
156
|
+
|
|
157
|
+
→ 查项目 A:
|
|
158
|
+
skimmer_get_component_outline({ project_path: "/work/project-a", file_path: "src/views/home.vue" })
|
|
159
|
+
|
|
160
|
+
→ 查项目 B:
|
|
161
|
+
skimmer_find_symbol({ project_path: "/work/project-b", query: "handleSubmit" })
|
|
162
|
+
|
|
163
|
+
→ 省略 project_path 时，自动使用上次操作的项目：
|
|
164
|
+
skimmer_find_symbol({ query: "handleSubmit" })
|
|
165
|
+
|
|
166
|
+
→ 文件修改后强制全量重建索引：
|
|
167
|
+
skimmer_index_project({ project_path: "/work/project-a", force: true })
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### 数据库存放位置
|
|
171
|
+
|
|
172
|
+
| 情况 | 数据库位置 |
|
|
173
|
+
| ------------ | ----------------------------------------------------------------- |
|
|
174
|
+
| 项目目录可写 | `<项目根>/.agent/skimmer_find_symbol/.skimmer-index.db` |
|
|
175
|
+
| 项目只读 | `~/.frontend-code-skimmer/databases/<hash>_<path尾部>.db` |
|
|
176
|
+
| 自定义路径 | `SKIMMER_DB` 环境变量指定的路径（仅单项目场景有效） |
|
|
177
|
+
|
|
178
|
+
## 环境变量（全部可选）
|
|
179
|
+
|
|
180
|
+
| 变量 | 说明 | 默认值 |
|
|
181
|
+
| --------------------------- | ------------------------------------------ | ------- |
|
|
182
|
+
| `SKIMMER_PROJECT` | 全局默认项目路径 | 无 |
|
|
183
|
+
| `SKIMMER_AUTO_INDEX` | 启动时自动索引默认项目（需配合上一项使用） | `false` |
|
|
184
|
+
| `SKIMMER_DB` | 自定义数据库路径（仅单项目场景有效） | 自动 |
|
|
185
|
+
| `SKIMMER_MAX_OPEN_PROJECTS` | 最大同时打开的项目数（LRU 淘汰） | `8` |
|
|
186
|
+
| `SKIMMER_DB_IDLE_MINUTES` | 项目空闲多久后自动关闭数据库连接（分钟） | `30` |
|
|
187
|
+
| `SKIMMER_DB_TTL_DAYS` | 全局缓存数据库的 TTL（天），过期自动清理 | `14` |
|
|
188
|
+
|
|
189
|
+
## 使用示例
|
|
190
|
+
|
|
191
|
+
### 1. 首次使用
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
调用 skimmer_index_project → 等待索引完成（50 个文件约 2 秒）
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### 2. 快速了解组件
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
调用 skimmer_get_component_outline({ file_path: "src/views/apply/index.vue" })
|
|
201
|
+
→ 返回组件所有方法、状态、行为标签的骨架视图（7000 行 → 60 行）
|
|
202
|
+
→ 若文件在索引后被修改，自动输出 ⚠️ [索引已过期] 警告并提示重建
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### 3. 查找拼写错误的函数
|
|
206
|
+
|
|
207
|
+
```
|
|
208
|
+
调用 skimmer_find_symbol({ query: "changeCash" })
|
|
209
|
+
→ 找到 changeCashValue，提示 "cash 可能是 cache 的拼写错误"
|
|
210
|
+
→ 行为标签显示: [storage:localStorage.setItem]
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### 3.5 ⭐ 自然语言第一跳代码片段搜索
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
调用 skimmer_search_snippets({ query: "save to cache" })
|
|
217
|
+
→ 直接返回 changeCacheValue / persistDraft 等高相关代码片段
|
|
218
|
+
→ 优先看 snippet，不必先猜函数名再调用 get_code_slice
|
|
219
|
+
→ 输出会显示查询意图，如 `behavior_like`
|
|
220
|
+
|
|
221
|
+
调用 skimmer_search_snippets({ query: "localStorage setItem" })
|
|
222
|
+
→ 直接返回 localStorage.setItem 所在实现片段
|
|
223
|
+
→ 显式 API 查询会识别为 `api_like`，优先按行为实现排序
|
|
224
|
+
→ 若同时存在业务页实现和 util 封装，默认优先业务文件
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
当前排序信号（面向 Agent 第一跳）：
|
|
228
|
+
|
|
229
|
+
- query intent：`symbol_like / behavior_like / api_like / natural_language`
|
|
230
|
+
- definition boost：可执行定义（function / method / hook / lifecycle）优先于常量/元数据
|
|
231
|
+
- file coherence：同一文件内多处相关命中会整体抬升
|
|
232
|
+
- file role：`views/pages/features/modules` 业务文件优先，`config/utils/helpers/lib/shared` 通用封装降权
|
|
233
|
+
- noise penalty：测试、mock、demo、声明文件降权
|
|
234
|
+
|
|
235
|
+
### 4. 查找操作本地存储的函数
|
|
236
|
+
|
|
237
|
+
```
|
|
238
|
+
调用 skimmer_find_by_behavior({ category: "storage", operation: "setItem", file_path: "src/views/apply/index.vue" })
|
|
239
|
+
→ 列出所有写入 localStorage 的函数，带文件位置
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
### 5. ⭐ 变量完整数据流追踪（首选）
|
|
243
|
+
|
|
244
|
+
```
|
|
245
|
+
调用 skimmer_trace_data_lifecycle({
|
|
246
|
+
variable: "storageParams",
|
|
247
|
+
file_path: "src/views/apply/index.vue",
|
|
248
|
+
storage_api: "localStorage",
|
|
249
|
+
max_depth: 2
|
|
250
|
+
})
|
|
251
|
+
→ 一次返回 5 个维度：
|
|
252
|
+
① 声明 & 整体赋值（含来源分层：初始化/缓存回显/用户交互）
|
|
253
|
+
② 属性修改（object.prop = xxx，含别名展开）
|
|
254
|
+
③ 作为参数被传入的调用
|
|
255
|
+
④ template 绑定 / watch / computed / return 中的读取引用
|
|
256
|
+
⑤ Storage 落点追踪（自动顺着调用链打通到 localStorage 写入）
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
### 6. 追踪变量赋值与属性修改（轻量降级）
|
|
260
|
+
|
|
261
|
+
```
|
|
262
|
+
skimmer_trace_assignments({ variable: "changeResult", file_path: "src/views/apply/index.vue" })
|
|
263
|
+
skimmer_trace_property_changes({ object: "params", property: "receiveAdr", file_path: "src/views/apply/index.vue" })
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
说明：
|
|
267
|
+
|
|
268
|
+
- 绝大多数场景推荐优先用 `skimmer_trace_data_lifecycle`，上面两个工具仅在只需查看单一维度时使用。
|
|
269
|
+
- `skimmer_trace_assignments` 使用 **AST 优先**（正则兜底），可稳定识别 `this.xxx = ...`、`obj[prop] = ...` 等赋值。
|
|
270
|
+
|
|
271
|
+
### 7. 函数调用图谱 & 影响评估
|
|
272
|
+
|
|
273
|
+
```
|
|
274
|
+
skimmer_get_call_graph({ symbol_name: "saveToCache", direction: "both" })
|
|
275
|
+
skimmer_get_blast_radius({ symbol_name: "saveToCache" })
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
### 8. 精度模式（precise）
|
|
279
|
+
|
|
280
|
+
`precision_mode="precise"` 用于增强跨文件 import/export 绑定。
|
|
281
|
+
|
|
282
|
+
前提与边界：
|
|
283
|
+
|
|
284
|
+
- 需要项目根目录存在 `tsconfig.json`，否则会自动降级到 `heuristic`
|
|
285
|
+
- 当前精确绑定覆盖 **JS / JSX / TS / TSX** 文件
|
|
286
|
+
- 适合查 `import { foo } from './bar'` 这类跨文件调用，不等于完整类型系统求值
|
|
287
|
+
- 若 import 名在局部作用域被参数/变量遮蔽，会保留 heuristic，避免误判
|
|
288
|
+
|
|
289
|
+
示例：
|
|
290
|
+
|
|
291
|
+
```js
|
|
292
|
+
skimmer_index_project({
|
|
293
|
+
project_path: "/work/project-a",
|
|
294
|
+
precision_mode: "precise"
|
|
295
|
+
})
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### 9. 选择性 precise 重算（大项目推荐）
|
|
299
|
+
|
|
300
|
+
`selective_precise=true` 会在索引后只重算**变更文件 + 受影响文件**，降低 precise 全量成本。
|
|
301
|
+
|
|
302
|
+
当前规则：
|
|
303
|
+
|
|
304
|
+
- `body_only`：只重算当前文件 precise
|
|
305
|
+
- `import_changed`：只重算当前文件
|
|
306
|
+
- `export_changed` / `full_changed`：重算当前文件 + 所有直接/间接依赖它的文件
|
|
307
|
+
- `re-export` / barrel 链会纳入 import 签名与反向依赖扩散
|
|
308
|
+
|
|
309
|
+
示例：
|
|
310
|
+
|
|
311
|
+
```js
|
|
312
|
+
skimmer_index_project({
|
|
313
|
+
project_path: "/work/project-a",
|
|
314
|
+
precision_mode: "precise",
|
|
315
|
+
selective_precise: true,
|
|
316
|
+
max_precise_files: 20
|
|
317
|
+
})
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
### 10. 索引行号不准怎么办？
|
|
321
|
+
|
|
322
|
+
行号偏移的根本原因通常是索引未及时更新。排查步骤：
|
|
323
|
+
|
|
324
|
+
1. `skimmer_get_component_outline` 返回 `⚠️ [索引已过期]` → 立即执行第 3 步
|
|
325
|
+
2. `skimmer_get_code_slice` 返回 `⚠️ [行号偏移]` → 说明代码切片位置不对
|
|
326
|
+
3. 强制重建：`skimmer_index_project({ project_path: "...", force: true })`
|
|
327
|
+
|
|
328
|
+
> 当前增量索引使用 **mtime + 文件大小** 做快速跳过，能覆盖大多数变更场景；如果你的编辑器或同步工具存在极端时间戳行为，仍建议在异常时执行 `force: true` 全量重建。
|
|
329
|
+
|
|
330
|
+
### 11. 索引坏了怎么排障？
|
|
331
|
+
|
|
332
|
+
```js
|
|
333
|
+
skimmer_index_health({ project_path: "/work/project-a" })
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
可直接看到：
|
|
337
|
+
|
|
338
|
+
- 已索引文件数 / 符号数 / 关系数 / 行为数
|
|
339
|
+
- 最后索引时间
|
|
340
|
+
- 失败文件数量
|
|
341
|
+
- 最近失败文件和错误信息
|
|
342
|
+
- watcher 是否活跃
|
|
343
|
+
- 数据库大小与路径
|
|
344
|
+
|
|
345
|
+
当你发现“文件明明在，但工具查不到”时，先看这里，而不是只看总文件数。
|
|
346
|
+
|
|
347
|
+
## 框架支持
|
|
348
|
+
|
|
349
|
+
| 类型 | 解析方式 | 支持范围 | 说明 |
|
|
350
|
+
| ---- | -------- | -------- | ---- |
|
|
351
|
+
| Vue 2 | `vue-template-compiler` + `@babel/parser` | Options API | 适合 SFC 组件骨架、行为标签、调用关系 |
|
|
352
|
+
| Vue 3 | `@vue/compiler-sfc` + `@babel/parser` | `<script setup>` + Composition API | 适合现代 Vue 单文件组件分析 |
|
|
353
|
+
| React | `@babel/parser` + JSX | 函数组件 + Hooks | 适合组件骨架、事件入口、行为标签、调用关系 |
|
|
354
|
+
| 纯 TS/JS 工具模块 | `@babel/parser` | class / method / top-level function / constant | 基础结构化符号提取，适合 parser / indexer / cache / CLI / MCP / util，不等于完整框架语义分析 |
|
|
355
|
+
|
|
356
|
+
## 行为检测
|
|
357
|
+
|
|
358
|
+
自动识别以下 API 调用并打上标签：
|
|
359
|
+
|
|
360
|
+
- `storage`：localStorage / sessionStorage
|
|
361
|
+
- `network`：axios / fetch
|
|
362
|
+
- `router`：$router / useRouter / navigate
|
|
363
|
+
- `vuex`：$store / useStore / dispatch / commit
|
|
364
|
+
- `dom`：document / $refs / $nextTick
|
|
365
|
+
- `event`：$emit / EventBus
|
|
366
|
+
- `timer`：setTimeout / setInterval
|
|
367
|
+
- `i18n`：$t / useI18n
|