Code Cube

Code Cube 是一个基于对话式 AI 的应用生成与静态发布平台，支持通过自然语言完成需求分析、代码生成与修改、实时预览、源码下载和主动部署。项目还提供基于角色权限的后台管理，支持用户和应用管理，以及部署记录查询。

🚀 项目亮点

• 🧭 意图识别与工作流策略：系统会结合应用类型、当前生成状态和用户输入，判断是首次生成、继续修改、需求澄清、普通聊天还是超出范围的请求。工作流采用策略模式，通过统一接口选择 H5 或 Vue 的处理流程。
• 🛠️ 模型文件读写与项目校验：通过文件工具，模型可以查看目录，并读取、创建、修改或删除项目文件；后端会统一检查文件路径。Vue 修改完成后执行 TypeScript 编译和 Vite 打包，检查通过后才更新预览。
• 🧠 长短期记忆与对话摘要：MySQL 保存完整聊天记录和长期摘要，Redis 分别保存最近的聊天内容和代码操作记录。对话达到一定长度后，将已有摘要和新增消息合并为新的摘要，避免每次都把完整聊天记录提交给模型，缩短上下文并减少 Token 消耗。
• 🔄 生成状态与失败恢复：通过 SSE 返回生成开始、处理进度、文件变化、预览更新、完成和错误事件，并同步更新应用与消息状态。发生异常或用户取消时记录对应结果；Vue 在修改前创建源码快照，编译、打包或预览失败时恢复原有代码。
• 🔒 应用级并发控制：按照 appKey 为每个应用维护一个 Semaphore(1)，生成、部署、删除和源码下载前先尝试加锁。同一应用发生冲突时提示忙碌，不同应用仍可并行处理，操作结束后自动释放锁。
• 🚀 预览与部署版本分离：应用源码、最新预览和正式部署版本分别保存。预览更新前复制到临时目录并检查入口文件，切换失败时恢复旧预览；后续修改不会直接影响已部署版本，只有用户主动部署时才更新正式版本。

🤝 Vibe Coding

项目采用 Vibe Coding 方式开发，使用 Codex 参与方案分析、代码实现、测试和文档整理。通过 AGENTS.md 约定项目结构、编码规范、支持范围和验证要求；需求与方案由本人确认，重要改动会经过代码审查、编译、测试和实际运行验证。

🖼️ 效果展示

✨ 应用创建

📚 应用管理

🧩 生成示例

H5 应用生成示例	Vue 应用生成示例

🏗️ 核心架构

flowchart LR
    U["用户需求"] --> M["需求分析与元数据确认"]
    M --> A["创建 H5 / Vue 应用"]
    A --> C["AI 对话工作区"]
    C --> W{"按应用类型选择 Workflow"}
    W --> H["H5 生成或修改"]
    W --> V["Vue 模板化开发"]
    H --> Q["代码文件与入口校验"]
    V --> B["依赖安装与构建校验"]
    Q --> P["实时预览"]
    B --> P
    H --> S["源码下载"]
    V --> S
    P --> D["用户主动部署"]
    C <--> R["MySQL 历史与摘要<br/>Redis 对话与代码记忆"]

Loading

目录	用途
project/generated/{appKey}	可继续编辑的应用源码
project/preview/{appKey}	当前校验通过的实时预览
project/deployed/{appKey}	用户主动发布的稳定静态版本

更详细的状态流转见 应用生成状态图 和 应用部署状态图。

🧰 技术栈

领域	主要技术
后端	Java 17、Spring Boot、Spring Security、MyBatis Plus
AI	LangChain4j、OpenAI 兼容模型服务、Agent、Workflow、Tool Calling
数据	MySQL、Redis
前端	Vue 3、TypeScript、Ant Design Vue、Vue Router、Pinia、Vite
构建与部署	Maven、npm、Orval、Playwright、Nginx

📂 项目结构

code-cube-api/   Spring Boot 后端
code-cube-ui/    Vue 3 前端
templates/       AI 生成应用使用的项目模板
docs/            状态图等稳定文档
sql/             数据库初始化脚本
config/          Nginx 静态预览与部署参考配置

⚡ 快速开始

📋 环境要求

• JDK 17 与 Maven
• Node.js 与 npm（建议使用较新的 LTS 版本）
• MySQL、Redis 服务
• OpenAI 兼容模型服务
• 完整体验预览、部署和封面截图时，还需要 Nginx 以及 Playwright 支持的浏览器

1. 🗄️ 初始化数据库

启动 MySQL 和 Redis，并在本地开发数据库中执行 sql/create_table.sql。

该脚本会创建 code_cube 数据库并重建项目表，请勿在生产数据库中执行。

2. ⚙️ 配置后端

从仓库根目录复制本地配置示例：

cp code-cube-api/src/main/resources/application-local.example.yml \
  code-cube-api/src/main/resources/application-local.yml

打开 application-local.yml，填写以下内容：

• MySQL、Redis 的连接信息
• JWT 密钥
• OpenAI 兼容模型的 API Key、接口地址和模型名称
• 项目数据目录与仓库中 templates/vue-app 的绝对路径
• 预览和部署地址前缀

3. 🖼️ 配置预览、部署与截图

如果只想启动前后端，可以先跳过本节；完整体验应用预览、主动部署和封面截图时需要完成以下配置。

Nginx 需要分别托管两个目录：

Nginx 用途	对应目录	对应后端配置
实时预览	<root-path>/project/preview	app.access-url.preview-prefix
正式部署	<root-path>/project/deployed	app.access-url.deployed-prefix

将 config/nginx/nginx.local.conf 放入 Nginx 已加载的 conf.d 或 servers 目录，并按本地环境修改其中的监听端口、域名、两个 root 路径，以及 CSP 中允许嵌入预览页的前端地址。该文件是 server 配置片段，不能直接作为完整的 Nginx 主配置使用。

本地开发时，还需要以管理员权限修改 hosts 文件，让配置中的域名指向本机。不同系统的文件位置如下：

系统	hosts 文件
Windows	C:\Windows\System32\drivers\etc\hosts
macOS	/etc/hosts
Linux	/etc/hosts

在文件中增加：

127.0.0.1 preview.codecube.com apps.codecube.com

修改后执行 nginx -t 检查配置，再通过本机的 Nginx 服务管理方式重新加载。后端的预览、部署地址前缀必须与 Nginx 的协议、域名和端口保持一致。

应用封面由 Playwright 截取预览页面生成。浏览器的安装与选择请参考 Playwright Java 浏览器安装文档。

4. ☕ 启动后端

cd code-cube-api
mvn spring-boot:run

5. 🌐 启动前端

cd code-cube-ui
cp .env.example .env
npm ci
npm run dev

启动后可访问：

• 前端页面：http://localhost:5173
• 健康检查：http://localhost:8080/api/health/check
• API 文档：http://localhost:8080/api/doc.html
• OpenAPI：http://localhost:8080/api/v3/api-docs

后端接口发生变化后，可在后端运行期间进入 code-cube-ui/，执行 npm run gen:api 重新生成前端接口代码。

🧭 支持的应用类型

应用类型	说明
H5_APP	使用 HTML、CSS 和原生 JavaScript 的静态应用
VUE_APP	使用本地 Mock 数据的纯前端 Vue 原型

后续计划：支持全栈应用生成。