A²OS — 面向多智能体应用的系统级 Runtime

Agent-Oriented Operating System Runtime：让 Agent 的执行可以被调度、隔离、提交、恢复和复核。

A²OS 是运行在 Linux/openEuler 上的多智能体执行底座。上层框架负责描述 Agent、Prompt 和任务图，A²OS 负责处理它们落到真实系统后共同面对的问题：谁先运行、可以使用多少资源、如何共享上下文、怎样合并并发副作用、如何隔离不可信进程，以及故障后如何得到可验证的终态。

A²OS 不替代 LangGraph、AutoGen、CrewAI 等编排框架，也不托管大模型。它位于这些框架与操作系统之间，通过 Rust Runtime、Python SDK 和版本化 JSONL 协议提供统一的执行环境。

Agent 应用 / Workflow / LangGraph / AutoGen / CrewAI
                         │
              Python SDK / Adapter / JSONL v1
                         │
                         ▼
┌────────────────────────── A²OS Runtime ──────────────────────────┐
│ Router & Replay Ledger                                           │
├────────────┬────────────┬────────────┬────────────────────────────┤
│ Lifecycle  │ Scheduler  │ Workflow   │ Execution & Supervision    │
├────────────┼────────────┼────────────┼────────────────────────────┤
│ Context    │ A²Tx       │ IPC        │ LLM Gateway & Telemetry    │
├────────────┴────────────┴────────────┴────────────────────────────┤
│ cgroup v2 · namespace · seccomp · process group · memfd/mmap     │
└────────────────────────────────┬─────────────────────────────────┘
                                 ▼
                         Linux / openEuler

为什么需要 A²OS

多智能体框架通常已经能表达角色、依赖和对话，但应用层并不适合独自解决所有系统问题。

问题	A²OS 的处理方式
多个 Agent 争用 CPU、内存、进程数和外部服务配额	使用 RunPermit、MLFQ/WFQ、依赖关系和资源反馈统一调度
大上下文全量复制成本高，共享可变对象又容易相互污染	Runtime 维护 Context 单一真源，支持 CoW fork/merge、内容寻址和冷热分层
多个 Agent 同时修改文件或发送副作用	A²Tx 记录结构化 Effect，检测语义冲突并原子提交兼容结果
Agent 生成的命令、脚本和补丁不可信	通过进程组、cgroup v2、namespace、seccomp 和路径边界限制执行
spawn、超时、SIGKILL 或取消可能留下未知状态	Supervisor 统一提交终态并回收进程、socket、cgroup 和临时工作区
一张汇总表无法证明实验真实发生	验收工具保留命令、日志、资源数据、环境指纹、结构化结果和 SHA-256

核心能力

Agent 生命周期与调度

Runtime 使用状态机管理 Agent 的注册、就绪、运行、阻塞、完成、失败和注销。任务只有取得有期限且绑定执行主体的 RunPermit 后才能运行。后台 Dispatcher 结合依赖、优先级、MLFQ、组间 WFQ 和资源压力选择任务；工具等待结束后，任务可以重新进入就绪队列。

Workflow 与确定终态

Python SDK 和 Rust Runtime 共享 Workflow Schema。Runtime 原子编译 DAG，执行并行任务、动态任务、Retry、FailFast 和补偿策略。spawn、exit、timeout、cancel 等过程事实最终进入同一终态提交路径，避免重复完成、丢失唤醒和永久等待。

CoW Context

Context 由 Runtime 维护，而不是散落在各个 Agent 的本地内存中。子分支只复制被修改的页面，父子和兄弟分支可以基于 fork snapshot 做三方合并。内容寻址、引用计数、Hot/Warm/Cold 分层、checkpoint 与 WAL 用于降低复制开销并支持重启恢复。

A²Tx Agent Transaction

每个 Agent 在独立分支中产生 ContextRead、ContextWrite、FileWrite、MessageSend、ToolCall、NetworkCall 等 Effect。Runtime 根据版本、读写集合、文件哈希、消息语义和可逆性构建冲突图，再生成带 plan hash、graph hash 和 base epoch 的提交信封。

