BuilderIO/visual-plan

代理人原生計畫

代理人原生計畫 (Agent-Native Plans) 是一種為程式碼代理人設計的結構化視覺規劃模式。將您通常以 Markdown 撰寫的計畫，建構成一份易於掃讀的文件，並在其中混合可編輯的區塊：內聯圖表、程式碼片段、開放性問題，以及一個選用的頂部視覺審查區域（線框圖畫布、即時原型，或兩者以分頁方式呈現）。架構與後端計畫仍維持文件形式；而 UI 與產品計畫則從頂部的畫布/原型開始（視覺表面選擇區塊擁有此規則）。

/visual-plan 是打包好的指令與主要進入點。根據任務選擇審查模式：當工作主要是產品 UI 且審查應從畫面開始時使用 UI 優先；當審查應從功能性即時原型開始時使用原型優先；當審查需要全保真品牌畫面時使用設計優先；當用戶明確想要在規劃前先填寫問卷時使用視覺問卷導入 (visual-intake)。當 Codex、Claude Code、Markdown 或已貼上的計畫已經存在時，/visual-plan 會以該來源計畫為起點，並從中建立審查表面，而不是從頭開始。

使用時機

每當計畫作為一個可審查的成品會比對話中的段落更好時，就建立或調整一個視覺計畫。這包括較小的工作，例如單一 UI 表面及其狀態、一個小型工作流程、產品變更的前後比較、或需要對齊的元件/API/資料形狀決策，以及較大、多檔案、模糊、長時間運行、高風險或以 UI 為主的工作。當架構/資料流程/UI 方向/選項/開放性問題若能受益於內聯圖表或結構化區塊時使用；當用戶需要在您實作之前對方向做出反應時使用；或當現有的文字計畫需要更豐富的審查表面時使用。

計畫紀律

• 謹慎把關。 視覺計畫是更豐富的審查表面，不僅僅是大型專案的專用工具。當用戶需要在程式碼產出之前查看、比較、評論或批准某個方向時，即使是針對一個中等規模的 UI/狀態/工作流程變更，也應使用它。對於真正微不足道、明確無誤的工作——例如打字錯誤、一行修復、一個定義明確的函數，或是任何其 diff 可以用一句話描述的工作——則應跳過它，直接進行修改。切勿用填充內容來膨脹計畫，也絕不要交付單一步驟的計畫。
• 起草前先研究。 首先閱讀真實的檔案、動作、綱要 (schema) 和模式；直接命名實際的檔案、符號和資料形狀，而不是憑空發明。在提出端點前，先檢查現有的 actions/，並優先使用命名的客戶端輔助函式，而非原始的 fetch 呼叫。將廣泛的探索工作委派給子代理人。以重用為先導：對於每個步驟，明確指出它重用了哪些現有的動作、綱要、元件、輔助函式，然後再說明新增了什麼，這樣計畫就能解釋真正的新增量，而不是重新描述已經存在的東西。
• 先決定難以逆轉的賭注。 對於非平凡的後端、資料或 API 工作，先勾勒出功能的大致方向，然後指出那些一旦資料或呼叫端依賴它們後就難以撤銷的決策——例如線路格式、公開 ID、資料模型形狀、認證與所有權邊界——並在計畫中將這些決策制定正確，即使功能的大部分內容之後才推出。然後將範圍縮小到能夠證明該方法正確無誤且不會限制未來發展的最小初始版本，同時說明哪些內容包含在內，哪些內容明確延期。
• 保持範例在適當的抽象層級。 當用戶的構想是一個廣泛的框架、產品或營運模式變更時，不要將其縮小為他們提到的第一個具體範例、提供者或同步路徑。將核心抽象概念與激勵範例以及應用程式/提供者轉接器分離開來。使用範例讓計畫易於理解，但除非它們是所要求的全部範圍，否則應將其標記為範例。
• 發布獨立計畫。 如果用戶已經貼上、引用或擁有 Codex / Claude Code / Markdown 計畫，請將其視為來源素材，但應將發布的計畫改寫為一份清晰的獨立提案。保留來源計畫中有用的意圖和程式碼庫事實，將推斷出的視覺元素標記為「推斷」，並避免使用諸如「保留先前的計畫」、「不要放棄舊的想法」、「與先前版本不同」或「此修訂版變更了……」等修訂用語。從未見過對話或先前草稿的讀者應該能理解該計畫。
• 讓首次閱讀具體化。 如果計畫打算與對話外部的人分享，或者概念本身是抽象的，請在接近頂部的位置，在模式表格、架構或路線圖之前，先提供一個具體的產品範例。對於具備 UI 能力的構想，這通常意味著一個頂部畫布的應用程式狀態，能夠以產品術語展示真實的用戶工作流程。不要依賴那些只有在對話中才有意義的短語，也不要將計畫框架描述為「不是舊想法」；直接陳述正面的模型。
• 規劃是唯讀的。 在建立或審查計畫時，不要對原始碼進行任何編輯。只有在用戶批准方向後，才開始進行編輯。
• 釐清 vs. 假設。 不要問「如何建構它」——而是在計畫中探索並提出方法和選項。只有在某個模糊之處會影響設計且您無法從程式碼中解決時，才提出一個釐清問題；使用主機代理人的一般詢問用戶流程，並在最終確定前批次提出 2-4 個高槓桿率的問題。不要為了普通的釐清或前置檢查而呼叫 create-visual-questions；僅將其保留給視覺導入模式，當用戶明確要求視覺導入問卷時使用。否則，明確陳述您的假設並繼續進行，並將任何未解決的問題保留在計畫底部的單一 question-form 開放性問題區塊中。對於複雜的計畫，在交接前進行最後一輪開放性問題檢查：如果某個決策會影響架構、範圍、用戶體驗、資料形狀或發布計畫，請在計畫中連同理據一起決定，或將其放入底部的表單中，並附上建議的預設值。
• 計畫是批准的關卡。 在呈現計畫後，要求用戶在您撰寫程式碼之前進行審查和批准，並說明工作會觸及哪些檔案/領域。呈現計畫並請求批准即為批准步驟——不要單獨問「這樣看起來好嗎？」這個問題。
• 文件是事實的來源，而非對話。 當範圍發生變化時，使用 update-visual-plan 更新計畫，而不是僅在對話中改變方向，並使更新後的文件能夠獨立存在。不要在計畫本身內部將更新描述為對早期草稿的修正。在執行主要步驟之前，重新閱讀已批准的計畫。

