RepoLens

    ██████╗ ███████╗██████╗  ██████╗ ██╗     ███████╗███╗   ██╗███████╗
    ██╔══██╗██╔════╝██╔══██╗██╔═══██╗██║     ██╔════╝████╗  ██║██╔════╝
    ██████╔╝█████╗  ██████╔╝██║   ██║██║     █████╗  ██╔██╗ ██║███████╗
    ██╔══██╗██╔══╝  ██╔═══╝ ██║   ██║██║     ██╔══╝  ██║╚██╗██║╚════██║
    ██║  ██║███████╗██║     ╚██████╔╝███████╗███████╗██║ ╚████║███████║
    ╚═╝  ╚═╝╚══════╝╚═╝      ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═══╝╚══════╝
                        Repository Intelligence CLI

链接： 图库 · npm · MCP Registry · MCP Rush · VS Code 扩展 · GitHub Action

你的架构文档已经过时。 RepoLens 来解决这个问题。

RepoLens 会扫描你的代码仓库，生成持续更新的架构文档，并在每次推送时自动发布到 Notion、Confluence、GitHub Wiki、Obsidian 或 Markdown。工程师可以获取技术文档，利益相关者可以查看易读的系统概览。无需任何人动笔。

自 v1.0 起稳定 — API 保证 · 已强化安全性 · 版本来自 package.json

---

🎬 演示

立即试用 — 无需安装。运行 npx @chappibunny/repolens demo，即可预览你指定的代码仓库。它能检测常见语言（Python、Go、Rust、Java、JavaScript/TypeScript 等）。如果扫描结果中没有匹配的源文件，demo 会以状态码 2 退出，且不会生成空文档。代码健康度评分支持 JavaScript/TypeScript、Python 和 Go。

查看真实代码仓库案例 — RepoLens 为 Express、FastAPI、Django、Gin、mdBook 及其他公开项目生成的架构页面。确定性模式，无需 API 密钥。

🎬 观看演示视频 — 查看 RepoLens 如何在 60 秒内生成文档

Notion	Confluence

🔍 支持的语言（自动检测 16 种）

JavaScript TypeScript Python Go Rust Java C C++ C# Ruby PHP Swift Kotlin Scala Shell SQL

此外还能检测框架：Django · FastAPI · Flask · Gin · Echo · Fiber · Actix · Rocket — 以及所有主流 JS 框架（React、Next.js、Vue、Angular、Express、NestJS、Svelte 等）

---

🚀 快速开始（60 秒）

步骤 1：安装（Node.js 18+）

npm install @chappibunny/repolens

步骤 2：初始化（创建配置和 GitHub Actions 工作流）

npx @chappibunny/repolens init

步骤 3：配置发布（可选；仅使用 Markdown 时可跳过）

对于 Notion：

# Edit .env and add:
NOTION_TOKEN=secret_xxx
NOTION_PARENT_PAGE_ID=xxx

对于 Confluence：

# Edit .env and add:
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
[email protected]
CONFLUENCE_API_TOKEN=your-token
CONFLUENCE_SPACE_KEY=DOCS

步骤 4：发布

npx @chappibunny/repolens publish

完成！ 编号笔记和 Markdown 发布器的文件位于 .repolens/ 中。只有在配置后，才会发布到 Notion、Confluence、GitHub Wiki 和 Obsidian。Obsidian 需要在 .repolens.yml 中设置 obsidian.vault，且不使用 API 密钥。

🔄 从 v0.3.0 或更早版本升级？ 运行 npx @chappibunny/repolens migrate，自动更新工作流文件。详情请参阅 MIGRATION.md。

---

📋 生成内容

面向三类受众的 17 种文档类型——无需手动编写。如果仓库没有路由或 GraphQL 架构，则会跳过路由图和 GraphQL 架构：

受众	文档
利益相关者	执行摘要
混合受众	系统概览 · 业务领域 · 路由图 · 数据流 · 变更影响 · 系统地图 · 架构偏移 · 代码健康度
工程师	架构概览 · 模块目录 · API 概览 · 开发者入门指南 · GraphQL 架构 · TypeScript 类型图 · 依赖关系图 · 安全热点

**两种模式：**确定性模式（免费、快速、始终可用）或 AI 增强模式（可选——GitHub Models、OpenAI、Anthropic、Google、Azure、Ollama）。

---

✨ 为什么选择 RepoLens

