@wenext/code-context-rag v1.0.0

为 JS/TS/Vue 前端项目提供符号级代码智能索引，让 AI 编码助手（Claude Code、Cursor 等）在探索大型代码库时更高效、更节省 token。

背景与目标

大型前端 monorepo（如 wenext-web-mono，9000+ 文件）存在两个核心痛点：

AI 读文件消耗大量 token — 整文件读取，大量无关代码被塞入上下文
AI 搜索效率低 — 用 Glob/Grep 查符号定义，既慢又不精准

本工具的目标：让 AI 先搜索符号索引，只读必要的代码片段，将探索一个功能的 token 消耗从"整文件"降到"相关函数片段"。

核心功能

符号级索引

解析 .ts .tsx .js .jsx .vue 源文件，提取函数、类、组件、Hook、接口、类型等符号
存储每个符号的名称、类型、所在文件、行号、源码片段（≤600字符）、依赖关系
追踪 6 种有向边：imports（导入）、calls（调用）、extends（继承）、implements（实现）、uses_component（组件引用）、uses_hook（Hook 调用）
增量更新：基于文件 SHA-256 哈希，只重新解析变更文件；watch 模式下边图同步维护

CLI 搜索（Agent 模式）

bash

npx web-context-rag search "jackpot" --project . --json --limit 10
npx web-context-rag search "auth"    --project . --json --context        # 含代码片段和依赖图
npx web-context-rag search ""        --project . --json --file packages/h5-lucky-gift --type component

输出结构化 JSON，专为 AI agent 消费设计：

json

{
  "total": 64,
  "shown": 10,
  "results": [{
    "name": "JackpotPrize",
    "type": "component",
    "file": "packages/.../JackpotPrize.vue",
    "line": 1,
    "exported": true,
    "snippet": "...",
    "deps": ["[uses_hook] useRequest (src/hooks/useRequest.ts:1)", "[calls] formatDate (src/utils.ts:8)"],
    "usedBy": ["[uses_component] JackpotPanel (packages/.../JackpotPanel.vue:12)"]
  }]
}

PostToolUse Hook 自动观察

通过 Claude Code 的 PostToolUse Hook，在 AI 每次 Read/Grep/Glob 后自动记录探索记录到数据库。

json

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Read|Grep|Glob",
      "hooks": [{ "type": "command", "command": "npx web-context-rag hook --project /path/to/project" }]
    }]
  }
}

影响分析（impact）

bash

npx web-context-rag impact useLottery --project .
npx web-context-rag impact Button --project . --depth 2 --json

从指定符号出发，沿 usedBy 入边 BFS 遍历，输出所有直接/间接依赖它的上游符号及调用链。适用于评估改动影响范围：

Impact: "useLottery"  src/hooks/useLottery.ts
Symbols that depend on it (depth ≤ 3):

  [uses_hook] LuckyGift   packages/h5-lucky-gift/LuckyGift.vue:5
    [uses_component] LuckyGiftPage   packages/h5-lucky-gift/pages/index.vue:3

Total: 2 dependents

跨会话记忆（recall）

bash

npx web-context-rag recall --project .

输出：最近修改热点文件、频繁变动的符号（churn）、AI 最近探索过的文件，帮助新会话快速建立上下文。

手动注记（note）

bash

npx web-context-rag note "h5-lucky-gift 的抽奖流程入口在 useLottery hook" --project .

将人工洞察持久化，跨会话可检索。

技术实现

层	技术
语言	TypeScript 5 / Node.js 18+ / ESM
解析器	`tree-sitter` + JS/TS/Vue grammar（native 模块，仅 index 时需要）
数据库	`sql.js`（纯 WASM SQLite，无 native 模块，任意 Node 版本可用）
文件监听	`chokidar`（1500ms 防抖增量索引）
MCP 服务	`@modelcontextprotocol/sdk`（stdio transport）
CLI	`commander`

关键设计决策：

SQLite 用 sql.js（WASM）而非 better-sqlite3（native），解决跨 Node 版本兼容性问题
索引数据存于 ~/.web-context-rag/<project-hash>.db，与项目目录无关
结构化 diff 追踪每次重新索引时的符号变更（added/modified/removed），stale 自动标记

与 Claude Code 集成

1. CLAUDE.md 行为协议

在项目的 CLAUDE.md 中写入搜索优先策略，Claude 会自主在探索代码时先调用 CLI 而不是直接 Read 文件，支持 5 种意图类型：

意图	策略
具名符号	`search "ComponentName" --context --depth 2`
概念/功能	假设 3-5 个候选名称，并行搜索，取最相关结果
依赖关系	`search "fn" --context`，看 `usedBy` / `deps` 数组（含边类型前缀 `[calls]`/`[uses_hook]` 等）
模块浏览	`search "" --file packages/xxx --limit 30`
模式搜索	`search "keyword" --type function/class/hook`
改动影响	`impact "SymbolName" --depth 3`，评估修改该符号的上游影响范围

2. MCP Server 模式

json

{
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["web-context-rag", "serve", "--project", "."]
    }
  }
}

提供 6 个 MCP tool：index_project、get_symbol_context、search_symbols、get_file_map、get_session_memories、check_stale_memories。

项目数据（wenext-web-mono）

指标	数据
项目规模	9,494 文件
索引耗时	~12 秒（首次）
符号数量	14,285 个
数据库大小	~17 MB
增量更新（无变更）	<2 秒
搜索响应	<500ms

效果： AI 探索一个功能（如 jackpot 相关组件）从"读 5-10 个完整文件（~50K tokens）"降到"搜索 + 读 2-3 个函数片段（~3K tokens）"。

CLI 命令速查

bash

npx web-context-rag index   --project .                    # 索引/更新项目
npx web-context-rag search  "query" --project . --json \
  [--context] [--depth 2] [--type component] [--file src/store] [--limit 20]
npx web-context-rag impact  "SymbolName" --project . \
  [--depth 3] [--json]                                     # 影响分析：谁依赖了这个符号
npx web-context-rag recall  --project .                    # 历史探索 + 变更热点
npx web-context-rag note    "备注" --project .             # 写入人工注记
npx web-context-rag hook    --project .                    # PostToolUse Hook 入口
npx web-context-rag serve   --project .                    # 启动 MCP server

@wenext/code-context-rag v1.0.0 ​

背景与目标 ​

核心功能 ​

符号级索引 ​

CLI 搜索（Agent 模式） ​

PostToolUse Hook 自动观察 ​

影响分析（impact） ​

跨会话记忆（recall） ​

手动注记（note） ​

技术实现 ​

与 Claude Code 集成 ​

1. CLAUDE.md 行为协议 ​

2. MCP Server 模式 ​

项目数据（wenext-web-mono） ​

CLI 命令速查 ​

@wenext/code-context-rag v1.0.0

背景与目标

核心功能

符号级索引

CLI 搜索（Agent 模式）

PostToolUse Hook 自动观察

影响分析（impact）

跨会话记忆（recall）

手动注记（note）

技术实现

与 Claude Code 集成

1. CLAUDE.md 行为协议

2. MCP Server 模式

项目数据（wenext-web-mono）

CLI 命令速查