Unfold（代碼庫可視化）

Unfold（代碼庫可視化） 是做什麼的？

產生一個自包含的 HTML 頁面：一個總覽，可以逐層展開成系統的各個部分。引擎（assets/template.html）負責繪製、佈局、縮放、追蹤和編輯。你的工作是理解代碼並編寫圖表資料（JSON），讓一個對專案一無所知的讀者在看完後能夠解釋它。

在每一層，頁面都會回答三個問題：什麼進來了、對它做了什麼、什麼出去了。

品質標準

• 精確。 每個節點和邊都必須有你實際查看過的代碼作為依據。它的 source 要標明位置：path/file.py:symbol。在每個節點上標記 confidence：read、peeked 或 inferred。任何推斷出來的內容都要列給使用者看。
• 適配代碼庫。 使用專案自己的詞彙（模組名稱、主題和路由名稱照原樣使用），並根據每個部分的代碼選擇適合的圖表類型（見步驟 4）。
• 簡潔。 標籤 2 到 4 個字，標題一行，註解 1 到 3 句話，其他什麼都沒有。細節放在一次點擊或一次懸停之後，絕不顯示在畫布上。
• 從零開始即可導航。 meta.summary 用一句話說明系統的用途。一個簡短的 meta.glossary 定義專案的行話。註解以一個可作為懸停提示的句子開頭。

工作流程

1. 確定需求

意圖優先： 地圖的用途是什麼。它設定了範圍、深度、層級類型、導覽、媒體和詞彙表；references/intents.md 為每個意圖提供了預設值。

• 如果提示已經說明了，就不要問。 "帶我了解這個專案" 意味著 學習。"重試邏輯是如何運作的？" 意味著 解釋。"這個 PR 改變了什麼？" 意味著 審查。"我星期五要演示這個" 意味著 演示。
• 否則，在掃描之前先問一個問題，從以下選項中選擇：學習代碼庫、演示我的工作、解釋特定細節、審查變更，或其他（文件或交接、除錯單一路徑、規劃重構、審計資料流）。
• 然後最多問兩個後續問題，針對該意圖從 references/intents.md 中挑選。跳過對話中已經回答的問題。
• 記錄答案為 meta.intent 和 meta.audience。當擴展現有頁面時，復用其 meta.intent 而不是再次詢問。

然後，從對話中或在同一個簡短的批次中，確定：

• scope（範圍）： 哪個倉庫或其哪個部分；
• audience（受眾）： 新開發者、審查者、經理或演講；
• focus（重點）： 最重要的部分，需要最大的深度；
• confidentiality（保密性）： 頁面會被分享，所以除非另有說明，否則不要包含主機、機密、客戶名稱和未發布的計劃。

如果沒有代碼，則根據使用者的描述來工作。絕不憑空發明任何部分、流程或數字。

2. 分階段閱讀代碼庫，在預算內

大型倉庫無法放入上下文，而瀏覽整個檔案則會浪費上下文。分階段閱讀，一旦地圖有了基礎就立刻停止。

階段	命令	你得到的內容	成本
地圖	python scripts/scan_repo.py REPO [--section NAME]	語言、佈局、清單、入口點、帶有 file:line 的 I/O 信號、各部分之間的匯入、一個優先閱讀列表	小，由 --budget 限制
輪廓	python scripts/scan_repo.py REPO --outline [PREFIX]	每個類別和函式，帶有簽名和第一個文檔字符串行，不含函式體	中，由 --budget 限制
證據	python scripts/peek.py REPO file:line file:symbol ...	僅圍繞每個引用的幾行，合併後輸出，在固定的行和 token 預算內	每次調用小
深度	讀取完整檔案	僅在使用者關注區域內承載核心邏輯的 3 到 8 個檔案	大

如何進行各階段：

