本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文

@defai-digital/ax-code-sdk 套件

這是 TypeScript SDK，用來把 AX Code 程式開發代理程式的執行環境整合進你自己的應用程式。

用它透過有型別的 無介面 或 gRPC 邊界，監督相容且已簽章的 AX Code 執行環境、取用串流事件、投影工作階段狀態，並測試應用程式整合。刻意提供私有執行環境套件的來源主機，也可以使用處理程序內的 createAgent() 配接器。

安裝

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

需要 Node.js 26+（或具備 Node 相容性的 Deno）。較舊的 Node.js 版本不受支援。無介面與 gRPC 的生命週期輔助函式，預期有已簽章的 ax-code 執行檔位於 PATH，或把絕對路徑當作 binary 傳入。SDK 版本與執行環境版本彼此獨立。啟用應用程式功能之前，請先檢查執行環境的能力協定；只檢查 SDK 版本並不能建立執行環境相容性。

工作區套件名稱 @ax-code/sdk 是這個單一儲存庫私有的。公開的取用者一律從 JSR 安裝 @defai-digital/ax-code-sdk。

報告 API 遷移

AX Code 7.24.1 以執行報告取代 DRE 圖表報告。報告整合必須使用 ax-code run-report 與 /run-report HTTP 路由；舊的 dre-graph 指令與 /dre-graph 路由已經移除。產生的 SDK 操作現在是 getRunReportSessionSessionId 與 getRunReportSessionSessionIdFingerprint，取代對應的 getDreGraph 操作。

請同時升級報告整合與執行環境。其他整合表面仍須各自檢查執行環境能力。

選擇整合表面

公開應用程式應使用 headless 或 grpc，並搭配相容且已簽章的 AX Code 執行環境。HTTP 與 OpenAPI 留在這些 SDK 後面，作為後援與診斷層。舊的 @defai-digital/ax-code-sdk/v2 子路徑仍為執行環境相容性保留；新的整合不應從那裡開始。

createAgent() 會在呼叫時載入私有的 ax-code 來源套件。該執行環境沒有在 JSR 上發行。

快速開始（無介面）

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

桌面主機可以把已驗證的絕對路徑當作 binary 傳入。以投影為基礎的應用程式迴圈，請見 example/headless-app.ts。

無介面後端

startHeadlessBackend 會在隨機的本機回送連接埠上產生 ax-code serve，產生一次性憑證，等待 /global/health，並傳回控制代碼。close() 會先送 SIGTERM，再送 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 與 applyHeadlessProjectionEvent 是純 TypeScript。應用程式介面應把 permission、question、session_diff、todo、session_status 與 session_error 當作主要狀態。自主回覆是選擇加入的；受監督的應用程式應呈現待處理的權限與提問請求。

自主投影會讓 isolation_escalation、bash_destructive、ops_approve、webmcp、hook 與 computer 的權限保持待處理，中繼資料設了 requireInteractive: true 的任何請求也一樣。取用者必須為這些請求取得明確的人工回覆。

gRPC 與原生桌面

當原生主機已經持有傳輸時（Electron preload、Tauri、Rust、HTTP/2），請使用 @defai-digital/ax-code-sdk/grpc。

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（preload 或 Tauri）。
• createAxCodeGrpcClientFromNativeBridge()：同一個 JavaScript 領域，帶有 AbortSignal 與非同步可迭代物件。
• createAxCodeGrpcClientFromNativeHandlers()：把方法名稱繫結到有型別的處理函式；有缺口時 requireHandlers 會立即失敗。
• startAxCodeGrpcNodeHttp2Server()，來自 @defai-digital/ax-code-sdk/grpc/node：把同一個橋接公開為本機 HTTP/2 gRPC 端點。
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods()：供允許清單與 proto 名稱使用的標準方法目錄。

createAxCodeGrpcClientFromHttp() 僅限本機回送。proto 資產是 packages/sdk/proto/ax_code/v1/headless.proto，並在執行時以 resolveAxCodeGrpcProtoUrl() 解析。

處理程序內的代理程式（僅限來源主機）

這條路徑需要私有的 ax-code 執行環境套件。它不是公開的應用程式整合邊界。

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

驗證會從環境變數自動偵測、透過 auth: { provider, apiKey } 注入，或取自 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`)
}

更多範例：example/programmatic.ts。

測試

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

版本相容性

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

請求控制與導向

SDK 2.6 為無介面請求加上選擇性控制。既有呼叫保持原有行為；不會施加預設期限。

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) 公開不可分割的、已排入佇列之後續訊息端點。它的 generation_not_active 結果會讓該列保持不變。SDK 會原樣傳回回執與拒絕原因。accepted 表示已准入，留待之後的迴圈邊界；applied 表示在該邊界已持久准入，供應商是否完成仍然分開。回執只存在於處理程序內，而且有上限，因此重新啟動後找不到，並不能證明更正從未套用。

requestOptions 為所有無介面的便利請求與指令提供預設值，包含工作流程與工作佇列操作。核心的工作階段與指令方法，以及導向，都接受每次呼叫的覆寫；timeoutMs: 0 會停用預設期限。訂閱使用自己的 signal，client.client 則保留產生之用戶端的控制。自訂的 HeadlessTransport 會收到該信號，並應在中止時釋放待處理資源。

HTTP 與 IPC 的取消會停止本機等待。已經分派的變更仍可能執行；採取進一步動作之前，請先核對工作階段與佇列狀態。兩種傳輸都不會重試變更。期限會拋出 TimeoutError；呼叫者中止會保留信號的原因。非成功的 HTTP 與 IPC 回應會拋出 HeadlessRequestError，並帶有 status、body、method 與 path；IPC 協定錯誤框架會保留 IpcTransportError。

執行環境相容性，以及從 SDK 2.5 升級

目前產生的契約基準是 AX Code 來源 v7.23.0。SDK 2.6 不會從執行環境版本推論未宣告的功能。目前的能力目錄不會另外宣告導向；提供導向之前請先檢查讀取端點，並處理不支援路由的錯誤。SDK 2.6 保留既有的產生進入點與無介面進入點。新的回應錯誤中繼資料與請求控制都是新增的；捕捉 Error 的程式碼仍然可用。

正在升級較舊釘選的應用程式，應先驗證已簽章的執行環境，再測試能力協商、事件投影、待處理的權限與提問、取消，以及後端關閉。取用端的釘選變更，應在目標 SDK 發行之後，放進取用它的儲存庫。請用 pnpm --dir packages/sdk/js run test:consumer 在本機驗證編譯後的套件；這會在隔離的測試夾具中檢查公開匯入、宣告與 proto 資產，而不含私有的執行環境來源套件。

跨語言整合

這個套件是官方第一方的 TypeScript 與 JavaScript SDK。若是 Python、Go、Java、Rust 或其他執行環境，請從儲存庫的 gRPC proto 產生，或使用該整合所擁有的 CLI 與執行環境邊界。

從 @ax-code/sdk 1.4.0 遷移

./programmatic 子路徑仍然重新匯出預設進入點；請把它視為已淘汰。

授權

Apache-2.0