dsh-project-based-learning 1.1.0

package/docs/ENGINE-REVISION-2.zh.md

@@ -0,0 +1,487 @@
+# 引擎修订 2（教学缺陷修复）——改动设计与审核记录
+
+状态：**三轮独立审核全部完成、发现已逐条处置、修订 2.1 已实现并自测通过**（§7–§10）。发布状态见 [`releasing.zh.md`](releasing.zh.md)。
+
+## 0. 背景：三条真实缺陷
+
+来自一位真实使用者的使用反馈（非推测）：
+
+1. **只问不教**：即使明确说明"我不了解这方面的知识"，引擎也不进行详细讲解；
+2. **过度严格**：明显可以通过阅读代码/文档判定的问题，仍坚持要求实测；
+3. **该教的却让人自己悟**：可以直接讲授的知识，被安排成需要自行领悟的实测。
+
+### 0.1 真实对话证据
+
+使用者被问到的第一道题（`diagnosis-bank.md` Q1-1，生命周期顺序预测）：
+
+> 下面脚本挂在一个初始未启用的 GameObject 上……请回答：从 `SetActive(true)` 那一刻起，Console 里按什么顺序出现这些字母、每个字母出现几次……之后又 `SetActive(false)` 会发生什么。
+
+使用者答对之后，引擎仍要求"实测确认（实验台我已写好）"；使用者实测并说明已完成之后，引擎**再次**要求实测。
+
+### 0.2 条款级根因（已逐条核对原文）
+
+| 缺陷 | 责任条款 | 机制 |
+|---|---|---|
+| ①③ | `SKILL.md:23` R1 先做后教；`:24` R2 不得跳到第 5 级；`task-loop.md:15`「已在第 1 级时不再降级，改为缩小任务或回补前置知识」；`adapt.md:9`「概念未理解 → 回到最小示例」 | **引擎里没有"讲授"这个动作**。受阻路径的终点全是"缩任务／最小示例／回补前置"，没有一条是"把这个知识讲清楚"；"最小示例"仍要求学员自己看出来 |
+| ③ | `SKILL.md` 主循环第 2 步即**诊断**（讲授只出现在第 5 步任务循环）；`intake.md:36`「自述一律先记为 `待验证`」 | 零基础学员的**第一次接触**就是测试 |
+| ② | `state.md` 不变量 6（`artifact` 必须指向可核对材料）＋`review-acceptance.md:43-45`（可复现）＋`SKILL.md:25` R3（自述不是证据） | `diagnosis.md:41` 明文承认"有用户回答"即为 `已验证`，但落盘要求"材料"，而允许的材料类型全是文件行号/日志/截图/复现步骤，**没有"问答记录"**；"可复现"本是阶段验收判据，被越界用于单个知识结论 |
+| ② | `SKILL.md:25` R3 措辞「用户自述只是线索」 | 立法本意是防"我熟练"这类**能力**自夸，却被无差别用于"我刚跑过一次，输出是 X"这类**操作**陈述 → 学员照做了仍不被承认 |
+
+### 0.3 更深一层的前提错误
+
+引擎把**一切学习**都建模为"脚手架下的自我发现"。学习至少分两类：
+
+- **技能**（写代码、排错、设计、拆解）→ "先做后教 + 分级提示"是合适的；
+- **知识**（API 名称与签名、调用顺序、语言规则、术语、文档已明的默认值）→ **适合直接讲授**，让学员自己悟是低效且有打击性的。
+
+引擎只实现了前者，并把后者硬塞进前者。**该前提继承自原始工作流文档**，第 1–2 轮审核按"原文默认保留"原则未予质疑，因此本修订属于**对原文的实质改动**，必须重新过六项检验。
+
+## 1. 改动清单（逐条给出精确替换）
+
+### F1 新增"讲授"动作（R9）
+
+**现状**：无此规则；一切学习都走脚手架。
+
+**改为**（`SKILL.md` 常驻规则新增 R9）：
+
+```md
+- **R9 讲授（知识类不做自我发现）**：出现下列任一情形时**直接讲授**，不进入脚手架：
+  1. 学员明说自己没学过、不了解该内容；
+  2. 诊断或练习显示必要前置知识缺失；
+  3. 内容属于**事实性知识**：API 名称与签名、调用与执行顺序、语言与类型规则、术语定义、文档已明确的默认值。
+  讲授结构固定：**概念 → 为什么当前任务需要 → 最小示例 → 一道确认题**（确认题不是实测，见 R10）。
+  讲授只覆盖当前目标所需范围，超出部分记入 `strategy.deferred`；讲完必须出确认题。
+  **技能类内容（写代码、排错、设计、拆解）仍按 R1／R2 先做后教**，本条不适用。
+```
+
+### F2 区分两类自述（改 `intake.md:36`）
+
+**现状**：`自述一律先记为 状态: 待验证，由诊断或后续证据升级。不得因用户自称"熟练"就直接跳过诊断。`
+
+**改为**：
+
+```md
+自述分两类处理：
+- **能力自述**（"我熟练／我会"）：先记为 `待验证`，由诊断或后续证据升级；不得仅凭自称跳过诊断。
+- **缺口自述**（"我没学过 X／我不了解 Y"）：**直接采信**，立即转入 R9 讲授，不得先考一遍。
+  （采信缺口自述只决定"讲不讲"，不改变后续要求：仍需确认题，技能类仍需亲手做。）
+```
+
+### F3 证据分层（改 `diagnosis.md`、`review-acceptance.md`、`state.md`）
+
+**现状**：三态定义在 `diagnosis.md:41-43`（"有用户回答、成果、运行结果或测试支持"即可 `已验证`），但落盘要求材料；`review-acceptance.md:43-45` 的"可复现+可解释+可修改"未声明适用范围。
+
+**改为**：
+
+1. `review-acceptance.md` 增加**适用范围声明**：三条件**只用于阶段验收**；单个知识结论与单题诊断不适用。
+2. 新增**证据分层表**（同时写进 `diagnosis.md` 与 `review-acceptance.md`）：
+
+| 结论类型 | 判为 `已验证` 的条件 | `artifact` 可以是什么 |
+|---|---|---|
+| **知识类**（事实、机制、术语、顺序、规则） | 同类 2–3 题正确，或同题加难追问也正确；**单题正确只算 `部分验证`** | 问答记录（题目编号 + 学员原话摘录） |
+| **行为类**（代码、功能、排错、设计取舍） | 运行结果、测试或断言支持 | 文件与行号、日志片段、截图位置、可复现步骤 |
+
+3. `state.md` 的 `artifact` 允许类型显式加入"问答记录（题目编号＋学员原话摘录）"，并注明知识类结论可用它。
+
+### F4 操作自述可作证据（改 `SKILL.md:25` R3）
+
+**现状**：`- **R3 证据判定**：用户自述只是线索。每项能力标 **已验证 / 部分验证 / 待验证**；无证据不得标"已验证"。`
+
+**改为**：
+
+```md
+- **R3 证据判定**：三类自述区别对待——
+  - **能力自述**（"我熟练"）：只是线索，不得直接标"已验证"；
+  - **缺口自述**（"我没学过"）：直接采信，转入 R9（见 `intake.md`）；
+  - **操作自述**（"我跑了一次，输出是 X"／"我按你说的改了"）：在没有反证时按**部分验证**接受，**不得要求重复实测**；
+  每项能力标 **已验证 / 部分验证 / 待验证**；无证据不得标"已验证"。
+```
+
+### F5 实测最小化（新增 R10）
+
+```md
+- **R10 实测最小化**：只有同时满足"结论依赖运行时行为"与"静态阅读代码或文档无法判定"时才要求实测。
+  以下情形**不需要实测**，直接由代码或文档判定：API 名称与签名、生命周期与调用顺序、语法与类型规则、
+  文档已明确的默认值、可从代码直接读出的分支逻辑。
+  **每次要求实测前，必须先用一句话说明"为什么这一点无法从代码或文档判定"**；说不出理由就不得要求实测。
+```
+
+### F6 题库门槛与类型标签（改领域包）
+
+- 每题新增两个字段：`类型`（事实性／推理性／综合）与 `前置知识`（无／基础／已学 X）；
+- 规则：**事实性题不得作为首次接触题**；`前置知识` 未满足的题不得使用；
+- `diagnosis-bank.md` 的 Q1-1 移入"讲授后确认题"分组，题面前补讲授要点（生命周期调用顺序与次数规则）；
+- `manifest.yml` 的 `sections` 不变，字段约定写进 `domain-contract.md`。
+
+### F7 防过度矫正（约束本次修复自身）
+
+```md
+- 讲授不得变成整章讲课：只讲当前任务所需，连续讲授不超过 2 个知识点，超出则先让学员动手；
+- 讲完必须出确认题；确认题答错则**换一种表征重讲**，不是重复同一段；
+- 技能类任务（写代码、排错、设计、拆解）**不得**因 R9 改为讲授；
+- 讲授不得取代"学员亲手做"：写代码类成果仍须学员本人完成并运行。
+```
+
+### F8 把 F3 机械化（状态契约 1.0 → 1.1）
+
+**动机**：本次事故的教训是"散文规则会被误用"。F3 若只写在散文里，同样会漂移。
+
+- `evidence[]` 新增必填字段 `kind`：`知识类` | `行为类`；
+- 校验器新增不变量：
+  - `kind=知识类` 且 `strength=已验证` ⇒ 该结论引用的知识类证据 **≥2 条**（拦住"问一次就发已验证"）；
+  - `kind=行为类` 且 `strength=已验证` ⇒ 其 `artifact` **不得**是问答记录型（必须指向运行结果/材料）；
+  - `kind` 缺失或非法 ⇒ 报错；
+- `schemaVersion` 升为 `1.1`；`examples/` 两个夹具、`assets/state.template.json`、`coach-selftest.mjs` 断言、`state.md` 字段表同步更新。
+
+> 本条是本次改动中最容易被质疑为**过度设计**的一条，请在审核中重点攻击（见 §3 反方 B）。
+
+## 2. 六项检验（逐条裁定，审核者请逐条挑战）
+
+| 编号 | A 必要性 | B 最小性 | C 反方（最强反驳） | D 回归 | E 可验证 | F 复审 |
+|---|---|---|---|---|---|---|
+| F1 | 成立：零基础学员第一次接触即被考，且引擎无讲授动作 | 新增一条常驻规则，不改循环结构 | 「会把教练变回讲师」→ 缓解：三条明确触发条件 + F7 上限 + 确认题 | 与 R1/R2 的边界已写明（技能类不适用） | 触发条件可核对（学员原话／题干类型） | 待第 2 轮 |
+| F2 | 成立：两类自述被同一条规则误伤 | 仅改 `intake.md` 一段 | 「学员谎称没学过以逃避练习」→ 采信只影响"讲不讲"，确认题与技能类亲手做不变 | 与 R3 一致 | 可直接引用学员原话核对 | 待第 2 轮 |
+| F3 | 成立：条款互相打架（回答算证据 vs 必须有材料） | 加适用范围声明 + 分层表，不改三态定义本身 | 「削弱'无证据不得标已验证'这一核心卖点」→ 行为类标准**未降**；知识类改用同类多题，artifact 仍须可核对 | 与 R4、验收三档一致 | F8 机械化 | 待第 2 轮 |
+| F4 | 成立：学员实测后仍被要求再测 | 改 R3 一句话为三类分述 | 「会接受编造的操作自述」→ 仍标注为"部分验证"，且在有反证（日志矛盾、无法复现）时降级 | 与 F3 分层一致 | 可核对（是否出现重复实测要求） | 待第 2 轮 |
+| F5 | 成立：实测被用于读文档即可判定的事项 | 新增一条规则，无结构性改动 | 「模型会滥用'不需要实测'来偷懒」→ 要求每次实测前**给出理由**，把判断显式化；行为类成果仍须运行 | 与 R10/R3 一致 | 理由是否给出可核对 | 待第 2 轮 |
+| F6 | 成立：Q1-1 作为首次接触题不合适 | 仅加两个字段 + 一题归位 | 「增加题库维护成本」→ 一次性，14 题 | 领域包契约需更新 | **人工核对**（校验器不解析题库——第 1 轮审核指出此处原写"校验器可强制字段存在"属过度声明，已改） | 待第 2 轮 |
+| F7 | 成立：无此约束则修复本身会制造新失败 | 四条"不得"，无新增流程 | 「约束过多会僵化」→ 均为可核对的硬边界 | 与 R1/R2 兼容 | 可核对 | 待第 2 轮 |
+| F8 | 部分成立：散文规则确有漂移史；但机械化有成本 | 一个必填枚举 + 两条不变量 | **最强反驳见 §3-B** | 触及 schema、夹具、自测、文档，回归面最大 | 自测 + 反向夹具 | 待第 2 轮 |
+
+## 3. 反方论证专章（审核者应重点攻击这两点）
+
+**A. 「R9/R10 会把教练变回讲师，正是原始文档要防的失败模式。」**
+回应：R9 的触发是**可判定的三类情形**，而非模型自选；F7 设了连续讲授上限与确认题；技能类明示不适用。若审核认为仍不足以防止"逢题就讲"，请给出更小的替代方案（例如仅在"缺口自述"时允许讲授，取消"事实性知识"这一自动触发）。
+
+**B. 「F8 是过度设计：为一条散文规则引入 schema 变更、夹具改动与自测改动，成本高于收益。」**
+回应：本次事故的根因正是"散文规则被误用"，而机械校验是唯一能在无人复核时拦住复发的手段。但请审核者判断：
+- `kind` 必填是否会给正常使用带来明显摩擦？
+- 「知识类 ≥2 条证据」的阈值是否合理（1 太松、3 是否过严）？
+- 是否存在**更小**的机械化方案（例如只加"知识类结论不得要求实测"的 warn，而不改 schema）？
+
+## 4. 验证计划
+
+1. **现有四件套复跑**：`test/entry.smoke.mjs`、`coach-selftest.mjs`、`coach-validate.mjs`（正向/反向夹具）、`dsh-plugin-dev check`；
+2. **新增零基础路径回归清单**（`docs/zero-knowledge-path.zh.md`，人工可核对）：
+   - 学员说"没学过"→ 必须出现讲授，不得先出题；
+   - 知识类结论 → 不得要求实测；要求实测时必须给出"为什么无法从代码/文档判定"的理由；
+   - 学员说明已实测 → 不得重复要求实测；
+   - 技能类任务 → 仍须学员亲手写并运行。
+3. **机械化部分**（F8）：反向夹具中加入 `kind` 缺失、知识类单证据却标 `已验证`、行为类用问答记录当证据三种违规，自测断言必须命中；
+4. 全部通过后，由第 2 轮审核复核实现，再做全局复核。
+
+## 5. 未决问题（需使用者决定，审核者可提替代值）
+
+- F3 的力度：本设计取"**单题正确 → 部分验证；同类 2–3 题正确 → 已验证**"。若认为仍偏松/偏严，请给出阈值。
+- F8 的 `kind` 是否必填：默认**必填**（摩擦换防漂移）；替代方案是"选填 + 缺失时按行为类从严"。
+
+## 6. 审核记录
+
+### 第 1 轮（设计审核）——已完成，三份独立报告
+
+| 审核者 | 视角 | 报告存档 | F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 |
+|---|---|---|---|---|---|---|---|---|---|---|
+| A | 教育学与学习者体验 | `docs/review-round1-A-edu.zh.md` | 需修改 | 需修改 | 需修改 | 需修改 | 需修改 | 需修改 | 需修改 | **应驳回** |
+| B | 工程实现与规则契约 | `docs/review-round1-B-eng.zh.md` | 需修改 | 需修改 | 需修改 | 需修改 | 需修改 | 需修改 | **成立** | 需修改（推迟） |
+| C | 有界审核（F1／F8 两问） | `docs/review-round1-C-bounded.zh.md` | 需修改 | — | — | — | — | — | — | 过度设计 |
+
+**证据等级最高的一条（A 提供）**：一份真实在学状态里，若干条已记为「已验证／部分验证」的证据，其 `artifact` 本来就是「用户消息中的作答原文」；另有一条的 note 写着「尚未附实测截图，实测后升级为已验证」——**这正是"证据落盘把讲授逼回实测"的现场证据**，同一状态目录下还留有教练自建实验台的记录。
+
+### 第 2 轮（实现审核）
+待实现完成后进行。
+
+### 全局复核
+待前两轮完成后进行。
+
+---
+
+## 7. 修订 2.1（依第 1 轮三份独立审核）
+
+> 本节**取代 §1 的对应条目**（§1 保留为原始提案，便于对照审核意见）。凡本节与 §1 冲突，以本节为准。
+
+### 7.1 裁定汇总
+
+- **F8 按现规格驳回**（三份审核一致或趋同）：A 判"应驳回"，C 判"过度设计"，B 判"需修改（推迟）"并给出更小替代。
+- **F1、F3、F4、F5、F6 需结构性补丁**（不是措辞微调）：漏改的文件会导致规则在同一触发上给出不同终点，或与必读文件正面矛盾。
+- **F2、F7 方向成立但需改造**：F2 需回应既有裁定 R2-W01 并允许一句层级确认；F7 需把不可判定的"2 个知识点"换成可判定单元。
+- **三份审核共同确认的两处现状描述**：`task-loop.md:32-38` 是既有讲授槽位（故 §0.2「没有讲授动作」已更正）；`diagnosis.md:29-35` 确无讲授分支。
+
+### 7.2 修订后的改动清单
+
+#### F1′ 讲授（重写）
+
+**必须同步的**六处**（缺一处即出现"同一触发、不同终点"）：
+
+| # | 位置 | 改法 |
+|---|---|---|
+| 1 | `SKILL.md` 常驻规则 | 新增 R9（文本见下） |
+| 2 | `SKILL.md:81` | 「不得假装已知用户水平，也不从最基础内容开始空讲」**恢复原文限定词**：原文 `original-workflow.zh.md:375` 为"在获得必要信息前，不假装已经了解用户水平，也不直接从最基础内容开始讲解"；本项目改写时丢掉了限定词，使其变成**无条件禁令**，正面挡住 R9 触发条件①。改为"**在获得必要信息前**……；R9 讲授不受此限" |
+| 3 | `task-loop.md` §4 | 保留原有四步，**确认题作为第 5 步另加**（C 指出：把"用户亲自应用"换成确认题是**削弱**既有槽位，且丢掉唯一能产出行为类证据的一步）；并注明"本条亦可由 R9 在诊断阶段独立调用" |
+| 4 | `task-loop.md:15` | 「已在第 1 级时不再降级，改为缩小任务或回补前置知识」→ 补"**若缺失的是知识类内容，按 §4／R9 讲清机制后再换表征**" |
+| 5 | `adapt.md:9` | 「概念未理解 → 回到最小示例，换一种表征」→ 补"**若学员尚未学过该概念，先按 R9 讲授，再换表征**" |
+| 6 | `diagnosis.md` 动态调整表（`:29-35`） | 新增一列措施："**概念未理解且学员未学过 → 直接讲授（R9）**"——这是让讲授在**诊断阶段可达**的最小结构性改动 |
+
+**R9 文本（修订版）**：
+
+```md
+- **R9 讲授（知识类不做自我发现）**：R9 是**回补形式**的例外，**不是加速项**。三条触发均不成立时，一律走 R1／R2。
+  触发条件（**必须引用可见观察**，不得凭自我断言）：
+  1. 学员明说自己没学过、不了解该内容（引用学员原话）；
+  2. 诊断或练习显示必要前置知识缺失（引用已提交作答的具体位置，并落一条 `evidence` 或 `open`）；
+  3. 内容**同时**满足三项：
+     (a) 有一句**官方文档中唯一确定**的写法，不依赖本项目上下文与取舍；
+     (b) 该点在学员现有记录（`state.capability`／`evidence`）中**既无"已验证"也无"部分验证"**；
+     (c) 能用**一句话**陈述完毕，不含"如何组合／如何选型／如何排错"。
+     判例：`WaitForSeconds` 的名称与签名 → 可讲；"如何用协程做计时" → (c) 不成立 → 走 R1／R2。
+  讲授结构：概念 → 为什么当前任务需要 → 最小示例 → **用户亲自应用** → **确认题**（第 5 步）。
+  知识类的"亲自应用"可由确认题承担；**技能类必须亲手实现**。
+  **技能类排除下沉到知识点级**：技能类任务内，R9 只改变"回补的形式"（讲授而非让学员自己悟），
+  **不得改变"先尝试"的顺序**；也不得据此把技能类任务改成"我讲完你照着敲"。
+  预算："连续讲授"指**同一任务循环内累计**；每讲完 1 个机制，必须回到一次学员产出（预测下一步／确认题／亲手改一处）。
+  讲授 ≠ 直接答案：讲授给概念、机制、结构与最小示例；学员任务的核心实现仍不代做（仍走 R1 与 `route[].userOnly`）。
+```
+
+#### F2′ 两类自述（改 `intake.md:36`）
+
+在 §1 F2 文本基础上补两点：
+
+1. **回应既有裁定 R2-W01**：`DESIGN-AUDIT.md:267` 曾驳回"跳过诊断的新手快通道"，理由是**断裂证据链**。F2′ **不跳过诊断**——它只改变**首次接触的形式**（先讲，再确认），三类最小覆盖与后续证据要求不变。这一点必须写进 `intake.md` 的说明，避免与旧裁定冲突。
+2. **允许一句层级确认**（A 提供）：采信缺口自述后，可问**一句**偏好／层级确认（例如"你是完全没接触过，还是学过但忘了？"），以免讲错层（"不会协程"常因 `IEnumerator` 前置缺失）。这属 `SKILL.md:18` 既有的意图确认，**不算"考一遍"**。
+
+#### F3′ 证据分层（改落点，改判据）
+
+- **落点修正**（B 提供）：`state.md:45` **只禁占位符，没有任何条款拒绝"问答记录"**，因此 §1 F3.3「给 state.md 的允许类型加一项」是在**改一个不存在的列表**。真正需要改的是：
+  1. `review-acceptance.md:20`（"依据"的举例全部是材料型内容，没有一种适用于口语回答）；
+  2. `coach-validate.mjs:308` 的错误提示串（"证据必须指向可核对材料（文件/日志/截图/复现步骤）"）；
+  3. `state.md:45` 明确一句："**问答记录与操作自述记录均属可核对材料**"。
+- **判据修正**（A 提供）：放弃"同类 2–3 题"与"或同题加难追问也正确"（后者在 Q1-1 上正撞 `diagnosis-bank.md:68`，且全库每维度仅 2 题、生命周期顺序无同类第二题，会反向激励多出题）。改为：
+  - 知识类结论判 `已验证` 的条件 = **无提示下解释机制 ＋ 迁移到新情境**（复用 `adapt.md:29` 的迁移检查与 `review-acceptance.md:55` 的检索式复述）；
+  - **单题正确一律停留"部分验证"**。
+- **适用范围声明**（原 F3.1 保留）：`review-acceptance.md` 的三条件**只用于阶段验收**，并写明"单个知识结论与单题诊断不适用"。
+
+#### F4′ 操作自述（三处，缺一则事故原样复发）
+
+1. `SKILL.md:25` R3 改为三类自述分述（原 F4 文本）；
+2. **`task-loop.md:46`**「声称'我做了'不是证据……按'待验证'记录」→ 按三类自述改写（该条属于 `本次任务：…` 的**必读文件**，`SKILL.md:54`，不改会与 R3 正面矛盾）；
+3. **artifact 第三类**（见 F3′ 落点）：操作自述的合法 artifact = 「操作自述记录（学员原话摘录＋时间）」；
+4. 措辞改为："**不得再要求学员执行同一实测，也不得要求补交其实测材料**（例如截图）"——否则改口要"Console 截图"即可绕过（A 的现场证据：真实状态里正有一条 note 写着"尚未附实测截图"）。
+
+#### F5′ 实测最小化
+
+- 豁免清单由**无条件**改为"**通常**可静态判定"；并写明"**文档未覆盖、文档自相矛盾或存在版本差异时，仍须实测**"（B、A 共同指出：原清单与 `diagnosis-bank.md:68`「此类差异应要求学员实测」直接冲突，且 R10 的无条件清单与其合取式门禁自相矛盾）。
+- 门槛要求具体依据：要求实测前须说明"为什么无法从代码或文档判定"，并**给出所依据的文档章节或文件行号**（把 C 所指出的"只剩模型自判"变成可核对）。
+- 同步修正领域包 `diagnosis-bank.md:68`，使其与 R10′ 一致。
+
+#### F6′ 题库门槛与类型标签
+
+1. **门禁落点改到 `diagnosis.md`**（B 提供）：`domain-contract.md` 只在切换学科时读（`SKILL.md:63`），诊断时读不到；因此字段要求必须写进 `diagnosis.md` 的取题流程，`domain-contract.md` 只作契约声明。
+2. **同步三处**（A、B 共同指出）：`diagnosis-bank.md:827-835` 的最小覆盖索引、`:837-846` 的按原型推荐组合、`example.md:74-80` 的示范；并为 2D/3D 原型指定替代的"理解预测"题（Q2-1 或 Q3-2），以维持 `diagnosis.md:11-17` 要求的三类最小覆盖。
+3. **落地形态**（A 的未完成项）：`diagnosis-bank.md` 目前**只有按维度分节、没有分组机制**，因此"移入讲授后确认题分组"需明确为：新增一节 `## 讲授后确认题`，把 Q1-1 移入并在题前补讲授要点。
+4. **§2 中 F6 行 E 列改为"人工核对"**：`coach-validate.mjs` **从不解析 `diagnosis-bank.md`**（只校验 manifest 键、小节存在与大小），原声明属过度声明，与已修的 D9 同类。
+5. **字段示例不得含学科词条**：`domain-contract.md` 在 LY01 扫描面内，按 D7/D14 先例，示例值一旦含学科词条会触发自测第 4 项失败。
+
+#### F7′ 防过度矫正
+
+- 原第 1 条"连续讲授不超过 2 个知识点"（A：无依据、不可判定；C：可被"讲 2 点→确认题→再讲 2 点"绕过）改为**可判定单元**：**一次讲授＝一个机制＋一个最小示例**，讲完必须回到一次学员产出；"连续"按**同一任务循环内累计**计。
+- 原第 2 条与 `adapt.md:9`「换一种表征」重复 → 写成对 `adapt.md:9` 的**补充**（"确认题答错 → 回退到更小机制并换表征"），不另立规则。
+- 其余两条（技能类不得改为讲授；讲授不得取代亲手做）保留。
+
+### 7.3 F8 的处置：按现规格驳回，改采 F8-lite
+
+**驳回理由（合并三份审核）**：
+
+1. 两条不变量检查的都是**模型自己写的自述字段**，拦得住无意漂移、拦不住有意粉饰（把 `kind` 写成"行为类"、或把一次问答拆成两行即可通过）；`state.md:108` 本就声明校验器只查状态层。
+2. 不变量 1 与 F3′ **不等价**：F3′ 的"解释机制＋迁移"无法用"证据条数 ≥2"忠实编码；要忠实就得按题目编号去重，反而要加更多字段。
+3. 不变量 2（artifact 前缀断言）**不可判定且是误报源**：全仓没有"问答记录型"的可判定表示，artifact 是自由文本。
+4. **成本不对称**：`schemaVersion` ＋ 校验器 ＋ 自测 ＋ 两夹具 ＋ 模板 ＋ 文档共 6 处联动，而按 `SKILL.md:45`，校验失败是"必须先修状态再继续"的**阻塞**；且 `coach-validate.mjs:36/196` 是**相等**判断，升 1.1 会让既有状态文件（真实用户 `schemaVersion=1.0`、10 条无 `kind` 的证据，现跑 `ok:true`）全部报 ST01，把已发布用户**拦死**。
+5. **错配**：事故中被违反的直接规则是 F5′（要求实测前须说明理由），而状态文件没有"实测要求及理由"字段——F8 机械化的是 F3′，不是真正出事的规则。
+
+**F8-lite 规格（零 schema 变更）**：
+
+- 不升 `schemaVersion`、不加必填 `kind`；
+- 校验器新增**一条 warn**：某维度 `status=已验证`，且其引用证据的 `artifact` **全部**形如「问答记录…」、去重后题目编号 **<2** → 提醒"知识类结论疑为单题即发已验证"；
+- 证据分层的强制力留在 `state.md` 的文档约定 + `docs/zero-knowledge-path.zh.md` 人工清单（**每阶段**跑一次，而非每次落盘付费）；
+- 如实声明：**warn 不构成门禁**（CI 退出码只看 error；自测只断言 `r.errors`），选它即接受"只提醒、不拦截"。
+
+**推迟到下一版**：C 提出的"选填 `kind` ＋ 缺失时按行为类从严"（零摩擦、不升 schema），以及 B 提出的 `--migrate`（在 F8 不做的前提下无必要）。
+
+### 7.4 新增改动（第 1 轮审核提出）
+
+| 编号 | 改动 | 来源 |
+|---|---|---|
+| **F9** | `evidence[].stage` 允许 `0`：F1′ 触发条件①/② 发生在诊断、基线、路线之前，而现状要求 `stage ≥ 1` 整数（`coach-validate.mjs:306`、`state.md:32`），只能硬填 1，导致 `PROGRESS.md` 的"阶段"列失真。改为允许 `0` 并在渲染时显示"诊断期" | B |
+| **F10** | 版本与对外文档同步：① 按 `CHANGELOG.md:6` 的定义，R9/R10 属**交互协议变化** → 递增引擎版本；② 双语 README（`README.md:17`／`README.zh.md:15`）的「Self-reports are not evidence／自述不算证据」与 F2′、F4′ 冲突，必须改写（仓库已发布）；③ `example.md:111,114,117,120,123` 的 strength 写作"中/弱"，不在三态枚举内，且 artifact 用的是"诊断对话记录"——按 F3′/F4′ 规范化；④ `renderProgress` 的证据表加"类型/材料"column 若做 F8-lite 则同步 | A、B |
+
+### 7.5 对"审核对象是否漂移"的回应（A 的提醒）
+
+`coach/docs/zero-knowledge-path.zh.md` 是设计 §4.2 **预告要生产的产物**，我在等待审核期间先行起草并在文件头标注"草稿"；**设计文档本体在审核期间未被修改**（A 以 SHA256 核对）。因此审核对象未漂移；该清单的定稿仍待本轮修订完成后进行。
+
+### 7.6 下一步
+
+1. 按 F1′–F10 实现（引擎 6 处 + 领域包 4 处 + 校验器 warn + 文档与版本）；
+2. 新增零基础路径回归并跑通全部验证；
+3. **第 2 轮独立审核**：新代理，核对"实现是否忠实于 F1′–F10"与"第 1 轮发现的处置是否到位"；
+4. 通过后做**全局复核**；任何一轮发现不合理即回到该轮重审。
+
+---
+
+## 8. 实现状态与自查证据（引擎 1.1.0）
+
+> 本节只记录"实现了什么、用什么证据自查"，不改动 §7 的规格正文。
+
+### 8.1 已实现（逐项）
+
+| 项 | 落点 | 关键内容 |
+|---|---|---|
+| **F1′** | `SKILL.md`（R9）、`task-loop.md`（§4 与 `:15`）、`adapt.md`（`:9` 与新增行）、`diagnosis.md`（动态调整表）、`SKILL.md:81` | 六处同步齐备；R9 为五步结构（保留"用户亲自应用"，确认题为第 5 步）；含"不是加速项"默认条款、可见观察要求、条件③可判定收紧、技能类排除下沉到知识点级、讲授预算 |
+| **F2′** | `intake.md` | 两类自述分述；明示"不等于跳过诊断"以回应 R2-W01；允许一句层级确认 |
+| **F3′** | `review-acceptance.md`、`state.md`、`coach-validate.mjs` | 三条件限定为阶段验收；`artifact` 承认问答记录与操作自述记录；判据改为"无提示解释机制＋迁移"，单题正确只算部分验证 |
+| **F4′** | `SKILL.md`（R3）、`task-loop.md`（§5 证据表）、`state.md` | 三类自述；"不得要求重复实测，也不得要求补交实测材料" |
+| **F5′** | `SKILL.md`（R10）、`diagnosis-bank.md` | 豁免清单改"通常"；例外为"文档未覆盖／自相矛盾／版本差异"；要求给出文档章节或行号；领域包那条实测要求已按例外条款对齐 |
+| **F6′** | `diagnosis-bank.md`、`example.md`、`domain-contract.md` | 14 题各加 `类型`/`前置知识`；Q1-1 移入《讲授后确认题》并补讲授要点；索引与 2D/3D 推荐组合同步；维度 1 补交叉引用以维持"每维度 ≥2 题"；`example.md` 的 strength 与 artifact 规范化 |
+| **F7′** | `SKILL.md`（R9 预算）、`adapt.md` | 讲授单元＝一个机制＋一个最小示例；确认题答错→回退更小机制（作为 `adapt.md:9` 的补充） |
+| **F8** | 未做（按现规格驳回） | 改采 **F8-lite**：`coach-validate.mjs` 新增 `ST-W7` **warn**（不拦截），规格与理由见 §7.3 |
+| **F9** | `coach-validate.mjs`、`state.md` | `evidence[].stage` 允许 `0`；渲染显示"诊断期" |
+| **F10** | `CHANGELOG.md`、`package.json`、三个状态文件、双语 README、`zero-knowledge-path.zh.md` | 引擎与包版本 → 1.1.0（三个 `engineVersion` 已核对一致）；README 的"自述不算证据"改为三类自述并新增"知识直接教、技能才靠练"；清单定稿为 Z1–Z10 |
+
+### 8.2 自查证据（可复跑）
+
+实质断言（`coach-selftest.mjs`，**9 项全 PASS**）：反向夹具被拦下（23 条 error，关键规则齐全）／正向夹具状态层／领域包结构／**`ST-W7` 命中 warn 且未升级为 error**／**不变量 3 反绕过子句**／**`ST-W8` 推测状态提醒（含"省略字段不提醒"）**／分层负例（副本 3 条 LY01、原目录 0 条）／迷你 YAML 子集解析／渲染函数形状。
+
+其余验证：
+
+```
+coach-validate.mjs --state examples/state.demo.json    → 退出码 0
+coach-validate.mjs --state …/state.selftest-invalid.json → 退出码 1（预期拦截）
+test/entry.smoke.mjs                                   → PASS（入口契约 + 11 个技能资源）
+dsh-plugin-dev check                                   → ok=true，9 通过 / 0 失败 / 2 警告（两条为样板作者的文档约定，理由已记录）
+```
+
+六处同步与关键条款的存在性逐项核对通过（R9／R10／`:81` 限定词／§4 五步／`:15`／`adapt:9`／diagnosis 表讲授行＝全 True；stage≥0、诊断期渲染、适用范围声明、问答记录合法性、R10 例外条款＝全 True）。
+
+**分层红线**：除校验器的黑名单外，另按常见引擎 API 名（`Unity` `MonoBehaviour` `Rigidbody` `Coroutine` `GameObject` `Instantiate` `SerializeField` `GetComponent` `WaitForSeconds` `FixedUpdate` `OnEnable` `Transform` `Prefab` `asmdef` `C#`）扫描 `SKILL.md` + `references/engine/*.md` + `assets/*.md` → **零命中**。（先前我误把 `WaitForSeconds` 写进 R9 判例，已自行修掉，并在 R9 内补"判例必须学科无关"的硬规则。）
+
+### 8.3 版本与发布状态
+
+- `package.json` = **1.1.0**；`CHANGELOG.md` 已加 `[1.1.0]` 条目（含"未做"事项与理由）；
+- 三个 `engineVersion`（模板、正向夹具、反向夹具）已同步为 1.1.0；
+- **发布状态**：仓库已公开；本地 1.1.0 已 rebase 到远端 `372f381` 之上（5 个提交，可 fast-forward 推送）；原生 `dsh plugin add` 安装通道已实测可用；npm 尚未发布。详见 [`releasing.zh.md`](releasing.zh.md)。
+
+### 8.4 待办
+
+1. **第 2 轮独立审核**（已完成三份：R2-A 忠实度/处置、R2-B 新冲突/漏洞、R2-C 有界保底）：三家独立指向同一批问题，处置见 §9；
+2. **全局复核**（第三轮，任务书见工作区 `.publish/global-review-brief.md`）；
+3. 全部通过并经使用者确认后，才恢复发布。
+
+### 8.5 审核期间的对象变化（如实记录）
+
+第 2 轮审核进行中，本文档新增了本节所在的 §8（实现状态与自查证据），文件从 324 行增至 375 行以上。**§7 的规格正文在该期间未被修改**，审核者是对照 §7 判定"实现是否忠实"的，因此结论有效；但 R2-B 如实指出了这一点（"审核对象在审核期间增长"），记录在此以免日后误读。同类情况在第 1 轮也出现过一次（`docs/zero-knowledge-path.zh.md` 在审核期间创建，已在 §7.5 说明）。
+
+---
+
+## 9. 第 2 轮审核发现与处置
+
+### 9.1 三家独立发现（去重后）
+
+| 编号 | 发现 | 提出者 | 严重度 |
+|---|---|---|---|
+| R2-1 | **Q1-1 讲授要点与判分要点相反**：讲授要点写"未激活对象 `Awake` 仍会执行"，而同一题的合格回答要点明确"本题对象初始未激活，**场景加载时不会执行 `Awake`**"，且该说法正被列为"典型错误回答"。R9 让教练照讲授要点讲 → 把错的机制教给零基础学员 | B、C（独立） | **阻塞** |
+| R2-2 | `example.md` 仍把 Q1-1 当**首次接触题**（出题表、作答记录、内容索引表），与题库"事实性题不得作首次接触题"及索引更新冲突；`CHANGELOG` 却称已同步 | A、B、C | **阻塞** |
+| R2-3 | `intake.md`／`diagnosis.md` 仍写"**两类**自述"，而 R3／`task-loop.md` 已是**三类**——诊断入口恰好是这两处，读不到"操作自述不得要求重复实测/补交材料" | B | **阻塞** |
+| R2-4 | Z2（零基础清单）写"事实性知识 → 禁止要求实测"**没有例外**，与 R10 的例外条款及题库 `:850` 相反 | B | **阻塞** |
+| R2-5 | 引擎层仍有学科词：`intake.md` 新引入 `IEnumerator`／协程；`diagnosis.md` 残留"协程取消逻辑" | A | **阻塞** |
+| R2-6 | `ST-W7` 形同虚设：仅按 `artifact` **前缀**字面匹配且要求问答记录占满全部证据 → 改前缀／混一条证据／伪造题号／裸 `Q` 误报四条路径 | B、C | 重要 |
+| R2-7 | R9 触发集在三处不一致；`SKILL.md` 把"事实性知识"单列为**无条件**触发，而零基础学员对 ③(b) 恒真 → 门槛实际只剩模型自判 | B | 重要 |
+| R2-8 | `前置知识` 是自由文本、状态层无知识点级记录 → 门禁不可判定（Q1-1 写"无"更使其恒真） | B | 重要 |
+| R2-9 | 操作自述无可判定边界 → "我写完了"这类**无结果的完成声明**可被归入操作自述拿"部分验证" | B | 重要 |
+| R2-10 | 4 组推荐组合不满足其上方"任选一组即可满足三类覆盖"的声明；题库 `engine: ">=1.0.0"` 与新字段不匹配 | B | 重要 |
+| R2-11 | `ENGINE-REVISION-2.zh.md` §2 表中"校验器可强制字段存在"仍属过度声明 | A | 重要 |
+| R2-12 | 维度 1 对**零基础学员**实际只剩 1 道可用首触题（Q1-1 属事实性被挡） | C | 重要 |
+| R2-13 | R10 缺"核对状态"落盘机制；`CHANGELOG:6` 定义的"引擎版本"在 `SKILL.md`/engine 内没有版本字符串 | B | 建议 |
+
+### 9.2 处置（本轮已实施）
+
+| 编号 | 处置 |
+|---|---|
+| R2-1 | **重写 Q1-1 讲授要点**：明确"本题对象初始未激活 → 场景加载时**不**执行 `Awake`，推迟到 `SetActive(true)`"、"`Awake` 绑定脚本实例创建时机而非对象激活"、"`enabled = false` 时 `Awake` 仍执行**但不适用于未激活对象**"、`Instantiate` 情形属 R10 例外。并在 `CONTRIBUTING.md` 加硬规则：**讲授要点必须与合格回答要点/典型错误回答逐条对照，不得矛盾** |
+| R2-2 | `example.md` 改为**演示 R9 路径**：首次诊断用索引推荐的 Q3-2＋Q4-2＋Q6-1，另用 Q1-1 作**讲授后确认题**；补齐 Q3-2 的作答记录与证据 E-06、更新能力画像与内容索引表；`CHANGELOG` 措辞同步 |
+| R2-3 | `intake.md`／`diagnosis.md` 统一为**三类自述**，并补操作自述的 artifact 与"不得重复实测/补交材料" |
+| R2-4 | Z2 补 R10 例外条款，并把触发条件收窄为"事实性知识**且**满足 R9 ③ 的 (a)(b)(c)" |
+| R2-5 | `intake.md` 改为学科无关措辞（"缺的往往是 X 依赖的更小的前置概念"）；`diagnosis.md` 的旧术语一并改净 |
+| R2-6 | `ST-W7` 判据重写：**按题号正则**（`Q<数字>-<数字>`）识别、**只统计 `strength=已验证`** 的证据、题号归一化为 `主-次`；已在真实绕过样本上复测（改前缀的写法照样命中）；残余边界（降级为"部分验证"可完全回避）如实写进代码注释 |
+| R2-7 | `SKILL.md:101` 改为"事实性知识是 ③ 的特例，仍受 (a)(b)(c) 约束" |
+| R2-8 | `diagnosis.md` 取题前置检查补一条：**无法判定时按"未满足"处理**（先讲授或换题），不得默认视为满足 |
+| R2-9 | R3 与 `task-loop.md` 补边界：**不含可观察结果的完成声明按能力自述处理（`待验证`）**，操作自述的 artifact 必须含结果原文 |
+| R2-10 | 4 组组合分别换入满足三类覆盖的题（编辑器侧用 Q7-1、UI/存档用 Q2-1、网络用 Q6-2、性能用 Q6-1）；题库 `engine` 升为 `>=1.1.0`，领域包版本与三个状态文件的 `domainVersion` 同步为 1.1.0 |
+| R2-11 | §2 表该列改为"**人工核对**（校验器不解析题库）" |
+| R2-12 | 已在题库维度 1 的说明中如实标注：Q1-1 移出后，**零基础学员在该维度只有 1 道可用首触题**；理解预测类由索引中的其它题承担 |
+| R2-13 | R10 增加**留痕要求**：提出实测要求时在 `state.open[]` 落一条（含依据与核对状态）；`SKILL.md` 顶部加**引擎版本标记 1.1.0**，使 `CHANGELOG` 的定义可核对 |
+
+### 9.3 复测证据
+
+```
+coach-selftest.mjs                        → PASS 9 / SKIP 0 / FAIL 0（含 ST-W7、ST-W8、不变量 3 反绕过、分层负例断言）
+coach-validate.mjs 正向夹具                → 退出码 0
+coach-validate.mjs 反向夹具                → 退出码 1（23 条 error）
+ST-W7 绕过复测（改前缀 + 伪造题号写法）      → 仍命中 warn（按题号正则识别）
+```
+
+### 9.4 尚未处理（留待全局复核判断）
+
+- R2-12 的**结构性**部分：维度 1 首触题只剩 1 道属题库设计取舍，本轮只做了如实标注，未新增题目；
+- R2-6 的**残余边界**：`ST-W7` 只提醒不拦截，把维度状态降为"部分验证"即可完全回避——这是 §7.3 的既定取舍，需在全局复核中确认是否可接受。
+
+---
+
+## 10. 第三轮：全局复核（已完成，两份独立报告）
+
+### 10.1 两份报告的结论
+
+| 报告 | 范围 | 结论 |
+|---|---|---|
+| 全局复核（完整版） | G1 端到端可用性、G2 跨文件一致性、G3 契约与实现一致、G4 文档诚实性、G5 可发布性、G6 两项裁决 | **需小改后发布**；**无阻塞级缺陷**；1 条候选阻塞（技能类缺口自述的终点冲突） |
+| 全局复核（有界版） | 三条抱怨的复发路径、契约↔校验器↔断言自洽性、两项裁决 | **【阻塞】无发现**；【重要】2 条；【建议】3 条；**需小改后发布** |
+
+**G6 两项裁决（两份一致）**：
+1. `ST-W7` 只提醒不拦截——**可接受**：升 schema／加 error 会拦死既有 `schemaVersion=1.0` 的真实用户（成本不对称）；且把结论降为"部分验证"本身是标得更保守，不是粉饰。
+2. 题库维度 1 对零基础学员**无可用首触题**——**需补 1 道**（不必改引擎）。有界版进一步指出：断的不是覆盖（可由"讲授→确认题"顶上），而是**起点测量**——先教后测会让能力画像起点偏高。
+
+### 10.2 本轮处置
+
+| # | 发现（提出者） | 处置 | 落点 |
+|---|---|---|---|
+| 1 | **技能类缺口自述的终点冲突（候选阻塞）**：`intake.md` 要求"缺口自述立即讲授"，`task-loop.md`／`SKILL.md` 要求"技能类仍守先尝试"——同一情形两个终点，正是抱怨①的现场措辞 | 三处加**优先级裁定**：学员原话明确表示未学过时，**讲授优先于"先尝试"**；技能类则"先讲清其中最小的一个机制，再让他动手"；**不得代做** | `SKILL.md` R9 触发①与技能类段、`intake.md`、`task-loop.md` §4 |
+| 2 | **R10 留痕无契约**（重要）：要求 `open` 项含"依据/核对状态"，但契约、校验器、渲染都没有这两个字段 → 留痕不可复核 | `state.md` 的 `open` 增加**可选** `basis`／`checkStatus`；校验器校验类型与枚举，对 `推测` 报 **ST-W8** 提醒；渲染输出两者；`SKILL.md` R10 补"**`推测` 状态不得据此要求实测**" | `state.md`、`coach-validate.mjs`、`SKILL.md` |
+| 3 | **行为类"已验证"索要截图 vs R3"不得要求补交实测材料"**（重要） | R3 补边界：禁止的是就**同一事项**重复取证；**阶段验收**所需材料属**新的证据要求**，不受此限，但须事先说明用途与验收标准 | `SKILL.md` R3 |
+| 4 | 概念题结论可能被并入阶段验收、经 `userOnly` 要求"亲手跑一次" | `review-acceptance.md` 补：**不得用 `userOnly` 通道给概念题取证** | `review-acceptance.md` |
+| 5 | 首触规则只禁"事实性"题；关键词式分类可能把"这块我不太熟"判成能力自述 → 出题 | 分类补默认值：**中间的模糊表述按缺口自述处理**；首触规则扩展为"对某知识点，学员记录中既无已验证也无部分验证时，该知识点的题目（**无论类型**）不得作为首次接触题" | `SKILL.md` R3、`diagnosis.md` |
+| 6 | 维度 1 对零基础学员**可用首触题为 0 道** | 新增 **Q1-3**（`前置知识`：无（可首触）、`类型`：推理性、最小诊断类别：问题定位，含完整判分要点与 1–5 锚点）；维度 1 说明更新为 3 题；索引新增"**首触可用题**"一行 | `diagnosis-bank.md` |
+| 7 | `ST-W7` 仍可用"混入一条 `已验证` 且不含题号的证据"压制 | **不收紧判据**（加严会误伤"一条问答记录 ＋ 一条材料证据"这类合法组合；两份复核均确认 warn-only 可接受）→ 在代码注释与 §7.3 **如实记录为已知边界** | `coach-validate.mjs`、§7.3 |
+| 8 | 自测未断言不变量 3 的**反绕过子句** | 新增专门断言：构造"已验证 + 引用证据强度=待验证"的探针，要求命中"没有一条是已验证" | `coach-selftest.mjs` |
+
+### 10.3 复测证据
+
+```
+coach-selftest.mjs  → PASS 8 / SKIP 0 / FAIL 0（新增"不变量 3 反绕过子句"断言）
+正向夹具 → 0 ｜ 反向夹具 → 1（23 条 error） ｜ 入口冒烟 → PASS
+题库：15 题，类型/前置知识字段各 15，首触可用题 1 道（Q1-3）
+引擎分层红线（含黑名单外 API 名与中文术语）→ 零命中
+```
+
+### 10.4 三轮审核的收敛
+
+| 轮次 | 报告数 | 层次 | 主要产出 |
+|---|---:|---|---|
+| 第 1 轮 | 3 | 设计 | F1–F8 逐条裁定：F8 按现规格**驳回**、F1/F3/F4/F5/F6 结构性补丁、C 的 5 条最小加固 |
+| 第 2 轮 | 3 | 实现忠实度与新冲突 | 13 条发现，含 1 条**会教错机制的事实错误**与 `ST-W7` 的 4 条绕过 |
+| 第 3 轮 | 2 | 整体 | 8 条复发路径、2 项裁决；**两份均无阻塞** |
+
+累计处置 30+ 项。三条原始抱怨：① 条款层已闭合，唯一终点冲突已裁定；② 已闭合（三条件限定阶段验收、R10 明列静态可判情形、操作自述封顶部分验证）；③ 已闭合（触发①无条件覆盖"学员明说不知道"，"事实性知识"降为条件③的特例），起点测量缺口已补题。
+
+### 10.5 仍未解决（如实声明，不包装）
+
+1. **`ST-W7` 的两条已知边界**（混入一条已验证的非问答证据可压制；把维度降为"部分验证"可完全回避）——**有意不改判据**，靠 `docs/zero-knowledge-path.zh.md` 的人工清单兜底；
+2. **R10 的"版本差异"例外仍可由模型自判**，但已加两道约束（必须给出文档章节/行号；`checkStatus` 为 `推测` 时不得据此要求实测）；
+3. **R9 条件③ 的门槛仍主要靠模型自判**（第 2 轮已记录为已知残余）；
+4. **题库 `类型`/`前置知识` 字段的完整性只有人工核对**，校验器不解析题库（`domain-contract.md` 已如实声明）；
+5. 与本次教学修订无关、沿用 1.0.0 既有声明的两项：原生 `dsh plugin add` 端到端未实测、领域包中标注「（未验证）」的 Unity 配方未实测。

