Mindwalk: 以 3D 方式視覺化 AI 編碼代理會話

Mindwalk: 以 3D 方式視覺化 AI 編碼代理會話

Mindwalk 提供了一種空間化方法來審核 AI 編碼代理，透過在儲存庫的 3D 地圖上回放會話日誌。雖然標準的會話日誌會記錄代理做了什麼，但 Mindwalk 視覺化了代理如何理解任務——特別是它將哪些檔案視為相關，以及在採取行動之前探索了哪些地方。

代理行為的空間分析

Mindwalk 將儲存庫轉換為「夜間地圖」，代理的活動會產生光亮。這讓開發者可以一目了然地看到代理的足跡，判斷代理的探索是否符合任務的預期範圍。

視覺化模式與指標

  • Tree and Terrain Views (樹狀與地形視圖)：程式碼庫被表示為徑向樹或樹狀圖平面。發光的強度表示檔案被觸及的深度與頻率。
  • Touch States (觸及狀態)：檔案根據其最深層次的互動進行顏色編碼：
    • Moss Green (苔蘚綠)：已查看
    • Moon White (月光白)：已讀取
    • Warm Amber (暖琥珀色)：已編輯
    • Dark (深色)：未造訪
  • Playback Deck (回放控制面板)：分桶直方圖允許使用者透過滑動來瀏覽會話。觀察階段（search, read, exec）由冷色調表示，而變異階段（edit, verify）則發出暖色光。
  • Timeline Marks (時間軸標記)：特定符號標記關鍵事件：◇ 代表上下文壓縮 (context compactions)，○ 代表子代理啟動 (subagent launches)，以及 › 代表使用者回合 (user turns)。

技術架構

Mindwalk 被建置為一個本地 Go 二進位檔，確保任何會話數據都不會離開使用者的機器。它將數據分為兩個不同的產物：

  1. The Trace (追蹤)：透過適配器從會話日誌中衍生的正規化檔案觸及事件流。目前支援 Claude Code 和 Codex 會話日誌。
  2. The Citymap (城市地圖)：儲存庫的確定性佈局。因為相同的樹狀結構總是會產生相同的地圖，所以可以在不同的會話之間進行回放比較。

該系統使用本地 Go 伺服器來結合 trace 與 citymap，並提供使用 React 和 Three.js 建置的前端介面。

安裝與使用

Mindwalk 可以透過 shell 腳本安裝，或使用 Makefile 從原始碼建置。

Quick Start:

curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
mindwalk

Core Commands:

  • mindwalk serve: 掃描 ~/.claude/projects 和 ~/.codex/sessions 並在本地連接埠提供 UI 介面。
  • mindwalk open <session.jsonl>: 開啟特定的會話日誌。
  • mindwalk build <repo>: 生成儲存庫的 citymap JSON。
  • mindwalk trace <session>: 寫入正規化的 trace JSON。

社群洞察與使用案例

雖然有些使用者質疑 3D 視覺化相對於傳統 diff 的即時效用，但其他人則強調了空間化代理審核的高價值潛在案例：

"我認為其中一個很酷的點可能是某種空間/表示形式的比較：讓我們看看兩個不同的模型如何與程式碼庫互動（針對同一個問題），它們觸及了哪些檔案，以及它們做了什麼。"

其他社群成員指出，基於終端機的 "Read file" 日誌通常很難跟隨，而空間化表示形式可以更容易地識別 LLM 究竟是從哪裡獲取資訊。有些使用者建議將工具擴展到提供所有代理的累積歷史記錄，而非僅限於單次會話的歷史記錄。

Sources