repoviz

repoviz 是做什麼的？

將程式碼庫轉換為可渲染的圖表 URL。每個圖表都是一個 https://x-cmd.com/draw URL（扁平化、百分比編碼的參數），可在瀏覽器、GitHub README 和任何 Markdown 檢視器中渲染 SVG。預設模式不會寫入任何本地檔案；僅在透過 scripts/ 明確要求時才會進行本地匯出。

渲染 ≠ 憑空捏造：每個節點和連線都帶有來源證據（已驗證 / 推斷 / 未知）——輸出是可驗證的資產，而非 AI 草稿。

步驟 1 — 意圖分析與圖表路由

根據使用者意圖 + 儲存庫形狀選擇圖表類型。在構建該圖表前，僅讀取對應的 references/ 檔案。

使用者意圖	圖表	參考文件
系統概覽、資料夾層次、微服務、技術棧	架構圖 (/draw/archmap)	references/architecture.md
請求生命週期、函式呼叫鏈、API 握手	序列圖 (/draw/seq)	references/flowchart.md
分支邏輯、演算法、認證/管線階段	流程圖 (/draw/mermaid)	references/flowchart.md
狀態機、狀態、重試/回滾	生命週期圖 (/draw/lifecycle)	references/flowchart.md
資料管線、依賴/套件權重、流量路由	Sankey 圖 (?type=sankey)	references/sankey.md
功能樹、模組分類	心智圖 (/draw/mindmap)	references/general-charts.md
路線圖、時程、發佈計畫	甘特圖 (/draw/gantt)	references/general-charts.md
量化儲存庫指標（語言拆分、覆蓋率、成長）	資料圖表 (`?type=pie	hbar
泛稱的「視覺化此儲存庫」	多圖表組合：1 張 archmap 概覽 + 1 張 Sankey（資料/依賴流）或 seq（核心請求流）	兩個對應的參考文件

archmap 的相同語法同類（參見 references/architecture.md）：arch2（替代外觀）。資料/行為模型：uc、dataflow、erd、class —— 語法和即時範例在 references/technical-diagrams.md 中。長尾圖表（treemap、funnel、graph、...）：/draw/echarts?d=<url-encoded echarts option JSON>。

掃描模式 — 在讀取程式碼前設定掃描範圍（使用者可選擇；預設從意圖推斷）：

模式	範圍	典型輸出
快速	清單檔案、深度 2 的目錄樹、進入點	1 張概覽圖表
架構	模組、服務、依賴圖	archmap（+ 按權重排序的 Sankey）
深入分析	呼叫鏈、資料流、狀態機	seq / 流程圖 / Sankey 組合
影響	git diff 與基礎版本比較：變更的檔案及其依賴項目	變更流圖表
完整	以上所有	儲存庫報告（組合 + 品質報告）

影響模式會載入 references/architecture-diff.md（git diff 差異工作流程）；完整模式會載入 references/codebase-report.md（標準報告結構）；對同一儲存庫的重複掃描可能會載入 references/incremental-scan.md（可選的快取協定）；多圖表或對證據敏感的工作會載入 references/repository-ir.md。

步驟 2 — 有 Token 約束的程式碼庫掃描

1. 首先讀取根目錄的清單檔案：package.json、go.mod、Cargo.toml、 pyproject.toml、docker-compose.yml，以及深度 3 的目錄樹和已宣告的 進入點。
2. 永遠不要讀取每個原始檔。對進入點檔案和路由表進行抽樣；將元件總結為 高訊號節點和連線。
3. 盡可能從真實數量推導 Sankey 權重：檔案大小（du -sh）、 匯入/引用計數，或使用者提供的流量/成本數據。
4. URL 長度限制：將一個圖表保持在約 15–20 個節點（Sankey 約 60 條連線）， 以便 URL 保持可讀且在 CDN 限制內。對於大型儲存庫，產生一個高層級的 概覽圖表 + 每個子系統一個圖表，永遠不要產生單個密集的超大圖表。
5. 從清單檔案偵測語言和技術棧，並以此視角進行掃描：Go → 套件/介面/goroutine；TypeScript → 模組/匯入圖/API 路由；Rust → crate/trait/功能；Python → 套件/裝飾器/進入點。
6. 在掃描時記錄證據：每個節點/連線都會獲得 file[:symbol[:lines]] 和一個 等級——已驗證（在程式碼中看到）、推斷（從結構推導），或 未知（模式假設）。未實際開啟檔案前，永遠不要標記為已驗證。

步驟 3 — 構建 URL

• 首先為組合圖表構建輕量級的儲存庫 IR（一個共享的節點清單， 每個圖表一份文件）；在編碼時將 IR 映射到 URL。架構和驗證 協定：references/repository-ir.md。
• 您構建的每個 URL 都會將其標籤傳遞給渲染器——在構建、驗證或匯出之前， 套用步驟 4 的保密規則。
• 語法（節點/連線/邊界）、編碼表、工作範例和每種類型的限制 都在參考檔案中。請嚴格遵循；那裡的每個範例都經過即時測試。
• 編碼要點：空格 %20、+ %2B、& %26、# %23、</> %3C/%3E、 換行 %0A；分隔符 ; = , : / @ 保持原樣。不使用 Base64。
• 常用修飾符：title=、scheme=dark|light、t=<style>（每種類型的系列在 參考文件中——arch2/seq 使用 t=shadcn 效果最佳；arch2 節點接受一個可選的第 6 個 icon 欄位，例如 n=api;be;API;ECS;r2c0;aws:ecs）、w=/h=、v=N 用於固定快取 版本、num=all|peak|none（用於圖表）。
• PNG 輸出內嵌了 GB2312 一級 CJK 子集：罕見字元（例如「渲」）在 PNG 中會變成 方塊。SVG 沒有此限制——對於中文 PNG 標籤，建議使用常見的同義詞。
• 收到 4xx 回應時，回應主體是包含修正範例的純文字——讀取它， 修正有問題的參數，然後重試。永遠不要猜測兩次。

步驟 4 — 輸出交付

預設模式 — 不寫入檔案。 每個圖表回覆：

### <圖表標題>
![<標題>](<draw-url>)
*[互動預覽](<draw-url>)* · [在編輯器中開啟](<explore-url>)

- <項目符號：圖表顯示的內容——層級、關鍵路徑、最重的流量>
- <項目符號：顯著耦合 / 單點故障 / 所有權邊界>

• <explore-url> 將 /draw?type=X&q 重寫為 /draw/explore?type=X&q，將 /draw/<name>?q 重寫為 /draw/explore/<name>?q——draw 內建的互動式編輯器； 連結它，不要重新構建它。
• 每個圖表 2–5 個簡潔的項目符號。圖片是可交付成果；項目符號提供判斷。
• 保密：渲染——以及 L1 驗證和 export.sh 下載——會將圖表標籤 （對於流程圖，則是整個程式文本）作為 URL 參數發送到 x-cmd.com 渲染器；它們可能會出現在伺服器存取日誌中（百分比編碼 並非加密），而 Markdown 圖片嵌入可能會被用戶端或代理程式自動擷取。本地匯出並不能避免此情況——渲染仍然會向 x-cmd.com 請求。對於機密儲存庫，請在使用者明確批准前發出警告並獲得授權，再進行渲染、驗證或匯出——或者透過本機安裝的 draw CLI 完全離線渲染。

使用品質報告結束組合圖表（僅限真實計數——永遠不要捏造）：

儲存庫分析 — <repo> (<scan_mode>, <commit>)
檢查檔案數：N | 模組數：N | 關係數：N
證據：已驗證 N · 推斷 N · 未知 N
驗證：L1 通過|跳過（隱私） · L2 通過 · L3：N 個未解決（如下標記）

L1 並非自動執行——它會擷取 URL，也就是將圖表傳送到 x-cmd.com。對於機密儲存庫，僅在使用者明確批准後才執行（步驟 4 保密規則）；否則回報 L1 跳過（隱私）。在每個圖表下方標記每一個 未知。對於明確的「驗證」請求或 匯出前檢查：bash scripts/validate.sh <urls...>（L1 渲染）和 bash scripts/validate.sh --ir <ir.json>（L2 結構）。L3 是您對引用檔案的重讀。

匯出模式 — 僅當使用者明確說出「儲存到本機」、「下載 SVG/PNG」、「匯出圖片」、「短連結」、「將此放入我的 README」或「產生 HTML 報告」：

bash scripts/export.sh "<draw-url>" "<out.svg|png>"        # 單個下載
bash scripts/export.sh --batch <manifest.tsv>              # 多個："<url>\t<out>" 每行，支援 # 註解
bash scripts/shorten.sh <type> '<d-schema json>' [title]   # 永久 /draw/c/<hash>（僅限 ?type= 圖表）
bash scripts/build_html.sh "<title>" "<out.html>" '<json>' # 獨立報告（+ 可選的 ev 證據）
bash scripts/inject_readme.sh "<README.md>" '<json>'       # 在 repoviz 標記之間插入/更新圖表

• export.sh 透過 curl 下載（備用方案：已在本機安裝的 CLI——它永遠不會 擷取或安裝套件）；.png 目標會自動取得 &format=png（新增 &scale=2|3 以獲得更高解析度；傳遞 scheme=dark——PNG 預設為淺色主題）。 批次模式：每行一個 url<TAB>output，允許 # 註解；如果任何項目失敗則以非零退出。
• shorten.sh 將圖表定義（?d= JSON schema）以 POST 方式發送到 x-cmd.com—— 速率限制約每 IP 每分鐘 30 次。只有 ?type= 系列接受 POST；節點/連線圖表 （/draw/archmap、/draw/seq、...）會回傳 405——請保留其完整 URL。回傳的 /draw/c/<hash> 使用 GET 渲染且是永久的。僅在使用者明確要求時執行：儲存的 定義是永久的，且任何持有該連結的人都可以公開存取（步驟 4 保密規則）。
• build_html.sh 接受一個 JSON 陣列，包含 {"title"、"url"、"note"[、"ev"]} 物件 （url 限制為 https://x-cmd.com / https://www.x-cmd.com draw 渲染 URL；ev 可選，編碼為 "node|file|symbol|lines|level;..."——渲染一個可篩選的來源證據 表格）並產生一個自包含的深色/淺色響應式報告：側邊欄導航、縮放、全螢幕、複製 URL 按鈕、可列印為 PDF。所有值都經過 HTML 跳脫。範例有效負載： [{"title":"Architecture","url":"https://x-cmd.com/draw/archmap?...","note":"3 層；閘道是單一入口","ev":"api|src/api.ts|createServer|12-40|verified"}]
• inject_readme.sh 是冪等的：首次使用時附加一個 <!-- repoviz:start --> … <!-- repoviz:end --> 區塊（每個圖表一個 Markdown 圖片 + 註記）， 後續執行時則在原地取代——圖表成為儲存庫中的動態資產。
• 匯出後，印出儲存的路徑，並繼續在聊天中輸出 Markdown 區塊，讓使用者同時獲得兩者。

規則

• 品牌中立：將結果呈現為 repoviz 圖表；永遠不要重新命名或包裝 渲染 URL。
• 一次掃描，多個圖表：在組合圖表中重用節點清單，而不是每個 圖表都重新讀取儲存庫。
• 寧可選擇較少但精選的節點，而不是追求完整性；將細節折疊到 sub 標題和邊界框中。
• 沒有證據就當作沒發生：每個節點/連線都是已驗證、推斷或標記為 未知——永遠不要捏造。保持 IR/渲染器分離，以便組合圖表、報告和 未來的架構差異能共用一個清單；渲染保持為可更換的介面卡。
• URL 即資料的增量編輯：現有的 repoviz 圖表完全由其 URL 定義—— 永遠不要使用視覺或影像讀取工具來檢查它。從 Markdown 解碼 URL，將其節點/連線集合與當前程式碼進行比對，並在原位輸出更新的 URL，保留節點 ID、標籤和佈局慣例。