viz 是做什麼的？
一個固定的渲染器 assets/viz.js 負責繪製所有視覺元素。Agent 只需依照文法撰寫資料，因此一個視覺元素的 token 成本約等於它所取代的 ASCII 樹狀圖。作為交換，它可獲得步驟重播、節點檢視器、邊緣追蹤、篩選及路徑複製功能。
選擇視圖
撰寫資料，而非 HTML：一個 == graph 區段（節點、路徑及 view:）或一個圖表區段。根據讀者提出的問題選擇視圖，然後僅閱讀所需的文法：grammar（適用於圖形、樹狀圖與差異圖），charts（適用於 == timing、gantt、hist、retries、causes、board、stock 及 waits）。
流程如何運作？
- 元件間的資料移動（分支、後備、非同步跳躍、失敗出口）→
view: flow，為預設值。「Walk me through」會附加敘述尾（見下方）。為每條邊標記傳遞的內容，並按照發生順序宣告邊緣；數字會自動跟隨。 - 誰執行動作、傳送了什麼、經過了什麼過濾、產生了什麼結果 →
ranks:欄位，每個觸發一條路徑，成功抵達時以=> result結尾，被過濾掉時以=| result結尾。團隊或服務作為帶狀區域 → 加上lane:。 - 服務間的請求隨時間變化 →
view: seq，搭配at:時間（當等待時間很重要時）。當呼叫順序及之間等待時間是重點時選擇 seq 而非 flow；當分支是重點時則選擇 flow。每個服務在每次訊息後的狀態 → 在邊緣下加上sets: id=*charging，在節點下加上state:。 - 某個欄位或任務的生命週期 →
view: states，每個故事一條路徑（!giveup: running > blocked => dead）。使用者導向流程加上起始點（[*] -> form）、語氣標示及group框（views）。 - 誰呼叫誰 →
== tree。某個時刻的呼叫堆疊，包含出錯的值 →view: stack及locals:。
何時發生，持續多久？
- 同時執行的內容：競賽、重疊的工作 →
== timing，每個工作者一條通道，加上!window標記重疊範圍。 - 為何重試堆積：退避、抖動、放棄點、多個客戶端同時請求 →
== retries，加上policy:。 - 請求的延遲分佈在哪裡，以及哪個鏈結限制了它（關鍵路徑、閒置時間）→
== gantt，使用after鏈結長條；budget:繪製限制線，was 140ms在已修改的行上繪製舊的執行結果於其下方。
數量多少？
- 流量如何分割：流量拆分、漏斗、請求在哪裡流失 →
view: sankey，每條路徑下加上weight:，流失的路徑以=| <exit node>結尾。當流量數量是重點時，使用 sankey 而非ranks:。 - 是尾端還是全部（p50 vs p99、延遲迴歸）→
== hist，加上was:表示舊的分佈。 - 隨時間變化的單一數量（對照閾值）：佇列深度、延遲、使用中的資源池），以庫存流量圖呈現 →
== stock，加上meter:頻帶。對於重複的模式，繪製一個典型的時間窗口並說明是哪一個。
為何中斷，卡在哪裡？
- 誰持有哪個鎖，以及誰在等待它（死結）→
== waits；它會自動找出循環。 - 事故的疑似原因，已確認或排除 →
== causes，魚骨圖。 - 跨階段的工作項目（後台填充中的分片、管線中的任務），含 WIP 限制及哪些被阻塞 →
== board，看板。 - 某個檢查讀取了哪些輸入，以及哪些觸發會使其保持新鮮 → 在圖形之後加上
== cover；一個寫入者 × 欄位矩陣 →columns: <rank>。
有什麼改變？
- 對單一佈局的變更 → 在節點及路徑上使用
+和-；讀者可以切換 before | both | after。 - 變更對呼叫樹造成的影響 →
== diff，應由轉換器產生而非手動撰寫。<viz>是此技能的目錄；前兩個參數是基礎版本與目標版本（例如 PR 的基礎分支及HEAD）；<paths>限制掃描範圍：
python3 <viz>/scripts/viz.py calldiff main HEAD --max-depth 4 <paths> # 輸出基礎內容 + == diff，未變更的子樹會被折疊
python3 <viz>/scripts/viz.py calltree --entry submitForm
根據需要附加到任何視圖上：
- 每個步驟的原因 → 在路徑上加上
| payload | narration尾綴；每個步驟都會成為重播步驟。 - 一個逐步引導場景的設計文件 →
theme drawing，在步驟下加上shows: id = text，以及當某個數字決定結果時加上meter:（drawing）。 - 一個將被儲存、列印或分享的頁面 →
theme paper。它會自行繪製頁面，因此內嵌於 T3 的渲染保留預設主題。
所有內容都要有證據支持。每個節點應有一個 @path:line 以及關於讀取、寫入和失敗行為的詳細行。每個數字（持續時間、權重、層級）都應來自追蹤紀錄、日誌、查詢或程式碼。對於任何你尚未閱讀或測量的內容，請以 ? 標記：在節點、路徑、長條或區段前加上 ? 前綴，並在庫存點上加上 # estimate 備註。
顯示它
T3 Code（工具列表中包含 html_render）：直接將頁面寫入 html_preview，檢查其主控台是否有 viz: 解析錯誤，然後將同一頁面傳遞給 html_render。請勿貼上 viz.js。
<!doctype html><script src="https://cdn.jsdelivr.net/gh/Yeshwanthyk/agent-skills@efe8911d3765b764d7f0bf775e395d5201e29b16/skills/viz/assets/viz.js"></script>
<script type="text/viz">
…
</script>
如果預覽主控台顯示腳本載入失敗，請回退到以下頁面（其他任何地方）並將路徑提供給使用者。切勿將 viz.js 內嵌到 T3 渲染中：它每次呼叫約佔 55k tokens。
其他任何地方：將資料儲存到 /tmp/viz/<name>.viz，然後執行 python3 <viz>/scripts/viz.py html /tmp/viz/<name>.viz --open。它會回報解析錯誤，將 /tmp/viz/<name>.html 與渲染器一起內嵌，並在瀏覽器中開啟。在已安裝 glimpse 的 pi 上，改為在該處開啟檔案（pi）。回報路徑。
在需要保持自包含的已儲存頁面中（使用者保留或分享的頁面）：在視圖所屬位置撰寫 text/viz 區塊，在 body 結尾處加上 <script data-viz></script>，然後執行 viz.py inline page.html。更新 viz.js 後重新執行它。為故事說明文字、表格列或字彙條目加上 data-viz-id="<node id or path name>"，滑鼠懸停時會點亮頁面上每個圖形中的該部分，無需頁面腳本。
回覆
視覺元素承載結構。回覆僅加入視覺元素無法顯示的內容：你未曾驗證的事項，以及應首先檢視的一件事。
完成條件
當視覺元素渲染完成且無 viz: 錯誤，每個節點和數字都有依據或標記為 ?，並且你已在讀者會查看的地方（T3 內聯，或已開啟頁面的螢幕截圖）看過它時，即為完成。無頭載入、curl 或乾淨的主控台不等同於看到它；當你無法查看時，請如實說明，而非聲稱已渲染完成。