目录
master
分支1
标签0
+ 疑修
Web IDE
liquan
文档完善
3天前10次提交
README.md

多 Agent 通信实验：四 Agent 协作 + 纯文本基线 + JSON 结构化控制消息

本项目用于参加”第三届中国研究生操作系统开源创新大赛”。当前包含：

  • 阶段一（text_baseline）：最小但完整、可重复运行的双 Agent 协作系统， Agent 间只允许传递自然语言字符串，统计 Token、延迟、消息数和正确率， 作为所有后续优化的对照组（保持原样，未做任何口径修改）；
  • 阶段二（structured_json）：JSON 结构化控制消息协议——统一 Envelope+Body 消息模型、JSON Schema 校验、能力注册与路由、请求响应 关联、任务状态机、deadline/超时/取消、明确记录的纯文本回退，以及 结构化通信指标与两种模式的对照报告。协议文档见 docs/；
  • 正式四 Agent 系统（multi_agent）：必选 Planner + Retriever + Executor + Summarizer（可选 Verifier），完成多步骤复杂任务 （openEuler 构建失败诊断），支持 UDS 控制消息、Socket 字节与 CPU 共享内存三种大状态传输，A/B/C/D 四个实验组使用相同四 Agent 拓扑对照。见第 15 节与 docs/role_specification.md、 docs/task_flow.md、docs/experiment_contract.md。

纯文本模式是对照组，不代表最终优化方案。两种模式在相同任务集、 相同模型、相同参数和相同评测规则下运行，结果可直接比较。

1. 阶段目标

测试任务 → Agent A → 自然语言消息(TextChannel) → Agent B → 最终结果 → 评测与指标记录

产出四类指标：Token 数量、端到端延迟、Agent 间消息数、最终结果正确率， 作为阶段二（结构化协议）、阶段三（共享内存/非文本状态传递）的对照基线。

2. 系统执行流程

对每条测试任务：

  1. 运行器从 data/benchmark_tasks.jsonl 读取任务（JSONL 仅是本地测试数据格式，不属于 Agent 间通信协议）；
  2. Agent A 读取原始任务，将其转述为一段自包含的自然语言指令（普通字符串，禁止 JSON/结构化内容）；
  3. 指令通过 TextChannel 原样传递（不解析语义、不校验 Schema、不压缩、不去重），消息数 +1；
  4. Agent B 只根据收到的自然语言消息生成最终答案（它看不到原始任务对象，以便真实衡量纯文本通信的信息损失）；
  5. 运行器对答案做正确性评测，并记录全部指标；
  6. 单条任务失败被捕获记录，不中断整个实验。

3. 为什么当前阶段只使用纯文本

纯文本自然语言是多 Agent 系统最朴素的通信方式，也是本赛题所有优化 （结构化协议、非文本状态传递、共享记忆）要对比的基准。先把对照组 做稳、做可复现，后续每一项优化的收益才有可信的参照系。

4. Agent 职责

Agent 职责 接口
Agent A（任务转述） 理解原始任务，整理成自然语言指令发给 B AgentA.process(task) -> str
Agent B（任务执行） 只依据收到的消息完成任务，输出最终答案 AgentB.handle(message) -> str

Agent 不做实验指标汇总；统计统一由 ExperimentRunner 和 MetricsRecorder 完成。

5. 统计口径

Token

按六个维度记录：agent_a_input_tokens、agent_a_output_tokens、 agent_b_input_tokens、agent_b_output_tokens、message_tokens（Agent 间 消息单独统计，供阶段二对比）、total_model_tokens（四个模型端数值之和）。

  • API 模式：优先使用 API 返回的官方 usage 精确值（token_count_exact=true）； API 未返回 usage 时使用本地估算器，并如实标记 token_count_exact=false；
  • Mock 模式：Mock 模型没有外部分词器，内置估算器即其”官方分词器”，标记为精确；
  • 估算规则（确定性）：每个 CJK 字符计 1 token；其余按空白切分后每 4 字符约 1 token（向上取整）。 估算值绝不伪装成官方精确值。
  • Agent 间消息 Token（message_tokens）始终使用同一估算器计算，保证两种模式下口径一致。

