RepoLens 🔍
帮 AI 编码助手(Claude Code / Codex CLI / DeepSeek Harness 等)省 token、更准确地读懂仓库 —— 用确定性分析替代盲目 grep。
为什么需要 RepoLens
AI 编码助手理解一个新仓库,通常要靠反复 grep、逐个读文件去"摸索"结构;每一次摸索都是一轮
工具调用,消耗大量 context token,而且结论容易随模型猜测漂移。
RepoLens 把这部分工作前移:用确定性的程序分析(目录树扫描 + manifest 解析 + 语言识别 +
AST 调用图)预先算出仓库画像(profile),缓存在仓库内的 .repo-lens/ 目录里。agent 只需
一次调用,就能拿到结构化结论。远程仓库也无需手动 clone:传入仓库 URL 或 owner/repo
短写,RepoLens 会浅克隆到用户目录的缓存中再分析。
- ⚡ 省 token:预计算的仓库画像一次调用给到结论,替代多轮盲目探索
- 🌐 远程直连:
repo-lens analyze owner/repo即可分析远程仓库,克隆缓存到~/.repo-lens/repos并复用 - 🗄️ 跨会话缓存:profile 落盘在
<root>/.repo-lens/profile.json,同一仓库反复分析不用重算 - 🔄 缓存新鲜度:profile 记录分析时的 git HEAD,
map发现代码已变化会提示并自动重算 - 🎯 确定性 > 臆测:结论来自文件系统、manifest 与 AST 的真实解析,而非 LLM 猜测
三层架构
RepoLens 的「三层壳 + 一个内核」已全部落地:
| 层 | 职责 | 状态 |
|---|---|---|
| Skill 壳 | 每个 AI harness 一个薄 SKILL.md,教 agent 何时/如何调用内核 | ✅ 已实现 |
| MCP 壳 | 跨平台工具接口(repo_lens_analyze / repo_lens_map / repo_lens_profile / repo_lens_chain) | ✅ 已实现 |
| 内核 CLI | 扫描 → 解析 → 分析 → 缓存 → 格式化,含 AST 调用链(analyze / map / chain,支持本地目录与远程仓库) | ✅ 已实现 |
整体设计(数据流、profile schema、扩展方式)详见 docs/ARCHITECTURE.md。
安装
环境要求
- Node.js >= 22.18
- pnpm
从源码构建
git clone https://github.com/wwwsure/repo-lens.git
cd repo-lens
pnpm install
pnpm build
构建产物:
packages/cli/dist/index.js—— CLI(bin 名repo-lens)packages/mcp-server/dist/index.js—— MCP server(bin 名repo-lens-mcp)
建议为 CLI 建一个别名,下文用 repo-lens 指代:
alias repo-lens='node packages/cli/dist/index.js'
npm
三个包已发布到 npm(scope @1mper-labs,当前版本 0.2.0):
| 包 | 命令 / 用法 |
|---|---|
@1mper-labs/cli |
npm i -g @1mper-labs/cli,bin 名 repo-lens |
@1mper-labs/mcp-server |
npm i -g @1mper-labs/mcp-server,bin 名 repo-lens-mcp |
@1mper-labs/core |
可编程 API,import { analyzeRepo } from '@1mper-labs/core' |
npm install -g @1mper-labs/cli
repo-lens --version
快速开始
# 1. 分析仓库:生成 profile 并缓存到 <root>/.repo-lens/profile.json
repo-lens analyze .
# 2. 目录树地图(优先读缓存,默认深度 4)
repo-lens map .
# 3. 调用链追踪(AST 级,默认深度 3)
repo-lens chain packages/cli/src/args.ts:parseArgs --dir .
# 4. 直接分析远程仓库:自动浅克隆到 ~/.repo-lens/repos,后续复用
repo-lens analyze owner/repo
# 5. 重新拉取已缓存的远程仓库(git fetch + reset)后再分析
repo-lens analyze https://github.com/owner/repo --refresh
命令参考
repo-lens analyze [dir|repo=.] [--json] [--no-cache] [--no-gitignore] [--no-workspaces] [--refresh]
分析 dir|repo(默认当前目录)生成 RepoProfile 并缓存;默认输出人类可读摘要。dir|repo
既可以是本地目录,也可以是远程仓库来源(见仓库来源)。
| 选项 | 说明 |
|---|---|
--json |
以 JSON 输出完整 profile(默认输出摘要) |
--no-cache |
不写入 .repo-lens/profile.json |
--no-gitignore |
不遵循 .gitignore,扫描全部目录 |
--no-workspaces |
不解析 monorepo 子目录中的子包清单(默认解析,最多 100 个目录) |
--refresh |
远程仓库:更新已有克隆(git fetch --depth=1 origin HEAD + reset --hard)后再分析 |
repo-lens map [dir|repo=.] [--max-depth N=4] [--no-cache] [--refresh]
打印目录树地图;优先读取已有缓存,缓存不存在时现场分析(不写缓存)。缓存存在但 git HEAD
已变化(stale)时会自动重算,并在 stderr 打印
repo-lens: cached profile is stale (git HEAD changed); recomputing;非 git 仓库无法判断
新鲜度(unknown),直接沿用缓存。
| 选项 | 说明 |
|---|---|
--max-depth N |
目录树最大深度,默认 4 |
--no-cache |
不读取缓存,现场重新分析 |
--refresh |
远程仓库:先重新拉取克隆缓存,再打印目录树 |
repo-lens chain <file[:symbol]> [--dir dir|repo] [--max-depth N=3] [--json] [--refresh]
AST 级调用链分析:构建 dir 内的调用图,从 <file>(该文件全部顶层符号)或
<file:Symbol>(指定符号)出发,BFS 展开调用链。输出 file::name 缩进树,每个节点标注
发现者(via)与调用行号;超出深度会截断并提示。
| 选项 | 说明 |
|---|---|
--dir dir|repo |
要扫描的仓库根目录或来源,缺省为当前目录 |
--max-depth N |
调用链深度,缺省 3 |
--json |
输出 ChainResult JSON(entry / steps / truncated) |
--refresh |
远程仓库:先重新拉取克隆缓存,再构建调用图 |
repo-lens chain src/index.ts --dir . # 整个文件的顶层符号
repo-lens chain src/args.ts:parseArgs --dir . --max-depth 5 # 指定符号、指定深度
repo-lens chain src/index.ts --dir owner/repo # 直接分析远程仓库
解析规则(确定性、刻意轻量,基于 TypeScript 编译器 API 的 AST,不做类型检查):
- 支持
.ts/.tsx/.mts/.js/.jsx/.mjs源文件 - 只有相对 import(
./x、../x)可解析为仓库内文件;bare specifier(路径别名、 node_modules 包)视为外部,不产生调用边 - 只追踪标识符调用
foo();成员调用x.foo()不在范围内
通用
--help/-h、--version/-v- 错误统一输出到 stderr(
repo-lens: <消息>),进程退出码 1;目录不存在、符号不存在等 会给出明确错误
仓库来源(URL / 短写)
所有接受 dir|repo 的命令都支持以下输入形式:
| 输入形式 | 示例 |
|---|---|
| 本地目录 | repo-lens analyze ./packages/core |
| HTTPS URL | repo-lens analyze https://github.com/wwwsure/repo-lens |
| SSH(scp 风格) | repo-lens analyze git@github.com:wwwsure/repo-lens.git |
owner/repo 短写 |
repo-lens map wwwsure/repo-lens |
远程仓库会浅克隆(git clone --depth=1 --single-branch)到
~/.repo-lens/repos/<host>/<owner>/<repo>,后续调用直接复用;--refresh 对已有克隆执行
git fetch --depth=1 origin HEAD + git reset --hard FETCH_HEAD。克隆缓存写在用户目录,
被分析的仓库本身不会被修改。远程功能需要本机有 git 与网络(或代理);git 缺失、地址
不可达时命令以 repo-lens: <消息> 失败并退出 1。
monorepo 子包
analyze 在扫描目录树后,会发现子目录中的清单文件(package.json /
pyproject.toml / Cargo.toml / go.mod,最多 100 个目录),解析后放入 profile 的
nestedManifests,摘要输出对应 Workspace packages (N): 段。--no-workspaces 关闭该
行为;根目录清单始终解析。嵌套清单的 path 是相对仓库根目录的路径。
缓存新鲜度
profile 会记录分析时的 git HEAD(gitHead)。repo-lens map 读取缓存后会用当前 HEAD
校验:
| cacheStatus | 含义 | map 行为 |
|---|---|---|
fresh |
gitHead 与当前 HEAD 相同 |
直接使用缓存 |
stale |
HEAD 已变化(缓存来自旧提交) | stderr 提示后现场重算(不写缓存) |
unknown |
profile 未记录 gitHead,或当前目录不是 git 仓库 |
沿用缓存(无法判断新鲜度) |
MCP 的 repo_lens_profile 会把 cacheStatus 与 profile 一起返回。
在 MCP 宿主中使用(DSH / Claude Code / Codex)
@1mper-labs/mcp-server 通过 stdio 暴露四个工具(v0.2.0):
| 工具 | 入参 | 行为 |
|---|---|---|
repo_lens_analyze |
dir?、json?、refresh? |
现场分析,不写缓存(无副作用);json=true 返回 RepoProfile JSON,否则返回文本摘要 |
repo_lens_map |
dir?、maxDepth?、refresh? |
优先读缓存,缺失或 stale 时现场分析;返回 ASCII 目录树(maxDepth 省略为不限深度),stale 重算时附提示 |
repo_lens_profile |
dir? |
返回 { cacheStatus, profile };无缓存时提示先运行 repo_lens_analyze |
repo_lens_chain |
file(必填)、dir?、maxDepth?(默认 3)、json? |
现场构建调用图并 BFS 展开调用链;file 为 path/file.ts 或 path/file.ts:Symbol,返回文本树或 ChainResult JSON |
dir 同样接受本地目录或仓库来源(URL / owner/repo),远程来源会自动浅克隆并复用。
错误(目录不存在等)统一返回 isError: true + 错误消息,server 不崩溃。
接入配置(mcpServers,发布后用 bin 名):
{
"mcpServers": {
"repo-lens": {
"command": "repo-lens-mcp"
}
}
}
从源码运行(发布前):
{
"mcpServers": {
"repo-lens": {
"command": "node",
"args": ["D:/vibe-coding/repo-lens/packages/mcp-server/dist/index.js"]
}
}
}
Claude Code 可写入用户级 ~/.claude.json 或项目级 .mcp.json;DSH / Codex 等宿主以各自
文档的 MCP 配置方式为准。冒烟验证:
pnpm --filter @1mper-labs/mcp-server smoke
Skill 壳安装
Skill 壳本体在仓库内 skills/repo-lens/SKILL.md。把它复制到对应
harness 的技能目录即可:
| Harness | 目标路径 |
|---|---|
| DeepSeek Harness | ~/.agents/skills/repo-lens/ |
| Claude Code | ~/.claude/skills/repo-lens/ |
| Codex | ~/.codex/skills/repo-lens/ |
cp -r skills/repo-lens ~/.claude/skills/
cp -r skills/repo-lens ~/.codex/skills/
安装后无需点名工具,直接说「分析这个仓库」「了解项目结构」「understand this repo」即可触发。
Monorepo 结构
pnpm workspace(packages/*)+ TypeScript project references(tsc -b 增量构建)。
| 路径 | 包 | 说明 |
|---|---|---|
packages/core |
@1mper-labs/core |
分析内核:目录树扫描、manifest 解析(含 monorepo 子包)、语言识别、profile 缓存与新鲜度、git/远程克隆、AST 调用图 |
packages/cli |
@1mper-labs/cli |
命令行壳:analyze / map / chain,bin 名 repo-lens |
packages/mcp-server |
@1mper-labs/mcp-server |
MCP 壳:stdio 传输,四工具,bin 名 repo-lens-mcp |
skills/repo-lens |
—— | Skill 壳本体(SKILL.md),复制到 harness 技能目录即用 |
测试:Node 内置 node:test,根脚本覆盖 packages/core/test/ 与 packages/cli/test/;
MCP server 另有冒烟脚本 packages/mcp-server/scripts/smoke.mjs。
从代码调用(core API)
@1mper-labs/core 导出可编程 API,CLI / MCP 壳只是它的薄壳:
| API | 签名 / 说明 |
|---|---|
analyzeRepo |
analyzeRepo(root: string, options?: AnalyzeOptions): Promise<RepoProfile> —— 一站式分析入口;AnalyzeOptions 继承 ScanOptions(gitignore、ignoreDirs),另有 nestedManifests?(默认 true)与 maxNestedManifests?(默认 100) |
analyzeCallGraph |
analyzeCallGraph(root: string, options?: ScanOptions): Promise<CallGraph> —— 构建仓库内调用图 |
resolveChain |
resolveChain(graph: CallGraph, entry: string, maxDepth = 3): ChainResult —— 从入口 BFS 展开调用链 |
scanTree |
scanTree(root: string, options?: ScanOptions): Promise<ScanResult> —— 目录树扫描 |
parseManifests |
解析仓库根目录的依赖清单(npm / Python / Rust / Go) |
findManifestDirs |
findManifestDirs(tree: DirNode): string[] —— 从目录树找出含清单的子目录(monorepo 子包) |
parseNestedManifests |
parseNestedManifests(root: string, dirs: string[], max = 100): Promise<ManifestInfo[]> —— 解析子包清单,path 为相对路径 |
MANIFEST_FILE_NAMES |
支持的清单文件名常量(package.json / pyproject.toml / Cargo.toml / go.mod) |
detectLanguage |
detectLanguage(filePath: string): string | null —— 单文件语言识别(扩展名 + 特殊文件名) |
saveProfile |
saveProfile(profile: RepoProfile): Promise<string> —— 写入 <root>/.repo-lens/profile.json,返回写入路径 |
loadProfile |
loadProfile(root: string): Promise<RepoProfile | null> —— 读取缓存,不存在返回 null |
cacheStatus |
cacheStatus(profile: RepoProfile, currentHead: string | null): 'fresh' | 'stale' | 'unknown' —— 缓存与当前 git HEAD 的新鲜度判断 |
gitHead |
gitHead(root: string): Promise<string | null> —— 读取 git HEAD;非 git 仓库或无 git 时返回 null |
runGit |
runGit(args: string[], cwd: string, timeoutMs = 120000): Promise<GitResult> —— 不抛错的 git 子进程封装 |
parseRepoSpec |
parseRepoSpec(input: string): RepoSpec | null;isRepoUrl(input: string): boolean —— 解析仓库 URL / owner/repo 短写 |
fetchRepo |
fetchRepo(spec: RepoSpec, options?: FetchRepoOptions): Promise<string> —— 浅克隆 / 复用 / 刷新到 ~/.repo-lens/repos,返回本地路径 |
resolveRepoInput |
resolveRepoInput(input: string, options?: FetchRepoOptions): Promise<string> —— 本地目录直接用,仓库来源则克隆后返回本地路径 |
formatTree |
formatTree(tree: DirEntry, opts?: { maxDepth?: number }): string |
formatSummary |
formatSummary(profile: RepoProfile): string |
formatChain |
formatChain(result: ChainResult, maxDepth: number): string —— 调用链文本树 |
主要类型:RepoProfile、DirEntry / DirNode / FileNode、LanguageStat、ManifestInfo、
CallGraph、CallEdge、ChainResult、ChainStep、FileAst、SymbolRef,以及
AnalyzeOptions、CacheStatus、GitResult、RepoSpec、FetchRepoOptions。
数据流、profile schema 与扩展方式详见 docs/ARCHITECTURE.md。
路线图
- 项目初始化(monorepo / TypeScript project references)
- 核心内核:目录树扫描、manifest 解析、语言识别、profile 缓存、文本格式化
- CLI 壳:
analyze/map/chain命令 - AST 调用链追踪(TypeScript 编译器 API)
- 远程仓库直接分析(URL /
owner/repo短写,浅克隆缓存 +--refresh) - monorepo 子包清单(
nestedManifests/--no-workspaces) - 缓存新鲜度校验(
gitHead/cacheStatus,stale 自动重算) - MCP server 壳(stdio,四工具,DSH / Claude Code / Codex 可接入)
- Claude Code / DSH skill 壳
- npm 发布(
@1mper-labs/core/@1mper-labs/cli/@1mper-labs/mcp-serverv0.2.0) - Marketplace 上架(skills.sh)
更新日志
v0.2.0
- 支持直接分析远程仓库:
analyze/map/chain --dir接受https://github.com/owner/repo、git@github.com:owner/repo.git、owner/repo短写;远程仓库浅克隆到~/.repo-lens/repos/<host>/<owner>/<repo>并复用,--refresh更新已有克隆。被分析仓库本身 不会被修改。 - monorepo 子包:profile 新增
nestedManifests,摘要新增Workspace packages段,analyze --no-workspaces可关闭。 - 缓存新鲜度:profile 新增
gitHead,cacheStatus区分fresh/stale/unknown;map发现 stale 缓存时自动重算并提示。 - MCP 新增
repo_lens_chain工具;repo_lens_analyze/repo_lens_map支持refresh与 仓库来源,repo_lens_profile返回{ cacheStatus, profile };server 版本 0.2.0。 - 根测试脚本改为覆盖
packages/*/test/*.test.ts(core + cli)。 - 三个包已发布到 npm(
@1mper-labs/*@0.2.0)。
v0.1.1
- 首发:分析内核、CLI(
analyze/map/chain)、MCP server(三工具)、Skill 壳, 发布到 npm(scope@1mper-labs)。
参与贡献
License
MIT
No comments yet. Be the first to write one.