• 🇨🇳 中文文档
  • 在线演示 (Live Demo)
  • 一、项目初衷 (Motivation)
  • 二、模块设计与系统架构 (Architecture)
  • 三、使用手册与快速上手 (User Manual)
  • 四、课题组二次开发与 Vibe-Coding 定制 (Customization & Vibe-Coding Skill)
  • 五、版权、致谢与开源声明 (Copyright & Acknowledgements)
  • 六、赞助与支持 (Buy Me a Coffee)
• 🇬🇧 English Documentation
  • Online Demo (Live Preview)
  • 1. Motivation
  • 2. Modular Design & Architecture
  • 3. User Manual & Getting Started
  • 4. Lab Customization & Vibe-Coding Skill
  • 5. Copyright, Acknowledgements & Open Source Statement
  • 6. Sponsor & Buy Me a Coffee

无需配置或搭建后端，即可直接在浏览器体验课题组“已正常使用一段时间”后的真实视觉设计与交互流程：

👉 点击直接体验 LabOrbit 在线演示版 (GitHub Pages)

• 免密秒进：无需注册或登录，默认以课题组负责人「李华（教授/管理员）」身份直接进入管理工作台；
• 全套预置数据：预填天体物理与交叉科学课题组真实学术数据（组会排期、arXiv 推荐精选、通知公告、研讨评论与经典教材）；
• 角色专属向导：右下角常驻演示控制浮窗，点击 🎓 功能向导 启动交互式引导；管理员与组员视角各自适配了针对性的功能漫游向导；
• 双重视角切换：浮窗内支持在「管理员 / 课题组长」与「普通组员 / 研究生」视角间一键无缝切换，体验不同角色的权限与界面设计；
• 纯前端沙盒：数据基于浏览器本地（localStorage）隔离持久化，配备半透明演示水印与一键 🔄 重置 恢复出厂状态。

在高校与科研院所课题组的日常科研协作中，常会遇到一些繁琐却高频的小问题：

1. 文献分享易被冲淡：在微信群、QQ 群或邮件里随手分享的 arXiv 论文或顶刊链接，往往很快被日常聊天刷过去，缺乏集中归档、标签分类与组内交流记录；
2. 组会排期沟通琐碎：组会常靠口头通知或共享表格登记，容易发生时间冲突；轮值主讲人有时也会忘记提前填报题目摘要或上传幻灯片；
3. 基础参考资料分散：经典的参考教材、讲义 PPT 与代码仓库散落在不同网盘或个人电脑中，新人进组时常常需要反复找人索要；
4. 学术报告通知零散：院系前沿讲座常以海报图片或邮件分发，手动转录至个人日程容易遗漏。

LabOrbit 最初正是为了解决这些实际需求而开发的一个轻量协作工具，将文献推荐、组会排期、资料归档与日程提醒整合在一个界面中，支持本地私有部署，也支持通过 Cloudflare 免费服务托管。

系统采用前后端分离架构，提供两种部署形态：

• 自建服务模式：基于 Python FastAPI 与 SQLite，适合在局域网工作站或云服务器上直接运行；
• Serverless 托管模式：基于 Cloudflare Pages Functions、D1 关系数据库与 R2 存储桶，无需自备常开服务器。

┌────────────────────────────────────────────────────────────────────────┐
│                          LabOrbit 前端 (Frontend)                         │
│           Vue 3 + Vite + Tailwind CSS + Three.js + KaTeX                │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
         ┌──────────────────────────┴──────────────────────────┐
         ▼                                                     ▼
┌──────────────────────────────────┐  ┌──────────────────────────────────┐
│        自建模式 (Self-Hosted)    │  │    Serverless 托管 (Cloudflare)  │
│      FastAPI + SQLite + Docker   │  │     Pages Functions + D1 + R2    │
├──────────────────────────────────┤  ├──────────────────────────────────┤
│ • Python 异步后端 API            │  │ • Cloudflare Pages 静态与边缘函数│
│ • SQLite3 本地单文件数据库       │  │ • Cloudflare D1 边缘关系数据库   │
│ • 本地目录持久化存储             │  │ • Cloudflare R2 对象存储 (免流量)│
└──────────────────────────────────┘  └──────────────────────────────────┘

• 1. 工作台主页 (Home Dashboard)
  ├─ 快捷入口：一键录入 arXiv 推荐、快速登记日程与智能粘贴导入
  ├─ 通知公告：重要截稿日期与讲座滚动的公告栏
  ├─ 每周日程：按周查看全组会议安排与个人倒计时看板
  └─ 个人待办：下一次主讲或文献分享的到期提醒