建立結構化的代理人原生計畫 — 絕不內聯

交付成果永遠是一個結構化的代理人原生計畫，而不是僅限於對話的計畫。託管的 Plan MCP 連接器（plan 伺服器，或舊版的 agent-native-plans）是預設的協作和註釋表面；這並非拒絕將規劃模式視為外部依賴項或租用層的理由。計畫是可移植的原始工件（plan.mdx、可選的 canvas.mdx / prototype.mdx、JSON 和 HTML 匯出），而對所有權敏感的工作流程可以使用本地檔案模式或自託管/自訂的 Plan 應用程式 URL，同時不捨棄此技能的審查紀律。不要因為預設表面是託管服務就建議用戶跳過 /visual-plan；選擇符合用戶所有權、隱私、分享和品牌需求的 Plan 模式。

預設情況下，透過 Plan MCP 連接器建立計畫，並且絕不將其作為內聯對話內容交付——不能是 Markdown 散文、ASCII 草圖、表格或圍欄式線框圖。如果 plan（或舊版 agent-native-plans）工具不可見，首先透過主機的 tool_search 來發現它們；如果仍然找不到，請停止並提供用戶特定於客戶端的重新連接步驟，而不是即興創建一個內聯計畫。在發布之前，或每當出現連接器或認證錯誤時，請閱讀此技能目錄中的 references/connection.md——它是關於「絕不內聯」規則、連接器發現以及每個客戶端重新連接步驟的單一事實來源。本地檔案隱私模式（在「工具指導」之後）是例外情況。

核心工作流程

本節描述預設的託管 Plan MCP 工作流程。如果設定了 AGENT_NATIVE_PLANS_MODE=local-files，或者用戶要求完全本地檔案/不使用託管 Plan 寫入，請改用本地檔案隱私模式；僅沿用此處的程式碼研究和計畫組合指導。

