Interface preview · follows system theme · Light · Dark
--- ## Overview **code-agent** extends the OpenCode agent engine with domain support for UBML (Unified Business Modeling Language). - Chat with the Agent in the Web UI, and have it write code and edit configs in your local workspace - Use the UBML knowledge pack so the model understands how low-code components should be used and their constraints - Describe pages with a YAML DSL, compile the model with one click, preview it after validation, and decompile back if needed The OpenCode engine and Web UI source are shipped in this repo (see `packages/opencode/`, `packages/app/`, etc.); this project's own development lives in `packages/extension/`, kept separate from the upstream engine code. --- ## Contributing Issues and Pull Requests are welcome. If you're new to the repo, here's where to start: | What you want to do | Start here | |------------|------------| | Pick up a task, fix a bug | [Gitee Issues](https://gitee.com/ubml/code-agent/issues) (filterable by milestone, e.g. `AppGen v1`, `开发活动工作台 v1`) | | First time here, want a quick UBML taste | [UBML Quickstart Guide](./docs/UBML-QUICKSTART.md) (5-minute walkthrough) | | First time here, want to set up the environment | [Contributor Guide](./docs/product-design/07-contributing.md) | | Understand product direction and roadmap | [Product Design Docs](./docs/product-design/README.md) | | Change UI, workbench, Mission | [`packages/extension/`](./packages/extension/README.md) — the most commonly touched area | | Change DSL compilation/validation logic | `packages/ubml-codegen/` | | Change knowledge base, MCP tools | `packages/knowledge/` | | Larger features spanning multiple packages | Follow the [OpenSpec workflow](./docs/SDD-WORKFLOW.md) first | Product logic should primarily live in the project's own packages: `extension`, `knowledge`, `ubml-codegen`. To change the OpenCode engine itself, follow the maintainers' upstream sync process — see [docs/VENDOR-SYNC.md](./docs/VENDOR-SYNC.md). More detailed conventions are in [AGENTS.md](./AGENTS.md). --- ## Quick Start > **UBML quick trial**: Want to try the UBML toolchain first? See the [UBML Quickstart Guide](./docs/UBML-QUICKSTART.md) (5-minute walkthrough, no LLM configuration needed). Requires [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 # backend :4096, frontend :3000, page preview :3100 ``` When you need to restart the services after code changes: ```bash bun run dev:stop && bun run dev:with-preview ``` On Windows, use `bun run dev:windows` for a one-click start, or double-click `script\start-dev.bat`; stop services with `bun run dev:windows:stop`. After starting: 1. Open http://localhost:3000 in your browser 2. Pick a local working directory 3. Configure your LLM under **Settings → Providers** (credentials stay local, never committed to git) 4. Start a new Session and send a message to confirm the Agent responds --- ## Key Features | | | |---|---| | 🤖 **Agent Chat** | Built on OpenCode, supports multiple LLM providers, streaming Web interaction | | 📦 **UBML Knowledge Pack** | Low-code modeling examples shared by the Agent and the compiler | | 🎨 **Extensible UI** | The Extension customizes the interface via module overrides, no need to fork upstream | | 📐 **Spec-Driven Development** | Larger changes use [OpenSpec](https://github.com/Fission-AI/OpenSpec) with a proposal → design → tasks workflow | --- ## Directory Structure ``` code-agent/ ├── packages/ │ ├── extension/ ★ Main entry point for product customization │ │ ├── src/ UI, Workbench, UBML API │ │ ├── assets/ubml/ Schemas, prompts, examples │ │ └── preview/ Vue low-code preview │ ├── ubml-codegen/ DSL compilation, validation, decompilation │ ├── knowledge/ Knowledge service and MCP │ ├── ide-host/ IDE Host integration │ ├── desktop/ Electron desktop shell │ │ │ ├── opencode/ ┐ │ ├── core/ │ OpenCode engine and Web UI (MIT) │ ├── app/ │ Day-to-day dev happens in extension, don't modify these │ ├── ui/ │ │ ├── sdk/js/ │ │ └── plugin/ ┘ │ ├── script/ Development scripts ├── docs/ Documentation ├── openspec/ OpenSpec change records ├── assets/ Static assets (e.g. README preview images) └── vendor/ Version baseline and import manifests ``` | Code | License | How to contribute | |------|------|----------| | `extension/`, `knowledge/`, `ubml-codegen/`, `script/`, `docs/`, `openspec/` | Apache-2.0 | Submit a PR directly | | `opencode/`, `app/`, `ui/`, and other OpenCode packages | MIT | See [docs/VENDOR-SYNC.md](./docs/VENDOR-SYNC.md) | --- ## Common Commands | Command | What it does | |------|--------| | `bun run dev:with-preview` | **Recommended** — main environment + UBML page preview (:3000 / :4096 / :3100) | | `bun run dev:stop` | Stop the dev services above | | `bun run dev` | Main environment only, without page preview | | `bun run dev:backend` | Only run the OpenCode API (:4096) | | `bun run dev:web` | Only run the extension frontend (:3000) | | `bun run dev:preview` | Only run the UBML page preview (:3100) | | `bun run dev:desktop` | Electron desktop shell | | `bun run dev:ide-host` | IDE Host (OpenVSCode Server) | | `bun run dev:windows` | Windows one-click start | | `bun run typecheck` | Repo-wide type checking | | `bun run smoke` | API smoke test (requires a configured provider) | UBML related: ```bash bun run ubml:build-pack # Build / sync the knowledge 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 ``` More details in [docs/UBML-PAGEGEN.md](./docs/UBML-PAGEGEN.md). --- ## PR Tips 1. Fork this repo and branch off `main` for your feature 2. Run `bun run typecheck` after your changes 3. If you touched session or provider-related logic, verify locally with `bun run dev:with-preview` and `bun run smoke` 4. In your PR description, briefly explain why you made the change, what you changed, and how you verified it Try to make commit messages explain the motivation, not just list files. **When do you need OpenSpec?** Docs fixes and small bugs can go straight to a PR. Larger changes — new APIs, cross-package refactors — should start with a proposal and tasks under `openspec/changes/