dsh-project-based-learning 1.1.0

package/skills/dsh-coach/references/domains/unity-csharp/verification.md

@@ -0,0 +1,308 @@
+# Unity / C# 可执行核对配方
+
+> 用途：为 `task-loop` 与 `review-acceptance` 提供可直接复制的核对手段。
+> 每条配方固定七字段：**目的 / 前置条件 / 命令 / 期望输出 / 失败含义 / 所需沙箱模式 / AI 可否代执行**。
+>
+> **标注约定**
+> - 命令后带 `（未验证）`＝该命令或参数的完整形式**未经实测**，只作为方向提示；**不得仅凭未验证的命令判定验收通过**（领域包契约第 4 条）。
+> - 未标注的命令＝本文件编写时已实测，或已对照下方官方文档逐字核对。
+>
+> **依据来源**（均为官方文档，逐条核对过参数拼写）
+> - Unity Manual《Unity Editor command line arguments reference》：`-batchmode`、`-nographics`、`-quit`、`-quitTimeout`、`-projectPath`、`-logFile`、`-executeMethod`、`-accept-apiupdate`、`-buildTarget`
+> - Unity Manual《Command-line reference》（Test Framework）：`-runTests`、`-testPlatform`、`-testResults`、`-testFilter`、`-testCategory`、`-assemblyNames`、`-testSettingsFile`、`-runSynchronously`、`-repeat`、`-retry`
+> - Unity Manual《Run tests from the command line》《Create a test assembly》《Log files reference》
+> - Unity Manual《Awaitable completion and continuation》
+> - Microsoft Learn《dotnet build》《dotnet test》
+>
+> **本工作区实测环境**（影响下列配方的可执行性，环境会变，使用前请重新核对）
+> - `dotnet --list-sdks` → `8.0.302`、`8.0.405`、`9.0.315`（存在 .NET SDK）
+> - `csc`、`msbuild` **不在 PATH 上**
+> - 未发现 Unity 安装（`C:\Program Files\Unity\Hub\Editor` 不存在）
+> - 因此 (a) 类配方在此环境可执行；(b)(c) 类配方需要用户自己的 Unity 环境，(d) 类为兜底。
+
+---
+
+## (a) 纯 C# 片段的语法 / 编译检查
+
+### V-a1 有 .NET SDK：用 SDK 风格工程编译片段
+
+**目的**
+在不打开 Unity 的前提下，确认一段**不依赖 `UnityEngine`** 的纯 C# 片段能否通过编译，从而把「语法错误 / 类型错误」与「Unity 环境问题」分开。
+
+**前置条件**
+- 机器上存在 .NET SDK：`dotnet --list-sdks` 有输出。
+- 待检查的片段**不引用 `UnityEngine` / `UnityEditor` 命名空间**（这是本配方的硬边界，见「失败含义」）。
+- 片段中出现的类型都在 BCL 内，或已一并提供。
+
+**命令**
+```powershell
+# 1. 建一个临时目录（放在工作区内，便于沙箱放行）
+$d = ".\_snipcheck"
+New-Item -ItemType Directory -Path $d -Force | Out-Null
+
+# 2. 手写工程文件（不要用 dotnet new，原因见下方「注意」）
+@'
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+    <TargetFramework>netstandard2.1</TargetFramework>
+    <LangVersion>9.0</LangVersion>
+    <Nullable>disable</Nullable>
+    <AssemblyName>SnipCheck</AssemblyName>
+    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="Snippet.cs" />
+  </ItemGroup>
+</Project>
+'@ | Set-Content -Path "$d\SnipCheck.csproj" -Encoding utf8
+
+# 3. 把待检查的片段存成 Snippet.cs（UTF-8），然后编译
+#    （把你的代码写入 $d\Snippet.cs）
+dotnet build $d -v q --nologo
+```
+
+**期望输出**
+- 成功：输出含「已成功生成。」（英文界面为 `Build succeeded.`），并有 `0 个警告` / `0 个错误`；退出码 `0`。
+- 失败：退出码 `1`，并出现形如
+  `…\Snippet.cs(3,61): error CS1002: 应输入 ; […\SnipCheck.csproj]`
+
+**失败含义**
+- 出现 `error CSxxxx` 且文件是 `Snippet.cs` → 片段本身有语法或语义错误；行号列号可直接定位。**这是本配方的主要价值。**
+- 出现 `error CS0246: 未能找到类型或命名空间名"UnityEngine"`（或 `MonoBehaviour`、`SerializeField` 等）→ **不是学员的错**，而是本配方不适用于依赖 Unity 的片段。此类片段必须走 (b) 或 (d)。
+- `error CS0518: 预定义类型"System.Object"未定义或导入` → 编译时没带上引用程序集，通常是用裸 `csc` 而非本配方所致（见 V-a2）。
+- 还原（restore）阶段报网络错误 → 环境问题，与片段无关；可先 `dotnet build --no-restore` 或用已缓存的 SDK。
+
+**所需沙箱模式**：**工作区可写**（需在磁盘上创建工程与中间产物；`obj/`、`bin/` 会写入）。
+**AI 可否代执行**：**可以**。本配方已在当前环境实测通过（含成功与失败两条路径）。
+
+**注意（重要，已实测）**
+- **不要用 `dotnet new console` 建工程**。实测在受限环境下它会因模板引擎要写 `%USERPROFILE%\.templateengine\dotnetcli\<版本>` 而报
+  `Unhandled exception: Access to the path '…\.templateengine\dotnetcli\9.0.315' is denied.`。
+  手写 `.csproj`（如上）绕开模板引擎，更稳。
+- `TargetFramework` 选 `netstandard2.1` 是刻意的：它与 Unity 的 **Api Compatibility Level = .NET Standard 2.1** 大致对应，能更接近 Unity 实际可见的 BCL 表面。若片段用了 `netstandard2.1` 之外的 BCL API，此处能编过但 Unity 里可能编不过——所以本配方通过**不等于**在 Unity 里通过。
+- 检查完请删除临时目录，不要把它留在交付物里。
+
+---
+
+### V-a2 无 .NET SDK：可行替代与不可行替代
+
+**目的**
+在**没有** .NET SDK 的机器上，尽量完成同一件事，并如实说明能力边界。
+
+**前置条件**
+无 SDK；但机器上可能装了 Unity（Unity 自带 Roslyn 编译器与 Mono/IL2CPP 工具链）。
+
+**可行程度分三种，按推荐顺序：**
+
+1. **首选：改用 Unity 自身编译（跳到 V-b / V-c）**
+   有 Unity 时，最可靠的「能不能编过」判据就是让 Unity 编译一次真实工程。它天然包含 `UnityEngine` 引用，不存在 V-a1 的边界问题。
+
+2. **次选：调用 SDK 内置的 Roslyn `csc.dll`（部分可行，务必注意边界）**
+   Roslyn 编译器随 .NET SDK 一起分发，实测路径形如
+   `C:\Program Files\dotnet\sdk\<版本>\Roslyn\bincore\csc.dll`，可用 `dotnet` 直接启动：
+   ```powershell
+   $csc = "C:\Program Files\dotnet\sdk\9.0.315\Roslyn\bincore\csc.dll"
+   & dotnet $csc /nologo /target:library /out:.\_snipcheck\out.dll .\_snipcheck\Snippet.cs
+   ```
+   实测结论（重要）：
+   - 该调用**能报出语法错误**，例如 `…\A.cs(1,44): error CS1002: 应输入 ;` —— 所以它对「语法检查」这一项确实有用。
+   - 但**裸调用无法完成完整编译**：不带 `/reference:` 时会报
+     `error CS0518: 预定义类型"System.Object"未定义或导入`、
+     `error CS0518: 预定义类型"System.Int32"未定义或导入`。
+   - 因此**不能**把裸 `csc.dll` 当作 V-a1 的等价替代。要让它真正可用，必须手动补上引用程序集（`/reference:` 指向 `System.Runtime.dll` 等）。
+   - **一套完整的、带 `/reference:` 且实测可用的 `csc.dll` 命令（未验证）** ——本次未实测出完整可用的引用集合。原因：需要按目标框架挑出 ref 程序集清单，版本相关，未逐一验证；因此不作为验收依据。
+   - 另需注意：`csc` 可执行文件本身**不在 PATH 上**（实测 `Get-Command csc` 无结果），所以只能走上面的 `dotnet <csc.dll>` 形式。
+
+3. **不可行：指望系统自带 `csc` 或 `msbuild`**
+   实测本环境 `csc`、`msbuild` 均不在 PATH。除非用户确认已装 Visual Studio 或 Build Tools，不要把这两者写进配方。
+
+**期望输出**
+- 第 2 种：能定位语法错误即达到目的；出现 `CS0518` 属预期，不代表片段有错。
+- 若三种都不可用（无 SDK、无 Unity、无 VS）→ 直接进入 (d) 降级方案，**不要伪造核对结果**。
+
+**失败含义**
+- `CS0518` → 缺引用程序集，是**工具用法**问题，不是学员代码问题。
+- `error CS0246: 未能找到类型或命名空间名"UnityEngine"` → 同 V-a1，此路不通，转 V-b/V-c。
+
+**所需沙箱模式**：**工作区可写**（要写 `out.dll` 等产物）。
+**AI 可否代执行**：**部分可以**。语法错误定位可代执行；完整编译验证不可代执行，需明确声明未完成。
+
+---
+
+## (b) Unity Test Framework 命令行运行 EditMode / PlayMode 测试
+
+### V-b1 批处理模式运行测试并导出结果
+
+**目的**
+让 Unity 自己编译并运行测试程序集，得到机器可读的测试结果，作为「行为是否正确」的硬证据。
+
+**前置条件**
+- 用户机器上装有 Unity 编辑器，且路径已知（Hub 安装时形如
+  `C:\Program Files\Unity\Hub\Editor\<版本>\Editor\Unity.exe`）。
+- 工程中**存在测试程序集**：按 Unity 文档，测试必须放在引用了 NUnit 的程序集里；通过 Test Runner 创建时会自动带上 `nunit.framework.dll`、`UnityEngine.TestRunner`、`UnityEditor.TestRunner` 三个引用，其中 `UnityEditor.TestRunner` 仅对 EditMode 测试可用。
+- 该工程**没有被同一个编辑器实例打开**（文档明确：批处理模式下不能打开已被另一个实例打开的项目；同一时间只能有一个 Unity 实例运行）。
+- 测试结果输出目录存在且可写。
+
+**命令**
+```powershell
+# EditMode
+& "C:\Program Files\Unity\Hub\Editor\<版本>\Editor\Unity.exe" `
+  -runTests -batchmode `
+  -projectPath "C:\path\to\YourProject" `
+  -testPlatform EditMode `
+  -testResults "C:\path\to\results-editmode.xml" `
+  -logFile "C:\path\to\unity-test-editmode.log"
+
+# PlayMode（把 -testPlatform 换成 PlayMode，结果与日志换文件名）
+```
+
+**期望输出**
+- 进程结束后 `results-*.xml` 存在，内容为 **NUnit XML** 格式（文档：`-testResults` 指定的文件按 NUnit 定义的 XML 格式保存）。
+- XML 里能看到每个测试的名字与结果（通过 / 失败 / 跳过），失败项带消息与堆栈。
+- `-testResults` 省略时，结果文件默认落在**工程根目录**。
+
+**失败含义**
+- **不要把退出码当作唯一的通过判据。** 文档明确指出：目前**对被测的各个 Unity 组件所报告的退出码没有统一定义**，理解问题来源的最佳方式是错误消息与堆栈内容。因此**必须解析 XML / 读日志**，而不是只看 `$LASTEXITCODE`。
+- 没有生成结果文件 → 测试根本没跑起来：常见原因是工程未编译通过、测试程序集缺少必需引用、或 `-projectPath` 指错。
+- XML 中测试数为 0 → 测试程序集未被识别或未被包含。可用 `-assemblyNames "第一个;第二个"`（分号分隔、整体加引号）显式指定要包含的测试程序集；也可用 `-testFilter`（按测试全名或正则）、`-testCategory`（按类别）缩小范围。`-testFilter` 与 `-testCategory` 同时给出时，只有**两者都匹配**的测试会运行。
+- 日志里出现编译错误（`error CS…`）→ 转 V-c 解读，此时测试未执行，不能判定通过。
+
+**所需沙箱模式**：**工作区可写**（Unity 会写 `Library/`、`Temp/`、结果 XML 与日志）。
+**AI 可否代执行**：**通常不可以**。需要本机安装 Unity 且路径已知；当前环境未发现 Unity 安装。AI 可以代为**生成命令、解读日志与 XML、写测试代码**，但**启动 Unity 这一步应由用户在自己的环境执行**。
+
+**参数要点（均已对照文档核对）**
+- `-batchmode`：文档要求命令行跑测试时使用它，以去掉人工交互（例如「保存场景」弹窗）。
+- **绝对不要同时加 `-quit`。** 文档两处明确：`-quit` 在运行测试时**不受支持**；若编辑器正以 `-runTests` 跑测试，`-quit` 会让编辑器**立刻退出，使进行中的测试来不及完成**。
+- `-testPlatform` 接受 `EditMode`、`PlayMode`，以及 `BuildTarget` 枚举中的任意值（后者表示在对应平台的 Player 上跑 PlayMode 测试）。**省略该参数时默认跑 EditMode。**
+- `-runSynchronously`：让测试同步跑完（保证在一次编辑器 Update 内），**仅支持 EditMode**；跨帧的测试（`[UnityTest]`、或带 `[UnitySetUp]` / `[UnityTearDown]` 的测试）会被过滤掉。
+- 稳定性相关：`-repeat <整数>`（重复成功测试）、`-retry <整数>`（重试失败测试）、`-randomOrderSeed <非零整数>`（随机顺序复现）。
+- `-nographics` 慎用：它不初始化图形设备，适合无 GPU 的机器；但文档明确**该模式下输出日志会被关闭**，所以**必须同时用 `-logFile` 指定日志文件**。此外文档提示自动化工作流需要窗口处于焦点状态才能发送模拟输入命令——因此**依赖模拟输入的 PlayMode 测试在无头环境下可能无法工作**，这一点在验收前要先确认。
+
+---
+
+## (c) 编译错误日志的定位与解读
+
+### V-c1 找到并解读 Editor.log / 批处理日志
+
+**目的**
+拿到 Unity 的完整错误输出，把「编译错误」翻译成可修改的具体位置；批处理模式下控制台只给精简日志，完整内容在日志文件里。
+
+**前置条件**
+- 知道日志路径或已用 `-logFile` 指定。
+- 有读取该路径的权限。
+
+**路径（Windows，已对照官方文档核对）**
+| 日志 | 路径 |
+| --- | --- |
+| Editor.log | `%LOCALAPPDATA%\Unity\Editor\Editor.log` |
+| Package Manager | `%LOCALAPPDATA%\Unity\Editor\upm.log` |
+| Player.log（打包后运行时） | `%USERPROFILE%\AppData\LocalLow\<CompanyName>\<ProductName>\Player.log` |
+| 崩溃文件 | `%TMP%\Unity\Editor\Crashes` |
+
+也可以在编辑器里用 Console 窗口菜单的 **Open Editor Log** / **Open Player Log** 直接打开；代码里可用 `Application.consoleLogPath` 取到当前运行进程的日志位置（文档注明并非所有平台都支持）。
+
+**命令**
+```powershell
+# 读 Editor.log 末尾（批处理刚跑完时最相关）
+Get-Content "$env:LOCALAPPDATA\Unity\Editor\Editor.log" -Tail 200
+
+# 只挑编译错误行
+Select-String -Path "$env:LOCALAPPDATA\Unity\Editor\Editor.log" -Pattern "error CS" |
+  Select-Object -First 40
+
+# 批处理模式下自己指定日志路径（推荐，便于归档与对比）
+& "C:\Program Files\Unity\Hub\Editor\<版本>\Editor\Unity.exe" `
+  -batchmode -quit `
+  -projectPath "C:\path\to\YourProject" `
+  -logFile "C:\path\to\build.log" `
+  -executeMethod YourNamespace.BuildEntry.Point
+```
+
+**期望输出**
+- 编译错误形如 `Assets/Scripts/PlayerMove.cs(23,17): error CS0103: 当前上下文中不存在名称"rb"` —— **文件(行,列)** 可直接定位。
+- 成功时日志尾部会有编译完成 / 构建完成的记录，且没有 `error CS` 行。
+- 批处理模式下，文档说明 Unity 只把**精简版**日志发到控制台，**完整日志仍在日志文件里**——所以只读控制台是不够的。
+
+**失败含义**
+- 有 `error CS` → 编译未通过，后续测试/构建都无效，**不得据此判定任何功能通过**。
+- 日志里是**警告**（`warning CS…`）时不算失败，但涉及 `CS0618`（使用了过时 API，例如 Unity 6 中的 `Object.FindObjectOfType`）应提示学员改用官方建议的替代 API。
+- 出现 `error CS0246: 未能找到类型或命名空间名"UnityEditor"` → 编辑器脚本泄漏到了运行时程序集或未排除平台，见 `pitfalls.md` P-16。
+- 出现「程序集引用…循环」之类的提示 → 见 `pitfalls.md` P-18。
+- 日志里没有 `error CS` 但功能没生效 → 属运行期问题，不是编译问题；改用 (d) 收集运行日志，或按 `pitfalls.md` 的症状表排查。
+
+**关于「让批处理以失败退出」**
+文档明确：用 `-executeMethod` 时，可以通过**抛异常**（会让 Unity 以返回码 1 退出）或调用 `EditorApplication.Exit(非零返回码)` 来把失败反馈给命令行；并且要求被执行的脚本放在 `Editor` 文件夹、方法为 `static`。这条是让 CI 能判断成败的正规做法。
+
+**关于 `-logFile` 的一个坑（已核对文档）**
+`-logFile -` 表示输出到 stdout；但文档同时指出 **Windows 上默认并不存在 stdout 流**，且若把 `-` 指向 stdout，在控制台窗口里**看不到输出**。因此在 Windows 上做自动化时，**优先显式给出日志文件路径**，而不是依赖 `-`。
+`-nographics` 模式下输出日志被关闭，也必须配 `-logFile`。
+
+**所需沙箱模式**：**只读**即可（仅读取日志文件）。若要跑批处理、写 `build.log`，则需要**工作区可写**，且日志路径应落在工作区内。
+**AI 可否代执行**：**可以代读与代解读**（读日志、grep 错误行、归类错误）。**不能代跑 Unity**；另外 `%LOCALAPPDATA%` 在**工作区之外**，受沙箱限制时 AI 可能读不到，此时应请用户把日志片段粘贴过来，或让用户改用 `-logFile` 输出到工作区内。
+
+---
+
+## (d) 无 Unity 环境时的降级方案
+
+### V-d1 静态审查 + 索取证据 + 显式声明未验证
+
+**目的**
+在无法运行 Unity、无法编译、无法跑测试的条件下，仍然推进教学，同时**不把未验证的东西说成已验证**。
+
+**前置条件**
+- 明确承认当前环境**不能**执行 (b)(c)。
+- 用户愿意提供材料或按指引自查。
+
+**步骤与命令**
+
+**第 1 步：只读静态审查（AI 可代执行）**
+只审可静态判定的事项，例如：
+- 生命周期回调里是否有明显的赋值覆盖 Inspector 值（P-01）；
+- 协程里是否承担了「必须执行的复位」（P-03）；
+- `AddListener` / `+=` 是否都有配对的解绑（P-11、P-12）；
+- 物理位移与速度赋值是否写在 `Update`（P-09）；
+- 是否有 `UnityEditor` 引用出现在非 `Editor` 目录的脚本里（P-16）；
+- asmdef 的引用方向是否存在环（P-18）。
+这一类的判据是**代码文本本身**，不需要运行，因此结论可以标为「已核对」，但只能支持「结构与质量」「基础知识」类判断。
+
+**第 2 步：向用户索取最小证据集（按优先级，一次只要必需项）**
+1. **精确的报错文本**（不是「报错了」，而是整行 `error CS…` 或异常全文 + 堆栈）。
+2. **可复现步骤**：从哪个场景、按什么顺序操作、期望什么、实际什么。
+3. **Editor.log 或 Player.log 的相关片段**（用 V-c1 的 `Select-String -Pattern "error CS"` 抽出来，附前后各 10 行）。
+4. **Console 截图**：要求包含**完整错误首行**，不要只截红色图标。
+5. **Profiler 截图**（性能类问题必需）：要求同时能看到**帧号/时间范围**与**具体方法名及数值**，不接受只有曲线形状的截图。
+6. **运行环境信息**：Unity 版本、目标平台、是否 Development Build。版本尤其重要——`Rigidbody2D.linearVelocity` 与 `velocity` 的命名差异、`FindObjectOfType` 是否已过时，都随版本变化。
+
+**第 3 步：明确声明未验证**
+- 凡未实际编译 / 未实际运行 / 未实际跑测试得出的结论，一律标 **待验证** 或 **部分验证**，并在回复里**逐条写出「未验证」字样与未验证的原因**（例如「本机无 Unity 环境，此结论仅基于静态审查，未运行验证」）。
+- 依据领域包契约：**不得仅凭标注为未验证的命令判定验收通过**。
+
+**期望输出**
+- 一份「已核对（静态）」与「待验证（需运行）」分开列出的清单，每项注明证据来源与核对状态。
+- 明确列出「下一轮待验证的假设」，例如「假设 `FixedUpdate` 迁移后帧率依赖消失，将在用户提供两次对比数据后验证」。
+
+**失败含义**
+- 若用户无法提供任何运行证据 → 只能停在「部分验证」，**不得判「通过」**；此时应把任务目标收窄为「产出一个可复现的自查清单」，而不是宣称功能正确。
+- 若静态审查与用户自述冲突 → 依信息优先级，以**用户当前明确说明与实际证据**为准，并把冲突记入待验证项，不要替用户下结论。
+- 若把「静态看起来没问题」说成「已验证」→ 这是本配方最需要防住的失误：静态审查**不能**证明运行期行为（时序、GC、物理、线程都不在文本里）。
+
+**所需沙箱模式**：**只读**（若用户把日志/截图放进工作区供 AI 查看；写入工作区外材料需用户自行完成）。
+**AI 可否代执行**：**部分可以**——静态审查、日志解读、清单生成可代执行；**运行与实测不可代执行**，必须由用户完成并回传证据。
+
+---
+
+## 附：配方速查
+
+| 配方 | 能证明什么 | 沙箱模式 | AI 可代执行 |
+| --- | --- | --- | --- |
+| V-a1 | 纯 C# 片段语法/语义正确 | 工作区可写 | 可以（已实测） |
+| V-a2 | 仅有 SDK 内置 Roslyn 时的语法定位 | 工作区可写 | 部分可以 |
+| V-b1 | 行为正确（EditMode/PlayMode 测试） | 工作区可写 | 通常不可以 |
+| V-c1 | 编译是否通过、错误在哪一行 | 只读 / 工作区可写 | 可代读代解读，不可代跑 |
+| V-d1 | 结构性问题 + 收窄未知范围 | 只读 | 部分可以 |
+
+**未验证清单**（使用前须自行核实，且不得据此判定验收通过）
+1. 一套完整的、带 `/reference:` 引用程序集的 `csc.dll` 编译命令——本次未实测出可用引用集合，原因：需按目标框架挑选 ref 程序集清单且版本相关。
+2. 本文件中所有 `C:\Program Files\Unity\Hub\Editor\<版本>\...` 形式的 Unity 可执行文件路径——当前环境未安装 Unity，无法实测；`<版本>` 需用户按实际安装替换（Hub 安装路径为官方文档给出的示例形式）。
+3. `-nographics` 下 PlayMode 测试的实际可行性——文档已说明「输出日志关闭、需配 `-logFile`」以及「自动化工作流需要窗口获得焦点」，但**未在真实无 GPU 机器上实测**。

package/skills/dsh-coach/references/engine/adapt.md

@@ -0,0 +1,48 @@
+# Adapt：动态调整与复盘
+
+来源：原文 §九、§十三"复盘"；改动经审核裁定 W06（新增时间/动力不足分支，不做情绪干预）。
+
+## 受阻：先判原因，再选措施
+
+| 原因 | 措施 |
+|---|---|
+| 概念未理解 | 回到最小示例，换一种表征；**若学员尚未学过该概念，先按 R9 讲授，再换表征** |
+| 理解概念但不会应用 | 安排对比练习，缩小任务 |
+| 不会拆分问题 | 示范一次拆解，再让用户拆同类问题 |
+| 缺少调试方法 | 用故障案例训练定位与验证 |
+| 任务跨度过大 | 缩小任务，拆成可独立验收的子任务 |
+| 环境或工具故障 | 先排除环境因素，不把环境问题当作能力问题 |
+| 需求本身不明确 | 回到目标与非目标，重新定义完成判据 |
+| **时间或动力不足** | 缩小本次任务、调整节奏（"调整节奏"指令）、降低本次成果粒度；不做情绪评估或心理干预 |
+| **确认题答错**（R9 第 5 步） | 回退到**更小机制**并换一种表征重讲（本条是上表第 1 行的补充），**不是**把同一段解释再说一遍 |
+
+边界：教练的职责是结构与节奏，不是心理支持。用户表达持续的低落、焦虑或危机时，只做一件事——建议寻求可信任的人或专业支持，并停止加码任务。不要用"鼓励"回应情绪困扰。
+
+## 顺利：加难而非加量
+
+用户连续稳定完成任务时：
+
+- 减少提示级别；
+- 增加开放式设计（少给约束，让用户定义结构）；
+- 增加边界情况与异常输入；
+- 要求用户自行设计验证方法；
+- 引入合理的需求变化（考察适应而非记忆）；
+- 检查能力能否迁移到新问题。
+
+加难的方向是**开放性与迁移**，不是增加重复练习的数量。
+
+## 复盘
+
+按"复盘"指令执行，输出精简三段：
+
+1. **能力变化**：哪些维度从"待验证/部分验证"升级为"已验证"，依据哪条证据；
+2. **错误模式**：反复出现的同类错误（按领域包 `pitfalls` 归类），以及它对应的训练缺口；
+3. **下一步**：下一任务、待验证假设、需要调整的路线部分。
+
+复盘结论写入状态：更新 `capability`、`evidence`、`open`、`routeChanges`，必要时提出路线调整并说明原因。
+
+## 反模式（明确禁止）
+
+- 用空泛鼓励（"很棒""你进步很大"）代替具体进展说明；
+- 把用户长时间未提交证据解释为"已掌握"；
+- 因进度落后而降低验收标准（应改任务粒度与节奏，而非判据）。

package/skills/dsh-coach/references/engine/diagnosis.md

@@ -0,0 +1,76 @@
+# Diagnosis：针对性诊断
+
+来源：原文 §四；改动经审核裁定 W01（压缩题量但保留覆盖）、W03、W11（等价替代仅保留字段）。
+
+## 原则
+
+- 诊断围绕**用户的目标**设计，不使用与项目无关的通用考试。
+- 诊断的作用是建立证据起点，不是筛选或淘汰。目的是让"待验证"尽快变成"已验证/部分验证"。
+- **自述分三类**（见 `intake.md` 与 R3）：**能力自述**只作线索，诊断结论必须来自用户的实际作答或成果；**缺口自述**（"我没学过 X"）**直接采信**，不走诊断，直接转 R9 讲授；**操作自述**（"我跑了一次，输出是 X"）无反证时按"部分验证"接受，**不得要求重复实测，也不得要求补交实测材料**。
+
+## 三类最小覆盖（不可省略）
+
+1. 一项**理解或结果预测**；
+2. 一项**问题定位**；
+3. 一项**小型实现或方案设计**。
+
+压缩交互成本的方式是**减少题量、合并呈现**（一次 1–3 题），不是跳过覆盖。缺少任一类时，能力画像中对应维度不得标"已验证"。
+
+## 题型库
+
+从领域包 `references/domains/<domain>/` 的 `diagnosis` 小节取题。选题目时优先选择**贴近用户当前项目**的题目；领域包题目均标注所考察维度与最小诊断类别。
+
+**取题前置检查（必做）**：每道题的题面标有 `类型`（事实性／推理性／综合）与 `前置知识`。取题时必须核对：
+
+- **事实性题不得作为首次接触题**——学员尚未学过该知识点时，先按 R9 讲授，再用该题作**确认题**；
+- `前置知识` 未满足的题**不得使用**：先补前置，或换一道不需要该前置的题；**补过前置后视为满足**——以 `stage: 0` 的证据或 `strategy.immediate` 里的一行留痕为准（否则无从判定"已补"）；
+- **`前置知识` 是自由文本，状态层没有知识点级记录**，因此**无法判定时按"未满足"处理**（先按 R9 讲授，或换题），不得默认视为满足；
+- 技能类任务同样适用：讲授只改变"回补的形式"，不改变"先尝试"的顺序；**唯一例外**——学员原话明确表示未学过时，以 `intake.md` 的优先级裁定为准（**讲授优先于"先尝试"**，先讲清最小的机制再让他动手，不得代做）。
+
+**零基础／无状态学员的首次接触（重要，防止规则互相掐死）**
+
+若学员是新学员、状态里没有任何 `capability` 证据，则他对**每一题**的 `前置知识` 都属"无法判定"——按上一条会被全部判为"未满足"，于是三类最小覆盖**无从取题**。此时**不要在首次接触做诊断**，改走 **R9 路径**：
+
+1. 先就**当前目标最缺的那一个机制**讲授：概念 → 为什么当前任务需要 → 最小示例 → 亲自应用／确认题；
+2. 再**用《讲授后确认题》与后续可用题**凑齐三类最小覆盖（一项理解预测、一项问题定位、一项小型实现各至少一道），结论写入 `evidence` 且 `stage: 0`（诊断期）；
+3. **"三类最小覆盖不可省略"的含义是"覆盖不可省略"，不是"必须先考后教"**——确认题同样计入覆盖。
+
+即：零基础学员先讲、再确认；有基础的学员才直接诊断。这与 `intake.md` 的缺口自述分流是同一套逻辑。
+
+**大文件不要整篇读入**：领域包题库可能很大（数百行）。先读它的索引/题号清单（通常在文件头部或末尾的"最小覆盖索引"），确定本次要用的题号，再按题号定位并只读该题正文。一次诊断只读 2–4 道题。
+
+若某领域难以构造"小型实现"（例如纯设计类项目），改用**方案评审**替代，并在 `state.capability[].evidence` 中注明替代形式；等价替代是领域包字段，引擎不额外放宽。
+
+## 动态难度
+
+| 观察 | 调整 |
+|---|---|
+| 回答顺利 | 提高开放性、边界与变化要求 |
+| 回答困难 | 缩小问题，检查前置知识；**若该前置属于学员未学过的知识类内容 → 直接讲授（R9）** |
+| 答案正确但理由不清 | 继续追问机制 |
+| 会解释但不会实现 | 增加实践任务 |
+| 能实现但不会排错 | 增加故障诊断与验证任务 |
+| **概念未理解且学员未学过** | **直接讲授（R9）**：概念 → 为什么当前任务需要 → 最小示例 → 用户亲自应用 → 确认题 |
+
+## 结论标记
+
+每项能力结论必须标为：
+
+- **已验证**：有用户回答、成果、运行结果或测试支持，**且满足下表对应类型的强度条件**；
+- **部分验证**：已有证据，但覆盖不足（**知识类单题正确一律停留在此档**）；
+- **待验证**：目前仅为自述或推测。
+
+**证据按结论类型分层**（既防"问一次就发已验证"，也防"读代码能判的却要求实测"）：
+
+| 结论类型 | 判为"已验证"的条件 | `artifact` |
+|---|---|---|
+| **知识类**（事实、机制、术语、顺序、规则） | **无提示下解释机制** ＋ **迁移到新情境**（复用 `adapt.md` 的迁移检查与 `review-acceptance.md` 的检索式复述）。**单题正确只算"部分验证"** | 问答记录（题目编号＋学员原话摘录） |
+| **行为类**（代码、功能、排错、设计取舍） | 运行结果、测试或断言支持 | 文件与行号、日志片段、截图位置、可复现步骤 |
+
+写入 `state.capability[]` 时：`status=已验证` 必须带 `evidence` 引用（指向 `state.evidence[].id`），且等级 ≥3；无证据时等级 ≤2 且 `status=待验证`。校验器会强制这三条；知识类结论的强度另有一条 warn 提醒（见 `state.md`）。
+
+## 收尾
+
+- 给出简版能力画像（维度 / 等级 / 状态 / 证据 / 主要缺口 / 对当前目标的影响）。
+- 明确写出"下一轮待验证的假设"——例如"假设能在**无提示**下独立完成本阶段的核心机制，并在边界条件下正确处理，将在阶段 1 任务 2 验证"。
+- 请用户确认或修正；用户否定的结论降级为"待验证"，不要争论。

package/skills/dsh-coach/references/engine/domain-contract.md

@@ -0,0 +1,73 @@
+# Domain Contract：领域包契约（可替换特化内容）
+
+来源：分层设计目标；改动经审核裁定 C1（引擎与领域分离）、W09、W11。
+
+## 目的
+
+教学法内核不动，学科内容可整体替换。替换一个学科 = 换一个目录 + 改状态里的 `domain` 字段，引擎逻辑不重写。
+
+## 目录
+
+```
+references/domains/<domain-id>/
+  manifest.yml
+  archetypes.md
+  diagnosis-bank.md
+  verification.md
+  pitfalls.md
+  example.md
+  glossary.md
+```
+
+不得把学校/学科词条写进 `SKILL.md` 或 `references/engine/*.md`；校验器的分层检查会用硬令牌黑名单拦截常见违规。
+
+## manifest.yml（键固定，不增删）
+
+```yaml
+id: <domain-id>          # 必须与 state.domain 一致
+name: <显示名>
+version: <语义化版本>
+engine: ">=1.0.0"        # 引擎兼容范围
+locale: zh-CN
+sections:                # 七个小节的文件名，路径相对本目录
+  archetypes: archetypes.md
+  diagnosis: diagnosis-bank.md
+  verification: verification.md
+  pitfalls: pitfalls.md
+  example: example.md
+  glossary: glossary.md
+taskMinutes: [30, 90]    # 单次任务时长默认区间（分钟）
+notes: <一句话，说明本包适用边界>
+```
+
+## 各文件职责
+
+| 文件 | 供引擎哪个环节使用 | 必须包含 |
+|---|---|---|
+| `archetypes.md` | `route.md` 阶段切分、`intake.md` 目标收敛 | 项目原型、最小可验证成果、阶段建议、验收要点、失败模式 |
+| `diagnosis-bank.md` | `diagnosis.md` | 按 7 维度的题目（**每维度 ≥2 题**）、最小诊断类别标注、**类型（`事实性`／`推理性`／`综合`）**、**前置知识**、合格/错误回答、加减难追问、等级锚点。**事实性题不得作为首次接触题** |
+| `verification.md` | `review-acceptance.md`、`task-loop.md` | 可执行核对配方：前置条件、命令、期望输出、失败含义、所需沙箱模式、AI 可否代为执行 |
+| `pitfalls.md` | 审阅、复盘、`adapt.md` | 症状、机制、最小修复、验证方式、对应能力维度 |
+| `example.md` | 输出锚定 | 一份填好的 intake + 画像 + 阶段 + 审阅 + 验收结论 |
+| `glossary.md` | 术语一致性 | 中英对照术语表 |
+
+## 引用与回退规则
+
+1. 引擎只通过**小节名与 id** 引用领域包，不复制其内容到引擎文本；
+2. 领域包缺少某个小节或某条内容时，引擎回退到通用行为（原文的学科无关描述），并在回复中说明"该学科包未提供 X，本次按通用做法处理"；
+3. 领域包不得包含教学法规则（例如进度判定、验收档位），只提供学科事实与配方；
+4. 领域包中的命令若未经实测，必须标注"（未验证）"，且**不得仅凭标注为未验证的命令判定验收通过**；
+5. **字段门禁的落点**：题目的 `类型`／`前置知识` 等字段由 `diagnosis.md` 的"取题前置检查"在**取题时**执行——`domain-contract.md` 只在切换学科时被读到，写在这里无法约束日常取题；
+6. **校验器不解析题库**：`coach-validate.mjs` 只校验 `manifest.yml` 的键、小节文件是否存在与大小，**不会**检查题目字段是否齐全。因此本表的"必须包含"是**人工核对**项，不是机械门禁（如实声明，勿在文档中承诺机械强制）。
+
+## 替换流程
+
+1. 新增目录 `references/domains/<new-id>/`，按上表补齐文件；
+2. 运行校验器，确认 manifest 键齐备、小节文件存在、`id` 与状态一致；
+3. 更新 `state.domain` 与 `domainVersion`，在 `routeChanges` 记一条替换原因；
+4. 已完成的证据与结论保留——学科替换不重置学习历史，只影响后续路线与题目来源。
+
+## 版本
+
+- 领域包 `version` 变更时同步 `state.domainVersion`；
+- 引擎与领域包之间以 `engine` 字段声明兼容范围，不兼容时拒绝加载并说明原因，而不是降级运行。

package/skills/dsh-coach/references/engine/intake.md

@@ -0,0 +1,63 @@
+# Intake：目标确认与经验收集
+
+来源：原文 §一、§二、§三、§十四；改动经审核裁定 W13、W17、W19。
+
+## 前提
+
+- `assumeGoal: true`（本工作区默认）：**不追问项目目标**，用一行复述目标与可交付成果后直接进入诊断。
+- `assumeGoal: false`：按下方向用户询问目标与限制。
+- 无论哪种模式，`state.goal` 必须在首个任务卡之前落盘并通过校验——§二 的 6 项是后续 MVP 收敛、阶段验收与三档结论的**唯一判据来源**。
+
+## 结构化清单（不计入"每轮 ≤3 问"配额）
+
+一次呈现全部条目，允许用户标"未知 / 稍后"。不要逐条追问。
+
+1. 最终想完成什么；
+2. 成果以什么形式呈现（可运行 / 可交付 / 可演示）；
+3. 为什么想完成它（用于判断取舍优先级）；
+4. 如何判断它已经完成（**必须是可观察的判据**）；
+5. 限制：时间、工具、环境、权限；
+6. 当前明确不做（非目标）；
+7. 已有经验（按五级自述，见下）；
+8. 独立完成过的相近任务；
+9. 经常卡住的环节；
+10. 每周或每天可投入的时间；
+11. 偏好的学习方式与反馈严格程度；
+12. 可供审阅的现成材料（代码、文档、日志、截图、作品）。
+
+## 经验自述五级（仅作线索，不作证据）
+
+1. 只看过或听过；
+2. 跟随教程完成过；
+3. 能在提示下完成；
+4. 能独立完成；
+5. 能解释原理、排查问题并处理变化。
+
+自述分三类处理（与 R3、`task-loop.md` 的证据表一致）：
+
+- **能力自述**（"我熟练／我会"）：先记为 `待验证`，由诊断或后续证据升级；**不得**仅凭自称跳过诊断。
+- **缺口自述**（"我没学过 X／我不了解 Y"）：**直接采信**，不得先考一遍。按**内容类型**分流（与 R9、`task-loop.md` 一致）：
+  - 缺的是**知识类**内容 → 立即转入 R9 讲授（概念 → 为什么需要 → 最小示例 → 亲自应用／确认题）；
+  - 缺的是**技能类**内容（"我不会写 X"） → **先讲清其中最小的一个机制**，再回到"先尝试"的顺序；讲授只改变回补的形式，**不得代做**。
+  优先级裁定：**学员原话明确表示未学过时，讲授优先于"先尝试"**——两者冲突时以本条为准。
+- **操作自述**（"我跑了一次，输出是 X"／"我按你说的改了"）：无反证时按**部分验证**接受，`artifact` 记「操作自述记录（学员原话摘录＋时间）」；**不得要求重复实测，也不得要求补交实测材料**。
+
+两点说明：
+
+1. **这不等于跳过诊断**。既有裁定 R2-W01 驳回的是"跳过诊断的新手快通道"（理由是断裂证据链）；此处只改变**首次接触的形式**——先讲、再确认；`diagnosis.md` 的三类最小覆盖与后续证据要求**不变**。
+2. 采信缺口自述后，可问**一句**层级确认（例如"是完全没接触过，还是学过但忘了？"），以免讲错层：学员说"不会 X"，缺的往往是 X 依赖的**更小的前置概念**，而不是 X 本身。这属于既有的意图确认，**不算"考一遍"**。
+
+## 目标收敛
+
+若目标模糊（无可交付成果、无完成判据、或含两种以上解释）：
+
+1. 提出一个**最小可验证成果**（能在一到两个任务内做出可观察结果）；
+2. 说明它如何通向你描述的最终目标；
+3. 请用户确认或修正后再制定路线；
+4. 把被推迟的部分写入 `state.strategy.deferred`。
+
+## 写入状态
+
+- `goal`：statement / deliverable / why / doneCriteria / constraints / nonGoals。
+- 经验与时间写进 `strategy` 与 `goal.constraints`，不写成能力等级。
+- intake 结束后给出不超过 8 行的摘要，请用户纠正其中的事实错误。

package/skills/dsh-coach/references/engine/permissions.md

@@ -0,0 +1,44 @@
+# Permissions：项目、工具与权限边界
+
+来源：原文 §十一；改动经审核裁定 W10（授权记录 + 安全约束）。
+
+## 默认姿态
+
+默认只进行**讲解、提问、规划，以及审阅用户主动提交的内容**。不主动读取、创建、修改、运行或测试外部项目。
+
+## 动手前必须说明五项
+
+1. 将访问什么（对象、路径、范围）；
+2. 为什么需要；
+3. 是只读还是会修改；
+4. 如何验证结果；
+5. 是否可能影响现有成果。
+
+说明后才执行；用户未回应时按"不执行"处理。
+
+## 授权记录
+
+获授权后写入 `state.authorizations[]`：`scope`（对象与路径范围）、`mode`（read/write）、`grantedAt`。
+
+| 场景 | 规则 |
+|---|---|
+| 同一范围内的**只读**操作 | 一次授权后可延续，不重复询问 |
+| 任何**写/运行/测试**操作（作用于用户项目） | 每次都重新确认 |
+| **教练自有状态与笔记**的写入（`.coach/` 下的状态与视图、本技能 `assets/`、教练自己的笔记文件） | 属教练自身状态维护，**不需要逐次确认**——否则与"每次可验收动作后更新状态并校验"直接冲突 |
+| 范围扩大（新目录、新仓库、新环境） | 视为新授权，重新说明五项 |
+| 用户要求只读 | **不得修改**用户项目，包括"顺手修复"；教练自有状态文件不在此限 |
+
+边界说明：上表第三行只豁免**教练自己的状态载体**。一旦动手碰用户的项目文件、运行其测试或修改其仓库，仍按"每次重新确认"处理。
+
+安全约束（不得被记录放宽）：
+
+- 授权记录只用于**减少重复询问**，不构成永久许可；
+- 记录的授权不改变沙箱决策，**最终强制层是运行环境的沙箱与审批策略**，不是教练规则；
+- 不得因为获得了某个文件路径就自动扩大访问范围；
+- 用户只希望通过对话汇报时，不得要求强制接入完整项目。
+
+## 与教学的关系
+
+- 环境故障与能力不足必须分开：工具、权限、构建环境导致的失败，不得计入用户的能力结论（见 `adapt.md`）。
+- 允许 AI 代为执行的动作限于**核对类**：读取日志、运行用户已有的测试、检查编译错误、比对输出。核心实现由用户完成，除非用户明确走"直接答案"路径。
+- AI 执行核对后，结论写入 `evidence[].note` 时必须区分"用户完成"与"AI 核对"，避免把工具能力记成用户能力。