提交过程采用 prepare、stage、validate、apply、finalize 五阶段协议。发生崩溃后，恢复结果只能是完整旧状态或完整新状态，不会留下部分应用的混合工作区。

真实进程执行与隔离

A²OS 管理真实子进程和进程组，并可使用 cgroup v2 限制 CPU、内存和 PID。Formal 路径进一步要求 no_new_privs、seccomp 以及 user、net、mount、ipc、uts namespace。

Formal 结论不依赖配置自报：有效 execution receipt 必须包含真实 pid > 0 和实际验证得到的 isolation_status。Runtime 会读取系统事实逐项确认隔离；缺少委托、PID 或任一必要能力时直接失败。

IPC、事件与外部模型

控制面使用 Unix Domain Socket 上的版本化 JSONL 协议，包含请求标识、帧限制、幂等重放和结构化错误。大数据面支持 memfd、mmap 环形缓冲、eventfd 与 Unix FD 传递。执行完成事件可通过持久事件流通知客户端，避免高频轮询。

可信 LLM Gateway 使用长连接池访问 OpenAI-compatible API，并把外部模型调用与 sandbox worker 隔开。API Key 只存在于可信 Runtime/Gateway 或场景父进程的内存与环境中；不可信 worker 只接收任务输入或预生成补丁，不读取密钥，也不在工作区创建密钥文件。

故障恢复与可验证证据

Runtime 对超时、SIGKILL、spawn 失败和取消提供统一收据与清理。Context 和 A²Tx 使用 journal 恢复持久状态。实验与发布工具可以记录：

stdout、stderr、退出码、signal、超时和清理动作；
wall time、CPU time、RSS、进程树和 cgroup 快照；
OS、内核、工具链和 Git 指纹；
结构化验收报告、原始样本和文件 SHA-256；
运行前后的工作区状态与临时资源残留。

快速开始

环境要求

基础开发环境需要：

Linux x86_64；
Rust 1.96.0，版本由 rust-toolchain.toml 固定；
Python 3.10+，推荐 Python 3.11；
Git、C/C++ toolchain、make 和 pkg-config。

Node.js、Playwright、Clang/LLVM、eBPF 工具和 cargo-deny 只在运行相应 Web、诊断或供应链检查时需要。Formal 模式还需要 cgroup v2 delegation、cpu memory pids controller、user namespace 和 seccomp。

openEuler 24.03 的基础系统包：

sudo dnf install -y \
  git gcc gcc-c++ make pkgconf \
  python3 python3-devel python3-pip \
  util-linux

Ubuntu/Debian 的等价基础包：

sudo apt-get update
sudo apt-get install -y \
  git build-essential pkg-config \
  python3 python3-dev python3-venv python3-pip \
  util-linux

需要 eBPF 构建或诊断时再安装 Clang/LLVM、libelf、zlib 和可选的 bpftool；需要 Web 测试时再安装 Node.js 18+、npm 和 Playwright Chromium。

安装与构建

git clone https://github.com/Tekeli-Li-123/A2OS-public.git A2OS
cd A2OS/src/a2os-rust

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.lock.txt
python -m pip install --no-deps -e ./a2os-sdk

cargo build --workspace --locked

仓库以以下文件作为依赖版本真源：

Rust：rust-toolchain.toml 与 Cargo.lock；
Python：requirements-dev.in 与 requirements-dev.lock.txt；
Web：web-tests/package-lock.json。

启动 Runtime

在第一个终端中：

cd A2OS/src/a2os-rust
source .venv/bin/activate

mkdir -p /tmp/a2os-quickstart
./target/debug/a2os-runtime \
  --socket /tmp/a2os-quickstart/runtime.sock \
  --quick

在第二个终端运行 SDK 冒烟场景：

cd A2OS/src/a2os-rust
source .venv/bin/activate

