Newshot 
你的架构，鲜活呈现。你仓库的实时 C4 地图，以 OKF Markdown 形式存储在 Git 中。
groma.md 将你的代码扫描成第一版 C4 架构图。你可以亲自或借助编码智能体，把它整理成你会向新同事讲解的架构。工作时地图保持打开。保存文件，地图即更新。处理 Backlog.md 任务时，它会固定显示在其涉及的组件上。一切都在你的仓库中以纯 Markdown 保存，因此架构变更会与代码在同一个拉取请求中审阅。
想要在你的 PR 上自动显示架构差异？把它们添加到你的仓库。
groma.md 免费、采用 MIT 许可证，在本地运行，无需账户或后端。安装扫描器后，扫描可离线运行，使用确定性代码分析，不调用任何 AI 服务。你完全可以不使用 AI 来使用 groma.md。
开始使用
三步。扫描你的代码，然后由你自己或借助编码智能体审阅并整理地图。
1. 安装
npm i -g groma.md backlog.md
Backlog.md 提供地图上显示的任务；没有它 groma.md 也能工作。要在没有 Node.js 的情况下运行，请下载适用于你平台的独立可执行文件。macOS 要求 Apple Silicon。
2. 扫描
cd your-repo
groma web # scans and opens the browser map on http://localhost:4747
groma web 在启动时自动扫描你的仓库并打开地图。对于新项目，它会先在浏览器中引导你完成项目设置和扫描器选择。
3. 审阅与整理
首次扫描会根据扫描器能检测到的内容给出一张起始地图。要把它变成你的架构，请点击地图首次扫描提示上的 Copy prompt，并将其粘贴到你的编码智能体中：
Curate this repository's architecture with Groma. Run groma agent-instructions and follow its curation workflow. Describe the architecture as it exists today; do not change application code.
你也可以使用 groma.md 的命令（groma instructions 和 --help）自行整理地图。设置过程会将 groma.md 注册到你的 AGENTS.md 或 CLAUDE.md 中，这样你的智能体就知道从哪里开始。工作时保持地图打开：更改会实时显示，后续扫描会保留你的整理成果。
与你的智能体协作
智能体与人使用相同的 CLI。groma agent-instructions 会打印一份以任务为中心的智能体指南索引，每个命令都可通过 --help 自我说明。任何文件都能解析到拥有它的架构，因此智能体可以从它刚刚更改的代码开始：
groma view src/orders.ts # the owner of this file and its relationships
智能体指南
你将获得什么
- 可浏览的浏览器地图。从系统缩放到容器再缩放到组件。选择任何内容即可阅读其作用，并打开其背后的源代码。浏览器指南
- 实时更新。保存代码会刷新源代码证据和检测到的关系；新文件会成为新组件。
- 关系与流程。描述组件如何交互，然后将关系串联成读者可逐步查看的命名流程。关系与流程
- 草稿。在系统、容器和组件实际存在之前先勾勒它们。它们会以虚线形式显示在真实项旁边，直到扫描匹配到其代码并且你接受它们。草稿生命周期
- 跨架构查看工作进展。Backlog.md 任务会标出人和 agent 正在处理的位置；选中一个任务即可高亮它涉及的组件，并在不离开地图的情况下查看其改动。任务链接
- 探索历史并比较提交。打开任意较早的版本及其源码，或在地图上比较两次提交（或未提交的改动），查看新增、修改和移除的组件与关系。
- 发布静态站点。
groma export ./site会把你的工作树、某次提交或某次提交比较导出为一份独立、只读的地图，你可以托管到任何地方。静态发布
纯 Markdown、C4、OKF
架构以 Open Knowledge Format 0.2 bundle 的形式存放在 groma/ 文件夹中：每个元素一个 Markdown 文档（包含其关系），另有 flows 和 drafts 的记录。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 | 🧪 实验性 |
| Elixir / Phoenix / Ash | 🧪 实验性 |
| Scala 3 | 🧪 实验性 |
| Dart (Flutter and Serverpod source) | 🧪 实验性 |
| R | 🧪 实验性 |
| Ada | 🧪 实验性 |
| Mojo | 🧪 实验性 |
| MQL5 | 🧪 实验性 |
| COBOL (IBM fixed format) | 🧪 实验性 |
| Assembly (NASM x86-64, Linux ELF64) | 🧪 实验性 |
| 你最喜欢的语言或框架 | 提交 issue 提出请求 |
更多语言会以扫描器插件的形式加入；用 groma plugin add 添加你自己的。每个扫描器的页面会说明它读取哪些内容。查看 groma.md 会检测哪些关系。
FAQ
为什么我不能直接让 agent 画一张架构图？
你可以这么做，而且画出来那天图是对的。之后它就成了一张静态图片：每提交一次就落后一点，再问一次只会得到一张新图，而这张新图无法与旧图比较。
groma.md 让架构保持鲜活。agent 的整理结果以 Markdown 形式保存在你的仓库中，地图从那里开始跟随代码：保存文件就会更新它，后续扫描会保留 agent 写下的内容，你还可以比较任意两次提交，或比较未提交的改动，看看架构发生了什么变化。
groma.md 会把我的代码发送到别处吗？
不会。groma.md 在你的机器上运行，不需要账号。它读取你的仓库，把 Markdown 写入其中，并在 localhost 上提供地图。它不调用任何 AI 服务。你可以自己整理地图；如果你使用编码 agent，请了解该 agent 如何处理你的代码。groma.md 唯一的网络请求是查找并下载你安装的扫描器包。
下一次扫描会不会覆盖 agent 写的内容？
不会。文档一旦存在，扫描只会刷新它的代码引用：即它所拥有的文件中的符号。名称、描述、分组、agent 合并的文件以及它添加的关系都保持原样。新文件会作为新组件出现，等待你的 agent 安置。
我能在 pull request 中看到架构变化吗？
可以。架构就是同一仓库中的 Markdown，因此它的变化也属于该 pull request 的一部分。在公开仓库上，groma.md GitHub Action 会在 pull request 下评论变更计数，并附上交互式前后对比地图的链接。可以看一个 pull request 上的示例，或把它添加到你的仓库。
如果我停止使用 groma.md 会怎样？
不会破坏任何东西。架构以普通 Markdown 形式保留在你的仓库中，采用 Open Knowledge Format：每个元素一个文档，彼此链接，可在 GitHub 或任何编辑器中阅读。若要移除 groma.md，请删除 groma/ 文件夹以及 AGENTS.md 或 CLAUDE.md 中 <!-- groma:start --> 与 <!-- groma:end --> 之间的块。
它支持哪些语言？
每种语言或框架都通过一个扫描器插件运行；当前列表见 Languages。对于其他语言，可以编写一个扫描器插件或请求提供。
文档与贡献
- 文档索引
- 产品模型
- 贡献指南
- groma.md 宣言
- 什么是 groma？
许可证
groma.md 在 MIT 许可证下免费且开源。