superDS - AI 驱动的设计开发一体化平台

语言: English | 中文

一个集成 HTML 可视化编辑器、多模型 AI 助手、项目管理、产品设计能力的 AI 驱动设计-编程一体化平台。基于 OpenCode Serve 进行 LLM 编排。

架构概览

┌──────────────┐    ┌──────────────┐    ┌──────────────────┐    ┌───────────────┐
│   浏览器      │───▶│   前端        │───▶│     后端         │───▶│ OpenCode Serve│
│  (React SPA) │    │  (Nginx/Vite)│    │   (FastAPI)      │    │  (Docker)     │
└──────────────┘    └──────────────┘    └────────┬─────────┘    └───────┬───────┘
                                                 │                      │
                                                 ▼                      ▼
                                         ┌──────────────┐      ┌───────────────┐
                                         │  PMS 系统     │      │  LLM 提供商   │
                                         │  (项目管理)   │      │  (自建端点)   │
                                         └──────────────┘      └───────────────┘

核心定位：后端作为中间层，管理用户认证、会话路由、工作区隔离，将请求透明转发到 OpenCode Serve（Docker 容器化部署）。所有容器通过共享 Docker 网络 superds-net 使用容器名互相通信。

技术栈

层级	技术
前端	React 19 + TypeScript + Vite 5 + Tailwind CSS 3 + Zustand 5
后端	FastAPI + Uvicorn + httpx（异步）+ SQLite（aiosqlite）
AI 引擎	OpenCode Serve v1.15.13（Docker 容器化部署）
LLM 提供商	环境自建模型端点（Qwen3.8 INT4、DeepSeek 系列，经 opencode.json 配置）
部署	Docker Compose + Nginx + Gitea Actions CI/CD
实时通信	SSE（Server-Sent Events）+ WebSocket

项目结构

superDS/
├── backend/                    # 后端 API 服务（FastAPI）
│   ├── src/
│   │   ├── api/                # API 路由层（10 个模块）
│   │   │   ├── main.py         # FastAPI 应用入口 & 路由注册
│   │   │   ├── session_routes.py    # 会话管理（核心）
│   │   │   ├── auth_routes.py       # 认证（注册/登录）
│   │   │   ├── workspace_routes.py  # 工作区（克隆/删除/文件浏览）
│   │   │   ├── event_routes.py      # SSE 事件流转发
│   │   │   ├── websocket_routes.py  # WebSocket
│   │   │   ├── config_routes.py     # 配置文件 CRUD（管理员）
│   │   │   ├── model_routes.py      # 模型列表查询
│   │   │   ├── pms_routes.py        # PMS 项目初始化
│   │   │   ├── file_routes.py       # 文件读取
│   │   │   └── conversion_routes.py # 文件转换
│   │   ├── services/          # 业务逻辑层
│   │   ├── models/            # 数据模型（LLM 工厂、OpenCode 客户端）
│   │   ├── session/           # 会话管理
│   │   ├── schemas/           # 请求/响应 Schema
│   │   ├── configs/           # 配置管理 & 数据库
│   │   └── middleware/        # 认证 & 异常中间件
│   ├── deploy/                # 部署配置（Docker + K8s）
│   │   ├── docker/            # Docker Compose、Dockerfile、deploy.sh
│   │   └── k8s/               # Kubernetes 清单
│   ├── skills/                # OpenCode 技能（SKILL.md，LLM 按需加载）
│   ├── knowledge/             # 项目知识库（参考文档）
│   ├── opencode_workspace/    # 工作区初始化模板（生产环境只读）
│   ├── updates/               # 更新日志 & 变更记录
│   ├── AGENTS.md              # AI 编码助手规则
│   ├── MEMORY.md              # 项目知识沉淀 & 踩坑经验
│   └── requirements.txt
├── frontend/                   # 主前端应用（React + TS）
│   ├── src/
│   │   ├── components/        # UI 组件（ai/、layout/、ui/）
│   │   ├── pages/             # 页面组件
│   │   │   ├── auth/          # 落地页
│   │   │   ├── projects/      # 项目列表
│   │   │   ├── design/        # 设计工作台（核心：iframe 编辑器）
│   │   │   ├── product/       # 产品设计（思维导图/流程/线框图）
│   │   │   ├── admins/        # 后台管理（Agent/Skill/Command 编辑器）
│   │   │   ├── settings/      # 用户设置
│   │   │   └── icons/         # 图标库
│   │   ├── services/api/      # API 服务层（Axios）
│   │   ├── stores/            # Zustand 状态管理（模块化）
│   │   ├── i18n/              # 国际化（中/英）
│   │   ├── hooks/             # 自定义 Hooks
│   │   └── router.tsx         # 路由配置（懒加载 + AuthGuard）
│   ├── public/assets/iframe/  # iframe 注入脚本（原生 JS）
│   ├── doc/                   # 前端文档
│   ├── e2e/                   # Playwright E2E 测试
│   ├── nginx.conf             # 生产环境 Nginx 配置
│   ├── Dockerfile             # 多阶段构建
│   ├── docker-compose.yml     # 前端容器编排
│   └── AGENTS.md              # 前端 AI 编码规则
├── deploy/                     # 统一部署
│   ├── deploy.sh              # 一键部署脚本（前端 + 后端）
│   └── .env.example           # 统一配置源
├── doc/                        # 项目级文档
│   ├── ai-chat-research/      # AI 聊天实现调研
│   ├── docker-network-setting/# Docker 网络配置
│   └── front-fix/             # 前端 Bug 修复记录
├── .gitea/workflows/           # CI/CD（Gitea Actions）
└── README.md

