StateBus

面向多智能体协作的低开销通信、状态传递与共享记忆机制

Typed state transfer and shared memory for multi-agent workflows.

StateBus Runtime

应用场景 · 系统环境与依赖 · 快速开始 · Studio · 前端展示 · 测试 · 系统架构 · 实验结果 · 已知限制 · 实现文档 · 赛题对应关系

StateBus 是什么

多 Agent 协作时，计划、证据、表格、执行输出和历史经验常被重新拼进 prompt。上下文会变长，角色还要重复解析已经存在的内容。

StateBus 把控制消息和较大的状态对象分开。Planner、Retriever、Executor、Summarizer 负责提出计划、检索结果、执行程序和组织结论；Runtime 负责编译任务、批准计划、检查引用、验证产物并记录运行事实。

当前实现包含 Python Runtime、UDS + Protobuf、StateRef / ArtifactRef / MemoryRef、shared memory/mmap/CAS、受限 CodeAct，以及 vLLM 侧的 APC、显式 KV 和 Logit utility。模型专项从各自的实际接入位置读取数据，默认任务流程继续使用同一组对象合同。

应用场景

StateBus 的应用场景：面向需要本地部署和低开销多 Agent 协作的任务

StateBus 面向数据不宜离开本地环境、但单机算力和模型能力有限的工作流，例如检索增强、复杂规划、代码协作和知识分析。多个 Agent 可以分别承担规划、检索、执行和总结；Runtime 通过结构化消息和类型化状态引用传递中间结果，并用共享记忆保存可复用的经验，减少把长段历史反复放入 prompt 的需要。这样做旨在降低重复文本与 token 开销、缩短多步协作中的等待，并帮助本地模型处理更复杂的任务；实际质量和性能仍取决于模型、任务、硬件及配置。

系统架构

StateBus Runtime 系统架构

图示展示 StateBus Runtime 的控制层、执行层、对象层、模型层和记忆层：Runtime 组织任务准备与执行推进，由 Planner、Retriever、Executor、Summarizer 依次协作；对象层通过 EvidencePack、StateRef、ArtifactRef 保存证据、状态和产物，并按需使用共享内存、mmap/CAS 或 Workspace；模型层提供 BGE 向量编码、APC 与显式 KV 上下文复用和 Llama 推理；记忆层检索历史任务，判断复用或重算，并写回本轮可保留的结论、方法、来源、标签和产物引用。图示对应的源码入口见 docs/architecture/README.md。

赛题对应关系

赛题要求	当前实现	代码与结果入口
三类以上 Agent 协作	Planner、Retriever、Executor、Summarizer	`src/statebus/runtime/`
结构化通信	typed Protobuf、UDS、ACK、心跳和终态事件	`src/statebus/control/`
非文本状态	`SemanticStateRef`、`LogitStateRef`、APC、`EngineLocalKVHandle`	`src/statebus/state/`、`src/statebus/integrations/vllm_kv/`
共享记忆	SQLite/FTS、向量检索、兼容性检查、validated replay	`src/statebus/memory/`
可复现实验	标准任务 24 对、机制位置 24 个、utility 位置 28 个	`tests/evidence/README.md`、`docs/experiments/README.md`

实验结果

实验分为主实验、Memory/State 机制实验和 APC/KV/Logit 模型侧专项。主页保留关键结果，逐任务数据和字段说明见 docs/experiments/results.md。

实验	分母	主要对照	关键结果
主实验	24 对、48 次执行	`SB-FULL` / `P-TEXT`	质量 24/24；requests 降低 31.67%；provider tokens 降低 39.05%；Executor generations 降低 52.78%；repairs 降低 58.33%；E2E 降低 24.47%
Memory	16 个位置	`off` / `on`	质量 8/8；requests 降低 33.33%；provider tokens 降低 44.12%；任务耗时降低 27.12%；4/8 进入 validated replay
State	8 个位置	`off` / `on`	质量 4/4；任务耗时降低 3.43%；publish/transfer/consume `10/10/10`；S1 的 behavioral effect 为 `changed`
APC	8 个位置	`independent` / `shared`	consumer TTFT 降低 89.59%；hit tokens `48 → 5,168`；task wall 降低 4.29%
显式 KV	8 个位置	`full_replay` / `continuation`	computed prefill 降低 90.37%；TTFT 降低 60.88%；request wall 降低 11.88%；task wall 降低 3.58%
Logit	12 个位置	`full` / `compact` / `selective`	logical input 降低 75.21%；request wall 降低 17.18% / 18.51%；9 个 resolved case 通过，3 个正确 `abstention`