• 2. 组会与学术日程 (Seminar & Schedule)
  ├─ 视图切换：时间轴、周历及学术会议列表
  ├─ 封面相册：基于 Three.js 实现的 3D 轮播展示海报与近期组会
  ├─ 主讲人填报：到期前提醒主讲人补充题目、摘要与课件链接
  ├─ 日历导出：支持生成标准 iCalendar (.ics) 文件同步至手机或日历软件
  └─ 批量导入：支持解析带有主讲人和主题的 CSV 排期表

• 3. 智能粘贴与协作待审 (Smart Paste & Pending Queue)
  ├─ 智能识别：支持一键粘贴纯文本通知、长排期表或拖入学术海报截图
  ├─ 多模态解析：借助 AI 视觉与启发式正则引擎自动提取时间、地点、报告人与摘要
  ├─ 分类推断：自动判断为学术报告、组会、文献推荐或通知
  └─ 协作待审队列：成员提交草案进入待审池，管理员统一批量审核并一键同步入历

• 4. 文献推荐与集中文献库 (Literature Hub & Archive)
  ├─ 自动解析：输入 arXiv 编号/链接或 DOI，异步获取标题、作者与摘要
  ├─ 范围控制：支持“公开推荐”（全组可见）与“定向推荐”（仅指定成员可见）
  ├─ 重点标记：课题组负责人（PI）推荐带有高亮徽章
  ├─ 研讨评论：组员标记阅读状态，沉淀简短讨论与笔记
  └─ 集中文献库：汇聚全组学术文献，支持按来源（推荐/组会/定向收录）过滤与全字段检索

• 5. 教材资料文库 (Resource Hub)
  ├─ 分类归档：按基础理论、专业方向及工具库分门别类
  ├─ 检索定位：支持拼音首字母筛选与常用资料星标收藏
  └─ 资源链接：汇总在线教程、配套 GitHub 代码仓库与下载链接

• 6. 学术邮箱与海报解析 (Mailbox & OCR)
  ├─ 邮箱互联：支持配置高校或研究所 IMAP/SMTP 邮箱
  ├─ 海报识别：提取报告海报中的时间、地点与报告人信息
  └─ 一键入历：确认信息后直接添加到组内公共日程

• 7. 学术 AI 辅助 (AI Assistant)
  ├─ 公式渲染：基于 KaTeX 实时排版 LaTeX 数学公式
  ├─ 翻译与润色：保留专业术语与公式符号的学术翻译
  └─ 接口兼容：支持对接主流大模型 API 服务

• 8. 系统与权限设置 (Settings & Governance)
  ├─ 注册邀请码：内置邀请码验证（默认 LAB-2026），避免无关人员注册
  ├─ 角色管理：管理员 (Admin)、教师/负责人 (Teacher)、组员 (Student) 三级权限
  └─ 界面配置：支持深色/浅色及多套界面主题切换

克隆代码后直接运行根目录的启动脚本。脚本会自动检测 Python 环境、安装后端依赖、构建前端并启动服务：

git clone https://github.com/Chocologism/lab-orbit.git
cd lab-orbit
chmod +x start.sh
./start.sh

服务启动后，浏览器打开 http://127.0.0.1:8000 即可访问。

仓库内提供配置好的 Dockerfile 与 Docker Compose 编排文件，可在服务器后台运行并自动持久化数据：

docker compose -f deploy/docker-compose.yml up -d

• 服务端口：默认映射宿主机 8000 端口；
• 数据目录：数据库保存于宿主机 ./data/labhub.db，容器更新重启不影响已有数据；
• 环境变量：可在 deploy/docker-compose.yml 中修改注册邀请码 LABHUB_INVITE_CODE 与密钥 LABHUB_SECRET_KEY。

若没有独立的常开服务器，可部署在 Cloudflare 免费套餐（Pages + D1 数据库 + R2 存储桶）上：

1. 登录 Wrangler：

   npm install -g wrangler
   npx wrangler login

2. 创建 D1 数据库与 R2 存储桶：

   cd frontend
   npx wrangler d1 create labhub-db
   npx wrangler r2 bucket create labhub-files
   npx wrangler d1 execute labhub-db --file=functions/schema.sql

3. 构建并发布：

   npm run build
   npx wrangler pages deploy dist --project-name lab-orbit

