# code-agent **Repository Path**: neu-zhangyy/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**: 0 - **Forks**: 59 - **Created**: 2026-09-18 - **Last Updated**: 2026-09-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # code-agent [English](./README.en.md) | 中文 [![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 做页面开发——理解 Farris 组件语义、校验 DSL、预览页面，并在 Agent 工作流里完成生成与迭代。 > 当前版本：**v2.0.0-beta.1** · OpenCode vendor 基线 · UBML 知识包 · 页面生成管线 · 可扩展 Web UI

code-agent 工作台界面预览

界面预览 · 跟随系统主题自动切换 · 日间 · 夜间

--- ## 项目简介 **code-agent** 在 OpenCode 智能体引擎之上，为 UBML（Unified Business Modeling Language）做了领域扩展。 - 在 Web UI 里和 Agent 对话，让它在你的本地工作区里帮忙写代码、改配置 - 借助 UBML 知识包，让模型理解低代码组件该怎么用、有哪些约束 - 用 YAML DSL 描述页面，一键编译模型，校验通过后还能预览，必要时也可以反编译回来 OpenCode 的引擎和 Web UI 基座已随本仓库提供（见 `packages/opencode/`、`packages/app/` 等）。产品能力分布在 Extension、Knowledge、UBML Codegen、MCP、DevPack、IDE Host、Desktop 和 Writeback Sandbox 等自有包中，与 upstream vendor 代码分开；完整所有权边界以 [OpenSpec 项目宪法](./openspec/project.md) 为准。 --- ## 参与贡献 欢迎 Issue 和 Pull Request。如果你还不熟悉仓库，可以按下面的路径找入口： | 你想做什么 | 从这里开始 | |------------|------------| | 领任务、修 Bug | [Gitee Issues](https://gitee.com/ubml/code-agent/issues)（可按里程碑筛选，如 `AppGen v1`、`开发活动工作台 v1`） | | 第一次来，想快速体验 UBML | [UBML 快速上手指南](./docs/guide/ubml-quickstart.md)（5 分钟体验） | | 第一次来，想搭环境 | [协作开发指南](./docs/product-design/07-contributing.md) | | 了解产品方向和路线图 | [产品设计文档](./docs/product-design/README.md) | | 改界面、工作台、Mission | [`packages/extension/`](./packages/extension/README.md) — 日常开发最常动的地方 | | 改 DSL 编译、校验逻辑 | `packages/ubml-codegen/` | | 改知识库、MCP 工具 | `packages/knowledge/` | | 功能较大，或要动多个包 | 建议先走 [OpenSpec 流程](./docs/guide/sdd-workflow.md) | 产品逻辑优先写在 `extension`、`knowledge`、`ubml-codegen` 这些自有包里。若要改 OpenCode 引擎本身，需要走维护者的上游同步流程，见 [docs/guide/vendor-sync.md](./docs/guide/vendor-sync.md)。 更细的约定见 [AGENTS.md](./AGENTS.md)。 --- ## 快速开始 > **UBML 快速体验**：想先快速体验 UBML 工具链？请参考 [UBML 快速上手指南](./docs/guide/ubml-quickstart.md)（5 分钟体验，无需配置 LLM）。 需要 [Bun](https://bun.sh) ≥ 1.3.14。 ```bash git clone https://gitee.com/ubml/code-agent.git cd code-agent bun install bun run dev:with-preview # 后端 :4096，前端 :3000，页面预览 :3100 ``` 改完代码需要重启服务再看效果时： ```bash bun run dev:stop && bun run dev:with-preview ``` Windows 可以用 `bun run dev:windows` 一键启动，或双击 [`script\windows\start-dev.bat`](./script/windows/start-dev.bat)；停止服务用 `bun run dev:windows:stop`。 在 Windows runner 或 Windows PowerShell 环境里，可先运行 `bun run dev:windows:check`。该命令通过真实 `start-dev.bat --check` 检查 Bun、配置和启动路径，不启动服务；它仍需在真实 Windows runner 上执行并保存输出，才能作为 Windows 验收证据。 启动后： 1. 浏览器访问 http://localhost:3000 2. 选一个本地工作目录 3. 在 **Settings → Providers** 里配置 LLM（凭据存在本地，不会进 git） 4. 新建 Session，发一条消息看看 Agent 是否正常回复 --- ## 主要能力 | | | |---|---| | 🤖 **Agent 对话** | 基于 OpenCode，支持多 LLM Provider，Web 端流式交互 | | 📦 **UBML 知识包** | 低代码模型范例，给 Agent 和编译器共用 | | 🎨 **可扩展 UI** | Extension 通过 module override 定制界面，不必 fork 上游 | | 📐 **规约驱动开发** | 较大变更使用 [OpenSpec](https://github.com/Fission-AI/OpenSpec)，proposal → design → tasks 工作流 | --- ## 目录结构 ``` code-agent/ ├── packages/ │ ├── extension/ ★ 产品定制主入口 │ │ ├── src/ UI、Workbench、UBML API │ │ ├── assets/ubml/ Schema、prompt、范例 │ │ └── preview/ Vue 低代码预览 │ ├── ubml-codegen/ DSL 编译、校验、反编译 │ ├── knowledge/ 知识服务与 MCP │ ├── ubml-mcp/ 独立 UBML MCP / CLI │ ├── devpack/ 开发包契约与分发引擎 │ ├── ide-host/ IDE Host 集成 │ ├── desktop/ Electron 桌面壳 │ ├── writeback-sandbox/ 写回隔离运行时 │ ├── opencode/ ┐ │ ├── core/ │ OpenCode 引擎与 Web UI（MIT） │ ├── app/ │ 日常开发改 extension，不要修改这里 │ ├── ui/ │ │ ├── sdk/js/ │ │ ├── plugin/ │ │ └── 其他 vendor 包 ┘ 完整列表见 vendor/MANIFEST.json │ ├── script/ 开发脚本 ├── docs/ 概要设计、系统需求、操作手册 ├── test/ 产品级评测、黄金任务、手验 ├── openspec/ OpenSpec 变更记录 ├── assets/ 预览图、UBML 样例参照 └── vendor/ 版本基线与 import 清单 ``` | 代码 | 许可 | 怎么贡献 | |------|------|----------| | `extension/`、`knowledge/`、`ubml-codegen/`、`script/`、`docs/`、`openspec/` | Apache-2.0 | 直接提 PR | | `opencode/`、`app/`、`ui/` 等 OpenCode 包 | MIT | 见 [docs/guide/vendor-sync.md](./docs/guide/vendor-sync.md) | --- ## 常用命令 | 命令 | 做什么 | |------|--------| | `bun run dev:with-preview` | **推荐** — 主环境 + UBML 页面预览（:3000 / :4096 / :3100） | | `bun run dev:stop` | 停止上述开发服务 | | `bun run dev` | 仅主环境，不含页面预览 | | `bun run dev:backend` | 只跑 OpenCode API（:4096） | | `bun run dev:web` | 只跑 extension 前端（:3000） | | `bun run dev:preview` | 只跑 UBML 页面预览（:3100） | | `bun run dev:desktop` | Electron 桌面壳 | | `bun run dev:ide-host` | IDE Host（OpenVSCode Server） | | `bun run dev:windows` | Windows 一键启动 | | `bun run dev:windows:check` | 通过真实 batch 入口检查 Windows 启动前置条件（不启动服务） | | `bun run typecheck` | 全仓库类型检查 | | `bun run smoke` | API 冒烟（需已配置 Provider） | | `bun run docs:links:check` | 检查活动 Markdown 相对文件、锚点与大小写 | 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/guide/ubml-pagegen.md](./docs/guide/ubml-pagegen.md)。 --- ## 提 PR 的小建议 1. Fork 本仓库，从 `main` 拉一个特性分支 2. 改完跑一遍 `bun run typecheck` 3. 如果动了会话或 Provider 相关逻辑，本地用 `bun run dev:with-preview` 和 `bun run smoke` 确认一下 4. 提 PR 时简单写清楚：为什么改、改了什么、你怎么验证的 Commit message 也尽量说明动机，而不只是列文件名。 **什么时候需要 OpenSpec？** 修文档、小 bug 直接 PR 就行；新 API、跨包重构这类较大改动，建议先在 `openspec/changes//` 里写 proposal 和 tasks。Cursor 里可以用 `/opsx:propose`、`/opsx:apply`；手动开发参考 [docs/guide/sdd-workflow.md](./docs/guide/sdd-workflow.md)。 --- ## 文档 | 文档 | 内容 | |------|------| | [docs/README.md](./docs/README.md) | 文档目录职责 | | [docs/guide/ubml-quickstart.md](./docs/guide/ubml-quickstart.md) | UBML 快速上手指南（5 分钟体验） | | [docs/product-design/](./docs/product-design/README.md) | 概要设计、路线图、Issue 索引 | | [docs/system-requirements/](./docs/system-requirements/README.md) | 系统需求 | | [docs/guide/](./docs/guide/README.md) | 操作手册 | | [docs/product-design/07-contributing.md](./docs/product-design/07-contributing.md) | 新贡献者指南 | | [docs/guide/setup.md](./docs/guide/setup.md) | 环境搭建与故障排查 | | [docs/guide/install-windows.md](./docs/guide/install-windows.md) | Windows 安装器 | | [docs/guide/vendor-sync.md](./docs/guide/vendor-sync.md) | 同步 OpenCode 上游（维护者） | | [docs/guide/sdd-workflow.md](./docs/guide/sdd-workflow.md) | OpenSpec 工作流 | | [test/](./test/README.md) | 产品级评测、黄金任务、手验 | | [docs/guide/ubml-pagegen.md](./docs/guide/ubml-pagegen.md) | 页面生成管线 | | [docs/guide/ubml-knowledge.md](./docs/guide/ubml-knowledge.md) | 知识包构建 | | [packages/extension/README.md](./packages/extension/README.md) | Extension 模块覆盖机制 | | [AGENTS.md](./AGENTS.md) | 协作者与 AI 助手约定 | | [openspec/project.md](./openspec/project.md) | 项目架构约束 | --- ## 相关项目 - [OpenCode](https://github.com/anomalyco/opencode) — 上游智能体引擎与 Web UI - [chenshj/opencode](https://github.com/chenshj/opencode) — 本项目的 OpenCode 维护 fork - [OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规约驱动开发工具链 - [UBML 社区](https://gitee.com/ubml/community) — UBML 背景与规范 --- ## 许可 | 部分 | 许可 | |------|------| | 本仓库扩展与自有代码 | [Apache-2.0](./LICENSE) | | OpenCode vendor 代码 | MIT（见 `vendor/opencode/LICENSE`） | 第三方组件声明见 [NOTICE](./NOTICE)。 --- ## Windows 环境部署常见问题 1. bun install 时报错 tree-sitter-powershell 编译失败 > 原因：缺少C++编译工具链。需要安装 Microsoft Visual Studio Build Tools，安装时勾选「使用C++的桌面开发」组件。 2. 文档提及 config.example.yaml，但仓库内不存在该文件 > 当前仓库没有提供此模板文件，可参考项目文档自行创建配置。 --- --- ## 常见问题 FAQ > 本节为通用使用问题，Windows系统安装相关问题请查阅【Windows环境部署常见问题】章节。 ### Q1：本地服务启动成功，但访问页面空白 A： 1. 查看控制台日志，确认 3000（前端）、4096（API）、3100（预览）端口正常监听，没有报错； 2. 检查端口是否被其他软件占用，若端口占用可修改对应配置更换端口； 3. 刷新页面，或清除浏览器缓存重试。 ### Q2：UBML模型预览功能不生效 A： 1. 需要启动 `dev:with-preview` 或者单独执行 `dev:preview` 命令； 2. 检查UBML模型文件语法，执行 `bun run typecheck` 做类型校验； 3. 查看preview服务控制台输出，确认模型文件被成功加载。 ### Q3：bun install 安装依赖失败（非Windows网络问题） A： 1. 确认本地Bun版本满足项目最低版本要求； 2. 清理bun缓存：`bun pm cache clear`，之后重新执行安装； 3. 检查网络环境，切换镜像源重试。 ### Q4：执行 `bun run smoke` 冒烟测试失败 A： 冒烟测试需要预先配置LLM Provider密钥，未配置密钥会直接报错。 > 提示：普通本地开发调试不需要执行smoke，仅在验证完整API链路时使用。 ### Q5：提交MR前，`bun run typecheck` 报类型错误 A： - 如果**仅修改文档（md文件）**：一般不会触发类型报错，可以忽略； - 如果修改了TS源码：需要根据控制台提示修复全部类型问题，才可以提交MR。 ### Q6：修改代码后，页面没有自动更新 A： 确认使用开发模式 `bun run dev` / `dev:with-preview`； 如果热重载失效，可以重启开发服务。