🤖 自组织多智能体协作框架
特性 • 快速开始 • 架构概览 • 文档 • 示例 • 贡献
--- ## 简介  Agent Society 是一个基于大语言模型（LLM）的自组织多智能体协作框架。系统仅提供最小化的能力原语与运行时，组织结构由智能体在运行时自主建立与演化。 核心设计理念： - **最小化系统**：系统只提供能力，不提供组织社会规则 - **自组织**：组织结构、岗位职责、协作规则由智能体自主决定 - **上下文最小化**：通过任务拆解，让每个智能体只控制必要的最小上下文 - **异步协作**：智能体之间通过异步消息通信，支持并行处理与并发控制  ## 特性 - 🏗️ **组织构建原语**：创建岗位、创建智能体实例、维护父子链结构 - 🧠 **多模型支持**：支持配置多个 LLM 服务（OpenAI, Anthropic, Local LLMs 等），并根据岗位需求自动选择最合适的模型 - 🔌 **模块化系统**：支持动态加载外部模块，扩展工具集、Web 组件和 HTTP 路由 - 📋 **结构化任务委托**：基于 Task Brief 的标准化任务分发与上下文注入 - 🤝 **智能联系人管理**：自动维护协作关系网络，支持跨任务协作 - 📨 **异步消息通道**：发送、投递、接收与基础排队，支持并发控制 - 📦 **工件存储与引用**：跨岗位交付以工件引用为主，避免长上下文传递 - 📝 **提示词模板系统**：系统预置提示词与拼接模板加载 - 🔧 **丰富的工具集**：文件操作、HTTP 请求、JavaScript 沙箱运行、上下文压缩、SSH远程连接等 - 📊 **上下文管理**：自动监控上下文使用率，支持压缩、摘要与硬性限制保护 - 🌐 **HTTP API & Web UI**：内置 HTTP 服务器与可视化 Web 界面 - 📋 **完整日志系统**：分模块日志记录，支持多级别配置与生命周期追踪 ## 快速开始 ### 环境要求 - [Bun](https://bun.sh/) >= 1.0（推荐）或 Node.js >= 18 - 兼容 OpenAI API 的 LLM 服务（本地或远程） ### 安装 ```bash # 克隆仓库 git clone https://gitee.com/duzc2/agent_society.git cd agent-society # 安装依赖 bun install ``` ### 配置 1. 复制并编辑配置文件： ```bash cp config/app.json config/app.local.json cp config/llmservices_template.json config/llmservices.local.json ``` 2. 配置主程序（`config/app.local.json`）： ```json { "llm": { "baseURL": "http://127.0.0.1:1234/v1", "model": "your-default-model", "apiKey": "your-api-key" }, "modules": { "chrome": { "headless": false }, "ssh": { "enabled": true } } // 启用可选模块 } ``` 3. 配置多模型服务（`config/llmservices.local.json`，可选）： ```json { "services": [ { "id": "gpt4", "name": "GPT-4 Service", "baseURL": "https://api.openai.com/v1", "model": "gpt-4", "apiKey": "sk-...", "capabilityTags": ["reasoning", "coding"], "description": "擅长复杂推理和编程任务" }, { "id": "local-fast", "name": "Local Fast Model", "baseURL": "http://localhost:1234/v1", "model": "qwen2.5-7b-instruct", "apiKey": "any", "capabilityTags": ["chat", "fast"], "description": "响应速度快，适合简单对话" } ] } ``` ### 启动服务器 最简单的方式是启动空环境服务器，然后通过 Web 界面交互： ```bash # 使用默认配置启动（数据目录: ./agent-society-data，端口: 3000） bun start # 或使用平台脚本 ./start.sh # Unix/macOS start.cmd # Windows # 自定义数据目录 bun start ./my-data # 自定义端口 bun start --port 3001 # 不自动打开浏览器 bun start --no-browser # 组合使用 bun start ./my-data --port 3001 --no-browser ``` 服务器启动后会自动打开浏览器访问 Web 界面（`http://localhost:3000`）。 ### 运行示例 ```bash # 简单计算示例 bun run demo/demo1.js # 交互式饭店模拟 bun run demo/demo3.js # 自组织编程团队 bun run demo/dev_team.js -w ./my_project -r "创建一个计算器程序" ``` ## 架构概览 ``` ┌─────────────────────────────────────────────────────────────┐ │ AgentSociety │ │ (core/agent_society.js) │ │ (用户入口：提交需求、发送消息、接收回传) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Runtime │ │ (core/runtime.js) │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │MessageBus│ │OrgPrimi-│ │Services │ │Runtime │ │ │ │(消息通道)│ │tives │ │(服务模块)│ │(子模块) │ │ │ │ │ │(组织原语)│ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │Utils │ │Extensio-│ │Prompt │ │ │ │(工具模块)│ │ns │ │Loader │ │ │ │ │ │(扩展) │ │(提示词) │ │ │ └─────────┘ └─────────┘ └─────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Agent Instances │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Root │───▶│ Agent A │───▶│ Agent B │ │ │ │(根智能体)│ │(子智能体)│ │(孙智能体)│ │ │ └─────────┘ └─────────┘ └─────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 模块组织 系统采用模块化架构，按功能域清晰组织： - **核心模块 (core/)**: 系统基础（AgentSociety、Runtime、MessageBus、OrgPrimitives） - **服务模块 (services/)**: 独立功能服务（工件、LLM、会话、工作空间、HTTP、联系人） - **Runtime子模块 (runtime/)**: Runtime职责拆分（状态、事件、生命周期、消息、工具、LLM） - **工具模块 (utils/)**: 辅助功能（消息、内容、配置、日志） - **扩展模块 (extensions/)**: 可插拔扩展（模块加载器、工具组管理器） ### 核心概念 | 概念 | 说明 | |------|------| | **组织 (Organization)** | 岗位与智能体实例构成的层级结构 | | **岗位 (Role)** | 岗位职责、能力边界、输入输出标准的模板定义，可绑定特定 LLM 服务 | | **智能体实例 (Agent)** | 某岗位在某任务场景中的一次运行实体 | | **任务委托书 (Task Brief)** | 标准化的任务描述对象，包含目标、约束、输入输出和协作关系 | | **工件 (Artifact)** | 任务中产生的可持久化产物 | | **异步消息** | 智能体之间的协作载体 | | **模块 (Module)** | 可插拔的功能扩展单元，提供工具、UI 和 API | ## 文档 详细文档请参阅 [docs](./docs) 目录： - [快速入门指南](./docs/getting-started.md) - [架构设计](./docs/architecture.md) - [API 参考](./docs/api-reference.md) - [配置说明](./docs/configuration.md) - [工具参考](./docs/tools.md) - [示例教程](./docs/examples.md) ## 示例 ### Demo 1: 简单计算 最简单的使用示例，提交计算需求并等待结果： ```javascript import { AgentSociety } from "./src/platform/agent_society.js"; const system = new AgentSociety({ dataDir: "data/demo1" }); await system.init(); const { taskId } = await system.submitRequirement("计算 5+3 等于几？"); const reply = await system.waitForUserMessage( (m) => m?.taskId === taskId, { timeoutMs: 60000 } ); console.log(reply?.payload?.text); ``` ### Demo 3: 饭店经营模拟 一个完整的自组织场景，智能体自主创建饭店组织结构： ```bash bun run demo/demo3.js ``` ### Dev Team: 自组织编程团队 架构师智能体分析需求、创建程序员智能体、协作完成开发任务： ```bash bun run demo/dev_team.js -w ./my_project -r "创建一个待办事项应用" ``` ## 项目结构 ``` agent-society/ ├── config/ # 配置文件 │ ├── app.json # 主配置 │ ├── llmservices.json # 多模型服务配置 │ ├── logging.json # 日志配置 │ └── prompts/ # 系统提示词模板 ├── src/ │ ├── agents/ # 智能体定义 │ │ └── agent.js │ └── platform/ # 平台核心组件 │ ├── core/ # 核心模块 │ │ ├── agent_society.js # 系统入口 │ │ ├── runtime.js # 运行时核心 │ │ ├── message_bus.js # 消息总线 │ │ └── org_primitives.js # 组织原语 │ ├── services/ # 服务模块 │ │ ├── artifact/ # 工件服务 │ │ │ ├── artifact_store.js │ │ │ ├── binary_detector.js │ │ │ └── content_router.js │ │ ├── llm/ # LLM服务 │ │ │ ├── llm_client.js │ │ │ ├── llm_service_registry.js │ │ │ ├── model_selector.js │ │ │ └── concurrency_controller.js │ │ ├── conversation/ # 会话服务 │ │ │ └── conversation_manager.js │ │ ├── workspace/ # 工作空间服务 │ │ │ ├── workspace_manager.js │ │ ├── http/ # HTTP服务 │ │ │ ├── http_server.js │ │ │ └── http_client.js │ │ └── contact/ # 联系人服务 │ │ └── contact_manager.js │ ├── runtime/ # Runtime子模块 │ │ ├── runtime_state.js # 状态管理 │ │ ├── runtime_events.js # 事件系统 │ │ ├── runtime_lifecycle.js # 智能体生命周期 │ │ ├── runtime_messaging.js # 消息处理循环 │ │ ├── runtime_tools.js # 工具管理 │ │ ├── runtime_llm.js # LLM交互 │ │ ├── agent_manager.js # 智能体管理器 │ │ ├── message_processor.js # 消息处理器 │ │ ├── tool_executor.js # 工具执行器 │ │ ├── llm_handler.js # LLM处理器 │ │ ├── context_builder.js # 上下文构建器 │ │ ├── javascript_executor.js # JS执行器 │ │ ├── browser_javascript_executor.js # 浏览器JS执行器 │ │ └── shutdown_manager.js # 关闭管理器 │ ├── utils/ # 工具模块 │ │ ├── message/ # 消息工具 │ │ │ ├── message_formatter.js │ │ │ ├── message_validator.js │ │ │ └── task_brief.js │ │ ├── content/ # 内容工具 │ │ │ ├── content_adapter.js │ │ │ └── capability_router.js │ │ ├── config/ # 配置工具 │ │ │ ├── config_loader.js │ │ │ └── config_service.js │ │ └── logger/ # 日志工具 │ │ └── logger.js │ ├── extensions/ # 扩展模块 │ │ ├── module_loader.js │ │ └── tool_group_manager.js │ ├── prompt_loader.js # 提示词加载器 │ └── index.js # 统一导出 ├── modules/ # 可插拔模块 │ ├── chrome/ # Chrome浏览器控制模块 │ └── ssh/ # SSH远程连接模块 ├── demo/ # 示例程序 ├── test/ # 测试文件 ├── docs/ # 文档 └── data/ # 运行时数据 ``` ### 目录说明 - **core/**: 系统核心模块，包含系统入口、运行时、消息总线和组织原语 - **services/**: 独立的服务模块，按功能域组织（工件、LLM、会话、工作空间、HTTP、联系人） - **runtime/**: Runtime的子模块，将Runtime的职责拆分为多个独立模块 - **utils/**: 工具模块，提供辅助功能（消息、内容、配置、日志） - **extensions/**: 扩展模块，提供可插拔的功能扩展 ## 运行测试 ```bash bun test ``` ## 开发指南 ### 代码组织 项目采用模块化架构，遵循以下原则： - **单一职责**：每个模块只负责一项功能 - **高内聚低耦合**：相关功能集中，模块间依赖最小化 - **代码行数限制**：每个文件不超过500行（不含注释） - **清晰的目录结构**：按功能域组织，目录层级不超过3层 ### 导入路径 推荐使用新的模块化导入路径： ```javascript // 核心模块 import { AgentSociety } from './src/platform/core/agent_society.js'; import { Runtime } from './src/platform/core/runtime.js'; // 服务模块 import { ArtifactStore } from './src/platform/services/artifact/artifact_store.js'; import { LlmClient } from './src/platform/services/llm/llm_client.js'; // 或使用统一导出 import { AgentSociety, Runtime, ArtifactStore, LlmClient } from './src/platform/index.js'; ``` 旧的导入路径仍然可用（通过兼容性导出），但建议更新为新路径。 ### 添加新功能 1. **确定模块位置**：根据功能类型选择合适的目录（core/services/runtime/utils/extensions） 2. **遵循命名规范**：使用清晰的文件名和函数名 3. **编写测试**：为新功能编写单元测试和集成测试 4. **更新文档**：在相应的目录说明文档中添加说明 ### 代码重构 系统经历了全面的代码重构，主要变更包括： - 目录结构优化：按功能域组织模块 - Runtime类拆分：将职责分散到多个子模块 - 模块合并：消除职责重叠 - 服务模块化：按功能域组织服务 详细的重构说明请参阅 [架构设计文档](./docs/architecture.md#代码重构说明)。 ## 贡献 欢迎贡献代码、报告问题或提出建议！ 1. Fork 本仓库 2. 创建特性分支 (`git checkout -b feature/amazing-feature`) 3. 提交更改 (`git commit -m 'Add amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 创建 Pull Request ## 许可证 本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。 ## 致谢 - 感谢所有贡献者的付出 - 本项目使用 [OpenAI API](https://openai.com/) 兼容接口 ---Made with ❤️ by the Agent Society Team