Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Транспорт gRPC и собственного SDK

Статус: действует Область: контракт транспорта для настольных приложений Последняя проверка: 2026-09-02 Владелец: SDK ax-code

AX Code теперь открывает необязательный контракт транспорта в форме gRPC для настольных и собственных графических приложений. Контракт намеренно уже полного дерева маршрутов HTTP/OpenAPI: он сосредоточен на возможностях неинтерактивной среды выполнения, которые нужны графическому интерфейсу, чтобы ощущаться своим, а HTTP/OpenAPI остаётся внутри для совместимости, диагностики и сгенерированных клиентов.

Рекомендация

Используйте транспорт gRPC или собственный транспорт как предпочтительную границу для собственных настольных приложений. Оставьте HTTP/SSE включённым как запасной путь и поверхность отладки.

Почему не убирать HTTP

Удаление HTTP/OpenAPI из среды выполнения убрало бы самый удобный для осмотра и переносимый путь совместимости. SDK на JavaScript не должен открывать подпути клиента и сервера HTTP как поверхности поддержки первой стороны, но внутренний мост HTTP остаётся полезен для диагностики, существующего запуска неинтерактивного сервера и рабочих процессов сгенерированного клиента. Текущий контроль сервера HTTP включает принудительную привязку только к loopback, порождённые учётные данные Basic Auth в помощниках сервера под управлением SDK, проверку источника у изменяющих запросов браузера, проверку каталогов, пределы частоты запросов и документацию OpenAPI вживую только на loopback.

Транспорт — не главный источник задержки обычных ходов агента. Вызовы LLM, команды оболочки, файловый ввод-вывод, индексация, запуск LSP и выполнение инструментов обычно дороже JSON на localhost. gRPC всё же полезен настольному интерфейсу: он даёт более чистый собственный контракт API, сроки, метаданные, серверный поток и путь к транспортам сокета Unix или именованного канала, не таща API, ориентированный на браузер, в оболочку приложения.

Форма контракта

Языково-нейтральный контракт находится в packages/sdk/proto/ax_code/v1/headless.proto. Пакет JSR также содержит этот proto как ресурс. Узлы TypeScript находят его через resolveAxCodeGrpcProtoUrl(). Генераторам не на JavaScript следует использовать канонический контракт репозитория.

Фасад TypeScript находится в @defai-digital/ax-code-sdk/grpc и охватывает:

• здоровье и готовность жизненного цикла
• приём журналов приложения и управление освобождением и перезапуском экземпляра для жизненного цикла собственного узла
• создание сеанса
• промпт, команду, оболочку, прерывание, ответ на право и ответ на вопрос
• снимки начальной загрузки интерфейса для провайдеров, сеансов, прав, вопросов, пути, VCS, LSP, MCP, форматтера и состояния команд
• список сеансов, подробности, историю сообщений, подробности сообщения, потомков, цель, задачи, diff, ответвление, общий доступ и операции сводки
• обнаружение интерфейса и навигацию по рабочей области для агентов, навыков, проектов, пути, VCS, команд, дерева, содержимого и статуса файлов, поиска текста, файлов и символов и схем инструментов
• контекст проекта, шаблоны контекста, обновление и очистку кэшированной памяти и диагностику ожидающего плана отладочного движка
• операции списка, ответа и отказа для ожидающих прав и вопросов в наблюдаемых потоках интерфейса
• настройки провайдера, конфигурации, аутентификации ключом API и OAuth провайдера для экранов настроек
• управление настройками среды выполнения для автономного режима, режима изоляции и умной маршрутизации LLM
• статус MCP, обнаружение ресурсов, динамическое управление серверами, OAuth, подключение и отключение
• статус LSP и форматтера для диагностики и экранов настроек
• управление терминалом PTY и двунаправленный поток терминала
• свидетельства сеанса для интерфейса рецензии и отладки
• операции очереди задач
• операции запланированных задач
• шаблоны рабочего процесса, прогоны, сводки панели, случаи оценки, процедуры и артефакты прогона
• события среды выполнения в серверном потоке

Proto использует структурированные нагрузки JSON для тел команд и нагрузок рабочего процесса и задач. Транспорт остаётся устойчивым, пока схемы среды выполнения AX Code быстро развиваются.

@defai-digital/ax-code-sdk/grpc также экспортирует AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers() и assertAxCodeGrpcNativeHandlers(). Собственным узлам следует использовать эти дескрипторы и проверки покрытия как канонический каталог методов при сборке карт обработчиков, привязок службы gRPC, списков разрешений preload или шлюзов запуска. Каждый дескриптор включает имя метода, полностью квалифицированный путь метода, вид потока, имена сообщений запроса и ответа proto, область интерфейса, доступность моста HTTP и текущую устойчивость. Граница собственного транспорта остаётся явной, без открытия и без зеркала полного дерева маршрутов HTTP.