详细实验结果：docs/experiments/README.md → docs/experiments/results.md。

系统环境与依赖

仓库支持离线开发/测试和依赖本地模型服务的完整运行两种路径。下表列出对应代码和配置中的环境要求；GPU 显存需求会随模型、上下文长度、并发数和推理配置变化，本项目不把单一显卡规格作为通用最低要求。

用途	环境要求
Host Runtime、离线测试	Linux 主机、Bash、Conda；Python 3.11（`pyproject.toml` 要求 Python >=3.11）。Host 包含 NumPy、Protobuf、Pydantic、MsgPack、OpenAI 客户端、FAISS CPU、Transformers、Sentence Transformers 和 PyYAML；测试使用 pytest 与 pytest-asyncio。
应用容器	Docker Engine 和 Docker Compose 插件；仓库 Dockerfile 基于 openEuler 24.03 LTS-SP3，并提供 `core`、`embed` 构建目标。容器镜像内安装 Python、Node.js/npm 及运行时构建工具。
Studio	Python API 使用 FastAPI 0.116.1、Uvicorn 0.35.0；前端使用 Node.js/npm、React 18、Vite 5 和 TypeScript 5。前端依赖由 `src/studio-ui/package-lock.json` 锁定。
本地 vLLM 推理	可用的 NVIDIA 驱动和 CUDA GPU、足够的显存，以及本地模型权重。仓库推理环境使用 Python 3.11、vLLM 0.9.2、PyTorch 2.7.0（CUDA 12.6 构建）、Transformers 4.52.4 和 Tokenizers 0.21.4；示例模型为 Qwen3-32B BF16。

Host Python 依赖见 requirements-host.txt、requirements-studio.txt 和 pyproject.toml；vLLM 独立依赖见 requirements-vllm.txt。Embedding 在仓库默认容器配置中使用 CPU，不要求与 vLLM 共享 GPU。权重文件不由 pip 安装，需单独准备，并通过 deploy/vllm.env.local 配置模型路径、GPU 和服务参数。

快速开始

所有命令从仓库根目录执行：

cd /home/qcrs/statebus/os

1. 真实启动：Runtime、vLLM 和应用容器

完成一次 Host 环境安装后，下面第三条命令就是实际启动入口。它会读取 profile，启动或复用匹配的 vLLM 服务，启动 statebus-runtime 容器，并执行服务检查和 smoke：

nvidia-smi -L
scripts/start_statebus.sh qwen3-32b-gpu2-u050 --print-config
scripts/start_statebus.sh qwen3-32b-gpu2-u050

--print-config 只显示解析后的配置；不带该参数的命令才执行启动。可用 profile：

scripts/start_statebus.sh --list-profiles

启动完成后，Runtime 使用 http://127.0.0.1:53334/v1 的 Qwen3 服务，应用容器由 statebus-runtime 管理。

2. Host 环境

statebus_host 安装脚本会安装 requirements-host.txt、requirements-studio.txt 并以 editable 方式安装当前源码：

deploy/install_statebus_host.sh
source deploy/activate_statebus_host.sh
python -c 'import statebus; print(statebus.__file__)'

已有环境只需执行 source deploy/activate_statebus_host.sh。

3. vLLM 配置与手动服务管理

vLLM 使用独立 Conda 环境和 host GPU。配置文件位置如下：

文件	内容
`deploy/vllm.env.local`	模型路径、服务端口、物理 GPU、context、显存比例和 APC/KV 模式
`deploy/statebus_llm.yaml.local`	Runtime 的 provider、角色模型和请求参数
`deploy/statebus_llm.env.local`	API key、embedding 和临时环境变量

cp deploy/vllm.env.example deploy/vllm.env.local
cp deploy/statebus_llm.local_vllm.example deploy/statebus_llm.yaml.local
cp deploy/statebus_llm.env.example deploy/statebus_llm.env.local
nvidia-smi -L
scripts/vllm/manage_qwen3_32b.sh print-config
scripts/vllm/manage_qwen3_32b.sh start
scripts/vllm/manage_qwen3_32b.sh health

