BuilderIO/visual-recap

視覺摘要

/visual-recap 從差異（diff）建立視覺計劃，而非為未來變更做規劃。 它與前瞻規劃相反：不是描述你即將進行的變更，而是以比逐行審查 更高的抽象層次，描述剛剛完成的變更。相同的計劃資料模型 同時支援兩個方向——結構描述、API、檔案與架構變更，會變成 與前瞻計劃相同的 data-model、api-endpoint、file-tree 與 diagram 區塊，只是現在它們總結的是已存在的成果。審查者可以先掃描變更的輪廓， 再花注意力在逐行程式碼上。

以代理原生計劃形式發佈——絕不內聯

最終產出一律是已發佈的代理原生計劃，透過 Plan MCP 連接器上的 create-visual-recap 建立——絕不是內聯聊天內容（不是 Markdown 散文、 ASCII 草圖、表格、圍欄式「線框圖」或「以下是摘要」）。摘要的 全部價值在於託管、可互動、可註解的計劃；內聯摘要不是退化的摘要， 而是摘要所要取代的事物。如果看不到 plan（或舊版 agent-native-plans） 工具，請先透過主機的 tool_search 發現它們；如果仍然找不到，請停止並 提供使用者特定客戶端的重新連線步驟，而不是臨時拼湊一個內聯摘要。 在發佈之前，或每當出現連接器或驗證錯誤時，請閱讀此技能目錄中的 references/connection.md——這是「絕不內聯」規則、連接器發現與 各客戶端重新連線步驟的唯一真相來源。本機檔案隱私模式（如下）是唯一的例外。

本機檔案隱私模式——請閱讀 references/local-files.md

當使用者不希望寫入託管的計劃資料庫——不寫入資料庫、不發佈 Plan MCP、 完全本機/離線/私密摘要，或是 AGENT_NATIVE_PLANS_MODE=local-files ——時，除了僅用於結構描述查詢的 get-plan-blocks 目錄查詢外， 請不要呼叫任何託管的計劃工具。使用本機的 recap collect-diff / scan / build-prompt --local-files 輔助工具讀取差異，建立一個本機的 MDX 資料夾 （設定 kind: "recap" 與 localOnly: true），然後使用 plan local check、 plan local serve --kind recap 與 plan local verify --kind recap 預覽它。 在使用本機檔案模式之前，請閱讀此技能目錄中的 references/local-files.md ——這是完整合約的唯一真相來源。

何時使用

當 PR 或提交規模較大、涉及多個檔案，或影響結構描述、API 合約 或架構，而審查者會因在閱讀原始差異前看到變更被映射為結構化區塊 而受益時，請建立摘要。GitHub Action 可以從 PR 差異自動產生； 代理程式也可以根據要求產生（「摘要此 PR」、「顯示此分支變更了什麼」）。 對於小型、單一檔案或顯而易見的差異，請跳過——摘要是審查的額外開銷， 而微小的變更以普通差異形式審查更快。

摘要整個工作單元

當 /visual-recap 在工作完成後於聊天線程中被呼叫時，預設範圍是 整個目前的工作單元/線程，而不僅是最新的使用者訊息、工具動作或 後續修正。收集整個對話中線程所屬的變更：原始實作工作、後來的錯誤修正、 UI 後續調整、測試、變更集、技能/指令更新、產生的計劃/原始碼成品， 以及使摘要能開啟所需的任何本機匯入/連結修正。

使用目前的差異加上對話上下文，將線程所屬的變更與線程前就已存在的 不相關髒工作分開。排除不相關的既有編輯。如果範圍確實含糊不清 且無法推斷，請陳述假設或提出簡潔的問題，然後再發佈。

在收到回饋後更新既有摘要時，請修改摘要，使其仍然涵蓋整個線程/工作單元 加上新的修正。除非使用者明確要求較窄的範圍，否則不要以僅涵蓋最新回饋的 窄化摘要來取代廣泛的摘要。

保持摘要主體精簡