• 從 README、文檔和地圖開始。
• 對重要的資料夾使用輪廓。對於大型倉庫，對每個頂層部分單獨運行，而不是對整個倉庫運行。
• 對你計劃繪製的每個 I/O 信號和入口點，以及每個流程層背後的函式，使用 peek。
• 只有在邏輯真正複雜的情況下才讀取完整檔案。
• 維護一個持續更新的證據列表（節點 → file:symbol）。它將成為 source 欄位。
• 掃描基於正則表達式：它會漏掉動態綁定，並報告一些誤報，例如字串內的模式。在繪製之前用 peek 確認。

Token 預算。 每個命令都會以（≈N tokens）結尾。只花費地圖所需的：

• 在取得輪廓之前，絕不讀取完整檔案。Peek file:symbol，不要用寬廣的行範圍，並將引用批次處理到一個 peek 調用中。
• 一個截斷列表以 … N more; rerun with --section X 結尾。只有在地圖需要它時才去獲取。在大型倉庫上，一次使用 --outline PREFIX 只輪廓一個部分。
• 一旦你計劃繪製的每個節點都有了 source，就停止閱讀。
• 使用 unfold.py check 和 outline 檢查；不要重新讀取 JSON 或頁面。使用小編輯來修補 diagram.json；絕不要全部重新列印它。

成本、掃描快取以及跳過了什麼：references/reading-code.md（Token 預算）。

3. 確定系統邊界

列出輸入（請求、訂閱的主題、CLI 參數、讀取的檔案、感測器、配置）和輸出（回應、發布的主題、寫入的檔案、命令、資料庫寫入）。在每個架構和流程層級將其標記為 "role": "input" 或 "role": "output"。

4. 為每一層選擇圖表類型

總覽始終是 architecture：4 到 10 個部分、儲存庫和外部系統，左側輸入，右側輸出。值得打開的每個部分都會獲得其代碼所需的子類型：

內部的代碼是…	type	繪製方式
互相調用或傳遞消息的多個部分	architecture	rounded 部分，cylinder 儲存庫，cloud 外部系統
對輸入執行的一系列步驟：處理器、管道、作業或演算法	process	pill 開始/結束，rect 步驟，diamond 決策（帶有標記的分支），虛線迴圈
一段時間內的跨部分交互：請求生命週期、握手、動作目標	sequence	參與者為節點，從左到右；消息為邊 按順序；虛線代表返回
由狀態和事件驅動的行為：狀態機、模式管理器、連接、行為樹狀態	state	initial 和 final 標記，pill 狀態，邊標記事件或守衛條件
資料結構、結構描述、ORM 模型、訊息定義	data	table 節點，帶有 fields（"id: int PK"），邊標記基數
類別及其關係：物件模型、插件層級結構	class	class 節點，帶有 fields 和 methods；邊帶有 rel（inherits、implements、composition...）
系統在其世界中的樣子：使用者、相鄰系統、每個容器的技術	c4	person 代表人，部分帶有 tech，cloud 外部系統，分組作為邊界
什麼程式在哪裡運行：主機、設備、叢集、容器	deployment	node3d 機器，環境分組，每個上面有 tech
模組或套件匯入	dependency	rect 模組，邊從匯入者指向被匯入者
一個行為樹（py_trees、BehaviorTree.CPP、Nav2）	behaviour	節點帶有 bt（sequence、selector、parallel、decorator、action、condition）；邊從父到子 按執行順序
層級結構：配置樹、選單、文檔、主題	tree	父到子邊，按順序
發布、遷移、啟動或開機順序	timeline	節點按順序，每個都帶有 date

在代碼深入的地方也深入，在一個註解就足夠的地方停止。只有當一個部分的內部有 3 個或更多有意義的元素時才打開它。保持每一層大約 12 個節點；超過這個數量就進行巢狀。references/reading-code.md 包含 Web 服務、ROS 2、管道、CLI、韌體、前端和單一倉庫的模式。

5. 在代碼有視覺素材的地方添加

