Tải AX Code · Miễn phíTài liệu
AX Code.
vi
English繁體中文简体中文日本語한국어FrançaisDeutschBahasa IndonesiaItalianoPortuguês (Brasil)РусскийEspañolTürkçeTiếng Việt
Bắt đầu

Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh

Vận chuyển gRPC và SDK gốc

Trạng thái: Đang hoạt động Phạm vi: hợp đồng vận chuyển gốc cho máy tính Xem xét lần cuối: 2026-09-02 Chủ sở hữu: sdk ax-code

AX Code giờ phơi bày một hợp đồng vận chuyển dạng gRPC tùy chọn cho ứng dụng máy tính và GUI gốc. Hợp đồng cố ý hẹp hơn cây tuyến HTTP/OpenAPI đầy đủ: nó tập trung vào các khả năng môi trường chạy không tương tác mà một GUI cần để có cảm giác gốc, đồng thời giữ HTTP/OpenAPI sẵn có bên trong cho tương thích, chẩn đoán và máy khách đã sinh.

Khuyến nghị

Dùng vận chuyển gRPC/gốc làm ranh giới ưu tiên cho ứng dụng máy tính bên thứ nhất. Giữ HTTP/SSE bật như bề mặt dự phòng và gỡ lỗi.

Nhu cầu Đường được khuyến nghị Lý do
GUI máy tính bên thứ nhất @defai-digital/ax-code-sdk/grpc Hợp đồng lệnh/sự kiện ổn định, sẵn sàng phát luồng, siêu dữ liệu và hạn thân thiện với gốc
Tự động hóa TypeScript trong cùng tiến trình @defai-digital/ax-code-sdk với createAgent() Chi phí thấp nhất và hỗ trợ công cụ tùy chỉnh
Trình duyệt, dự phòng WebView, hoặc chẩn đoán dễ HTTP/SSE với @defai-digital/ax-code-sdk/headless Hoạt động với fetch, curl, công cụ phát triển trình duyệt và các điều khiển xác thực máy chủ hiện tại
Tích hợp ngoài JS Proto gRPC hoặc máy khách sinh từ OpenAPI Hỗ trợ công cụ rộng mà không phải bảo trì SDK HTTP bên thứ nhất
Nhúng máy chủ Rust Dịch vụ gRPC/gốc hoặc cầu tiến trình con Tránh phơi cây tuyến HTTP đầy đủ cho vỏ ứng dụng

Vì sao không gỡ HTTP

Gỡ HTTP/OpenAPI khỏi môi trường chạy sẽ gỡ đường tương thích dễ kiểm tra và dễ mang nhất. SDK JavaScript không nên phơi các đường con máy khách/máy chủ HTTP như bề mặt hỗ trợ bên thứ nhất, nhưng cầu HTTP nội bộ vẫn hữu ích cho chẩn đoán, khởi động backend không tương tác sẵn có, và quy trình máy khách đã sinh. Các điều khiển máy chủ HTTP hiện tại gồm gắn chỉ loopback bắt buộc, thông tin xác thực Basic Auth đã sinh trong trợ giúp backend do SDK quản lý, kiểm tra origin trên yêu cầu đột biến từ trình duyệt, xác thực thư mục, giới hạn tốc độ yêu cầu, và tài liệu OpenAPI trực tiếp chỉ loopback.

Vận chuyển không phải nguồn độ trễ chủ đạo cho các lượt tác nhân bình thường. Lời gọi LLM, lệnh shell, IO tệp, lập chỉ mục, khởi động LSP và thực thi công cụ thường đắt hơn JSON localhost. gRPC vẫn hữu ích cho GUI máy tính vì nó cung cấp hợp đồng API gốc sạch hơn, hạn thời gian, siêu dữ liệu, phát luồng máy chủ, và một đường tới vận chuyển ổ cắm Unix hoặc ống đặt tên mà không kéo một API hướng trình duyệt vào vỏ ứng dụng.

Hình dạng hợp đồng

Hợp đồng trung lập ngôn ngữ nằm tại packages/sdk/proto/ax_code/v1/headless.proto. Gói JSR cũng chứa proto đó như một tài sản. Máy chủ TypeScript định vị nó bằng resolveAxCodeGrpcProtoUrl(); trình sinh không phải JavaScript nên dùng hợp đồng kho chuẩn.

