Astrologistic：為 Astro 專案打造的 JSON 頁面區塊編輯器基礎

Astrologistic 是一套以 Astro 為核心、以 JSON 描述頁面結構的可重用區塊編輯器基礎。它的目標不是再做一個只能服務單一網站的 CMS，也不是把每個頁面都變成任意拖拉的畫布，而是把頁面組合、內容區塊、驗證、版本與發布流程整理成可以被不同產品採用的工程能力。

對需要長期維護的 Astro 專案來說，真正棘手的往往不是把第一個頁面做出來，而是當頁面數量、內容編輯、媒體素材與產品需求一起增加之後，如何仍然維持結構清楚、版本可追蹤、前台渲染一致。Astrologistic 就是從這個問題出發。

為什麼需要結構化的頁面編輯

傳統做法很容易在兩個極端之間擺盪：一端是把內容寫死在 Astro 元件裡，開發者有完整控制，但每次改文案或調整版面都需要重新修改程式；另一端是直接儲存一大段 HTML，編輯看似自由，卻很難保證安全性、可遷移性與不同頁面的呈現一致。

Astrologistic 選擇第三條路：把頁面保存成有 schema 版本的 PageDocument。內容不是沒有結構的 HTML，而是由 layout node 與 block node 組成的資料。這讓編輯器、預覽頁、公開頁與後續的內容工作流，都能對同一份資料模型建立清楚的契約。

用 layout 與 block 分開頁面責任

Astrologistic 的基本模型分成兩種節點。layout node 負責頁面的結構，例如 section、stack、欄位、間距、寬度與可放入哪些子節點；block node 則負責實際內容，例如標題、文字、圖片、連結、FAQ 或其他產品需要的內容模組。

這個分層讓「內容是什麼」與「內容放在哪裡」可以分開演進。編輯器可以依照 registry 知道某個區塊能放進哪些 layout，也能在插入、移動或儲存時執行 schema 驗證。未來不同產品需要不同業務區塊時，也可以透過 extension registry 加入，而不必把所有產品邏輯塞進核心套件。

Astrologistic
├─ Layout nodes：頁面結構與容器
├─ Block nodes：內容與互動模組
└─ Extension registry：產品化擴充與驗證

從 schema、驗證到版本管理

結構化資料的價值，不只是讓編輯器比較容易讀取。每個 page、layout、block 與 preset 都帶有 schema 版本，載入、匯入與儲存前可以先驗證，必要時再透過 migration 轉換舊格式。當產品持續演進時，這比直接修改一段不透明的 HTML 更容易理解，也更容易保留既有內容。

在編輯體驗上，目前的基礎也涵蓋畫布選取、區塊插入、拖放、Inspector、undo/redo、autosave、版本比較與還原。發布流程會檢查文件是否符合目前的 registry 與驗證規則，並以版本快照保存每次重要變更。這些能力的重點不是增加更多按鈕，而是讓「改了什麼、目前哪一版、能不能安全發布」變得可追蹤。

讓前台與編輯器共享同一個 renderer

如果編輯器與公開頁各自維護一套內容解讀方式，久了就會出現預覽和正式頁不一致、某個區塊只在後台看得到，或更新 schema 後舊內容無法正常呈現的問題。

Astrologistic 把 registry、validation 與 renderer 放在同一條內容契約上。編輯器使用它來決定可用的區塊與欄位，預覽與公開頁則使用相同的結構來產生渲染結果；Astro 端的套件負責把這些內容安全地轉成頁面輸出。這樣，新增能力時需要思考的不只是「後台如何編輯」，也包括「正式頁如何穩定渲染」與「資料如何向前相容」。

以 Cloudflare 作為可替換的儲存層

Astrologistic 的核心不綁定特定基礎設施，但已提供 Cloudflare 導向的儲存適配：D1 保存頁面與版本相關資料，KV 可用於預覽快取，R2 則適合保存上傳的媒體物件。這些能力被放在 Cloudflare adapter，而不是塞進 editor-core，讓核心模型仍能在不同宿主環境中被測試與重用。

這種切分也保留了產品的選擇空間。採用 Astrologistic 的專案可以使用既有的 Astro 與 Cloudflare 組合，也可以自行替換身份、權限、資料庫或媒體管線；編輯器提供的是可驗證的內容與版本基礎，不假裝替產品決定完整的營運流程。

套件邊界比功能清單更重要

Astrologistic 目前拆成數個各自負責不同問題的套件：editor-core 管理頁面、節點、registry、validation 與 migration；editor-astro 負責 Astro 渲染與相關輸出；editor-cloudflare 負責 D1、KV、R2 的儲存協作；editor-astromer 提供與 Astromer 設計系統的橋接；editor-shell 與 editor-ui 則整理可重用的編輯器介面與狀態能力。

這樣的邊界讓 Astrologistic 可以獨立演進，也讓採用它的 consumer 專案不必被迫接受整套產品決策。Astromer 可以專注在 token、元件與視覺語言；Astrologistic 則專注在編輯、內容結構、驗證與版本；真正的產品再決定自己的資料權限、品牌語氣與業務區塊。

如果用一句話總結，Astrologistic 想解決的是「如何讓可視化內容編輯，仍然保有工程系統需要的結構與可控性」。它把頁面編輯從一次性的後台功能，提升成有 schema、有 registry、有版本、有 renderer 的產品基礎。

這條路徑仍然可以繼續擴充：更多產品化 block pack、更完整的協作與權限流程、排程發布、在安全邊界內接入 AI authoring，以及不同 consumer 專案的實際導入。但無論功能如何增加，核心原則不變：內容要可驗證，版本要可追蹤，產品邊界要清楚，前台與編輯器要共享同一份契約。