🤖 自主运行	每次推送时通过 GitHub Actions 运行——文档始终保持最新
👥 面向多类受众	一次扫描即可生成技术文档和便于利益相关者阅读的概览
📤 支持多个发布平台	可同时或单独发布到 Notion、Confluence、GitHub Wiki、Obsidian 和 Markdown
🗺️ 呈现你未曾询问的内容	大模型只会回答给定的问题，而新人并不知道该问什么。RepoLens 会在每个 PR 上发布完整地图（每个模块、循环和枢纽），每次方式一致，无需为每个问题消耗令牌
🧠 AI 辅助	可选 AI，采用零幻觉策略（仅使用结构化上下文）
🔍 智能检测	自动检测框架、领域、数据流、依赖关系和偏移
🔌 可扩展	提供插件系统，支持自定义渲染器、发布器和钩子
🛡️ 安全	支持密钥检测、注入防护、速率限制和供应链加固
⚡ 快速	可处理多达 50k 个文件的仓库，并提供性能防护措施

---

📦 安装

npm install @chappibunny/repolens

也可立即试用，无需安装：npx @chappibunny/repolens demo

其他安装方式请参阅 INSTALLATION.md。

---

🎨 VS Code 扩展

在 VS Code 中直接查看架构——浏览模块、可视化依赖关系并探索代码库结构，无需离开编辑器。

从 Marketplace 安装：

ext install repolensdox.repolensdox

→ 前往 Visual Studio Marketplace 获取

功能：

• 🏗️ 架构浏览器——以树形视图查看系统结构
• 📊 依赖关系可视化器——交互式依赖关系图
• 📁 模块浏览器——按领域和功能浏览模块
• 🔍 命令面板——快速访问架构洞察
• 📈 系统指标——实时架构健康指标

该扩展会读取你的 .repolens.yml 配置，并提供交互式界面，供你浏览 RepoLens 生成的文档。

---

🎓 入门指南

逐步指导你设置发布器、AI 功能、Notion、Confluence、GitHub Wiki、Obsidian、Discord 和 CI/CD 自动化。

→ 查看完整入门指南

---

🎮 命令

命令	说明
npx @chappibunny/repolens	显示帮助。直接运行不会发布
npx @chappibunny/repolens init	交互式向导 — 配置发布器、AI 和凭据
npx @chappibunny/repolens init --quick	仅设置 Markdown。Glob 模式会根据检测到的语言调整
npx @chappibunny/repolens init --help	该命令的标志。以下每个命令都采用相同模式
npx @chappibunny/repolens publish	扫描、生成并发布文档
npx @chappibunny/repolens publish --strict	配置的发布器缺少凭据时，以状态码 2 退出
npx @chappibunny/repolens demo	本地预览 — 无需 API 密钥。匹配到 0 个文件时以状态码 2 退出
npx @chappibunny/repolens doctor	验证设置，包括扫描 glob 模式是否匹配文件
npx @chappibunny/repolens watch	文件更改时自动重新生成文档。缺少 module_roots 或 scan.include 未匹配到文件时，以状态码 2 退出
npx @chappibunny/repolens migrate	从 v0.3.0 工作流升级（详情）
npx @chappibunny/repolens uninstall	移除所有 RepoLens 文件（配置、文档、工作流）
npx @chappibunny/repolens uninstall --force	无需确认提示即可移除
npx @chappibunny/repolens feedback	向团队发送反馈
npx @chappibunny/repolens mcp	启动 stdio MCP 服务（repolens-mcp 是同一服务）
npx @chappibunny/repolens badge	输出 shields.io 代码健康度 JSON、SVG 或 Markdown。没有任何评分时，以状态码 2 退出
npx @chappibunny/repolens comment --base <ref> --head <ref>	架构差异（文件、模块、依赖项、健康度变化、新热点）
npx @chappibunny/repolens app	自托管 GitHub App webhook。--manifest 用于输出清单

注意： 如果你使用 npm install -g @chappibunny/repolens 进行了全局安装，就可以使用较短的 repolens <command> 形式。当 PATH 上的命令是全局安装版本时，init 的后续步骤文本也会使用这种较短形式。 警告： 不要直接运行 npx repolens — npm 上有一个无关的占位包 [email protected]。请始终使用带作用域的名称 @chappibunny/repolens。

退出码