默认 profile 为 Qwen3-32B、http://127.0.0.1:53334/v1、物理 GPU 2、max-model-len=8192 的配置。正式 profile 可由 scripts/start_statebus.sh --list-profiles 查看。

4. 单独启动 Runtime 容器

需要拆开启动步骤时，使用同一个 profile。脚本会先检查并复用健康的 vLLM 服务，再启动 statebus-runtime：

scripts/start_statebus.sh --list-profiles
scripts/start_statebus.sh qwen3-32b-gpu2-u050 --print-config
scripts/start_statebus.sh qwen3-32b-gpu2-u050

只查看 Docker Compose 配置：

docker compose --env-file docker/.env.example -f docker/compose.yaml config

实际构建镜像（读取本机配置；.env.example 可用于按默认值构建）：

deploy/build_statebus_image.sh --env-file docker/.env.example

只预览命令时加 --dry-run。该脚本只构建镜像，不创建或替换容器；容器、挂载和环境变量说明见 docker/README.md。

5. Live smoke

start_statebus.sh 启动时会执行一次 smoke。服务保持运行后，可以用 benchmark dispatcher 再执行完整的 host、vLLM、容器和 Runtime smoke：

tests/benchmarks/run_statebus.sh smoke

这个命令会访问 127.0.0.1:53334/health，在 statebus-runtime 中运行 statebus.runtime.smoke --role-path-mode local_vllm，并把本次结果写入 runs/。--dry-run 只打印底层命令，不会执行 smoke。入口说明见 tests/benchmarks/README.md。

6. Demo

使用本地 vLLM 和 Runtime 启动 Studio Demo。API 和 UI 分别在两个终端运行：

终端一：

source deploy/activate_statebus_host.sh
demo/run_demo.sh --local-vllm

终端二：

scripts/run_statebus_studio_ui.sh

浏览器访问 http://127.0.0.1:50173。demo/run_demo.sh --offline 只回放已保存的结果，不访问服务。命令说明见 demo/README.md。

7. Live benchmark

先执行上面的真实启动命令并通过 smoke，再启动 benchmark。Benchmark runner 不负责启动或重启 vLLM 和容器；每次执行写入新的 runs/ 子目录。

主实验（24 对、48 次执行）：

tests/benchmarks/run_statebus.sh mainline-24

Memory / State 机制实验：

tests/benchmarks/run_statebus.sh mainline-mechanisms

APC、显式 KV 和 Logit utility suite：

tests/benchmarks/run_statebus.sh utility --execute --yes

只运行一个 utility phase 时，将 utility 换为 apc、kv 或 logit。运行前可用对应命令加 --dry-run 查看解析后的 runner 参数；完整参数和输出目录见 tests/benchmarks/README.md。

Studio

Studio API 默认监听 http://127.0.0.1:50080，Vite 开发页面默认监听 http://127.0.0.1:50173。先启动 vLLM 和 Runtime 所需的 host 环境，再开两个终端：

终端一：

source deploy/activate_statebus_host.sh
scripts/run_statebus_studio.sh

终端二：

cd src/studio-ui
npm ci
cd ../..
scripts/run_statebus_studio_ui.sh

浏览器打开 http://127.0.0.1:50173。需要由 API 直接提供构建后的页面时，执行 cd src/studio-ui && npm ci && npm run build，然后访问 http://127.0.0.1:50080。

前端展示

下图展示 StateBus Studio 的前端协作运行观测界面：页面按 Planner、Retriever、Executor 和 Summarizer 展示任务推进，连接线上标注结构化交接、状态引用和记忆复用；右侧面板显示当前任务、执行命令和 StateReceipt 等可追溯对象，底部事件栏记录本次协作的状态变化。该界面用于观察 Runtime 的执行过程和证据，不代表模型内部 hidden state 或跨服务 KV-cache 的直接传输。

StateBus Studio 前端协作运行观测界面

测试

测试入口和命令索引见 tests/README.md。离线测试不需要 vLLM：

source deploy/activate_statebus_host.sh
PYTHONDONTWRITEBYTECODE=1 python -m pytest -q tests/unit
PYTHONDONTWRITEBYTECODE=1 python -m pytest -q tests/integration
PYTHONDONTWRITEBYTECODE=1 python -m pytest -q tests/benchmarks