延迟

使用 time.perf_counter_ns() 高精度计时，单位毫秒：

  • agent_a_latency_ms：Agent A 从开始处理任务到生成消息；
  • message_transfer_latency_ms：TextChannel.send() 到消息交给 Agent B 前；
  • agent_b_latency_ms：Agent B 从收到消息到生成答案；
  • end_to_end_latency_ms：任务开始到获得最终答案（不含数据加载和结果写盘）。

近似满足：端到端 ≈ A + 传输 + B + 运行器开销。

消息数

第一版口径：只统计 Agent 之间实际经过 TextChannel.send() 的消息。 Agent B 的最终结果直接交给实验运行器，不额外算一条消息，即每任务 1 条 （A→B）。如将配置 communication.count_return_message 设为 true， B→A 的回程结果消息也会入账，每任务记 2 条。

正确率

accuracy = 正确任务数 / 总任务数。支持四种评测方式：

  • exact_match：输出与标准答案完全一致；
  • normalized_exact_match：去首尾空格、转小写、合并连续空白、去常见结尾标点后比较；
  • contains：标准化后答案包含标准答案；
  • numeric_match：提取数字比较（取预测文本中最后一个数字，容差 1e-6）。

6. 环境安装

要求 Python ≥ 3.11（在 openEuler 24.03-LTS-SP3 自带 Python 3.11 上验证目标）。

# openEuler 如缺少 pip：dnf install python3-pip
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .                 # 以包形式安装 src/baseline，使 python -m baseline.main 可用

不想安装也可以用 PYTHONPATH=src python3 -m baseline.main ... 运行。

7. 配置

实验参数集中在 configs/baseline.yaml（provider、模型名、温度、超时、 重试次数、消息统计口径、数据集路径、输出目录、随机种子等），命令行参数 可覆盖其中的 provider、repeat 和数据集。

8. Mock 模式运行（离线、确定性、CI 可用）

python -m baseline.main --config configs/baseline.yaml --provider mock

Mock 客户端对相同输入永远产生相同输出：Agent A 用固定模板转述任务， Agent B 用内置确定性规则引擎求解，无任何随机性，无网络依赖。

9. API 模式运行（OpenAI-compatible）

export LLM_API_KEY=sk-xxxx
export LLM_BASE_URL=https://api.deepseek.com/v1
export LLM_MODEL=deepseek-chat
python -m baseline.main --config configs/baseline.yaml --provider openai-compatible

参考 .env.example。密钥只从环境变量读取，不写入代码和配置。调用失败 （网络错误、超时、HTTP 错误、空响应）会抛出明确错误并记录到该条任务的 结果里，不会静默切换成 Mock 模式。

常用参数：

python -m baseline.main --config configs/baseline.yaml --max-tasks 5   # 只跑前 5 条
python -m baseline.main --config configs/baseline.yaml --repeat 3      # 重复 3 轮

10. 测试

pytest -q

覆盖 TextChannel（类型约束、计数、内容不变、元数据）、Evaluator（四种 评测方式）、指标统计（Token 累加、延迟、消息数、正确率、P50/P95）、 ExperimentRunner（单任务全流程、多任务、失败隔离、文件输出）以及 “Mock 模式下基准任务集 100% 通过”的回归保护。

阶段二新增测试：消息模型与序列化一致性、Schema 校验（缺字段/未知 类型/未知动作/版本不符/缺 correlation_id 等均被拒绝）、RequestTracker （登记/关联/重复响应/未知关联/超时）、CapabilityRegistry 与路由 （注册/查询/注销/确定性多 Agent 路由）、任务状态机（合法与非法转换/ 取消/超时）、StructuredChannel（字节统计/校验先于执行/消息去重）、 文本回退（许可控制/原因记录/JSON 不进 LLM）、结构化集成与两种模式 对照实验（含对照报告生成）。

11. 输出文件

