Mens 校园助手MENS CAMPUS ASSISTANT

名字取自拉丁语 mēns（属格 mentis），意为「心智、理性、思维」，与英文单词 men 无关。

把校园政策问答、知识库与办事服务放进一个本地优先的桌面应用

Mens 是一个面向院校场景的问答工作台：知识库文档（PDF / Markdown / TXT / Word）在本机检索，校园服务（成绩、课表、学分、空教室、报修）通过可配置的 HTTPS 接口接入，聊天支持流式回答、可停止生成、历史会话隔离，并可按需开启联网搜索引用网页来源；输入框右端可在「快速 / 深度」两档推理强度间切换；回答以 Markdown 排版，深度档的思考过程可展开查看。文档、数据和密钥都留在本机，模型可接 Qwen3 / DeepSeek 云端 API，也可用 Ollama 跑本地模型。

版本 1.2.2 Windows 已构建并验收 macOS / Linux：CI 构建，未真机验收 Android / iOS：可安装网页版本地 SQLite · 无需外部数据库 Apache-2.0 开源

下载 Windows 安装包查看仓库命令行平台支持开源协议已知限制

功能一览

以下功能均已在开发副本中实现并有验证记录（含安装后的真机验收），具体证据见仓库中的 docs/VERIFICATION.md。

问答

流式回答 · 可停止生成

逐字输出，随时可中断。中断时已生成的内容会连同“已停止”标记保存，历史记录不会伪造完整答案；回答可标注“演示数据”，不会假装已接入学校系统。

会话

按用户隔离的历史会话

桌面版按本机配置、网页版按浏览器分别隔离；可恢复任意会话、单条删除或一键清空。历史面板显示每条会话的标题与时间。

知识库

多格式文档检索

支持 PDF、Markdown、TXT 与 Word (.docx)（单个 ≤5 MB）。文档数据库是权威数据源，索引用版本哈希校验，删除或更新后不会返回过期分段。

检索

关键词与可选的向量检索

默认使用本地关键词检索，无需额外依赖；启用 RAG 后使用 BGE-M3 + Chroma 做语义检索，向量不可用时自动降级并在界面上如实提示。

联网

可选的实时联网搜索

按每条消息开启。默认免密钥的 Bing 网页搜索（中国大陆可直连），也可配置 Tavily 或博查；会抓取前 1–3 个网页正文，回答引用链接与检索时间。未启用时应用完全不发起检索。

服务

校园数据接口与报修

九类校园 HTTPS JSON 接口可配置（成绩、课表、学分、空教室、报修等），支持结果路径与 Bearer 令牌；报修提交后本机保留记录便于核对。

模型

云端 API 或本地 Ollama

Qwen3 / DeepSeek 走各自 API Key（地址必须 HTTPS）；本地模型由 Ollama 提供，内置模型目录支持断点续传、SHA-256 校验与导入重试。

数据

备份导出 / 导入

一键导出包含知识库、会话、模型与校园接口配置的 zip（SQLite 用 VACUUM INTO 生成一致性快照，附各文件 SHA-256 清单），换机或重装后可完整恢复。

桌面

单机运行，开箱即用

安装包内置 Python 运行时，无需另装 Python / Node / 数据库。窗口大小与位置会记住，设置页可查看后端日志与打开数据目录。

外观

可定制主题

浅色 / 深色 / 跟随系统，自定义主题色，界面按对比度自动推导文字颜色；侧栏与移动端布局分别适配。

插件

GitHub 自定义插件

插件改为 GitHub 自定义安装：粘贴仓库地址即读取仓库根目录 plugin.json（自动经 jsDelivr 与 raw 重试抓取）；插件必须使用公网 HTTPS 主机，且只能返回 JSON。

运维

更新检查与版本一致性

管理员配置 HTTPS 清单后可在设置页检查新版本并打开下载页；构建脚本会校验桌面、前端、后端三处版本号一致，且所有测试通过才产出安装包。

界面

截图为真实运行界面（开发副本，浅色主题）。

设置页：管理员可启用联网搜索、选择服务商（Bing 免密钥 / Tavily / 博查）并配置 Key。

平台支持

“已验收”指在对应系统上真实安装、启动并完成界面检查；“CI 构建”指由 GitHub Actions 生成产物但尚未真机运行。

平台	状态	交付物与说明
Windows 10/11 x64	已构建并验收	NSIS 安装包，用户级安装（`%LOCALAPPDATA%\Programs\Mens`），数据在 `%APPDATA%\CampusAgent`
macOS 12+（Intel / Apple silicon）	CI 构建，未真机验收	dmg + zip；未签名、未公证，首次打开需右键“打开”或在系统设置中允许
Linux x64	CI 构建，未真机验收	AppImage（免安装）与 deb；数据在 `~/.config/CampusAgent`
Android / iOS	不提供原生应用	使用可安装网页版（PWA）：手机浏览器打开部署好的站点 → 添加到主屏幕；推理由服务端完成

