Personal Tutor — Full-Cycle Learning Management / 全流程学习管理系统

Overview / 概述

Personal Tutor turns every learning session into structured, searchable, long-term knowledge. It handles three scenarios / 三个场景：

1. Start a new subject / 开启新学科 — create syllabus, learning log, config entries
2. Daily lesson / 每日上课 — review → teach → quiz → prompt to archive
3. Post-lesson archive / 课后归档 — update 6 layers: log, syllabus, memory, knowledge base, index, config

First-Run Onboarding / 首次设置引导

Before executing any workflow, check for a config file at:

{workspace}/.personal-tutor-config.json

If it does not exist, run the onboarding flow / 如不存在则运行引导流程：

Onboarding Flow / 引导问题

Ask the user these questions (one at a time, or all at once if they prefer)：

1. Learning root directory / 学习资料根目录 — Where should subject folders be stored?

   • Example: D:\Learning\ or ~/Documents/Learning/
   • This is where syllabus files and learning logs live.

2. Knowledge base tool / 知识库工具 — What do you use for long-term notes?

   • obsidian — wikilinks ([[link]]), vault-based
   • plain — standard Markdown, folder-based / 纯文件夹
   • notion — notes only (API integration not included)
   • none — skip concept archiving entirely / 跳过概念归档

3. Knowledge base path / 知识库路径 (if tool ≠ none) — Where is your vault/notes root?

   • Example: D:\Obsidian\MyVault\ or ~/Notes/

4. Archive depth / 归档深度 — How thorough should post-lesson archiving be?

   • light — update log + syllabus + memory only / 仅更新记录+大纲+记忆
   • full — light + extract concepts to knowledge base + refresh index / 完整归档含概念入库+索引刷新

