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

HTTP 与 OpenAPI 兼容

状态：生效范围：当前状态最近审阅：2026-09-02 负责人：ax-code sdk

AX Code 有两条集成路径：

下方的 JSR 包名已可发布，但尚未收到第一个公开版本。

第一方 TypeScript 和 JavaScript 应用集成使用 @defai-digital/ax-code-sdk。
第一方应用和桌面 GUI 工作使用 @defai-digital/ax-code-sdk/headless 或 @defai-digital/ax-code-sdk/grpc。
当需要另一种语言或兼容进程边界时，使用 ax-code serve 加上 OpenAPI 契约。
当 AX Code 拥有传输两端时，第一方桌面 GUI 工作使用原生 SDK 传输。

HTTP/OpenAPI 路径是兼容性和生成客户端的基础设施。它让 Python、Go、Java、Rust 和其他客户端调用同一服务器 API，而 AX Code 不必承诺为每种语言维护完整的官方包。当 gRPC/原生契约可用时，不应把它当作第一方桌面 GUI 内部首选的特权桥接，它也不再作为第一方 JavaScript SDK 子路径暴露。

选择路径

需求	推荐路径	原因
同一进程中的 TypeScript 或 JavaScript	源码工作区 `createAgent()` 适配器	仅当私有 AX Code 运行时源包被有意解析时可用
第一方桌面/原生 GUI	`@defai-digital/ax-code-sdk/grpc`	更窄的无头契约、服务器流、对元数据与截止时间友好，且更少暴露给 WebView
带本地后端的 TypeScript 或 JavaScript	`@defai-digital/ax-code-sdk/headless`	保持生命周期和事件投影的类型，而不暴露完整的 HTTP SDK 表面
Python、Go、Java、Rust 或其他运行时	从 `packages/sdk/openapi.json` 生成客户端	复用 HTTP 契约，而不为每种语言增加第一方包维护
CI、自动化或一次性脚本	针对 `ax-code serve` 的 HTTP 调用	部署模型简单，进程隔离容易

目前什么是官方的

@defai-digital/ax-code-sdk 是第一方 TypeScript 和 JavaScript SDK；其公共应用边界是 headless 和 grpc。
@defai-digital/ax-code-sdk/grpc 是第一方可选的桌面/原生无头传输外观。
@defai-digital/ax-code-sdk/headless 是用于本地后端进程边界的第一方 TypeScript 和 JavaScript 生命周期/事件 SDK。
packages/sdk/openapi.json 是供生成 HTTP 客户端使用的 OpenAPI 快照。
生成的非 JavaScript 客户端作为 HTTP 上的集成受支持，但除非存在包负责人、测试和发布工作流，它们不是第一方发布的包。

基本 HTTP 流程

启动服务器：

export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096

@defai-digital/ax-code-sdk/headless 生命周期辅助程序会生成一次性 Basic Auth 密码，并自动用匹配的 Authorization 头接通返回的客户端。手动使用 ax-code serve 的用户应显式设置 AX_CODE_SERVER_PASSWORD，并发送对应的 Basic Auth 头。位于 /doc 的实时 OpenAPI 文档以及所有服务器端点都仅限环回。

SDK 管理的后端辅助程序始终拒绝诸如 0.0.0.0 的网络主机名。旧的 allowNetworkBind 选项为源码兼容而保留，但不再绕过仅本地策略。桌面 GUI 外壳应优先使用 @defai-digital/ax-code-sdk/grpc 或进程内 SDK 边界。

HTTP 运行时辅助程序不再是公共 JavaScript SDK 子路径。该包仍包含生成的客户端内部实现，因为 @defai-digital/ax-code-sdk/headless、gRPC HTTP 回退和旧式 AX Code 运行时代码使用它们，但外部集成应使用无头、gRPC，或从 OpenAPI 快照生成的客户端，而不是从 @defai-digital/ax-code-sdk 导入 HTTP 运行时值。

检查服务器健康：

curl http://127.0.0.1:4096/global/health

在把快照校验为 JSON 和 OpenAPI 之后，从 OpenAPI 快照创建生成的客户端：

openapi-python-client generate --path packages/sdk/openapi.json

oapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.go

openapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-java

生成护栏

把 OpenAPI 文档当作语言中立的契约。除非需要一小层人机工程包装，否则不要手工维护围绕单条路由的大型包装。

把 AX Code 版本和生成的客户端版本一起固定。如果服务器路由模式变化，重新生成客户端，并带着明确的兼容说明一起发布。

把生成的代码与手写辅助程序分开。生成的文件应易于替换，手写文件只应包含认证、默认值、重试和更高层的便利 API。

保留服务边界行为。非 JavaScript 客户端使用 HTTP 服务器路径，得不到进程内的 createAgent()、JavaScript 自定义工具执行或 @defai-digital/ax-code-sdk/testing 实用工具。

在把生成的客户端提升为第一方之前，先覆盖困难部分：

OpenAPI 校验在 CI 中运行。
契约测试启动 ax-code serve 并调用有代表性的路由。
如果客户端暴露事件 API，则测试流式或 SSE 行为。
记录目录范围头和认证行为。
发布、版本管理和所有权是明确的。

SDK 包包含针对当前快照的轻量本地守卫：

pnpm run check:openapi

在 SDK 包内工作时也可使用包级命令：

pnpm --dir packages/sdk/js run validate:openapi

这会校验 packages/sdk/openapi.json 是可解析的 JSON，声明 OpenAPI 3.x，并包含生成客户端所需的核心路由。