# 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**: 9
- **Forks**: 4
- **Created**: 2025-12-01
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: lowcode

**Tags**: None

## README

# code-agent

## 介绍

本项目是一个基于语义化标记UBML元模型获得低代码知识，从而利用Qwen3-Coder模型进行智能辅助开发低代码页面的智能体项目。

项目通过解析UBML（Unified Business Modeling Language）元模型的JSON Schema定义，获取低代码组件的语义化知识，结合阿里云DashScope平台的Qwen3-Coder大语言模型，构建了一个能够理解低代码页面结构、自动生成和修改页面配置的智能开发助手。智能体可以理解各种低代码组件的属性、事件和行为，帮助开发者快速构建符合UBML规范的低代码页面。

## 软件架构

本项目采用Monorepo架构，使用pnpm workspace进行包管理，主要包含以下模块：

### 核心模块

- **code-agent**: 核心智能体模块，负责与Qwen3-Coder模型交互，执行代码生成和页面编辑任务
  - `src/agent/`: 智能体核心逻辑
  - `src/providers/`: Qwen3-Coder模型提供者实现
  - `src/tools/`: 工具集（文件读写、编辑、搜索等）
  - `src/session/`: 会话管理和消息处理
  - `src/cli/`: 命令行接口
  - `schemas/`: UBML元模型JSON Schema定义文件

- **schemas/**: 项目根目录下的UBML元模型Schema定义，包含各种低代码组件的规范定义
  - 组件Schema：button、data-grid、form-group等
  - 配置Schema：query-solution-config、filter-bar-config等
  - 编辑器Schema：expression-editor、property-editor等

### 技术栈

- **运行时**: Bun
- **包管理**: pnpm (workspace)
- **AI模型**: Qwen3-Coder (通过阿里云DashScope API)
- **语言**: TypeScript
- **构建工具**: Turbo

### 架构特点

- 模块化设计，各功能模块职责清晰
- 基于工具调用（Tool Calling）的智能体架构
- 支持会话管理和上下文保持
- 提供丰富的文件操作和代码编辑工具

## 安装编译和运行依赖包

### 前置要求

- Node.js >= 18
- pnpm >= 9
- Bun (推荐使用最新版本)
- ripgrep (rg) - 用于文件搜索功能

#### macOS 环境工具安装

在 macOS 环境下，以下工具需要手动安装：

**1. 安装 Bun**

使用官方安装脚本（推荐）：

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

或者使用 Homebrew：

```bash
brew install bun
```

安装完成后，重启终端或运行 `source ~/.zshrc`（如果使用 zsh）使命令生效。

验证安装：

```bash
bun --version
```

**2. 安装 ripgrep**

使用 Homebrew 安装（推荐）：

```bash
brew install ripgrep
```

或者使用 MacPorts：

```bash
sudo port install ripgrep
```

验证安装：

```bash
rg --version
```

**3. 安装 pnpm**

如果尚未安装 pnpm，可以使用以下方式：

通过 npm 安装：

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

或使用 Homebrew：

```bash
brew install pnpm
```

验证安装：

```bash
pnpm --version
```

> **注意**：虽然项目代码会在首次运行时自动下载 ripgrep（如果系统中未找到），但为了更好的性能和稳定性，建议提前手动安装。其他工具（如 `realpath`）在 macOS 系统中已默认包含，无需额外安装。

### 安装步骤

1. **克隆项目**

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

2. **安装依赖**

在项目根目录执行：

```bash
pnpm install
```

这将自动安装所有工作区（workspace）中的依赖包。

3. **配置API密钥**

获取阿里云DashScope API密钥，设置环境变量：

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

或者创建 `.env` 文件：

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

API密钥获取地址：[阿里云DashScope控制台](https://dashscope.aliyuncs.com/)

4. **编译项目**

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

### 验证安装

运行以下命令验证安装是否成功：

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

## 运行code-agent示例程序

### 示例程序说明

项目提供了示例程序 `demos/demo01.sh`，演示如何使用code-agent智能体根据UBML Schema定义来编辑低代码页面。

### 运行步骤

1. **进入code-agent目录**

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

2. **确保已设置API密钥**

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

3. **运行示例程序**

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

或者直接使用code-agent命令：

```bash
./bin/code-agent run --message="忽略上次上下文信息, 参考schemas目录下的button.schema.json, 在pages/demo-page.json文件中的基本信息下面添加一个蓝色按钮"
```

### 示例程序功能

示例程序会：
1. 读取 `schemas/button.schema.json` 了解按钮组件的UBML规范
2. 读取 `pages/demo-page.json` 查看当前页面配置
3. 使用Qwen3-Coder模型理解需求并生成符合UBML规范的按钮配置
4. 将生成的按钮添加到页面的指定位置

### 自定义运行

你也可以使用自己的消息来运行智能体：

```bash
./bin/code-agent run --message="你的需求描述"
```

例如：

```bash
./bin/code-agent run --message="在demo-page.json中添加一个数据表格组件，包含姓名和年龄两列"
```

### 其他命令选项

- `--continue` 或 `-c`: 继续上一次会话
- `--session <session-id>`: 指定会话ID
- `--command <command>`: 执行特定命令

更多帮助信息：

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