Groma.md 发布：可随代码变更实时更新的 C4 架构图工具

你的架构，活起来了。 以 OKF Markdown 存储在 Git 中的仓库实时 C4 架构图。 groma.md 将你的代码扫描成初始的 C4 架构图。你可以自己或借助编码智能体将它整理成你会向新同事讲解的架构。工作时架构图保持打开。保存文件，图就会更新。处理 Backlog.md 任务时，该任务会固定显示在它涉及的组件上。一切都是以纯 Markdown 形式存放在你的仓库中，因此架构变更与代码在同一个 pull request 中接受审查。 想要在你的 PR 上自动生成架构 diff？把它添加到你的仓库。 groma.md 免费、采用 MIT 许可证，在本地运行，无需账户或后端。安装扫描器后，扫描可离线运行，使用确定性的代码分析，不调用任何 AI 服务。你可以完全不使用 AI 来使用 groma.md。 三步。扫描你的代码，然后自己或借助编码智能体审查并整理架构图。 npm i -g groma.md backlog.md Backlog.md 提供图上显示的任务；groma.md 在没有它的情况下也能工作。若不想用 Node.js，可下载适用于你平台的独立可执行文件。macOS 需要 Apple Silicon。 cd your-repo groma web # 扫描并在 http://localhost:4747 打开浏览器架构图 groma web 在启动时自动扫描你的仓库并打开架构图。在新项目中，它会首先在浏览器中引导你完成项目设置和扫描器选择。 首次扫描会根据扫描器能检测到的内容给你一张初始图。要把它变成你的架构，点击架构图首次扫描提示上的 Copy prompt，并粘贴到你的编码智能体中： 使用 Groma 整理此仓库的架构。运行 groma agent-instructions 并遵循其整理工作流。按架构当前的实际情况描述它；不要修改应用代码。 你也可以用 groma.md 的命令（groma instructions 和 --help）自己整理架构图。安装过程会在你的 AGENTS.md 或 CLAUDE.md 中注册 groma.md，让智能体知道从哪里开始。工作时保持架构图打开：变更会实时出现，后续扫描会保留你的整理结果。 智能体与人们使用相同的 CLI。groma agent-instructions 打印一份以任务为导向的智能体指南索引，每个命令都通过 --help 自我说明。任何文件都能解析到拥有它的架构，因此智能体可以从它刚刚修改的代码开始： groma view src/orders.ts # 此文件的拥有者及其关系 智能体指南 可漫游的浏览器架构图。从系统缩放到容器再到组件。选择任何元素以阅读它的功能并打开其背后的源代码。浏览器指南 实时更新。保存代码会刷新源证据和检测到的关系；新文件会成为新组件。 关系与流程。描述组件如何交互，然后将关系串联成读者可以逐步浏览的具名流程。关系与流程 草稿。在系统、容器和组件存在之前先勾勒它们。它们会以虚线形式显示在真实元素旁边，直到扫描匹配到它们的代码并且你接受它们。草稿生命周期 跨架构查看工作。Backlog.md 任务会固定显示人们和智能体正在工作的位置；选择一个任务以高亮它涉及的组件，并在不离开架构图的情况下检查其变更。任务链接 探索历史并比较提交。打开任何早期修订版本及其源代码，或在架构图上比较两个提交（或未提交的变更），查看新增、修改和移除的组件与关系。 发布静态站点。groma export ./site 导出一个独立、只读的架构图，涵盖你的工作树、某个提交或提交比较，你可以将其托管在任何地方。静态发布 纯 Markdown、C4、OKF 架构以 Open Knowledge Format 0.2 bundle 的形式存放在 groma/ 文件夹中：每个元素一个 Markdown 文档（包含其关系），外加流程和草稿记录。C4 提供结构，OKF 保持其可移植性，文档在没有 groma.md 的情况下仍然可读。架构 Markdown 契约 语言或框架 状态 TypeScript ✅ 可用 JavaScript ✅ 可用 Angular ✅ 可用 React ✅ 可用 Vue ✅ 可用 C#/.NET ✅ 可用 Go ✅ 可用 Java (Maven, Gradle) ✅ 可用 Python ✅ 可用 Rust ✅ 可用 PHP ✅ 可用 Swift ✅ 可用 C 🧪 实验性 C++ 🧪 实验性 Kotlin 🧪 实验性 Ruby / Rails 🧪 实验性 Scala 3 🧪 实验性 Dart（Flutter 和 Serverpod 源码） 🧪 实验性 R 🧪 实验性 Ada 🧪 实验性 Mojo 🧪 实验性 MQL5 🧪 实验性 COBOL（IBM 固定格式） 🧪 实验性 Assembly（NASM x86-64、Linux ELF64） 🧪 实验性 你最喜欢的语言或框架 提交 issue 提出你的请求 更多语言以扫描器插件的形式到来；用 groma plugin add 添加你自己的。每个扫描器的页面描述它能读取什么。查看 groma.md 检测哪些关系。 为什么我不能直接让我的智能体画一张架构图？ 你可以，而且这张图在绘制当天是准确的。在那之后它就是一张静态图片：随着每次提交而落后，再问一次会得到一张新图，你无法与旧图比较。 groma.md 让架构保持实时。你的智能体的整理结果以 Markdown 形式保存在你的仓库中，架构图从那里跟随代码：保存文件会更新它，后续扫描会保留你的智能体所写的内容，你可以比较任意两个提交，或你的未提交变更，来看架构如何变化。 不能。groma.md 在你的机器上运行，不需要账户。它读取你的仓库，将 Markdown 写入其中，并在 localhost 上提供架构图。它不调用任何 AI 服务。你可以自己整理架构图；如果你使用编码智能体，请检查该智能体如何处理你的代码。groma.md 唯一的网络请求是查找和下载你安装的扫描器包。 不能。一旦文档存在，扫描只会刷新其代码引用：即它拥有的文件中的符号。名称、描述、分组、你的智能体合并的文件，以及它添加的关系都保持原样。新文件会作为新组件出现，供你的智能体放置。

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）