每轮运行在 outputs/ 生成三个文件：

  • run_<时间戳>_<轮次>_details.jsonl：任务级明细（问题、A 的消息、B 的答案、 正误、六维 Token、四段延迟、消息数、错误信息）；
  • run_<时间戳>_<轮次>_summary.json：实验汇总（正确率、失败率、消息总数、 Token 总量与均值、平均/P50/P95 延迟等）；
  • run_<时间戳>_<轮次>_details.csv：与明细同构，便于绘图与统计。

12. 当前阶段的限制

  • 单机、单进程，TextChannel 为进程内传递，传输延迟接近 0（仍如实记录）；
  • 有意不实现：结构化消息、Schema 校验、能力注册、任务状态机、共享内存、 Embedding/隐状态传递、共享记忆、向量数据库、gRPC/eBPF/WASM；
  • Mock 规则引擎只覆盖基准任务集的五类任务，超纲任务返回固定兜底文本（判错）；
  • 开放式写作任务不在正确率统计范围内。

13. 阶段二：JSON 结构化控制消息（structured_json）

13.1 运行

# 结构化模式（Mock，离线确定性）
python -m baseline.main --config configs/structured.yaml --provider mock

# 等价写法：用 --mode 覆盖任意配置
python -m baseline.main --config configs/baseline.yaml --mode structured_json

# 对照实验：同一任务集依次运行两种模式并生成对照报告
python -m baseline.main --config configs/baseline.yaml --mode compare

通信模式也可用环境变量覆盖：BASELINE_COMMUNICATION_MODE=structured_json。

13.2 消息流程

Planner（程序侧） → HELLO / CAPABILITY_REGISTER / CAPABILITY_QUERY（会话建立）
每条任务：TASK_REQUEST → TASK_ACCEPT → ACTION_REQUEST → ACTION_RESULT
  • 所有消息统一 Envelope（protocol_version、message_id、task_id、 session_id、trace_id、correlation_id、sender、receiver、message_type、 timestamp、deadline）+ 类型化 Body（action、parameters、status、 result、error）；
  • JSON Schema 校验发生在 Agent 执行前，非法消息绝不到达 Agent；
  • 请求与响应通过 correlation_id 关联；支持 deadline、超时与 CANCEL；
  • 路由由 CapabilityRegistry + Router 按能力/版本/状态/负载确定性完成， 不用 LLM 选路；
  • 控制字段不进入 LLM Prompt——只有 parameters.task_text 业务文本 交给模型（指标 llm_visible_tokens / control_plane_bytes 佐证）；
  • 结构化失败且错误码允许时，走明确记录的纯文本回退 （复用阶段一 TextChannel，记录原因/Token/延迟/结果，禁止静默回退）。

13.3 新增输出

结构化模式除三个常规文件外多一个消息级明细 run_<时间戳>_<轮次>_structured_json_messages.jsonl； compare 模式额外生成 outputs/comparison_<时间戳>.{json,csv,md} 对照报告（Token 收益、字节开销、Schema/路由开销、质量变化， 全部来自实际实验数据）。

13.4 协议文档

文档 内容
docs/protocol_spec.md 协议目标/边界/生命周期/Envelope/Body/消息类型/版本与回退规则
docs/field_dictionary.md 全字段类型、必填性、示例、语义、生成方与消费方
docs/error_codes.md 13 个错误码的触发条件、可重试性、回退许可与处理建议
docs/routing_rules.md 能力注册/查询、Agent 选择策略、失败处理
docs/fallback_strategy.md 回退许可、内容提取、指标记录、失败处理

14. 与阶段三的衔接

协议语义（baseline/protocol/）、编码（JSON）与传输 （baseline/communication/）严格解耦。UnixSocketTransport 已实现 （socket.socketpair()，Linux 上即 AF_UNIX；4 字节长度前缀 + JSON 帧），供 C/D 实验组使用；后续把 StructuredRuntime 的状态机/路由/ 关联逻辑迁往独立 Rust Runtime 进程时，业务 Agent、评测与指标模块 不修改（见 docs/rust_runtime_architecture.md）。

以下接口保持稳定：

AgentA.process(task) -> str
AgentB.handle(message) -> str
TextChannel.send(sender, receiver, content) -> str
Transport.send(message) -> TransportResult
StructuredChannel.send(message) -> StructuredMessage | None
StructuredRuntime.dispatch(message) -> StructuredMessage | None
Evaluator.evaluate(prediction, expected, evaluation_type) -> bool
ExperimentRunner.run(tasks) -> ExperimentSummary
StructuredExperimentRunner.run(tasks) -> StructuredExperimentSummary
MultiAgentPipeline.run(tasks) -> CollabExperimentSummary
SharedStateManager.create/read/add_ref/release/reclaim_expired

15. 正式四 Agent 系统（multi_agent 模式）

必选：Planner + Retriever + Executor + Summarizer；可选： Verifier（质量检查角色，不代替信息检索或总结生成角色）。 Experiment Runner、Runtime、Capability Registry、Router 与共享 内存管理器均为基础设施，不算作 Agent。

15.1 拓扑与流程

用户复杂任务 → Planner（任务 DAG）
                 ├→ Retriever（本地知识库检索，来源+相关性分数）
                 └→ Executor（白名单工具：os_info/python_env/disk_usage/read_build_log/check_commands）
                        ↓ 证据引用 / 状态句柄（内联 / Socket 字节 / CPU 共享内存）
               Summarizer（综合两个上游结果 → 最终报告）
                 → 可选 Verifier → Experiment Runner（指标与协作审计）
  • 能力路由强约束：检索能力只能路由到 Retriever、工具能力只能到 Executor、总结能力只能到 Summarizer；能力注册到错误角色或万能 Agent 直接拒绝（ROLE_CAPABILITY_MISMATCH）；
  • 启动前拓扑校验：核心 Agent 少于 3 个、角色类别少于 3 类或四类 核心角色不全时拒绝启动；
  • 协作审计：只发 HELLO 不算参与；最终结果必须来自 Summarizer 且 实际消费上游结果；不满足要求的任务不计为有效成功 （multi_agent_collaboration_valid=false）。

15.2 实验组（相同拓扑对照）

组 控制消息 大状态传输
A 自然语言（TextChannel） 内联（不共享大状态）
B JSON 结构化（进程内） 内联（不共享大状态）
C JSON 经 Unix Domain Socket 普通 Socket 字节传输
D JSON 经 UDS CPU 共享内存（state_ref 引用传递）

15.3 运行

python -m baseline.main --config configs/multi_agent.yaml --provider mock
python -m baseline.main --config configs/multi_agent.yaml --groups A,D --no-verifier

正式复杂任务集：data/complex_tasks.jsonl（openEuler 软件包构建 失败诊断，需检索 data/knowledge_base/ 并诊断 data/build_logs/）。输出：每组 run_*_group<X>_{details.jsonl,summary.json,details.csv,collaboration.md} 与跨组 multi_agent_comparison_*.{json,md}（含每任务完整调用链 “用户任务 → Planner → Retriever/Executor → Summarizer → 最终结果”、 角色消息数、能力路由次数、检索/执行→总结字节与状态引用次数、 共享状态泄漏检查）。

15.4 新增测试

四 Agent 注册、能力路由（含错误角色拒绝、万能 Agent 拒绝）、多 步骤流水线（顺序与调用链）、角色绕过、虚假参与、Summarizer 上游 缺失（UPSTREAM_RESULT_MISSING）、共享内存协作（创建/读取/释放/ 租约/引用计数/无泄漏、双上游 state_ref 路径）、三 Agent 最低要求 与角色类别最低要求、四实验组拓扑一致性。

16. 跨环境：Windows 通信性能测试 + Linux AI 流程验证

两套环境共用协议与 Agent 契约，但性能数据严格隔离：

环境 职责 结果前缀
Windows 本机 Named Pipe / Windows File Mapping IPC 微基准、Dashboard、四 Agent 动画（Mock，不调用真实 AI） outputs/windows_bench_*
Linux 虚拟机 四 Agent + OpenAI-compatible API 完整业务流程 outputs/linux_ai_demo_*