注意：backend/frontend/ 是历史遗留的 AI 生成测试前端，不是生产前端。生产前端是根目录下的 frontend/ 目录。

快速开始

前置条件

• Python 3.10+
• Node.js 18+（npm 8+）
• Docker & Docker Compose（用于 OpenCode Serve 部署）

方式一：统一 Docker 部署（推荐）

# 1. 配置环境变量（唯一配置源）
cd deploy
cp .env.example .env
# 编辑 .env：填入 OPENSANDBOX_API_KEY、PMS_BASE_URL 等

# 2. 一键部署（前端 + 后端 + opencode-serve）
./deploy.sh --build

# 3. 验证
./deploy.sh  # 重新运行检查健康状态

服务访问地址：

• 前端：http://localhost:8800
• 后端：http://localhost:8000
• OpenCode Serve：http://localhost:4096

方式二：本地开发

后端：

cd backend
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # 配置 OPENSANDBOX_API_KEY 等

# 启动 OpenCode Serve（Docker）
cd deploy/docker && docker compose up -d opencode-serve

# 启动后端
uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload

前端：

cd frontend
npm install
npm run dev      # 启动于 http://localhost:4173

部署命令

cd deploy

./deploy.sh                    # 默认部署（使用已有镜像）
./deploy.sh --build            # 部署并重新构建镜像
./deploy.sh --backend-only     # 仅部署后端
./deploy.sh --frontend-only    # 仅部署前端
./deploy.sh --stop             # 停止并移除容器（保留网络）
./deploy.sh --stop --backend-only  # 仅停止后端
./deploy.sh --no-start         # 仅生成配置，不启动服务

Docker 网络

所有容器通过共享外部网络 superds-net 通信：

• frontend → backend：http://backend:8000
• backend → opencode-serve：http://opencode-serve:4096

网络由 deploy.sh 自动创建（幂等）。详见 doc/docker-network-setting/spec.md。

API 概览

模块	前缀	说明
认证	/api/v1/auth	注册、登录
会话	/api/v1/sessions	创建会话、流式聊天、消息历史、权限审批
模型	/api/v1/models	查询可用模型列表
工作区	/api/v1/workspace	仓库克隆/删除、文件浏览、代码保存、SSH 管理
配置	/api/v1/workspace/config	配置文件 CRUD（仅管理员）
PMS	/api/v1/pms	项目管理系统初始化
事件	/api/events	SSE 事件流转发
健康检查	/health	健康检查

详见 backend/README.md。

支持的模型

LLM 提供商为环境自建模型端点，由 opencode.json 配置 （模板：backend/deploy/docker/opencode.json.template）。当前集合：

提供商	模型	说明
qwen3.8-int4	qwen3.8-int4-AWQ	自建 vLLM 端点
deepseek-v4-q4	deepseek-v4-q4	自建端点
deepseek-hny	deepseek-v4-flash	DeepSeek API（Anthropic 兼容）

模型列表经 GET /api/v1/models 动态下发。

核心功能

前端

• 设计工作台：React 外壳 + iframe 画布 + postMessage 通信 + Zustand 状态管理
• AI 助手：多模型支持、SSE 流式响应、Markdown 渲染（Shiki 语法高亮）、Slash 命令
• 产品设计：思维导图（@antv/x6）、页面流程、线框图、AI 辅助需求分析
• 后台管理：Agent/Skill/Command 编辑器、文件管理
• 国际化：中文（默认）/ 英文

后端

• 会话管理：本地会话 ↔ OpenCode 会话映射
• 工作区隔离：Docker 卷挂载 + OpenCode 权限规则（双层防护）
• 权限控制：templates/AGENTS.md 只读挂载，OPENCODE_DISABLE_PROJECT_CONFIG=true
• PMS 集成：项目/仓库 CRUD、中文转拼音仓库名、SSH 优先克隆策略

CI/CD

生产环境部署使用 Gitea Actions（.gitea/workflows/deploy-production.yml）：

• 触发条件：push 到 master 分支
• 策略：内网通过 SSH 主动推送到公网生产服务器（单向出站）
• 安全性：git archive 仅导出 git 跟踪文件（机密由 .gitignore 边界保证）
• 流程：检出 → SSH 配置 → 流式推送代码 → 生产部署脚本（原子切换 + 健康检查 + 失败回滚）

文档导航

路径	内容
doc/	项目级文档 & 架构规范
doc/architecture.md	整体系统架构
doc/deployment.md	部署指南
doc/ai-coding-guide.md	AI Coding 开发指南与规范
backend/README.md	后端详细文档
backend/AGENTS.md	后端 AI 编码规则
backend/MEMORY.md	后端知识沉淀 & 踩坑经验
frontend/README.md	前端详细文档
frontend/AGENTS.md	前端 AI 编码规则
doc/ai-chat-research/	AI 聊天实现调研

配置说明

所有配置通过唯一配置源 deploy/.env 管理。部署脚本会自动同步到 backend/.env 和 frontend/.env。关键配置项：

配置项	说明	是否必填
OPENSANDBOX_API_KEY	OpenSandbox 控制面 REST API 认证键（随机串）	是
PMS_BASE_URL	PMS 系统地址	是
OPENCODE_SERVE_PASSWORD	OpenCode Serve 访问密码	是
JWT_SECRET_KEY	JWT 签名密钥（生产环境务必修改）	是
WORKSPACE_ROOT	工作区根目录（容器内）	默认：/app/opencode_workspace
NETWORK_NAME	共享 Docker 网络名	默认：superds-net

完整配置参考 deploy/.env.example。

许可证

本项目仅供内部开发使用。