程式碼可視化編輯架構：AST插樁與狀態對齊實踐

在構建由 AI 驅動的商業建站系統時，我們面臨一個核心矛盾：Coding Agent 需要純粹的程式碼環境來發揮其生成複雜佈局與交互的潛力，但真實業務的商家使用者期望的卻是所見即所得（WYSIWYG）的可視化編輯體驗。他們希望在畫布上直接點選修改文字、替換圖片或調整間距，而不必每次都呼叫模型重新生成，甚至不想看到任何一行程式碼。

傳統的解決方案是讓 AI 輸出基於固定組件 Schema 的 JSON 配置。這種做法在內容範圍清晰時非常有效，但當品牌網站需要不斷突破原有的佈局與交互設計時，擴充欄位和組件的工作量會呈指數級上升，最終變成維護的夢魘。

為了解決這個問題，Foundax 選擇讓 AI 直接編寫普通的 React (TypeScript) 和 CSS 程式碼，賦予模型熟悉的創作空間。但這意味著，固定 Schema 天然提供的「編輯映射」被打破了。本文將深入探討如何從普通的 React 原始碼中，透過編譯與執行期技術，重新建立可靠的可視化編輯能力，並處理動態業務數據與併發修改的工程難點。

拋棄協定束縛：從 AST 與符號解析出發

在架構演進的早期，我們曾嘗試透過提示詞（Prompt）要求模型在生成的程式碼中手寫特定的節點標記（例如 <div data-edit-id="xxx">）、維持固定的區塊目錄，甚至限制其使用的表達式。結果證明這是一條掘頭路：多重規則的疊加使得即便是合法的 React 程式碼，也經常落在「不可編輯」的範圍內。模型為了迎合這套脆弱的編輯協定，不斷在修復錯誤與回寫之間打轉，導致協定、驗證器與提示詞都需要極高的同步維護成本。

我們最終的共識是：編輯能力應該是原始碼的派生產物，而不是對源碼的侵入式約束。

為此，我們依賴 AST（抽象語法樹）與 TypeScript 符號解析來建立 Edit Index（編輯索引）。這個索引涵蓋了組件定義、呼叫點（Call Sites）、欄位表達式以及候選值的來源。

為何不直接依賴 Source Map？因為 Source Map 的設計初衷是將執行期的行列號映射回源碼，它本身並不具備「渲染實例語義」與「欄位所有權」的概念。我們需要的是精確到變數與屬性傳遞路徑的追蹤。

追溯值的來源 (Value Provenance)

考慮以下具體的 TSX 例子：

const Note = ({ title }: { title: string }) => {
  return <h2>{title}</h2>;
};

// 在頁面中兩次呼叫
export default function Page() {
  return (
    <div>
      <Note title="極簡主義設計"/>
      <Note title="為小空間而設計"/>
    </div>
  );
}

當商家在畫布上點選第二個標題並嘗試修改為「專為細單位設計」時，系統不能簡單地在全域進行字串替換（這會誤傷其他同名字串），更不能去修改 Note 組件內部 <h2> 的預設值（這會影響所有 Note 實例）。

透過 Compiler Instrumentation（編譯器插樁）在預覽環境中補充 DOM 選擇、呼叫路徑與 Runtime Observation（執行期觀測），系統可以精確定位到第二個 <h2> 節點。結合 Edit Index，系統能夠追溯出該值的 Value Provenance（來源出處）：它來自於 <Note> 第二個呼叫點的 title 屬性字串。因此，寫回的目標（Write Target）非常明確，就是精準 Patch 該源碼呼叫點的屬性值。變數同名並不等於來源相同，這裏追蹤的是源碼層級的引用關係，而非單純的 JavaScript 呼叫棧。

更多關於如何將 Agent 的程式碼執行能力融入業務系統的探討，可參考將 Coding Agent 接入真實商業系統：Foundax 架構實踐。

處理迴圈、分支與動態業務數據

真實的網店頁面遠比靜態文字複雜，包含了大量由迴圈產生的列表和條件分支，以及與業務後台強綁定的動態數據。

迴圈與集合成員身份

當程式碼包含 items.map(item => <ProductCard key={item.id} data={item} />) 時，定義、呼叫點、集合成員與最終生成的 DOM 實例擁有不同的身份。React 的 key 屬性有助於框架在渲染時進行協調，但它無法獨自作為一個持久的「編輯位址」；商品的 ID 也不足以區分同一件商品在「購物車」、「推薦欄」或「主列表」中的不同展示。

因此，畫布的操作必須依賴經過驗證的「組件呼叫路徑」與「成員身份」，才能在寫回時不至於發生錯位。

分支結構的執行期觀測

對於帶有條件分支的邏輯，例如： const title = product.title ?? fallbackTitle;

在靜態分析階段，系統只能保留這兩個候選來源。我們不能為了解析來源而重新執行該表達式，因為 getter 或函數可能帶有副作用。我們的做法是在 Runtime Observation 中，記錄受支援路徑當前實際求出的值以及對象/欄位關係。當商家點擊元素時，系統用對象身份與屬性描述資訊進行核對，確認當前採用的到底是 product.title 還是 fallbackTitle，絕不單憑畫面上顯示的文字去猜測。

業務狀態與項目狀態的隔離

一個核心的架構決策是區分「項目狀態」（源碼、頁面引用）與「業務狀態」（商品價格、庫存）。