5. Preferred language / 内容语言 — zh (Chinese), en (English), zh-en (bilingual / 中英双语), or auto (follow user's language)

6. Knowledge base schema / 知识库规则文件 (if tool = obsidian or plain) — Do you have a rules file that defines how concepts should be structured, named, and linked?

   • If yes, provide the path (e.g., D:\Notes\WIKI-SCHEMA.md). This file will be read before every concept extraction and its rules take priority over built-in defaults.
   • If no, the built-in Knowledge Base Rules (see section below) will be used.

Config File Schema / 配置文件结构

After onboarding, create:

{
  "version": "1.0",
  "learningRoot": "/path/to/learning/",
  "knowledgeBase": {
    "tool": "obsidian",
    "path": "/path/to/vault/",
    "schemaPath": "/path/to/WIKI-SCHEMA.md"
  },
  "archiveDepth": "full",
  "language": "auto",
  "subjects": {}
}

The subjects field will be populated as new subjects are added.

Scenario 1: Starting a New Subject / 场景一：开启新学科

Trigger / 触发条件

User says "start learning [subject name]" or "open a new subject: [name]"。 中文触发："开启[学科名]学习"、"新建学科[学科名]"。

Workflow / 工作流

1. Read config / 读取配置 — Load .personal-tutor-config.json to get learningRoot and preferences.

2. Detect category structure / 检测分类结构 — Scan {learningRoot}/ for existing subdirectories:

   • If subdirectories exist (e.g., 大学专业知识/, 职业发展/, Academic/, Professional/), they are treated as categories / 分类。Present them to the user and ask which one the new subject belongs to. If none fit, offer to create a new category.
   • If {learningRoot}/ is flat (no subdirectories), the subject goes directly under {learningRoot}/.
   • Store the chosen category in the subject's config entry as category.

3. Create subject directory / 创建学科目录 — Under {learningRoot}/{category}/ (or {learningRoot}/ if no category), create a folder named after the subject.

4. Create syllabus file / 创建教学大纲 — {learningRoot}/{category}/{subject}/syllabus.md

   • Content: subject overview, learning objectives, phased plan (by day/week), key topics per phase, estimated completion, expected outcomes.
   • If the user provides specific goals or a textbook, incorporate them.
   • Leave the first phase/day marked as ⏳ Pending / 待学.

5. Create learning log file / 创建学习记录 — {learningRoot}/{category}/{subject}/learning-log.md

   • Content: an empty tracking table with columns: Date | Content | Mastery | Issues | Next
   • Initial entry: today's date, "Subject initialized", N/A, "None", "Day 1 — start learning"

6. Update config / 更新配置 — Add to subjects:

   "subject-name": {
     "currentDay": 1,
     "category": "大学专业知识",
     "syllabusPath": "{learningRoot}/{category}/{subject}/syllabus.md",
     "logPath": "{learningRoot}/{category}/{subject}/learning-log.md",
     "status": "active",
     "startedAt": "YYYY-MM-DD"
   }
   

7. Update memory / 更新记忆 — If the agent has a memory system (MEMORY.md or equivalent), record the new subject there.

8. Create knowledge base folder / 创建知识库文件夹 (if archiveDepth = full and knowledgeBase.tool ≠ none) — Create an empty subject folder under {knowledgeBase.path}/ if it doesn't exist.

9. Report / 汇报 (output in configured language，按配置语言输出):

✅ New subject "[Subject Name]" is ready. / 新学科"[学科名]"已开启。

Created / 已创建：
  📋 Syllabus: {category}/{subject}/syllabus.md
  📝 Learning log: {category}/{subject}/learning-log.md
  ⚙️  Config updated / 配置已更新

You're all set for Day 1. Say "start learning [subject]" when ready.

Scenario 2: Daily Lesson / 场景二：每日上课

Trigger / 触发条件

User says "start learning [subject]" or "continue [subject]"。 中文触发："开始[学科名]学习"、"继续[学科名]学习"。

Workflow / 工作流

1. Read config / 读取配置 — Load current progress from .personal-tutor-config.json.

2. Read syllabus and log / 读取大纲与记录 — Load syllabus.md and learning-log.md to understand where we are.

3. Review previous lesson / 回顾上节课 — Briefly summarize the last session's core content (read from the learning log). Keep it under 3 bullet points.

4. Teach new content / 讲授新知 — Deliver the next topic(s) according to the syllabus. Follow these teaching principles:

   • Start with "why this matters" before "how it works" / 先讲"为什么重要"再讲"怎么运作"
   • Use concrete examples before abstract definitions / 用具体例子引导抽象定义
   • Break complex topics into digestible chunks / 把复杂话题拆成可消化的模块
   • Pause for questions between major sections / 大段落之间主动询问

5. Interactive check / 互动测验 (if applicable to the subject) — Ask 2-5 questions to verify understanding. Wait for user's answers, then give feedback and corrections.

6. Session notes / 课堂记录 — Mentally record: what was covered, what the user struggled with, what needs review.

7. Post-Lesson Self-Verification / 课后自查（强制执行） — Before telling the user the lesson is complete, run the Post-Lesson Self-Verification Protocol (see dedicated section below). If any layer is missing, fix it immediately. Do NOT say "lesson complete" / "学完了" / "done" until all layers pass.

8. End prompt / 课堂结束语 (only after self-verification passes, output in configured language):

📚 Today's lesson on [Subject] (Day [N]) is complete. / 今日课程完成。

Covered / 内容: [brief summary]
Mastery / 掌握: [assessment]
Issues / 问题: [any problems noted]

✅ Archive verified / 归档自检:
  📁 Learning records: updated
  🧠 Knowledge base: [N concepts created/updated, or "no changes"]
  ⚙️  Config: updated

Ready for Day [N+1]! / 准备好下一课了！

Scenario 3: Post-Lesson Archive / 场景三：课后归档

Trigger / 触发条件

User says "update learning records" or "archive today's learning"。 中文触发："更新学习记录"、"归档今天的学习"。

Workflow / 工作流

This is the most important scenario — it turns a conversation into permanent knowledge. 这是最关键的步骤——把对话变成永久知识。

Step 1: Update Learning Log / 更新学习记录

Append to the learning log (path from config):

## Day [N] — YYYY-MM-DD

**Content / 内容:** [summary of what was covered]
**Mastery / 掌握程度:** [good / okay / needs review]
**Quiz results / 测验成绩:** [scores & wrong answers if applicable]
**Issues / 遇到问题:** [concepts the user struggled with]
**Next / 下一步:** Day [N+1] — [next topic from syllabus]

Step 2: Update Syllabus Progress / 更新大纲进度

In syllabus.md, mark the current phase/day as ✅ Complete / 完成. If a milestone was reached, note it.

Step 3: Update Config / 更新配置

In .personal-tutor-config.json, update:

"subject-name": {
  "currentDay": N+1,
  ...
}

Step 4: Update Memory / 更新记忆

If the agent has a memory system, update it with the subject's new progress.

Step 5: Extract Concepts to Knowledge Base / 提取概念入库

Only if archiveDepth = full and knowledgeBase.tool ≠ none.

Follow the Knowledge Base Rules section below. If a custom schemaPath is configured, read that file first — its rules take priority over built-in defaults.

从当日课程提炼核心概念，严格按照下方「知识库规则」章节执行。如配置了自定义 schema 文件，先读取它——其规则覆盖内置默认。

If no new concepts were introduced: note this in the report / 如无新概念，在汇报中说明。

Step 6: Report / 汇报 (output in configured language)

✅ Learning records updated. / 学习记录已更新。

  📚 Subject: [Subject Name]
  📍 Progress: Day [N] → Day [N+1]
  🆕 New concepts: [list, or "none"]
  📁 Archived to: {path}
  🧠 Knowledge base: [updated / no changes]
  ⚙️  Config updated / 配置已更新

Post-Lesson Self-Verification Protocol / 课后自查协议（v1.0.1 新增）

🚨 THIS IS A RED LINE. DO NOT CROSS IT. 这是红线。不可越界。

Every agent that teaches a lesson via this skill MUST self-verify all three layers below before telling the user "lesson complete" ("学完了"/"done"/etc). If any layer is missing, you are NOT done. There is no exception. There is no "I'll do it later." Fix the gap now.

每个使用此 skill 教课的 agent，在告诉用户"学完了"之前，必须自检以下三层。少一层就不是"学完了"。没有例外。没有"待会补"。现在修。

After every lesson (whether triggered via Scenario 2 or via the agent's own workflow), the agent MUST self-verify the following three layers before declaring the session complete:

The Three-Layer Verification / 三层验证

Self-Check Mantra / 自查口诀

Before saying anything that means "done", mentally run this checklist:

1️⃣ D盘/Learning records → ✅ ?
2️⃣ Agent memory → ✅ ?
3️⃣ Knowledge base → ✅ ?
→ All three checked? NOW you can say "lesson complete."

When to skip Layer 3 / 何时可跳过第三层

Only skip knowledge base archiving if:

• archiveDepth is set to light (not full), OR
• knowledgeBase.tool is set to none, OR
• The lesson was pure review with zero new concepts introduced

In all other cases, Layer 3 is mandatory.

Failure Recovery / 故障恢复

If any verification fails:

1. Do NOT tell the user the lesson is complete — fix the gap first
2. If the gap cannot be fixed (e.g., missing path), report it to the user with a clear description
3. Record the failure in the learning log so the next session can catch up

If the user catches you skipping a layer (they will notice):

• Stop immediately. Do not argue. Do not defend.
• Fix the missing layer right there.
• Record this as a lesson learned — update your own rules (SOUL.md, TOOLS.md, etc.) to make it harder to skip next time.

Multi-Agent Guarantee / 多智能体保障

This protocol is designed for environments where different agents may handle different sessions. Each agent is independently responsible for completing all three layers. Do not assume a previous agent already did it — verify.

Knowledge Base Rules / 知识库规则（内置默认）

⚠️ If a custom schemaPath is configured, read that file before every concept extraction — its rules take priority over the defaults below. 如配置了自定义 schema 文件，每次提取概念前先读取它——其规则优先于以下默认。

When extracting concepts from a lesson, follow these rules strictly: 从课程提炼概念时，严格遵循以下规则：

1. One Concept = One File / 一个概念一个文件

• Each core concept gets its own .md file. Never bundle multiple concepts into one file.
• File name format: {NN}-{ConceptName}.md (e.g., 01-Derivative.md, 01-导数.md)
• Use a numbered prefix to maintain sort order within the folder.
• Place files in the appropriate subject folder under {knowledgeBase.path}/.

2. File Format / 文件格式

Every concept file must include:

---
aliases:
  - ConceptName
  - 别名1
  - 别名2
---

# ConceptName / 概念名

> One-line summary. 一句话概述。

## Core Content / 核心内容
...

## Related / 关联
- [[path/to/related-concept|Related Concept]] — relationship description

• YAML frontmatter with aliases — list synonyms and translations for searchability
• Output language follows the user's configured language setting
• If language = zh-en, output bilingual (Chinese + English)

3. Naming & Linking / 命名与链接

Obsidian (wikilink) mode:

• Use [[full/path/to/file|Display Name]] format — full path from vault root, pipe (|) without spaces
• Always reference the numbered filename (e.g., [[01-Derivative]], not [[Derivative]])
• Cross-discipline links: [[OtherFolder/SomeFile|Display]]

Plain Markdown mode:

• Use standard relative links: [Display Name](../folder/file.md)

Bidirectional linking / 双向链接:

• If A links to B, also add a backlink from B to A (create or update B's file)
• Tag cross-discipline links with type hints: 💡 方法借鉴 (method reference), 💡 思维模型类比 (mental model analogy)

4. Duplicate Detection / 去重检查

Before creating any new file, check for existing content:

1. Search for files with the same or similar name (including aliases in frontmatter)
2. If an exact match exists → add a wikilink to it, do NOT create a duplicate / 已存在则不新建，直接引用
3. If partial overlap → enrich the existing file with new content, do NOT create a duplicate / 部分重叠则补充已有文件
4. If contradictory content found → mark ⚠️ 待确认 and flag to the user / 发现矛盾则标记待确认

5. Index & Outline Updates / 索引与总纲更新

If the knowledge base has an index file (e.g., 00_概念索引.md) or subject outlines (e.g., XX-XXX总纲.md):

• Add new concepts to the index under the correct subject
• Update the subject outline to include new concept entries with correct wikilink paths
• Verify that outline links point to actual files on disk
• If the knowledge base has a link-checking script, run it after major updates

6. Post-Archive Verification / 归档后验证

After creating or modifying knowledge base files:

1. Verify all new wikilinks resolve to existing files
2. Check numbering consistency within the subject folder (no gaps or collisions)
3. Report any broken links or inconsistencies to the user

Configuration Reference / 配置参考

.personal-tutor-config.json

Directory Structure / 目录结构 (after setup)

{learningRoot}/
├── {Category/分类}/
│   ├── {Subject Name/学科名}/
│   │   ├── syllabus.md
│   │   └── learning-log.md
│   └── {Another Subject}/
│       ├── syllabus.md
│       └── learning-log.md
├── {Another Category}/
│   └── ...
└── ...

{knowledgeBase.path}/
├── {Subject Name}/
│   ├── 01-concept.md
│   ├── 02-concept.md
│   └── ...
└── (existing vault structure preserved / 现有结构保留)

Design Principles / 设计原则

1. Progressive disclosure / 渐进展开 — Lightweight onboarding, fully optional deep features
2. Tool-agnostic / 工具无关 — Works with Obsidian, plain folders, or no knowledge base at all
3. Conversation-first / 对话优先 — The lesson happens in chat; the skill handles the paperwork behind the scenes
4. Incremental / 增量式 — Each day builds on the last; the log and syllabus grow together
5. Non-destructive / 非破坏性 — Never overwrite existing knowledge base content; always check for duplicates first
6. Language-respecting / 语言自适应 — Follow the user's configured language for all generated content

Common Edge Cases / 常见边缘情况