AI Feeds
开源项目

gitdiagram

gitdiagram

基于 LLM 的仓库架构图生成器：抓取目录树、README 和有限源码片段后让模型输出组件与连线，编译成 Mermaid 渲染，点击节点可跳转 GitHub 真实文件，支持私有仓库 token 和 Mermaid/PNG 导出。亮点是把画目录树升级成系统级依赖图，并做了路径校验、失败重试与浏览器端 SVG 净化，结果持久化避免重复调用模型。MIT 协议。

README

GitDiagram 首页

License Ko-fi

GitDiagram

在几秒钟内，把任意公开或私有的 GitHub 仓库转换成可交互的架构图。

你也可以把 GitHub URL 中的 hub 替换为 diagram，直接打开它的架构图。

赞助位： 在开发者主动探索代码库时触达他们。赞助 GitDiagram。

功能特性

  • 架构优先的图： 将仓库目录树、README 以及有界的源码片段转换成系统级关系图，而不只是画出文件夹结构。
  • 可交互的源码链接： 点击某个组件，即可在 GitHub 上打开它对应的真实文件或目录。
  • 流式生成： 图还在规划时，就能看到说明文字逐步呈现。
  • 私有仓库： 在浏览器本地提供 GitHub token；私有产物使用单独受保护的存储命名空间。
  • 导出： 复制 Mermaid 源码，或将渲染后的图下载为 PNG。
  • 可选 provider： 默认使用 OpenAI，自托管部署可使用 OpenRouter。

技术栈

  • 应用： Next.js 16 App Router、React 19、TypeScript、Tailwind CSS 与 Radix UI
  • 生成 API： 同源的 Next.js Route Handlers，运行在 Vercel 的 Bun runtime 上
  • 存储： Cloudflare R2 用于存放图产物
  • 协调： Upstash Redis 用于配额核算、取消、锁以及短时失败状态
  • AI： 通过 AI_PROVIDER 选择 OpenAI 或 OpenRouter
  • 分析： PostHog
  • 部署： Vercel 是唯一在线运行的 runtime；保留了一套离线的 Railway/Docker 方案用于灾难恢复

这里没有单独的 FastAPI 实现、Postgres 数据库或 Neon runtime。

生产架构

Vercel 同时提供 UI 与生成端点：

  • /api/generate/cost 在完成有界的 GitHub 数据抓取后估算一次运行的消耗，同源且限流。
  • /api/generate/stream 通过 Server-Sent Events 流式推送说明文字与图的生成进度。
  • /api/generate/cancel 记录经过鉴权的同源取消信号。
  • /api/diagram-state 读取和写入持久化的结果契约。
  • /api/healthz 提供轻量的部署健康检查。

长时间的生成使用 300 秒的 Vercel function 预算，并设置更短的应用程序截止时间，以便配额对账与持久化仍有时间完成。请求使用显式的上游截止时间、重试、结构化日志、心跳以及分布式取消，而非进程本地状态。

默认的托管 OpenAI pipeline 会以 medium reasoning 发起一次 GPT-5.6 Luna 请求，产出以源码为依据的关系图和简短的流式概览。模型返回的是紧凑的关系图，不含冗余描述或类型说明。关系图会以确定性方式校验并编译；额外的 Luna 调用仅保留用于结构性修复，或在遇到 18 秒慢请求后进行一次恢复。慢连接会在其替代请求启动前被取消；其无法获取的部分用量会作为估算成本计入。托管的 GPT-5.6 请求显式使用 Fast 模式（service_tier: "priority"）；估算中包含其溢价，而最终成本按实际服务的模型与层级计算。用户自备的 key 保留标准服务与其配置的模型。显式的模型覆盖与 OpenRouter 保留两阶段 pipeline。输出 token 估算会预留配额，但不会限制 provider 的输出。

同一个 Next.js 应用还可以构建成面向 Railway 的极简、非 root 的 standalone Docker 镜像。不保留任何在线的 Railway 服务、源码连接或 Railway 域名。已提交的 Dockerfile 与 railway.json 是一套冷恢复方案，日后可在不恢复第二套后端实现的前提下重建完整应用。参见 docs/deployment-failover.md。

生成流程

  1. GitDiagram 通过 GitHub API 获取仓库的默认分支、递归目录树与 README。被截断的目录树与过大的输入会在模型工作开始前被拒绝。
  2. GitDiagram 获取有界的、带完整性校验的源码片段。选取时优先选择实质性的运行时模块，把片段分散到较长的文件中，并为被抽样的调用保留 import 绑定。
  3. 一次托管的 Luna 请求会流式输出简短的架构概览，紧随其后是严格格式的图：分组、节点、边、形状、标签与仓库路径。显式的模型覆盖与用户自备的 key 会保留各自独立的说明／图生成流程。
  4. 服务端会校验标识符、图的连通性、各项限制，以及每一条链接路径是否与实际仓库对应。无效输出会带着针对性的反馈重试。
  5. 确定性的编译器把校验后的 AST 转换为 Mermaid，并做完整的文本转义，且只生成指向 GitHub 的链接。
  6. 浏览器会对源码做净化处理，在严格安全模式下渲染 Mermaid，再对生成的 SVG 做净化，并再次强制链接白名单。
  7. 成功的产物与最终审计状态会被持久化，之后的访问无需再次调用模型即可重新打开该图。

完整的 Mermaid 解析器仍保留在测试套件中，作为编译器的契约测试。它被有意地不加载进生产环境的生成函数中，从而在不削弱图校验或浏览器安全性的前提下让服务端 bundle 保持小巧。

状态存储

  • 成功的公开生成结果： R2 对象，以仓库为 key
  • 成功的私有生成结果： 独立的 R2 命名空间，由服务端密钥派生
  • 赠送配额与有效取消 token： Upstash Redis
  • 无已保存产物的最终失败： 短时 Upstash 状态
  • 并发写入： 分布式锁，加最新会话胜出的持久化策略

私有仓库

在页头选择 Private Repos，并提供具备目标仓库读取权限的细粒度 GitHub personal access token。该 token 只会随相关的同源请求发送，绝不会嵌入公开的架构图链接中。

本地开发

确切的前置条件与环境细节请参见 docs/dev-setup.md。

git clone https://github.com/ahmedkhaleel2004/gitdiagram.git
cd gitdiagram
bun install
cp .env.example .env
bun run dev

打开 http://localhost:3000。

至少需要在 .env 中配置 R2、Upstash 以及一个 AI provider。GitHub PAT 或 GitHub App 是可选项，但强烈建议配置以获得更高的 GitHub API 限额。

提交 pull request 前，请运行完整的本地检查：

bun run lint
bun run typecheck
bun run test
bun run build

贡献

欢迎贡献。请提交带有明确描述与验证说明的 issue 或 pull request。

致谢

灵感来自 Romain Courtois 的 Gitingest。

开源项目ahmedkhaleel20042026-09-18原文

相关内容