SDK 与 machine bridge

定义

SDK 是以程序调用代替命令行的本地控制面。四种语言操作同一套本机资源与持久状态，不暴露远程 URL，也不要求配置 API 密钥。

语言	安装	访问方式
Rust	`cargo add a3s-box-sdk`	直接调用 runtime 与代际围栏的 ExecutionManager
Python	`python -m pip install a3s-box`	同步 / 异步 API，经 machine bridge
TypeScript	`npm install @a3s-lab/box`	Promise API，经 machine bridge；要求 Node.js 20 以上
Go	`go get github.com/A3S-Lab/Box/sdk/go/v3`	Context API，经 machine bridge；要求 Go 1.25 以上

machine bridge 是 a3s-box sdk-bridge 子进程。它与语言包之间传送结构化 protocol-v3 消息。握手必须精确覆盖约定的 52 个操作；缺失、重复、畸形或不兼容的能力使握手失败。

问题背景

解析 a3s-box ps 的表格输出无法作为 API：列宽、语言、时间格式都会变。把 CLI 当成 IPC 还会把人类提示混进机器状态。bridge 把「给人类看的命令」和「给程序看的协议」分开，同时让 Python / TS / Go 不必链接 Rust ABI。

机制说明

一套状态，两种运输

Rust SDK 与 CLI 可以同进程调用 LocalExecutionManager。其他语言启动已安装的 a3s-box 二进制，进入 sdk-bridge 子命令，然后按 sdk/bridge-protocol.json 与 bridge-operations.json 发消息。运输不同，对象相同：box 记录、镜像、卷、事件与资源更新。

异步 Rust 构造器 A3sBoxClient::with_configured_paths(...).await 选择与 CLI 相同的 OCI 迁移路径。同步的 new / from_home / with_paths 保留遗留行为，供旧代码编译。

四种语言共同暴露的能力

文档列出的公共面包括：生命周期、exec / PTY、有界文件与文件系统、进程清单、规范化统计、有序事件、可重放的实时资源更新，以及有界单文件产物导出（上限至多 8 MiB 单帧，带 SHA-256）。未宣告对应运行时操作的后端，在调度前返回类型化可用性错误，而不是返回空结果。

语言中的方法名按习惯对齐：processes、runtime_stats / runtimeStats、events、update_resources / updateResources。

断开与重连

保留的本地 SDK 客户端在流断开时报告第一个断开结果，不重放未知请求；随后在显式对账时重连并重新协商。进程边界契约允许两个所有者交换磁盘上的运行时状态时，继续使用同一 exec 流且不重复启动。这些规则与代际与 fail-closed 一致。

在 Box 中的位置

Rust：src/sdk/，指南 src/sdk/README.md。
桥接协议：sdk/bridge-protocol.json、sdk/bridge-operations.json。
语言包：sdk/python、sdk/typescript、sdk/go。
CLI 入口：src/cli/src/commands/sdk_bridge.rs。
跨语言契约：docs/sdk-api-and-programmable-cicd.md。
冒烟：scripts/local-sdk-smoke.sh。

验证命令

# Rust
cd src && cargo test -p a3s-box-sdk

# Python（需已安装 a3s-box 与语言包）
cd sdk/python && python -m unittest discover -s tests

不要用「运行 CLI 再正则匹配表格」作为 SDK 测试。那会重新引入 bridge 要消除的脆弱性。