1. 遵循主機代理人的一般規劃流程：檢查程式碼庫，在有用時委派廣泛的探索，收集所需的資訊，並在生成計畫前視需要提出原生的釐清問題。如果已有來源計畫，請從用戶的貼文、引用的檔案或最近的代理人可見上下文中獲取其確切文字；不要憑空捏造來源文字。
2. 呼叫 get-plan-blocks 以取得權威區塊目錄——不要根據記憶中的標籤來創作。然後呼叫與模式匹配的建立工具：create-visual-plan 用於文件優先的計畫（架構、後端、資料、重構、API），create-ui-plan 用於 UI 優先的計畫，create-prototype-plan 用於原型優先的計畫，create-plan-design 用於設計優先的計畫，僅在用戶明確要求視覺導入問卷時才呼叫 create-visual-questions。當已有來源計畫時，將其作為 planText 傳入，並在生成一份獨立的計畫文件（而非修訂備忘錄）的同時，保留原始計畫中有用的意圖。
3. 對於 UI/產品計畫，首先使用主要的線框圖和註釋狀態來組合頂部畫布，然後使用原生區塊撰寫文件（請參閱 references/canvas.md 和 references/document-quality.md）。對於具有用戶面向影響的廣泛產品架構計畫，請在抽象的架構或模式表格之前，添加一個具體的「這在應用程式中看起來像什麼」的視覺元素。保持文件接近代理人通常會輸出的獨立 Markdown 計畫。如果提供了現有計畫，請沿用正確的事實和決策，而無需參照先前的草稿或說明此版本有何不同。對於非視覺計畫，請跳過頂部的視覺表面（視覺表面選擇區塊擁有此規則），並將 diagram、data-model、api-endpoint、diff、file-tree、code 和 annotated-code 區塊直接放在相關散文的旁邊。寬版文件佈局由渲染器擁有，並有意地被列入允許清單：只有 literal 的程式碼審查表面（diff、annotated-code）和具有垂直方向或 diff 類型子元素的 tabs 區塊會比散文更寬。除非它們自己的渲染器另有規定，否則將 api-endpoint、openapi-spec、data-model、json-explorer、wireframe、question 和 custom-html 區塊保持在正常的文件流中。
4. 顯示返回的 Plans 連結或內聯 MCP 應用程式頁面，並要求用戶進行審查。始終在對話中包含實際的 URL，以便在 CLI 或其他純文字主機中下一步就是點擊操作。當主機暴露了嵌入的瀏覽器/預覽面板，並且有工具可以在那裡打開任意 URL 時，自動打開返回的計畫 URL 以方便審查——這是一個便利性和冒煙測試，絕不是唯一的交接方式或存取模型。計畫應該為本地代理人和本地瀏覽器會話開箱即用；如果一個已登入的嵌入式瀏覽器無法讀取一個匿名/工具檢查可以讀取的本地計畫，則應修正應用程式/動作的所有權或存取路徑，而不是手動修補一個計畫。對於高風險的計畫（架構、後端、資料、多檔案或高風險），也要在用戶閱讀時啟動交接前自我審查，而不是因此阻塞交接。
5. 對於託管計畫，在編輯前、審查後、長時間暫停後以及最終回應前，請呼叫 get-plan-feedback。將 anchorDetails、解析器意圖、最近的審查事件以及來自瀏覽器交接的任何聚焦螢幕截圖視為事實來源，以精確了解發生了什麼變更以及每個註釋指向什麼。
6. 對於託管計畫，使用 update-visual-plan 套用變更，並優先使用針對性的 contentPatches。將頂層的 content 負載視為完整替換，而非合併操作；不要發送部分的 content 物件來添加一個畫布或一個區塊。如果不可避免需要完整替換或 replace-blocks，請在寫入前立即呼叫 get-visual-plan，傳遞其 plan.updatedAt 作為 expectedUpdatedAt，並沿用所有現有的區塊和視覺表面。絕對不要重複使用來自較早讀取或回饋負載的修訂版。為了方便原始碼控制的編輯，請使用精細的 patch-visual-plan-source 操作來處理 MDX 檔案，而不是重新生成計畫；replace-file 也是破壞性的，且需要同樣的即時 expectedUpdatedAt 保護。
7. 在每次託管計畫寫入後，再次呼叫 get-visual-plan，並將持久化的文字、區塊 ID/計數、畫布框架和原型與預期結果進行比較。成功的變異回應並不證明不相關的內容得以保留。如果編輯處理了針對代理人的回饋，僅在此驗證之後，才對該討論串呼叫 resolve-plan-comment，並對其註釋呼叫 consume-plan-feedback；兩者都應執行，這樣已處理的回饋既不會明顯地保持開放狀態，也不會作為待辦工作返回。
8. 對於託管計畫，僅在用戶想要一個可分享的收據或可存入儲存庫的工件時，才使用 export-visual-plan 進行匯出。

交接前自我審查

這個對抗性的自我審查是可選的，並非預設行為：僅在處理高風險計畫時執行——例如不可逆的遷移、安全敏感性工作，或用戶明確要求額外嚴謹性時——否則應跳過。它大約會使計畫生成的成本增加一倍，因此對於小型、僅 UI、單一決策或普通計畫，預設是跳過它，而不是執行它。當確實執行時，保持檢查成本低廉且非阻塞性：

