本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文
HTTP 與 OpenAPI 相容
狀態：現行 範圍：現行狀態 上次審閱：2026-09-02 負責人：ax-code sdk
AX Code 有兩條整合路徑：
下面的 JSR 套件名稱已可發行，但尚未收到第一個公開版本。
- 第一方 TypeScript 與 JavaScript 應用程式整合，請使用
@defai-digital/ax-code-sdk。 - 第一方應用程式與桌面 GUI 工作，請使用
@defai-digital/ax-code-sdk/headless或@defai-digital/ax-code-sdk/grpc。 - 當需要另一種語言或相容處理程序邊界時，請使用
ax-code serve加上 OpenAPI 契約。 - 當 AX Code 擁有傳輸兩端、且是第一方桌面 GUI 工作時，請使用原生 SDK 傳輸。
HTTP/OpenAPI 路徑是相容與產生用戶端的基礎設施。它讓 Python、Go、Java、Rust 與其他用戶端呼叫同一個伺服器 API，而 AX Code 不必承諾為每種語言維護完整的官方套件。當 gRPC／原生契約可用時，不應把它當成第一方桌面 GUI 內部偏好的特權橋接，它也不再以第一方 JavaScript SDK 子路徑暴露。
選擇路徑
| 需求 | 建議路徑 | 原因 |
|---|---|---|
| 同一處理程序中的 TypeScript 或 JavaScript | 原始碼工作區 createAgent() 配接器 |
只有在刻意可解析私有 AX Code 執行環境原始碼套件時才可用 |
| 第一方桌面／原生 GUI | @defai-digital/ax-code-sdk/grpc |
較窄的無介面契約、伺服器串流、對中繼資料／期限友善，且較少暴露 WebView |
| 帶有本機後端的 TypeScript 或 JavaScript | @defai-digital/ax-code-sdk/headless |
保持生命週期與事件投影的型別，而不暴露完整的 HTTP SDK 介面 |
| Python、Go、Java、Rust 或其他執行環境 | 從 packages/sdk/openapi.json 產生用戶端 |
重用 HTTP 契約，而不必為每種語言增加第一方套件維護 |
| CI、自動化或一次性指令碼 | 對 ax-code serve 發出 HTTP 呼叫 |
部署模型簡單，處理程序隔離也容易 |
目前的官方項目
@defai-digital/ax-code-sdk是第一方 TypeScript 與 JavaScript SDK；其公開應用程式邊界是headless與grpc。@defai-digital/ax-code-sdk/grpc是第一方選用的桌面／原生無介面傳輸外觀。@defai-digital/ax-code-sdk/headless是第一方 TypeScript 與 JavaScript 生命週期／事件 SDK，用於本機後端處理程序邊界。packages/sdk/openapi.json是供產生 HTTP 用戶端的 OpenAPI 快照。- 產生的非 JavaScript 用戶端被支援為 HTTP 上的整合，但除非有套件負責人、測試與發行工作流程，否則它們不是第一方已發布套件。
基本 HTTP 流程
啟動伺服器：
export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096@defai-digital/ax-code-sdk/headless 生命週期輔助程式會產生一次性 Basic Auth 密碼，並自動以相符的
Authorization 標頭接上回傳的用戶端。手動的 ax-code serve 使用者應明確設定 AX_CODE_SERVER_PASSWORD，
並送出對應的 Basic Auth 標頭。位於 /doc 的即時 OpenAPI 文件與所有伺服器端點都
僅限迴路。
SDK 管理的後端輔助程式一律拒絕例如 0.0.0.0 的網路主機名稱。舊有的 allowNetworkBind 選項為了
原始碼相容而保留，但不再能繞過僅限本機的原則。桌面 GUI 殼層應偏好
@defai-digital/ax-code-sdk/grpc 或處理程序內 SDK 邊界。
HTTP 執行環境輔助程式不再是公開的 JavaScript SDK 子路徑。套件仍包含產生的用戶端內部實作，
因為 @defai-digital/ax-code-sdk/headless、gRPC HTTP 後備，以及舊有的 AX Code 執行環境程式碼會使用它們，但外部
整合應使用無介面、gRPC，或從 OpenAPI 快照產生的用戶端，而不是從 @defai-digital/ax-code-sdk 匯入 HTTP 執行環境
值。
檢查伺服器健康狀態：
curl http://127.0.0.1:4096/global/health在把快照驗證為 JSON 與 OpenAPI 之後，從 OpenAPI 快照建立產生的用戶端：
openapi-python-client generate --path packages/sdk/openapi.jsonoapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.goopenapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-java產生防護
把 OpenAPI 文件視為語言中立的契約。除非需要一小層易用層，否則不要手動維護圍繞個別路由的大型包裝。
把 AX Code 版本與產生的用戶端版本一起釘選。若伺服器路由結構描述變更，請重新產生用戶端，並以清楚的相容說明一起發行。
把產生的程式碼與手寫輔助程式分開。產生的檔案應容易替換，手寫檔案只應放驗證、預設、重試，以及較高階的便利 API。
保留服務邊界行為。非 JavaScript 用戶端使用 HTTP 伺服器路徑，不會得到處理程序內的 createAgent()、JavaScript 自訂工具執行，或 @defai-digital/ax-code-sdk/testing 公用程式。
在把產生的用戶端提升為第一方狀態之前，請覆蓋較難的部分：
- OpenAPI 驗證在 CI 中執行。
- 契約測試啟動
ax-code serve並呼叫具代表性的路由。 - 若用戶端暴露事件 API，則測試串流或 SSE 行為。
- 記載目錄範圍標頭與驗證行為。
- 發布、版本控制與所有權必須明確。
SDK 套件包含目前快照的輕量本機防護：
pnpm run check:openapi在 SDK 套件內工作時，也可使用套件層級指令：
pnpm --dir packages/sdk/js run validate:openapi這會驗證 packages/sdk/openapi.json 是可剖析的 JSON、宣告 OpenAPI 3.x，並包含產生用戶端所需的核心路由。