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

gRPC ve yerel SDK taşıması

Durum: Etkin Kapsam: masaüstü-yerel taşıma sözleşmesi Son inceleme: 2026-09-02 Sahip: ax-code sdk

AX Code artık masaüstü ve yerel GUI uygulamaları için isteğe bağlı, gRPC biçimli bir taşıma sözleşmesi sunar. Sözleşme kasıtlı olarak tam HTTP/OpenAPI yol ağacından daha dardır: bir GUI’nin yerel hissetmesi için gereken başsız çalışma zamanı yeteneklerine odaklanır; HTTP/OpenAPI uyumluluk, tanılar ve üretilmiş istemciler için içeride kullanılabilir kalır.

Öneri

Birinci taraf masaüstü uygulamaları için yeğlenen sınır olarak gRPC/yerel taşımayı kullanın. HTTP/SSE’yi geri dönüş ve hata ayıklama yüzeyi olarak açık tutun.

HTTP neden kaldırılmamalı

Çalışma zamanından HTTP/OpenAPI kaldırmak en incelenebilir ve taşınabilir uyumluluk yolunu kaldırır. JavaScript SDK, HTTP istemci/sunucu alt yollarını birinci taraf destek yüzeyleri olarak açmamalıdır; iç HTTP köprüsü tanılar, mevcut başsız arka uç başlatması ve üretilmiş istemci iş akışları için yararlı kalır. Güncel HTTP sunucu denetimleri zorlanmış yalnızca geri döngü bağlamayı, SDK yönetimli arka uç yardımcılarında üretilmiş Basic Auth kimlik bilgilerini, değiştiren tarayıcı isteklerinde kaynak denetimlerini, dizin doğrulamasını, istek hız sınırlarını ve yalnızca geri döngü canlı OpenAPI belgelerini içerir.

Taşıma, olağan ajan turları için baskın gecikme kaynağı değildir. LLM çağrıları, kabuk komutları, dosya G/Ç, dizinleme, LSP başlatması ve araç yürütmesi genellikle localhost JSON’dan daha pahalıdır. gRPC bir masaüstü GUI için yine yararlıdır çünkü daha temiz bir yerel API sözleşmesi, son tarihler, üst veri, sunucu akışı ve tarayıcı yönelimli bir API’yi uygulama kabuğuna sürüklemeden Unix soketi veya adlandırılmış boru taşımalarına giden bir yol sağlar.

Sözleşme biçimi

Dilden bağımsız sözleşme packages/sdk/proto/ax_code/v1/headless.proto adresindedir. JSR paketi bu proto’yu bir varlık olarak da içerir. TypeScript konakları onu resolveAxCodeGrpcProtoUrl() ile bulur; JavaScript dışı üreticiler kanonik depo sözleşmesini kullanmalıdır.

TypeScript cephesi @defai-digital/ax-code-sdk/grpc adresindedir ve şunları kapsar:

• sağlık ve yaşam döngüsü hazırlığı
• yerel konak yaşam döngüsü yönetimi için uygulama günlüğü alımı ve örnek atma/yeniden başlatma denetimleri
• oturum oluşturma
• istem, komut, kabuk, iptal, izin yanıtı ve soru yanıtı
• sağlayıcılar, oturumlar, izinler, sorular, yol, VCS, LSP, MCP, biçimlendirici ve komut durumu için GUI önyükleme anlık görüntüleri
• oturum listesi, ayrıntı, ileti geçmişi, ileti ayrıntısı, çocuklar, hedef, yapılacak, fark, çatal, paylaşma ve özetleme işlemleri
• ajanlar, beceriler, projeler, yol, VCS, komutlar, dosya ağacı/içerik/durum, metin/dosya/simge araması ve araç şemaları için GUI keşfi ve çalışma alanı gezinmesi
• proje bağlamı, bağlam şablonları, önbelleğe alınmış bellek yenileme/temizleme ve hata ayıklama motoru bekleyen plan tanıları
• gözetimli GUI akışları için bekleyen izin ve soru listeleme/yanıtlama/reddetme işlemleri
• GUI ayar ekranları için sağlayıcı, yapılandırma, API anahtarı kimlik doğrulaması ve sağlayıcı OAuth ayarları
• otonom kip, yalıtım kipi ve akıllı LLM yönlendirme için çalışma zamanı ayar denetimleri
• MCP durumu, kaynak keşfi, dinamik sunucu yönetimi, OAuth, bağlanma ve bağlantı kesme denetimleri
• tanı ve ayar ekranları için LSP ve biçimlendirici durumu
• PTY terminal yönetimi ve çift yönlü terminal akışı
• inceleme/hata ayıklama arayüzü için oturum kanıtı
• görev kuyruğu işlemleri
• zamanlanmış görev işlemleri
• iş akışı şablonları, iş akışı çalıştırmaları, pano özetleri, değerlendirme vakaları, iş akışı rutinleri ve çalıştırma yapıtları
• sunucudan akıtılan çalışma zamanı olayları