請勿在產生的計劃主體中加入樣板化的引言、免責聲明、來源說明或摘要 散文區塊。特別注意，不要為了說明摘要是輔助工具、審查者仍應審查差異、 多少檔案變更、或哪個參照/工作目錄產生了摘要，而建立一個 rich-text 區塊。計劃標題、簡短說明與 file-tree（其中包含每個檔案的變更統計） 已經承載了這些上下文。

只有在散文區塊能告訴審查者一些結構化區塊無法提供的具體變更資訊時， 才加入：目標、真正的相容性風險、差異中可見的重要決策，或是有根據的 審查備註。

摘要必須有實質內容

精簡不等於單薄。摘要不是單一線框圖加上一句話——那樣對審查者的幫助 不足，正如樣板化散文會過度幫助他們。除了視覺/結構焦點（線框圖、 data-model、api-endpoint、diagram）之外，一份有實質內容的摘要 也攜帶了實作證據：

• 在製作前進行簡短的表層/狀態盤點：列出差異中可見的已變更路由、 元件、彈出視窗/對話框、角色/存取狀態、空狀態/錯誤狀態，以及 共享抽象。最終摘要必須以區塊表示每個有意義的項目，或是有意 省略它，因為它太小、重複，或非使用者可見。
• 一個已變更檔案的 file-tree，每個條目附帶 change 標記， 讓審查者一眼就能看到工作的影響範圍。
• 關鍵已變更檔案的 diff 分割視圖，歸類在一個 ## Key changes rich-text 標題下，放在單一水平 tabs 區塊中（預設方向， 每個分頁一個檔案），每個檔案附帶一行 summary 與一些 annotations ——讓審查者可以從高空輪廓直接下降到承載程式碼。使用水平檔案分頁， 而不是垂直側欄，讓選取的檔案有足夠的寬度顯示並排差異。

只有在變更確實極小，以普通差異形式審查更快時，才跳過差異附錄 （請參閱「何時使用」）；對於任何值得摘要的變更，檔案樹與關鍵變更差異 都應納入計劃中。

標準樣式與預算

一份強而有力的摘要遵循從上到下的單一架構：

1. UI 影響焦點——當差異變更了渲染的 UI 時，先放線框圖。
2. 簡短的結果敘述（rich-text）：變更了什麼以及為什麼，1-3 段落。
3. 結構描述與合約變更的 data-model / api-endpoint 區塊。
4. 已變更檔案的 file-tree，附帶 change 標記。
5. ## Key changes——一個包含 diff / annotated-code 的水平 tabs 區塊。

保持摘要易於審查的預算：

• 3-8 個關鍵變更分頁。在大型變更中少於 3 個分頁會對審查者幫助不足； 超過 8 個分頁就不再是摘要。
• 保持每個 diff/annotated-code 摘錄的重點——每個分頁偏好約 150 行以下； 將長檔案的其餘部分總結或連結，而不是傾倒出來。
• 標題最多約 70 個字元；簡短說明 1-3 句。

這些預算同時也是成本上限：不要以詳盡為名超過它們，也不要在初始 循序掃描後重新讀取完整的差異——從那次掃描中記錄的筆記開始工作。

好示例。 一個 25 個檔案的驗證變更：登入介面的之前/之後線框圖、 兩個段落的敘述、感知差異的 sessions 表格 data-model、新 refresh 路由的 api-endpoint、附帶變更標記的 file-tree，以及 ## Key changes 與 五個重點分頁，每個分頁有一行 summary 與一些關於承載區塊的註解。

壞示例。 一個巨大、未分段、沒有摘要或註解的差異傾倒；或是 一個稀疏的三區塊摘要（一個線框圖、一句話、一個檔案列表）， 迫使審查者無論如何還是得回到原始差異。

UI 影響需要線框圖

當差異變更了渲染的 UI、版面配置、密度、視覺狀態、互動功能、 導覽、控制項、選單、對話框或設計代碼時，摘要必須包含一個或 多個線框圖。散文與檔案差異不能替代顯示視覺上的變更。

在選擇線框圖之前，請從差異進行 UI 覆蓋檢查：

