inkboard/system-atlas

解决的问题

System Atlas 解决了过时且静态的架构图问题。与其手动绘制很快就会变成"谎言"的图，它提供了一个单一真实来源（数据文件），可自动生成交互式等轴测图可视化地图和结构化文本文档（SYSTEM.md）。这确保了系统架构的视觉和文本表示始终保持一致，并可通过一次编辑完成更新。

如何工作

该工具采用数据驱动的方式映射系统：

1. 单一真实来源：所有系统结构、流程和决策均在 data.mjs 文件中定义。
2. 生成：构建脚本（build.mjs）处理此数据，生成两个输出：用于交互式探索的自包含 atlas.html 文件和用于文档的 SYSTEM.md 文件。
3. 交互式地图：生成的 HTML 地图允许用户悬停查看结构内容，点击进行固定，并深入查看执行步骤。它采用“渐进式披露章节”机制，通过逐步揭示系统的小块内容，防止信息过载。
4. 代理集成：它被设计为一种“代理技能”，意味着 AI 代理可以根据自然语言请求触发创建、更新或浏览该地图。

适用人群

适用于需要向他人传达复杂系统设计的开发者和架构师，需要通过稳定 ID 追踪架构决策和待解决问题，并希望维护与实际代码库保持同步的文档的人。

主要亮点

• 交互式等轴测图：可缩放、可平移的 HTML 地图，不同系统组件（如大脑、存储、网关）使用角色特定的形状。
• 文本孪生：自动生成包含决策表、流程表和问题索引的 SYSTEM.md 文件。
• 渐进式披露：将系统组织为章节，逐步揭示结构和数据流。
• 可检查的数据包：将实际请求可视化为移动的点，点击可检查 JSON 负载。
• 问题追踪：使用稳定 ID（Q-<code><n>）通过反馈轮次追踪开放和已解决的架构问题。