Windows 不得使用 memfd / SCM_RIGHTS / POSIX shm_open。
Linux AI 延迟不得画进 Windows IPC 柱状图。
KPI 中的「KV Cache」显示为 未启用；共享内存压力来自真实 active/max 字节比。

16.1 Windows 安装与运行

# 1) 安装
.\scripts\windows\setup.ps1

# 2) 构建 Rust Runtime
.\scripts\windows\build-runtime.ps1

# 3)（可选）启动 Rust Runtime；Benchmark 也可自动使用 Python Shim
.\scripts\windows\start-runtime.ps1

# 4) IPC 微基准（禁止调用 AI API）
.\scripts\windows\run-benchmark.ps1

# 5) Dashboard（API :8000；若无 dist 先 npm run build）
.\scripts\windows\start-dashboard.ps1
# 浏览器打开 http://127.0.0.1:8000
# 顶部「赛题标准指标」固定展示：消息次数 / Token / 字符开销 /
# 非文本传递次数与字节 / 单任务时延 / 记忆命中率 / 整体性能提升
# 主看组 D vs 组 A；点击「运行赛题评测」
# 打包提交辅助材料：
.\scripts\windows\package-contest.ps1
# 另开终端开发前端：
cd dashboard\frontend; npm run dev

openEuler / Linux 看板与打包：

bash scripts/linux/start-dashboard.sh
bash scripts/linux/package-contest.sh

结果路径：

  • outputs/windows_bench_<timestamp>_details.jsonl
  • outputs/windows_bench_<timestamp>_summary.json
  • outputs/windows_bench_<timestamp>_comparison.csv
  • outputs/windows_bench_<timestamp>_report.md

访问 Linux AI（可选联动，不传 API Key）：

$env:LINUX_VM_API_BASE_URL = "http://<vm-ip>:8100"
# 或写入 configs/windows_benchmark.yaml 的 linux_vm.api_base_url

16.2 Linux 虚拟机安装与运行

# 1) 安装
bash scripts/linux/setup.sh

# 2) 配置 API（只在 Linux 上）
cp linux-ai-service/.env.example linux-ai-service/.env
# 编辑：
#   LLM_API_KEY=...
#   LLM_BASE_URL=https://.../v1
#   LLM_MODEL=...

# 3) 启动服务（0.0.0.0:8100）
bash scripts/linux/start-ai-service.sh

# 4) 最小 API 探测 / 完整 Demo
bash scripts/linux/test-api.sh
bash scripts/linux/run-ai-demo.sh

结果路径：outputs/linux_ai_demo_<timestamp>.json
无 Key 时返回 real_api_success=false / skipped=true，不会伪装成功。

16.3 目录要点

  • rust-runtime/：Windows Named Pipe + CreateFileMappingW
  • src/baseline/platform/：Python Windows Backend + framing
  • src/baseline/experiment/windows_benchmark_runner.py：IPC 微基准
  • dashboard/：FastAPI + React/Vite 实时可视化
  • linux-ai-service/：Linux AI Demo FastAPI
  • configs/windows_benchmark.yaml / configs/linux_ai_demo.yaml

16.4 openEuler 赛题主路径（共享记忆 + 非文本状态 + 连续任务）

技术报告见 docs/技术报告.md， 系统设计见 docs/system_design.md， 实验报告见 docs/contest_experiment_report.md， 完整部署与验收见 docs/deploy_openeuler.md。

# 四 Agent + 共享记忆 + embedding 非文本传递
python -m baseline.main --config configs/multi_agent.yaml --provider mock

# 两组关联连续任务记忆实测（gcc_chain / openssl_chain）
python -m baseline.main --config configs/multi_agent.yaml --mode continuous_memory --provider mock

# ≥10 轮稳定性
bash scripts/linux/run-contest-stability.sh

# 演示录屏辅助
bash scripts/linux/record-demo.sh

非文本状态说明：docs/non_text_state_transfer.md。

关于
README.md
92.9 MB
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号