DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

wwwsure /

wwwsure/repo-lens

Topic repository only

This plugin has no description yet.

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@a8e673b0

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-server v0.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)。

参与贡献

见 CONTRIBUTING.md。

License

MIT

—/ 5

No ratings yet

Manifest verification required

Commit a8e673b0794b

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout