# code-agent

**Repository Path**: ubml/code-agent

## Basic Information

- **Project Name**: code-agent
- **Description**: UBML / Code Agent 是基于UBML实现智能辅助低代码开发的智能体
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 35
- **Forks**: 8
- **Created**: 2025-12-01
- **Last Updated**: 2025-12-09

## Categories & Tags

**Categories**: lowcode

**Tags**: None

## README

# code-agent

## Introduction

This project is an intelligent agent system that leverages semantically marked UBML metamodels to acquire low-code knowledge, and utilizes the Qwen3-Coder model for intelligent assistance in developing low-code pages.

By parsing JSON Schema definitions of UBML (Unified Business Modeling Language) metamodels, the project extracts semantic knowledge of low-code components. Combined with Alibaba Cloud DashScope's Qwen3-Coder large language model, it builds an intelligent development assistant capable of understanding low-code page structures and automatically generating and modifying page configurations. The agent can understand various low-code component properties, events, and behaviors, helping developers quickly build low-code pages that comply with UBML specifications.

## Software Architecture

This project adopts a Monorepo architecture using pnpm workspace for package management, primarily consisting of the following modules:

### Core Modules

- **code-agent**: Core agent module responsible for interacting with the Qwen3-Coder model and executing code generation and page editing tasks
  - `src/agent/`: Core agent logic
  - `src/providers/`: Qwen3-Coder model provider implementation
  - `src/tools/`: Toolset (file read/write, editing, searching, etc.)
  - `src/session/`: Session management and message processing
  - `src/cli/`: Command-line interface
  - `schemas/`: UBML metamodel JSON Schema definition files

- **schemas/**: UBML metamodel Schema definitions in the project root directory, containing specification definitions for various low-code components
  - Component Schemas: button, data-grid, form-group, etc.
  - Configuration Schemas: query-solution-config, filter-bar-config, etc.
  - Editor Schemas: expression-editor, property-editor, etc.

### Technology Stack

- **Runtime**: Bun
- **Package Manager**: pnpm (workspace)
- **AI Model**: Qwen3-Coder (via Alibaba Cloud DashScope API)
- **Language**: TypeScript
- **Build Tool**: Turbo

### Architecture Features

- Modular design with clear responsibilities for each functional module
- Agent architecture based on Tool Calling
- Supports session management and context preservation
- Provides rich file operations and code editing tools

## Installation, Compilation, and Running Dependencies

### Prerequisites

- Node.js >= 18
- pnpm >= 9
- Bun (latest version recommended)
- ripgrep (rg) - for file search functionality

#### macOS Environment Tool Installation

The following tools need to be manually installed on macOS:

**1. Install Bun**

Using the official installation script (recommended):

```bash
curl -fsSL https://bun.sh/install | bash
```

Or using Homebrew:

```bash
brew install bun
```

After installation, restart the terminal or run `source ~/.zshrc` (if using zsh) to make the command available.

Verify installation:

```bash
bun --version
```

**2. Install ripgrep**

Using Homebrew (recommended):

```bash
brew install ripgrep
```

Or using MacPorts:

```bash
sudo port install ripgrep
```

Verify installation:

```bash
rg --version
```

**3. Install pnpm**

If pnpm is not yet installed, you can use the following methods:

Install via npm:

```bash
npm install -g pnpm
```

Or using Homebrew:

```bash
brew install pnpm
```

Verify installation:

```bash
pnpm --version
```

> **Note**: Although the project code will automatically download ripgrep on first run (if not found in the system), it is recommended to install it manually in advance for better performance and stability. Other tools (such as `realpath`) are already included by default in macOS systems and do not require additional installation.

### Installation Steps

1. **Clone the repository**

```bash
git clone <repository-url>
cd ai-coding
```

2. **Install dependencies**

Execute in the project root directory:

```bash
pnpm install
```

This will automatically install all dependency packages in the workspace.

3. **Configure API Key**

Obtain your Alibaba Cloud DashScope API key and set the environment variable:

```bash
export DASHSCOPE_API_KEY="your-api-key-here"
```

Or create a `.env` file:

```env
DASHSCOPE_API_KEY=your-api-key-here
```

API key acquisition: [Alibaba Cloud DashScope Console](https://dashscope.aliyuncs.com/)

4. **Build the project**

```bash
cd packages/code-agent
pnpm build
```

### Verify Installation

Run the following command to verify that the installation was successful:

```bash
cd packages/code-agent
bun run ./src/index.ts --help
```

## Running code-agent Example Program

### Example Program Description

The project provides an example program `demos/demo01.sh` that demonstrates how to use the code-agent to edit low-code pages based on UBML Schema definitions.

### Running Steps

1. **Navigate to the code-agent directory**

```bash
cd packages/code-agent
```

2. **Ensure API key is set**

```bash
export DASHSCOPE_API_KEY="your-api-key-here"
```

3. **Run the example program**

```bash
chmod +x demos/demo01.sh
./demos/demo01.sh
```

Or directly use the code-agent command:

```bash
./bin/code-agent run --message="Ignore previous context, refer to button.schema.json in the schemas directory, and add a blue button below the basic information in the pages/demo-page.json file"
```

### Example Program Functionality

The example program will:
1. Read `schemas/button.schema.json` to understand the UBML specification for button components
2. Read `pages/demo-page.json` to view the current page configuration
3. Use the Qwen3-Coder model to understand the requirements and generate button configuration that complies with UBML specifications
4. Add the generated button to the specified location in the page

### Custom Execution

You can also run the agent with your own message:

```bash
./bin/code-agent run --message="Your requirement description"
```

For example:

```bash
./bin/code-agent run --message="Add a data grid component to demo-page.json with name and age columns"
```

### Other Command Options

- `--continue` or `-c`: Continue the last session
- `--session <session-id>`: Specify session ID
- `--command <command>`: Execute a specific command

For more help information:

```bash
./bin/code-agent run --help
```