sparklumina

🎨 SparkLumina

SparkLens：聚焦你的灵感，释疑万物万象

聚焦你的想法，讲清一切

✨ 功能概览

已实现

🎯 白板核心

无限画布 — 创作空间不受限
丰富绘图工具 — 画笔、图形、文字、箭头、便签等
多媒体 — 图片、视频与文件上传
撤销/重做 — 完整历史管理
缩放与平移 — 轻松浏览大画布

🤝 实时协作

多人会话 — 支持多名用户同时协作
实时光标 — 查看他人操作位置
即时同步 — 变更实时可见
在线状态 — 了解房间内成员情况

🎬 录制与回放

会话录制 — 录制整段白板会话
事件回放 — 回放已录内容
导出 — 保存录制供后续使用

🎨 界面

现代设计 — 简洁直观
响应式 — 适配桌面、平板与手机

📚 AI 讲题（房间内双 AI 面板）

AI 智能绘图 - 侧边栏输入需求，生成 Excalidraw 图形并应用到画布；支持 ExcalidrawElementSkeleton 格式（text、rectangle、ellipse、diamond、arrow 及 label、script 等扩展字段），动态解析列表并渲染到画布，应用后自动同步到多人服务器（同房间其他用户实时看到）。
AI 讲题 - 并列侧边栏：输入题目 → 流式生成讲解步骤 → TTS 播放、上/下一步、向老师提问（交互问答）
后端代理 - Node 后端将讲题请求代理到 ai_agent_service（Python FastAPI）服务

规划中

深色/浅色主题 — 按环境切换配色
无障碍 — 面向 WCAG 的改进

更长期的计划见下文 路线图 一节。

🚀 快速开始

环境要求

Node.js 18+（建议 LTS）
npm 或 yarn
AI 讲题 / AI 素材：使用 ./start.sh 时会自动启动内置 backend/src/ai_agent_service（端口 8652）；也可单独设置 AI_AGENT_SERVICE_URL 指向外部服务。

安装

cd SparkLumina

安装依赖

npm run install:all

将同时安装前端与后端依赖。

开发

同时启动前端与后端开发模式：

npm run dev

将启动：

🎨 前端：http://localhost:8051
📡 后端：http://localhost:8056

使用 AI 讲题 / AI 素材：需要 AI Agent 服务（默认端口 8652）。可用根目录 ./start.sh（会先 npm run build 再预览，见 QUICKSTART.md）；日常开发用 npm run dev 时请自行启动 backend/src/ai_agent_service（uvicorn）。后端通过 aiAgentProxy 将请求转发至该服务（AI_AGENT_SERVICE_URL）。

或分别启动：

# 终端 1 — 后端
npm run dev:backend

# 终端 2 — 前端
npm run dev:frontend

生产构建

构建前端

npm run build

启动后端

npm start

统一发布入口 release.sh

仓库根目录提供 release.sh，用参数指定发布内容（Docker 镜像 / macOS 安装包 / Windows 安装包 / 全部）：

./release.sh <target> [选项]

target	说明
docker	构建并推送双后端 Docker 镜像（frontend_server、backend_server、ai_agent_service），需 `.env` 中 ACR 配置
mac	构建 macOS DMG（仅可在 macOS 上执行）
windows	构建 Windows NSIS 安装包（仅可在 Windows 上执行）
all	先执行 docker，再按当前系统打 Electron（macOS 打 DMG，Windows 打 exe；Linux 仅 docker）

docker 子选项：--platform amd64|arm64|both（默认 amd64）、--no-push（仅构建不推送）。示例：

./release.sh docker --no-push
./release.sh mac
./release.sh desktop     # macOS 上同时打 DMG + Windows
./release.sh android     # Android APK
./release.sh all --platform amd64
./release.sh mac --debug # DMG 内嵌 vConsole 调试

全局选项 --debug：桌面/Android 包注入 vConsole；docker/all 时镜像 tag 可带 -debug 后缀（见 release.sh 注释）。

macOS DMG 打包

在 macOS 上可将前端打包为独立 DMG 安装包，内置固定后端地址，无需用户配置。

方式一（推荐）： ./release.sh mac
方式二： 在仓库根目录执行 npm run build:dmg

产物输出在 app/release/ 下（如 SparkLumina-1.0.0-macos-arm64.dmg）。DMG 内应用会固定使用以下服务地址：

服务	地址	用途
backend	`http://localhost:8056`（示例；生产环境自行配置）	房间、录制、Socket.IO、账号 API、AI 代理等
ai_agent_service	`http://localhost:8652`（示例；生产环境自行配置）	讲题流式生成、TTS、config、音色等

