# 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**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 39
- **Forks**: 15
- **Created**: 2025-12-01
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: lowcode

**Tags**: None

## README

# code-agent

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
[![Bun](https://img.shields.io/badge/Bun-≥1.3.14-black?logo=bun&logoColor=white)](https://bun.sh)

基于 [OpenCode](https://github.com/anomalyco/opencode) 的开源智能体平台，为 **UBML 低代码页面** 提供 AI 辅助开发能力——从组件语义理解、DSL 编译校验，到页面预览与 Agent 驱动的生成工作流。

> 当前版本：**v2.0.0-beta.1**（OpenCode vendor 基线 · UBML 知识包 · 页面生成管线 · 可扩展 Web UI）

---

## 简介

**code-agent** 在 OpenCode 智能体引擎之上，叠加面向 UBML（Unified Business Modeling Language）的领域扩展。你可以用它：

- 通过 Web UI 与 AI Agent 对话，在本地工作区中完成开发任务
- 利用 UBML 知识包，让 LLM 理解 Farris 低代码组件的语义与约束
- 用 YAML DSL 描述页面，编译为 Farris JSON、校验、预览，并支持反编译

项目采用 **fork → vendor import** 方式跟踪 [OpenCode](https://github.com/anomalyco/opencode) 上游：引擎与 UI 基线可持续同步，领域定制集中在 `packages/extension/`，边界清晰、便于贡献。

---

## 特性

| | |
|---|---|
| 🤖 **Agent 对话** | OpenCode Agent loop，支持多 LLM Provider，Web 端流式会话 |
| 📦 **UBML 知识包** | Farris 组件 JSON Schema、模板与 few-shot 范例，供 Agent 与编译器使用 |
| 🔧 **页面生成管线** | YAML DSL ↔ Farris JSON 编译、校验、反编译；Vue 实时预览 |
| 🎨 **可扩展 UI** | Extension 层通过 module override 定制界面，无需 fork 上游即可改产品体验 |
| 📐 **规约驱动开发** | [OpenSpec](https://github.com/Fission-AI/OpenSpec) 管理变更，proposal → design → tasks 可追溯 |

---

## 架构

code-agent 与 OpenCode 上游通过三层仓库协作：

```
anomalyco/opencode     OpenCode 官方仓库（upstream, dev）
        │ merge
        ▼
chenshj/opencode       维护 fork（合并上游、承载必要补丁）
        │ vendor import
        ▼
code-agent             本仓库：领域扩展 + 开源贡献入口
```

**请求链路（开发模式）：**

```
浏览器 :3000          extension 覆盖的 Web UI
  → POST /api/session/{id}/prompt
  → SSE /global/event
      ↓
OpenCode :4096        Agent loop → LLM Provider
      ↓
流式回复 → UI 渲染
```

---

## 快速开始

### 环境要求

| 依赖 | 说明 |
|------|------|
| [Bun](https://bun.sh) ≥ 1.3.14 | 运行时与包管理 |
| jq、rsync | vendor 导入脚本 |
| OpenCode fork | 见下方「Vendor 准备」 |

### 1. 克隆本仓库

```bash
git clone https://gitee.com/Sagi_Chen/code-agent.git
cd code-agent
chmod +x script/*.sh script/vendor/*.sh
```

### 2. Vendor 准备

首次运行需从 OpenCode fork 导入引擎与 UI 包。克隆 fork 并 checkout `dev` 分支：

```bash
git clone https://github.com/chenshj/opencode.git /path/to/opencode-fork
cd /path/to/opencode-fork && git checkout dev
```

将 fork 本地路径写入 `vendor/MANIFEST.json` 的 `fork.localPath`（或通过环境变量覆盖，见 [docs/SETUP.md](./docs/SETUP.md)）。

### 3. 导入、安装、启动

```bash
bash script/vendor/import-opencode.sh   # 导入 vendor 包
bun install
bun run dev                             # 后端 :4096 + 前端 :3000
```

### 4. 验证

1. 打开 http://localhost:3000
2. 选择本地工作目录
3. **Settings → Providers** 配置 LLM（API Key 保存在本地用户目录，不会进入仓库）
4. 新建 Session 并发送消息

可选：`bun run smoke` 进行 API 冒烟测试。

更完整的环境说明与故障排查见 **[docs/SETUP.md](./docs/SETUP.md)**。

---

## 开发

### 常用命令

| 命令 | 说明 |
|------|------|
| `bun run dev` | 主开发环境（Agent 后端 + Web UI） |
| `bun run dev:backend` | 仅 OpenCode API（:4096） |
| `bun run dev:web` | 仅 extension 前端（:3000） |
| `bun run dev:preview` | UBML 页面预览（:3100） |
| `bun run dev:with-preview` | 主环境 + 预览 dev server |
| `bun run dev:desktop` | Electron 桌面壳 |
| `bun run dev:ide-host` | IDE Host（OpenVSCode Server） |
| `bun run typecheck` | 全仓库类型检查 |
| `bun run smoke` | API 冒烟（需已配置 Provider） |

### UBML 工具链

```bash
bun run ubml:build-pack    # 构建 / 同步知识包
bun run ubml:compile -- path/to/page.yaml
bun run ubml:verify -- path/to/page.yaml
bun run ubml:decompile -- path/to/page.json
bun run ubml:install-agent
```

详见 [docs/UBML-PAGEGEN.md](./docs/UBML-PAGEGEN.md)。

### 同步 OpenCode 上游

| 命令 | 适用场景 |
|------|----------|
| `bun run vendor:sync` | fork 已有更新，导入到本仓库 |
| `bun run vendor:sync-upstream` | 从官方 upstream 合并到 fork 再导入 |
| `IMPORT_REF=<sha> bun run vendor:import` | 导入 fork 指定 commit |

建议顺序：**先更新 fork，再 import**。请勿在 vendor 目录直接提交产品逻辑——定制应放在 `packages/extension/`。

---

## 项目结构

```
code-agent/
├── packages/
│   ├── extension/          ★ 主要贡献入口（Apache-2.0）
│   │   ├── src/              UI 覆盖、UBML API、Workbench
│   │   ├── assets/ubml/      Schema、prompt、exemplar
│   │   └── preview/          Vue 低代码预览
│   ├── ubml-codegen/         DSL 编译 / 反编译 / 校验
│   ├── knowledge/            知识服务
│   ├── ide-host/             IDE Host 集成
│   ├── desktop/              Electron 桌面应用
│   │
│   ├── opencode/             ┐
│   ├── core/                 │ 来自 OpenCode fork（MIT）
│   ├── app/                  │ import 时覆盖，请勿直接修改
│   ├── ui/                   │
│   ├── sdk/js/               │
│   └── plugin/               ┘
│
├── script/                   开发与 vendor 同步脚本
├── docs/                     文档
├── openspec/                 OpenSpec 规约与变更记录
├── vendor/                   导入清单与版本基线
└── patches/                  上游依赖 patch
```

| 代码 | 许可 | 贡献方式 |
|------|------|----------|
| `packages/extension/`、`script/`、`docs/`、`openspec/` | Apache-2.0 | 欢迎 PR |
| `packages/opencode/`、`app/`、`ui/` 等 vendor 包 | MIT | 请先在 [OpenCode fork](https://github.com/chenshj/opencode) 修改，再 sync 导入 |

Extension 模块覆盖机制见 [packages/extension/README.md](./packages/extension/README.md)。

---

## 参与贡献

欢迎 Issue 与 Pull Request。开始前建议阅读 [AGENTS.md](./AGENTS.md) 了解架构边界。

### 从哪里入手

| 你想做什么 | 建议路径 |
|------------|----------|
| 新功能、UI 调整、UBML 逻辑 | `packages/extension/` |
| 文档改进 | `docs/` |
| 需修改 OpenCode 核心行为 | [chenshj/opencode](https://github.com/chenshj/opencode) fork → sync → import |
| 较大功能或架构变更 | 先开 OpenSpec 变更（见下） |

### 开发流程

1. Fork 本仓库，创建特性分支
2. 实现改动，确保 `bun run typecheck` 通过
3. 若涉及会话/Provider，本地验证 `bun run dev` 与 `bun run smoke`
4. 提交 PR，说明动机与验证方式

### 变更规约（OpenSpec）

较大变更遵循 **先规约、后实现** 的流程，产物位于 `openspec/changes/<name>/`：

```
探索 → 提案 → 审阅 → 实现 → 验证 → 归档
```

使用 Cursor 时可借助 `/opsx:propose`、`/opsx:apply` 等命令；手动开发请参考 [docs/SDD-WORKFLOW.md](./docs/SDD-WORKFLOW.md)。变更命名建议 kebab-case、动词开头（如 `add-ubml-layout-preview`）。

### 提交注意

- Commit message 说明**为什么**做这次改动
- Vendor 更新单独提交：`vendor(opencode): import fork @ <sha>`
- **切勿提交** API Key、`.env` 或个人凭据文件

---

## 文档

| 文档 | 说明 |
|------|------|
| [docs/SETUP.md](./docs/SETUP.md) | 环境准备与 vendor 导入 |
| [docs/SDD-WORKFLOW.md](./docs/SDD-WORKFLOW.md) | OpenSpec 开发流程 |
| [docs/UBML-PAGEGEN.md](./docs/UBML-PAGEGEN.md) | 页面生成管线 |
| [docs/UBML-KNOWLEDGE.md](./docs/UBML-KNOWLEDGE.md) | 知识包构建 |
| [docs/LAYOUT-UX.md](./docs/LAYOUT-UX.md) | 布局与 UX |
| [openspec/project.md](./openspec/project.md) | 项目架构约束 |
| [AGENTS.md](./AGENTS.md) | 贡献者与 AI 助手规约 |

---

## 相关项目

- [OpenCode](https://github.com/anomalyco/opencode) — 上游智能体引擎与 Web UI
- [chenshj/opencode](https://github.com/chenshj/opencode) — 本项目的 OpenCode 维护 fork
- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规约驱动开发工具链

---

## 许可

| 部分 | 许可 |
|------|------|
| 本仓库扩展与自有代码 | [Apache-2.0](./LICENSE) |
| OpenCode vendor 代码 | MIT（见 `vendor/opencode/LICENSE`） |

第三方组件声明见 [NOTICE](./NOTICE)。