Halaman ini diterjemahkan dari dokumentasi bahasa Inggris. Perintah, pengenal, dan contoh tidak diubah. Runtime 7.24.4 · SDK 2.6.7. Sumber bahasa Inggris

Kompatibilitas HTTP dan OpenAPI

Status: Aktif Cakupan: kondisi terkini Terakhir ditinjau: 2026-09-02 Pemilik: sdk ax-code

AX Code memiliki dua jalur integrasi:

Nama paket JSR di bawah siap rilis tetapi belum menerima versi publik pertamanya.

Pakai @defai-digital/ax-code-sdk untuk integrasi aplikasi TypeScript dan JavaScript pihak pertama.
Pakai @defai-digital/ax-code-sdk/headless atau @defai-digital/ax-code-sdk/grpc untuk pekerjaan aplikasi dan GUI desktop pihak pertama.
Pakai ax-code serve plus kontrak OpenAPI bila bahasa lain atau batas proses kompatibilitas diperlukan.
Pakai Transport SDK bawaan untuk pekerjaan GUI desktop pihak pertama di mana AX Code memiliki kedua ujung transport.

Jalur HTTP/OpenAPI adalah infrastruktur kompatibilitas dan klien yang dihasilkan. Ia memungkinkan klien Python, Go, Java, Rust, dan lainnya memanggil API server yang sama tanpa AX Code berkomitmen memelihara paket resmi penuh untuk setiap bahasa. Ia tidak boleh diperlakukan sebagai jembatan istimewa yang diutamakan di dalam GUI desktop pihak pertama bila kontrak gRPC/bawaan tersedia, dan ia tidak lagi diekspos sebagai subjalur SDK JavaScript pihak pertama.

Pilih jalur

Kebutuhan	Jalur yang disarankan	Mengapa
TypeScript atau JavaScript dalam proses yang sama	Adaptor `createAgent()` ruang kerja sumber	Tersedia hanya bila paket sumber runtime AX Code privat sengaja dapat diselesaikan
GUI desktop/bawaan pihak pertama	`@defai-digital/ax-code-sdk/grpc`	Kontrak tanpa interaksi yang lebih sempit, aliran server, ramah metadata/batas waktu, dan paparan WebView yang lebih sedikit
TypeScript atau JavaScript dengan backend lokal	`@defai-digital/ax-code-sdk/headless`	Menjaga siklus hidup dan proyeksi peristiwa tetap bertipe tanpa mengekspos permukaan SDK HTTP penuh
Python, Go, Java, Rust, atau runtime lain	Hasilkan klien dari `packages/sdk/openapi.json`	Memakai ulang kontrak HTTP tanpa menambah pemeliharaan paket pihak pertama untuk setiap bahasa
CI, otomasi, atau skrip sekali jalan	Panggilan HTTP terhadap `ax-code serve`	Model penyebaran yang sederhana dan isolasi proses yang mudah

Yang resmi hari ini

@defai-digital/ax-code-sdk adalah SDK TypeScript dan JavaScript pihak pertama; batas aplikasi publiknya adalah headless dan grpc.
@defai-digital/ax-code-sdk/grpc adalah fasad transport tanpa interaksi desktop/bawaan opsional pihak pertama.
@defai-digital/ax-code-sdk/headless adalah SDK siklus hidup/peristiwa TypeScript dan JavaScript pihak pertama untuk batas proses backend lokal.
packages/sdk/openapi.json adalah cuplikan OpenAPI untuk klien HTTP yang dihasilkan.
Klien non-JavaScript yang dihasilkan didukung sebagai integrasi melalui HTTP, tetapi mereka bukan paket terbitan pihak pertama kecuali ada pemilik paket, uji, dan alur kerja rilis.

Alur HTTP dasar

Mulai server:

export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096

Pembantu siklus hidup @defai-digital/ax-code-sdk/headless menghasilkan kata sandi Basic Auth sekali pakai dan menghubungkan klien yang dikembalikan dengan header Authorization yang cocok secara otomatis. Pengguna ax-code serve manual harus menyetel AX_CODE_SERVER_PASSWORD secara eksplisit dan mengirim header Basic Auth yang sesuai. Dokumen OpenAPI langsung di /doc dan semua titik akhir server hanya loopback.

Pembantu backend terkelola SDK selalu menolak nama host jaringan seperti 0.0.0.0. Opsi lama allowNetworkBind dipertahankan untuk kompatibilitas sumber tetapi tidak lagi melewati kebijakan hanya-lokal. Shell GUI desktop harus mengutamakan @defai-digital/ax-code-sdk/grpc atau batas SDK dalam proses.

Pembantu runtime HTTP tidak lagi menjadi subjalur SDK JavaScript publik. Paket masih berisi internal klien yang dihasilkan karena @defai-digital/ax-code-sdk/headless, cadangan HTTP gRPC, dan kode runtime AX Code lama memakainya, tetapi integrasi eksternal harus memakai klien tanpa interaksi, gRPC, atau yang dihasilkan dari cuplikan OpenAPI alih-alih mengimpor nilai runtime HTTP dari @defai-digital/ax-code-sdk.

Periksa kesehatan server:

curl http://127.0.0.1:4096/global/health

Buat klien yang dihasilkan dari cuplikan OpenAPI setelah memvalidasi cuplikan sebagai JSON dan OpenAPI:

openapi-python-client generate --path packages/sdk/openapi.json

oapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.go

openapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-java

Pagar pembuatan

Perlakukan dokumen OpenAPI sebagai kontrak netral bahasa. Jangan memelihara pembungkus besar secara manual di sekitar rute individual kecuali lapisan ergonomi kecil diperlukan.

Sematkan versi AX Code dan versi klien yang dihasilkan bersama-sama. Jika skema rute server berubah, buat ulang klien dan rilis dengan catatan kompatibilitas yang jelas.

Pisahkan kode yang dihasilkan dari pembantu tulisan tangan. Berkas yang dihasilkan harus mudah diganti, sementara berkas tulisan tangan hanya menahan autentikasi, bawaan, percobaan ulang, dan API kenyamanan tingkat lebih tinggi.

Pertahankan perilaku batas layanan. Klien non-JavaScript memakai jalur server HTTP dan tidak mendapat createAgent() dalam proses, eksekusi alat kustom JavaScript, atau utilitas @defai-digital/ax-code-sdk/testing.

Cakup bagian yang sulit sebelum mempromosikan klien yang dihasilkan ke status pihak pertama:

Validasi OpenAPI berjalan di CI.
Uji kontrak memulai ax-code serve dan memanggil rute yang mewakili.
Perilaku aliran atau SSE diuji jika klien mengekspos API peristiwa.
Header cakupan direktori dan perilaku autentikasi didokumentasikan.
Penerbitan, versi, dan kepemilikan bersifat eksplisit.

Paket SDK menyertakan penjaga lokal yang ringan untuk cuplikan saat ini:

pnpm run check:openapi

Perintah tingkat paket juga tersedia saat bekerja di dalam paket SDK:

pnpm --dir packages/sdk/js run validate:openapi

Ini memvalidasi bahwa packages/sdk/openapi.json adalah JSON yang dapat diurai, menyatakan OpenAPI 3.x, dan berisi rute inti yang dibutuhkan klien yang dihasilkan.