Использование TypeScript

Используйте сервер gRPC headless под управлением SDK, когда узлу всё ещё нужна существующая среда HTTP внутри. Он держит мост HTTP внутри процесса узла и возвращает только клиент gRPC плюс дескриптор жизненного цикла:

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()
}

Используйте собственный мост IPC, когда настольный узел владеет привилегированной границей среды выполнения через preload Electron, команды Tauri или другую границу structured-clone. Вызовы IPC намеренно опускают AbortSignal и держат двунаправленный входной поток вне нагрузки вызова, чтобы объект вызова чисто пересекал границу отрисовщика и узла:

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(), только когда обе стороны в одной области JavaScript и могут безопасно передавать AbortSignal и асинхронные итерируемые прямо в объекте вызова.

Если узел открывает подписки в стиле push, используйте createAxCodeGrpcNativeIpcBridgeFromChannels() или createAxCodeGrpcNativeIpcStream(), чтобы превратить обратные вызовы узла в потоки AsyncIterable, которых ждёт SDK gRPC. Эти помощники полезны для слушателей событий Tauri, обратных вызовов preload Electron и других систем IPC, которые возвращают функцию отписки, а не асинхронный генератор JavaScript.

Собственные узлы могут также открыть карту обработчиков вместо рукописного переключателя методов. Это полезно для команд Rust и Tauri, API preload Electron или настоящего локального сервера gRPC, который хочет привязывать операции среды выполнения AX Code метод за методом. Используйте дескрипторы методов, чтобы проверить, что каждая ожидаемая область покрыта, прежде чем отдавать мост коду отрисовщика:

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() намеренно является снимком, ориентированным на интерфейс, а не копией один к одному каждого маршрута HTTP. Используйте include, чтобы запросить только состояние, нужное текущему виду. Неуспешные подзапросы сообщаются в errors, а успешные поля всё ещё возвращаются, поэтому отсутствующая необязательная подсистема не мешает оболочке открыться.

Поток событий принимает необязательные фильтры types и sessionID. Собственные транспорты должны применять эти фильтры на стороне сервера. Мост совместимости HTTP применяет те же фильтры на стороне клиента поверх существующего маршрута SSE, чтобы код интерфейса сохранял одну форму подписки, пока реализуется собственный сервер.

startAxCodeGrpcHeadlessBackend() — предпочтительный временный запасной путь, когда узел всё ещё запускает ax-code serve внутри. Он не возвращает URL HTTP и заголовок авторизации, поэтому код отрисовщика можно писать против фасада gRPC и позже перенести на настоящий собственный транспорт gRPC без переписывания публичного API.

Настольные узлы на Node.js могут открыть настоящую конечную точку gRPC на HTTP/2 из того же собственного моста через @defai-digital/ax-code-sdk/grpc/node. Это для привилегированных процессов узла, а не для кода отрисовщика:

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 смоделирован как двунаправленный поток gRPC. Мост HTTP приспосабливает этот поток к существующему маршруту WebSocket ради совместимости. Собственным узлам интерфейса следует реализовать его поверх локального gRPC, сокета Unix или именованного канала, а не открывать маршрут WebSocket коду отрисовщика.

Когда настоящий транспорт gRPC доступен, передайте его в createAxCodeGrpcClient({ transport }). Высокоуровневый клиент остаётся тем же.

Поза безопасности

Для настольных приложений предпочитайте такой порядок:

1. SDK в процессе, когда интерфейс на TypeScript и может безопасно загрузить среду выполнения.
2. Локальный транспорт gRPC или собственный транспорт через loopback, сокет Unix или именованный канал.
3. Неинтерактивный мост HTTP/SSE с порождёнными одноразовыми учётными данными Basic Auth.
4. Не открывайте AX Code по сетевому HTTP.

Мост совместимости gRPC с HTTP и помощники сервера HTTP под управлением SDK принимают только буквальные конечные точки loopback. Устаревшие параметры allowRemoteHttpBridge и allowNetworkBind сохранены для совместимости исходного кода, но не обходят политику только локального доступа. Держите /doc ограниченным сервером loopback.

Мост совместимости HTTP по умолчанию отвергает повышения WebSocket с другого источника. Добавляйте источник в явный список CORS сервера, только если этот источник браузера входит в доверенную оболочку приложения.

Не открывайте полный API HTTP, WebSocket PTY и документацию OpenAPI произвольным WebView. Если WebView используется, держите его отрисовщиком и проводите привилегированные операции через собственный узел с помощью фасада gRPC или собственного фасада.