#SDK 与 API

A3S Code 提供 Rust、Node.js、Python 和 Go SDK。想直接使用终端应用，则安装 a3s CLI。版本号与发布状态以对应 Registry 和 GitHub Releases 为准。

#安装

# Rust
cargo add a3s-code-core

# Node.js
npm install @a3s-lab/code

# Python
python -m pip install a3s-code

# Go
go get github.com/A3S-Lab/Code/sdk/go/v8

#Python Wheel 平台（v8.2.0）

PyPI 上的 a3s-code 是一个纯 Python Bootstrap。首次导入时，它会从 v8.2.0 GitHub Release 下载匹配的 Native Wheel，并根据 SHA-256 Manifest 校验。Native Wheel 使用 CPython 3.10 Stable ABI（cp310-abi3），同一个 Asset 支持 CPython 3.10 至 3.14：

每个 Wheel 都包含 a3s_code/moli/<moli executable> 和来源记录。Bootstrap 会把 Native Extension 与 Sidecar 解压到按用户共享的缓存；进程锁与原子替换确保多个 应用同时首次启动时只安装一次，后续进程复用同一个已校验的 Moli。Linux musl 没有列出，因为上游 Moli 没有 musl 资产；该平台请使用系统/显式 Moli，或选择 Chrome/Lightpanda 后端。

Intel Mac 使用 macOS 12 或更高版本时，应使用实际运行应用的同一个解释器安装：

python3.14 -m ensurepip --upgrade  # 只有该解释器没有 pip 时才需要
python3.14 -m pip install --upgrade pip
python3.14 -m pip install a3s-code

如果 python3.14 -m pip 报告 No module named pip，问题发生在 Python 环境中， 还没有进入 A3S Code。请先为该解释器初始化或重新安装 pip，再重试。Intel Wheel 使用 x86_64 并以 macOS 12 为最低版本；该构建不包含可选的本地 ONNX Embedding 适配器。在 Intel 平台请保持 Workspace Retrieval 的 Model-free 模式，或配置明确 授权的远程 Embedding Provider。

#Go 模块与桥接程序

Go 1.23 及以上版本使用纯 Go API，不需要 CGO。一个长驻的 a3s-code-go-bridge 进程持有原生 Runtime，通过带版本号的 JSONL 协议传输 多路复用请求和 EventEnvelopeV1。

包含 Go SDK 的仓库 Release 会发布路径前缀 Tag sdk/go/vX.Y.Z，它与 vX.Y.Z Release 对应，同时提供 a3s-code-go-bridge-SHA256SUMS、独立桥接 程序和包含对应 Moli Sidecar 的 Bundle：

从 GitHub Releases 下载桥接程序， 使用发布的 SHA-256 文件校验，并确保它与 Go module 版本相同。可以将程序加入 PATH、设置 A3S_CODE_GO_BRIDGE，或传入 code.WithBridgePath：

export A3S_CODE_GO_BRIDGE=/opt/a3s/bin/a3s-code-go-bridge

$env:A3S_CODE_GO_BRIDGE = 'C:\a3s\a3s-code-go-bridge.exe'

没有对应架构的 Release 资产时，可以从源码构建：

bash .github/setup-workspace.sh
cargo build --release --package a3s-code-go-bridge --bin a3s-code-go-bridge

code.Create 会对传输协议、事件协议和完整操作清单执行 fail-closed 握手。 Go 错误使用稳定的 *code.Error 错误码，Context 取消和 Deadline 仍可通过 errors.Is 判断。桥接程序覆盖完整的可序列化 Agent/Session 能力，以及由 Go 实现的 Hook、预算守卫、斜杠命令和流水线回调。任意 Rust trait 对象仍属于 Rust 原生扩展机制；其他 SDK 通过等价的值配置、回调、直接工具或 MCP 边界接入。

#四种 SDK 的共用能力

四种 SDK 使用相同的 Session 生命周期、事件格式和 Snapshot。界面可以订阅同一套 AgentEvent / EventEnvelopeV1，保存后也可以按 Session ID 恢复。

#优先级调度器接口

v6.9 为四种 SDK 增加相同的 Agent 级调度器控制。创建 Session 时选择 urgent、 interactive、foreground、background 或 maintenance，再从 Agent 或任意 同级 Session 读取共享占用快照：

快照包含全局容量、活动与等待总数、按优先级分组的计数和关闭状态。顺序、老化、取消、 配置与完整示例见任务优先级调度器。

#安全点运行控制接口

四种 SDK 都能在不发起第二个对话操作的情况下，调整或中断当前活动 Run：

请求使用不可变 Run ID、可选乐观回合守卫、截止时间与幂等键。回执会区分 accepted、 applied、settled 与 rejected；共用 run_control_applied 事件记录安全点应用。 完整示例与生命周期语义见会话。

#工具结果投影接口

四种 SDK 都能把同一个带版本的确定性投影策略固定到 Session：

Rust 与 Python 提供 context_efficient() 预设；Node.js 与 Go 接受相同的显式字段。策略 会写入快照，每个工具结果都会携带 a3s.code.tool-result-evidence.v1 元数据。字段值、 执行顺序、边界、损失模式与四种 SDK 示例见 工具。

共用指南会在完整的共用 SDK 能力面中，将 Go 与 Node.js、Python 并列展示。 可以从快速开始开始，再阅读 流式事件、直接工具、 会话、验证、MCP和 持久化。

四种 SDK 都能配置持久化、记忆、Local/S3 Workspace、Remote Git、权限与确认、 Hook、MCP、队列、确定性重放和编排。Rust 还可以接收自定义 LlmClient 或 ContextProvider 等任意进程内 trait 实现；其他语言通过回调、直接工具或 MCP 接入自定义服务。界面接入可从 Session 与事件流 开始。

#产品能力发现

本版本只有一份产品级能力契约。每个官方 SDK 的 sdk_capabilities()（或对应语言名称）都会返回相同顺序的 27 条能力记录。 每条记录包含稳定 ID、分类、规范操作名、描述和 host_owned 标志。 host_owned 只表示策略、凭据或外部生命周期由谁提供，不表示 SDK 不支持该操作。

能力清单覆盖 Agent/Runtime 生命周期、受治理工具、代码智能、Workspace 检索与工具、 记忆与 Cognitive Package、A3S Use 任务、模型适配器、结构化输出、MCP 与 Skill、 规划与优先级调度、可编程工作流、持久化、State Graph、发布/协议契约、网页搜索、 Moli、S3、Agent Server、OpenTelemetry、对话、运行观测和治理。应用应通过清单 协商可选能力，不要根据包文件或版本号猜测支持情况。

use a3s_code_core::{sdk_capabilities, sdk_capabilities_schema};

let capabilities = sdk_capabilities();
assert_eq!(sdk_capabilities_schema(), "a3s-code/sdk-capabilities/v1");
assert!(capabilities.iter().any(|item| item.id == "web_search"));

import { sdkCapabilities, sdkCapabilitiesSchema } from '@a3s-lab/code';

const capabilities = sdkCapabilities();
console.log(sdkCapabilitiesSchema(), capabilities.length);

from a3s_code import sdk_capabilities, sdk_capabilities_schema

capabilities = sdk_capabilities()
assert sdk_capabilities_schema() == "a3s-code/sdk-capabilities/v1"

capabilities, err := code.SDKCapabilities(ctx)
if err != nil {
	return err
}
fmt.Println(code.SDKCapabilitiesSchema(), len(capabilities))

#Moli Runtime 与网页搜索

web_search 使用 a3s-search v3.1.0，并默认用 Moli 执行 JavaScript 渲染搜索。 Runtime 的解析顺序固定为：显式 browserPath/A3S_CODE_MOLI_EXECUTABLE、打包 Sidecar、已校验的共享缓存、可发现的系统 Moli，最后才通过 HTTPS 下载固定版本。 缓存按用户、版本和目标平台隔离；独占安装锁与原子收据确保多个 a3s-code 进程同时启动时不会重复安装。严格离线时可设置 autoDownloadMoli: false（或对应语言字段）。

诊断调用只读；Ensure 调用只有在默认自动配置开启且 Release Manifest/SHA-256 校验 通过后才可能下载。v8.2.0 的上游 Moli 没有 Linux musl 资产；该平台请提供系统/显式 Moli，或选择 Chrome/Lightpanda 后端。

use a3s_code_core::{ensure_moli, moli_runtime_info, HeadlessConfig};
use std::time::Duration;

let config = HeadlessConfig::default();
let status = moli_runtime_info(Some(&config));
let executable = ensure_moli(&config, Duration::from_secs(120)).await?;
println!("{} {:?} {}", status.version, status.executable, executable.display());

import { BrowserBackend, ensureMoli, moliRuntimeInfo } from '@a3s-lab/code';

const status = moliRuntimeInfo({
  backend: BrowserBackend.Moli,
  autoDownloadMoli: true,
});
const executable = await ensureMoli({ backend: BrowserBackend.Moli });
console.log(status.version, executable);

from a3s_code import ensure_moli_async, moli_runtime_info

status = moli_runtime_info()
executable = await ensure_moli_async()
print(status["version"], executable)

status, err := code.MoliRuntimeInfo(ctx, code.NewMoliHeadlessConfig())
if err != nil {
	return err
}
executable, err := code.EnsureMoli(ctx, code.NewMoliHeadlessConfig())
if err != nil {
	return err
}
fmt.Println(status.Version, executable)