tutor-setup

Tutor 设置 — 知识转化为 Obsidian StudyVault

CWD 边界规则（所有模式）

绝不访问当前工作目录（CWD）以外的文件。 所有源文件扫描、读取和知识库输出都必须位于 CWD 及其子目录中。 如果用户提供外部路径，请先让他们将文件复制到 CWD。

模式检测

调用时，自动检测模式：

1. 检查 CWD 中的项目标记：
   • package.json、pom.xml、build.gradle、Cargo.toml、go.mod、Makefile、 *.sln、pyproject.toml、setup.py、Gemfile
2. 如果找到任何标记 → 代码库模式
3. 如果未找到标记 → 文档模式
4. 平局处理：如果 .git/ 是唯一的标记，且不存在源代码文件（*.ts、*.py、*.java、*.go、*.rs 等），则默认使用文档模式。
5. 宣布检测到的模式，并请用户确认或更改。

---

文档模式

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

阶段 D1：来源发现与提取

1. 自动扫描 CWD 中的 **/*.pdf、**/*.txt、**/*.md、**/*.html、**/*.epub（排除 node_modules/、.git/、dist/、build/、StudyVault/）。请用户确认。
2. 提取文本（必须使用指定工具）：
   • PDF → 仅使用 pdftotext CLI（通过 Bash 工具运行）。绝不直接使用 Read 工具读取 PDF 文件——它会将页面渲染为图片，浪费 10-50 倍令牌。先转换为 .txt，然后读取 .txt 文件。

     pdftotext "source.pdf" "/tmp/source.txt"
     

   • 如果尚未安装 pdftotext，请先安装：macOS 上运行 brew install poppler，Linux 上运行 apt-get install poppler-utils。
   • URL → WebFetch
   • 其他格式（.md、.txt、.html）→ 直接读取。
3. 读取提取出的 .txt 文件——了解范围、结构和深度。只能使用转换后的文本，不得读取原始 PDF。
4. 来源内容映射（多文件来源时必须执行）：
   • 每个来源文件都要读取封面页 + 目录 + 至少 3 页中间或末尾的样本页
   • 绝不根据文件名推测内容——文件编号通常不等于章节编号
   • 建立经核实的映射：{ source_file → actual_topics → page_ranges }
   • 标记非学术文件和缺失来源
   • 继续之前向用户展示映射并请其核实

阶段 D2：内容分析

1. 确定主题层级——章节、篇章、领域划分。
2. 区分概念内容与练习题。
3. 梳理主题间的依赖关系。
4. 确定关键模式——比较、决策树、公式。
5. 完整主题清单（必须执行）——列出所有主题和子主题，并用于驱动后续所有阶段。

深度均等规则：即使只是简要提及的子主题，也必须单独建立完整笔记，并补充教科书级知识。

6. 分类完整性：当来源列出类别（如“X 的 3 种类型”）时，每个类别成员都必须有单独的笔记。扫描以下表述：“types of”、“N가지”、“categories”、“there are N”。
7. 来源与笔记交叉核验（必须执行）：记录每个主题对应的来源文件和页码范围。无法追溯的主题标记为“source not available”。

阶段 D3：标签标准

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

• 格式：英文、小写、kebab-case（例如 #data-hazard）
• 层级：顶层 → 领域 → 细节 → 技法 → 笔记类型
• 注册表：只允许使用已注册的标签。细节标签必须同时附加其上级领域标签。

阶段 D4：知识库结构

按照 templates.md 创建 StudyVault/，并建立带编号的文件夹。每个文件归纳 3-5 个相关概念。

阶段 D5：创建仪表板

创建 00-Dashboard/：MOC、快速参考、考试陷阱。请参阅 templates.md。

• MOC：主题地图 + 练习笔记 + 学习工具 + 标签索引（含规则）+ 薄弱领域（含链接）+ 非核心主题策略
• 快速参考：每个标题都包含 → [[Concept Note]] 链接；列出所有关键公式
• 考试陷阱：按主题整理陷阱要点，放入可折叠提示框，并链接到概念笔记

阶段 D6：概念笔记

遵循 templates.md。关键规则：

• YAML 前置元数据：source_pdf、part、keywords（必填）
• source_pdf 必须与经验证的阶段 D1 映射一致——绝不可根据文件名猜测
• 如果不可用：source_pdf: 원문 미보유
• 使用 [[wiki-links]]、提示框（[!tip]、[!important]、[!warning]），优先使用对比表而非散文
• 使用 ASCII 图表示流程、流转和顺序
• 简化时说明例外：一般性陈述必须注明边缘情况

阶段 D7：练习题

遵循 templates.md。关键规则：

• 每个主题文件夹都必须有一个练习文件（至少 8 道题）
• 主动回忆：答案使用 > [!answer]- 정답 보기 可折叠提示框
• 规律使用 > [!hint]- / > [!summary]- 可折叠提示框
• 题型多样性：每个文件中，回忆题占比 ≥60%，应用题占比 ≥20%，分析题至少 2 道
• 使用 ## Related Concepts，并包含 [[wiki-links]]

阶段 D8：建立相互链接

1. 每篇概念笔记都添加 ## Related Notes
2. MOC 链接到每篇概念笔记和练习笔记
3. 概念笔记与练习笔记互相链接；同级笔记互相引用
4. 快速参考中的各个部分 → [[Concept Note]] 链接
5. 薄弱领域 → 相关笔记 + 考试陷阱；考试陷阱 → 概念笔记

阶段 D9：自我审查（必填）

根据 quality-checklist.md 的 Document Mode 部分进行核验。修复问题并重新核验，直到所有检查均通过。

---

代码库模式

根据源代码项目生成面向新开发者的入门 StudyVault。 完整工作流：codebase-workflow.md 模板：codebase-templates.md

阶段摘要

阶段	名称	关键操作
C1	项目探索	扫描文件、检测技术栈、阅读入口点、梳理目录布局
C2	架构分析	识别模式、追踪请求流、梳理模块边界和数据流
C3	标签标准	定义 #arch-*、#module-*、#pattern-*、#api-* 标签注册表
C4	知识库结构	创建 StudyVault/，包含仪表板、架构、各模块、DevOps 和练习文件夹
C5	仪表板	MOC（模块地图 + API 概览 + 入门指南 + 入职路径）+ 快速参考
C6	模块笔记	各模块笔记：用途、关键文件、公共接口、内部流程、依赖项
C7	入门练习	代码阅读、配置、调试、扩展练习（每个主要模块至少 5 项）
C8	建立相互链接	交叉链接模块、架构 ↔ 实现、练习 ↔ 模块
C9	自我审查	根据 quality-checklist.md 的 Codebase Mode 部分进行核验

各阶段的详细说明请参阅 codebase-workflow.md。

---

语言

• 与源材料的语言保持一致（韩语 → 韩语笔记等）
• 标签/关键词：始终使用英语