Skip to content

mini_program.md

Latest commit

 

History

History
354 lines (259 loc) · 13.7 KB

mini_program.md

File metadata and controls

354 lines (259 loc) · 13.7 KB

Mini Program Development

AI-Powered Development Environment

An AI-assisted mini program development IDE that demonstrates AEnvironment's capabilities for tool integration, deployment, and scaling. This IDE enables developers to create web applications through natural language conversations with an AI agent.

Features

  • AI Agent: Multi-turn conversation powered by OpenAI API with automatic retry logic for rate limits
  • Virtual File System (VFS): Persistent file system for managing mini program files
  • MCP Tools: Model Context Protocol tools for file operations and code execution
  • Live Preview: Real-time preview of generated applications in an iframe
  • Responsive Design: Automatically ensures generated content fits the preview window
  • Version Tracking: Displays version numbers on generated pages for update verification

Architecture

The project is organized into three main directories:

mini-program/
├── agent/              # Agent server (FastAPI + OpenAI integration)
│   └── agent_server.py
├── environment/        # AEnvironment tools and configuration
│   ├── src/            # MCP tools (read_file, write_file, etc.)
│   ├── config.json     # Environment configuration
│   ├── Dockerfile      # Container build configuration
│   └── requirements.txt
└── frontend/           # Web UI (HTML/CSS/JavaScript)
    ├── index.html
    ├── app.js
    └── style.css

Component Overview

  • Frontend: HTML/CSS/JS interface with split view (chat | live preview)
  • Agent Server: FastAPI backend that integrates OpenAI API with MCP tools
  • MCP Server: AEnvironment MCP server providing tools via Model Context Protocol
  • Tools:
    • read_file: Read files from virtual file system
    • write_file: Write files to virtual file system
    • list_files: List all files in the VFS
    • execute_python_code: Execute Python code snippets for validation
    • validate_html: Validate HTML structure and syntax
    • check_responsive_design: Analyze CSS for responsive design compliance

Prerequisites

  1. Python 3.8+ installed
  2. AEnvironment SDK installed (pip install aenvironment)
  3. OpenAI API Key (required for AI chat functionality)
  4. Node.js and npm (for MCP Inspector, installed automatically by aenv run)

Installation

  1. Install Python dependencies:
pip install -r environment/requirements.txt
  1. Set environment variables:
export OPENAI_API_KEY='your-api-key-here'
export OPENAI_MODEL='gpt-4'  # Optional, defaults to gpt-4
export OPENAI_BASE_URL='https://api.openai.com/v1'  # Optional, for custom endpoints
export AENV_ENV_NAME='mini-program@1.0.0'  # Optional, environment name

Quick Start

Step 1: Start the MCP Server (Environment Side)

Open a terminal and navigate to the environment directory:

cd environment
aenv run