具体配置说明与数据迁移步骤可参考 Cloudflare 部署指南。

系统采用「首位注册即管理员」的极简两步向导机制，在完成首次部署或配置新域名后即可快速完成全站初始化：

• 自建服务 / 本地与 Docker 部署： 服务启动后，直接访问 http://127.0.0.1:8000（或您的服务器 IP/域名）。系统路由守卫检测到未初始化时会自动跳转至 /setup；亦可手动访问 http://127.0.0.1:8000/setup。
• Cloudflare 全托管部署（Pages + D1）： 按照上述步骤部署完成后，直接在浏览器中打开 Cloudflare Pages 为您生成的默认项目域名（如 https://lab-orbit.pages.dev）或已绑定的自定义二级域名（如 https://lab.yourdomain.org）。前端边缘检测到 D1 数据库内尚无用户时，会自动强制重定向至 /setup 初始化页面；也可以在域名后直接访问 https://your-domain.pages.dev/setup。
• 配置了 Nginx / Caddy 反向代理或私有自定义域名： 访问您的自定义公网/校网域名根路径（如 https://hub.physics.edu.cn/），站点同样会自动检测并引导进入 /setup 页面。

💡 特别提醒（与 GitHub Pages 演示模式的区别）： 官方 GitHub Pages 演示站（*.github.io）因为预置了完整的脱敏学术演示数据，会自动激活只读沙盒模式；而在您自己的 Cloudflare Pages、独立服务器或自建域名上部署时，属于全新的生产环境实例，初次打开均会自动进入此初始化向导。

1. 步骤一：设立超级管理员：填写首任管理员用户名、真实姓名、工作邮箱与登录密码（建议由课题组负责人或指定运维学生填写）；
2. 步骤二：课题组品牌与协作配置：
   • 课题组名称与缩写：例如「天体物理与交叉科学课题组」（缩写 LabOrbit），系统标题与导航徽标将自动同步更新；
   • 所属机构与地点：填入学院/系所名称及默认研讨室（如“物理楼 302 / 腾讯会议”）；
   • 初始注册邀请码：设定用于吸纳本组组员的注册口令（系统默认预填 LAB-2026，可自由设定）。

• 安全自锁防重置：完成第二步并点击确认后，管理员账号自动登入并进入主工作台。此时系统后端 API（POST /api/system/setup）与前端路由守卫将永久锁定并禁用 /setup 路径。任何后续针对 /setup 的未授权访问都会被拦截并重定向回首页或登录页，彻底杜绝数据覆盖或恶意重置风险。
• 邀请课题组组员： 初始化完成后，管理员可将设定的注册邀请码告知本组师生，成员在登录页（/login）点击“注册新账号”输入该邀请码即可自主加入。
• 角色与权限层级说明：
  • 管理员 (Admin)：负责系统全局设置、成员角色调整（如授予组会管理权）、批量导入排期以及处理组内反馈；
  • 教师 / 课题组长 (Teacher/PI)：发布置顶公告、重点星标推荐文献、指定组会主讲人与审核协作草案；
  • 组员 (Student)：正常推荐前沿文献、登记组会题目课件、借阅/下载教材资料与沉淀阅读笔记。

• 智能粘贴与海报解析入历： 点击导航栏或工作台的“智能粘贴”，直接粘贴通知文本、微信/邮件消息，或拖入讲座海报截图。系统会自动提取时间、地点、报告人与摘要等关键元数据，确认无误后可一键加入公共日程或提交待审池。
• 协作排期与审核流转： 组员提交的学术会议或讲座草案会自动沉淀至“待审队列”；管理员与导师可在专属面板中批量审阅、一键通过或调整细节，兼顾组员共建活力与团队日程的准确性。
• 文献推荐与集中文献库沉淀： 在页面右上角点击“推荐文献”，填入 arXiv 编号或 DOI，系统会自动解析元信息。支持“公开推荐”或面向导师/特定组员的“定向推荐”。全组推荐与组会分享的论文将自动归集于“文献库”，支持多维度筛选检索与阅读状态追踪。
• 组会排期与日历同步： 学期初管理员可通过 CSV 文件一次性批量导入排期。系统在轮值到期前自动提示主讲人补充题目与课件，组员可随时导出 .ics 日历文件同步至手机与个人日程。
• 参考资料与文库整理： 在“资料整合”中录入组内常用教材、参考书与讲义链接，支持按拼音字母检索与星标收藏，大幅降低新成员进组的学习门槛。