• 找出變更出現的進入表面，例如頁面標題、列表列、工具列、路由殼層 或選單觸發器。
• 找出開啟或變更的互動表面，例如彈出視窗、對話框、分頁、工作表、 下拉式選單、內聯編輯器或提示訊息。
• 找出結果的目標或持續狀態，例如公開頁面、唯讀檢視、空狀態、錯誤狀態、 載入狀態、權限被拒狀態或已儲存/已共享狀態。
• 當權限變更時，找出存取或角色變體。擁有者/管理員/編輯者與 檢視者/非管理員的差異是視覺行為，需要緊湊的矩陣、配對線框圖， 或清楚標示的狀態序列。

對於 UI 密集的 PR，單一進入表面的之前/之後是不夠的。顯示變更的 進入點、主要的變更互動表面，以及結果/目標狀態。當差異加入了分頁、 角色基礎控制項、公開/私人可見性、邀請/管理流程、破壞性控制項， 或空/錯誤分支時，加入更多狀態。

選擇讓審查最清晰的最小視覺表面：

• 當審查者從直接比較中受益時，使用 Before / After 線框圖配對， 例如已移除或新增的控制項、已變更的狀態、版面配置密度、排序、 導覽，或可見的元件替換。references/wireframe.md 負責如何佈局 該配對（按幾何形狀決定欄 vs. 垂直堆疊）。
• 當變更純粹是新增，或「之前」狀態只會顯示缺失而不增加審查價值時， 僅使用之後的線框圖。
• 當 UI 變更與流程相關、響應式或具有狀態性時，使用超過兩個線框圖； 依序顯示有意義的狀態，而不是強迫使用單一之前/之後配對。
• 對於較小的表面，如選單、彈出視窗、對話框、提示訊息或面板， 使用相符的 surface（popover、panel 等）並顯示焦點的子表面。 除非在頁面中的位置本身就是變更的一部分，否則不要重新繪製完整頁面。

將每個線框圖根植於已變更的 UI 行為、元件名稱、檔案路徑，以及 差異可見的標籤/狀態。如果確切像素是推斷而非捕捉的，請在線框圖的 標題或簡潔的註解中說明。對於本機/手動摘要，匯入或更新包含線框圖的 計劃來源，使渲染的摘要能在開啟時提供 UI 視覺。

線框圖品質——請閱讀 references/wireframe.md

UI 摘要/計劃線框圖必須達到嚴格的品質標準——全寬 Chrome、固定在底部的 工具列、真實的產品內容、之前/之後的可比較性、正確的 surface 預設集、 使用 --wf-* 代碼而非十六進位色碼，且沒有 <html>/<style>/字型標籤。 在製作任何線框圖 / <Screen> / WireframeBlock 之前，請閱讀此技能 目錄中的 references/wireframe.md——這是 HTML 線框圖品質的唯一真相來源， 並與 /visual-plan 和 /visual-recap 逐字共用。不要憑記憶製作線框圖。

使用標準的 WireframeBlock / <Screen> 格式，讓計劃檢視器擁有表面框架、 主題與草稿/乾淨切換。當放置精確度重要時，尤其是彈出視窗、選單、 對話框與密集表單，HTML 線框圖是合適的。對於 HTML 線框圖，保持 renderMode 未設定或為 wireframe，除非明確需要僅限設計的可編輯 模型，因為 renderMode="design" 會停用草稿粗糙疊加層。

當瀏覽器工具可用時，在計劃檢視器中渲染 UI 影響摘要，並在共享前 以目前主題視覺檢查。如果任何標籤、註解、工具列或線框圖內容與其他 元素重疊，請修正 MDX 並在回報連結前重新匯入。將此限制為一次渲染與 檢查，加上最多一次修正與重新渲染；除非使用者明確要求，否則不要 繼續迭代超過這個次數。文字匹配的螢幕截圖是不夠的；請視覺檢查 捕捉的圖像。當沒有瀏覽器可用時（例如無頭 CI 代理），請在摘要交接中 說明。

頂部畫布摘要——請閱讀 ../visual-plan/references/canvas.md

