StudyHub 连接学习资料、经验分享与校园互助，围绕高校学生的学习和生活需求，提供资源共享、求购协作与校园集市服务。
分享知识，交流经验，让校园资源更容易找到。
| 场景 | 主要功能 |
|---|---|
| 资料共享 | 上传、浏览与获取课程资料、复习提纲和学习笔记 |
| 经验分享 | 沉淀学习经验、选课建议与校园生活内容 |
| 求购协作 | 发布资源需求，开展求购、互助与交换 |
| 校园集市 | 发布校内二手交易与校园信息 |
官网：study-hub.cn
| 层次 | 技术 |
|---|---|
| 后端服务 | FastAPI、SQLAlchemy、Pydantic Settings、Uvicorn |
| 前端界面 | Next.js 15、React、TypeScript |
| 数据存储 | MySQL、SQLite、阿里云 OSS |
| 缓存与任务 | Redis、BackgroundTasks、独立 Worker |
| 异步处理 | 局部异步数据库访问与异步 I/O |
| 部署运维 | Docker Compose、systemd、Nginx |
| Agent | Qwen3.5-4B / 9B、SGLang、tokenizers、统一 Agent 执行器 |
| 内容审核 | Qwen3Guard-Gen-0.6B、ShieldGemma 2-4B、Guard-as-Jev、PyTorch、Transformers |
MySQL 用于预览与生产环境，SQLite 用于本地开发和快速体验。
studyhub/
backend/ # 后端服务、测试与运维辅助代码
frontend/ # 前端应用与 PWA
studyhub-agent/ # Agent 运行框架
review-jev/ # 文字与图片审核组件
assets/ # 宣传片、动态预览与项目海报
docs/ # 项目技术文档
reports/ # 技术报告与项目复盘
scripts/ # 开发、部署与运维脚本
推荐使用 Python 3.12、Node.js 22、npm 10，版本配置见 .python-version 与 .nvmrc。
bash scripts/dev/docker-dev-up.shbash scripts/dev/local-dev-up.sh| 模块 | 说明 |
|---|---|
| 后端服务 | 环境配置、接口与测试 |
| 前端应用 | 页面开发、构建与 PWA |
| Agent | 工具调用、运行契约与模型推理 |
| 内容审核 | 模型分流、审核接口与批量评测 |
| 开发脚本 | 本地启动、部署与运维 |
公开 API 采用 RESTful 风格，资源以复数名词命名，使用 HTTP Method 表达操作。
| 场景 | 接口示例 |
|---|---|
| 登录会话 | POST /api/session |
| 退出登录 | DELETE /api/session |
| 下载授权 | POST /api/materials/{id}/downloads |
历史动作型路径保留兼容，新客户端优先使用 OpenAPI 中的资源接口。智能体接入、OAuth 权限范围与配额见 MCP 接口说明。
bash scripts/check-shell-scripts.sh
${STUDYHUB_PYTHON_BIN:-.venv/bin/python} -m ruff check backend/app backend/tests
${STUDYHUB_PYTHON_BIN:-.venv/bin/python} -m pytest backend/tests
npm --prefix frontend run check
npm --prefix frontend run test:unitbash scripts/predeploy-check.sh发布采用独立 Release 构建、验证与切换流程。完成首次配置后，使用 bash scripts/deploy/atomic-release.sh <commit>，避免直接在在线目录构建前端。
CI 与本地质量检查可使用 bash scripts/ci-check.sh。完整门禁包含开发及生产构建下的 Playwright 关键路径，部署配置与运维命令见 脚本文档。
生产和预览环境默认关闭 FastAPI 接口文档，需要时通过 STUDYHUB_DOCS_ENABLED=true 开启。域名白名单使用 STUDYHUB_TRUSTED_HOSTS，可信代理使用 STUDYHUB_TRUSTED_PROXY_IPS，按实际部署环境配置。
欢迎通过 Issue 和 Pull Request 参与项目改进。
| 贡献者 | 姓名 |
|---|---|
| @ChengjinLii | 李承锦 |
| @Sgt-Friedrich | 曾逸帆 |
| 贡献者 | 姓名 |
|---|---|
| @JoeyLam2005 | 林俊宇 |
| @xiaji | 季文君 |
初版 SpringBoot 实现见 studyhub-springboot，目前为内部仓库。
独立运行的文档知识库、RAG 与 Agent。
StudyHub Agent 借鉴腾讯开源 WeKnora 的知识库设计，支持 PDF/OCR 文档解析、结构感知切分与 Parent-Child 分层索引，通过 BM25、向量召回、RRF 融合与 Rerank 连接 RAG 和多步 Agent；以 Map-Reduce 实现实体、概念聚合和增量 Wiki，保留文档、Chunk、版本及页码关联。
| 能力 | 实现 |
|---|---|
| 知识管理 | 本地 Markdown/TXT 导入、结构分块、版本化快照与来源定位 |
| 正文检索 | 关键词召回、可选向量召回、RRF 融合与模型重排 |
| 问答与工具 | 固定 RAG 流程，多步 Agent 通过检索、阅读和列表工具获取证据 |
| 引用核查 | 按实际展示的版本化片段核查引用，并支持反馈纠正 |
| 运行契约 | 统一消息渲染、调用解析、预算控制与契约哈希 |
| 轨迹记录 | 保存消息、工具证据、架构决策与模型信息 |
| 推理接口 | 支持 SGLang token 级接口和 OpenAI-compatible 接口 |
技术栈：Python 3.12、Pydantic、Jinja2、httpx、SGLang。架构与使用方法见 Agent 文档。
面向文字与图片投稿的内容审核组件。
StudyHub Review-Jev 采用 Qwen3Guard-Gen-0.6B 与 ShieldGemma 2-4B 双路架构，通过 Guard-as-Jev 读取安全等级与图像政策候选概率，结合规则融合、置信度门槛与人工复核，输出可解释的内容审核结果。
| 内容类型 | 默认模型 |
|---|---|
| 纯文字 | Qwen3Guard-Gen-0.6B |
| 图片 | ShieldGemma 2-4B；检出文字时按需调用 Qwen |
| 文字配图 | 正文与 OCR 走 Qwen，画面走 ShieldGemma |
| 不确定或覆盖缺失 | 人工复核 |
审核组件提供 FastAPI 服务、JSON 命令行、概率评分与批量评测工具，保留各分支风险、模型版本、OCR 状态、版权声明、开放许可与参考匹配记录。模型分流、请求示例和使用方法见 Review-Jev 文档。
StudyHub 支持 PWA 安装。通过手机浏览器打开网站，点击右下角的下载箭头即可进入安装流程；iPhone 使用分享菜单中的“添加到主屏幕”，微信等内嵌浏览器可按提示在系统浏览器中打开。
安装后沿用网站的页面、账户和 API。版本化前端资源与离线提示页由 Service Worker 缓存，登录、投稿、文件下载与支付通过在线服务完成；页面更新会在旧窗口关闭后生效。
PWA 图标位于 frontend/public/icons/，生成命令为 node frontend/scripts/build-pwa-icons.mjs。缓存策略、更新机制和验收说明见 PWA 技术说明。
StudyHub 主项目采用 MIT License。Review-Jev 的代码许可见 Apache-2.0 许可证。