如果商家在畫布上將商品卡的價格顏色改為紫色，這屬於展示層的變更，但系統不會一概將其直接寫入源碼。對於獨立的可寫參數或全域樣式，系統會直接 Patch 對應的源碼呼叫點；但如果是在一個商品清單迴圈中，單獨為其中一張卡片設定特殊樣式，這份差異會被保存為版本化的 Instance Override（實例覆蓋），以避免改動組件預設值而影響所有卡片。若商家在畫布上更換了展示的商品，這會修改專案狀態中的商品 ID 引用或查詢參數；但如果商家想要修改商品的實際售價，這個操作便超出了項目程式碼的範疇，必須交由真正的業務服務 API 進行調價。

網店的價格與庫存需要動態綁定業務的讀取/快取策略更新，不承諾實時刷新。靜態嵌入價格容易導致結帳數據不一致。因此，動態頁面持久化的是「數據引用」與「展示規則」。當後台調價後，前端會按策略刷新並顯示新價格，而不需要 Coding Agent 去修改源碼或重新發佈網站。撤銷前端項目的修改，也絕不能意外回滾後台真正的業務調價。

這也呼應了我們在我們為什麼讓業務 Agent 像 Coding Agent 一樣工作中提到的理念：區分不同 Agent 的職責邊界與執行上下文。

實例覆蓋 (Instance Override) 與源碼 Patch

對於獨立參數可以直接表達的修改，系統會直接 Patch 對應的呼叫點。但並非所有編輯都能或都應該直接修改源碼。

如果商家在一個由 .map() 生成的商品列表中，只想將其中一張卡片的樣式進行特殊調整。若強制修改組件的預設值，會導致所有卡片連帶變更；若要求 Agent 複製整套組件代碼來實現特例，則會破壞程式碼的維護性。

此時，實例覆蓋（Instance Override）是更合適的機制。系統會將這次編輯記錄為一個 Override 規則，隨項目狀態一起進行版本化管理。持久化的資料包含了可解析的實例目標、欄位以及作用域（Scope，例如區分手機端與桌面端）。編譯器、預覽環境與最終發佈的網站都會讀取並應用同一套覆蓋語義。

併發控制與跨版本身份協調

當可視化編輯器與 Coding Agent 同時對同一個項目進行操作時，狀態同步與併發控制成為最大的挑戰。

CAS 併發檢查

畫布的操作指令通常包含 expectedRevision, selectionId, field, operation, scope, value 等資訊。假設畫布目前基於版本 r1，但 Coding Agent 已經在後台提交了重構佈局的 r2 版本。此時，舊的編輯位址可能已經失效。

系統在處理畫布指令時，會先進行預解析，檢驗權限、版本與原值。準備好 Patch 之後，會使用 CAS（Compare-And-Swap）機制進行原子檢查，確認項目的 Head 依然是 r1 才會提交。這兩次檢查分別防止了過期的輸入，以及準備期間發生的併發衝突。需要強調的是，這裏的 CAS 是基於版本化的項目提交，而不是單純的檔案系統原子寫入，更不能與下面提到的身份協調混為一談。

跨版本節點身份協調 (Identity Reconciliation)

當 Agent 成功提交了 r2（例如在商品卡外層包了一個新的 <div> 容器），商家在 r1 時留下的實例覆蓋（如「單商品價格紫色」）該如何處理？

這依賴於 Identity Reconciliation 機制。系統只會在可確認結構對應範圍的情況下延續身份。包一層容器通常可以延續，但如果 Agent 複製了相同的卡片，或對缺乏身份標記的列表進行了重排，系統絕對不能單靠文字或舊順序去瞎猜。

即便節點身份得以保留，系統仍需驗證覆蓋欄位的來源及基礎值是否依然有效。例如，佈局改動保留了與之無關的顏色樣式，但如果值的來源徹底改變了，該覆蓋就會停止應用，並在系統中留下診斷日誌供開發者或 Agent 排查。身份匹配與值來源驗證，是兩個必須獨立滿足的條件。

結語

讓 AI 生成的普通 React 程式碼具備可視化編輯能力，絕不是在源碼之上套一層脆弱的正則替換，而是一系列工程機制的精確配合：透過靜態 AST 與符號分析建立候選的值來源；透過 Runtime Observation 補充當前的 DOM 實例與實際取值；透過 Identity Reconciliation 在跨項目版本之間協調節點的對應關係與實例覆蓋的依據；最後利用 CAS 負責項目提交時的併發控制。

必須承認，這套機制的編輯能力高度依賴系統的可解析範圍。一段合法的 React 程式碼能夠完美運行，並不代表其中所有複雜的動態表達式都能被可靠地反向編輯。當遇到無法可靠解析來源的極端情況時，系統會坦然退讓，為使用者提供明確的程式碼或配置入口，而不是強行猜測導致不可預期的覆蓋。

這套從源碼到畫布的雙向映射機制需要持續的工程投入。同版本的索引需要盡可能複用，檔案改變後需評估受影響的依賴再進行局部重算；編譯插樁分析與身份維護本身就是不可忽視的成本取捨。為了與社區更深入地探討這些技術細節，我們已將這份工程設計整理在開源專案 Agent Editable UI。該專案採用 MIT 授權，包含了核心設計文檔，以及普通 TSX 與合成商品資料的連續靜態推演過程（專案範圍專注於架構推演，不含可運行的視覺化編輯器、完整編譯器或預覽運行時）。

這是一場關於「開發者體驗」與「業務編輯體驗」的持續探索，歡迎各位前端與平台工程師透過 GitHub 倉庫與我們交流具體的工程實踐。

如何讓 AI 生成的前端程式碼支援可視化編輯