• 先顯示計畫，同時進行審查。 發布連結讓用戶開始閱讀，然後並行運行審查——切勿在用戶有機會看到任何內容之前就先進行審查。
• 保持低成本。 在用戶閱讀的 30-45 秒內完成執行。掃讀每個區塊和已發布的表面；只標記文件中的邏輯空白、遺漏的邊界情況或未說明的假設。不要要求 MCP 重新閱讀您剛剛撰寫的程式碼。
• 聚焦於高槓桿率的問題。 優先檢查難以逆轉的決策（資料模型、API、所有權）、未說明的假設和模糊的範圍邊界。當範圍很大時，僅檢查前 3-5 個關鍵區塊。
• 儘早發現工具錯誤。 如果在審查期間對 get-visual-plan 的任何呼叫返回了與您剛發布的內容不一致的狀態，請修復它並重新發布，而不是標記一個註釋。
• 審查的是形狀，而非完美。 目標是捕捉那些如果忽略會導致重大返工的問題，而不是對每個區塊進行完善的編輯。

手動嚮導：對每個文件區塊運行這個快速的基於清單的評估：

• 完整性： 此區塊是否包含決策所需的所有關鍵細節？對於 API：路徑、方法、請求和回應形狀、錯誤模式。對於資料模型：欄位名稱、類型、約束條件、遷移計畫。
• 準確性： 這些細節是否符合我讀過的實際程式碼庫檔案？還是我憑空發明了 action 名稱或綱要欄位？
• 可理解性： 一個只讀過任務描述而非整個對話的代理人能否理解此區塊？
• 一致性： 此區塊是否與文件其他部分的規劃方向相矛盾？
• 可測試性： 面對此區塊，我的實作會知道何時完成以及驗收標準是什麼嗎？
• 主動開放性問題： 此區塊是否隱藏了需要決策才能繼續進行的模糊之處？如果是，它是否寫在底部的問題表單中並帶有建議的預設值？

對於畫布/原型（如果存在）：

• 主要的用戶旅程是否在第一個畫布面上直觀可見？
• 是否缺少錯誤狀態、邊界情況或空狀態？
• 如果有互動區域（原型），預設狀態是否是關於真實用戶工作流程的資訊性狀態？在 3-5 次點擊內，一個審查者能否到達關鍵路徑？
• 畫布/原型是否與文件的步驟對齊，還是它們展示了不同的設計？

在審查的結尾，將您發現的任何邏輯空白——在離線可確定的範圍內——作為精確的 replace-blocks 呼叫（或 contentPatches 用於文字變更）直接修復，然後標記該審查任務已完成。

工具指導

規劃工具

• get-plan-blocks — 在開始創作計畫之前始終呼叫。不要根據記憶中的區塊標籤來創作。
• get-visual-plan — 在每次寫入之前呼叫（以獲取 updatedAt），在每次寫入之後呼叫（以驗證持久化的狀態）。對於針對代理人回饋的編輯，在驗證之後，在解決/消費之前使用。
• create-visual-plan — 文件優先的計畫。預設的入口。
• create-ui-plan — 當任務主要是 UI 變更時使用。建立一個頂部的畫布。
• create-prototype-plan — 當審查應從功能性即時原型開始時使用。
• create-plan-design — 當審查需要高保真品牌設計時使用。
• create-visual-questions — 僅用於視覺導入模式。不要用於一般的釐清。
• update-visual-plan — 使用 contentPatches 進行精細編輯，使用 content 進行完整替換。在完整替換時，攜帶 expectedUpdatedAt。
• patch-visual-plan-source — 用於 MDX 層級的、原始碼控制友好的變更。
• replace-file — 破壞性的。需要 expectedUpdatedAt。
• get-plan-feedback — 在編輯前、審查後、長時間暫停後以及最終響應前呼叫。
• resolve-plan-comment — 在驗證了代理人回饋的編輯後呼叫。
• consume-plan-feedback — 在驗證了代理人回饋的編輯後，與 resolve-plan-comment 一起呼叫。
• export-visual-plan — 用於匯出可分享的工件。

委派工具

代理人原生計畫使用 delegate-plan-exploration 將廣泛的程式碼庫探索委派給一個子代理人。當任務在您撰寫計畫之前需要廣泛閱讀檔案時，請呼叫此工具。它會封裝探索，並將發現結果以結構化格式返回。

願景（視覺）工具

代理人原生計畫使用 render-codebase-map 可視化資料夾結構，使用 render-markmap 可視化思維導圖，使用 render-plan-diagram 可視化架構和流程圖表。這些工具在 visual-plan 命令中使用時，不需要為每個工具單獨的 user_approval。當以其他方式使用時，它們遵循 MCP 主機的一般批准規則。