python scripts/smoke_sdk_runtime.py \
  --socket /tmp/a2os-quickstart/runtime.sock

该场景覆盖连接、Agent 注册与状态迁移、调度、CoW Context、消息通信和注销。完成后在第一个终端按 Ctrl-C 停止 Runtime。

使用 Python SDK

import asyncio

from a2os import RuntimeClient, RuntimeConfig


async def main() -> None:
    client = RuntimeClient(
        RuntimeConfig(
            unix_path="/tmp/a2os-quickstart/runtime.sock",
            timeout=5.0,
            enable_recv_thread=False,
        )
    )
    await client.connect()
    try:
        print(await client.raw({"cmd": "ping"}))
    finally:
        await client.disconnect()


asyncio.run(main())

Agent、Workflow、Transaction、Workspace 和 Effect API 见 Python SDK 文档。

典型使用方式

为上层 Agent 框架提供统一 Runtime：框架继续管理角色和 Prompt，Adapter 把实际任务交给 A²OS 调度、执行和观测。
运行软件工程 Agent：分析、补丁生成和测试分支并行工作，A²Tx 检测冲突并以事务方式应用文件结果。
执行不可信工具：将命令放入受管进程，限制资源与系统边界，并获得真实 PID、终态和隔离收据。
构建可复现实验：固定任务、模型参数和随机种子，保存每轮原始样本、失败样本、环境信息与哈希。
验证故障恢复：在持久化边界注入 SIGKILL、timeout 或 spawn failure，检查恢复状态和资源残留。

开发验证

以下命令均从 src/a2os-rust 目录执行。

基础质量检查：

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked -- --test-threads=1

python -m compileall a2os-sdk benchmarks scenarios scripts acceptance
python -m ruff check a2os-sdk benchmarks scenarios scripts acceptance
PYTHONPATH=a2os-sdk python -m pytest -q a2os-sdk/tests
PYTHONPATH=a2os-sdk python -m pytest -q scripts/tests
PYTHONPATH=a2os-sdk python -m pytest -q \
  acceptance/tests -m "not formal and not live_llm"

统一验证入口：

verify_dir="$(mktemp -d /tmp/a2os-verify.XXXXXX)"
python scripts/verify_all.py \
  --profile release \
  --mode quick \
  --output-dir "$verify_dir" \
  --no-latest-update

verify_all.py 支持 a0–a8 与 release profile，以及 baseline、quick、complete 三种深度。它输出机器可读结果、Markdown 摘要和清理检查；某次运行的通过数量不作为 README 的固定能力声明。

Formal 模式

Formal 不是普通开发模式的别名。运行用户必须处于真实的 cgroup v2 委托边界中，并能在空的 A²OS 子树下创建 leaf cgroup、写入 PID 以及设置 cpu.max、memory.max、pids.max。

先检查主机基础能力：

test "$(stat -fc %T /sys/fs/cgroup)" = "cgroup2fs"
unshare -Ur true
unshare -Urnmiu true

推荐由带 Delegate=yes 的专用 systemd service 将 cgroup 子树委托给运行 A²OS 的非 root 用户。不要把 /sys/fs/cgroup、systemd 管理的 service 根节点或存在其他进程的 cgroup 直接用作 A²OS 子树。

export A2OS_CGROUP_BASE=/sys/fs/cgroup/<delegated-service>/a2os
bash scripts/formal_capability_check.sh

formal_dir="$(mktemp -d /tmp/a2os-formal.XXXXXX)"
PYTHONPATH=a2os-sdk python scripts/verify_all.py \
  --profile release \
  --mode complete \
  --formal \
  --output-dir "$formal_dir" \
  --no-latest-update

Formal 验收采用 fail-closed 语义：缺少基础能力、实际隔离证据、必要步骤、结果回读或完整清理时不会降级为“通过”。证据目录应放在源码树外；不要使用 git clean 或 reset 制造 clean-worktree 结果。

Real-SWE 与外部 LLM