Mặt tiền TypeScript nằm tại @defai-digital/ax-code-sdk/grpc và bao phủ:

  • sức khỏe và sẵn sàng vòng đời
  • nhận nhật ký ứng dụng và điều khiển hủy/khởi động lại thực thể cho quản lý vòng đời máy chủ gốc
  • tạo phiên
  • lời nhắc, lệnh, shell, hủy, trả lời quyền và trả lời câu hỏi
  • ảnh chụp khởi động GUI cho nhà cung cấp, phiên, quyền, câu hỏi, đường dẫn, VCS, LSP, MCP, bộ định dạng và trạng thái lệnh
  • danh sách phiên, chi tiết, lịch sử thông điệp, chi tiết thông điệp, con, mục tiêu, việc cần làm, diff, rẽ nhánh, chia sẻ và tóm tắt
  • khám phá GUI và điều hướng không gian làm việc cho tác nhân, kỹ năng, dự án, đường dẫn, VCS, lệnh, cây/nội dung/trạng thái tệp, tìm văn bản/tệp/ký hiệu, và lược đồ công cụ
  • ngữ cảnh dự án, mẫu ngữ cảnh, làm mới/xóa bộ nhớ đệm, và chẩn đoán kế hoạch đang chờ của engine gỡ lỗi
  • liệt kê/trả lời/từ chối quyền và câu hỏi đang chờ cho luồng GUI được giám sát
  • nhà cung cấp, cấu hình, xác thực khóa API và cài đặt OAuth nhà cung cấp cho màn hình cài đặt GUI
  • điều khiển cài đặt môi trường chạy cho chế độ tự chủ, chế độ cô lập và định tuyến LLM thông minh
  • trạng thái MCP, khám phá tài nguyên, quản lý máy chủ động, OAuth, kết nối và ngắt
  • trạng thái LSP và bộ định dạng cho màn hình chẩn đoán và cài đặt
  • quản lý terminal PTY và phát luồng terminal hai chiều
  • bằng chứng phiên cho giao diện xem lại/gỡ lỗi
  • thao tác hàng đợi tác vụ
  • thao tác tác vụ đã lên lịch
  • mẫu quy trình, lần chạy quy trình, tóm tắt bảng điều khiển, ca đánh giá, routine quy trình và tạo tác lần chạy
  • sự kiện môi trường chạy do máy chủ phát luồng

Proto dùng tải JSON có cấu trúc cho thân lệnh và tải quy trình/tác vụ. Việc đó giữ vận chuyển ổn định trong khi lược đồ môi trường chạy AX Code tiếp tục tiến hóa nhanh.

@defai-digital/ax-code-sdk/grpc cũng xuất AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers() và assertAxCodeGrpcNativeHandlers(). Máy chủ gốc nên dùng các bộ mô tả và kiểm tra độ phủ này làm danh mục phương thức chuẩn khi xây bản đồ trình xử lý, bộ gắn dịch vụ gRPC, danh sách cho phép preload, hoặc cổng khởi động. Mỗi bộ mô tả gồm tên phương thức, đường phương thức đủ điều kiện, loại luồng, tên thông điệp yêu cầu và phản hồi proto, miền GUI, khả năng cầu HTTP, và độ ổn định hiện tại. Việc này giữ ranh giới vận chuyển gốc tường minh mà không phơi bày hay phản chiếu cây tuyến HTTP đầy đủ.

Cách dùng TypeScript

Dùng backend không tương tác gRPC do SDK quản lý khi máy chủ vẫn cần môi trường chạy HTTP sẵn có bên trong. Nó giữ cầu HTTP bên trong tiến trình máy chủ và chỉ trả về máy khách gRPC cùng tay cầm vòng đời:

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

Dùng một cầu IPC gốc khi máy chủ máy tính sở hữu ranh giới môi trường chạy đặc quyền qua Electron preload, lệnh Tauri, hoặc một ranh giới structured-clone khác. Lời gọi IPC cố ý bỏ AbortSignal và giữ luồng đầu vào hai chiều ngoài tải lời gọi để đối tượng lời gọi có thể vượt ranh giới bộ kết xuất/máy chủ một cách sạch:

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

Chỉ dùng createAxCodeGrpcClientFromNativeBridge() khi cả hai phía ở cùng miền JavaScript và có thể truyền an toàn AbortSignal cùng các iterable bất đồng bộ trực tiếp trong đối tượng lời gọi.

