MAC-Comm：多智能体低开销协作系统

MAC-Comm（Multi-Agent Collaboration Communication）是一个面向多智能体协作的研究型原型系统。项目关注多个 Agent 在复杂工作流中如何交换任务、共享中间状态、复用记忆，并让这些过程可观测、可验证、可回退。

本 README 是评审和本地复现的主入口。无 GPU 时可以运行 mock 编排、协议和通信实验；有本地 GPU 和模型时可以运行真实模型实验。

1. 项目简介

MAC-Comm 将多 Agent 协作拆分为控制面、状态数据面和记忆持久面：

控制面：用 Envelope、G²CP performative 和任务元数据表达请求、结果、查询、确认、状态更新等协作语义；
状态数据面：用 StatePointer 引用文本制品、Semantic State Capsule、embedding、hidden state、KV handle 和共享状态，避免把大对象直接塞进控制消息；
记忆持久面：用 MemoryUnit、StateMemoryStore 和可选 Chroma 索引保存摘要、全文 Artifact、标签和状态指针；
运行时：提供配置驱动的 DAG 工作流、单进程执行、resident Worker 多进程执行、状态消费回执和实验审计；
验证层：提供 mock 端到端验证、本地通信微基准、状态物化实验、逻辑节点同步实验和论文结果分析。

项目不把 embedding、latent 或 KV 当作可逆的全文表示；接收端需要精确内容时，系统可以回退到 SSC、Artifact 或文本通道。

2. 应用场景

项目适用于需要多个角色协同完成、且中间结果规模较大或需要复用的任务，例如：

研究与报告生成：Planner 分解问题，Researcher 整理证据，Writer 汇总输出，Reviewer 检查约束；
故障响应：不同 Agent 分析日志、指标和发布信息，再由汇合节点生成处理建议；
代码项目协作：Coder 生成或修改代码，沙盒执行测试，Reviewer 检查结果并交给集成节点；
跨任务知识复用：将前一任务的摘要、证据和制品存入记忆，供后续任务按语义、关键词或标签检索；
通信与状态机制研究：比较文本、结构化状态、共享指针、队列、Pipe 和 loopback TCP 等路径的成本和消费证据。

3. 主要功能

3.1 结构化通信

Envelope 统一消息封皮，包含消息类型、源/目标 Agent、任务 ID、payload、状态指针和 metadata；
G²CP 支持 REQUEST、INFORM、QUERY、PROPOSE、CONFIRM、REJECT、UPDATE，并可通过 G2CPAdapter 与 Envelope 双向转换；
JSON 和 MessagePack 编解码均可用，控制消息与大对象数据面分离；
消息、能力、状态版本、checksum 和模型指纹可记录到事件和审计结果中。

3.2 多层状态传递

文本和结构化摘要适合作为通用回退路径；
Semantic State Capsule 传递可解释的计划、证据和执行字段；
ArtifactStore/SharedMemoryStore 保存大文本、代码、日志和二进制制品；
embedding 和 hidden sketch 用于检索、路由或去重；
KV continuation 仅在模型、设备域和生命周期兼容时使用，不兼容时回退；
ProcessStateBridge 支持完整状态、字段选择和 block 选择，并产生实际消费回执。

3.3 多 Agent 运行时

配置驱动的 Workflow DAG 和依赖分层调度；
Planner、Researcher、Writer、Reviewer、Coder 等角色工厂；
单进程模式和独立 Worker 多进程模式；
工具调用、路由、检查点、状态消费和事件记录；
统一实验入口支持 mock、paper、state、logical 和 communication 实验。

3.4 跨任务记忆

MemoryUnit 保存摘要、任务主题、来源 Agent、标签、重要性和记忆 ID；
StateMemoryStore 将摘要索引与完整 Artifact、semantic pointer 关联；
支持 InMemoryStore，以及配置 ChromaDB 时的持久化语义索引；
记忆命中、写入、Artifact 恢复和 prompt augmentation 均可记录；
Memory hit 表示检索候选被返回，不直接等同于长期收益或语义准确率。

4. 目录结构