Proto, komut gövdeleri ve iş akışı/görev yükleri için yapılandırılmış JSON yükleri kullanır. Bu, AX Code çalışma zamanı şemaları hızla gelişirken taşımayı kararlı tutar.

@defai-digital/ax-code-sdk/grpc ayrıca AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers() ve assertAxCodeGrpcNativeHandlers() dışa aktarır. Yerel konaklar işleyici haritaları, gRPC hizmet bağlayıcıları, ön yükleme izin listeleri veya başlatma kapıları kurarken bu tanımlayıcıları ve kapsam denetimlerini kanonik yöntem kataloğu olarak kullanmalıdır. Her tanımlayıcı yöntem adını, tam nitelikli yöntem yolunu, akış türünü, proto istek ve yanıt ileti adlarını, GUI alanını, HTTP köprü kullanılabilirliğini ve güncel kararlılığı içerir. Bu, tam HTTP yol ağacını açmadan veya yansıtmadan yerel taşıma sınırını açık tutar.

TypeScript kullanımı

Konak mevcut HTTP çalışma zamanını içeride hâlâ gerektiriyorsa SDK yönetimli gRPC başsız arka ucunu kullanın. HTTP köprüsünü konak sürecinin içinde tutar ve yalnızca gRPC istemcisi ile yaşam döngüsü tutamacını döndürür:

import {
  createAxCodeGrpcClientFromNativeBridge,
  resolveAxCodeGrpcProtoUrl,
  startAxCodeGrpcHeadlessBackend,
} from "@defai-digital/ax-code-sdk/grpc"

const backend = await startAxCodeGrpcHeadlessBackend({ directory: "/workspace/app" })
try {
  const client = backend.client

  const session = await client.createSession({ title: "GUI session" })
  const messages = await client.session.messages((session as { id: string }).id, { limit: 50 })
  const skills = await client.app.skills()
  const readme = await client.file.read("README.md")
  const authMethods = await client.provider.auth()
  const bootstrap = await client.bootstrap.load({
    include: { sessions: true, providers: true, providerList: true, path: true, vcs: true },
  })
  const terminal = (await client.pty.create({ title: "GUI shell" })) as { id: string }
  const protoUrl = resolveAxCodeGrpcProtoUrl()

  await client.sendPrompt((session as { id: string }).id, {
    parts: [{ type: "text", text: "Review this workspace" }],
  })

  for await (const event of client.subscribeEvents({ sessionID: (session as { id: string }).id })) {
    if (event.type === "server.heartbeat") continue
    // Project event into GUI state.
  }
} finally {
  await backend.close()
}

Masaüstü konak ayrıcalıklı çalışma zamanı sınırına Electron ön yüklemesi, Tauri komutları veya başka bir yapılandırılmış kopya sınırı üzerinden sahipse yerel bir IPC köprüsü kullanın. IPC çağrıları AbortSignal değerini kasıtlı atlar ve çift yönlü girdi akışını çağrı yükünün dışında tutar; böylece çağrı nesnesi işleyici/konak sınırlarını temiz geçer:

const client = createAxCodeGrpcClientFromNativeIpc({
  unary(call) {
    return window.axCodeNative.unary(call)
  },
  serverStream(call) {
    return window.axCodeNative.serverStream(call)
  },
  bidiStream(call, input) {
    return window.axCodeNative.bidiStream(call, input)
  },
})

createAxCodeGrpcClientFromNativeBridge() değerini yalnızca iki taraf da aynı JavaScript alanında olduğunda ve çağrı nesnesinde AbortSignal ile zaman uyumsuz yinelenebilirleri güvenle geçirebildiğinde kullanın.

Konak itme tarzı abonelikler sunuyorsa, konak geri çağrılarını gRPC SDK’nın beklediği AsyncIterable akışlarına uyarlamak için createAxCodeGrpcNativeIpcBridgeFromChannels() veya createAxCodeGrpcNativeIpcStream() kullanın. Bu yardımcılar, bir JavaScript zaman uyumsuz üreteci yerine abonelikten çıkma işlevi döndüren Tauri olay dinleyicileri, Electron ön yükleme geri çağrıları ve diğer IPC sistemleri için yararlıdır.

Yerel konaklar el ile bir yöntem anahtarı yazmak yerine bir işleyici haritası da sunabilir. Bu, Rust/Tauri komutları, Electron ön yükleme API’leri veya AX Code çalışma zamanı işlemlerini yöntem yöntem bağlamak isteyen gerçek bir yerel gRPC sunucusu için yararlıdır. Köprüyü işleyici koduna vermeden önce beklenen her alanın kapsandığını doğrulamak için yöntem tanımlayıcılarını kullanın:

import {
  AX_CODE_GRPC_METHOD,
  assertAxCodeGrpcNativeHandlers,
  createAxCodeGrpcNativeBridgeFromHandlers,
  listAxCodeGrpcMethods,
} from "@defai-digital/ax-code-sdk/grpc"

const handlers = {
  unary: {
    [AX_CODE_GRPC_METHOD.GetSession](request, options) {
      return runtime.getSession(request.sessionID, options)
    },
  },
  serverStream: {
    [AX_CODE_GRPC_METHOD.SubscribeEvents](_request, options) {
      return runtime.events(options)
    },
  },
  bidiStream: {
    [AX_CODE_GRPC_METHOD.ConnectPty](request, input, options) {
      return runtime.connectPty(request.id, input, options)
    },
  },
}

const mcpMethods = listAxCodeGrpcMethods({ domain: "mcp" })
const streamingMethods = listAxCodeGrpcMethods({ kind: "serverStream" })
const ptyDescriptor = listAxCodeGrpcMethods({ kind: "bidiStream" })[0]
// ptyDescriptor.requestType === "PtyClientEvent"
// ptyDescriptor.responseType === "PtyServerEvent"

assertAxCodeGrpcNativeHandlers(handlers, {
  methods: [AX_CODE_GRPC_METHOD.GetSession, AX_CODE_GRPC_METHOD.SubscribeEvents, AX_CODE_GRPC_METHOD.ConnectPty],
})

const bridge = createAxCodeGrpcNativeBridgeFromHandlers(handlers, {
  requireHandlers: {
    methods: [AX_CODE_GRPC_METHOD.GetSession, AX_CODE_GRPC_METHOD.SubscribeEvents, AX_CODE_GRPC_METHOD.ConnectPty],
  },
})

bootstrap.load() kasıtlı olarak her HTTP yolunun bire bir kopyası değil, GUI yönelimli bir anlık görüntüdür. Yalnızca geçerli görünümün ihtiyaç duyduğu durumu istemek için include kullanın. Başarısız alt istekler errors içinde raporlanırken başarılı alanlar yine döner; böylece eksik isteğe bağlı bir alt sistem masaüstü kabuğunun açılmasını engellemez.

