tutor-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tutor Setup — Knowledge to Obsidian StudyVault

Tutor 配置指南 — 知识转换为Obsidian StudyVault

CWD Boundary Rule (ALL MODES)

CWD边界规则（所有模式通用）

NEVER access files outside the current working directory (CWD). All source scanning, reading, and vault output MUST stay within CWD and its subdirectories. If the user provides an external path, ask them to copy the files into CWD first.

严禁访问当前工作目录(CWD)以外的文件。 所有源文件扫描、读取和知识库输出必须限定在CWD及其子目录范围内。如果用户提供了外部路径，请让他们先将文件复制到CWD中。

Mode Detection

模式检测

On invocation, detect mode automatically:

Check for project markers in CWD:

package.json

pom.xml

build.gradle

Cargo.toml

go.mod

Makefile

*.sln

pyproject.toml

setup.py

Gemfile

If any marker found → Codebase Mode
If no marker found → Document Mode
Tie-break: If
```
.git/
```
is the sole indicator and no source code files (
```
*.ts
```
,
```
*.py
```
,
```
*.java
```
,
```
*.go
```
,
```
*.rs
```
, etc.) exist, default to Document Mode.
Announce detected mode and ask user to confirm or override.

调用时自动检测模式：

检查CWD中的项目标记：

package.json

pom.xml

build.gradle

Cargo.toml

go.mod

Makefile

*.sln

pyproject.toml

setup.py

Gemfile

如果检测到任意标记 → 代码库模式
如果未检测到任何标记 → 文档模式
平局判定规则：如果只有
```
.git/
```
一个标记，且不存在任何源代码文件（
```
*.ts
```
,
```
*.py
```
,
```
*.java
```
,
```
*.go
```
,
```
*.rs
```
等），默认使用文档模式。
告知用户检测到的模式，请用户确认或手动切换。

Document Mode

文档模式

Transforms knowledge sources (PDF, text, web, epub) into study notes. Templates: templates.md

将知识源（PDF、文本、网页、epub）转换为学习笔记。模板：templates.md

Phase D1: Source Discovery & Extraction

阶段D1：资源发现与提取

Auto-scan CWD for

**/*.pdf

**/*.txt

**/*.md

**/*.html