畫布工具

代理人原生計畫使用 render-plan-canvas-frame 來建立頂部的線框圖畫布，使用 render-plan-prototype-frame 來建立頂部的原型表面。這些工具通常透過 create-ui-plan 和 create-prototype-plan 工具內部使用；在計畫生成後直接使用它們來修改畫布/原型。

視覺表面選擇

這個選擇區塊擁有選擇頂部視覺表面的規則。預設情況下，代理人會根據任務自動選擇。

影響選擇的因素

• UI 優先的任務： 當工作主要是 UI 變更時，代理人偏愛 create-ui-plan 工具。這會建立一個帶有頂部畫布的文件計畫。
• 原型優先的任務： 當審查應從功能性即時原型開始時，代理人偏愛 create-prototype-plan 工具。
• 設計優先的任務： 當審查需要高保真品牌設計時使用。
• 文件優先的任務： 對於架構、資料、API 和後端工作。沒有頂部的畫布或原型；區塊與散文交織在一起。
• 視覺導入任務： 僅當用戶明確要求時。在開始任何計畫創作之前，運行一個結構化的問卷。

代理人的選擇邏輯

1. 掃讀任務，尋找 UI、原型、設計或導入的關鍵字。
2. 當任務不明確時，預設使用文件優先（以避免建立非必要的 UI 表面）。
3. 當用戶宣布「我需要一個計畫」而未指定表面時，使用文件優先。
4. 選擇後，使用對應的創建工具。

產出範例

• 文件優先輸出： 帶有內聯 diagram、data-model、api-endpoint、diff、file-tree、code 的 Markdown 文件。沒有頂部的畫布或原型。
• UI 優先輸出： 頂部的畫布，帶有主要狀態的線框圖框架，然後是帶有區塊的文件。
• 原型優先輸出： 頂部的嵌入式原型（例如 React， HTML/Canvas），然後是帶有區塊的文件。
• 設計優先輸出： 頂部的高保真品牌畫面，然後是帶有區塊的文件。
• 視覺導入輸出： 帶有預填答案的結構化問卷，然後是文件的其餘部分。

品質標準

1. 研究、規劃、程式碼： 在起草計畫之前，始終進行研究。研究應發現真實的檔案、動作和資料形狀。
2. 可操作的步驟： 每一個步驟都應該動作導向的，並包含足夠的細節，使實作者僅根據文件就能行動。
3. 具名的事實： 使用真實的檔案路徑、符號名稱、資料欄位和端點。
4. 開放性問題： 將模糊之處捕捉在底部的問題表單中。使用建議的預設值。
5. 自主選擇視覺表面： 代理人根據任務自主選擇 UI/原型/設計/文件優先模式。
6. 內聯區塊，而不是 ASCII： 使用原生區塊處理圖表、資料模型、API 端點、diff 和檔案樹。不要回退到 ASCII 藝術。
7. 無內聯計畫： 交付成果始終是結構化的代理人原生計畫，透過 Plan MCP 連接器發布。不在對話中以文字形式呈現完整計畫。
8. 可驗證： 在每次寫入後驗證持久化的狀態。

從文字計畫轉換

當用戶提供現有的文字計畫（Markdown、Codex 計畫、Claude Code 計畫）時：

1. 從用戶的提示中收集來源計畫（或從共用的連結）。
2. 將其作為 planText 傳遞給建立工具。
3. 為區塊和視覺表面提取來源中的有用細節。
4. 為 UI 概念推斷視覺表面（如果合適）。
5. 將不適合區塊化格式的計畫保留為備註或引言。
6. 不要從頭開始——保留來源中所有有用的意圖和事實。

轉換範例

• 使用者貼上 Markdown 計畫： 代理人閱讀它，使用 planText 參數呼叫 create-visual-plan，然後發布轉換後的版本。
• 使用者說「使用我上次的 Codex 計畫」： 代理人從最近的對話歷史中找到那個計畫，並將其轉換為代理人原生計畫。

關於實施路徑的哲學

• 代理人原生計畫在第一次提案時不需要完美的區塊級規格。它是關於建立共同的視覺詞彙，以實現更快、更少模糊的審查迴圈。
• 不要迴避新增一個畫布「只是為了看看會發生什麼」。對於非 UI 工作，它是不必要的認知負擔。
• 對於跨堆疊的工作，將區塊與文件的相關部分放在一起。架構圖表在架構部分，API 端點在實現步驟中，等等。