當摘要包含頂部畫布、故事板或流程檢視時，請在製作 canvas.mdx 前閱讀 ../visual-plan/references/canvas.md。摘要畫布工作板必須使用與良好的 文件主體線框圖相同的 HTML 線框圖路徑：使用 <Screen surface="..." html={...} /> 與語意 HTML 片段。不要在畫布 <Screen> 標籤內製作全新的 kit-tree 子元件 （如 <FrameScreen>、<Card>、<Row>、<Title> 或 <Btn>）。 這些元件是舊計劃的相容性標記；在新的畫布故事板中，即使內聯主體線框圖 看起來不錯，它們也可能產生擁擠或重疊的版面配置。如果畫布模型看起來 比摺線以下的同一螢幕更差，請假設它使用了舊的 kit 路徑，並以 HTML 螢幕 取代它。

開啟並回報摘要

在本機檔案隱私模式中，先執行 plan local check，然後從 npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open 或從 <plan-dir>/.plan-url 回報本機橋接 URL。它會開啟託管的計劃 UI， 但從此機器的本機橋接讀取，因此不可跨機器共享。如果 Plan 應用程式本身 也在本機以相同的 PLAN_LOCAL_DIR 執行，則 /local-plans/<slug> 路由 也是有效的。請不要發明託管的資料庫 URL，也不要為了取得絕對的 Plan 連結 而發佈。

在建立摘要後，使用實際持有計劃的資料庫之來源的絕對 URL 連結 審查者到渲染的計劃。該來源就是你剛剛建立摘要的 Plan MCP 伺服器—— 而不是你碰巧知道正在執行的任何開發伺服器。建立工具會回傳正確的連結； 請回報那個。絕對不要將主要連結設為本機 plan.mdx 檔案、本機鏡像資料夾 或相對路徑（如 /plans/<id>）。

當摘要張貼到私人儲存庫的 PR 時，計劃連結必須使用私人訪問令牌（PAT） 或計劃檢視器內建的 PR 權杖驗證。如果管理員啟用了 PR 權杖驗證， 則嵌入在 <pr-url>/plans/<plan-id> 中的計劃權杖會自動對該 PR 的 預設通道授權。如果沒有 PR 權杖驗證，則建立者必須在摘要 URL 中附加 一個 ?token= 查詢參數，內含來自專案設定、技能環境變數或 PLAN_ACCESS_TOKEN 環境變數的 PAT。

結構化資料轉換：語意區塊優於傾倒

不要將 JSON 結構傾倒為 data-model，也不要將 OpenAPI 規格傾倒為 api-endpoint。差異感知區塊是為了摘要而設計的：它們會突出顯示 已變更的欄位、已移除的邊界案例，以及已遷移的屬性。

• 選擇性地包含區塊。選擇感知差異的欄位子集來顯示：已新增的欄位、 已重新命名的欄位、型別變更，以及重要的邊界案例移除。結構描述中 未變更的區段是噪音，不是訊號。
• 當 API 規格傾倒會比精選的摘要提供更多位元時，使用它作為 diff / annotated-code 分頁在 ## Key changes 區塊中。
• 將相關的結構描述集合包裝在 ## Schema changes 或 ## API contract changes 的 rich-text 標題下，以視覺上將它們分組。
• 當一組 data-model 或 api-endpoint 區塊有太多文字時， 使用 concise: true。

為什麼

逐行差異是非線性的——它們在概念上不相關的行之間跳動。視覺摘要 將這些行重新組織為模式：這個表格變更了（data-model），這個路由 變更了（api-endpoint），這些檔案變更了（file-tree）， 並且有（n）個承載的變更需要特別關注（diff < tabs）。 它還加入了一件事，是逐行差異無法做到的：說明了為什麼， 以 rich-text 敘述數學家稱之為潛在原因的方式——圍繞程式碼的 推理，模式匹配到計畫的形狀。

社交基礎設施：以視覺摘要開始審查，會灌輸閱讀計劃的習慣。 當每位工程師都習慣於由高層次形狀主導的審查時，開始規劃變更 （/visual-plan）會變得非常自然——審查者已經看到了藍圖的 相同形狀。他們只需要從回顧模式切換到前瞻模式。

發佈摘要

/visual-recap 是 /visual-plan 在時間上的鏡像。兩者共用相同的 標準區塊詞彙表、相同的 plan 工具、相同的「絕不內聯」規則， 以及相同的知覺經濟：形狀先於行。

有關發佈的詳細規範，請參閱 references/connection.md。