StudyMate

你的AI学习搭档：定计划、讲知识、做项目，学透一门科目

_{StudyMate 是面向数学与计算机科目学习的助手，原则是「learn with doing」}

快速开始 · 它是什么 · 核心功能 · 常见问题 · 使用说明

Preface

This project began as a small tool I vibe-coded for personal use, yet surprisingly many people came to like it. But vibe-coded output has a lot of problems, including bloated, AI-flavored docs with poor readability, huge amounts of useless defensive code, and a confusing tangle of functional modules.

While it works decently now, there is still a big gap from what I idealize it to be.

I feel this project doesn't deserve so much trust and stars. I will face these issues directly and manually review every file, so that future updates bring a better experience. Thanks for using and supporting the project — open an issue with any suggestion. It will be maintained long-term.

Quick Start

Dependencies: DSH, Python 3.9+, pyyaml, bash, coreutils, sed (on Windows, only DSH + Python 3.9+ + pyyaml are required).

Install via npm (recommended)

You can also use the following command to update; see Installation Guide for the native commands.

npx @yunmiao/studymate@latest install
dsh web

macOS / Linux

# ① 克隆本项目
git clone https://github.com/Miaotofu01/Study-Mate.git StudyMate && cd StudyMate
# ② 装「学习模式」预设 + 建学习工作区
./install.sh
# ③ 启动 DSH，在任意目录新建会话并选「学习模式」预设
dsh web

Windows (PowerShell)

git clone https://github.com/Miaotofu01/Study-Mate.git StudyMate; cd StudyMate
powershell -ExecutionPolicy Bypass -File .\install.ps1
dsh web

Successful install output:

① 预设 → /home/you/.dsh/.agent-presets/learning（skill 目录：/path/to/StudyMate/.dsh/skills）
② 学习工作区 → /path/to/StudyMate/workspace（配置在 /home/you/.dsh/studymate-config.yaml）
完成（StudyMate v0.1）。现在可在任意目录开会话，选'学习模式'预设开始学习。

• First time learning: when creating a new session, pick “Learning Mode” and say something like “I want to learn [a subject]”.
• The learning workspace defaults to StudyMate/workspace; all courseware and memory are stored in the workspace
• After the first course generation, the course home page lives at <workspace>/index.html in the workspace directory and serves as the entry point for all future courseware

What It Is

StudyMate is a “Learning Mode” preset + a set of SKILLs for DSH (DeepSeek Harness). It on-demand schedules five sub-roles behind the scenes — material gathering, image collection, course design, explanation, and exercise evaluation — and the output is a full set of HTML courseware. It focuses on learning math/computer science related subjects.

• Course composition: explanation | practice | project: each subject has an outline — knowledge points form a roadmap by prerequisite order, each labeled with type "concept | hands-on | lab" (in the outline written as 概念／实操／实验). Progress is saved to files so new conversations can resume.
• Cross-subject shared memory: remembers your level, what teaching style works, and common sticking points, so you skip the re-intro on the next subject.

Why Use It

Core Features

Course overview & roadmap: overview lists all subjects and current node; open one to see that course's dependency-layered, status-colored knowledge map; nodes expand in place to show lesson sub-cards.

Lessons are the main learning vehicle: textbook-style, richly illustrated, with custom exercises & project goals.

Want to browse real output? The examples/ directory in the repo is a complete example workspace (Linear Algebra + Computer Networks), already rendered into pages — clone it, open examples/index.html in your browser, and you can click all the way through to the subject home pages and lessons.

Usage Examples

• "I want C++ for competitions" → probes goals/level/projects/lab first, then outputs outline roadmap & subject page, opens lesson 1.
• Paste a confusing paragraph + "don't get this" → coach answers a short snippet, logs a profile entry, puts you back where you left off.
• "Quiz me" → on-the-spot questions verified by runnable evidence, assessment record + progress update.
• "Too easy / lost" → switches style (counterexamples or lower abstraction), records preference to shared memory.

Config & Maintenance

