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>）透過反饋回合追蹤開放與已解決的架構問題。