AgentFabric

AgentFabric 是面向 openEuler/Linux 的多智能体协作运行时。系统通过版本化 AFP/1 协议完成 Agent 握手、能力发现与动作路由；通过 mmap 和 StateRef 交换类型化非文本状态；通过 SQLite 共享记忆在关联任务之间复用证据与策略。可选的受限 CodeAct Agent 执行有界 JSON 数据变换。

应用场景与主要功能

项目面向代码协作、部署规划与知识分析等多步骤任务。Planner、Retriever、Summarizer 三个独立 Agent 构成基本工作流，CodeAct 为可选第四角色。运行时提供结构化通信、状态租约与校验、记忆检索与复用、任务关联和指标采集。B0 纯文本、B1 结构化、B2 非文本状态、B3 共享记忆四种模式使用相同任务和质量契约。

b2_state_fused 仅作为 O2 生命周期调用融合的附加消融，不改变正式四模式含义。

决赛目录

README.md                       构建、运行、测试和提交状态
src/                            Rust workspace 成员、AFP schema、Python SDK、配置与检查脚本
docs/                           工程文档、部署指南及待制作的四份决赛 PDF
tests/                          单元与端到端测试、评测工具、任务数据、历史验证证据
demo/                           可运行的多 Agent 机制演示
presentation/                   待制作的新版决赛 PPT 与演示视频
Cargo.toml / Cargo.lock         根目录构建入口
Makefile                        Linux 构建与测试入口

决赛材料的文件名、来源模板与待完成项见 docs/决赛材料检查表.md。旧版 PPT、视频、说明书和组委会模板只保存在本地忽略的 docs/.reference/、presentation/.reference/ 中，不作为决赛成品。决赛阶段的优化优先级、验收门槛和停止规则见 docs/决赛优化方案与执行计划.md；其中目标与假设不代表已实现或已验证的收益。

系统环境与依赖

目标系统：openEuler 24.03-LTS-SP3 x86_64；已在该版本完成初赛阶段原生验收。
工具链：Rust 1.75+、Python 3.11+、GCC、Make、Git；构建时由 Cargo 的 vendored protoc 生成 Rust 协议绑定。
Python SDK 依赖 protobuf>=5.29,<7。核心机制不要求外部模型服务、容器或向量数据库。
Linux 状态平面优先使用 /dev/shm；Windows 可用于开发，目标平台结论以 openEuler 复测为准。

构建与安装

在仓库根目录执行：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ./src/python
make build
cargo build -p agentfabric-runtime --release

系统包安装、资源建议和目标平台验收命令见 docs/deploy/openeuler/README.md。

运行

PYTHONPATH=src/python/src:tests python3 demo/run_showcase.py --profile release --workflow all

该入口依次展示结构化协议、非文本状态、共享记忆和受限 CodeAct。也可单独运行 cargo run -p agentfabric-runtime -- serve-workflow --agents 3 等子命令。演示步骤见 demo/README.md。

测试与验证

make test
make check
PYTHONPATH=src/python/src:tests python3 tests/benchmarks/run_experiment.py --repetitions 128 --random-seed 20261006 --experiment-id agentfabric-o4-paired-bootstrap-1024
PYTHONPATH=src/python/src:tests python3 tests/benchmarks/run_codeact_benchmark.py --repetitions 30 --random-seed 20260727

make test 包含 Rust、Python 单元与跨语言端到端测试；make check 增加格式和 Clippy 检查。正式基准需要 release Runtime 和干净工作区，输出到被 Git 忽略的 benchmark-results/。测试材料、任务数据、历史证据与复现限制见 tests/README.md。

已验证结果与已知限制

决赛目录迁移基线 9724d4c 已在 openEuler 24.03-LTS-SP3 x86_64 干净版本上通过 240/240 个四模式样本、60/60 个 CodeAct 样本和 100 任务耐久测试。B3 相比 B0 的文本字符下降 98.1%、wire bytes 下降 95.6%，两个任务组总 p50 时延下降 75.3%～75.4%。这些数值仅适用于确定性工作负载、本次环境和该 revision；新机制落地后仍需重新测量。初赛旧版数据、当前基线及后续优化结果不得混用，详见 docs/milestones/0008-final-round-baseline-progress.md。

当前未接入真实 LLM 或 tokenizer，因此没有真实 token 节省结论；CodeAct restricted-process-v1 不等同于容器或 WASM 级隔离；AArch64 尚未验收。决赛阶段的功能优化和新版匿名材料仍在进行，缺失材料清单见 docs/决赛材料检查表.md。

O3/O4 工作区已在 openEuler 24.03-LTS-SP3 x86_64 上完成 1024/1024 条扩展实验，四种模式、两组任务、每模式每组 128 次重复均通过质量契约。新增的 manifest v4 使用 task_group + repetition 配对，并以固定种子的 4000 次百分位 Bootstrap 输出 95% 置信区间：B3 总时延降幅为 75.1%（95% CI 75.0%～75.2%），热任务降幅为 87.0%（95% CI 86.9%～87.1%）；B1/B2 的端到端配对收益接近零，项目不作宽泛加速声明。该轮源码 revision 为 d63d62674b1b5efd04d648a5513394840a31e6b4 且工作区为 dirty，属于优化开发验收，最终发布前仍需干净 revision 重跑。方法和完整边界见 docs/milestones/0011-evaluation-uncertainty.md。

干净 openEuler 24.03-LTS-SP3 checkout 的一键发布验收入口为 python3 demo/run_acceptance.py --repetitions 30；它顺序运行测试、演示和正式基准，并在 benchmark-results/acceptance-*/ 保留日志及结果索引。具体门禁见 demo/README.md。