**/*.epub

(exclude

node_modules/

.git/

dist/

build/

StudyVault/

). Present for user confirmation.

Extract text (MANDATORY tools):
- PDF →
  pdftotext
  CLI ONLY (run via Bash tool). NEVER use the Read tool directly on PDF files — it renders pages as images and wastes 10-50x more tokens. Convert to
```
.txt
```
  first, then Read the
```
.txt
```
  file.
  bash
```
pdftotext "source.pdf" "/tmp/source.txt"
```
- If
```
pdftotext
```
  is not installed, install it first:
```
brew install poppler
```
  (macOS) or
```
apt-get install poppler-utils
```
  (Linux).
- URL → WebFetch
- Other formats (
```
.md
```
  ,
```
.txt
```
  ,
```
.html
```
  ) → Read directly.
Read extracted
.txt
files — understand scope, structure, depth. Work exclusively from the converted text, never from the raw PDF.
Source Content Mapping (MANDATORY for multi-file sources):
- Read cover page + TOC + 3+ sample pages from middle/end for EVERY source file
- NEVER assume content from filename — file numbering often ≠ chapter numbering
- Build verified mapping:
```
{ source_file → actual_topics → page_ranges }
```
- Flag non-academic files and missing sources
- Present mapping to user for verification before proceeding

自动扫描CWD中的
```
**/*.pdf
```
,
```
**/*.txt
```
,
```
**/*.md
```
,
```
**/*.html
```
,
```
**/*.epub
```
文件（排除
```
node_modules/
```
、
```
.git/
```
、
```
dist/
```
、
```
build/
```
、
```
StudyVault/
```
目录），提交给用户确认。
提取文本（必须使用指定工具）：
- PDF → 仅使用
  pdftotext
  CLI（通过Bash工具运行）。严禁直接对PDF文件使用读取工具——它会将页面渲染为图片，消耗10-50倍的token。请先转换为
```
.txt
```
  文件，再读取
```
.txt
```
  文件。
  bash
```
pdftotext "source.pdf" "/tmp/source.txt"
```
- 如果未安装
```
pdftotext
```
  ，请先安装：macOS执行
```
brew install poppler
```
  ，Linux执行
```
apt-get install poppler-utils
```
  。
- URL → 使用WebFetch工具
- 其他格式（
```
.md
```
  、
```
.txt
```
  、
```
.html
```
  ）→ 直接读取
读取提取后的
.txt
文件，理解内容范围、结构、深度。仅基于转换后的文本工作，绝对不要使用原始PDF。
资源内容映射（多文件资源必须执行）：
- 每个资源文件都要读取封面+目录+3页以上正文/末尾样例页
- 绝对不要通过文件名推测内容——文件编号通常不等于章节编号
- 构建经过验证的映射关系：
```
{ 源文件 → 实际主题 → 页码范围 }
```
- 标记非学术类文件和缺失的资源
- 在继续流程前，将映射关系提交给用户确认

Phase D2: Content Analysis

阶段D2：内容分析

Identify topic hierarchy — sections, chapters, domain divisions.
Separate concept content vs practice questions.
Map dependencies between topics.
Identify key patterns — comparisons, decision trees, formulas.
Full topic checklist (MANDATORY) — every topic/subtopic listed. Drives all subsequent phases.

Equal Depth Rule: Even a briefly mentioned subtopic MUST get a full dedicated note supplemented with textbook-level knowledge.

Classification completeness: When source enumerates categories ("3 types of X"), every member gets a dedicated note. Scan for: "types of", "N가지", "categories", "there are N".
Source-to-note cross-verification (MANDATORY): Record which source file(s) and page range(s) cover each topic. Flag untraceable topics as "source not available".

识别主题层级：章节、版块、领域划分。
区分概念内容和练习题。
梳理主题之间的依赖关系。
识别关键模式：对比、决策树、公式。
完整主题清单（必须执行）——列出所有主题/子主题，作为后续所有阶段的依据。

深度一致规则：即使是仅被简要提及的子主题，也必须生成独立完整的笔记，并补充教材级别的相关知识。

分类完整性：当源文件枚举类别时（如“X的3种类型”），每个分类都必须生成独立笔记。留意关键词：“types of”、“N种”、“categories”、“there are N”。
资源与笔记交叉验证（必须执行）：记录每个主题对应的源文件和页码范围，将无法追溯来源的主题标记为“无对应资源”。

Phase D3: Tag Standard

阶段D3：标签规范

Define tag vocabulary before creating notes:

Format: English, lowercase, kebab-case (e.g.,
```
#data-hazard
```
)
Hierarchy: top-level → domain → detail → technique → note-type
Registry: Only registered tags allowed. Detail tags co-attach parent domain tag.

创建笔记前先定义标签词表：

格式：英文、小写、短横线分隔（如：
```
#data-hazard
```
）
层级：顶级分类 → 领域 → 细节 → 技术 → 笔记类型
注册制：仅允许使用已注册的标签，细节标签必须同时关联所属父领域标签。

Phase D4: Vault Structure

阶段D4：知识库结构

Create

StudyVault/

with numbered folders per templates.md. Group 3-5 related concepts per file.

按照templates.md的要求创建带编号的

StudyVault/

目录，每个文件归组3-5个相关概念。

Phase D5: Dashboard Creation

阶段D5：控制面板创建

Create

00-Dashboard/

: MOC, Quick Reference, Exam Traps. See templates.md.

MOC: Topic Map + Practice Notes + Study Tools + Tag Index (with rules) + Weak Areas (with links) + Non-core Topic Policy
Quick Reference: every heading includes
```
→ [[Concept Note]]
```
link; all key formulas
Exam Traps: per-topic trap points in fold callouts, linked to concept notes

创建

00-Dashboard/

目录：包含MOC、速查手册、考点陷阱，详情参考templates.md。

MOC：主题地图+练习笔记+学习工具+标签索引（含规则）+薄弱知识点（带链接）+非核心主题处理规则
速查手册：每个标题都包含
```
→ [[概念笔记]]
```
链接，汇总所有核心公式
考点陷阱：分主题的陷阱点放在折叠标注中，关联到对应概念笔记

Phase D6: Concept Notes

阶段D6：概念笔记

Per templates.md. Key rules:

YAML frontmatter:
```
source_pdf
```
,
```
part
```
,
```
keywords
```
(MANDATORY)
source_pdf MUST match verified Phase D1 mapping — never guess from filename
If unavailable:
```
source_pdf: 원문 미보유
```

[[wiki-links]]

, callouts (

[!tip]

[!important]

[!warning]

), comparison tables > prose

ASCII diagrams for processes/flows/sequences
Simplification-with-exceptions: general statements must note edge cases

按照templates.md要求生成，核心规则：

YAML frontmatter必须包含
```
source_pdf
```
、
```
part
```
、
```
keywords
```
字段
source_pdf
必须匹配阶段D1验证后的映射关系——绝对不要通过文件名推测
如果没有对应源文件：
```
source_pdf: 无原文
```
优先使用
```
[[wiki-links]]
```
、标注（
```
[!tip]
```
、
```
[!important]
```
、
```
[!warning]
```
）、对比表格，而非大段文字
流程/数据流/时序内容使用ASCII图表
简化+例外说明：通用规则必须注明边缘情况

Phase D7: Practice Questions

阶段D7：练习题

Per templates.md. Key rules:

Every topic folder MUST have a practice file (8+ questions)
Active recall: answers use
```
> [!answer]- 정답 보기
```
fold callout
Patterns use
```
> [!hint]-
```
/
```
> [!summary]-
```
fold callouts
Question type diversity: ≥60% recall, ≥20% application, ≥2 analysis per file
```
## Related Concepts
```
with
```
[[wiki-links]]
```

按照templates.md要求生成，核心规则：

每个主题目录必须包含练习文件（不少于8道题）
主动回忆设计：答案使用
```
> [!answer]- 查看答案
```
折叠标注
解题规律使用
```
> [!hint]-
```
/
```
> [!summary]-
```
折叠标注
题型多样性：每个文件中记忆类题型≥60%、应用类≥20%、分析类≥20%
包含
```
## 相关概念
```
章节，附带
```
[[wiki-links]]
```
链接

Phase D8: Interlinking

阶段D8：关联链接

```
## Related Notes
```
on every concept note
MOC links to every concept + practice note
Cross-link concept ↔ practice; siblings reference each other
Quick Reference sections →
```
[[Concept Note]]
```
links
Weak Areas → relevant note + Exam Traps; Exam Traps → concept notes

每个概念笔记都添加
```
## 相关笔记
```
章节
MOC链接到所有概念和练习笔记
概念 ↔ 练习题双向链接；同级主题互相引用
速查手册对应章节 →
```
[[概念笔记]]
```
链接
薄弱知识点 → 对应笔记+考点陷阱；考点陷阱 → 概念笔记

Phase D9: Self-Review (MANDATORY)

阶段D9：自我审核（必须执行）

Verify against quality-checklist.md Document Mode section. Fix and re-verify until all checks pass.

对照quality-checklist.md的文档模式部分验证，修改后重新验证直到所有检查项通过。

Codebase Mode

代码库模式

Generates a new-developer onboarding StudyVault from a source code project. Full workflow: codebase-workflow.md Templates: codebase-templates.md

从源代码项目生成供新开发者入职使用的StudyVault。完整工作流：codebase-workflow.md 模板：codebase-templates.md

Phase Summary

阶段概览

Phase	Name	Key Action
C1	Project Exploration	Scan files, detect tech stack, read entry points, map directory layout
C2	Architecture Analysis	Identify patterns, trace request flow, map module boundaries and data flow
C3	Tag Standard	Define `#arch-` , `#module-` , `#pattern-` , `#api-` tag registry
C4	Vault Structure	Create `StudyVault/` with Dashboard, Architecture, per-module, DevOps, Exercises folders
C5	Dashboard	MOC (Module Map + API Surface + Getting Started + Onboarding Path) + Quick Reference
C6	Module Notes	Per-module notes: Purpose, Key Files, Public Interface, Internal Flow, Dependencies
C7	Onboarding Exercises	Code reading, configuration, debugging, extension exercises (5+ per major module)
C8	Interlinking	Cross-link modules, architecture ↔ implementations, exercises ↔ modules
C9	Self-Review	Verify against quality-checklist.md Codebase Mode section