python3 scripts/gen_home.py                    # 生成根主页 + 全部科目主页（默认读配置里的 workspace）
python3 scripts/preview_templates.py --open    # 用假数据渲染主页模板到 .preview/，只看样式与交互
python3 scripts/render_lesson.py <subject_path> <节点id>   # 内容文件 + 题库 → 课件 HTML（--check 只校验不写盘）
python3 scripts/check_curriculum.py examples/.learning/subjects/computer-networks/curriculum.yaml
python3 scripts/check_lesson.py examples/.learning/subjects/linear-algebra/lessons/0001-vector.space.html --subject examples/.learning/subjects/linear-algebra --node vector.space
python3 scripts/check_pool.py <你的科目目录>    # 图片池：索引 pool.md 与 assets/img/pool/ 对不对得上
python3 scripts/check_skill.py .dsh/skills/*    # 技能 frontmatter（改过技能就跑一次）
bash scripts/tests/run_tests.sh                # 回归测试：检查/题目属性/命名指针/提示词规则/DOM（改引擎就跑一次）

# 换成你自己的科目：--subject 给科目目录，--node 给该课件对应的节点 id；大纲校验可一次传多个 curriculum.yaml

Project Structure

StudyMate/                     ← 本仓库：系统源码（引擎），学习时只读
├── install.sh / install.ps1   # 装预设 + 建学习工作区，幂等（macOS/Linux 与 Windows 各一份）
├── .dsh/skills/               # 11 个技能：总控 learning-system + 5 个角色 + 5 个规范
│   ├── learning-system/       #   总控（主教练）：开场、盘问、调度、档案
│   ├── resource-scout/        #   角色：收集资料（权威教材与官方文档 → 资源清单）
│   ├── image-scout/           #   角色：采图（抓网页现成的图 → 科目图片库与索引）
│   ├── curriculum-designer/   #   角色：课程设计（大纲 / 实验课节点）
│   ├── learning-coach/        #   角色：讲解（写课件内容）
│   ├── practice-evaluator/    #   角色：出题与评估（题目唯一 owner）
│   ├── lesson-design/         #   规范：课件唯一约束来源
│   ├── layered-practice/      #   规范：四层练习与题型
│   ├── evidence-check/        #   规范：完成证据核验
│   ├── local-qa/              #   规范：局部提问怎么答
│   └── record-keeping/        #   规范：学习状态读写规则
├── preset/learning/           # 「学习模式」预设源（安装脚本装到 ~/.dsh/）
├── schemas/                   # 5 份数据结构：大纲 / 进度 / 评估 / 会话摘要 / 科目
├── templates/                 # 页面骨架（主页、科目页、课件壳）与前端资源 assets/
├── scripts/                   # 主页生成 + 课件渲染器 + 四道校验检查（用法见上）+ tests/ 回归测试
├── examples/                  # 示例学习工作区：线性代数 + 计算机网络，页面已生成，clone 即可点开
├── docs/                      # 使用说明、课件内容格式、设计方案、工程约束、文件归属、docs/images/ 截图
└── workspace/                 # 你的学习数据（默认位置，可配置；也被 .gitignore 忽略）

Beyond the repo there is one more installation footprint: ~/.dsh/.agent-presets/learning/ (presets) and ~/.dsh/studymate-config.yaml (workspace locator), both written by the install script.

What the learning workspace looks like inside (subject folders, lessons, labs, profiles, course and exercise types, template and generator contracts) is documented in User Guide §Six.

FAQ

More questions (pitfalls of hand-editing YAML, why pointers can break after changing outline nodes, whether it can work offline) are in User Guide §Eight FAQ.

Contributing / License

• Project chat group (QQ): 161914370
• Changelog: CHANGELOG.md
• Documentation: User Guide (daily usage, course and exercise types, check and profile rules) · Lesson Content Format (syntax for content files and exercise locations) · File Ownership (alias ↔ path ↔ maintainer) · Design Proposal (product perspective) · Engineering Constraints (directory conventions, placeholder contracts, script overview, tech choices) · Template Guide · Front-end Asset Contract

Run These Before Proposing Changes

四条校验器各管一段（最后一行是回归套件），都是确定性的、带行号报错：

python3 scripts/check_skill.py .dsh/skills/*                                   # 提示词与技能：契约、单一 owner、措辞闸门
python3 scripts/check_curriculum.py <学习工作区>/.learning/subjects/<slug>/curriculum.yaml  # 大纲：schema、引用完整、无环、实验课要写 prerequisites
python3 scripts/check_lesson.py <课件.html> --subject <科目目录> --node <节点 id>   # 课件：版式、配图、题目、命名与上下节课指针
python3 scripts/check_pool.py <科目目录>                                        # 图片库：索引七列、图片存在、命名合规、单张 ≤500 KB
bash scripts/tests/run_tests.sh                                               # 回归：11 套快测（--browser 再加 2 套，共 13 套）

License

MIT (see LICENSE, copyright Cattofu).

Star Trend