Your data. Your way. All for learning.
OwnClass 是为一对一辅导老师准备的教学工具，可以部署在自己的电脑或服务器上。老师把讲义和习题导入系统，学生通过浏览器阅读、做题、手写和订正，老师随后查看作答过程与学习情况。
AI 可以参与备课、答疑和课后复盘。老师可以让 AI 按提供的格式整理教学材料；学生可以带着当前题目和手写过程向自己连接的 AI 求助；老师也可以把学习记录交给 AI，准备下一节课。
教学资料、作答记录和手写文件保存在自己的服务器上。使用 AI 求助时，系统按老师设置的教学方式，把本题内容和选定材料发送给学生连接的 AI 服务。
演示站提供示例课程和账号，适合用示例材料体验完整流程。演示数据会定期重置。
可以先用学生账号做几题，再用教师账号打开「数据」和「学情」，查看作答、手写原稿与学习情况。
- 整理教学材料：用 Markdown 编写讲义和习题，也可以把 dsl-kit/ 交给 AI，让 AI 按格式整理现有材料。导入时一起选择题目图片，系统会检查格式并展示导入预览。
- 安排课程与作业：把讲义和练习排成课程，给学生布置作业，设置截止时间和答案公布时间。多个练习单元可以分别布置，也可以合成一份作业。
- 批改与回看过程：逐题查看答案、草稿、题干圈画和订正；手写过程支持倍速回放。待批队列提供快捷键，方便连续批改。
- 查看学习情况：查看课程完成情况、正确率变化、薄弱考点、答题用时和讲义阅读情况，寻找下节课适合重点讲解的内容。
- 交给 AI 做复盘：导出学习数据和手写图片，或通过「连接 AI」让支持 MCP 的客户端读取资料、生成报告并将报告存回系统。
- 管理自己的数据：下载完整备份，通过密码确认恢复。每位老师分别管理自己的课程、学生和作业，也可以把教学材料发布到共享中心。
- 打开链接开始学习：使用老师提供的专属链接，或用账号密码登录；支持电脑、手机与 iPad 浏览器。
- 边读边练：在讲练页里读一段内容、做一道题，逐题提交并查看反馈；手写题按老师批改结果查看成绩。
- 直接动笔：在题干上圈画重点，在草稿纸演算，或用 Apple Pencil 手写答案。纸面支持全屏和分栏，笔写与手指滚动可以配合使用。
- 按题向 AI 求助：发送当前题目、作答和选定的草稿或圈画，收到回复后继续追问，或回到原题尝试新步骤。
- 交卷后复习：对照详解查看本次原稿，写订正与错因反思；从题目历史比较历次作答，从错题本发起重练。
- 调整个人偏好：在头像进入的设置页中管理书写手感、AI 连接和常用提问方式。
以下按功能整理 2026 年 10 月 10–19 日的主要变化，日期表示这些功能的集中更新时间。
- 三种求助方式：学生可以连接自己的 AI 接口、通过 MCP 客户端处理求助，或生成供外部 AI 读取的题目链接。结果页支持选择多道题，逐题发起 AI 复盘。
- 老师安排求助时机：支持「开放学习」「仅启发」「完成后可用」，可以为学生或作业单独设置。教师端可查看求助和回信记录。
- 回复接在原题下面：做哪道题，就在那道题下面提问和阅读回复。宽屏时可以主动固定在旁边对照，也可以进入专注阅读。
- 可以直接请求提示：选择问法后可以直接发送；自己写的问题会保留。发送前可以查看本次题目、作答和选定材料。
- 读完接着尝试：点「回题试一试」回到原来的位置；补写步骤后，可以选择新稿或输入文字，请 AI 检查。沿着旧回复追问时，会继续使用当时发送的材料。
- 输入和阅读位置都能接上：切题、收起对话、前往连接设置再返回时，保留当前会话中的提问草稿；新回复到达后先提示，由学生选择阅读时机。草稿在当前页面会话中保留，退出账号时清理。
- 长回复更方便阅读：支持回复目录、引用某一步继续提问、专注阅读和公式排版；较长内容还提供分段文字阅读。
- 求助记录能带回现场：从记录打开对应题目和对话，接着阅读或继续做题。
- 讲练一体已加入正式功能：老师可以把题目放在讲义的对应位置，学生边读边答，每题单独提交。
- 提交后逐题反馈：客观题可以即时查看判定与详解，手写题进入待批流程；最后一题提交后，本次学习自动完成。
- 课程目录更清楚：讲练页作为一项内容加入课程，随堂题跟随讲练页呈现。导入预览也按一份讲练页展示。
- 学习记录接上练习过程：保留逐题进度、作答与手写原稿，方便课后查看和再次练习。
- 圈画与草稿一起展开：边圈题干边演算，按空间选择左右分栏、上下排列或全屏书写。
- 题面与笔迹一起缩放：保存圈画时记录原题排版，回看和跨设备打开时按同一比例展示题面与笔迹。
- 保存过程更清楚：分别跟踪答案、草稿、正式手写与圈画的保存情况；换设备继续时核对已有材料，同一份内容发生冲突时由学生选择保留的版本。
- 本题材料可以导出：作答中导出题面、已有圈画和本题手写材料；长稿分页，每页带题面，支持下载与逐页复制。
- 书写手感可以保存：调整后给配置起名，在当前设备选择使用；草稿、正式手写和订正共用设备配置。
- 长作业里书写更顺畅：反复打开圈画更快，后台保存和求助状态更新时，其他题目保持原样，方便继续书写。
- 打开和回看更顺畅：优化题目材料读取、圈画准备和重复排版；回看中的原圈画会在题目进入可见区域后加载。
- 首页聚焦待办：显示最新两份待完成作业和待办总数；「我的作业」支持状态、日期、标题筛选与分页，返回列表时接上原筛选。
- 手机做题顶栏更简洁：返回、单元名称与更多入口集中在顶栏，保存状态和练习信息放在「更多 → 练习信息」。
- 结果页按题整理操作：详解、本次原稿、订正、本题历史和更多操作集中排列，方便对照；从历史返回时回到原来的题目。
- AI 连接集中管理：「我的连接」先展示连接列表，再进入新增、详情或修改；MCP 详情提供完整配置、Token 与端点，方便复制到客户端。
- 个人设置按用途分组：个人信息、学习偏好和 AI 求助偏好集中管理；展开编辑、收起再打开时继续保留当前输入。
- OwnClass 统一外观：教师端与管理端使用一致的品牌和靛蓝主题；导航按教学、分析、系统分组，窄屏通过抽屉访问。
- 设置按类别查看：教学、备份与账号分类展示；保存前可以继续修改，离开时提供保存相关提醒。
- 连续保存设置更稳妥：每次保存都会更新版本，旧页面再次提交时会提示刷新，保留已经保存的新设置。
- 课程选项及时更新：创建或调整课程后，导入页的「同时加入课程」同步刷新。
- 师生账号切换更稳妥：同一浏览器支持同时使用教师和学生身份，换账号时刷新对应页面数据。
- 公式与导出显示更完整：改进公式检查、圈画底图字体和导出图片中的公式显示。
| 内容 | 文件里的标记 | 适合怎样使用 |
|---|---|---|
| 讲义 | kind: lecture |
阅读知识讲解、公式、折叠例题、分步推导和函数图像。 |
| 练习 | kind: practice |
组织题库或作业，支持判断、单选、多选、填空、计算、应用和找错题。 |
| 讲义加配套练习 | kind: mixed |
一份文件导入后，形成讲义和关联的练习单元。 |
| 讲练一体 | kind: lesson |
题目穿插在讲义中，学生边读边答，逐题提交。 |
学生可以通过老师布置的作业、课程中的自主练习、错题重练和讲练页学习。普通作业按老师设置的时间公布答案；讲练页按题提交、按题反馈。历次作答与交卷原稿分别保存。
| 方式 | 怎样使用 |
|---|---|
| 页内 AI | 在「设置 → 连接 AI」填写兼容接口地址、模型和自己的 API Key，直接在题目下提问、看回复。 |
| MCP 客户端 | 复制完整 MCP 配置到支持该协议的 AI 客户端，由客户端领取题目求助并写回回复。 |
| 题目链接 | 生成包含本题与选定材料的链接，交给支持读取网页的外部 AI。链接可以设置有效期，也可以主动撤销。 |
老师可以选择「开放学习」「仅启发」「完成后可用」，并为学生或作业单独调整。启发模式会向 AI 提供本题答案与解析，并要求它用提示引导；希望学生完成后再接触 AI 的老师，可以选择「完成后可用」。本题完成后，AI 按复盘方式提供帮助。
AI 求助会发送本题上下文和选定材料；普通作答页的答案与详解继续按公布规则展示。题目链接的持有者可以读取其中内容，适合发给信任的 AI 服务。页内 AI 费用由学生选择的服务商收取，多题复盘按题分别调用。连接方法和教学设置见学生端 AI 伴学使用指南。
- Node.js 24 或更新版本。
- pnpm 12.6.0；使用 Docker 时，安装 Docker Engine 与 Compose 即可。
先在项目目录执行 pnpm install，随后选择一个脚本：
- 测试模式.cmd：启动开发服务，前端地址
http://localhost:5173，后端端口8787。同一 Wi-Fi 下，学生可以通过电脑局域网 IP 访问。 - 启动服务.cmd：构建并启动生产服务，浏览器打开
http://localhost:8787。
pnpm install
pnpm dev首次打开教师端，按设置向导创建管理员账号。服务完成建库后，可以运行 pnpm seed:demo 生成示例课程与学生；终端会显示 demo 教师的随机初始密码，示例学生密码为 demo-pass-123。
Docker Compose：
git clone https://github.com/LIziak112/simple-tutor-tool.git
cd simple-tutor-tool
mkdir -p data
sudo chown -R 1000:1000 data
docker compose up -d --build容器启动后打开 http://服务器地址。也可以在主机上执行 pnpm build，用 systemd 管理 node apps/server/dist/index.js。详细步骤见部署文档。
小内存服务器升级时，先停止原服务，再安装依赖并构建，完成后启动服务、检查健康状态。 升级前先备份完整数据目录；systemd 使用 systemctl stop simple-tutor-tool 停服，Docker Compose 使用 docker compose stop app 停服。
| 环境变量 | 默认值 | 作用 |
|---|---|---|
PORT |
8787 |
服务端口。 |
DATA_DIR |
./data |
保存数据库、手写文件、共享材料、备份和会话密钥。 |
PUBLIC_URL |
http://localhost:8787 |
填写实际访问地址；HTTPS 部署会启用安全 Cookie 和 PWA。 |
备份建议使用教师端「设置 → 备份与恢复」下载完整数据包；手动复制数据目录时先停服。
- 把 dsl-kit/ 交给 AI，整理讲义或试卷；在教师端导入材料，查看预览并确认。
- 创建课程、添加学生，安排讲义与练习，按需要布置作业。
- 把专属链接发给学生，让学生阅读、作答、手写和按需向 AI 求助。
- 查看学生作答过程，批改手写题，结合学习情况安排订正和重练。
- 导出 AI 学情数据包，或通过教师端 MCP 连接读取学习记录，准备下一节课。
项目采用 pnpm workspace。共享的 Zod schema 定义内容和接口格式，前端、后端、MCP 与导出共用这些定义。
| 部分 | 使用的技术 |
|---|---|
| 前端 | React 19、Vite、Tailwind CSS v4、shadcn/ui、TanStack Query、Zustand、React Router、CodeMirror、ECharts、KaTeX、MathLive。 |
| 手写与图片 | Atrament、Excalidraw、html-to-image。 |
| 后端 | Node.js 24、Hono、SQLite、better-sqlite3、Drizzle ORM、pino、MCP SDK。 |
| 检查与测试 | TypeScript strict、Vitest、Playwright（Chromium / WebKit）、Biome、GitHub Actions。 |
| 部署 | 单个 Node 进程提供网页和 API；支持 systemd 或 Docker + Caddy。 |
apps/web/ 学生端、教师端和管理端网页
apps/server/ API、MCP、静态资源与数据库
packages/contract/ 共用的数据定义与能力清单
packages/md-dsl/ Markdown 解析、检查与规范生成
packages/grading/ 服务端判分
samples/ 教学样例和兼容性测试材料
dsl-kit/ 交给 AI 使用的格式规范、样例、提示词与检查工具
docs/ 使用、部署、设计和验收文档
e2e/ 浏览器自动化测试
| 命令 | 用途 |
|---|---|
pnpm dev / pnpm build |
开发启动 / 构建。 |
pnpm test / pnpm e2e |
单元测试 / 浏览器端到端测试。 |
pnpm lint / pnpm typecheck / pnpm format |
代码检查 / 类型检查 / 格式化。 |
pnpm db:generate |
生成数据库迁移。 |
pnpm schema:export |
导出 JSON Schema。 |
pnpm gen:spec |
生成 DSL 规范，更新 dsl-kit 分发包与离线检查脚本。 |
pnpm tutor-lint <文件或目录> |
检查教学文档格式。 |
pnpm reparse [--dry-run] |
按当前解析规则重新提取题目和讲义内容，--dry-run 用于预览。 |
pnpm seed:demo |
生成演示数据。 |
开发时先更新共享契约，判分由服务端执行；学生可见内容按作答进度与答案公布规则生成，AI 出站按教学策略授权。现存样例承担兼容性回归检查。合并前执行 lint、类型检查、单测、规范生成校验、构建和浏览器测试，具体约定见 AGENTS.md。
| 文档 | 内容 |
|---|---|
| 页面功能清单 | 按页面了解现有功能。 |
| AI 伴学使用指南 | 师生设置、连接方式、求助与复盘。 |
| 部署文档 | 安装、升级、备份恢复与运维。 |
| DSL 规范与样例 | 教学材料格式与完整样例。 |
| AI 材料整理包 | 给 AI 使用的规范、提示词和检查工具。 |
| 技术架构与实施方案 | 架构决策与实现说明。 |
| 开发进度与验收 | 阶段记录与验证结果。 |
MIT。欢迎通过 Issue 分享教学场景、使用反馈和改进建议。