仓库提供由多个角色协作完成代码分析、补丁生成、故障重试、冲突审查、A²Tx apply 和最终测试的 Real-SWE 场景。Live Formal 运行需要可用的 cgroup 委托、网络和 DeepSeek API Key：

cd A2OS/src/a2os-rust
source .venv/bin/activate

export A2OS_LLM_API_KEY='<deepseek-api-key>'
./run_live_formal.sh
unset A2OS_LLM_API_KEY

Real-SWE provider 可通过 A2OS_LLM_API_URL 覆盖完整的 Chat Completions 地址；使用 Runtime LLM Gateway 的应用则通过 A2OS_LLM_BASE_URL 和 A2OS_LLM_MODEL 选择兼容服务。不要把 Key 写入 .env、Runtime 配置、命令行参数、工作区、日志或证据包；正式部署应使用密钥管理器向可信进程注入。

基准与运行记录

项目将不同问题拆成不同实验通道：

Runtime 微基准衡量调度、spawn、warm worker、IPC 和观测开销；
确定性 LLM fixture 固定服务端延迟，用于比较客户端与执行路径开销；
Live Real-LLM 用于验证兼容性和故障行为，不把网络与模型延迟解释为 Runtime 性能；
跨框架比较要求相同任务、Prompt、模型、Token 上限、超时、重试、并发度和样本顺序。

无需 API Key 的 Echo 对比：

mkdir -p /tmp/a2os-benchmark
./target/debug/a2os-runtime \
  --socket /tmp/a2os-benchmark/runtime.sock \
  --quick \
  --deterministic-dispatch

在另一个终端中：

export A2OS_RUNTIME_SOCKET=/tmp/a2os-benchmark/runtime.sock
report_dir="$(mktemp -d /tmp/a2os-compare.XXXXXX)"

python -m benchmarks.compare.run_compare \
  --workload echo \
  --adapters asyncio_baseline,a2os_runtime \
  --iterations 5 \
  --seed 42 \
  --reports "$report_dir"

使用统一记录器包装任意实验或验收命令：

python scripts/run_and_summarize.py \
  --output-root /tmp/a2os-run-records \
  --label release-quick \
  -- \
  python scripts/verify_all.py \
    --profile release \
    --mode quick \
    --output-dir '{run_dir}/verification' \
    --no-latest-update

每次运行会生成独立目录，其中包括日志、summary.json、summary.md、files.sha256 和结构化子报告。记录器会识别常见敏感变量名并替换已知值，但公开证据前仍应进行独立 secret scan。

仓库结构

项目根目录/
├── README.md
├── src/
│   ├── a2os-rust/       # Runtime、Python SDK、场景、工具和工作区内测试
│   └── repo-tools/      # 仓库维护工具
├── docs/
│   ├── 项目说明书.pdf
│   ├── 项目创新说明.pdf
│   ├── 成员分工及主要贡献说明.pdf
│   └── 人工智能及第三方工具使用说明.pdf
├── tests/               # 根级回归与验证脚本
├── demo/                # 演示说明与脚本
├── presentation/        # 决赛演示 PPT 与视频
└── 作品原创承诺书.pdf

设计边界

A²OS 是单机执行 Runtime，不负责模型训练、模型托管、Prompt 设计或知识库检索。
cgroup、namespace、seccomp、Landlock 和 eBPF 的能力取决于宿主内核、挂载方式和服务权限。
当前版本为 0.1.0 Alpha，定位是研究与竞赛原型，不是经过安全认证的容器平台。
外部 LLM 数据包含网络、排队和模型推理时间，必须与 Runtime 本地开销分开解释。
离线 SWE 场景是固定工程回归集，不代表完整 SWE-bench 泛化成绩。
Landlock/Sandlock 和 eBPF 是条件能力；启用前需要核对内核 ABI、权限和对应 feature。
分布式一致性、跨节点调度、更大规模压力测试和持续 fuzz 仍属于后续工作。

文档

A²OS 采用 MIT License。