This will:

  • Start the AEnvironment MCP server
  • Load tools from environment/src/
  • Start the MCP Inspector (available at http://localhost:6274)

Keep this terminal running.

Step 2: Start the Agent Server (Agent Side)

Open a new terminal and navigate to the agent directory:

cd agent
python agent_server.py

This will:

  • Start the FastAPI server on port 8080
  • Connect to the MCP server for tool access
  • Enable the web interface

Keep this terminal running.

Step 3: Open the Web Interface

Open your browser and navigate to:

http://localhost:8080

Step 4: Start Building

  1. Type your request in the chat input (e.g., "Create a simple counter mini program")
  2. The AI agent will:
    • Analyze your request
    • Use tools to read existing files (if any)
    • Create or modify files as needed
    • Generate complete HTML/CSS/JavaScript applications
  3. The Live Preview will automatically update to show your generated application
  4. Click the "🔄 Refresh" button to manually refresh the preview

Usage Examples

Example 1: Create a Counter Application

User: "Create a simple counter mini program"

Agent Actions:

  1. Uses list_files to check existing files
  2. Creates index.html with HTML structure, CSS styling, and JavaScript logic
  3. Uses validate_html to check for errors
  4. Uses check_responsive_design to ensure responsive layout
  5. Preview automatically updates

Result: A fully functional counter application appears in the Live Preview.

Example 2: Modify Existing Application

User: "Add a reset button to the counter"

Agent Actions:

  1. Uses read_file to read the existing index.html
  2. Modifies the file to add a reset button
  3. Increments the version number displayed on the page
  4. Preview updates automatically

Result: The counter now includes a reset button.

Example 3: Create a Game

User: "Create a Snake game"

Agent Actions:

  1. Plans the game structure (HTML canvas, game logic, controls)
  2. Creates index.html with complete game implementation
  3. Ensures responsive design (scales to fit preview window)
  4. Adds version number tracking
  5. Preview shows the playable game

Result: A fully playable Snake game in the Live Preview.

Workflow

  1. User Input: Type a natural language request in the chat
  2. Agent Planning: AI agent analyzes the request and plans the implementation
  3. Tool Execution: Agent uses MCP tools to:
    • Check existing files (list_files)
    • Read files if needed (read_file)
    • Create/modify files (write_file)
    • Validate code (validate_html, check_responsive_design)
    • Execute Python code for calculations (execute_python_code)
  4. Automatic Preview: System automatically renders the generated HTML in Live Preview
  5. Iteration: User can provide feedback and continue refining the application

Features in Detail

Rate Limit Handling

The agent server includes automatic retry logic with exponential backoff for OpenAI API rate limit errors (429):

  • Max Retries: 3 attempts
  • Initial Delay: 1 second
  • Backoff Factor: 2x (delays: 1s, 2s, 4s)
  • Max Delay: 60 seconds

Virtual File System

  • Persistent Storage: Files are stored in /tmp/code/ on disk
  • In-Memory Cache: Fast access to frequently used files
  • Automatic Loading: Existing files are loaded on server startup
  • Clear Function: Use /api/clear endpoint to reset the VFS

Responsive Design Enforcement

The agent is instructed to:

  • Use viewport-relative units (vw, vh, %, clamp)
  • Ensure content fits without scrolling
  • Scale canvas elements dynamically
  • Use flexible layouts (flexbox, grid)

Version Tracking

Every generated index.html includes a visible version number that increments with each modification, helping users verify that updates are working correctly.

API Endpoints

Agent Server Endpoints

  • GET /: Serve the main HTML interface
  • POST /api/chat: Send chat messages and receive AI responses
  • GET /api/files: List all files in VFS
  • GET /api/files/{file_path}: Get file content
  • POST /api/files/{file_path}: Save file content
  • POST /api/clear: Clear all files from VFS
  • GET /health: Health check endpoint
  • WebSocket /ws: Real-time communication (for future use)

Configuration

Environment Variables

  • OPENAI_API_KEY (required): Your OpenAI API key
  • OPENAI_MODEL (optional): Model to use (default: "gpt-4")
  • OPENAI_BASE_URL (optional): Custom API endpoint URL
  • AENV_ENV_NAME (optional): Environment name (default: "mini-program@1.0.0")

Project Configuration

  • environment/config.json: AEnvironment project metadata
  • environment/Dockerfile: Container build configuration
  • environment/requirements.txt: Python dependencies

Troubleshooting

MCP Server Not Starting

  • Ensure you're in the environment directory when running aenv run
  • Check that environment/src/ contains the tool files
  • Verify AEnvironment SDK is installed: pip list | grep aenv

Agent Server Connection Issues

  • Ensure the MCP server is running first
  • Check that AENV_ENV_NAME matches the environment name
  • Verify OpenAI API key is set correctly

Static Files Not Loading

  • Ensure you're running agent_server.py from the agent/ directory
  • Check that frontend/ directory exists at the project root
  • Verify FastAPI is serving static files (check server logs)

Rate Limit Errors

  • The system automatically retries with exponential backoff
  • If errors persist, check your OpenAI API quota
  • Consider using a different model or reducing request frequency

Testing

The project includes basic functionality tests. Run tests using pytest or your preferred testing framework.

Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│                    Browser (User)                        │
│              http://localhost:8080                      │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/WebSocket
┌────────────────────▼────────────────────────────────────┐
│              Agent Server (FastAPI)                      │
│              Port: 8080                                  │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  OpenAI API Client                               │   │
│  │  - Chat Completions                              │   │
│  │  - Tool Calling                                  │   │
│  │  - Retry Logic (429 handling)                    │   │
│  └──────────────┬───────────────────────────────────┘   │
│                 │ HTTP API                              │
│  ┌──────────────▼───────────────────────────────────┐   │
│  │  MCP Client                                      │   │
│  │  - Tool Discovery                                │   │
│  │  - Tool Execution                                │   │
│  └──────────────┬───────────────────────────────────┘   │
└─────────────────┼───────────────────────────────────────┘
                  │ MCP Protocol (HTTP)
┌─────────────────▼───────────────────────────────────────┐
│         AEnvironment MCP Server                          │
│         Port: 8081                                       │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  MCP Tools (from environment/src/)               │   │
│  │  - read_file                                     │   │
│  │  - write_file                                    │   │
│  │  - list_files                                    │   │
│  │  - execute_python_code                           │   │
│  │  - validate_html                                 │   │
│  │  - check_responsive_design                       │   │
│  └──────────────┬───────────────────────────────────┘   │
│                 │                                        │
│  ┌──────────────▼───────────────────────────────────┐   │
│  │  Virtual File System (VFS)                       │   │
│  │  Storage: /tmp/code/                             │   │
│  │  - Persistent on disk                            │   │
│  │  - In-memory cache                               │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────┘

Development

Project Structure

  • agent/: Agent server code (FastAPI application)
  • environment/src/: MCP tools implementation
  • frontend/: Web UI files
  • test_*.py: Test scripts for verification

Adding New Tools

  1. Create a new tool function in environment/src/mini_program_tools.py
  2. Use the @register_tool decorator
  3. Restart the MCP server (aenv run)
  4. The tool will be automatically available to the agent

Modifying the Frontend

  • Edit files in frontend/ directory
  • Changes take effect immediately (no rebuild needed)
  • Refresh the browser to see updates

License

Copyright 2025. Licensed under the Apache License, Version 2.0.

Support

For issues or questions:

  1. Check the troubleshooting section above
  2. Review server logs for error messages
  3. Verify all prerequisites are installed
  4. Ensure environment variables are set correctly