# ACEIntelliAgent

**Repository Path**: cmx1998/ace-intelligent-agent

## Basic Information

- **Project Name**: ACEIntelliAgent
- **Description**: 基于斯坦福大学等团队提出的Agentic Context Engineering（ACE）框架实现的可自我学习与进化的智能体原型系统。
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-05
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ACEIntelliAgent - 基于ACE框架的自学习进化智能体系统

## 项目介绍

基于斯坦福大学等团队提出的Agentic Context Engineering（ACE）框架实现的可自我学习与进化的智能体原型系统。该系统通过generation、reflection和curation的模块化工作流，实现上下文的自我优化和知识积累，无需修改模型参数即可显著提升性能。

## 核心特性

### 1. 自我学习与进化
- **Generator模块**：为新查询生成推理轨迹，暴露有效策略和反复出现的问题
- **Reflector模块**：批判生成的轨迹，提取经验教训，跨多次迭代精炼经验
- **Curator模块**：将经验教训合成紧凑的delta条目，通过轻量级非LLM逻辑确定性地合并到现有上下文中

### 2. 增量上下文管理
- **结构化Bullet系统**：上下文表示为结构化、分项的bullet集合，而非单一整体prompt
- **增量Delta更新**：避免完全重写上下文，支持并行处理多个delta
- **Grow-and-Refine机制**：周期性精炼上下文，保持紧凑性和相关性

### 3. 可视化监控
- **实时性能监控**：准确率、成功率、响应时间趋势图
- **上下文增长可视化**：Context Playbook大小、条目数量变化
- **学习进度可视化**：知识积累、经验增长曲线
- **交互式Dashboard**：Web界面实时显示智能体思考过程

## 系统架构

### 核心模块
```
ace-intelligent-agent/
├── core/                    # 核心框架
│   ├── __init__.py
│   ├── generator.py         # Generator模块
│   ├── reflector.py         # Reflector模块
│   ├── curator.py           # Curator模块
│   └── context_manager.py   # Context Manager
├── memory/                  # 记忆系统
│   ├── __init__.py
│   ├── bullet.py           # Bullet数据结构
│   ├── memory_store.py     # 记忆存储
│   └── retrieval.py        # 检索机制
├── database/               # 数据库管理
│   ├── __init__.py
│   ├── models.py          # 数据模型
│   ├── migrations.py      # 数据库迁移
│   └── connection.py      # 连接管理
├── agents/                 # 智能体实现
│   ├── __init__.py
│   ├── base_agent.py       # 基础智能体
│   ├── ace_agent.py        # ACE智能体
│   └── specialized/       # 领域专用智能体
├── visualization/          # 可视化模块
│   ├── __init__.py
│   ├── dashboard.py       # 仪表板
│   ├── charts.py          # 图表
│   └── web_ui/           # Web界面
├── logging/               # 日志系统
│   ├── __init__.py
│   ├── logger.py
│   └── log_analyzer.py
├── domains/               # 领域特定模块
│   ├── __init__.py
│   ├── appworld/
│   ├── finance/
│   └── general/
├── utils/                 # 工具函数
│   ├── __init__.py
│   ├── serialization.py
│   ├── metrics.py
│   └── performance.py
├── docker/                # Docker相关配置
│   ├── Dockerfile
│   └── docker-compose.yml
├── .github/               # CI/CD配置
│   └── workflows/
├── examples/
├── tests/
└── main.py
```

### 数据库设计

使用SQLite作为默认存储（轻量级、易于部署），同时支持扩展到PostgreSQL等其他数据库：

#### 核心数据表
- **bullets表**：存储上下文条目（id, content, metadata, helpful_count, harmful_count, created_at, updated_at）
- **execution_traces表**：存储执行轨迹（id, query, solution, result, feedback, timestamp）
- **context_history表**：存储上下文演变历史（id, context_snapshot, performance_metrics, update_reason, timestamp）
- **learning_logs表**：存储学习过程日志（id, agent_id, action, input, output, reward, timestamp）

### 多级日志系统
- **DEBUG级别**：详细执行轨迹、内部状态变化
- **INFO级别**：重要事件、上下文更新、性能指标
- **WARNING级别**：异常情况、性能下降
- **ERROR级别**：严重错误、系统故障

## 容器化部署

### Docker配置

#### Dockerfile
```dockerfile
FROM python:3.11-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件并安装Python包
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY .

# 创建非root用户
RUN useradd --create-home --shell /bin/bash app \
    && chown -R app:app /app
USER app

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["python", "main.py"]
```

