跳至主要内容

代理式工作流程

Neat 框架的公開 API 旨在不僅供應用程式開發人員使用，還供 AI 程式碼代理程式使用，這些代理程式會代表開發人員編寫針對 Modalix 的程式碼。本頁說明為什麼框架的某些設計選擇呈現目前的樣貌——它們是針對閱讀 API 的代理程式進行最佳化，而不僅僅是針對人類。

一個代理程式需要從框架中獲得什麼​

一個用於產生程式碼以處理不熟悉的 API 的 AI 代理程式通常需要：

  1. 一個小型的公共介面——種類較少，學習起來也更容易。
  2. 自我描述型別 — 型別簽章應編碼合約，而不僅僅是暗示合約。
  3. 完成每件事的一種方法——多種等效的途徑，這正是導致代理程式做出錯誤決策的原因。
  4. 相鄰的檔案 — 代理程式會讀取 @brief 程式碼區塊，而不是包含 8000 行的設計檔案。重要的上下文資訊必須與程式碼片段緊鄰。
  5. 確定性的輸出 — 當一個代理程式撰寫測試快照時，逐位元確定的方式能確保它們的穩定性。
  6. 能指出根本原因的錯誤——當某個東西發生錯誤時，錯誤訊息需要指出是哪個核心元件／合約／選項出了問題，而不是僅僅顯示「圖表建立失敗」。
  7. 重現錯誤的成品——如果代理程式的程式碼發生錯誤，它可以將 repro_gst_launch 字串貼入除錯工具中，並重複執行，而無需重新執行代理程式。
  8. 沒有隱藏的全局變數——每個行為都應該是建構函式參數或 Node 選項，而不是在執行階段讀取的環境變數。
  9. 穩定的識別碼 — 相同的節點 + 相同的選項 ⇒ 相同的元素名稱 ⇒ 相同的啟動字串 ⇒ 穩定的測試環境。
  10. 將模型封存檔視為資料，而非程式碼——模型是一個框架載入的套件，而不是代理程式需要編譯的標頭檔。
  11. 可組合的建構模組 — 節點、模型和可重複使用的 Graph 片段可以相互連接；代理程式不必預先知道框架「支援」哪些組合，因為規劃器會在建置時提供答案。
  12. 在建置期間進行嚴格的驗證 — 錯誤會在 Graph::build() 階段浮現，而不是在第一次 pull() 階段。代理程式的迴圈需要將錯誤指向正確的程式碼行。
  13. 結構化的 GraphReport — 以程式化的方式存取建置過程的資訊，讓代理程式能夠驗證其自身的工作。
  14. 逐步揭露——Model 是最簡單的路徑，Graph::add() 是下一個路徑，自訂節點則是更深入的路徑。一個代理程式會先選擇最簡單的路徑。
  15. 版本化的 MPK 合約——一個模型封存檔包含足夠的元資料，因此，產生程式碼的代理程式不需要查閱外部檔案。

這些會在整個架構中以具體的設計決策形式呈現：

  • 小型公共介面（模型、張量、樣本、節點、圖和執行）是代理程式學習應用程式程式碼所需的一切。
  • Graph::describe() 會傳回一份結構化的計畫摘要，讓代理程式可以驗證自己的管線。
  • NeatError 包含 error_code()，以及一份 GraphReport——代理程式可以啟用此代碼。
  • Node::backend_fragment() 具有確定性——代理程式可以針對管線編寫「黃金字串」測試。
  • MpkContract 是對某個模型的唯一權威性描述——代理程式在根據模型產生接執行緒式碼時，不需要任何其他東西。

應用程式開發者如何受益​

即使您不是代理人，您仍然可以從對代理人友善的 API 設計中受益：使自動程式碼生成更可靠的相同特性，也能讓手動程式碼審查更容易、重構更安全，並讓 AI 輔助開發（例如 Claude Code、Copilot、Cursor）在 Modalix 程式碼中更具生產力。

更多閱讀資料​

  • 「隆重推出 Neat」——設計深度探討的第 0.1 節。
  • Graph::describe() — 以圖表呈現的計畫概要。
  • NeatError — 結構化錯誤類型。
  • Model — 已載入模型封存檔，並已解析 MPK 合約。