ramp
將不熟悉儲存庫中的主題轉換成交互式地圖：分組節點、標籤邊、可點擊的詳細資訊面板，以及按實際執行順序編號的逐步解說。
此管線（pipeline）刻意拆分。靜態掃描找出哪些程式碼重要，你決定它的意義，然後渲染器繪製地圖。跳過靜態掃描直接閱讀儲存庫會比較慢且會遺漏檔案；跳過你的判斷則會產生一個沒人學到東西的呼叫圖。
工作流程
1. 掃描
node ~/.claude/skills/ramp/scripts/scan.js <repo> --topic "<topic>" --max 30 --out /tmp/scan.json
路徑使用絕對路徑，因為你將從目標儲存庫執行，而非從此處。
如果你還不熟悉儲存庫的結構，可以先不加 --topic 執行——這會輸出概覽，包含語言組成、最大的目錄以及最常被導入的檔案（hubs），這通常足以選擇一個好的主題。
主題掃描會回傳排序後的 nodes（檔案，包含 score、matched 術語以及提取的 defs）以及它們之間的 edges。seed: true 標記直接命中主題的檔案；其餘檔案則是透過圖形擴展（graph expansion）加入的，它們是補全圖像的呼叫者與被呼叫者。
如果掃描結果為空，表示主題術語不存在於程式碼中。請嘗試使用程式碼庫中使用的詞彙，而不是使用者所使用的詞彙。
2. 閱讀
閱讀所有種子檔案，以及任何名稱具有提示性的擴展節點。請確實閱讀它們——地圖的全部價值在於解說，而你無法從檔案列表寫出有用的 detail。
閱讀時，特別尋找：
- 進入點——這個流程在執行時期從哪裡開始？
- 不明顯的部分——防止錯誤的防護機制、真正完成工作的設定旗標、會讓新人感到驚訝的事情
- 實際順序——在執行時期，誰呼叫誰，順序為何？
3. 建模
撰寫一個模型 JSON（結構如下）。這是最需要判斷力的部分。
4. 渲染
node ~/.claude/skills/ramp/scripts/render.js /tmp/model.json -o /tmp/<repo>-<topic>.html
它會嚴格驗證，並拒絕渲染有缺陷的模型——邊中存在未知的節點 ID、重複的 ID、中斷的逐步解說參考。關於未解說或孤立節點的警告值得修復，而非忽略。
5. 發布
使用 Artifact 工具發布渲染後的檔案，並提供使用者連結。請勿先載入 artifact-design——範本已設計完成；直接按原樣發布即可。
模型的 Schema
{
"title": "登入流程",
"repo": "my-app",
"summary": "一到兩句話：事物的輪廓，以及關於它最有用的單一事實。",
"groups": [{ "id": "boot", "label": "應用程式啟動", "hint": "選擇性提示文字" }],
"nodes": [{
"id": "provider",
"label": "AuthProvider",
"group": "provider",
"role": "管理 Session 狀態",
"detail": "新人真正需要的那一段話。",
"files": ["src/context/AuthContext.jsx:12"],
"symbols": ["AuthProvider", "signInWithGoogle"]
}],
"edges": [{ "from": "provider", "to": "supabase", "label": "getSession, OAuth" }],
"walkthrough": [{ "node": "provider", "text": "這個步驟發生了什麼。" }]
}
groups 是列，從左到右，按依賴順序——左邊是進入點，右邊是原語。邊從導入者繪製到被導入者，因此遵循此順序的模型佈局會很整潔。最多六個群組會獲得不同的顏色。
walkthrough 是選擇性的，但它是具有教學功能的特性。請按執行時期順序排序，而非檔案結構。一個節點可能出現多次——流程會迴圈，而顯示這點正是重點。
好的地圖與無用地圖的區別
節點是概念，不是檔案。 兩個屬於同一概念的檔案（AuthContext.jsx + AuthContextValue.js）可以合併為一個節點；一個包含兩個不相關職責的檔案則可以拆分為兩個。無論如何，請將所有真實檔案放入 files 中。
6-14 個節點。 擁有 40 個節點的地圖就是使用者原本已經在看的那團亂麻。刪減到足以承載流程的節點——掃描的 score 排序會告訴你要保留哪些。在 summary 中說明你省略了什麼。
role 是一項工作，不是重複說明。 "管理 Session 狀態"——而不是 "Auth 提供者元件"。
detail 值得點擊。 寫出名稱無法直接體現的內容：為什麼這樣拆分、重要的旗標、它防止的錯誤、它所做的假設。如果一個 detail 只是重述標籤，請刪除該節點，或找出它真正的作用。
為每一條邊標示實際關係——"依據使用者進行守衛"、"getSession, OAuth"——而不是 "使用" 或 "導入"。
引用程式碼行。 在 files 中使用 path/to/file.ts:42 將讀者指向確切位置。
說明哪些部分承擔主要負載，哪些不是。 新人最需要知道哪些部分可以忽略。
備註
- 掃描器是零依賴的 Node.js 腳本，無需安裝。當目標是 Git 儲存庫時，它會尊重
.gitignore。 - Swift 以及同套件的 Java/C# 沒有檔案層級的導入；對於這些語言，掃描器會改為根據唯一的型別參考來推斷邊。請將這些邊視為強烈提示，而非確定事實。
- 導入解析是基於正則表達式的，並非型別檢查器。它能解析相對路徑、打包工具別名（
@/）以及基於路徑後綴的套件風格指定符。動態導入和生成的導入會被遺漏——如果你預期的檔案沒有出現，請自行將其加入模型中。