See codebase-workflow.md for detailed per-phase instructions.

阶段	名称	核心动作
C1	项目探索	扫描文件、检测技术栈、读取入口文件、梳理目录结构
C2	架构分析	识别设计模式、追踪请求流程、梳理模块边界和数据流
C3	标签规范	定义 `#arch-` 、 `#module-` 、 `#pattern-` 、 `#api-` 标签注册表
C4	知识库结构	创建 `StudyVault/` 目录，包含控制面板、架构、各模块、DevOps、练习题文件夹
C5	控制面板	MOC（模块地图+API暴露面+快速入门+入职路径）+速查手册
C6	模块笔记	每个模块的笔记包含：用途、核心文件、对外接口、内部流程、依赖
C7	入职练习题	代码阅读、配置、调试、扩展类练习（每个主模块不少于5道题）
C8	关联链接	模块之间双向链接、架构 ↔ 实现双向链接、练习题 ↔ 对应模块双向链接
C9	自我审核	对照quality-checklist.md的代码库模式部分验证

查看codebase-workflow.md获取各阶段详细说明。

Language

语言规则

Match source material language (Korean → Korean notes, etc.)
Tags/keywords: ALWAYS English

匹配源材料的语言（韩语→韩语笔记等）
标签/关键词：始终使用英文