Update README.md
面向多智能体协作场景的一体化可视化系统，围绕任务分类 → 协同规划 → 智能回答 → 内容总结 → 结果格式化构建清晰、可观察、可对比的 Agent 工作链路。
🌟 核心能力 · 🏗️ 系统架构 · 🚀 快速开始 · 🔌 API 概览 · 📚 扩展文档
DeepOS-Agent 让多个职责明确的 Agent 在统一协调器下完成任务，并将通信、记忆、执行与统计过程集中呈现在一个 Web 系统中。
用户任务 ↓ 任务分类 → 协同规划 → 智能回答 → 内容总结 → 结果格式化 ↓ ↓ ↓ ↓ ↓ 类型识别 步骤组织 LLM 处理 信息归纳 统一展示 ↕ 共享记忆与结果复用
MultiAgentCollaboration 是一个基于 Flask 构建的多智能体协作 Web 应用。系统通过 Coordinator 统一组织多个职责不同的 Agent，接收用户任务后完成分类、规划、回答生成、内容总结与结果格式化，并通过可视化页面集中呈现执行结果、通信开销、记忆复用和运行统计。
MultiAgentCollaboration
Coordinator
系统提供两种可对比的信息传递方式：
AgentMessage
项目将 多 Agent 编排、消息协议、共享记忆、向量检索、CodeAct 与 Web 可视化 集中到同一套运行链路中，可用于系统演示、协作机制观察、通信模式对比和功能扩展。
当前系统中共有 6 类 Agent 实例：
ClassifierAgent
PlannerAgent
SearcherAgent
SummarizerAgent
FormatterAgent
CodeActAgent
flowchart LR U[用户 / Web UI] --> API[Flask API] API --> W[CoordinatorWrapper] W --> C[Coordinator] C --> A1[ClassifierAgent] C --> A2[Planner / 固定计划] C --> A3[SearcherAgent] C --> A4[SummarizerAgent] C --> A5[FormatterAgent] C -. 可选 .-> A6[CodeActAgent] C <--> M[(SharedMemory\nJSON + Index)] M <--> V[(Faiss / NumPy\nVector Store)] W --> S[(Stats)] A3 -. OpenAI 兼容接口 .-> LLM[LLM Service] A1 -. OpenAI 兼容接口 .-> LLM A6 -. 生成代码 .-> LLM
MultiAgentCollaboration/ ├─ agents/ # Agent 基类、分类、规划、格式化与 CodeAct ├─ communication/ # AgentMessage 等通信协议 ├─ core/ # 协调器、包装层与统计逻辑 ├─ memory/ # 共享记忆与向量存储 ├─ web/ │ ├─ templates/ # 基础版、默认版、Premium 等页面 │ └─ static/ # 前端静态资源 ├─ data/ │ ├─ memory/ # JSON 记忆与索引 │ ├─ vectors/ # 向量数据 │ └─ stats/ # 运行统计 ├─ tests/ # 演示、基准及脚本式测试 ├─ docs/ # 项目、API、部署与 CodeAct 相关文档 ├─ app.py # Flask 应用入口 ├─ config.py # 配置项与目录定义 ├─ batch_test.py # 批量测试脚本 ├─ Dockerfile ├─ docker-compose.yml └─ .env.example
faiss-cpu
Windows PowerShell：
python -m venv venv .\venv\Scripts\Activate.ps1
Linux / macOS：
python3 -m venv venv source venv/bin/activate
python -m pip install Flask flask-cors openai numpy
按需安装：
# Faiss 向量索引 python -m pip install faiss-cpu # 部分演示/批量脚本 python -m pip install requests colorama # CodeAct 若生成相关代码，可能还需要 python -m pip install pandas matplotlib
当前配置读取以下环境变量：
OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_MODEL
Linux：
export OPENAI_API_KEY="your-api-key" export OPENAI_BASE_URL="https://your-provider.example/v1" export OPENAI_MODEL="your-model-name"
$env:OPENAI_API_KEY = "your-api-key" $env:OPENAI_BASE_URL = "https://your-provider.example/v1" $env:OPENAI_MODEL = "your-model-name"
python app.py
默认可访问：
以下路由以当前 app.py 为准：
app.py
POST
/api/task
/api/execute
/api/compare
GET
/api/stats
/api/stats/detailed
/api/agents/status
/api/memory
keyword
/api/memory/list
/api/memory/<id>
/api/memory/clear
/api/faiss/vectors
/api/codeact/history
/api/codeact/clear
/api/performance/charts
接口的具体请求字段和返回结构请以 app.py 为准；docs/ 中的补充文档可能对应较早版本。
docs/
SharedMemory 不是操作系统级共享内存，而是一个本地文件持久化层：
SharedMemory
data/memory/index.json
系统提供两种后端：
启用 use_codeact 后，系统可以让 LLM 生成 Python 代码，经过字符串黑名单和 import 白名单检查后，通过当前 Python 解释器在临时目录中执行。
use_codeact
当前已有的保护措施：
但它仍有明确边界：
系统会记录消息数量、估算消息大小、Agent 调用、记忆命中和耗时等数据。这些指标适合用于原型内部的相对比较。
tests/ 和根目录中的测试文件以可直接运行的脚本、演示和基准测试为主。
tests/
系统对比了 结构化协议（Struct-Ref） 和 纯文本协议（Text-Full） 两种通信模式在 9 个跨领域任务上的 Token 消耗：
核心发现：
统计数据：
测试目标： 验证共享记忆系统在同一主题关联任务中的复用准确率、性能提升和渐进式知识积累能力。
测试说明： 每组任务包含同一主题的 3 个相关查询，观察系统能否识别关联并复用历史记忆，从而大幅缩短执行时间并避免重复 LLM 调用。
✨ 核心指标 ✨
🎯 优化方向： 动态阈值 + Embedding 微调
测试结论：
版权所有：中国计算机学会技术支持：开源发展技术委员会 京ICP备13000930号-9 京公网安备 11010802047560号
多智能体协作 · 结构化通信 · 共享记忆 · 智能执行
面向多智能体协作场景的一体化可视化系统，围绕
任务分类 → 协同规划 → 智能回答 → 内容总结 → 结果格式化
构建清晰、可观察、可对比的 Agent 工作链路。
🌟 核心能力 · 🏗️ 系统架构 · 🚀 快速开始 · 🔌 API 概览 · 📚 扩展文档
🌐 项目总览
🔄 核心工作流
✨ 项目简介
MultiAgentCollaboration是一个基于 Flask 构建的多智能体协作 Web 应用。系统通过Coordinator统一组织多个职责不同的 Agent，接收用户任务后完成分类、规划、回答生成、内容总结与结果格式化，并通过可视化页面集中呈现执行结果、通信开销、记忆复用和运行统计。系统提供两种可对比的信息传递方式：
AgentMessage传递任务参数、执行结果与记忆引用，便于统一组织和追踪协作状态；项目将 多 Agent 编排、消息协议、共享记忆、向量检索、CodeAct 与 Web 可视化 集中到同一套运行链路中，可用于系统演示、协作机制观察、通信模式对比和功能扩展。
🌟 核心能力
AgentMessage统一承载任务与状态🧠 Agent 组成
当前系统中共有 6 类 Agent 实例：
ClassifierAgentPlannerAgentSearcherAgentSummarizerAgentFormatterAgentCodeActAgent🏗 系统架构
flowchart LR U[用户 / Web UI] --> API[Flask API] API --> W[CoordinatorWrapper] W --> C[Coordinator] C --> A1[ClassifierAgent] C --> A2[Planner / 固定计划] C --> A3[SearcherAgent] C --> A4[SummarizerAgent] C --> A5[FormatterAgent] C -. 可选 .-> A6[CodeActAgent] C <--> M[(SharedMemory\nJSON + Index)] M <--> V[(Faiss / NumPy\nVector Store)] W --> S[(Stats)] A3 -. OpenAI 兼容接口 .-> LLM[LLM Service] A1 -. OpenAI 兼容接口 .-> LLM A6 -. 生成代码 .-> LLM一次常规请求的大致流程
📁 项目结构
🚀 快速开始
1. 环境要求
faiss-cpu。2. 创建虚拟环境
Windows PowerShell：
Linux / macOS：
3. 安装基础依赖
按需安装：
4. 配置模型服务
当前配置读取以下环境变量：
OPENAI_API_KEYOPENAI_BASE_URLOPENAI_MODELLinux：
5. 启动应用
默认可访问：
🔌 API 概览
以下路由以当前
app.py为准：POST/api/taskPOST/api/executePOST/api/compareGET/api/statsGET/api/stats/detailedGET/api/agents/statusGET/api/memorykeyword查询参数搜索记忆GET/api/memory/listGET/api/memory/<id>POST/api/memory/clearGET/api/faiss/vectorsGET/api/codeact/historyPOST/api/codeact/clearGET/api/performance/charts接口的具体请求字段和返回结构请以
app.py为准；docs/中的补充文档可能对应较早版本。🧩 共享记忆与向量检索
文件记忆
SharedMemory不是操作系统级共享内存，而是一个本地文件持久化层：data/memory/index.json维护索引；向量存储
系统提供两种后端：
faiss-cpu：使用 Faiss 索引；🧪 CodeAct：实验性代码执行
启用
use_codeact后，系统可以让 LLM 生成 Python 代码，经过字符串黑名单和 import 白名单检查后，通过当前 Python 解释器在临时目录中执行。当前已有的保护措施：
但它仍有明确边界：
📊 统计数据如何理解
系统会记录消息数量、估算消息大小、Agent 调用、记忆命中和耗时等数据。这些指标适合用于原型内部的相对比较。
✅ 测试与验证现状
tests/和根目录中的测试文件以可直接运行的脚本、演示和基准测试为主。� 通信效率测试结果
📊 结构化协议 vs 纯文本协议 Token 消耗对比
系统对比了 结构化协议（Struct-Ref） 和 纯文本协议（Text-Full） 两种通信模式在 9 个跨领域任务上的 Token 消耗：
编号
Token
Token
下降 ↓
核心发现：
统计数据：
🧠 共享记忆复用测试结果
📋 记忆复用机制跨任务历史检索效果
测试目标： 验证共享记忆系统在同一主题关联任务中的复用准确率、性能提升和渐进式知识积累能力。
测试说明： 每组任务包含同一主题的 3 个相关查询，观察系统能否识别关联并复用历史记忆，从而大幅缩短执行时间并避免重复 LLM 调用。
✨ 核心指标 ✨
🎯 优化方向： 动态阈值 + Embedding 微调
编号
结果
结果
时间
研究系列
编程系列
系列
系列
系列
测试结论：