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

@defai-digital/ax-code-sdk cho ứng dụng

SDK TypeScript để tích hợp môi trường chạy tác nhân lập trình AX Code vào ứng dụng của bạn.

Dùng nó để giám sát một môi trường chạy AX Code đã ký, tương thích, qua các ranh giới không tương tác hoặc gRPC có kiểu, tiêu thụ sự kiện phát luồng, chiếu trạng thái phiên, và kiểm thử các tích hợp ứng dụng. Các máy chủ nguồn cố ý cung cấp gói môi trường chạy riêng cũng có thể dùng bộ chuyển đổi trong tiến trình createAgent().

Cài đặt

pnpm add jsr:@defai-digital/ax-code-sdk@2.6.7

deno add jsr:@defai-digital/ax-code-sdk@2.6.7

npx jsr add @defai-digital/ax-code-sdk@2.6.7

Cần Node.js 26+ (hoặc Deno với tương thích Node). Các phiên bản Node.js cũ hơn không được hỗ trợ. Trợ giúp vòng đời không tương tác và gRPC kỳ vọng một tệp thực thi ax-code đã ký trên PATH, hoặc một đường dẫn tuyệt đối truyền vào dưới dạng binary. Phiên bản SDK và môi trường chạy độc lập nhau. Hãy kiểm tra giao thức khả năng của môi trường chạy trước khi bật tính năng ứng dụng; riêng việc kiểm tra phiên bản SDK không thiết lập tương thích môi trường chạy.

Tên gói không gian làm việc @ax-code/sdk là riêng của monorepo này. Người dùng công khai luôn cài @defai-digital/ax-code-sdk từ JSR.

Di chuyển API báo cáo

AX Code 7.24.1 thay báo cáo đồ thị DRE bằng Run Report. Các tích hợp báo cáo phải dùng ax-code run-report và các tuyến HTTP /run-report; lệnh dre-graph cũ và các tuyến /dre-graph đã bị gỡ. Các thao tác SDK đã sinh hiện là getRunReportSessionSessionId và getRunReportSessionSessionIdFingerprint, thay các thao tác getDreGraph tương ứng.

Hãy nâng cấp tích hợp báo cáo và môi trường chạy cùng nhau. Các bề mặt tích hợp khác vẫn cần kiểm tra khả năng môi trường chạy của riêng chúng.

Chọn bề mặt tích hợp

Ứng dụng công khai nên dùng headless hoặc grpc với một môi trường chạy AX Code đã ký, tương thích. HTTP/OpenAPI nằm sau các SDK đó như lớp dự phòng và chẩn đoán. Các đường con @defai-digital/ax-code-sdk/v2 cũ vẫn còn để tương thích môi trường chạy; tích hợp mới không nên bắt đầu từ đó.

createAgent() tải gói nguồn riêng ax-code tại thời điểm gọi. Môi trường chạy không được phát hành trên JSR.

Bắt đầu nhanh (không tương tác)

import { createHeadlessClient, startHeadlessBackend } from "@defai-digital/ax-code-sdk/headless"

const directory = process.cwd()
const backend = await startHeadlessBackend({ directory })
try {
  const client = createHeadlessClient({
    baseUrl: backend.url,
    directory,
    headers: backend.headers,
  })
  const session = await client.createSession({ title: "SDK example" })
  await client.sendPrompt(session.id, {
    parts: [{ type: "text", text: "Summarize this project." }],
  })
} finally {
  await backend.close()
}

Máy chủ máy tính có thể truyền một đường dẫn tuyệt đối đã xác minh dưới dạng binary. Xem example/headless-app.ts để có một vòng lặp ứng dụng dựa trên phép chiếu.

Backend không tương tác

startHeadlessBackend sinh ax-code serve trên một cổng loopback ngẫu nhiên, tạo thông tin xác thực dùng một lần, chờ /global/health, và trả về một tay cầm. close() gửi SIGTERM, rồi SIGKILL.

import {
  startHeadlessBackend,
  createHeadlessClient,
  createHeadlessProjectionState,
  applyHeadlessProjectionEvent,
} from "@defai-digital/ax-code-sdk/headless"

const backend = await startHeadlessBackend({ directory: "/path/to/workspace" })
try {
  const client = createHeadlessClient({ baseUrl: backend.url, headers: backend.headers })
  const state = createHeadlessProjectionState()
  const session = await client.createSession({ title: "My session" })

  await client.sendPrompt(session.id, { parts: [{ type: "text", text: "Review this project" }] })
  for await (const event of client.subscribe()) {
    applyHeadlessProjectionEvent(state, event)
    if (state.session_status[session.id]?.type === "idle") break
  }
} finally {
  await backend.close()
}