Studio 前端类型检查和流程测试：

cd src/studio-ui
npm ci
npm run typecheck
npm run test:flow

离线查看 benchmark 计划（不会访问 vLLM、GPU 或 Docker）：

tests/benchmarks/run_statebus.sh smoke --dry-run
tests/benchmarks/run_statebus.sh mainline-24 --dry-run
tests/benchmarks/run_statebus.sh mainline-mechanisms --dry-run
tests/benchmarks/run_statebus.sh utility --dry-run

需要实际执行时，使用上面的 Live benchmark 命令；utility 必须显式带 --execute --yes。

汇总精选结果：

python tests/evidence/summarize_results.py
python tests/evidence/summarize_results.py --json

实时 runner 依赖 vLLM、GPU、Docker 和模型文件；启动顺序、健康检查和各配置字段见 docker/README.md 与 AGENTS.md。

已知限制

任务质量受所用模型的知识、推理和指令遵循能力影响。模型可能给出错误结论、遗漏证据或生成不符合预期的结构；Runtime 的合同检查和 Validator 能发现部分问题，但不能保证所有任务输出正确。涉及业务决策的结果仍需按应用要求复核。
多 Agent 编排和共享状态可以减少重复上下文并组织分工，但不会自动提升底层模型能力，也不保证每种任务都更快或更省 token。小任务的调度、对象读写和校验开销可能抵消复用收益。
完整本地推理依赖单独准备的模型权重、兼容的 NVIDIA 驱动/GPU 和足够的显存；加载时间及可用上下文还受并发、批量 token 和显存占用影响。没有运行中的模型服务时，离线单元测试仍可执行，但 live smoke 和模型 benchmark 不可用。
StateRef、ArtifactRef 和 MemoryRef 表示应用层结构化状态、产物和记忆，不是模型 hidden-state 张量或可跨服务传输的 KV-cache。APC 是 vLLM 引擎内的前缀缓存；显式 KV continuation 依赖匹配的 vLLM Worker/engine 身份，APC、KV 和 Logit 专项也需要显式启用，不能视为任意模型服务都支持的通用能力。
本地部署是否满足数据驻留要求取决于实际 provider、模型服务、日志、缓存和挂载配置。若将请求发送到远程 OpenAI-compatible 服务，相关输入会按该服务的连接与数据策略处理。
README 中的性能数据来自表内列出的任务集合、模型和运行配置，代表对应实验结果，不构成对其他硬件、模型或生产负载的性能保证。完整分母和实验条件见 docs/experiments/results.md。

实现文档

想了解什么	入口
文档地图	`docs/README.md`
系统分层、对象和源码归属	`docs/architecture/README.md`
一次任务、Runtime、Embedding、APC、显式 KV、Logit 的接入位置	`docs/implementation/README.md`
实验分母、结果和复现	`docs/experiments/README.md`
精选机器结果	`tests/evidence/README.md`
部署和服务检查	`docker/README.md`

目录导航

os/
├── README.md
├── docs/
├── src/
├── tests/
├── scripts/
├── demo/
├── docker/
├── presentation/
├── deploy/
├── tasks/
├── tools/
├── datasets/
└── runs/

目录入口：

目录	入口
`docs/`	`docs/README.md`
`src/`	`src/README.md`
`tests/`	`tests/README.md`
`scripts/`	`scripts/README.md`
`demo/`	`demo/README.md`
`docker/`	`docker/README.md`
`presentation/`	`presentation/README.md`
`deploy/`	`deploy/`
`tasks/`	`tasks/`
`tools/`	`tools/`
`datasets/`	`datasets/`
`runs/`	`runs/`（运行输出）

统计

标准任务、机制位置和 utility suite 使用独立任务集合与分母：24 对 / 48 个位置、24 个位置、28 个位置。
provider tokens、task_e2e_ms、computed prefill、TTFT、state bytes 和 KV bytes 是不同指标，按各自实验范围解读。
Memory 的候选命中、实际消费和 validated replay 分开记录；State 的事件记录与业务字段变化分开记录。
raw run 位于 runs/；精选结果位于 tests/evidence/README.md。