OpenPress

核心概念

Agent-First 哲學與系統概念

了解 OpenPress 為何不鼓勵使用者手寫程式碼，以及整個系統如何圍繞著「與 AI Agent 協作」而設計的核心理念與架構。

在傳統的軟體開發或文件排版中，使用者被期望親自撰寫程式碼、執行命令列 (CLI) 以及手動除錯。但在 OpenPress 中，我們徹底顛覆了這個模式。

OpenPress 是一個建立在 Agent-First (AI 代理優先) 哲學上的框架。這份文件將為您解釋整個系統的設計概念，讓您能夠轉換思維，從「寫程式的工程師」蛻變為「指揮 Agent 的架構師」。

1. 核心理念：人類負責決策，Agent 負責執行

OpenPress 的核心前提非常簡單：您不應該親自手寫 JSX 元件，也不該手動在終端機敲打 CLI 指令。

  • 人類的角色： 提供意圖、品味、業務邏輯、以及審閱最終產出。您是專案的「總編輯」與「產品經理」。
  • Agent 的角色： 理解您的意圖，將其轉化為精確的 React 程式碼、Markdown (MDX) 結構，並代為執行所有的建置與除錯流程。

因此，您不需要去背誦複雜的程式語法或設定步驟，這些繁瑣的實作細節都將由 AI 自動代勞。您真正需要掌握的，是整個系統的運作心智模型，以及如何清楚地向 Agent 下達指令。

2. Skills（技能）：注入領域知識與品味

如果您有注意到，我們經常提到安裝 Skills (例如 npx skills add ...)。Skill 是 OpenPress 生態系中非常關鍵的概念。

為什麼需要 Skill？

OpenPress 核心框架本身是「極度純粹且沒有意見的 (Opinionless)」。它只提供了將 Markdown 轉換成網頁或 PDF 的底層引擎，它本身不懂「什麼是好看的簡報」，也不懂「如何寫出一篇好文件」。

Skill 就是 Agent 的「外掛腦袋」與「品味濾鏡」。

  • 賦予能力： 當您安裝了一個 UI 設計 Skill，Agent 就學會了如何使用特定的 CSS 框架 (例如 Tailwind) 排版出有質感的畫面。
  • 賦予領域知識： 當您安裝了 documentation-writer Skill，Agent 就學會了專業的技術寫作原則，能幫您把雜亂的筆記重構為結構化文件。
  • 攜帶 Starter 模板： 許多 Skill 會自帶模板檔案。當您請 Agent 建立新專案時，Agent 會去讀取 Skill 內的 starter 檔案，作為幫您客製化專案的起點。

您可以把 Skill 想像成是您聘請來的「專家顧問團隊」，而 Agent 則是負責統籌並執行這些顧問意見的執行長。

3. 高階元件架構（給人類的心智模型）

雖然您不需要親自寫程式，但您必須與 Agent 擁有共同的語言。以下是 OpenPress 將文件視為「元件樹」的三個基礎層級：

  1. Workspace (工作區)： 您的整個專案宇宙。一個工作區內可以包含多份不同的出版物。
  2. Press (出版物)： 單一份獨立的文件或簡報（例如一份 A4 企劃書，或是一份 16:9 投影片）。
  3. Frame (框架/頁面)： 實體的頁面載體。有些是固定的（如封面），有些則會根據內容長度自動展開成多個實體頁面（如內文段落）。

為何放棄 WYSIWYG（所見即所得）？ 我們選擇使用 React 元件樹，是因為 AI 代理非常擅長輸出精確、結構化的程式碼。傳統的拖曳式編輯器很難用語音或文字指令精確控制，但透過結構化的 JSX，您只需要對 Agent 說：「幫我在這張投影片加入一個兩欄式的對比圖」，Agent 就能完美地產出對應的程式碼結構。

4. 底層的黑魔法（為何你不需要管細節）

為了解放使用者的心智負擔，OpenPress 的底層引擎自動處理了大量繁瑣的工程細節。您與 Agent 都不需要在這些事情上浪費時間：

  • 自動路徑推導： 系統會根據資料夾名稱（例如 press/report/）自動註冊路由與 slug。
  • MDX 自動注入魔法： 放在特定資料夾內的 React 元件，會被引擎自動開放給 Markdown 使用。Agent 在寫 MDX 時，可以直接使用 <Chart /> 而不需要處理煩人的 import 路徑。
  • 建置期 ID 注入： 引擎會在背景自動為每一個投影片和區塊注入隱藏的 ID (data-op-id)，讓視覺介面與原始碼之間能自動對應。

5. 如何與 Agent 完美協作（實踐迴圈）

理解了以上概念後，您與 Agent 的日常協作流程應該長這樣：

  1. 給予高階意圖： 「我需要建立一份 10 頁的產品發布簡報，請使用剛安裝的品牌 Skill 來確保視覺風格統一。」
  2. 讓 Agent 執行與建置： Agent 會自動建立 press.tsx，產生對應的 MDX 內容，並在背景幫您執行 npm run dev 啟動預覽。
  3. 利用「註解 (Comment Markers)」進行審閱： 當您在畫面上看到預覽結果時，不要自己打開編輯器修改程式碼。請直接使用系統的「註解標記」功能，在畫面上圈選不滿意的地方留下評論：「這裡的字體太小」、「這個段落請重寫得更專業」。
  4. 閉環修復： 命令 Agent：「請處理畫面上所有的 Comment Markers。」Agent 就會精確地循著 ID 找到原始碼，並修正所有的問題。

結語

歡迎來到 Agent-First 的時代。請放下您的工程師包袱，開始享受身為「架構師」的樂趣。如果您想了解更多的具體 API 參數與架構細節（通常是為了讓 Agent 參考），請前往參考資料區塊。