createHeadlessProjectionState và applyHeadlessProjectionEvent là TypeScript thuần. Giao diện ứng dụng nên coi permission, question, session_diff, todo, session_status và session_error là trạng thái chính. Câu trả lời tự chủ là tùy chọn bật; ứng dụng được giám sát nên kết xuất các yêu cầu quyền và câu hỏi đang chờ.

Phép chiếu tự chủ giữ quyền isolation_escalation, bash_destructive, ops_approve, webmcp, hook và computer ở trạng thái chờ, cũng như mọi yêu cầu có siêu dữ liệu đặt requireInteractive: true. Bên tiêu thụ phải nhận một câu trả lời của người một cách tường minh cho các yêu cầu này.

gRPC / máy tính gốc

Dùng @defai-digital/ax-code-sdk/grpc khi một máy chủ gốc đã sở hữu vận chuyển (Electron preload, Tauri, Rust, HTTP/2).

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

const backend = await startAxCodeGrpcHeadlessBackend({ directory: "/path/to/workspace" })
try {
  const client = backend.client
  await client.bootstrap.load({
    include: { sessions: true, providers: true, path: true, vcs: true },
  })
  const session = (await client.createSession({ title: "Desktop session" })) as { id: string }
  await client.sendPrompt(session.id, { parts: [{ type: "text", text: "Review this project" }] })
  const protoUrl = resolveAxCodeGrpcProtoUrl()
} finally {
  await backend.close()
}

• createAxCodeGrpcClientFromNativeIpc() — IPC structured-clone (preload / Tauri).
• createAxCodeGrpcClientFromNativeBridge() — cùng miền JavaScript, với AbortSignal và các iterable bất đồng bộ.
• createAxCodeGrpcClientFromNativeHandlers() — gắn tên phương thức vào trình xử lý có kiểu; requireHandlers thất bại nhanh khi có khoảng trống.
• startAxCodeGrpcNodeHttp2Server() từ @defai-digital/ax-code-sdk/grpc/node — phơi bày cùng cầu nối như một điểm cuối gRPC HTTP/2 cục bộ.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — danh mục phương thức chuẩn cho danh sách cho phép và tên proto.

createAxCodeGrpcClientFromHttp() chỉ dùng loopback. Tài sản proto là packages/sdk/proto/ax_code/v1/headless.proto và được phân giải lúc chạy bằng resolveAxCodeGrpcProtoUrl().

Tác nhân trong tiến trình (chỉ máy chủ nguồn)

Đường này cần gói môi trường chạy riêng ax-code. Đây không phải ranh giới tích hợp ứng dụng công khai.

import { createAgent, tool } from "@defai-digital/ax-code-sdk"
import { z } from "zod"

const deploy = tool({
  name: "deploy_staging",
  description: "Deploy the current branch to staging",
  parameters: z.object({
    service: z.enum(["api", "web", "worker"]),
    skipTests: z.boolean().default(false),
  }),
  execute: async ({ service }) => ({ url: `https://staging.example.com/${service}` }),
})

const agent = await createAgent({ directory: "/repo", tools: [deploy] })

const result = await agent.run("Fix the login bug")
for await (const event of agent.stream("Explain this codebase")) {
  if (event.type === "text") process.stdout.write(event.text)
}
const session = await agent.session()
await session.run("Read src/auth/index.ts")
await agent.dispose()

Xác thực được tự phát hiện từ biến môi trường, được tiêm qua auth: { provider, apiKey }, hoặc lấy từ ax-code providers login.

import { ProviderError, ToolError, TimeoutError } from "@defai-digital/ax-code-sdk"

try {
  await agent.run("Deploy to prod")
} catch (e) {
  if (e instanceof ProviderError && e.isRetryable) console.log("Rate limited, retry later")
  else if (e instanceof ToolError) console.log(`Tool "${e.tool}" failed: ${e.message}`)
  else if (e instanceof TimeoutError) console.log(`Timed out after ${e.timeout}ms`)
}

Thêm ví dụ: example/programmatic.ts.

Kiểm thử

import { createMockAgent, assertToolSuccess } from "@defai-digital/ax-code-sdk/testing"

test("CI bot scans for CVEs", async () => {
  const agent = createMockAgent({
    replies: ["Found 2 CVEs. Opening PR to bump versions."],
    toolCalls: [{ tool: "grep", input: { pattern: "CVE-" }, output: "CVE-2025-1234" }],
  })
  const result = await agent.run("scan for CVEs")
  expect(result.text).toContain("2 CVEs")
  assertToolSuccess(result, "grep")
})

Tương thích phiên bản

import { SDK_VERSION, isSDKVersionCompatible } from "@defai-digital/ax-code-sdk"

console.log(SDK_VERSION)
if (!isSDKVersionCompatible("^2.0.0")) {
  throw new Error("Incompatible SDK version")
}

Điều khiển yêu cầu và điều hướng

SDK 2.6 thêm các điều khiển tùy chọn cho yêu cầu không tương tác. Các lời gọi sẵn có giữ hành vi của chúng; không áp hạn mặc định.

