ROMA-Chinese: 递归开放元智能体 (中文增强版)

专为中文用户打造的分层高性能多智能体系统！包含Windows原生支持和智谱GLM-4.5集成 (Beta)

Technical Blog • Paper (Coming soon) • Build Agents for $$$

• 🪟 Windows原生部署 - 完整的Windows部署脚本和环境配置
• 🇨🇳 智谱GLM-4.5集成 - 零配置智谱AI模型接入指南
• 📊 可视化智能体监控 - 实时观察智能体执行过程

• 🚀 项目介绍 - 了解ROMA的架构和设计理念
• 📦 安装配置 - 详细的配置选项和环境设置
• 🤖 智能体指南 - 学习创建和定制专属智能体
• ⚙️ 配置详解 - 深入的配置选项和环境设置
• 🗺️ 发展路线 - 查看ROMA的未来规划
• 🌟 原开源项目 - 查看原始项目和更多资源

🌟 ROMA-Chinese特别增强版: 本项目基于原开源ROMA框架，专门为中文用户增加了Windows原生部署脚本和智谱GLM-4.5原生支持，让国内开发者零门槛体验先进的递归智能体技术。

ROMA-Chinese 是一个元智能体框架的中文增强版本，使用递归分层结构来解决复杂问题。通过将任务分解为可并行化的组件，ROMA-Chinese使智能体能够处理复杂的推理挑战，同时保持透明度，使上下文工程和迭代变得简单明了。

🇨🇳 中文增强特性:

• 并行问题解决 - 智能体同时处理复杂任务的不同部分
• 透明开发 - 清晰的结构便于调试，中文界面可视化监控
• Windows原生支持 - 一键部署脚本，无需复杂配置
• 智谱GLM-4.5集成 - 原生中文大模型支持，零配置接入

作为开源且可扩展的平台，ROMA-Chinese专为中文社区驱动开发而设计，让您可以根据特定需求构建和定制智能体，同时受益于中文社区的集体改进。

ROMA-Chinese 框架通过递归的规划-执行循环来处理任务：

def solve(task):
    if is_atomic(task):                 # Step 1: Atomizer
        return execute(task)            # Step 2: Executor
    else:
        subtasks = plan(task)           # Step 2: Planner
        results = []
        for subtask in subtasks:
            results.append(solve(subtask))  # Recursive call
        return aggregate(results)       # Step 3: Aggregator

# Entry point:
answer = solve(initial_request)

1. 原子化器 – 决定请求是否为原子级（可直接执行）或需要规划。
2. 规划器 – 如果需要规划，任务被分解为更小的子任务。每个子任务都被反馈到原子化器，使过程递归。
3. 执行器 – 处理原子任务。执行器可以是大语言模型、API或甚至其他智能体——只要它们实现了agent.execute()接口。
4. 聚合器 – 收集并整合子任务的结果。重要的是，聚合器产出的是原始父任务的答案，而不仅仅是原始子输出。

• Top-down: Tasks are decomposed into subtasks recursively.
• Bottom-up: Subtask results are aggregated upwards into solutions for parent tasks.
• Left-to-right: If a subtask depends on the output of a previous one, it waits until that subtask completes before execution.

This structure makes the system flexible, recursive, and dependency-aware — capable of decomposing complex problems into smaller steps while ensuring results are integrated coherently.

flowchart TB
    A[Your Request] --> B{Atomizer}
    B -->|Plan Needed| C[Planner]
    B -->|Atomic Task| D[Executor]

    %% Planner spawns subtasks
    C --> E[Subtasks]
    E --> G[Aggregator]

    %% Recursion
    E -.-> B  

    %% Execution + Aggregation
    D --> F[Final Result]
    G --> F

    style A fill:#e1f5fe
    style F fill:#c8e6c9
    style B fill:#fff3e0
    style C fill:#ffe0b2
    style D fill:#d1c4e9
    style G fill:#c5cae9

