agustinvillegas/repomap

# RepoMap — 交互式 GitHub 架构图 一款智能 Web 应用程序，可分析 GitHub 仓库并使用 AI 生成交互式、可编辑的架构图。RepoMap 能够区分运行时依赖和结构设计模式，从而为复杂的代码库创建有意义的可视化效果。 ## 功能 - **GitHub 仓库分析**：通过 URL 自动获取并分析任何公开的 GitHub 仓库 - **AI 驱动的架构检测**：使用 Claude (Anthropic) 或 Llama (Groq) 智能识别模块、层次、组件及其关系 - **交互式可视化**：基于 React Flow 的图形编辑器，用于探索和理解代码库架构 - **手动创建图表**：无需仓库或 API 密钥即可从头绘制图表 - **持久化存储**：基于 IndexedDB 的本地存储，用于保存分析过的图表和聊天历史 - **分支与探索**：创建独立的分析分支，探索不同的架构视角 - **进度恢复**：如果触发速率限制，可恢复中断的分析 - **私有仓库支持**：使用 GitHub 个人访问令牌分析私有仓库 - **灵活的 AI 提供商**：在运行时随时切换 Anthropic Claude（付费）或 Groq Llama（免费） ## 架构 ### 技术栈 - **前端**：Next.js 14 (App Router)、React 18、Tailwind CSS - **图形渲染**：React Flow，用于交互式节点/边可视化 - **AI 集成**：Vercel AI SDK，支持 Anthropic 和 Groq - **数据持久化**：通过 `idb` 库使用 IndexedDB（无需后端） - **GitHub 集成**：使用 Octokit 进行 REST API 访问 - **数据验证**：使用 Zod 进行 schema 验证 - **样式**：Tailwind CSS 结合自定义设计系统 ### 项目结构 ``` src/ ├── app/ │ ├── api/ │ │ ├── analyze/route.ts # Pipeline execution endpoint │ │ └── chat/route.ts # AI chat endpoint │ ├── layout.tsx # Root layout │ └── page.tsx # Main UI entry point ├── components/ │ └── graph/ │ ├── GraphRenderer.tsx # Main visualization component │ ├── GraphNodes.tsx # Node rendering logic │ ├── ManualEditor.tsx # Manual diagram creation │ ├── ChatPanel.tsx # AI chat interface │ ├── AlternativeViews.tsx # Alternative visualization modes │ └── graphLayout.ts # Graph layout algorithms ├── branches/ │ ├── UseBranches.tsx # React context for branch management │ ├── BranchPanel.tsx # Branch UI controls │ ├── storage.ts # Branch persistence │ ├── resolver.ts # Branch conflict resolution │ └── types.ts # TypeScript definitions ├── lib/ │ ├── pipeline/ │ │ ├── pipeline.ts # Main orchestrator │ │ ├── aiClient.ts # AI SDK initialization │ │ ├── prompts/ │ │ │ ├── pass1.ts # Structure detection │ │ │ ├── pass2.ts # Dependency mapping │ │ │ └── pass3.ts # Semantic analysis │ │ ├── sampler/ │ │ │ └── fileSampler.ts # Token budget manager │ │ └── schemas/ │ │ ├── graph.ts # Graph JSON schema │ │ └── validation.ts # Zod validators │ ├── storage/ │ │ ├── graphStore.ts # Graph persistence │ │ └── chatStore.ts # Chat history │ ├── github/ │ │ └── githubClient.ts # GitHub API wrapper │ ├── modelConfig.ts # AI provider configuration │ └── ai.ts # General AI utilities ``` ## 分析流水线 RepoMap 使用确定性的 3 阶段分析流水线来理解仓库结构： ### 第 1 阶段：结构检测 - **输入**：来自 GitHub 的文件树路径 - **输出**：识别相关文件、初步模块划分、大小估算 - **目的**：在不分析代码内容的情况下获取高层级仓库结构 ### 第 2 阶段：依赖映射 - **输入**：抽样文件内容 + 第 1 阶段的模块 - **输出**：带有类型、置信度和关系的图节点和边 - **目的**：识别组件之间的依赖和连接 - **采样**：基于估算的仓库大小进行智能文件采样 ### 第 3 阶段：语义分析 - **输入**：第 2 阶段的图结构（仅拓扑结构） - **输出**：节点角色、设计模式、布局建议 - **目的**：添加语义含义并优化可视化布局 - **效率**：仅处理图拓扑结构（token 成本最低） ## 图 Schema RepoMap 使用标准化的 JSON schema 来表示架构： ``` interface RepoGraph { meta: { repoUrl: string repoName: string analyzedAt: string detectedPattern: string estimatedSize: 'small' | 'medium' | 'large' } nodes: GraphNode[] luego edges: GraphEdge[] overlay: { nodeEdits: Record edgeEdits: Record } } interface GraphNode { id: string // Format: 'type__name' (layer__api, module__auth) label: string type: 'layer' | 'module' | 'file' | 'component' depth: 0 | 1 | 2 | 3 role?: string // 'controller', 'service', 'utility', etc. metadata: Record } interface GraphEdge { id: string source: string target: string type: 'import' | 'dependency' | 'reference' confidence: 'high' | 'medium' | 'uncertain' label?: string metadata: Record } ``` ## 入门指南 ### 前置条件 - Node.js 18+ - npm 或 yarn - 用于私有仓库分析：GitHub 个人访问令牌 ### 安装说明 ``` # Clone repository git clone cd repomap-pipeline-v2 # Install dependencies npm install # 启动 development server npm run dev ``` 在浏览器中打开 [http://localhost:3000](http://localhost:3000)。 ### 配置 #### AI 提供商选择 在两个提供商之间进行选择： **选项 1：Anthropic Claude（付费）** - 需要 Anthropic API 订阅 - 更好的分析质量 - 对复杂架构具有更高的准确性 - 默认使用 `claude-sonnet-4-20250514` **选项 2：Groq Llama（免费）** - 需要从 [console.groq.com](https://console.groq.com) 获取免费的 Groq API 密钥 - 使用 `llama-3.3-70b` 模型 - 速率限制约为 30 次请求/分钟 - 受速率限制时会话之间自动保存进度 可以通过 UI 或环境变量切换提供商： ``` AI_PROVIDER=groq # or 'anthropic' AI_MODEL=llama-3.3-70b # or 'claude-sonnet-4-20250514' GROQ_API_KEY=gsk_... # Groq key ANTHROPIC_API_KEY=sk-... # Anthropic key ``` #### GitHub 配置 针对私有仓库： 1. 在 [github.com/settings/tokens](https://github.com/settings/tokens) 创建一个 GitHub 个人访问令牌 2. 将令牌粘贴到 UI 界面的 "add github token" 部分 3. 令牌存储在 sessionStorage 中，永不会持久化保存 ### 使用方法 #### 自动分析 1. 输入 GitHub 仓库 URL（例如，`facebook/react`） 2. 选择 AI 提供商并添加所需的 API 密钥 3. 点击 "analyze repository" 4. 观察 3 阶段分析的进度 5. 探索交互式图表 #### 手动创建 1. 点击 "create diagram manually" 2. 绘制节点并将它们连接起来 3. 分配角色、类型和元数据 4. 保存到本地存储 #### 分支探索 1. 从已分析的仓库中，点击 "create branch" 2. 独立探索不同的替代架构 3. 将更改合并回基础图 4. 比较不同的视角 #### 聊天与讨论 1. 与 AI 就架构进行交流 2. 询问有关依赖、模式和设计的问题 3. 获取改进建议 4. 聊天历史记录保存在 IndexedDB 中 ## 关键设计决策 ### Token 预算管理 第 2 阶段的文件采样会根据仓库大小进行调整： - **小型**（<300 行）：完整内容，无骨架提取 - **中型**（<150 行）：骨架模式（导入/导出 + 函数签名） - **大型**（<80 行）：带有积极截断的骨架模式 这确保了在所有仓库大小下保持一致的 token 消耗。 ### 置信度水平 边包含置信度注释： - **high**：源代码中显式的导入/依赖 - **medium**：从命名模式或代码邻近性推断得出 - **uncertain**：模糊的关系，需要用户澄清 用户可以在 UI 中对边进行重新分类以提供反馈。 ### 用户编辑隔离 所有用户修改都存储在与分析图分离的 `overlay`（覆盖）层中。这允许： - 重新分析而不丢失手动编辑 - 轻松对比分析状态和编辑状态 - 非破坏性的探索 ### 确定性流水线 分析流水线是确定性的（而非自主的工具调用）： - 可预测的执行流程（3 个阶段始终按顺序执行） - 更容易进行调试和错误恢复 - 如果触发速率限制，可在阶段边界处恢复 - 更好的 token 预算控制 ## 开发 ### 可用脚本 ``` npm run dev # Start development server npm run build # Build for production npm start # Start production server npm run lint # Run ESLint ``` ### 构建生产版本 ``` npm run build npm start ``` 生产构建针对包大小和性能进行了优化。图形渲染器组件采用动态导入。 ## 数据存储 RepoMap 使用 **IndexedDB** 进行所有本地持久化存储： - **图表**：完整的已分析架构 - **进度**：用于恢复中断分析的保存状态 - **聊天历史**：每个仓库的对话日志 - **模型配置**：UI 偏好设置 不会向外部服务器发送任何数据（GitHub API 和所选的 AI 提供商除外）。 ## 限制与未来工作 ### 当前限制 - 仅支持公开仓库（如果没有 GitHub token） - 单文件分析深度（无法跟踪完整的调用栈） - 暂无针对 monorepo 的特定支持 - 复杂图形需要手动调整布局 ### 计划功能 - [ ] Supabase 集成以实现云同步 - [ ] 感知 monorepo 的分析 - [ ] 自定义分析模板 - [ ] 导出为 Mermaid/PlantUML - [ ] 团队协作功能 - [ ] 基准测试与成本估算 ## 故障排除 ### 速率限制问题 - RepoMap 会自动保存进度 - 使用“恢复”按钮从上次中断的地方继续 - 检查您所选提供商的 API 密钥速率限制 ### 图形未渲染 - 检查浏览器控制台是否有错误 - 确保已启用 IndexedDB - 尝试清除浏览器缓存并重新加载 ### 分析质量不佳 - 尝试使用 Anthropic/Claude 提供商以获得更好的结果 - 确保仓库是公开的，或者 token 具有访问权限 - 检查仓库结构是否符合常规标准 ## 许可证 [在此填写您的许可证] ## 致谢 基于以下技术构建： - [Next.js](https://nextjs.org) - [React Flow](https://reactflow.dev) - [Vercel AI SDK](https://github.com/vercel/ai) - [Octokit](https://octokit.js.org) - [Tailwind CSS](https://tailwindcss.com)

标签：AI代码助手, AI辅助分析, Anthropic Claude, CI/CD安全, DevTools, DLL 劫持, GitHub仓库分析, IndexedDB, Llama, LLM, Octokit, React 18, React Flow, Tailwind CSS, Unmanaged PE, Vercel AI SDK, Zod, 交互式架构图, 代码分析, 代码架构可视化, 代码结构图, 低代码, 凭证管理, 可视化工具, 图表生成, 大模型, 大语言模型, 威胁情报, 开发者工具, 无后端, 模块分析, 浏览器本地存储, 自动化攻击, 自动架构检测, 软件架构设计