dsh-mastery-loop 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0
+
+首个版本。
+
+**两个 skill**：
+
+- **`mastery-loop`** —— 复习闭环。模型可自动调用，也可手动 `/mastery-loop`。
+- **`mastery-loop-setup`** —— 一次性初始化。**纯手动**（`disable-model-invocation`），只响应 `/mastery-loop-setup`。
+
+**内容**：
+
+- 出题 → 批改 → 再出题，直到逐点达标（`总共出过 ≥ 5` 且 `熟练程度 ≥ 目标正确率`）
+- **每题必须写思维链**；批改**先判思维链、再判答案**；**蒙对不算对**
+- 错误原因**逐字复用**、按知识点分组、追加日期 → 可统计
+- 错误原因写法**借用 ASD-STE100 原则**（≤20 词、一句一个偏移、动词开头）
+- 初始化生成 **6 个根目录文件**，并可用 `scripts/validate.mjs` **机械校验**
+- 不做间隔重复排程（SM-2 那套）—— 那该由日历与考试表决定

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noct2vis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# mastery-loop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A general exam-revision loop for DeepSeek Harness.** It reads your course materials and your notes vault, then drills you — question, grade, question again — until **every knowledge point** reaches your target accuracy, and finally hands you a pre-exam list.
+
+Two things make it different from a quiz bot:
+
+- **Every question requires you to write your reasoning, not just your answer.** Grading checks the reasoning first, then the answer. **A lucky guess does not count as correct.**
+- **Wrong-answer reasons are stored verbatim and reused.** So a mistake you make three times is counted three times, instead of splitting into three near-synonyms and vanishing from the statistics.
+
+通用应试复习闭环：读你的课程材料与笔记库 → 出题 → 批改 → 再出题，直到每个知识点的熟练度都达到目标正确率，最后产出考前 list。**每道题都要求你写出思维链**，批改先判思维链再判答案，**蒙对不算对**。
+
+---
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-mastery-loop
+```
+
+## 用法：两步
+
+### 1 · 先初始化（只跑一次）
+
+```
+/mastery-loop-setup
+```
+
+它会探测你的课程材料与笔记库，问清路径 / 素材 / 语言 / 融合方式 / 卷子格式，然后在你**知识库根目录**生成 6 个文件并校验：
+
+| 文件 | 作用 |
+| --- | --- |
+| `ledger.md` | 复习账本（进度 + 已初始化的凭据） |
+| `index.md` | 主题 → 知识点的反向索引 |
+| `errors.md` | 错误原因表 |
+| `paper-format.md` | 每个课程的每个考试的卷子格式 |
+| `error-taxonomy.md` | 失分原因分类（**初始为空**，等归纳） |
+| `config.md` | 路径 / 每门课的素材选择 / 语言标准 |
+
+> 初始化**有意做成独立的 skill**：它要问六组问题，跟日常复习是两件事。分开之后 `mastery-loop` 本身短得多。
+
+### 2 · 之后正常复习
+
+```
+/mastery-loop
+```
+
+或者直接用自然语言说「我想开始复习了」—— 这个 skill **模型可以自动调用**。
+
+## 复习循环长什么样
+
+```
+读状态 → 与用户逐步确认（范围 / 目标正确率 / 是否混合考）
+   → 复习清单
+   → 出题（每题后面挂「答案：」「思维链：」两行）
+   → 批改（先判思维链 → 再判答案 → 错了才提炼错误原因）
+   → 写回账本与错误原因表
+   → 达标？→ 问是否继续
+   → 考前 list（从第一轮就开始攒，不是最后生成）
+```
+
+**达标是逐点判断的**：一个知识点要「**总共出过 ≥ 5** 且 **熟练程度 ≥ 目标正确率**」。不到 5 次标「样本不足」，继续出题。
+
+## 错误原因为什么写成英文
+
+`errors.md` 里的错误原因**默认用英文** —— 因为要套 **ASD-STE100（简化技术英语）** 的写法：一句一个偏移、不超过 20 词、动词开头、不写题号和数字。
+
+这样做的目的是**可统计**：同名错误必须逐字一致，才能数出「我在这一点上错了几次」。
+
+> ⚠️ 口径说明：本 skill **借用 ASD-STE100 的原则**，**不声称符合** ASD-STE100 —— 官方明说它不适用于一般写作。
+> 另外，「同一表述必须逐字复用」是本 skill 的**跨文档外推**（STE 只要求「一篇文档内一致」）。**这个外推的责任在本 skill，不在 ASD。**
+
+## 一次只复习一门课吗
+
+**建议**。但范围由你定 —— 跨多门时 skill 会问你是否要**跨课程混合出题**（**默认不混合**）。
+
+## 语言
+
+**按产物类别分别定**（知识点笔记 / 出的题 / 批改解析 / 记录性文件 / 产出 / 机制层），在初始化时问你。想要中英双语对照、法文、或纯中文都行 —— 除了 `errors.md` 的错误原因默认英文（要套 STE）。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# Opt-in mastery-loop filesystem Skill provider for DeepSeek Harness.
+# Resolves the packaged Skill root from the installed npm identity anchored at
+# the DSH profile (Loader baseUrl), never as a path concatenated onto baseUrl.
+- insert:
+    - id: mastery-loop-skill-filesystem
+      name: '@deepseek-ai/dsh-skill-filesystem'
+      config:
+        providerName: mastery-loop
+        includeDefaultRoots: false
+        bundledSkillDir: !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dsh-mastery-loop/package.json')), 'skills')

package/lib/index.js

@@ -0,0 +1,9 @@
+// dsh-mastery-loop carries no runtime code of its own.
+//
+// The bundle works entirely through cordis.patch.yml, which inserts the
+// official `@deepseek-ai/dsh-skill-filesystem` provider and points
+// `bundledSkillDir` at this package's `skills/` directory. Keeping the skill
+// content declarative is deliberate: there is no provider to maintain, no
+// discovery logic to get wrong, and nothing to break when DSH changes.
+
+export {};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "dsh-mastery-loop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Opt-in DeepSeek Harness skill bundle: mastery-loop — an exam-revision loop that drills until every knowledge point reaches your target accuracy. / 通用应试复习闭环。",
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "agent-skill",
+    "study",
+    "revision",
+    "exam",
+    "mastery"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Noct2vis/dsh-mastery-loop.git"
+  },
+  "homepage": "https://github.com/Noct2vis/dsh-mastery-loop#readme",
+  "bugs": "https://github.com/Noct2vis/dsh-mastery-loop/issues",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "sync": "node scripts/sync-dev.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/mastery-loop/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: mastery-loop
+description: >-
+  通用应试复习闭环 / A general exam-revision loop：读你的课程材料与笔记库 → 出题 → 批改 → 再出题，直到每个知识点的熟练度都达到目标正确率，最后产出考前 list。
+  每道题都要求你写出思维链，批改先判思维链再判答案，蒙对不算对。错误原因逐字复用、可统计。
+  Use when the user wants to start revising or review for a course ("我想开始复习", "复习某门课", "考前突击", "start revising", "review for my exam"), or mentions review progress, mistakes, weak spots, mastery, or knowledge points.
+---
+
+# mastery-loop —— 复习闭环
+
+出题 → 批改 → 再出题，直到**每个知识点的熟练度都达到目标正确率**，最后收成**考前 list**。
+
+---
+
+## 0 · 三条硬规矩
+
+1. **不主动扫库。** 初始化之后只在三种情况下才动知识库：① 读到**不符合要求**的文件 → 处理那**一个**；② 出现**新文件** → 处理；③ **用户主动调用** → 才做。
+2. **笔记的定义部分不动。** 只写那几个记录文件（`ledger.md` / `errors.md` / `index.md` / `paper-format.md`），以及 MOC 的「知识点清单」。**知识点正文与 frontmatter 不碰。**
+3. **不声称符合 ASD-STE100。** 错误原因**尽可能按 STE 的规则写**，这是借用它的原则，不是合规声明。
+
+---
+
+## 1 · 入口
+
+### 1.1 先确认初始化过
+
+读 `config.md` → 找**知识库根目录** → 读 `ledger.md`。
+
+- **`ledger.md` 不存在，或顶部没有「首次对齐」标记行** → **停下来**，告诉用户：
+
+  > 这个知识库还没初始化过。先跑一次 `/mastery-loop-setup`，它会把 6 个文件建好，之后我再开工。
+
+  **不要自己进初始化流程** —— 那件事归 `mastery-loop-setup`。
+
+- 初始化过 → 继续。
+
+### 1.2 读状态
+
+顺序固定：
+
+```
+config.md（路径 + 每门课的成员选择 + 语言标准）
+   → ledger.md（进度；标记行已确认）
+   → paper-format.md（本次考试的格式）
+```
+
+然后**把读到的状态摆出来**：
+
+- **一段话**：「你上次复习到 X，本次范围内 Y 个知识点，已达标 Z 个。」
+- **一张小表**：本次范围的知识点按熟练度排序，标出「样本不足」和 `NULL` 的。
+
+### 1.3 与用户确认 —— **用提问窗口，逐步问**
+
+⚠️ **不许把问题堆成一条消息。** 拉起**交互式提问窗口**，**一次一问**：
+
+1. **状态确认** ——「我查到你复习到这一步，对吗？」
+2. **本次范围** ——（建议一次一门课，但**范围由用户定**）
+3. **本次目标正确率** ——（推荐 90%）
+4. **是否跨课程混合考** —— **仅当范围跨多门时**才问（**默认不混合**）
+
+---
+
+## 2 · 环境勘察
+
+**顺序：问 → 读 → 确认匹配度。**
+
+1. **问**：这次要读什么 / 你手上有哪些。**先问，不扫盘猜。**
+2. **读**：按用户指的去读，**不预设文件类型**（别写死 `.pdf`）。
+3. **确认匹配度**：把结论摆出来，逐条说清 —— 哪些**匹配**、为什么；哪些**不匹配**、为什么；还**缺**什么、**去哪找**。
+   - **要写出具体后果**（「判分会偏松」，不是「缺少答案」）；**不必把文件列全**；判定标准只有一条：**两个类别都有着落**。
+   - 问一句：**「有没有你不想让我读的？」**
+4. **缺默认成员时**问用户是否用类里别的成员顶（**换成员必须问**）。**某一类整类为空**才是真缺必需项。
+
+> 每门课的**第一讲**（`W1L1 Introduction to the Unit` / `Unit organisation` 这类）通常就是**考试边界的来源** —— 哪些考、哪些不考。
+
+---
+
+## 3 · 复习循环
+
+### 3.1 先给复习清单
+
+按 `ledger.md` 排：**熟练度低的在前**，`NULL`（没学过）和「样本不足」标出来。
+
+### 3.2 出题
+
+**卷子参数从 `paper-format.md` 查**对应考试的那一条 —— **不要从往年卷现抄**。
+查不到 → 用**默认出卷法：判断题 + 每题说明理由**。
+
+配比（按本次范围的题池算，不按课程切分）：
+
+| 占比 | 打什么 |
+| --- | --- |
+| 60% | 熟练度最低的点 |
+| 30% | `是否学习过 = 否` 的点 |
+| 10% | `最后复习日期` 最久远的点（防遗忘） |
+
+卷子模板 → [templates.md](templates.md#试卷模板)。
+
+### 3.3 每题后面必须挂两行
+
+**不分题型，思维链是必写的。** 每道题后面就是这两行，别的都不要：
+
+```
+答案：
+思维链：
+```
+
+- **选题也要写** —— 有足够的推导过程即可，**不强制把所有选项都写出来**。
+- 用户不写思维链 → 那一题**无法判定**，记「**未判**」、**不入账本**，并**提示他补写**。
+
+### 3.4 批改 —— 顺序不能反
+
+```
+① 先确认思维链的逻辑对不对
+② 再确认答案对不对
+③ 只要错的个数 ≥ 1  →  才去提炼并规范化错误原因
+```
+
+- **做对 = 思维链对 且 答案对。** 任一不对 = 错 —— **蒙对不算对**。
+- 两样都错 = **错 2 个** → 很可能要提炼出**两条**错误原因（复合错误要拆）。
+- 两个都对 → 不走第 ③ 步。
+
+**批改产出三块**：
+
+1. **评分表** —— 逐题「你的判断 vs 正确答案」+ 得分 + 失分点 + 总分与正确率
+2. **详细解析** —— 引用材料原文逻辑；计算题给完整中间步骤
+3. **薄弱点定位** —— 说清**为什么错**（从思维链里看），别笼统说「理解不到位」
+
+判分口径 → [templates.md](templates.md#判分口径)。
+
+### 3.5 提炼错误原因（只在错 ≥1 时）
+
+写法**按 ASD-STE100 的规则**（**英文**）：
+
+- 句式优先 **`把 A 当成 B`**（概念混淆类，**必须写出 A 和 B**）；其余用 **`<动作> + <对象>`**
+- **一句只写一个偏移** —— 出现 `and / but / because / so / then` 就是两个命题，拆开
+- **≤20 词**；**名词短语 ≤3 词**
+- **不写**题号、数字、时间词、第一人称、情绪词
+- **动词开头**且**必须带对象**（禁 `wrong`、`didn't know`）
+- **指代不悬空**
+
+然后**去 `errors.md` 里查**：
+
+1. **在该知识点分组内全量检索**
+2. 有**逐字一样**的 → **只追加日期**，**绝不重新措辞**
+3. 没有 → 新增一条
+
+### 3.6 写回文件
+
+- **`ledger.md`** —— 更新 `做对` / `总共出过` / `熟练程度` / `最后复习日期` / `是否学习过`。
+  （`做对` 只在**思维链对且答案对**时 +1。）
+- **`errors.md`** —— 按上面的规则追加日期或新增条目（**先按知识点分组，再按错误原因分组**）。
+- **`index.md`** —— 有变动时**先改索引**。
+- **MOC 清单** —— 再从索引刷新受影响 MOC 的「## 知识点清单」。**永不反向。**
+
+### 3.7 达标与继续
+
+**达标是逐点判断的**（不是单轮卷面分）：
+
+```
+一个知识点达标  ⇔  总共出过 ≥ 5  且  熟练程度 ≥ 本次目标正确率
+```
+
+`总共出过 < 5` → 标「**样本不足**」：继续出题，**不算达标、也不算失败**。
+
+- 本次范围内**所有**知识点都达标 → **用提问窗口问**用户是否继续
+- 继续 → 回到 3.2
+- 不继续 → 进第 4 节
+
+### 3.8 考前 list 是**攒出来的**，不是最后生成的
+
+**从第一轮批改就开始攒。** 每轮出错，就把该点的 `规则 / ⚠️ 常见错误 / 🔑 锚` 三行补进去 —— 出错的那一刻正是信息最鲜活的时候。到复习结束时，它**已经**是成品。
+
+模板 → [templates.md](templates.md#考前-list)。
+
+---
+
+## 4 · 产出：考前 list
+
+**独立成文**（一篇笔记，与那 6 个文件并列）。**只收出过错的点**，按知识点一条，三行结构：
+
+```
+### <知识点>
+> **规则**：<正确说法>
+> ⚠️ **常见错误**：<我实际犯的错>
+> 🔑 **锚**：<一句话记忆钩子 / 反例>
+```
+
+末尾附「**考前 15 分钟速查**」：最致命的 N 条，一行一条。
+
+---
+
+## 固定参考
+
+[templates.md](templates.md) —— 试卷模板、判分口径、考前 list 模板。**按需查，别通读。**
+
+## 版本与口径
+
+- 错误原因的写法**借用 ASD-STE100 的原则**，**不声称符合 ASD-STE100**。
+- **「同一表述复用」是本 skill 的外推**：STE 只要求「一篇文档内一致」，这里放大成「跨全库、跨时间的去重键」—— **这个外推的责任在本 skill，不在 ASD**。

package/skills/mastery-loop/scripts/validate.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// mastery-loop 初始化校验
+//
+// 用法：node validate.mjs <知识库根目录>
+//
+// 判据（票 18 M4）：知识库根目录下 6 个固定文件名都在 = 初始化完成。
+// 硬要求：**永远不要崩溃** —— 干净目录上应当报「6 个全缺」并以退出码 1 结束。
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const FILES = [
+  { name: 'ledger.md', label: '复习账本', required: true },
+  { name: 'index.md', label: '反向索引', required: true },
+  { name: 'errors.md', label: '错误原因表', required: true },
+  { name: 'paper-format.md', label: '卷子格式', required: true },
+  { name: 'error-taxonomy.md', label: '失分原因分类', required: true },
+  { name: 'config.md', label: '配置', required: true },
+];
+
+function readIfPossible(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** 每个文件一点结构检查；返回问题列表（空 = 通过） */
+function inspect(name, text) {
+  const problems = [];
+  if (text === null) return problems;
+
+  if (name === 'ledger.md') {
+    if (!/首次对齐/.test(text)) problems.push('缺少「首次对齐」标记行 —— 初始化未完成');
+    if (!/\|\s*知识点\s*\|/.test(text)) problems.push('缺少账本表头（`知识点 / 是否学习过 / …`）');
+  }
+
+  if (name === 'index.md') {
+    if (!/^#\s/m.test(text)) problems.push('缺少 H1 标题');
+  }
+
+  if (name === 'errors.md') {
+    if (!/^#\s/m.test(text)) problems.push('缺少 H1 标题');
+  }
+
+  if (name === 'paper-format.md') {
+    const courses = (text.match(/^##\s+(?!没有往年卷)/gm) || []).length;
+    if (courses === 0) problems.push('还没有任何课程条目（每个课程的每个考试各一条）');
+  }
+
+  if (name === 'config.md') {
+    if (!/材料根目录/.test(text)) problems.push('缺少「材料根目录」');
+    if (!/知识库根目录/.test(text)) problems.push('缺少「知识库根目录」');
+    if (/<绝对路径>/.test(text)) problems.push('路径还是占位符，没填');
+  }
+
+  // error-taxonomy.md 初始为空是对的 —— 不检查内容
+
+  return problems;
+}
+
+function main() {
+  const arg = process.argv[2];
+  if (!arg) {
+    console.log('用法：node validate.mjs <知识库根目录>');
+    process.exit(2);
+  }
+
+  const root = resolve(arg);
+  console.log('校验知识库根目录：' + root);
+
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.log('❌ 这个目录不存在，或不是目录。');
+    process.exit(1);
+  }
+
+  let missing = 0;
+  let problematic = 0;
+
+  for (const f of FILES) {
+    const path = join(root, f.name);
+    let text = null;
+
+    if (!existsSync(path)) {
+      console.log(`❌ ${f.name}  —— 缺失（${f.label}）`);
+      missing++;
+      continue;
+    }
+
+    text = readIfPossible(path);
+    if (text === null) {
+      console.log(`❌ ${f.name}  —— 存在但读不了`);
+      problematic++;
+      continue;
+    }
+
+    const problems = inspect(f.name, text);
+    if (problems.length === 0) {
+      console.log(`✅ ${f.name}  —— ${f.label}`);
+    } else {
+      console.log(`⚠️  ${f.name}  —— ${f.label}`);
+      for (const p of problems) console.log(`      · ${p}`);
+      problematic++;
+    }
+  }
+
+  console.log('');
+  if (missing === 0 && problematic === 0) {
+    console.log('✅ 初始化已完成：6 个文件都在。');
+    process.exit(0);
+  }
+
+  console.log(`未完成：缺 ${missing} 个、有问题的 ${problematic} 个。`);
+  console.log('跑一遍 `mastery-loop-setup` 补齐。');
+  process.exit(1);
+}
+
+try {
+  main();
+} catch (err) {
+  // 无论如何都不要崩
+  console.log('❌ 校验脚本自身出错：' + (err && err.message ? err.message : String(err)));
+  process.exit(1);
+}

package/skills/mastery-loop/templates.md

@@ -0,0 +1,107 @@
+# 固定参考（Fixed Reference）
+
+[`SKILL.md`](SKILL.md) 的模板与口径。**按需查，别通读。**
+
+---
+
+## 试卷模板
+
+> ⚠️ **参数从 `paper-format.md` 查**对应考试的那一条 —— **不要从往年卷现抄**。
+> 查不到 → 用**默认出卷法：判断题 + 每题说明理由**。
+
+```markdown
+# PRACTICE EXAM PAPER — ROUND N
+
+**Based on**: <paper-format.md 里的考试名>
+**Time Allowed**: <抄自 paper-format.md>
+**Total Marks**: <抄自 paper-format.md>
+
+---
+
+## Question 1 (<marks> marks)
+
+<题干>
+
+(a) <小问> (<marks> marks)
+(b) ...
+
+答案：
+思维链：
+
+## Question 2 (<marks> marks)
+
+...
+
+答案：
+思维链：
+
+**END OF PAPER**
+```
+
+硬性要求：
+
+- **Round N** 每轮递增；**跨轮保持同一套卷子参数**，这样正确率才可比。
+- **每道题后面必须挂 `答案：` / `思维链：` 两行** —— 选择题也要。
+- 判断正误类小题，题干里就写明「**先判对错，再给理由**」。
+- 分值分配**照 `paper-format.md`**，不要自己发明比例。
+- 卷尾之后**不得**出现任何答案、提示、「解析见下」的字样。
+
+---
+
+## 判分口径
+
+| 题型 | 给分 | 扣分 / 零分 |
+| --- | --- | --- |
+| 判断正误 | 分类正确 + 解释命中关键词 | 只写 T/F 没解释 → 0；解释不引材料逻辑 → 减半 |
+| 计算 | 结果正确 + 中间步骤齐全 | 结果对但无 working → 扣步骤分；结果错但步骤对 → 给步骤分 |
+| 定义 | 关键词出现 + 给出具体示例 | 只背课本句式、无示例 → 不满分 |
+| 画图 / 证明 | 图元齐全（轴标签、方向、边界）/ 每步有依据 | 图对但无标注 → 扣分 |
+
+**总分与正确率按卷面原始分算**，不折算、不向上取整。
+
+### ⚠️ 与「做对」的区别
+
+- **判分**用的是上面这张表（看答案）。
+- **账本里的「做对」是另一回事**：必须 **思维链对 且 答案对**。
+  **蒙对**在评分表里可能得分，但在账本里**不算做对** —— 而且**要提炼一条错误原因**。
+
+批改纪律：
+
+- **给分严格，只认关键词。** 别给「思路对了」这种虚分。
+- 判错要**指到用户具体的句子**（在思维链里找），不要笼统说「理解不到位」。
+- 也要指出**答得好**的部分 —— 避免用户误以为整块都薄弱。
+
+---
+
+## 考前 list
+
+**独立成文**，与知识库根目录那 6 个文件并列。**只收出过错的点**，按知识点一条。
+
+**从第一轮批改就开始攒** —— 每轮出错就把三行补进去，别等最后生成。
+
+```markdown
+# 考前 list
+
+## Section A: <主题>
+
+### <知识点>
+> **规则**：<正确说法>
+> ⚠️ **常见错误**：<我实际犯的错 —— 与 errors.md 里的错误原因一致>
+> 🔑 **锚**：<一句话记忆钩子 / 反例>
+
+### <知识点>
+...
+
+## Section B: <主题>
+...
+
+## ⏱️ 考前 15 分钟速查
+- <最致命的 N 条，一行一条>
+```
+
+要求：
+
+- 一个知识点**只占三行**，超过说明还没提炼干净。
+- **`⚠️ 常见错误` 必须与 `errors.md` 里的错误原因逐字一致** —— 那是同一份事实，不要换措辞。
+- 锚点优先用**反例**或**极端情形**，不要口诀式废话。
+- 涵盖**全部轮次**，不重复同一意思的条目。

package/skills/mastery-loop-setup/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: mastery-loop-setup
+description: 一次性初始化 mastery-loop：探测课程材料与笔记库，问清路径 / 素材 / 语言 / 融合方式 / 卷子格式，在知识库根目录生成 6 个文件并校验。首次使用 mastery-loop 之前手动跑一次。 / One-time setup for mastery-loop: explore materials and the notes vault, ask about paths, sources, language, merging and exam format, then scaffold the 6 root files.
+disable-model-invocation: true
+---
+
+# mastery-loop 初始化
+
+给 `mastery-loop` 铺好它假设的那套配置。**只跑一次**，之后 `mastery-loop` 直接用你建好的东西。
+
+**产出的 6 个文件**（**全部落在知识库根目录**，文件名固定）：
+
+| 文件名 | 作用 |
+| --- | --- |
+| `ledger.md` | 复习账本（进度 + 「首次对齐已完成」凭据） |
+| `index.md` | 主题 → 知识点的反向索引（可重建缓存） |
+| `errors.md` | 错误原因表（真值） |
+| `paper-format.md` | 每个课程的每个考试的卷子格式 |
+| `error-taxonomy.md` | 失分原因分类（**初始为空**） |
+| `config.md` | 路径 + 每门课的成员选择 + 语言标准 |
+
+> 这是**prompt-driven skill，不是确定性脚本**。探索、把发现摆出来、问、确认，然后才写。
+
+---
+
+## 0 · 硬规矩
+
+- **材料目录只读。** 不修改、不移动、不重命名用户给的任何课程材料。
+- **只写这 6 个文件**（+ 刷新 MOC 清单，如果库里有 MOC）。**不动知识点笔记的定义部分**。
+- **写之前先给草稿让用户过目**（第 6 步）。
+- **不含任何真实路径进 skill 包** —— 真实路径只写进用户的 `config.md`。
+
+---
+
+## 1 · Explore（先看，别假设）
+
+- **材料**：用户给的课程目录下有什么？**先列实际目录，不要拿一份固定清单去套** —— 各课结构不同，有的课压根没有往年卷。
+- **笔记库**：有没有已存在的知识库？有没有 `MOC/`、`知识点/`？frontmatter 有哪些字段？
+- **是否已经初始化过**：`ledger.md` 在不在？**在的话先停下问用户**「要重新初始化，还是只补缺的」。
+- **git**：知识库是 git 仓库吗？（只影响要不要提醒用户 `config.md` 含真实路径）
+
+## 2 · 素材：两个类别
+
+**必需的只有两个类别**，不是两个确定的文件：
+
+| 类别 | 用来 | **默认成员** | 类里其他合格成员 |
+| --- | --- | --- | --- |
+| **建库参考** | 建知识库 | **课程讲义** | 教学大纲 / `exam_topics` / 课件 / 教科书章节 |
+| **出题参考** | 出题与判分 | **往年试卷** | 往年卷答案 / Lab sheet / Worksheet / Assessment 结构 |
+
+**判定分两级**：
+
+1. **某一类整类为空** → 真·缺必需项，告诉用户缺什么、去哪找
+2. **类里有内容、但没有默认成员** → **不算缺**，只需问一句「用类里另一样顶吗」
+
+**换成员必须问，不能默认。** 用户定了之后**记进 `config.md`**，之后不再问。
+
+> 同时问一句：**「有没有你不想让我读的？」**
+
+## 3 · 语言标准
+
+**按 6 个产物类别分别问**（用户可以用自然语言回答，比如「全都中英双语对照」）：
+
+1. 知识点笔记（正文 / 标题 / `aliases` / MOC / 索引）
+2. 出的题（题干 / 选项）
+3. 批改与解析
+4. 记录性文件（`ledger.md` 等）
+5. 产出（复习清单 / 考前 list）
+6. 机制层（frontmatter 字段名 / `config.md`）
+
+> ⚠️ **例外**：`errors.md` 里的**错误原因默认用英文** —— 它要套 ASD-STE100 的规则，不该跟着别的类别走。
+> 📌 **不要预设双语。** 有人要法文、有人只要中文，问出来。
+
+## 4 · 融合（用户已有知识库时）
+
+**目标不是把用户的库改成我们的样子，而是融合。改什么都要问。**
+
+- **缺 MOC** → 问用户：「按目录/章节能聚出 N 个主题，**要我替你建 MOC 吗**？」**不建是合法选项**（没有 MOC 时，`index.md` 自己就是那份清单）。
+- **字段冲突** → **并存 + 映射**，不要轻易改名（改名会打烂用户已有的查询/模板/Dataview）。有 `章节:` 就保留它，另加 `主题:`，值从它映射过来。
+- **`主题` 推不出来**（压根没有讲次/章节概念）→ **先推一版草案**（按目录结构或笔记命名规律聚类），摆给用户改。**别直接问「你的主题是什么」** —— 那问题用户答不上来。
+- **不动笔记正文**。新字段是**加**上去的。
+
+## 5 · 卷子格式
+
+**每个课程的每个考试各一条**（期中 / 期末 / in-class / coursework 形状不同，必须分开）。
+
+从材料里抄：时间 / 总分 / 题数 / 题型 / 分值分布，并**记住来源**（抄自哪份文件）。
+
+**没有往年卷时**：先问用户该怎么办。
+用户没有更好的主意 → 用**默认出卷法 = 判断题 + 每题说明理由**，并在该条目里写明「无往年卷 → 用默认出卷法」。
+
+## 6 · Confirm and edit
+
+**把 6 个文件的草稿摆给用户过目**，让他改。然后再写。
+
+草稿内容由本 skill 目录下的**种子模板**填充：
+
+- [ledger.md](./seeds/ledger.md) —— 账本
+- [index.md](./seeds/index.md) —— 索引
+- [errors.md](./seeds/errors.md) —— 错误原因表
+- [paper-format.md](./seeds/paper-format.md) —— 卷子格式
+- [error-taxonomy.md](./seeds/error-taxonomy.md) —— 失分原因分类（**保持为空**）
+- [config.md](./seeds/config.md) —— 配置
+
+**填充要点**：
+
+- `ledger.md`：先铺**全部知识点**，`是否学习过 = 否`、`做对/总共出过 = —`、`熟练程度 = NULL`；**顶部的「首次对齐」标记行写上日期与迁移篇数**
+- `index.md`：按 `主题` 字段反向生成（已经算出主题的那些）
+- `errors.md`：只写结构，**初始没有条目**
+- `paper-format.md`：第 5 步收来的每条考试一格
+- `error-taxonomy.md`：**保持空**
+- `config.md`：路径、每门课的成员选择、语言标准填满
+
+## 7 · Write
+
+写进**知识库根目录**，用**上面那 6 个固定文件名**。
+
+若有 MOC：**先写 `index.md`，再从索引刷新各 MOC 的「## 知识点清单」** —— **永不反向**。
+
+## 8 · 校验
+
+跑校验脚本，确认 6 个文件真的建好了：
+
+```bash
+node scripts/validate.mjs <知识库根目录>
+```
+
+**6 个文件都在 = 初始化完成。** 缺哪个就补哪个，别靠感觉。
+
+## 9 · Done
+
+告诉用户：初始化完了，`mastery-loop` 之后会读这些文件；想改直接编 `config.md` 那几个文件；**只有要换素材来源或从头再来时才需要重跑本 skill**。

package/skills/mastery-loop-setup/seeds/config.md

@@ -0,0 +1,34 @@
+# mastery-loop 配置
+
+> 由 `mastery-loop-setup` 在**首次初始化**时写入。
+> 之后 `mastery-loop` **有变动时读** —— 路径按需直接读，读不到就问；**成员选择与语言标准定下就不再问**。
+
+## 1 · 路径
+
+- **材料根目录**：<绝对路径>
+- **知识库根目录**：<绝对路径>
+
+> 🔒 本文件含本机真实路径。**要不要提交进 git，你自己决定** —— 发布出去的 skill 包里不含任何真实路径。
+
+## 2 · 每门课的类别成员选择
+
+只有**没有默认成员**时才需要问（默认成员：建库参考 = **讲义**，出题参考 = **往年试卷**）。
+
+| 课程 | 建库参考 | 出题参考 |
+| --- | --- | --- |
+| <课程名> | <讲义 / 教学大纲 / 课件 / 教科书章节> | <往年试卷 / 答案 / Lab sheet / Worksheet / Assessment 结构> |
+
+## 3 · 语言标准
+
+**按产物的 6 个类别分别定。** 用户可以用自然语言回答（「全都中英双语对照」这种也算）。
+
+| 类别 | 含什么 | 标准 |
+| --- | --- | --- |
+| **1 知识点笔记** | 正文 / 标题 / `aliases` / MOC / 索引 | |
+| **2 出的题** | 题干 / 选项 | |
+| **3 批改与解析** | 给分表 / 解析 / 薄弱点定位 | |
+| **4 记录性文件** | `ledger.md` / `errors.md` / `paper-format.md` / `error-taxonomy.md` | |
+| **5 产出** | 复习清单 / 考前 list | |
+| **6 机制层** | frontmatter 字段名 / 本配置文件 | |
+
+> ⚠️ **`errors.md` 里的错误原因例外**：它**默认用英文**，因为要套 ASD-STE100 的规则。

package/skills/mastery-loop-setup/seeds/error-taxonomy.md

@@ -0,0 +1,17 @@
+# 失分原因分类
+
+> ⚠️ **这里不预设类别 —— 初始就是空的，这是对的。**
+>
+> `errors.md` 里那些**固定表述的错误原因本身**就是统计单位。
+> 等某个知识点的错误原因多到看不完（默认 **> 60 条**）再回来**归纳**，把类别写在这里。
+
+## 归纳出来的类别写在这下面
+
+<!--
+格式建议（等真的归纳时再用）：
+
+## <类别名>
+- 含义：
+- 涵盖哪些错误原因：
+- 对应的补射方向：
+-->

package/skills/mastery-loop-setup/seeds/errors.md

@@ -0,0 +1,48 @@
+# 错误原因表
+
+> ⚠️ **本文件由 `mastery-loop` 维护。**
+> 是**真值**（错误历史只在这里），**删掉无法重建**。
+
+## 两条铁律
+
+1. **表述必须逐字一致才能被统计。** 同一个偏移犯三次，三次必须命中**同一条**。
+   新增前先**在该知识点分组内全量检索**：语义相同 → **复用原句、只追加日期**，**不许重新措辞**。
+2. **复合错误要拆分。** 一次作答里错了思维链又错了答案 → **两条**。
+
+## 写法（错误原因用英文）
+
+按 **ASD-STE100** 的规则写（`mastery-loop` 声称的是「尽可能按 STE 规则写」，**不是**「符合 ASD-STE100」）：
+
+- 句式优先 **`把 A 当成 B`**（概念混淆类）；其余用 **`<动作> + <对象>`**
+- **一句只写一个偏移** —— 出现 `and / but / because / so / then` 就是两个命题，必须拆
+- **不超过 20 词**（Rule 5.1）；**名词短语不超过 3 词**（Rule 2.1）
+- **不写**：题号、具体数字、时间词（`today / last time`）、第一人称、情绪词（`careless`）
+- **动词开头**，且**必须带对象**（禁 `wrong`、`didn't know` 这种空动词）
+- **指代不悬空** —— `it / this / the former` 必须在同一行找得到所指
+- **「概念混淆」必须写出 A 和 B** —— 只写 `concept confusion` 等于没写
+
+## 结构（**先按知识点分组，再按错误原因分组**）
+
+```markdown
+# 错误原因表
+
+## [[核技巧]]
+
+### forgot to normalise before comparing
+- 2026-10-09
+- 2026-10-11
+
+### treated explicit inner product as the kernel value
+- 2026-10-11
+
+## [[梯度]]
+
+### took steepest ascent for steepest descent
+- 2026-10-09
+```
+
+## 维护规则
+
+- **去重键 = 知识点 + 错误原因** → 同一句话在两个知识点上**各自成条**
+- 重复出现 → **只在该条目下追加日期**，不新增条目
+- **单个知识点上限 60 条**；超了就该回头归纳，把类别写进 `error-taxonomy.md`

package/skills/mastery-loop-setup/seeds/index.md

@@ -0,0 +1,25 @@
+# 索引 —— 主题 → 知识点
+
+> ✅ **本文件是派生缓存，删了可以重建**（真值在每篇知识点的 `主题` 字段里）。
+> 它存在是为了**不必扫全库**。
+
+## 更新顺序（写死，不许反向）
+
+```
+① 先改这里（索引）
+② 再从索引刷新受影响 MOC 的「## 知识点清单」
+③ 永不反向 —— 绝不因为有人手改了 MOC 清单就回写索引
+```
+
+派生链共三级：`主题` 字段（真值）→ **索引**（本文件，对 MOC 而言是真值）→ **MOC 清单**（索引的复制）
+
+## 内容
+
+每个主题一节，列出属于它的知识点：
+
+## [[<主题名（MOC）>]]
+
+- [[<知识点>]]
+- [[<知识点>]]
+
+> 📌 **如果这个知识库没有 MOC**，本文件就是那份清单本身 —— 第 ② 步自然消失。

package/skills/mastery-loop-setup/seeds/ledger.md

@@ -0,0 +1,26 @@
+# 复习账本
+
+> ⚠️ **本文件由 `mastery-loop` 维护。** 除了顶部的标记行和手工订正，日常不要手改。
+> 它是**真值**（做题统计只在这里），**删掉无法重建** —— 与索引不同。
+
+> 首次对齐：<YYYY-MM-DD> 完成 · schema v1 · 迁移 <N> 篇
+
+| 知识点 | 是否学习过 | 做对 | 总共出过 | 熟练程度 | 最后复习日期 |
+| --- | --- | --- | --- | --- | --- |
+| [[<知识点>]] | 否 | — | — | NULL | — |
+| [[<知识点>]] | 是 | 3 | 5 | 60% | <YYYY-MM-DD> |
+
+## 列的含义
+
+- **知识点** —— `[[wikilink]]`，纯名字，不带路径、不带 `.md`
+- **是否学习过** —— 是 / 否（`否` 时后面几列都是 `—` / `NULL`）
+- **做对** —— 次数。**判定口径**：思维链对 **且** 答案对，才记「做对」（**蒙对不算**）
+- **总共出过** —— 次数
+- **熟练程度** —— `做对 / 总共出过`，百分比展示；**没学过的写 `NULL`**（不是 0%）
+- **最后复习日期** —— 用于 ① 复习清单排序 ② 10%「已掌握点」挑最久没碰的
+
+## 达标规则（供回看）
+
+- 单个知识点**达标** = `总共出过 ≥ 5` **且** `熟练程度 ≥ 本次目标正确率`
+- `总共出过 < 5` → 标「**样本不足**」，继续出题，**不算达标、也不算失败**
+- 达标是**逐点**判断的，不是单轮卷面分

package/skills/mastery-loop-setup/seeds/paper-format.md

@@ -0,0 +1,30 @@
+# 卷子格式
+
+> ⚠️ **生成卷子时从这里查对应考试的那一条** —— `mastery-loop` **不再每轮从往年卷现抄参数**。
+> 由 `mastery-loop-setup` 在首次初始化时生成；**有变动时读**。
+
+## 结构：**每个课程的每个考试各一条**
+
+（期中 / 期末 / in-class / coursework 形状不同，必须分开）
+
+## <课程名>
+
+### <考试名>
+
+- **时间**：<分钟>
+- **总分**：<分>
+- **题数**：<题>
+- **题型**：<判断 / 定义 / 计算 / 画图 / 证明 / 简答…>
+- **分值分布**：<…>
+- **来源**：<抄自哪份往年卷；或「**无往年卷 → 用默认出卷法**」>
+
+### <考试名>
+
+…
+
+## 没有往年卷时：默认出卷法
+
+**判断题 + 每题说明理由。**
+（这也正好接上思维链要求 —— 「说出为什么」就是思维链。）
+
+> 📌 优先**问用户**该怎么办；用户没有更好的主意时，用上面这个默认。