代码	含义
0	成功，包括取消向导或仅显示帮助且未执行其他操作
1	运行时错误或未知命令
2	标志无效、缺少配置、找不到目标目录、doctor 检查失败（包括匹配到 0 个文件）、demo 或 publish 扫描到 0 个文件、watch 没有可监视的内容（缺少 module_roots，或 scan.include 未匹配到文件）、badge 评分的源文件为 0 个、comment 缺少 base 或 head ref、publish --strict 缺少发布器凭据、app 缺少其 id、webhook 密钥或私钥，或 feedback 没有终端

--target 必须指向已存在的目录。路径不存在时，会在任何扫描开始前以状态码 2 退出，并显示 Target directory not found: <path>。repolens <command> --help 会显示该命令的标志。stdout 不是终端或设置了 CI 时，不会显示 ASCII 横幅。

---

MCP 服务

Cursor、Cline、Claude Desktop、Claude Code 和 VS Code Copilot 可以通过 stdio 调用 RepoLens。除 generate_docs 会在工作区内写入 Markdown 外，该服务均为只读。确定性模式不会使用网络。路径不能超出工作区根目录。

Cursor、Claude Desktop 和 VS Code 的可复制粘贴配置见 docs/MCP.md。

{
  "mcpServers": {
    "repolens": {
      "command": "npx",
      "args": ["-y", "@chappibunny/repolens", "mcp"]
    }
  }
}

与 Cline 搭配使用

打开 Cline → MCP Servers → Installed → Configure MCP Servers，将以下内容粘贴到 cline_mcp_settings.json 并保存：

{"mcpServers":{"repolens":{"command":"npx","args":["-y","@chappibunny/repolens","mcp"]}}}

Cline 无需安装步骤即可启动该服务（需要 Node 18+）。它会读取服务启动时所在的目录。若要指定特定仓库，请添加 "env": {"REPOLENS_WORKSPACE": "/absolute/path/to/repo"}。界面中会显示六个工具：get_system_overview、list_modules、get_api_surface、get_dependency_graph、get_architecture_diff、generate_docs。分步 Agent 指引见 llms-install.md。

如果 npx 报告 Unknown command: mcp，则是带有 min-release-age 的 .npmrc（或过旧的 npx 缓存）解析到了早于 1.14.0 的版本。请使用 npx -y @chappibunny/repolens@latest mcp，或清除 ~/.npm/_npx。

GitHub Action

action.yml 是一个名为 RepoLens Architecture Docs 的组合操作。publish、demo 和 doctor 会运行已发布的 npm 包（npx --force --yes @chappibunny/[email protected]）。comment 和 badge 会从操作检出目录运行。输入项包括 command（publish、demo、doctor、comment 或 badge）、config、node-version、pr-comment、version、badge-out、badge-url 和 badge-link。该操作会传入 --force，这样在会强制执行 devEngines 的 npm 版本（较新版本的 npm）上，仓库中的 devEngines 固定版本就不会阻止 npx 运行。Node 20 自带的 npm 不会强制执行该字段。在 shell 中使用相同的标志：npx --force --yes @chappibunny/repolens demo。--ignore-engines 不会跳过 devEngines。

发布文档（npm 包的标签为 v1.16.1）：

name: Architecture docs
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
  pull-requests: write
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - uses: CHAPIBUNNY/[email protected]
        with:
          command: publish
          config: .repolens.yml
          node-version: "20"
          pr-comment: ${{ github.event_name == 'pull_request' && 'true' || 'false' }}

在 v1.15.2 上，pr-comment: true 会从操作检出目录运行架构差异，并关闭已发布包中较旧的简短摘要。差异会列出模块、文件、依赖项、代码健康度变化以及新增热点。它会编辑一条固定评论（``），而不是每次推送都新增评论。页脚为“Generated by RepoLens”，并链接到此仓库和展示库。标签 v1.15.1 不包含 command: comment。在生产环境中，请固定到 v1.16.1 或某个提交 SHA。

name: RepoLens architecture comment
on:
  pull_request:
permissions:
  contents: read
  pull-requests: write
jobs:
  architecture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          fetch-depth: 0
      - uses: CHAPIBUNNY/[email protected]
        with:
          command: comment

设置 contents: read 只是为了让 checkout 能读取仓库。评论本身使用带有 pull-requests: write 权限的 GITHUB_TOKEN。无需个人访问令牌。使用该令牌，来自 fork 的拉取请求无法写入评论。RepoLens 会跳过评论，并将相同的 Markdown 写入作业摘要。遇到 403 时也会以相同方式处理。必须设置 fetch-depth: 0，以便将基础提交和头部提交都保存在本地。