修改上述地址时，在 .env 中设置 VITE_API_BASE 与 VITE_AI_AGENT_SERVICE_BASE（或复制 .env.example 为 .env 后编辑），然后执行 ./release.sh mac 或 npm run build:dmg。

目录说明：Electron 主进程在 app/electron/（与 frontend 同级目录下的 app 内），由根目录的 electron-builder 打包，frontend 下无需也不保留 electron 软链。

Windows 安装包

需在 Windows 上（或 WINE）构建。

方式一（推荐）： ./release.sh windows
方式二： npm run build:win

产物在 app/release/ 下，如 SparkLumina-1.0.0-windows.exe（NSIS 安装程序，可选安装路径、中英文安装界面）。

Android APK

需安装 Android SDK。执行 ./release.sh android，产物在 app/release/SparkLumina-{version}-android.apk（debug 版）。

完整发布流程与 GitHub Release 管理 见 docs/RELEASE_SCHEME.md。

📁 项目结构

SparkLumina/
├── app/
│   ├── android/              # Capacitor Android 工程
│   └── electron/             # Electron 主进程（DMG 桌面壳）
├── frontend/                  # React + TypeScript + Excalidraw
│   ├── src/
│   │   ├── components/
│   │   │   ├── Home.tsx           # 首页（创建/加入房间）
│   │   │   ├── RoomPage.tsx       # 房间页（含 QuickJoin / WhiteboardRoom）
│   │   │   ├── WhiteboardRoom.tsx # 白板主页面（画布 + 右侧 AI 入口）
│   │   │   ├── AIPanel.tsx        # AI 讲题面板入口
│   │   │   ├── SmartDrawPanel.tsx # AI 素材面板入口
│   │   │   ├── XchatPanel.tsx     # 协作解题（画板 Agent）入口
│   │   │   ├── AISidebar.tsx      # AI 素材：生成/应用/导出
│   │   │   ├── AIProblemSolving/  # AI 讲题（流式讲解、TTS、交互）
│   │   │   └── ExAgent/           # 画板 Agent 组件与逻辑
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   └── lib/
│   ├── package.json
│   └── vite.config.ts
│
├── backend/                   # Node.js + Socket.IO + AI 代理
│   ├── src/
│   │   ├── server.ts          # HTTP + Socket.IO 入口
│   │   ├── roomManager.ts     # 房间/用户/白板状态
│   │   ├── recordingManager.ts
│   │   ├── aiAgentProxy.ts    # 代理到 ai_agent_service（讲题、智能绘图、TTS）
│   │   ├── agentStreamRoute.ts # ex_agent 流式路由 /api/agent/stream
│   │   └── ai_agent_service/   # Python FastAPI（LLM、TTS、各 Agent）
│   ├── package.json
│   └── tsconfig.json
│
├── docs/                      # 文档入口（详见 docs/README.md）
├── archive/                   # 开发/设计文档归档（快速启动、Docker、迁移等）
├── package.json               # 根工作区与 Electron 构建配置
├── start.sh                   # 一键启动（前端 + 后端 + AI 服务）
└── README.md                  # 本文件

🛠️ 技术栈

前端

React 18 — UI 框架
TypeScript — 类型安全
Excalidraw — 手绘风格白板引擎
Vite — 构建工具
Socket.IO Client — 实时通信
Lucide React — 图标库

后端

Node.js — 运行时
Express — Web 框架
Socket.IO — WebSocket 服务
TypeScript — 类型安全

🎮 使用说明

创建房间

在首页输入昵称
点击 「创建新房间」
将房间 ID 分享给他人

加入房间

输入昵称
切换到 「加入房间」 标签
输入房间 ID
点击 「加入房间」

白板工具

工具	说明
✏️ 画笔	自由手绘
▢ 矩形	绘制矩形
⭕ 圆形	绘制圆形
➡️ 箭头	绘制箭头
A	文本
📌 便签	便利贴
📷 图片	上传图片
🖐️ 选择	选择与移动对象
🗑️ 删除	删除对象

快捷键

快捷键	作用
`空格 + 拖拽`	平移画布
`Ctrl/Cmd + Z`	撤销
`Ctrl/Cmd + Shift + Z`	重做
`Ctrl/Cmd + +/-`	放大/缩小
`Ctrl/Cmd + 0`	重置缩放
`V`	选择工具
`D`	画笔工具
`R`	矩形工具
`O`	圆形工具
`A`	箭头工具
`T`	文本工具

🔧 配置

环境变量

推荐在仓库根目录复制 .env.example 为 .env（backend/src/server.ts 会优先加载根目录 .env，再加载 backend/.env）。示例：

PORT=8056
NODE_ENV=development
CORS_ORIGIN=http://localhost:8051

前端配置