Agentos/
├── src/macc/                 # 系统源代码
│   ├── agents/               # Agent 和角色工厂
│   ├── protocol/             # Envelope、G²CP、序列化和总线
│   ├── runtime/              # Workflow、ContextManifest、多进程运行时
│   ├── state/                # Artifact、共享状态、KV 和状态桥接
│   ├── memory/               # MemoryStore、Chroma、StateMemoryStore
│   ├── models/               # HuggingFace provider 和模型适配
│   └── experiments/          # 实验 harness、分析和指标
├── src/config/               # Agent、Workflow、模型和记忆配置
├── src/docs/                 # 架构、协议和部署说明
├── tests/run_all.py          # 统一运行入口
├── tests/README.md           # 实验与测试说明
├── tests/results/            # 本地实验输出和已保存结果
├── demo/                     # 网页前端、演示工作区和服务测试
├── pyproject.toml            # Python 包及可选依赖定义
└── requirements.txt          # 兼容安装方式的依赖列表

5. 系统环境

5.1 最小环境：mock、协议和本地微基准

Linux、macOS 或其他能够运行 Python 多进程的系统；
Python 3.11（pyproject.toml 声明最低为 3.11）；
8 GB 以上内存更适合运行完整 mock 实验；
不需要 NVIDIA GPU，不需要模型权重，不需要外部服务。

5.2 真实模型环境

Linux；
Python 3.11；
NVIDIA GPU、匹配的 PyTorch CUDA 版本和足够的显存；
本地可访问的 HuggingFace 模型目录或模型仓库；
0.5B 模型适合本地功能验证，32B 模型需要更多显存和存储。32B 不是评审运行项目的必要条件。

5.3 可选依赖环境

ChromaDB：持久化语义记忆；
Transformers、Accelerate：真实 HuggingFace 模型推理；
Wasmtime：WASM 沙盒工具；
pytest：自动化测试；
Node.js：网页前端语法和演示测试。

6. 依赖要求

基础依赖记录在 pyproject.toml，包括：

openai, pydantic, pyyaml, python-dotenv, rich, numpy, msgpack

可选依赖组包括：

test        pytest
metadata    plyvel
layout      cstruct
experiments chromadb, transformers, accelerate, wasmtime, pyzmq

推荐使用虚拟环境安装：

cd Agentos
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[test]'
# 需要真实模型、Chroma 或 WASM 时：
python -m pip install -e '.[test,experiments]'

如果本机尚未安装 PyTorch，请根据本机 CPU/CUDA 环境从 PyTorch 官方渠道安装匹配版本，再安装项目实验依赖。不要盲目复制某一台实验机器的 CUDA 安装命令。

7. 构建与安装

本项目是 Python 源码项目，不需要单独编译主程序。推荐的构建/安装步骤如下：

cd Agentos
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools
python -m pip install -e '.[test]'

安装后检查导入和命令入口：

PYTHONPATH=src python -c 'import macc; print(macc.__file__)'
PYTHONPATH=.:src python -m tests.run_all --help

若只进行无模型验证，不需要下载 Qwen 或 embedding 权重。运行真实模型时，应在配置文件或环境变量中设置模型路径；默认配置可查看 src/config/models.yaml。

8. 运行方法

以下命令均从 /Agentos 目录执行，输出目录可以替换为任意有写权限的本地路径。

8.1 最小 mock 运行

PYTHONPATH=.:src python -m tests.run_all \
  --mock --suite paper --mode single --repeats 1 \
  --output-dir /tmp/macc-paper-mock

该命令验证工作流编排、条件执行、结果落盘和分析链路，不代表真实模型质量、GPU 性能或论文结论。

8.2 本地真实模型运行

确认模型配置和本地 GPU 可用后运行：

PYTHONPATH=.:src python -m tests.run_all \
  --suite paper --mode single --repeats 1 \
  --output-dir /tmp/macc-paper-real

多进程模式为：

PYTHONPATH=.:src python -m tests.run_all \
  --suite paper --mode multiprocess --repeats 1 \
  --output-dir /tmp/macc-paper-multiprocess

多进程运行需要本机支持 Python spawn、独立 Worker 和相应的模型显存；它不要求特定调度器，但资源需求通常高于 mock 或单进程运行。

