Bu sayfa İngilizce belgenin çevirisidir. Komutlar, tanımlayıcılar ve örnekler aynıdır. Çalışma zamanı 7.24.4 · SDK 2.6.7. İngilizce kaynak

HTTP ve OpenAPI uyumluluğu

Durum: Etkin Kapsam: güncel durum Son inceleme: 2026-09-02 Sahip: ax-code sdk

AX Code’un iki entegrasyon yolu vardır:

Aşağıdaki JSR paket adı yayına hazırdır ancak henüz ilk herkese açık sürümünü almamıştır.

Birinci taraf TypeScript ve JavaScript uygulama entegrasyonu için @defai-digital/ax-code-sdk kullanın.
Birinci taraf uygulama ve masaüstü GUI işi için @defai-digital/ax-code-sdk/headless veya @defai-digital/ax-code-sdk/grpc kullanın.
Başka bir dil veya uyumluluk süreç sınırı gerektiğinde ax-code serve artı OpenAPI sözleşmesini kullanın.
AX Code taşımanın her iki ucuna da sahipse birinci taraf masaüstü GUI işi için Yerel SDK taşıması kullanın.

HTTP/OpenAPI yolu uyumluluk ve üretilmiş istemci altyapısıdır. Python, Go, Java, Rust ve diğer istemcilerin aynı sunucu API’sini çağırmasını sağlar; AX Code her dil için tam resmi bir paket sürdürmeyi üstlenmez. gRPC/yerel sözleşme varken birinci taraf bir masaüstü GUI içinde yeğlenen ayrıcalıklı köprü olarak ele alınmamalıdır ve artık birinci taraf JavaScript SDK alt yolları olarak sunulmaz.

Bir yol seçin

Gereksinim	Önerilen yol	Neden
Aynı süreçte TypeScript veya JavaScript	Kaynak çalışma alanı `createAgent()` bağdaştırıcısı	Yalnızca özel AX Code çalışma zamanı kaynak paketi bilinçli çözülebilir olduğunda kullanılabilir
Birinci taraf masaüstü/yerel GUI	`@defai-digital/ax-code-sdk/grpc`	Daha dar başsız sözleşme, sunucu akışı, üst veri/son tarih dostu ve daha az WebView açıklığı
Yerel bir arka uçla TypeScript veya JavaScript	`@defai-digital/ax-code-sdk/headless`	Tam HTTP SDK yüzeyini açmadan yaşam döngüsü ve olay izdüşümünü tipli tutar
Python, Go, Java, Rust veya başka bir çalışma zamanı	`packages/sdk/openapi.json` belgesinden istemci üretin	Her dil için birinci taraf paket bakımı eklemeden HTTP sözleşmesini yeniden kullanır
CI, otomasyon veya tek seferlik betikler	`ax-code serve` üzerine HTTP çağrıları	Basit dağıtım modeli ve kolay süreç yalıtımı

Bugün resmi olanlar

@defai-digital/ax-code-sdk birinci taraf TypeScript ve JavaScript SDK’sıdır; herkese açık uygulama sınırları headless ve grpc değerleridir.
@defai-digital/ax-code-sdk/grpc birinci taraf isteğe bağlı masaüstü/yerel başsız taşıma cephesidir.
@defai-digital/ax-code-sdk/headless yerel arka uç süreç sınırları için birinci taraf TypeScript ve JavaScript yaşam döngüsü/olay SDK’sıdır.
packages/sdk/openapi.json üretilmiş HTTP istemcileri için OpenAPI anlık görüntüsüdür.
Üretilmiş JavaScript dışı istemciler HTTP üzerinden entegrasyon olarak desteklenir; bir paket sahibi, sınamalar ve yayın iş akışı yoksa birinci taraf yayımlanmış paket değildir.

Temel HTTP akışı

Sunucuyu başlatın:

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 yaşam döngüsü yardımcısı tek kullanımlık bir Basic Auth parolası üretir ve dönen istemciyi eşleşen Authorization üst bilgisiyle otomatik bağlar. El ile ax-code serve kullanıcıları AX_CODE_SERVER_PASSWORD değerini açıkça ayarlamalı ve karşılık gelen Basic Auth üst bilgisini göndermelidir. /doc adresindeki canlı OpenAPI belgeleri ve tüm sunucu uç noktaları yalnızca geri döngüdür.

SDK yönetimli arka uç yardımcıları 0.0.0.0 gibi ağ ana bilgisayar adlarını her zaman reddeder. Eski allowNetworkBind seçeneği kaynak uyumluluğu için tutulur ancak artık yalnızca yerel ilkesini atlamaz. Masaüstü GUI kabukları @defai-digital/ax-code-sdk/grpc veya süreç içi bir SDK sınırını yeğlemelidir.

HTTP çalışma zamanı yardımcıları artık herkese açık JavaScript SDK alt yolları değildir. Paket hâlâ üretilmiş istemci içlerini içerir çünkü @defai-digital/ax-code-sdk/headless, gRPC HTTP geri dönüşü ve eski AX Code çalışma zamanı kodu onları kullanır; dış entegrasyonlar @defai-digital/ax-code-sdk içinden HTTP çalışma zamanı değerlerini içe aktarmak yerine başsız, gRPC veya OpenAPI anlık görüntüsünden üretilmiş istemciler kullanmalıdır.

Sunucu sağlığını denetleyin:

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

Anlık görüntüyü JSON ve OpenAPI olarak doğruladıktan sonra OpenAPI anlık görüntüsünden istemci üretin:

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

Üretim korkulukları

OpenAPI belgesini dilden bağımsız sözleşme olarak ele alın. Küçük bir ergonomi katmanı gerekmedikçe tek tek yolların çevresinde büyük sarmalayıcıları elle sürdürmeyin.

AX Code sürümünü ve üretilmiş istemci sürümünü birlikte sabitleyin. Sunucu yol şeması değişirse istemciyi yeniden üretin ve açık bir uyumluluk notuyla yayınlayın.

Üretilmiş kodu el yazısı yardımcılardan ayrı tutun. Üretilmiş dosyalar kolay değiştirilebilir olmalı; el yazısı dosyalar yalnızca kimlik doğrulama, varsayılanlar, yeniden denemeler ve daha üst düzey kolaylık API’lerini tutmalıdır.

Hizmet sınırı davranışını koruyun. JavaScript dışı istemciler HTTP sunucu yolunu kullanır ve süreç içi createAgent(), JavaScript özel araç yürütmesi veya @defai-digital/ax-code-sdk/testing yardımcılarını almaz.

Üretilmiş bir istemciyi birinci taraf durumuna yükseltmeden önce zor kısımları kapsayın:

OpenAPI doğrulaması CI içinde çalışır.
Bir sözleşme sınaması ax-code serve başlatır ve temsili yolları çağırır.
İstemci olay API’leri sunuyorsa akış veya SSE davranışı sınanır.
Dizin kapsamı üst bilgileri ve kimlik doğrulama davranışı belgelenir.
Yayımlama, sürümleme ve sahiplik açıktır.

SDK paketi geçerli anlık görüntü için hafif bir yerel koruma içerir:

pnpm run check:openapi

Paket düzeyi komut, SDK paketi içinde çalışırken de kullanılabilir:

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

Bu, packages/sdk/openapi.json dosyasının ayrıştırılabilir JSON olduğunu, OpenAPI 3.x bildirdiğini ve üretilmiş istemcilerin ihtiyaç duyduğu çekirdek yolları içerdiğini doğrular.