快速开始

Windows 安装包开箱即用；其他平台从源码构建，或使用网页版。

Windows：下载 Release 中的 Mens-Setup-<版本>-x64.exe，双击安装，从开始菜单或桌面启动。

从源码构建（三个平台同一脚本）：

python scripts/build_desktop.py
python scripts/build_desktop.py --os mac --arch arm64
python scripts/build_desktop.py --os linux --arch x64

从源码开发运行：

python scripts/install.py
scripts\start-backend.cmd
scripts\start-frontend.cmd

手机 / 平板：部署后端（见仓库 README 的服务器部署小节），手机浏览器打开站点后“添加到主屏幕”，即可获得全屏、独立图标的类应用体验。

命令行（CLI）

命令行是独立工具，不打包进桌面程序：它与桌面端共用同一套后端代码，数据目录默认在安装目录下，也可用 CAMPUS_DATA_DIR 指向桌面端的数据目录。

安装（Windows）：在 PowerShell 中执行：

irm https://raw.githubusercontent.com/HuanMoovo/campus-agent/main/scripts/install-cli.ps1 | iex

安装（macOS / Linux）：

curl -fsSL https://raw.githubusercontent.com/HuanMoovo/campus-agent/main/scripts/install-cli.sh | bash

脚本会把源码下载到用户目录（Windows 为 %LOCALAPPDATA%\Mens\cli，macOS/Linux 为 ~/.local/share/mens），创建独立虚拟环境、安装依赖并生成 mens 命令；不改动系统 Python，卸载只需删除该目录和命令。

装好后可以直接使用：

mens ask "图书馆开放时间"      # 提问一次（--json 便于脚本处理）
mens chat                      # 交互式对话：/quit 退出、/new 新对话
mens mcp list | test campus | tools --json
mens serve --port 8000         # 只启动本地后端

架构与安全边界

技术栈

Vue 3 + TypeScript + Vite + Element Plus + Pinia 前端；FastAPI + SQLAlchemy + LangGraph 后端；Electron 外壳内置 PyInstaller 冻结的 CPython；SQLite 单文件数据库（可选 PostgreSQL）。

本机优先

后端只监听 127.0.0.1 的随机端口，使用一次性令牌；桌面外壳注入额外请求头，外部页面无法拿到这些接口。

出站请求约束

插件、联网搜索与更新检查只允许 HTTPS、固定到校验过的公网地址（保留 SNI，防 DNS 重绑定）、禁止跳转、有大小与超时上限；解析到内网地址直接拒绝。

密钥存储

Windows 用 DPAPI 加密保存 API Key；macOS / Linux 无等价系统接口，改为 0600 权限的明文文件（同一用户可读）。这一点在 docs/PLATFORMS.md 中明确写出。

开源协议

Mens 校园助手以 Apache License 2.0（Apache-2.0）发布，完整文本见仓库根目录的 LICENSE。

你可以

自由使用、修改、再分发本项目，包括商业使用、校内自行部署，以及闭源发布你的修改版；前提是保留版权、许可证与 NOTICE 声明，并在修改过的文件中注明改动。

你需要

分发时必须随附 LICENSE 与 NOTICE 文件、保留全部版权与许可声明、并标注你修改过的文件；本许可证不授予项目名称或商标的使用权。

无担保

软件按“现状”提供，不附带任何明示或默示担保。校园生产部署（接口对接、数据合规、账号与权限）需由使用方自行验收并承担责任。

第三方组件

安装包内含 Electron、Chromium、CPython、FastAPI、Vue、Element Plus 等组件，各自按原许可证分发；完整清单见仓库中的 THIRD-PARTY-NOTICES.md。

已知限制

以下内容尚未验证或尚未实现，如实列出。

macOS / Linux 产物未真机验收：由 CI 构建，尚未在真机上安装运行过。
未签名、未公证：没有发行者证书，Windows/macOS 首次打开可能出现系统提示；正式分发前应配置签名。
校园接口与统一登录：项目不附带任何真实学校接口、统一身份认证或模型密钥；生产部署需学校提供已授权接口并验收。
云端模型与联网搜索：需要各自的 API Key（联网搜索的 Bing 通道免密钥）；搜索结果的服务端可用性受网络环境限制。
原生 Android / iOS 应用：不在本项目范围，原因见 docs/PLATFORMS.md（Python 后端无法随应用上架移动平台）。
一键更新：更新检查只提示版本差异并打开下载页，不做自动下载与静默安装。