• 自上而下：任务递归地分解为子任务。
• 自下而上：子任务结果向上聚合为父任务的解决方案。
• 从左到右：如果子任务依赖于前一个任务的输出，它会等待该子任务完成后再执行。

这种结构使系统具有灵活性、递归性和依赖感知能力——能够将复杂问题分解为更小的步骤，同时确保结果得到连贯整合。

# 1. 克隆中文增强版项目
git clone https://github.com/hhhh124hhhh/ROMA-Chinese.git
cd ROMA-Chinese

# 2. 配置智谱AI密钥
echo "ZHIPUAI_API_KEY=你的智谱AI密钥" > .env

# 3. 一键启动（Windows）
setup.bat --docker --glm45
start_fullstack.bat

# 4. 访问 http://localhost:3000 开始使用

git clone https://github.com/hhhh124hhhh/ROMA-Chinese.git
cd ROMA-Chinese

# 一键部署 - Docker方式（推荐）
setup.bat --docker

# 或者原生Windows环境
setup_native_windows.bat

# 快速启动服务
start_fullstack.bat

git clone https://github.com/hhhh124hhhh/ROMA-Chinese.git
cd ROMA-Chinese

# 自动化安装
./setup.sh

Choose between:

• Docker Setup (Recommended) - One-command setup with isolation
• Native Setup - Direct installation for development
• Windows Native (新增) - Full Windows support with batch scripts

• 🇨🇳 智谱GLM-4.5原生支持: 零配置接入智谱AI，专为中文优化
• 🪟 Windows原生部署: 完整批处理脚本，UV包管理器，中文环境支持
• 📊 可视化监控: 实时WebSocket展示智能体执行过程和状态

• Framework: 基于 AgnoAgents 构建
• Backend: Python 3.12+ with FastAPI/Flask
• Frontend: React + TypeScript with real-time WebSocket
• LLM Support: 支持任何提供商 via LiteLLM + 智谱AI GLM-4.5原生支持
• Platform Support: Linux/macOS + 完整Windows原生支持
• Data Persistence: 企业级S3挂载与安全验证
  • 🔒 goofys FUSE mounting 零延迟文件访问
  • 🛡️ 路径注入保护 全面验证机制
  • 🔐 AWS凭证验证 操作前预检
  • 📁 动态Docker Compose 安全卷挂载
• Code Execution: E2B沙箱与统一S3集成
• Security: 生产级验证和错误处理
• Features: 多模态、工具集成、MCP、钩子、缓存

# Linux/macOS - Main setup (choose Docker or Native)
./setup.sh

# Windows - Docker setup (Recommended)
setup.bat --docker

# Windows - Native setup
setup_native_windows.bat

# Optional: Setup E2B sandbox integration
./setup.sh --e2b

# Test E2B integration  
./setup.sh --test-e2b

# Linux/macOS
./setup.sh --docker     # Run Docker setup directly
./setup.sh --docker-from-scratch  # Rebuild Docker images/containers from scratch (down -v, no cache)
./setup.sh --native     # Run native setup directly (macOS/Ubuntu/Debian)
./setup.sh --e2b        # Setup E2B template (requires E2B_API_KEY + AWS creds)
./setup.sh --test-e2b   # Test E2B template integration
./setup.sh --help       # Show all available options

# Windows
setup.bat --docker      # Docker setup for Windows
setup.bat --help        # Show Windows-specific options
check_environment.bat    # Diagnose Windows environment
diagnose_environment.bat # Advanced Windows diagnostics

See setup docs for detailed instructions.

For secure code execution capabilities, optionally set up E2B sandboxes:

# After main setup, configure E2B (requires E2B_API_KEY and AWS credentials in .env)
./setup.sh --e2b

# Test E2B integration
./setup.sh --test-e2b

🌟 突破性改进: 完整的Windows原生部署解决方案，彻底解决原项目Windows支持不足的问题

# 🎯 智谱GLM-4.5 + Windows组合（推荐）
setup.bat --docker --glm45  # Docker + 智谱AI一键部署
start_fullstack.bat         # 全栈服务快速启动