Olay akışı isteğe bağlı types ve sessionID süzgeçlerini kabul eder. Yerel taşımalar bu süzgeçleri sunucu tarafında uygulamalıdır. HTTP uyumluluk köprüsü aynı süzgeçleri mevcut SSE yolu üzerinde istemci tarafında uygular; böylece GUI kodu yerel sunucu uygulanırken tek bir abonelik biçimini koruyabilir.

startAxCodeGrpcHeadlessBackend(), konak ax-code serve sürecini hâlâ içeride başlatıyorsa yeğlenen geçici geri dönüştür. HTTP URL’sini veya yetkilendirme üst bilgisini döndürmez; böylece işleyici kodu gRPC cephesine karşı yazılabilir ve sonra herkese açık bir API yeniden yazımı olmadan gerçek bir yerel gRPC taşımasına taşınabilir.

Node tabanlı masaüstü konaklar aynı yerel köprüden gerçek bir HTTP/2 gRPC uç noktası sunabilir; @defai-digital/ax-code-sdk/grpc/node bunun içindir. Bu, işleyici kodu için değil ayrıcalıklı konak süreçleri içindir:

import { createAxCodeGrpcNativeBridgeFromHandlers, AX_CODE_GRPC_METHOD } from "@defai-digital/ax-code-sdk/grpc"
import { startAxCodeGrpcNodeHttp2Server } from "@defai-digital/ax-code-sdk/grpc/node"

const bridge = createAxCodeGrpcNativeBridgeFromHandlers({
  unary: {
    [AX_CODE_GRPC_METHOD.Health]() {
      return { status: "SERVING" }
    },
  },
  serverStream: {
    [AX_CODE_GRPC_METHOD.SubscribeEvents](request) {
      return runtime.subscribeEvents(request)
    },
  },
})

const server = await startAxCodeGrpcNodeHttp2Server({ bridge, host: "127.0.0.1" })
try {
  // Native clients can generate from ax_code/v1/headless.proto and connect to server.url.
} finally {
  await server.close()
}

PTY akışı bir gRPC çift yönlü akışı olarak modellenir. HTTP köprüsü uyumluluk için bu akışı mevcut WebSocket yoluna uyarlar; yerel GUI konakları WebSocket yolunu işleyici koduna açmak yerine onu yerel gRPC, Unix soketi veya adlandırılmış boru taşıması üzerinden uygulamalıdır.

Gerçek bir gRPC taşıması varken onu createAxCodeGrpcClient({ transport }) değerine verin. Üst düzey istemci aynı kalır.

Güvenlik duruşu

Masaüstü uygulamalar için bu sırayı yeğleyin:

1. GUI TypeScript ise ve çalışma zamanını güvenle yükleyebiliyorsa süreç içi SDK.
2. Geri döngü, Unix soketi veya adlandırılmış boru üzerinde yerel gRPC/yerel taşıma.
3. Üretilmiş tek kullanımlık Basic Auth kimlik bilgileriyle HTTP/SSE başsız köprü.
4. AX Code’u ağ HTTP’si üzerinde açmayın.

gRPC HTTP uyumluluk köprüsü ve SDK yönetimli HTTP arka uç yardımcıları yalnızca düz geri döngü uç noktalarını kabul eder. Eski allowRemoteHttpBridge ve allowNetworkBind seçenekleri kaynak uyumluluğu için tutulur ancak yalnızca yerel ilkesini atlamaz. /doc değerini geri döngü sunucusuyla sınırlı tutun.

HTTP uyumluluk köprüsü çapraz kaynaklı WebSocket yükseltmelerini varsayılan olarak reddeder. Bir kaynağı açık sunucu CORS izin listesine yalnızca o tarayıcı kaynağı güvenilen uygulama kabuğunun parçasıysa ekleyin.

Tam HTTP API’sini, PTY WebSocket’ini veya OpenAPI belgelerini rastgele WebView’lara açmayın. Bir WebView kullanılıyorsa onu işleyici olarak tutun ve ayrıcalıklı işlemleri gRPC/yerel cepheyi kullanarak yerel konak üzerinden yönlendirin.