package/docs/installing.zh.md

@@ -0,0 +1,105 @@
+# 安装细则
+
+本文覆盖 dsh-coach 的全部安装路径（技能目录方式与组合包方式）。
+
+## 先选路径
+
+| 你的情况 | 选哪个 | 需要什么 |
+|---|---|---|
+| 只要在**当前项目**里用 | A1 项目级技能目录 | 无（复制文件即可） |
+| 想在**所有工作区**用（原生 DSH） | A2 用户级技能根 | 知道 `$DSH_HOME`（默认 `~/.dsh`） |
+| 已装 `dsh` CLI，且想按插件方式管理 | B 组合包 | `dsh` CLI；`dsh plugin add` 会调 pnpm |
+| 用 DSH Desktop | C 市场或技能目录 | 桌面端；市场插件 `dshmarket` |
+| 只想试一次 | D 直接让 agent 读 `SKILL.md` | 无 |
+
+技能根与优先级的**官方约定**（来自 `@deepseek-ai/dsh-skill-filesystem` 文档）：
+
+| Rank | 来源 | 路径 |
+|---:|---|---|
+| 100 | 项目 | `<项目根>/.dsh/skills` |
+| 200 | 项目 | `<项目根>/.agents/skills` |
+| 300 | 自定义 | `customSkillDirs` 配置项 |
+| 400 | 用户 | `<DSH_HOME>/skills` |
+| 500 | 用户 | `<AGENTS_HOME>/skills`（默认 `~/.agents`） |
+
+> **项目根的定义**：最近一个包含 `.git` 的祖先目录；**若不存在，就是当前工作目录**。本机工作区没有 `.git`，因此项目级技能只在"以该目录为工作目录"的会话里出现——在它的子目录里开会话也找不到。要跨工作区，请用 A2。
+
+## A. 纯技能安装
+
+### A1 项目级
+
+```powershell
+# 在本仓库根执行；默认目标是 <cwd>/.dsh/skills/dsh-coach
+node skills/dsh-coach/scripts/coach-install.mjs
+
+# 先看会做什么（不写盘）
+node skills/dsh-coach/scripts/coach-install.mjs --dry-run
+
+# 用目录联接安装：源文件改动即时生效，适合边改边用
+node skills/dsh-coach/scripts/coach-install.mjs --link
+```
+
+`--link` 在 Windows 上建立**目录联接（Junction）**，不需要管理员权限；其它平台建立目录符号链接。**分发时不要用 `--link`**——对方删掉你的源目录，技能就失效了。
+
+### A2 用户级（跨工作区）
+
+```powershell
+node skills/dsh-coach/scripts/coach-install.mjs --dest-root "$env:DSH_HOME\skills"
+# 原生 DSH 若未设置 DSH_HOME，其默认 home 为 ~/.dsh
+```
+
+### A3 其它技能根
+
+任何被扫描的根都可以，只要目录名是技能名：
+
+```powershell
+node skills/dsh-coach/scripts/coach-install.mjs --dest-root "<项目根>\.agents\skills"
+```
+
+## B. 组合包（插件）安装
+
+```bash
+dsh plugin --profile <profile> add /path/to/dsh-coach                     # 本地检出
+dsh plugin --profile <profile> add dsh-project-based-learning             # 从 npm
+dsh plugin --profile <profile> add github:Kirisame1969/dsh-project-based-learning   # 不经 npm，直接从仓库
+dsh --profile <profile> --dump-config                     # 应出现 dsh-project-based-learning 层
+dsh --profile <profile>                                   # 启动
+dsh plugin --profile <profile> remove dsh-project-based-learning          # 卸载（依赖与层一并移除）
+```
+
+层序（官方文档）：各组合包按 `dsh.profile.bundles` 顺序 → profile 自己的 `cordis.patch.yml` → `$DSH_HOME/cordis.patch.yml` → `--patch` overlay。
+
+**前提**：目标 profile 已挂载 `@deepseek-ai/dsh-skill`（`@deepseek-ai/dsh-base` 已包含）。本插件通过 `ctx.skills.register()` 注册技能，不贡献工具、不插队、不覆盖既有行。
+
+## C. DSH Desktop
+
+- 桌面端有自己的插件界面（市场插件 `dshmarket`，站点 <https://dshmarket.com>，仓库 [dsh-market/dsh-market](https://github.com/dsh-market/dsh-market)）。若 dsh-coach 已被收录，可直接在界面里一键安装。
+- 尚未收录时，用 A1/A2 的技能目录方式即可——桌面端同样扫描这些技能根。
+- 桌面端把插件装在 `$DSH_HOME/profiles/<profile>/` 下的"代际"目录中，并通过 profile 的 `package.json` 依赖与 pnpm override 指向它。
+
+## D. 不安装
+
+让 agent 直接读本仓库的 `skills/dsh-coach/SKILL.md` 并按它执行。适合评估与调试。
+
+## 怎么确认装好了
+
+1. **会话技能目录**里出现 `dsh-coach`（模型会在下一步看到它）；
+2. 让模型调用一次 `skill("dsh-coach")`，应返回技能正文，并在资源提示里给出技能目录的绝对路径；
+3. 目录检查：`<技能根>/dsh-coach/SKILL.md` 存在，且 `references/domains/unity-csharp/` 下有 7 个文件。
+
+## 卸载
+
+- 纯技能：删除 `<技能根>/dsh-coach` 目录（联接方式则删除联接本身，源目录不受影响）。
+- 组合包：`dsh plugin --profile <profile> remove dsh-project-based-learning`。
+- 学习数据在**你自己的工作区** `.coach/` 下，与安装无关；卸载技能不会删除它。
+
+## 已知限制
+
+领域包中标注「（未验证）」的 Unity 配方需要在装有 Unity Editor 的机器上实测确认。
+
+## 常见问题
+
+- **技能没出现**：确认工作目录就是技能所在的项目根（没有 `.git` 时项目根 = 当前目录）；或新开一个会话/重启宿主。
+- **`node` 找不到**：安装器与自测需要 Node ≥ 16.7（用 `fs.cpSync`）；本仓库在 Node 24 上验证。
+- **`dsh: command not found`**：`dsh` CLI 由 DSH 发行版提供；用桌面端时它位于桌面的运行时里，不一定会进入 PATH。
+- **改了源文件不生效**：若用复制模式安装，需要重新运行安装器（或加 `--force`）；`--link` 模式则即时生效。