xuemate-app

An Electron application with Vue

Focused Delivery Scenario

XueMate 的最终定位是：面向小学生的全面学习助手。

它不是单纯的编程产品，也不是泛泛的聊天机器人。它覆盖小学学习中的：

• 资料问答
• 作业辅导
• 动画讲解
• 长期学习画像
• 复习队列
• 网页资料辅助
• 硬件学习卡（实体身份卡 + 小屏状态显示）

答辩/demo 为了避免太散，选择一个代表性内容：小学编程启蒙中的冒泡排序。

核心 demo：

学生不理解 Python 冒泡排序
-> XueMate 读取老师课件和作业要求
-> 结合学生长期薄弱点
-> 用动画解释算法过程
-> 给代码修改提示但不直接代写
-> 自动寻找教学网页
-> 把循环/索引问题写入复习队列

交付口径：

XueMate 是面向小学生的全面学习助手。答辩中用“编程启蒙/冒泡排序”作为代表场景，展示资料问答、长期记忆、动画讲解、代码辅导和网页资料辅助如何形成完整学习闭环。

Detailed scenario script:

• docs/FOCUSED_SCENARIO.md

Competition Positioning

XueMate 当前建议参赛口径：中国高校计算机大赛-网络技术挑战赛 创意（A）普通 A 赛项。

参赛包装不要讲成单纯“小学生 AI 聊天助手”，而要讲成：

面向小学学习场景的云边协同智能学习网络平台。

对应网络技术方向：网络智能、云边协同、边缘 RAG、网络数据分析、多模态网页智能体。

Detailed competition analysis:

• docs/COMPETITION_POSITIONING.md

Expert Review Notes

Learning graph upgrade

XueMate 已接入 Sigma.js + Graphology，新增类似 Obsidian Graph 的「学习网络」：

• 把资料夹、文档、chunk、知识点、Memory Atom、复习任务组织成关系图。
• Sigma.js 负责 WebGL 图谱渲染，Graphology 负责图数据结构。
• 支持节点搜索、类型过滤、点击查看关联证据。
• 答辩口径：个性化学习知识图谱 / 学习资源网络可解释面板。

入口：

• 我的资料 -> 学习网络

RAG retrieval upgrade

XueMate 的资料问答已经从简单的「向量 TopK」升级为专家版 Hybrid RAG：

• 语义向量召回：理解学生的自然语言问题。
• 关键词召回：提升公式、专有名词、原文概念命中率。
• 章节结构信号：利用文件名、章节标题、重点/难点/例题等结构信息。
• MMR 多样性去重：避免多个重复片段占满上下文。
• 结构化引用：回答时可使用 [资料1] 这种可解释引用。

内部可复现 benchmark 数据：

Metric	Dense TopK Baseline	Hybrid RAG	Lift
Recall@K	93.33%	96.67%	+3.57%
Precision@K	46.67%	50.00%	+7.14%
nDCG@K	89.40%	97.04%	+8.55%
Context Waste	53.33%	50.00%	-6.25%
MRR	95.00%	100.00%	+5.26%
Context Compression vs full corpus	-	82.14% less input	-

Run the benchmark:

npm run --silent bench:rag

Detailed design and methodology:

• docs/RAG_METRICS.md
• docs/benchmarks/rag-benchmark-2026-05-29.json
• docs/benchmarks/expert-metrics-2026-05-29.json

Memory system upgrade

XueMate 的长期记忆系统也升级为专家版 Memory Atom 架构：

• 分层记忆：profile / preference / topic / weak_point / strong_point / goal / behavior / misconception。
• 每条记忆都有 confidence、importance、evidence、hits、firstSeen、lastSeen。
• 支持时间衰减，旧信息会自然降权。
• 自动生成学习画像 Learning Profile 和复习队列 Review Queue。
• Prompt 注入只选择高价值、未过期、有证据的记忆，减少上下文浪费。

内部可复现 benchmark 数据：

Metric	Flat Memory Baseline	Atom Memory	Lift
Prompt items	18	11	-38.89%
Prompt chars	531	333	-37.29%
Duplicate facts	5	0	-100%
Stale facts	2	0	-100%
Review queue coverage	0%	100%	+100%

Run the benchmark:

npm run --silent bench:memory

Detailed design and methodology:

• docs/MEMORY_SYSTEM.md
• docs/benchmarks/memory-benchmark-2026-05-29.json
• docs/benchmarks/expert-metrics-2026-05-29.json

Hardware Learning Card

XueMate 支持把一块实体硬件（LILYGO T-Dongle S3，ESP32-S3 + 0.96" ST7735 屏 + WiFi）做成「学习卡」：

• 实体身份卡：插上即识别学生身份（按硬件 UID），拔掉 / 断网 15s 自动锁定
• 小屏实时状态：显示当前学生的今日学习时长、待办 / 复习数、连续打卡（进度环、火焰、折线、翻滚数字动画）

通信：板子通过 WiFi 用 HTTP 和主进程通信 —— 主进程起独立 0.0.0.0:8799 服务，板子定时 POST 心跳上报身份、GET 拉状态。

• 主进程集成：src/main/services/hardware/、window.hardware IPC、渲染层「学习卡」tab（HardwareView.vue）
• 板子固件 + 烧录方法（独立公开仓库）：dsadsasdaddas/xuemate-dongle

XueMate Local Web Search

快速查资料已收敛为本地网页查询链路，不再维护外部搜索网关、Docker 搜索栈或 Crawl4AI vendor 目录：

• Electron 主进程通过 src/main/services/web.ts 打开搜索页并抓取正文。
• src/main/services/quickSearch.ts 做安全检查、网页摘要和本机 SQLite 历史记录写入。
• .env.example 只保留 XUEMATE_QUICK_SEARCH_MODE=local，演示部署不需要额外 cloud/search 服务。

详细说明：

• docs/WEB_SEARCH_VENDOR_STACK.md

Online Demo Deployment

香港线上演示采用 renderer-only Web preview：评委打开链接即可体验核心 UI 和流程；桌面沙箱、PeerEdge 多节点缓存、Computer Use 等本机能力在录屏中展示。

Current demo URL:

• https://yueanlab.com/xuemate/

Environment files:

• .env.example：本地桌面完整功能变量模板，包含 LLM、Embedding、Vertex Vision、PeerEdge、MCP 和缓存配置。
• .env.web-demo.example：香港 GCE 静态 Web 演示部署模板，不包含密钥。

Deploy to the existing Hong Kong GCE server:

cp .env.web-demo.example .env.web-demo
./scripts/deploy-web-demo.sh

Sync private runtime keys for server-side demos or future full-backend deployment:

# Reads local .env and installs it as root:root 600 at /etc/xuemate/runtime.env
./scripts/sync-gce-runtime-env.sh

The runtime env file is intentionally not committed. After syncing, verify server-side model access with a small smoke test before recording or submitting.

The deploy script reads .env.web-demo, builds with:

VITE_XUEMATE_BROWSER_PREVIEW=1 VITE_XUEMATE_BASE=/xuemate/ npx vite --config renderer.vite.config.mjs build

Then uploads src/renderer/dist to /var/www/aigcwzu/xuemate on hk-org-web-1 and writes the effective deployment env to /etc/xuemate/web-demo.env on the server.

Recommended IDE Setup

• VSCode + ESLint + Prettier + Volar

Project Setup

Install

$ npm install

Development

$ npm run dev

Build

# For windows
$ npm run build:win

# For macOS
$ npm run build:mac

# For Linux
$ npm run build:linux