#### docker-compose.yml
```yaml
version: '3.8'

services:
  # 主应用服务
  ace-agent:
    build: .
    container_name: ace-intelligent-agent
    ports:
      - "800:8000"
    environment:
      - DATABASE_URL=postgresql://ace_user:ace_password@db:5432/ace_db
      - REDIS_URL=redis://redis:6379/0
      - LOG_LEVEL=INFO
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    depends_on:
      - db
      - redis
    restart: unless-stopped

  # PostgreSQL数据库
  db:
    image: postgres:15-alpine
    container_name: ace-postgres
    environment:
      - POSTGRES_DB=ace_db
      - POSTGRES_USER=ace_user
      - POSTGRES_PASSWORD=ace_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init-db:/docker-entrypoint-initdb.d
    restart: unless-stopped

  # Redis缓存
  redis:
    image: redis:7-alpine
    container_name: ace-redis
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes
    restart: unless-stopped

  # 可视化前端（如果使用独立前端）
  frontend:
    build: ./frontend
    container_name: ace-frontend
    ports:
      - "3000:3000"
    environment:
      - REACT_APP_API_URL=http://localhost:8000
    depends_on:
      - ace-agent
    restart: unless-stopped

  # 监控面板
 grafana:
    image: grafana/grafana-oss
    container_name: ace-grafana
    ports:
      - "3001:3000"
    volumes:
      - grafana_data:/var/lib/grafana
      - ./monitoring/dashboards:/etc/grafana/provisioning/dashboards
      - ./monitoring/datasources:/etc/grafana/provisioning/datasources
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin123
    depends_on:
      - prometheus
    restart: unless-stopped

  # 指标收集
  prometheus:
    image: prom/prometheus
    container_name: ace-prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/etc/prometheus/console_libraries'
      - '--web.console.templates=/etc/prometheus/consoles'
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  grafana_data:
  prometheus_data:
```

## CI/CD流水线

### GitHub Actions流水线
```yaml
name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'
        
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
        pip install pytest pytest-cov
        
    - name: Run tests
      run: |
        pytest tests/ --cov=ace_intelligent_agent --cov-report=xml
        
    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v3

  build-and-push:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
    - name: Checkout
      uses: actions/checkout@v4
      
    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v3
      
    - name: Login to DockerHub
      uses: docker/login-action@v3
      with:
        username: ${{ secrets.DOCKER_USERNAME }}
        password: ${{ secrets.DOCKER_PASSWORD }}
        
    - name: Extract metadata
      id: meta
      uses: docker/metadata-action@v5
      with:
        images: cmx1998/ace-intelligent-agent
        tags: |
          type=ref,event=branch
          type=ref,event=pr
          type=sha,prefix={{branch}}-
          
    - name: Build and push
      uses: docker/build-push-action@v5
      with:
        context: .
        platforms: linux/amd64,linux/arm64
        push: true
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}

  deploy:
    needs: build-and-push
    runs-on: [self-hosted, linux, x64]
    if: github.ref == 'refs/heads/main'
    steps:
    - name: Checkout
      uses: actions/checkout@v4
      
    - name: Pull latest images
      run: |
        docker-compose pull
        
    - name: Deploy with Docker Compose
      run: |
        docker-compose up -d --remove-orphans
```

## 运行模式

### 通用型模式
- 基础的ACE框架实现
- 通用的上下文管理机制
- 基础的Generator/Reflector/Curator模块
- 通用的记忆和检索机制

### 领域专家型模式
- 领域特定的提示模板
- 专业工具和API集成
- 领域知识库
- 专业评估指标

通过配置文件选择运行模式，支持插件化架构进行领域扩展。

## 核心算法流程

1. **Query Processing**：处理输入查询
2. **Context Retrieval**：检索相关上下文信息
3. **Solution Generation**：生成解决方案
4. **Execution & Feedback**：执行并收集反馈
5. **Reflection**：分析执行结果
6. **Context Update**：更新上下文知识库
7. **Refinement**：定期精炼上下文

## 安装教程

### 本地开发环境
1. 克隆项目仓库
2. 安装依赖包：`pip install -r requirements.txt`
3. 配置数据库连接
4. 启动系统：`python main.py`

### Docker容器化部署
1. 克隆项目仓库
2. 确保已安装Docker和Docker Compose
3. 运行 `docker-compose up -d` 启动服务
4. 访问 `http://localhost:8000` 查看应用

### 开发模式
1. 克隆项目仓库
2. 运行 `docker-compose -f docker-compose.dev.yml up --build` 启动开发环境
3. 代码修改后容器会自动重载

## 使用说明

1. 启动Web Dashboard查看实时监控
2. 配置智能体运行模式（通用型/领域专家型）
3. 输入查询任务
4. 监控学习过程和性能指标
5. 查看日志分析和可视化报告

## 性能优势

- **准确性提升**：在AppWorld任务中比GPT-4驱动的agent高10.6%
- **成本降低**：成本和延迟降低86.9%
- **无需标注**：全程不需要人工标注，仅靠反馈循环完成优化
- **可扩展性**：支持大规模batch适应和在线学习

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 技术特点

1. **增量更新机制**：避免上下文崩溃，保持知识积累
2. **模块化设计**：各组件职责清晰，便于扩展和维护
3. **可解释性**：上下文对用户和开发者透明
4. **高效性**：相比完全重写，大幅降低计算成本
5. **混合架构**：支持通用型和领域专家型两种模式