@jokeran/frontend-code-skimmer 0.4.8 → 0.5.1

package/README.md

@@ -10,10 +10,13 @@ AI 代码助手的智能代码索引引擎，面向 **Vue 2 / Vue 3 / React /
 - `precision_mode="precise"` 支持 **JS / JSX / TS / TSX** 的跨文件 import/export 精确绑定
 - 对 **纯 TS/JS 工具类模块** 提供基础符号提取（class / method / function / constant）
 - `skimmer_index_health` 可显示**真实失败文件与错误信息**，便于排障
+- `skimmer_search_snippets` 已支持 **query intent 分类 + snippet-first 排序 + 业务文件优先**
 
 ## 解决什么问题？
 
 - **7000 行大文件**：`skimmer_get_component_outline` 将其压缩为 60 行骨架，节省 95% Token
+- **自然语言第一跳太吵**：`skimmer_search_snippets` 直接返回高相关代码片段，避免先猜函数名再二跳读文件
+- **API 查询先落到 util 包装层**：`skimmer_search_snippets` 会优先抬升 `views/pages/features` 等业务实现，压低 `config/utils/helpers` 这类通用封装
 - **函数名拼写错误**：搜 `changeCash` 能找到 `changeCashValue`，自动提示 "cash 可能是 cache 的拼写错误"
 - **不知道函数名**：`skimmer_find_by_behavior` 按行为搜索，搜 `storage` 直接列出所有操作 localStorage 的函数
 - **同名函数串台**：`skimmer_find_symbol` / `skimmer_find_by_behavior` / `skimmer_get_call_graph` 支持 `file_path` 过滤
@@ -31,6 +34,7 @@ AI 代码助手的智能代码索引引擎，面向 **Vue 2 / Vue 3 / React /
 | `skimmer_index_project`          | 初始化/更新代码索引（支持 `force: true` 全量重建） |
 | `skimmer_get_component_outline`  | ⭐ 获取文件骨架（极致 Token 节省，自动检测索引过期） |
 | `skimmer_find_symbol`            | 智能符号搜索（精确 → FTS5 → Levenshtein 三层，支持拼写错误） |
+| `skimmer_search_snippets`        | ⭐ 代码片段搜索（snippet-first，适合自然语言第一跳） |
 | `skimmer_get_code_slice`         | 精准代码切片（只取一个函数，自动检测行号偏移） |
 | `skimmer_trace_assignments`      | 变量赋值链路追踪（轻量降级工具，AST 优先）   |
 | `skimmer_trace_property_changes` | 对象属性修改追踪（轻量降级工具）             |
@@ -48,6 +52,9 @@ AI 代码助手的智能代码索引引擎，面向 **Vue 2 / Vue 3 / React /
 - **local shadowing 保护**：若 import 名在函数局部被参数或变量重新声明，会保留 heuristic，避免把本地变量误判成跨文件精确调用
 - **工具类模块覆盖增强**：新增 Tooling TS/JS Parser，能抽取 class、class method、top-level function、constant 等基础符号
 - **index health 更真实**：索引失败文件会持久化，`skimmer_index_health` 可查看最近失败文件和错误，而不是只看总量
+- **snippet 搜索引入 query intent**：区分 `symbol_like / behavior_like / api_like / natural_language`，工具输出会直接显示意图，便于调权和排障
+- **业务文件优先排序**：对 `views/pages/features/modules` 等业务文件加分，对 `config/utils/helpers/lib/shared` 等通用封装降权；在真实 Vue2 项目中，`localStorage setItem` 已可优先命中业务页实现而不是 `mUtils.js`
+- **评测集已固化**：仓库内有固定 snippet 回归测试，外部真实项目可通过 `eval/snippet-suites/*.json` + `npm run eval:snippet` 一键复跑
 
 ## 安装
 
@@ -75,6 +82,22 @@ npm install
 npm run build
 ```
 
+### 方式三：运行 snippet 评测集（开发调权用）
+
+```bash
+# 仓库内固定评测集
+npm test
+
+# 真实项目回归（以 apply-claim 为例）
+npm run eval:snippet -- --project /Users/anshunli1/jd/workSpace/jdGit/apply-claim --suite ./eval/snippet-suites/apply-claim.json
+```
+
+说明：
+
+- `npm test` 会跑固定 fixture 评测集，适合日常开发时快速防回归
+- `npm run eval:snippet` 用于真实项目相关性回归，适合调权、改 query 规则、评估业务文件优先是否生效
+- `eval/snippet-suites/*.json` 只属于研发保障设施，不参与运行时主链路
+
 ## 配置（Cursor / Claude Desktop）
 
 ### npx 安装（推荐）
@@ -87,7 +110,7 @@ npm run build
       "args": ["-y", "@jokeran/frontend-code-skimmer"],
       "autoApprove": [
         "skimmer_index_project", "skimmer_get_component_outline",
-        "skimmer_find_symbol", "skimmer_get_code_slice",
+        "skimmer_find_symbol", "skimmer_search_snippets", "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",
@@ -108,7 +131,7 @@ npm run build
       "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_find_symbol", "skimmer_search_snippets", "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",
@@ -187,6 +210,28 @@ npm run build
 → 行为标签显示: [storage:localStorage.setItem]
 ```
 
+### 3.5 ⭐ 自然语言第一跳代码片段搜索
+
+```
+调用 skimmer_search_snippets({ query: "save to cache" })
+→ 直接返回 changeCacheValue / persistDraft 等高相关代码片段
+→ 优先看 snippet，不必先猜函数名再调用 get_code_slice
+→ 输出会显示查询意图，如 `behavior_like`
+
+调用 skimmer_search_snippets({ query: "localStorage setItem" })
+→ 直接返回 localStorage.setItem 所在实现片段
+→ 显式 API 查询会识别为 `api_like`，优先按行为实现排序
+→ 若同时存在业务页实现和 util 封装，默认优先业务文件
+```
+
+当前排序信号（面向 Agent 第一跳）：
+
+- query intent：`symbol_like / behavior_like / api_like / natural_language`
+- definition boost：可执行定义（function / method / hook / lifecycle）优先于常量/元数据
+- file coherence：同一文件内多处相关命中会整体抬升
+- file role：`views/pages/features/modules` 业务文件优先，`config/utils/helpers/lib/shared` 通用封装降权
+- noise penalty：测试、mock、demo、声明文件降权
+
 ### 4. 查找操作本地存储的函数
 
 ```