开发时 Vite 将 /socket.io 与 /api 代理到后端（见 frontend/vite.config.ts 中 BACKEND_HOST/BACKEND_PORT，默认 localhost:8056）。修改端口或代理目标可编辑该文件；根目录 .env 中的 VITE_* 由 Vite 读取（envDir 指向仓库根目录）。

📡 API 参考

REST 接口

健康检查

GET /api/health
响应: { status: 'ok', rooms: number, timestamp: string }

房间信息

GET /api/rooms/:roomId
响应: { roomId: string, users: User[], createdAt: number }

Socket.IO 事件

客户端 → 服务端

事件	载荷	说明
`join-room`	`{ roomId, userName }`	加入房间
`leave-room`	`{ roomId }`	离开房间
`canvas-change`	`{ roomId, changes }`	发送画布更新
`get-room-state`	`roomId`	请求房间状态
`start-recording`	`{ roomId }`	开始录制
`stop-recording`	`{ roomId }`	停止录制
`chat-message`	`{ roomId, message }`	发送聊天消息

服务端 → 客户端

事件	载荷	说明
`users-update`	`User[]`	用户列表更新
`room-state`	`snapshot`	初始房间状态
`remote-changes`	`changes`	他人画布变更
`user-joined`	`{ user, message }`	用户加入通知
`user-left`	`{ userId, userName, message }`	用户离开通知
`recording-started`	`{ timestamp }`	录制已开始
`recording-stopped`	`{ timestamp, recordingId }`	录制已停止

🚧 路线图

第一阶段：核心能力 ✅

基于 Excalidraw 的白板与协作
实时协作
房间管理（含本地 JSON 持久化目录 .sparklumina-data）
用户在线状态
录制基础设施

第二阶段：增强功能 🚧

PDF 导入与标注
导出 PNG/SVG/PDF（白板菜单已有导出能力，此处指产品级统一导出）
带音频的视频录制
聊天能力
文件上传（图片、文档等）

第三阶段：进阶功能 📋

用户认证（注册/登录/会话 Cookie，见 /api/auth/*）
房间元数据等企业级数据库（当前为文件存储 + 可选 Stripe 等）
房间历史
模版库
更多 AI 能力
移动应用（Android：Capacitor；iOS 未在仓库中作为主要交付形态）

第四阶段：企业级 🔮

🤝 参与贡献

欢迎贡献代码，建议流程：

Fork 本仓库
创建功能分支（git checkout -b feature/你的功能）
提交更改（git commit -m 'feat: 说明'）
推送到远程分支（git push origin feature/你的功能）
发起 Pull Request

开发约定

使用 TypeScript 并保持严格类型
遵循现有代码风格
复杂逻辑补充注释
充分自测
变更同步更新文档

🐛 故障排查

端口被占用

若 8051 或 8056 已被占用：

# 释放 8051（前端）
lsof -ti:8051 | xargs kill -9

# 释放 8056（后端）
lsof -ti:8056 | xargs kill -9

依赖异常

# 清理后重装
rm -rf node_modules frontend/node_modules backend/node_modules
npm run install:all

Socket.IO 连接问题

确认后端在 8056 端口运行
检查 backend/src/server.ts 中的 CORS 配置
查看浏览器控制台错误信息

📚 更多文档

文档	说明
SECURITY.md	漏洞报告与密钥管理说明
ARCHITECTURE.md	架构说明
FEATURES.md	功能清单与规划
CHANGELOG.md	变更记录
QUICKSTART.md	快速启动
PROJECT_TREE.md	项目目录结构
docs/README.md	文档入口与归档索引
archive/	开发文档（Docker 部署、迁移日志等）

第三方依赖许可

本仓库中的 SparkLumina 应用代码 采用 MIT 许可证。npm 包与打包资源各有其许可证。

请在仓库根目录及 frontend/、backend/ 下查阅 package.json / package-lock.json 以了解完整依赖树与版本。
常用栈包括 React（MIT）、Excalidraw（MIT）、Socket.IO（MIT）。传递依赖可能使用其他 SPDX 标识；合规需求请查看各包在 node_modules/ 下的 LICENSE 或使用许可证审计工具。

可选外部 API： 部分功能（如第三方「扫码发布」）通过可配置端点调用（见 .env.example，例如 XHS_PUBLISH_API_BASE）。请使用自有 API 密钥并遵守对应服务商条款。

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

🙏 致谢

Excalidraw — 优秀的手绘风格白板引擎
Smart-Excalidraw-Next — AI 绘图灵感
Explain Everything — 产品设计启发
Socket.IO — 实时通信
React — UI 框架

📧 联系方式

项目维护者：

GitHub：@SparkLumina
邮箱：sparklumina@outlook.com

仓库地址： https://github.com/sparklumina/sparklumina

为全球教育者与学习者而做 ❤️

若本仓库对你有帮助，欢迎 Star。