## 目录 - [什么是 DevLens？](#what-is-devlens) - [快速入门](#getting-started) - [核心功能](#key-features) - [工作原理](#how-it-works) - [性能表现](#performance) - [应用场景](#use-cases) - [配置](#configuration) - [DevLens 云端版](#devlens-cloud) - [项目结构](#project-structure) - [贡献](#contributing) - [License](#license) ## 什么是 DevLens？ 像 Cursor 和 Claude Code 这样的 AI 编程工具让你以前所未有的速度交付软件——但这种速度也带来了新的问题。**代码库的增长速度超出了任何人能够理解它的极限。** 开发者在没有完全阅读代码的情况下就进行了合并。新员工在陌生的结构中苦苦挣扎。即便是作者自己也会忘记当初为什么要这样编写代码。 DevLens 解决了这个问题，它将任何 React、Next.js 或 Node.js 仓库转化为代码库的**动态、可查询图谱**——让你的团队始终清楚构建了什么、它们是如何连接的，以及为什么这样做。 将 DevLens 指向任何仓库，它会： 1. **遍历 AST** — 提取每个组件（包括 prop 类型）、hook、函数（包括类型化的参数和返回类型）、store、工具函数和 API 路由；内联捕获引用的 TypeScript 接口 2. **构建依赖图** — 映射所有关系：调用、导入、状态读取/写入、prop 传递、事件和路由处理 3. **为每个节点评分** — 使用多阶段算法（不涉及 AI）按架构重要性对节点进行排名 4. **通过 LLM 进行总结** — 为每个节点生成业务摘要和技术摘要 5. **渲染交互式图谱** — 可视化地探索、过滤、搜索和对比你的代码库 一切都在你的本地机器上运行。你的代码永远不会离开本地。 ## 快速入门 ### 前置条件 - [Bun](https://bun.sh) v1.0+ - Node.js 18+ - LLM 提供商的 API key（可选，仅在需要生成摘要时使用）（参见[配置](#configuration)） ### 安装说明 ``` # 1. Clone the repo git clone https://github.com/devlensio/devlensOSS.git cd devlensOSS # 2. 安装所有依赖（engine + frontend + shared） bun install # 3. 配置环境（可选 — 也可以在 UI 中设置） cp .env.example .env # 使用你的 LLM provider 设置编辑 .env # 4. 启动两个服务器 bun run dev ``` 引擎在 `http://localhost:3000` 启动，前端在 `http://localhost:3001` 启动。在启动之前，请确保这两个端口可用。 打开 `http://localhost:3001`，粘贴任何 React/Next.js/Node.js/Express 仓库的绝对路径（根目录下必须包含 `package.json`），然后点击 **Analyze**。 ### 结合 Ollama 快速开始（免费，本地） ``` # 从 https://ollama.ai 安装 Ollama ollama pull qwen2.5-coder:7b # 在你的 .env 中： LLM_PROVIDER=ollama LLM_MODEL=qwen2.5-coder:7b bun run dev ``` ## 核心功能 ### 图谱引擎 - **通过 ts-morph 进行全量 AST 分析** — 组件、hooks、函数、stores、工具函数、文件和 API 路由 - **10 种边类型** — `CALLS`, `IMPORTS`, `PROP_PASS`, `READS_FROM`, `WRITES_TO`, `EMITS`, `LISTENS`, `WRAPPED_BY`, `GUARDS`, `HANDLES`, `TESTS`, `USES` - **第三方依赖节点** — 选定的 npm 包在图中显示为紫红色六边形节点，并具有来自本地文件的 `IMPORTS` 边。分析前的库选择步骤允许你选择要包含哪些包（默认为检测到的运行时依赖项） - **完整的 TypeScript 签名** — 捕获并显示每个节点的带有类型的函数和 hook 参数、返回类型注解以及引用的接口定义 - **组件 prop 类型** — 检测每个 React 组件声明的 Props 接口，并显示在详情面板中 - **状态层检测** — 检测 Redux、Zustand、Jotai 和自定义 hooks，然后映射读取或写入每个 store 的每个组件 - **重要性评分** — 综合考虑复杂度、扇入、扇出和类型加分的多阶段算法 - **路由入口点** — 检测 Next.js app/pages router 以及 Express/Fastify/Koa 路由；从 HTTP endpoint 进行 BFS 扩展，揭示完整的调用链 - **提交感知** — 跟踪多个提交，通过 git 历史在分支间智能重用摘要 ### 摘要生成 - **每个节点包含两个摘要** — 业务摘要（用产品术语解释它的作用）和技术摘要（解释其实现方式） - **拓扑排序** — 首先总结叶子节点，以便每个节点的 prompt 包含其依赖项的摘要，从而生成更丰富、更准确的输出 - **检查点与恢复** — 在总结过程中暂停、恢复或从崩溃中恢复，实现零数据丢失 - **针对大文件的 MapReduce** — 超过 1,200 个 token 的文件会被自动拆分、并行映射，并归约为最终的摘要 - **安全分析** — 标记每个节点的高/中/低风险模式 - **智能重用** — 提交之间未更改的节点永远不会被重新总结；在典型的重新运行中，90% 以上的节点是免费的 ### 前端 - **交互式 Cytoscape 画布** — 力导向布局、节点聚焦、缩放、平移 - **7 个侧边栏面板** — 项目信息、节点、搜索、高亮、文件、提交差异、安全问题 - **节点详情面板** — 摘要、连接、源代码、K-hops 和影响范围工具 - **提交差异叠加** — 可视化跨提交添加、删除、移动和重新评分的节点 - **延迟应用过滤器** — 过滤器更改会批量处理，直到你点击 Apply，防止在大型仓库上发生重新渲染 - **实时任务流式传输** — 基于 SSE 的实时分析和摘要生成进度 ## 工作原理 ``` Your Repo │ ▼ [1] Fingerprint Detect framework, language, router, state manager, databases [2] Filesystem scan Extract routes (Next.js app/pages, Express, Fastify, Koa) [3] AST parse ts-morph walks every .ts/.tsx/.js/.jsx file [4] Edge detection 10 detectors run in parallel → dependency graph [5] Scoring Multi-pass importance scoring, noise filtering [6] Save graph Written to ~/.devlens/ — instant on re-open [7] Summarize Topologically ordered LLM calls with checkpoint/resume │ ▼ Interactive Graph UI ``` ## 性能表现 来自生产仓库的真实数据： | 指标 | 数值 | |--------|-------| | 图谱生成（499 个节点） | 约 6-7 秒 | | 图谱生成（2,500 个节点） | 约 20 秒 | | 摘要生成（499 个节点） | 约 5-6 分钟 | | 摘要生成（2,500 个节点） | 约 20 分钟 | | Token 使用量 — 499 个节点的仓库 | < 100 万 token | | Token 使用量 — 2,500 个节点的仓库 | 约 200 万 token | | 重新分析（重用未更改的节点） | 90%+ 的节点免费 | | 成本 — 使用 grok-4.1-fast 分析 400 个节点的仓库 | 约 $0.30 | ## 应用场景 ### 理解 AI 生成的代码库 AI 工具编写代码的速度很快——但快速生成的代码会变成一个黑盒。DevLens 为你提供每个组件的可视化图谱、它们的连接方式以及它们用通俗易懂的语言描述的功能。你消耗的 token 大幅减少，因为图谱和摘要提前完成了繁重的工作。 ### 新员工入职 让新员工接触任何代码库。他们可以探索图谱、阅读每个模块的 AI 摘要，并在数小时（而非数周）内理解架构。知识传递变成了一条链接，而不是一场会议。 ### 影响范围与冲击分析 在合并 PR 之前，使用影响范围分析查看可能受更改影响的每个节点。直观地对比提交，准确查看哪些内容发生了移动、重要性得分发生了什么变化，以及添加或删除了什么。 ### 架构审计 突显高重要性节点、识别安全风险、发现循环依赖，并了解哪些文件是真正的架构瓶颈——所有这些都在一个视图中完成。 ### 动态文档 每个节点都会自动生成业务摘要和技术摘要。你的代码库实现了自我文档化，并随着代码的更改保持最新状态。 ### 安全审查 安全面板将所有高/中/低风险节点集中展示，并提供严重性说明。按严重性过滤、按文件搜索、点击检查源代码。 ### 充满信心地进行重构 使用 K-hops 了解任何节点的周边环境——它调用了什么以及什么调用了它。使用影响范围了解如果更改它会导致什么崩溃。快速推进，而不会破坏原有功能。 ## 配置 如果你不想设置环境变量，请打开导航栏中的 Config 面板，直接在 UI 中输入你的设置。 ### 支持的提供商 | 提供商 | 推荐模型 | 备注 | |----------|------------------|-------| | Ollama (本地) | `qwen2.5-coder:7b` | 免费，本地运行，需要 8GB+ 内存。在大型仓库上运行较慢。 | | OpenAI | `gpt-4o-mini` | 快速，性价比高 | | Anthropic | `claude-haiku-4-5-20251001` | 卓越的代码理解能力 | | OpenRouter | `grok-4.1-fast` | 访问 100 多种模型。推荐用于平衡成本和质量。 | ### 环境变量 ``` LLM_PROVIDER=openrouter # ollama | openai | anthropic | openrouter LLM_MODEL=grok-4.1-fast # model name for the chosen provider LLM_API_KEY=your_api_key # not needed for ollama LLM_BASE_URL= # optional custom base URL ``` ## DevLens 云端版 托管的云端版本目前正在开发中。它将包含： - **GitHub 集成** — 直接连接仓库，无需本地克隆 - **可共享的图谱** — 与你的团队分享图谱，或通过链接将其公开 - **团队协作** — 在任何节点上留下注释，以团队形式跟踪更改 - **LLM 接口** — 用通俗易懂的语言询问有关代码库的任何问题，并使用你的图谱和摘要进行回答 - **语义搜索** — 跨所有节点摘要进行向量搜索 - **PR 审查摘要** — 在每个 pull request 上自动生成 AI diff 摘要 - **持久化存储** — 将图谱保存到云端，可从任何设备访问 **[加入候补名单 →](https://devlens.io)** ## 项目结构 ``` devlens/ ├── engine/ # Bun server + analysis pipeline │ └── src/ │ ├── server/ # HTTP handlers, SSE streaming, routing │ ├── pipeline/ # Main analysis orchestration │ ├── parser/ # ts-morph AST extraction │ ├── graph/ # Edge detection (10 detectors) │ ├── scoring/ # Importance scoring + noise filtering │ ├── summarizer/ # LLM summarization, checkpoint system │ ├── filesystem/ # Route detection (Next.js, Express, etc.) │ ├── storage/ # File-based graph persistence │ └── jobs/ # Job queue, concurrency, SSE events └── frontend/ # Next.js 15 UI └── src/ ├── app/ # Pages (home, graph view) ├── components/graph/ # Canvas, sidebar, panels, filters └── lib/ # API client, hooks, types, algorithms ``` ## License DevLens 采用 [GNU Affero General Public License v3.0](LICENSE) 授权。 你可以自由使用、修改和分发 DevLens。如果你将修改后的版本作为托管服务运行，则必须在相同的许可证下发布你的修改。

标签：AI风险缓解, TypeScript, 云安全监控, 人工智能辅助, 代码可视化, 代码审查, 威胁情报, 安全插件, 开发者工具, 数据可视化, 架构分析, 自动化攻击, 静态分析