把 URL 里的 hub 换成 diagram：一行字符改动看穿整个 GitHub 仓库

接手新项目的第一小时

你加入一个新团队，拿到一个有 200 个文件的项目仓库。README 写得不错——用了什么框架、解决什么问题、怎么跑起来。但你还是不知道这个项目"长什么样"。

你打开 tree 命令看目录结构，得到一个 200 行的文件树。你看到 src/auth/、src/api/、src/utils/、src/components/，但你不知道 auth 依赖了 api 还是反过来。你打开架构文档，发现最后更新是 8 个月前，和现在的代码已经对不上。

你只能 clone 下来，一个文件一个文件翻。第一小时就这么过去了。

这是每个开发者都经历过的场景。代码可视化工具存在了二十年——从 tree 到 git log --graph 到各种 dependency graph 工具——但它们都停留在同一个层面：画文件结构，不画系统架构。

ahmedkhaleel2004/gitdiagram 做了一次跳跃：用 LLM 理解代码语义，直接生成架构级图表。

URL hack：最低门槛的交互设计

GitDiagram 最聪明的设计是它的入口：

把 GitHub URL 里的 hub 换成 diagram。

github.com/owner/repo  →  gitdiagram.com/owner/repo

就这么简单。不需要装扩展、不需要 clone、不需要登录。你在浏览器地址栏改两个字符，就能看到这个仓库的架构图。

这个设计的巧妙之处在于它利用了用户已有的肌肉记忆。开发者每天都在敲 github.com/...，把 hub 改成 diagram 是一个极小的认知成本。相比之下，装扩展、配 token、学新命令都是摩擦。

URL hack 这个模式在开发者工具里有一段历史。Gitingest（GitDiagram 的灵感来源）用同样的模式——把 hub 换成 ingest——把 GitHub 仓库变成可读的纯文本。OctoPR 把 hub 换成 octo 看 PR 统计。这个模式的共同特点是：零安装、零配置、零认知成本。

从目录树到架构图：可视化的语义跳跃

代码可视化工具可以按"理解层次"分三代：

第一代：文件结构可视化

• 代表：tree、git log --graph、GitHub 自带的文件浏览器
• 做什么：画出文件和目录的树形结构
• 局限：只看到"有什么文件"，看不到"它们怎么协作"

第二代：依赖关系可视化

• 代表：madge、dependency-cruiser、pydeps
• 做什么：分析 import/require 语句，画出模块依赖图
• 局限：只看到"谁 import 谁"，看不到"业务上它们是什么"

第三代：架构语义可视化

• 代表：GitDiagram
• 做什么：用 LLM 理解代码的语义，画出"系统架构图"——哪些是入口、哪些是服务、哪些是数据层、它们怎么交互
• 突破：从"文件级"跳到"组件级"

第二代的依赖图长这样：auth.js → api.js → db.js。你看到的是文件名和箭头，但你不知道 auth.js 是认证服务、api.js 是 API 网关、db.js 是数据访问层。

第三代的架构图长这样：一个标着"Authentication"的框，通过箭头连到标着"API Gateway"的框，再连到"Data Layer"。同样的依赖关系，但用业务语义而非文件名表达。 这就是 LLM 带来的跳跃——它能理解代码"做什么"，不只是"引用谁"。

技术实现：一次 LLM 调用，多层校验

GitDiagram 的生成流程值得拆解：

1. 仓库获取：通过 GitHub API 拉取默认分支、递归文件树、README。超大仓库（truncated tree）直接拒绝，避免浪费 token。
2. 源码采样：不是把整个仓库丢给 LLM，而是采样关键模块的源码片段。采样策略优先选择"有实质内容的运行时模块"，跨长文件分布采样，保留 import 关系。
3. LLM 生成：一次 GPT-5.6 Luna 请求（medium reasoning），流式输出两部分——先一段架构概述，再一个结构化图（groups/nodes/edges/shapes/labels/paths）。
4. 校验：服务端验证 identifier、图连通性、size 限制、每个链接的路径是否真实存在于仓库中。无效输出带反馈重试。
5. 编译：确定性编译器把验证过的 AST 转成 Mermaid，全部文本转义，链接只允许指向 github.com。
6. 渲染：浏览器端 sanitize 源码，严格安全模式渲染 Mermaid，sanitize SVG，再次强制链接白名单。
7. 持久化：成功结果存到 R2，下次访问直接读缓存，不再调 LLM。

这个流程的关键设计是"LLM 只负责理解，不负责输出格式"。LLM 输出的是结构化 AST（抽象语法树），编译成 Mermaid 是确定性步骤。这意味着 LLM 即使"想画错"也错不到哪去——AST 的 schema 是固定的，校验器会拒绝不合规的输出。

