# SubjStudio **Repository Path**: codekpy/subj-studio ## Basic Information - **Project Name**: SubjStudio - **Description**: 人人都是学科创作者 SubjStudio 是一个基于 AI 辅助的学科交互式内容共创平台，让高中生、教师与开发者无需深厚代码基础，也能轻松创作、分享与协作开发物理、化学、数学等学科的可视化模拟演示。 - **Primary Language**: TypeScript - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-16 - **Last Updated**: 2026-05-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SubjStudio > **人人都是学科创作者** > *Empowering Everyone to Create Interactive Learning* SubjStudio 是一个基于 AI 辅助的学科交互式内容共创平台,让高中生、教师与开发者无需深厚代码基础,也能轻松创作、分享与协作开发物理、化学、数学等学科的可视化模拟演示。 --- ## 📌 项目定位 让抽象知识「看得见、摸得着、玩得转」,让每一个有创意的学习者,都能成为知识的「创作者」而非「消费者」。 **核心闭环**: 用户聊天 → AI 生成单文件 HTML → 预览/编辑 → 一键推送至 SubjEngine 仓库 --- ## 🌟 核心功能 ### 🤖 AI 智能创作 - **自然语言生成模拟**: 输入学科需求,AI 自动生成可视化演示代码 - **Function Call 工具链**: 文件写入、模板读取、问题确认、TODO 管理等 - **内容审查机制**: 自动过滤无关请求,节省 Token 消耗 - **流式输出**: 支持实时 AI 响应,前端 WebSocket 转发 ### 🧩 用户前台 - **首页瀑布流**: 公开项目展示,综合排序算法(点赞×0.3 + 浏览×0.2 + 时间×0.5) - **项目管理**: 个人项目列表,支持新建/编辑/学科标签筛选 - **Studio 创作空间**: 左右布局(预览 iframe + AI 聊天面板) - **收藏系统**: 收藏喜欢的项目,个人收藏页管理 - **用户主页**: 公开项目展示 + AI 编辑热力图 ### 🛡️ 管理后台 - **多级权限体系**: 三级角色(user/partial_admin/super_admin) + adminList 动态权限 - **项目管理**: 编辑简介/AI 重审/Git 推送/取消发布 - **用户管理**: 修改信息/冻结/权限分配(权限感知) - **实时通知**: WebSocket 推送完成/审核结果通知 ### 🔗 Git 集成 - **自动推送**: 项目文件复制到学科目录,追加 list.json - **内容审核队列**: AI 异步审核合规性 - **版本管理**: Git pull → 复制 → commit → push 自动化流程 --- ## ⚙️ 技术架构 | 层级 | 技术选型 | 说明 | |------|----------|------| | **前端** | Vue 3 + TypeScript + Vite | Composition API, 单文件组件 | | **前端样式** | Tailwind CSS 3 | 液态玻璃顶栏 + 蓝色左侧菜单 | | **前端通信** | Socket.IO 客户端 | 命名空间 + 事件驱动 + 重连逻辑 | | **后端** | Node.js 18+ + Express + TypeScript | ES Module, strict 模式 | | **后端通信** | Socket.IO + RESTful API | 聊天流式用 Socket.IO, CRUD 用 HTTP | | **AI 接入** | DeepSeek / OpenAI 兼容协议 | 中间件统一调用,支持 function_call | | **数据库** | MySQL 8 + mysql2 | 参数化查询,防 SQL 注入 | | **文件存储** | 本地文件系统 + Base64 | 演示文件存 `/files/{hash}.html` | | **Git 集成** | child_process 执行 git 命令 | 直接操作 `/Git` 目录下的仓库 | | **包管理** | npm workspaces | monorepo 前后端分离 | --- ## 📦 项目结构 ``` subj-studio/ ├── frontend/ # Vue 3 前端 (Vite) │ ├── src/ │ │ ├── api/ # HTTP 请求封装 │ │ ├── components/ # 公共组件 (GlassNav, ProjectCard, ChatPanel...) │ │ ├── composables/ # 组合式函数 (useTheme) │ │ ├── router/ # 路由配置 │ │ ├── socket/ # Socket.IO 客户端封装 │ │ ├── store/ # 状态管理 │ │ ├── utils/ # 工具函数 (permission, recorder, socket-events) │ │ └── views/ # 页面组件 │ │ ├── Admin/ # 管理后台 (Dashboard, UserManage, ProjectManage...) │ │ ├── Home.vue # 首页 │ │ ├── Studio.vue # AI 创作空间 │ │ └── ... │ └── package.json │ ├── backend/ # Node.js 后端 (Express + TS) │ ├── src/ │ │ ├── config/ # 配置 (database, system-config) │ │ ├── controllers/ # REST API 控制器 │ │ ├── function-calls/ # AI Function Call 实现 │ │ ├── middleware/ # 中间件 (auth, ai-proxy, permission, content-audit) │ │ ├── routes/ # 路由定义 │ │ ├── services/ # 服务层 (email, file, git, recommendation) │ │ ├── socket/ # Socket.IO 命名空间 │ │ └── index.ts # 服务入口 │ └── package.json │ ├── shared/ # 前后端共享类型定义 │ └── types.ts # Project/User/ChatMessage 等接口 │ ├── static/ # 静态资源库 (供 AI 生成页面引用) ├── .env.example # 环境变量模板 └── package.json # 根脚本 + workspaces 配置 ``` --- ## 🚀 快速开始 ### 环境要求 - **Node.js**: 18+ - **MySQL**: 8.0+ - **npm**: 9+ ### 安装步骤 #### 1. 克隆仓库 ```bash git clone cd subj-studio ``` #### 2. 配置 npm 国内镜像 (可选) ```bash npm config set registry https://registry.npmmirror.com ``` #### 3. 安装依赖 ```bash npm install ``` #### 4. 配置环境变量 复制 `.env.example` 为 `.env`: ```bash cp .env.example .env ``` 编辑 `.env` 文件,填入你的配置: ```env # 服务配置 PORT=3001 NODE_ENV=development # 数据库配置 DB_HOST=localhost DB_PORT=3306 DB_USER=root DB_PASSWORD=your_password DB_NAME=subj_studio # JWT 配置 JWT_SECRET=your_jwt_secret_key_change_in_production JWT_EXPIRES_IN=7d # 前端地址 FRONTEND_URL=http://localhost:5173 # SMTP 配置 (邮箱验证码) SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USER=your-email@example.com SMTP_PASS=your-email-password SMTP_FROM=noreply@subjstudio.com # AI 配置 AI_API_KEY=sk-your-api-key AI_BASE_URL=https://api.deepseek.com/v1 AI_MODEL=deepseek-chat # Git 配置 GIT_REPO_DIR=../Git ``` #### 5. 初始化数据库 ```bash # 登录 MySQL 创建数据库 mysql -u root -p CREATE DATABASE subj_studio DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; # 执行初始化脚本 mysql -u root -p subj_studio < backend/src/db/init.sql ``` #### 6. 启动开发服务器 ```bash # 同时启动前端和后端 npm run dev # 或分别启动 npm run dev:frontend # 前端 http://localhost:5173 npm run dev:backend # 后端 http://localhost:3001 ``` #### 7. 构建生产版本 ```bash # 构建全部 npm run build # 或分别构建 npm run build:frontend npm run build:backend # 启动生产服务器 npm start ``` --- ## 📖 使用说明 ### 用户注册与登录 1. **注册**: 访问 `/login` → 切换到注册页 → 输入用户名/邮箱 → 获取邮箱验证码 → 设置密码 2. **登录**: 支持用户名或邮箱登录 + 密码验证 3. **邮箱验证**: 注册时需完成邮箱验证,验证码通过 SMTP 发送 ### 创作项目 1. 登录后进入 **项目** 页面 2. 点击 **新建** 按钮进入 Studio 创作空间 3. 在右侧聊天面板输入需求,如 "我想演示光的折射" 4. AI 自动生成代码,左侧 iframe 实时预览 5. 可发送图片附件、压缩聊天记录、替换部分代码 ### 管理项目 1. 进入 **项目** 页面查看个人项目列表 2. 按时间降序排列,支持学科标签筛选 3. 点击项目进入详情页,可点赞/下载/新标签页打开 4. 公开项目会显示在首页瀑布流 ### 管理后台 > 需要 `partial_admin` 或 `super_admin` 权限 1. 登录后台: `/admin/dashboard` 2. **用户管理**: 查看/编辑用户信息、分配权限、冻结用户 3. **项目管理**: 编辑简介、AI 重审、Git 推送、取消发布 4. **AI 配置**: 配置 AI 模型参数 5. **SMTP 配置**: 配置邮件服务 --- ## 🔐 权限系统 ### 角色等级 | 角色 | 说明 | 管理后台访问 | |------|------|-------------| | `user` | 普通用户 | 无 | | `partial_admin` | 部分管理员 | 有,受 adminList 限制 | | `super_admin` | 超级管理员 | 有,全部权限 | ### adminList 权限格式 ```json [ { "name": "group", "spread": true }, { "name": "set_user", "spread": false } ] ``` | 权限项 | 含义 | 搭配要求 | |--------|------|---------| | `group` | 可见同 group 用户/项目 | 只读权限 | | `all_group` | 可见全部用户/项目 | 只读权限 | | `set_user` | 可编辑用户信息 | 需搭配 group/all_group | | `set_group` | 可编辑项目 | 需搭配 group/all_group | **spread 规则**: `true` 表示该权限可被部分管理员赋予其他用户,`false` 表示仅自己可用。 ### 权限特性 - 只读权限下邮箱自动脱敏: `code***@foxmail.com` - 部分管理员只能操作可见范围内的数据 - 超级管理员忽略 adminList,拥有全部权限 --- ## 🗄️ 数据库设计 ### 核心数据表 - **users**: 用户表 (含 rank/admin_list/group_name 等权限字段) - **projects**: 项目表 (含 file_path/git_path/pushed_at/统计数据) - **chat_sessions**: 聊天会话表 (含 todo_list JSON) - **chat_records**: 聊天记录表 (支持断连续传) - **collections**: 收藏表 完整 SQL 结构见 `backend/src/db/init.sql` --- ## 🔌 Socket.IO 事件 ### `/chat` 命名空间 (用户聊天) | 事件 | 方向 | 说明 | |------|------|------| | `join_session` | C→S | 加入聊天会话 | | `send_message` | C→S | 发送消息 | | `ai_response_chunk` | S→C | AI 流式输出 | | `ask_problem` | S→C | 交互问题表单 | | `ask_problem_answer` | C→S | 用户回答问题 | ### `/admin` 命名空间 (管理后台) | 事件 | 方向 | 说明 | |------|------|------| | `admin_join` | C→S | 管理员加入 | | `push_completed` | S→C | Git 推送完成 | | `review_completed` | S→C | AI 审核完成 | --- ## 🧪 开发指南 ### 运行类型检查 ```bash npm run typecheck ``` ### 添加新 Function Call 1. 在 `backend/src/function-calls/` 创建新文件 2. 实现函数逻辑,注意权限校验和路径白名单 3. 在 `ai-proxy.ts` 中间件中注册 ### 添加新 API 1. 在 `backend/src/controllers/` 创建控制器 2. 在 `backend/src/routes/` 定义路由 3. 添加权限中间件 (如需要) ### 前端组件开发 - 使用 Composition API (`