# 🔧 灵活部署选项
setup.bat --docker            # Docker部署（推荐）
setup_native_windows.bat      # 原生Windows环境
quickstart.bat                # 智能启动向导

• 🎯 中文路径完美支持 - 解决Windows中文环境兼容性
• 📊 可视化启动界面 - 新窗口显示，状态一目了然
• 🔧 智能环境检测 - 自动发现并解决配置问题
• ⚡ UV包管理器 - 比pip快10倍的依赖安装

📖 详细指南: Windows完整部署文档

E2B Features:

• 🔒 Secure Code Execution - Run untrusted code in isolated sandboxes
• ☁️ S3 Integration - Automatic data sync between local and sandbox environments
• 🚀 goofys Mounting - High-performance S3 filesystem mounting
• 🔧 AWS Credentials - Passed securely via Docker build arguments

Note: These agents are demonstrations built using ROMA's framework through simple vibe-prompting and minimal manual tuning. They showcase how easily you can create high-performance agents with ROMA, rather than being production-final solutions. Our mission is to empower the community to build, share, and get rewarded for creating innovative agent recipes and use-cases.

ROMA comes with example agents that demonstrate the framework's capabilities:

A versatile agent powered by ChatGPT Search Preview for handling diverse tasks:

• Intelligent Search: Leverages OpenAI's latest search capabilities for real-time information
• Flexible Planning: Adapts task decomposition based on query complexity
• Multi-Domain: Handles everything from technical questions to creative projects
• Quick Prototyping: Perfect for testing ROMA's capabilities without domain-specific setup

Perfect for: General research, fact-checking, exploratory analysis, quick information gathering

🌟 突破性改进: 原生智谱AI GLM-4.5支持，填补了原项目中文大模型支持的空白

• 🚀 零配置接入: 仅需API密钥，无需第三方代理或复杂设置
• 🎯 中文优化: 专门针对中文语境设计的提示工程和交互逻辑
• 📊 可视化执行: 实时观察智能体的中文思考和推理过程
• ⚡ 极速体验: 本土化部署，响应速度显著提升

# 1️⃣ 设置智谱AI密钥（获取地址：https://open.bigmodel.cn/）
echo "ZHIPUAI_API_KEY=你的智谱AI密钥" > .env

# 2️⃣ 一键启动智谱AI智能体
setup.bat --docker --glm45
start_fullstack.bat

# 3️⃣ 打开浏览器访问 http://localhost:3000

学术研究: 中文论文写作、文献综述、研究报告
商业应用: 市场调研、竞品分析、商业计划书
内容创作: 技术文档、培训材料、营销文案
数据分析: 行业报告、趋势分析、可视化图表

📖 深入了解: 智谱GLM-4.5完整配置指南

A comprehensive research system that breaks down complex research questions into manageable sub-tasks:

• Smart Task Decomposition: Automatically splits research topics into search, analysis, and synthesis phases
• Parallel Information Gathering: Executes multiple searches simultaneously for faster results
• Multi-Source Integration: Combines results from web search, Wikipedia, and specialized APIs
• Intelligent Synthesis: Aggregates findings into coherent, well-structured reports

Perfect for: Academic research, market analysis, competitive intelligence, technical documentation

Specialized financial analysis agent with deep blockchain and DeFi expertise:

• Real-Time Market Data: Integrates with Binance, CoinGecko, and DefiLlama APIs
• On-Chain Analytics: Access to Arkham Intelligence for wallet tracking and token flows
• Technical Analysis: Advanced charting with OHLC data and market indicators
• DeFi Metrics: TVL tracking, yield analysis, protocol comparisons
• Secure Execution: Runs analysis in E2B sandboxes with data persistence

Perfect for: Token research, portfolio analysis, DeFi protocol evaluation, market trend analysis

All three agents demonstrate ROMA's recursive architecture in action, showing how complex queries that would overwhelm single-pass systems can be elegantly decomposed and solved. They serve as templates and inspiration for building your own specialized agents.