这个"LLM 理解 + 确定性编译"的分工，是当前 LLM 应用工程的一个成熟模式。LLM 擅长语义理解（代码是什么意思），不擅长精确格式化（Mermaid 语法严格、容易出错）。把两件事分开，用 LLM 做前者、用代码做后者，比"让 LLM 直接输出 Mermaid"可靠得多。

交互式：点击节点跳到源文件

GitDiagram 的图不是静态图片。每个节点都是可点击的，点击后跳转到 GitHub 上对应的文件或目录。

这个设计解决了一个长期痛点：架构图和代码之间的"映射断层"。传统架构图（PPT 里画的那种）和代码是脱节的——你看图知道有"Auth Service"，但不知道它对应哪个文件。代码变了，图没变，图就成了谎言。

GitDiagram 的图里，每个节点都带着 GitHub 路径。你点击"Auth Service"，直接跳到 src/auth/index.ts。代码变了，重新生成图，映射关系自动更新。图和代码是同一个东西的两种视图，不是两个独立的产物。

这个设计也意味着 GitDiagram 不是"画图工具"，是"理解工具"。画图工具（draw.io、Excalidraw）让你从零开始画，你画什么取决于你理解多少。GitDiagram 让 LLM 帮你理解，图是理解的副产品。

私有仓库：token 不离开浏览器

GitDiagram 支持私有仓库，但设计得很谨慎：

• 用户在浏览器里输入 GitHub PAT（fine-grained，只读权限）
• token 只在 same-origin 请求里发送，不嵌入公开链接
• 私有生成的图存在 R2 的独立命名空间，用服务端 secret 隔离

这个设计的关键是"token 不离开浏览器"。很多工具会把 token 存到服务端数据库，方便后续调用，但也增加了泄露风险。GitDiagram 选择每次请求都带 token，不持久化，牺牲了便利性换安全。

流式生成：看 LLM "想"的过程

GitDiagram 的生成是流式的——你能看到 LLM 先输出一段架构概述（"这个项目是一个 Next.js 应用，主要分为..."），然后输出图的结构。

这个设计不是技术炫耀，是有实际价值的。流式输出让用户在等待时有反馈，知道"它在工作，不是卡死了"。对于大仓库（生成可能需要 30-60 秒），这个反馈至关重要。

但更深层的好处是：你能看到 LLM 的"思考过程"。 它先说"这个项目的入口是 server.ts"，然后你在图里看到 server.ts 节点。如果它理解错了（比如把测试文件当入口），你在概述阶段就能发现，不用等图画完再纠错。

Gitingest 的精神延续

GitDiagram 的 README 里有一行：

Inspired by Romain Courtois's Gitingest.

Gitingest 做的事情是把 GitHub 仓库变成可读的纯文本——把代码、README、目录结构拼接成一个长文本，方便丢给 LLM 做 context。它用的也是 URL hack（hub → ingest）。

GitDiagram 是这个思路的视觉化延伸。Gitingest 把仓库变成"给 LLM 看的文本"，GitDiagram 把仓库变成"给人看的图"。两者都利用了 LLM 的语义理解能力，只是输出形态不同。

这个"URL hack + LLM 理解"的模式可能还会衍生出更多变体——把仓库变成测试用例、变成 API 文档、变成 onboarding 教程。核心都是同一个洞察：GitHub 仓库是结构化数据，LLM 能把它转成任何形态。

代码可视化的下一步

GitDiagram 不是终点。代码可视化还有几个方向没被充分探索：

1. 动态图：现在的图是静态的，生成一次就固定了。理想状态是图能跟着代码 commit 自动更新，像 CI 一样跑在每次 push 后。
2. 多层级下钻：现在一张图画整个仓库。理想状态是点击"Auth Service"能展开它的内部架构，再点击能展开到具体函数。
3. 数据流标注：现在的图只画组件依赖。理想状态是能标注"用户请求从哪里进来、经过哪些层、数据怎么流动"。
4. 对比视图：两个版本的仓库并排显示架构图，高亮差异。这对 code review 有用。

这些方向 GitDiagram 都还没做，但它的架构（LLM 生成 AST + 确定性编译 + Mermaid 渲染）是支持这些扩展的。LLM 换个 prompt 就能生成不同层级的图，编译器换个 backend 就能输出不同格式（Mermaid、D2、PlantUML）。

代码可视化的瓶颈从来不是画图技术，而是"理解代码"这件事的成本。 LLM 把这个成本从"一个工程师读一周"降到"一次 API 调用 30 秒"。GitDiagram 是这个成本下降后的第一个产物，但不会是最后一个。

项目地址：https://github.com/ahmedkhaleel2004/gitdiagram
在线试用：https://gitdiagram.com/
协议：MIT
语言：TypeScript（Next.js 16 + React 19）
今日 Stars：145（2026-09-18 GitHub Trending）
灵感来源：Gitingest