8.3 独立机制实验

# JSON/MessagePack、Pipe、Queue、loopback TCP 和共享状态通信
PYTHONPATH=.:src python -m tests.run_all --experiment communication --output-dir /tmp/macc-communication

# 状态发布、字段/block 选择性读取和物化
PYTHONPATH=.:src python -m tests.run_all --experiment state --output-dir /tmp/macc-state

# Logical TCP 状态同步、ACK 和恢复事件
PYTHONPATH=.:src python -m tests.run_all --experiment logical --output-dir /tmp/macc-logical

8.4 分析已有结果

不启动模型即可分析已保存的当前结果：

PYTHONPATH=.:src python -m tests.run_all --analyze --output-dir tests/results/paper/current

若需要把生成的第四章写入仓库外的项目说明书，可在本机自行指定有写权限的相对路径：

PYTHONPATH=.:src python -m tests.run_all --analyze \
  --output-dir tests/results/paper/current \
  --chapter-file ../项目说明文档.md

9. 测试方法

9.1 单元和集成测试

cd Agentos
source .venv/bin/activate
PYTHONPATH=src python -m pytest -q

项目当前自动化 Python 测试主要位于 tests/service/；完整测试命令会自动收集仓库中可用测试。

9.2 服务和网页演示测试

若已安装 Node.js：

PYTHONPATH=src python -m pytest tests/service -q
node --check demo/visualization/app.js
node tests/service/test_frontend.js
bash -n demo/start_frontend.sh src/scripts/start_remote_tunnel.sh

网页静态前端可以本地启动：

bash demo/start_frontend.sh

打开 http://127.0.0.1:8765/。仅启动静态页面不会自动启动模型 API；需要真实服务时请按照 src/macc/service/ 的入口和本地模型配置启动后端。

9.3 结果审计

已保存结果位于：

tests/results/paper/current/raw/
tests/results/paper/current/tables/
tests/results/paper/current/figures/

分析脚本会校验原始 JSONL 与 audit 中的 SHA-256。不要把历史目录、临时输出或不同运行条件混合到 current/ 中。

10. 已知限制

实验规模限制：端到端样本按条件运行次数有限，不用于计算稳定的统计显著性或普遍适用的 P95；
通信范围限制：通信微基准是单主机 CPU 实验，不能推导跨节点网络吞吐、GPU DMA 或分布式存储性能；
状态物化范围：状态读取实验验证字段/block 选择和消费回执，但单个范围的测量不能包装成稳定分位数结论；
Logical TCP 定位：该实验验证状态同步、ACK 和恢复路径，不是网络吞吐基准；
记忆证据边界：Memory hit 只能证明候选检索进入执行链，不能直接证明长期复用收益或相关性准确率；
模型兼容性：KV/hidden state 与模型、dtype、进程和版本相关，跨模型或跨任务持久化会回退到摘要、SSC 或 Artifact；
资源需求：真实大模型和多进程模式需要本地足够的 GPU、内存和磁盘；无法满足时应先使用 mock 或 0.5B 模型；
代码任务评价：当前代码工作流的输出评分不等于独立隐藏测试 oracle 的代码正确率；
安全边界：工具沙盒和网页服务仅适合本地受控演示，不提供公网鉴权、多用户隔离或生产级安全保证。

11. 主要文档和代码入口

src/docs/ARCHITECTURE.md：系统架构和组件边界；
src/docs/PROTOCOL.md：Envelope、StatePointer 和 G²CP 协议；
src/docs/DEPLOYMENT.md：本地安装、运行和排错；
tests/README.md：实验入口、结果目录和审计规则；
tests/results/paper/current/：已保存机制基准和端到端结果；
tests/run_all.py：所有实验的统一命令入口；
项目主要创新说明.md：三项主要创新与代码、验证证据的对应关系。

12. 许可与第三方组件

项目使用的第三方库、模型和可选组件以 pyproject.toml、requirements.txt 及各自的官方许可为准。Qwen 模型、Transformers、ChromaDB、MessagePack、Wasmtime 等不属于本项目原创代码；发布或再分发前应分别核对其模型卡、许可证和使用条件。