./setup.sh  # Automated setup with Docker or native installation

Access all the pre-defined agents through the frontend on localhost:3000 after setting up the backend on localhost:5000. Please checkout Setup and the Agents guide to get started!

# Your first agent in 3 lines
from sentientresearchagent import SentientAgent

agent = SentientAgent.create()
result = await agent.run("Create a podcast about AI safety")

We evaluate our simple implementation of a search system using ROMA, called ROMA-Search across three benchmarks: SEAL-0, FRAMES, and SimpleQA.
Below are the performance graphs for each benchmark.

SealQA is a new challenging benchmark for evaluating Search-Augmented Language models on fact-seeking questions where web search yields conflicting, noisy, or unhelpful results.

本项目基于以下优秀的开源贡献构建，在此致以诚挚敬意：

• 核心理论基础 - "Beyond Outlining: Heterogeneous Recursive Planning" (Xiong et al.) 的分层规划方法论
• 数据验证框架 - Pydantic 基于Python类型注解的数据验证
• 智能体构建 - Agno AI智能体构建框架
• 云运行环境 - E2B AI智能体云运行环境

📚 原项目资源: 查看原始ROMA项目获取更多技术文档和社区资源

🎯 核心增强: 本版本专门为中文开发者新增了Windows原生部署脚本和智谱GLM-4.5集成，彻底解决了原项目在Windows支持和中文大模型方面的不足。

# 🚀 一键体验核心功能
setup.bat --docker --glm45    # Docker + 智谱AI组合部署
start_fullstack.bat           # 全栈服务快速启动
diagnose_environment.bat      # 智能环境诊断修复

🔧 完整工具链:

• 批处理脚本体系 - 涵盖安装、启动、管理、诊断全流程
• UV包管理器 - 比pip快10倍的Python依赖管理体验
• 中文环境兼容 - 完美解决Windows中文路径和编码问题
• 可视化界面 - 新窗口启动，状态一目了然

# 🎯 零配置智谱AI体验
echo "ZHIPUAI_API_KEY=sk-xxx" > .env  # 设置API密钥
setup.bat --glm45                    # 智谱AI专用部署
# 🌐 访问 http://localhost:3000 开始使用

🇨🇳 中文优化特性:

• 零配置接入 - 直接支持智谱AI API，无需第三方代理
• 中文提示工程 - 专门优化的中文语境交互逻辑
• 简化配置 - GLM-4.5专用配置模板和启动脚本
• 可视化执行 - 实时观察中文智能体的思考推理过程

这些核心增强为中国的AI开发者和大模型从业者提供：

• 🔍 透明的智能体执行窗口 - 实时可视化观察智能体思考过程
• 🚀 零门槛快速上手 - Windows用户30秒即可体验前沿智能体技术
• 📚 完整中文学习资源 - 从入门到高级应用的全中文指导
• 🛠️ 生产就绪部署 - 适合企业环境的稳定部署方案

我们承诺继续遵循开源精神，将这些增强功能回馈给社区，与原项目保持兼容，共同推动AI智能体技术的发展和普及。

如果您在研究中使用了ROMA-Chinese仓库，请引用：

@software{al_zubi_2025_17052592,
  author       = {Al-Zubi, Salah and
                  Nama, Baran and
                  Kaz, Arda and
                  Oh, Sewoong and
                  ROMA-Chinese Contributors},
  title        = {ROMA-Chinese: 递归开放元智能体
                   中文增强版 - Windows原生支持和智谱GLM-4.5集成
                  },
  month        = sep,
  year         = 2025,
  publisher    = {GitHub},
  version      = {ROMA-Chinese-v1.0},
  url          = {https://github.com/hhhh124hhhh/ROMA-Chinese},
  note         = {基于原始ROMA框架的中文增强版本，新增了Windows原生部署和智谱GLM-4.5集成}
}

该项目采用Apache 2.0许可证 - 详情请参见LICENSE文件。