本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

@defai-digital/ax-code-sdk 软件包

用于把 AX Code 编码智能体运行时集成进你自己应用的 TypeScript SDK。

用它通过带类型的无头或 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