为了让任何高校院系或科研课题组（如计算机视觉、自然语言处理、生物信息、计算化学、凝聚态物理等）都能以极低门槛将 LabOrbit 改造为本组专属的科研协作平台，本项目原生内置了完备的 Vibe-Coding 专属开发技能（Agent Skill）：vibe-coding-lab-orbit。

• AI 智能体自动发现入口：.agents/skills/vibe-coding-lab-orbit/SKILL.md（规范目录，兼容 Antigravity、Cursor、Windsurf、Claude Code、Codex 等主流 AI 编程 Agent）；
• 开发者网页查阅入口：skills/vibe-coding-lab-orbit/SKILL.md（镜像目录，便于直接在 GitHub 网页文件树中查阅）。

该 Skill 沉淀了从架构定位到生产验收的 8 大全栈标准作业程序 (SOP)：

1. 全栈架构地图与代码定位：完整梳理 12 个前端主视图、核心公共组件库（BaseDialog、AppIcon、SmartPaste 等）与三轨后端服务地图，秒级定位业务代码；
2. 课题组一键适配与自动化重整：提供针对不同学科的站点名称、Logo 与 Favicon、学科预置数据种子（Seed & Mock）及高校专属邮箱后缀的平滑替换方案；
3. 全栈双轨功能开发与接口对接：阐明「三轨一致性原则（Triple Consistency）」——FastAPI（自建）+ Cloudflare Pages Functions（托管）+ Demo Adapter（静态沙盒）同步开发与契约保持；
4. 数据库操作与平滑迁移：规范 SQLite 与 Cloudflare D1 的安全加法迁移方案，杜绝破坏性数据变更；
5. 页面布局与视觉重整规范：详述 Liquid Glass 流动毛玻璃设计变量、BaseDialog 双重坐标判定防误关黄金规则，以及多端自适应响应式设计；
6. 3D 动画、微动效与 KaTeX 渲染：指导调节 Three.js 封面轮播景深与手势阻尼、Hover 卡片微动效，以及 LaTeX 数学公式实时排版引擎；
7. 设计图标体系扩展与品牌替换：基于 AppIcon.vue 的 50+ 语义化 SVG 矢量图标字典扩展机制；
8. 质量门禁与测试验收清单：包含 57 个测试套件、369+ 单元测试 100% 通过核查、多环境静态构建与本地服务拉起验证。

在支持 Agent Skill 的编辑器（如 Antigravity、Cursor、Windsurf 等）中，无需手动翻阅全站代码，只需像与架构师对话一样提出需求，AI 将自动加载该 Skill 并执行精确修改：

示例提问与指令：

• “我想把 LabOrbit 适配到我们人工智能与计算机视觉课题组，请按照 vibe-coding-lab-orbit skill 的指南，帮我把预置数据、论文推荐分类和站点名称一键更新。”
• “请在文献库卡片上新增一个‘一键复制 BibTeX’的按钮，并遵循三轨一致性原则补充接口和演示沙盒。”
• “帮我把组会 3D 海报轮播的旋转惯性调大一点，卡片加一个发光悬停特效。”

修改完成后，AI 将自动运行 npm --prefix frontend test 确保全部 369 个单元测试 100% 通过，杜绝功能回退。

本项目在开发中采用了 Vibe-Coding 方式：由人类开发者把控实际需求、交互流程与整体架构，借助 AI 编程工具进行代码编写、接口联调与测试用例补全，快速完成系统构建与重构。

本项目由人类维护者主导需求把控与交互架构，并与 AI 结对编程助手共同构建完成：

界面的视觉效果与交互体验使用了以下开源项目：

• Three.js：用于组会日程海报的 3D 轮播展示；
• Tailwind CSS：提供页面样式与响应式布局支持；
• KaTeX：提供 LaTeX 数学公式实时排版渲染；
• Lucide Icons：提供统一的矢量图标库；
• Vue 3 & FastAPI：构成前后端核心技术栈。

• MIT License：本项目基于通用的 MIT 许可证 开源，可自由使用、修改与部署；
• 非营利声明：本项目完全开源，为个人/课题组科研实际需求驱动的非营利工具，不包含任何商业变现或付费功能；
• 欢迎共建：欢迎提出改进建议、提交 Issue 或发起 Pull Request。

如果 LabOrbit 对你的科研日常、课题组协作或开发有所帮助，欢迎请作者喝杯咖啡 ☕️，感谢你的认可与支持！

_{扫码支持作者（支付宝）}