如果倉庫包含螢幕截圖、架構圖、演示 GIF 或影片（在 docs/、assets/ 和 README 中查找），使用 "media": {"src": "relative/path.png", "caption": "…"} 附加它們，或使用一個列表來為一個部分提供多個素材。任何帶有媒體的節點都會顯示縮圖徽章並打開檢視器；一個帶有 "shape": "image" 的節點會將圖片顯示在畫布上。對於 演示 意圖，請使用者提供你顯示的部分的螢幕截圖。

unfold.py build 會內嵌本地檔案。已發布的 claude.ai 頁面會阻擋遠端圖片，所以優先使用本地檔案。

6. 撰寫文字

• meta.summary：一句話說明系統為誰做什麼。
• meta.glossary：最多 8 個專案術語，每個定義不超過 10 個字。
• 每層的 caption：一行說明用途，例如 "每個目標在機械手臂移動前都會檢查其可達性"。
• 節點上的 note：其第一句話在懸停時顯示，因此要使其獨立成句；最多再寫兩句話放在詳細資訊卡中。
• 邊標籤：流動的內容，1 到 3 個字。

7. 撰寫導覽

對於 學習 和 演示（以及當地圖有超過兩層時），添加一個 meta.tours 條目：5 到 9 個步驟，按開發者會解釋的順序，從輸入到輸出。每個步驟命名一個 path（要打開的節點 ID，從總覽向下）以及可選的 node 來聚焦，帶有 title 和一到兩句 text。對於 演示，添加演講者 notes。對於 學習，以一個 quiz 步驟結束（{"q", "answer": node id, "explain"}）。如果沒有撰寫導覽，頁面也會生成一個，所以對於小型單層地圖可以跳過此步驟。

8. 檢查、審查、建置

python scripts/unfold.py check   diagram.json     # 錯誤會失敗；閱讀每個警告
python scripts/unfold.py outline diagram.json     # 在一個畫面中顯示整棵樹
python scripts/unfold.py drift   diagram.json --repo REPO   # 每個來源仍然可解析
python scripts/unfold.py build   diagram.json page.html --repo REPO   # 將 meta.repo 固定到該提交

將你生成的副本存為 diagram.generated.json，放在 diagram.json 旁邊；重新映射時需要它。

像你是新進開發者一樣閱讀輪廓：

• 你能從中解釋這個系統嗎？
• 每一層都回答了 輸入 → 處理 → 輸出 嗎？
• 每個子層的類型是否正確？

如果瀏覽器自動化（如 Playwright）可用，截取總覽和每種類型的一個內層的螢幕截圖，並修正重疊或交叉。

9. 交付

在 claude.ai 上使用 Artifact 工具，從 /mnt/user-data/outputs/ 發布 page.html，並使用 capabilities: {"artifact": {}, "downloads": true}，這將啟用儲存和匯出。在其他地方，直接交付檔案；它可以離線工作。

然後，用幾行文字告訴使用者：

• 總覽顯示了什麼；
• 哪些部分是推斷出來的；
• 如何閱讀頁面：點擊打開，懸停追蹤，Esc 或縮小返回，/ 搜尋，導覽 或 T 進行引導式導覽，P 進行簡報，以及編輯來更改內容；
• 匯出提供 PNG、SVG、PDF、Mermaid、draw.io 和 Excalidraw，用於投影片、README 和其他工具。

如果使用者之後編輯了頁面，從 python scripts/unfold.py extract page.html diagram.json 繼續，而不是從你的舊副本。

要在代碼更改後重新映射，使用 --changed-since <meta.repo.commit> 進行掃描，使用相同的 ID 更新 diagram.generated.json 的副本，然後使用 unfold.py merge 將其合併到編輯過的地圖中，以便手動編輯得以保留。步驟：references/reading-code.md（重新映射）。

參考資料

• references/intents.md：每個意圖改變了什麼，以及它的後續問題。
• references/schema.md：每個欄位、層級類型、形狀和顏色。
• references/reading-code.md：將代碼轉換為層級，包含每個生態系統的模式。
• 不要為一個圖表更改 assets/template.html。引擎的更改屬於倉庫，並應附有測試。