Nếu máy chủ phơi các đăng ký kiểu đẩy, hãy dùng createAxCodeGrpcNativeIpcBridgeFromChannels() hoặc createAxCodeGrpcNativeIpcStream() để chuyển callback máy chủ thành các luồng AsyncIterable mà SDK gRPC kỳ vọng. Các trợ giúp đó hữu ích cho trình nghe sự kiện Tauri, callback Electron preload, và các hệ IPC khác trả về một hàm hủy đăng ký thay vì một generator bất đồng bộ JavaScript.

Máy chủ gốc cũng có thể phơi một bản đồ trình xử lý thay vì tự viết một nhánh phương thức. Việc này hữu ích cho lệnh Rust/Tauri, API Electron preload, hoặc một máy chủ gRPC cục bộ thật muốn gắn các thao tác môi trường chạy AX Code theo từng phương thức. Dùng các bộ mô tả phương thức để xác thực mọi miền kỳ vọng đã được bao phủ trước khi trao cầu cho mã bộ kết xuất:

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() cố ý là một ảnh chụp hướng GUI chứ không phải bản sao một-một của mọi tuyến HTTP. Dùng include để chỉ yêu cầu trạng thái mà khung nhìn hiện tại cần. Các yêu cầu con thất bại được báo trong errors trong khi các trường thành công vẫn được trả về, nên một phân hệ tùy chọn thiếu không chặn vỏ máy tính mở.

Phát luồng sự kiện nhận các bộ lọc types và sessionID tùy chọn. Vận chuyển gốc nên áp dụng các bộ lọc đó phía máy chủ. Cầu tương thích HTTP áp dụng cùng bộ lọc phía máy khách trên tuyến SSE sẵn có để mã GUI giữ một hình dạng đăng ký trong lúc máy chủ gốc đang được triển khai.

startAxCodeGrpcHeadlessBackend() là phương án dự phòng tạm ưu tiên khi máy chủ vẫn khởi động ax-code serve bên trong. Nó không trả về URL HTTP hay tiêu đề ủy quyền, nên mã bộ kết xuất có thể được viết đối với mặt tiền gRPC và sau đó chuyển sang một vận chuyển gRPC gốc thật mà không viết lại API công khai.

Máy chủ máy tính dựa trên Node có thể phơi một điểm cuối gRPC HTTP/2 thật từ cùng cầu gốc bằng @defai-digital/ax-code-sdk/grpc/node. Việc này dành cho tiến trình máy chủ đặc quyền, không phải mã bộ kết xuất:

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

Phát luồng PTY được mô hình hóa như một luồng hai chiều gRPC. Cầu HTTP chuyển luồng đó sang tuyến WebSocket sẵn có để tương thích; máy chủ GUI gốc nên triển khai nó trên vận chuyển gRPC cục bộ, ổ cắm Unix, hoặc ống đặt tên của chúng thay vì phơi tuyến WebSocket cho mã bộ kết xuất.

Khi một vận chuyển gRPC thật sẵn có, hãy cung cấp nó cho createAxCodeGrpcClient({ transport }). Máy khách cấp cao vẫn như cũ.

Tư thế bảo mật

Với ứng dụng máy tính, hãy ưu tiên thứ tự này:

  1. SDK trong tiến trình khi GUI là TypeScript và có thể tải môi trường chạy một cách an toàn.
  2. Vận chuyển gRPC/gốc cục bộ qua loopback, ổ cắm Unix, hoặc ống đặt tên.
  3. Cầu không tương tác HTTP/SSE với thông tin xác thực Basic Auth dùng một lần đã sinh.
  4. Đừng phơi AX Code qua HTTP mạng.

Cầu tương thích HTTP của gRPC và các trợ giúp backend HTTP do SDK quản lý chỉ nhận endpoint loopback nguyên văn. Các tùy chọn cũ allowRemoteHttpBridge và allowNetworkBind được giữ để tương thích nguồn nhưng không vòng qua chính sách chỉ cục bộ. Hãy giữ /doc giới hạn ở máy chủ loopback.

Cầu tương thích HTTP từ chối nâng cấp WebSocket xuyên origin theo mặc định. Chỉ thêm một origin vào danh sách cho phép CORS máy chủ tường minh khi origin trình duyệt đó là một phần của vỏ ứng dụng đáng tin.

Đừng phơi API HTTP đầy đủ, WebSocket PTY, hoặc tài liệu OpenAPI cho WebView tùy ý. Nếu dùng WebView, hãy giữ nó như bộ kết xuất và định tuyến các thao tác đặc quyền qua máy chủ gốc bằng mặt tiền gRPC/gốc.