在 publish、demo 或 doctor 上设置 pr-comment: true（当操作引用包含此更改时），会在运行包之后执行相同的评论操作，并关闭包中较旧的评论功能，因此拉取请求仍只会收到一条评论。

只有在发布版本时勾选 Publish this Action to the GitHub Marketplace，该操作才会列入 GitHub Marketplace。相关步骤见 docs/RELEASE.md。必须先存在标签 v1.16.1，uses: CHAPIBUNNY/[email protected] 才能解析；必须先将 @chappibunny/[email protected] 发布到 npm，publish 才能安装它。command: comment 和 command: badge 不会安装该包。

将徽章添加到仓库

除非 .repolens.yml 设置了 branding: false（或 branding.badge: false），生成的 Markdown 都会包含以下行。将相同的徽章添加到仓库 README：

[![Docs by RepoLens](https://img.shields.io/badge/Docs%20by-RepoLens-0B5FFF)](https://github.com/CHAPIBUNNY/repolens) · [Examples](https://chapibunny.github.io/repolens/)

徽章后面，生成的文档还会链接到展示库。

代码健康度徽章

repolens badge 会为 JavaScript、TypeScript、Python 和 Go 评分，然后输出 shields.io endpoint JSON 文档。徽章消息为代码健康度平均分。如果没有源文件获得评分，它会以状态码 2 退出；对于空目录树，它不会输出 100。

npx @chappibunny/repolens badge
npx @chappibunny/repolens badge --format svg --out repolens-badge.svg
npx @chappibunny/repolens badge --format markdown --url https://USER.github.io/REPO/repolens-badge.json --link https://USER.github.io/REPO/

将 JSON 放在 shields.io 可以获取的位置。此操作无需发布 npm 包，即可写入两个文件：

name: RepoLens badge
on:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  badge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - uses: CHAPIBUNNY/[email protected]
        with:
          command: badge
          badge-url: https://USER.github.io/REPO/repolens-badge.json
          badge-link: https://USER.github.io/REPO/
      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: repolens-badge
          path: |
            repolens-badge.json
            repolens-badge.svg

如果要使用实时 shields.io 徽章，请将 repolens-badge.json 提交到 gh-pages（或任何公开的 HTTPS 路径）。badge-url 即该公开 URL。作业摘要会打印：

[![code health](https://img.shields.io/endpoint?url=https%3A%2F%2FUSER.github.io%2FREPO%2Frepolens-badge.json&style=flat-square)](https://USER.github.io/REPO/)

展示库中的仓库已发布此内容。每个仓库都有一个评分页面，其中包含代码片段、badge.json 和方形 SVG。徽章会链接回该评分页面。旁边还会为每个仓库编入一个名为“ architecture explained”的说明页面索引（sitemap.xml、robots.txt、Open Graph、canonical URL、JSON-LD SoftwareSourceCode）。llms.txt 和 llms-full.txt 位于网站根目录以及此仓库中。

---

📸 示例输出

系统图

发布的系统图是根据导入边绘制的 Unicode 图表。RepoLens 不会生成 Mermaid。

发布器集合包括 Notion、Confluence、GitHub Wiki、Obsidian 和 Markdown（src/publishers，共 7 个文件）。1.14.0 添加了 MCP 服务、Marketplace 操作和文档徽章。1.14.1 将注册表名称设为 io.github.CHAPIBUNNY/repolens。1.14.2 在徽章行、glama.json 和 CITATION.cff 中添加了画廊链接。1.14.3 添加了 Cline 配置文档和 llms-install.md。1.15.0 在 init --quick 中检测仓库语言、拒绝空扫描，并添加各命令的帮助信息。1.15.1 在这些 glob 匹配不到任何内容时让 watch 以状态码 2 退出，并为 Python 和 Go 以及 JavaScript 和 TypeScript 评分代码健康度。1.15.2 在依赖图中读取 Python 和 Go 导入，跳过注释和仅类型导入，添加 repolens badge 和 repolens comment，并添加画廊说明页面以及 llms.txt。1.15.3 跳过 Python TYPE_CHECKING 导入，从外部软件包中排除 Node.js 内置模块，按软件包对 Go 枢纽分组，并忽略测试文件作为架构模式的依据。1.15.4 根据 package.json 为项目命名，根据版本、历史记录、测试、CI 和文档评估成熟度，将循环依赖报告为发现项，剔除自导入和噪声数据流，并停止根据文件名将 index 和 core 文件分类。1.15.5 将扁平的 src/ 视为一个模块，根据 package.json 区分库和 CLI，将运行时软件包与开发软件包分开，不将测试、示例和构建脚本纳入枢纽和安全严重性评估，并跳过空的 Route Map 和 GraphQL 页面。1.16.0 添加了 repolens app（可自托管的 GitHub App webhook），将扁平软件包按其目录命名，在缺少 main 时将框架描述视为库，并将测试和示例路由排除在产品 API 之外。1.16.1 在文件计数、孤立项列表和类型图中跳过快照、样例、固件、示例和生成的目录树，并将调用密集型的双文件夹循环标记为相互递归，而非高优先级重构项。布局和计数详见 ARCHITECTURE.md。

系统概览（技术档案）

根据你的 package.json 生成：

## Technical Profile

**Tech Stack**: Next.js, React  
**Languages**: TypeScript  
**Build Tools**: Vite, Turbo  
**Testing**: Vitest, Playwright  
**Architecture**: Medium-sized modular structure with 42 modules  
**API Coverage**: 18 API endpoints detected  
**UI Pages**: 25 application pages detected  

PR 中的架构差异

打开拉取请求时，RepoLens 会发布：

## 📐 Architecture Diff

**Modules Changed**: 3
**New Endpoints**: 2
**Routes Modified**: 1

### New API Endpoints
- POST /api/users/:id/verify
- GET /api/users/:id/settings

### Modified Routes
- /dashboard → components/Dashboard.tsx (updated)

---

🔒 隐私与安全

• 遥测为主动选择加入，默认禁用 — 不会有代码、机密或个人数据离开你的计算机。参见 TELEMETRY.md。
• 纵深防御安全机制 — 输入验证、机密检测（15 种以上模式）、速率限制、注入防护、供应链加固。参见 SECURITY.md。
• 报告漏洞：发送邮件至 [email protected]（请勿在公开问题中报告）。我们会在 48 小时内回复。

---

📚 文档

指南	说明
入门指南	分步设置：发布器、AI、Notion、Confluence、GitHub Wiki、Obsidian、Discord
配置	完整的 .repolens.yml 架构和示例
环境变量	按发布器和功能分类的所有环境变量
架构	流水线图、项目结构
开发	设置、测试和发布流程
安全	威胁模型、机密检测、验证层
遥测	主动选择加入、以隐私为先的使用情况分析
故障排除	常见问题及解决方法
迁移	从 v0.3.0 或更早版本升级
稳定性	API 契约和语义化版本保证
MCP 服务	面向 Cursor、Claude 和 VS Code 的 stdio 服务
GitHub App	自托管 webhook：清单、环境变量、检查运行

---

🤝 参与贡献

参与方式：

• 试用：安装并在项目中使用
• 报告问题：反馈错误、边缘情况或使用体验上的阻碍
• 提出功能需求：告诉我们缺少什么
• 构建插件：通过自定义渲染器和发布器扩展 RepoLens
• 分享反馈：npx @chappibunny/repolens feedback

请参阅 CONTRIBUTING.md 和 AI 政策。欢迎提交 AI 辅助的 PR，但请注明使用情况，并进行审查和测试。

---

🗺️ 路线图

v1.0+ 的功能已完成——CLI、配置架构和插件接口均已冻结。

已完成：

• VS Code 扩展（可在 Marketplace 获取）
• Obsidian 知识库发布器（支持本地笔记、双向链接和 frontmatter）
• MCP 服务（repolens mcp），适用于 Cursor、Claude 和 VS Code
• GitHub Action RepoLens Architecture Docs（action.yml）
• 生成的 Markdown 中包含 Docs by RepoLens 徽章
• GitHub App webhook（repolens app），用于创建检查运行和架构评论

接下来：

• 支持 Java 和 C#
• 有依据的 AI 解释与问答（repolens ask、PR 评论、MCP、VS Code 悬停提示），基于始终发布的架构图，并非用来取代它
• Slack 通知
• 支持自定义 webhook
• 跨仓库架构分析
• 安全边界验证
• 交互式 HTML 文档输出
• 生成架构决策记录（ADR）

详细规划请参阅 ROADMAP.md。

---

📄 许可证

MIT

---

💬 支持与联系

• 故障排查：TROUBLESHOOTING.md — 安装、配置、发布、AI 和 CI/CD 相关问题
• 诊断：运行 npx @chappibunny/repolens doctor 验证设置
• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions
• 电子邮件：联系仓库维护者

---