import { createHeadlessClient, HeadlessRequestError } from "@defai-digital/ax-code-sdk/headless"

const client = createHeadlessClient({
  baseUrl: backend.url,
  headers: backend.headers,
  directory,
  requestOptions: { timeoutMs: 30_000 },
})
const compatibility = await client.checkCompatibility({ requiredFeatures: ["sessions", "asyncPrompt"] })
if (!compatibility.compatible) throw new Error(compatibility.issues.join("; "))

const controller = new AbortController()
const state = await client.steering(sessionID, { signal: controller.signal, timeoutMs: 5_000 })
if (state.generation) {
  try {
    const receipt = await client.steer(
      sessionID,
      {
        expectedGeneration: state.generation,
        clientID, // Keep this id with the correction so uncertain outcomes can be reconciled.
        text: "Use the existing session contract.",
      },
      { signal: controller.signal },
    )
    console.log(receipt.status)
  } catch (error) {
    if (error instanceof HeadlessRequestError && error.status === 409) {
      console.log("Correction conflicts with a prior request; reconcile the steering state.")
    } else {
      throw error
    }
  }
}

client.taskQueue.steer(taskID) phơi bày điểm cuối phần theo dõi đã xếp hàng nguyên tử. Kết quả generation_not_active của nó để hàng không đổi. SDK trả về biên nhận và lý do từ chối nguyên văn. accepted nghĩa là đã được nhận cho một ranh giới vòng lặp sau; applied nghĩa là đã được nhận bền vững tại ranh giới đó, còn việc nhà cung cấp hoàn tất vẫn tách riêng. Biên nhận thuộc tiến trình cục bộ và có giới hạn, nên sự vắng mặt của chúng sau khi khởi động lại không chứng minh một bản sửa chưa từng được áp dụng.

requestOptions cung cấp mặc định cho mọi yêu cầu tiện ích không tương tác và lệnh, gồm thao tác quy trình và hàng đợi tác vụ. Các phương thức phiên/lệnh cốt lõi và điều hướng nhận ghi đè theo từng lời gọi; timeoutMs: 0 tắt một hạn mặc định. Các đăng ký dùng signal riêng, và client.client giữ các điều khiển của máy khách đã sinh. Một HeadlessTransport tùy chỉnh nhận tín hiệu và nên giải phóng tài nguyên đang chờ khi nó bị hủy.

Việc hủy HTTP và IPC dừng chờ cục bộ. Một đột biến đã điều phối vẫn có thể thực thi; hãy đối chiếu trạng thái phiên/hàng đợi trước khi hành động tiếp. Không vận chuyển nào thử lại đột biến. Hạn thời gian ném TimeoutError; việc bên gọi hủy giữ lý do của tín hiệu. Phản hồi HTTP và IPC không thành công ném HeadlessRequestError với status, body, method và path; khung lỗi giao thức IPC giữ IpcTransportError.

Tương thích môi trường chạy và nâng cấp từ SDK 2.5

Đường cơ sở hợp đồng đã sinh hiện tại là nguồn AX Code v7.23.0. SDK 2.6 không suy ra tính năng chưa được quảng bá từ phiên bản môi trường chạy. Danh mục khả năng hiện tại không quảng bá điều hướng một cách riêng; hãy kiểm tra điểm cuối đọc trước khi đưa ra điều hướng, và xử lý lỗi tuyến không được hỗ trợ. SDK 2.6 giữ các điểm vào đã sinh và không tương tác sẵn có. Siêu dữ liệu lỗi phản hồi mới và điều khiển yêu cầu là phần bổ sung; mã bắt Error vẫn hoạt động.

Ứng dụng nâng các ghim cũ hơn nên xác minh môi trường chạy đã ký trước, rồi kiểm thử thương lượng khả năng, phép chiếu sự kiện, quyền/câu hỏi đang chờ, việc hủy, và tắt backend. Thay đổi ghim của bên tiêu thụ thuộc kho đang tiêu thụ sau khi SDK đích được phát hành. Hãy xác thực gói đã biên dịch tại chỗ bằng pnpm --dir packages/sdk/js run test:consumer; việc này kiểm tra các import công khai, khai báo và tài sản proto trong một bộ thử tách biệt, không có gói nguồn môi trường chạy riêng.

Tích hợp đa ngôn ngữ

Gói này là SDK TypeScript/JavaScript của bên thứ nhất. Với Python, Go, Java, Rust hoặc các môi trường chạy khác, hãy sinh từ proto gRPC của kho hoặc dùng ranh giới CLI/môi trường chạy do tích hợp đó sở hữu.

Di chuyển từ @ax-code/sdk 1.4.0

Đường con ./programmatic vẫn xuất lại điểm vào mặc định; hãy coi nó là đã lỗi thời.

Giấy phép

Apache-2.0