dsh-project-based-learning 1.1.0

package/docs/zero-knowledge-path.zh.md

@@ -0,0 +1,60 @@
+# 零基础路径回归清单
+
+> **用途**：本次教学缺陷修复（引擎 1.1.0 / R9·R10）的验收与回归清单。
+> 每条给出「触发 → 必须出现 → 禁止出现 → 机械化程度」，可在真实会话中逐条核对。
+> **来源**：使用者反馈的三条缺陷（只问不教／过度要求实测／该教的让人自己悟）＋ 第 1 轮三份独立审核的最小加固要求。
+
+## 为什么需要它
+
+上一版引擎的失败不是"规则实现错了"，而是**散文规则在真实对话里被误用**：条款自洽、机械校验全绿、CI 全绿，但学习者体验是坏的。因此修复必须配一份**面向行为的清单**，并且明确哪些项**机械能拦**、哪些项**只能人工核对**。
+
+## 清单
+
+| # | 触发场景 | 必须出现 | 禁止出现 | 机械化程度 |
+|---|---|---|---|---|
+| **Z1** | 学员说「我没学过 X／我不了解 Y」（缺口自述） | 直接进入 **R9 讲授**：概念 → 为什么当前任务需要 → 最小示例 → 用户亲自应用 → 确认题 | 先出诊断题；把缺口自述记成"待验证"后继续考 | 部分：状态中应出现该知识点的问答记录（`stage: 0`） |
+| **Z2** | 内容是**事实性知识**且满足 R9 条件③ 的 (a)(b)(c)（API 名称与签名、调用与执行顺序、语言与类型规则、文档已明的默认值） | 讲授 + 确认题 | 要求**实测**——**R10 例外成立时除外**：文档未覆盖／自相矛盾／版本差异时仍须实测，且必须先给出所依据的文档章节或行号 | 间接：由 Z6/Z7 的证据类型规则约束 |
+| **Z3** | 任何一次要求实测之前 | 说明"为什么这一点无法从代码或文档判定"，并**给出所依据的文档章节或文件行号** | 无理由的实测要求；只说"你跑一下看看" | 部分：知识类结论出现实测要求即可判违规 |
+| **Z4** | 学员说「我跑了一次，输出是 X」／「我按你说的改了」（操作自述） | 按**部分验证**接受，继续推进 | 就同一件事**再次**要求实测；要求补交截图等实测材料 | 部分：同一结论下不应出现重复的实测要求 |
+| **Z5** | 技能类任务（写代码、排错、设计、拆解） | 仍按 R1／R2 **先让学员动手**；R9 只改变"回补的形式" | 因 R9 把技能任务改成"我讲完你照着敲"；让学员跳过亲手实现 | 机械：`route[].userOnly` 非空且验收时逐项核对 |
+| **Z6** | 知识类结论要标"已验证" | **无提示下解释机制 ＋ 迁移到新情境**（检索式复述／迁移检查） | **单题正确即标"已验证"** | 部分：校验器 `ST-W7` warn（**只提醒、不拦截**）；强制力靠本清单 |
+| **Z7** | 行为类结论要标"已验证" | 运行结果、测试或可核对材料（文件与行号／日志／截图／复现步骤） | 用**问答记录**充当行为类结论的证据 | 部分：`artifact` 不得是占位符；类型匹配靠人工 |
+| **Z8** | 一次讲授 | **一个机制 ＋ 一个最小示例**；讲完必须回到一次学员产出 | 整章式讲课；讲完不出确认题；"讲 2 点→确认题→再讲 2 点"式循环 | 人工核对 |
+| **Z9** | 确认题答错 | **回退到更小机制**并换一种表征重讲 | 把同一段解释再说一遍；直接给答案了事 | 人工核对 |
+| **Z10** | 三条 R9 触发都不成立时 | 一律走 **R1／R2**（先做后教、分级提示） | 把 R9 当加速项，逢题就讲 | 人工核对 |
+
+## 在真实会话里怎么用
+
+1. **Z1／Z2 判据**：对教练说
+   > 我完全没学过 Unity 的生命周期，请评估我的水平。
+
+   若它先出题（例如"预测下面脚本的 Console 输出顺序"）而不是先讲，**Z1 失败**。反过来，若它讲完却不给确认题，**Z8 失败**。
+
+2. **Z3 判据**：任何一次被要求实测时，检查是否给出了"为什么无法从代码或文档判定"以及文档章节／行号。没有 → 违规。
+
+3. **Z4 判据**：说
+   > 我按你说的跑过了，输出是 A B C D。
+
+   若它仍要求你再跑一次、或要你补截图 → 违规。
+
+4. **Z5 判据**：进入实现类任务后，确认代码仍由学员本人写、本人运行（`route[].userOnly` 逐项核对）。
+
+5. **Z6／Z7 判据**：跑校验器，看是否有 `ST-W7` 提醒：
+
+   ```bash
+   node skills/dsh-coach/scripts/coach-validate.mjs --state .coach/state.json
+   ```
+
+   > `ST-W7` 是 **warn，不是门禁**（CI 退出码只看 error）。这是 2.1 修订的明确取舍：漏报的代价是"可能漂移"（有本清单兜底），误报的代价是每次正常教学都被阻塞。
+
+6. **Z8／Z9／Z10 判据**：翻一遍对话记录，数一次讲授覆盖了几个机制、讲完学员做了什么、答错后是"换表征"还是"重复同段"。
+
+## 机械化覆盖边界（如实声明）
+
+- **机械能拦**：`userOnly` 非空、`artifact` 非占位符、`stage ≥ 0`、`ST-W7` 提醒（不拦截）；
+- **只能人工核对**：Z1、Z2、Z3、Z8、Z9、Z10 属**对话质量**；Z6、Z7 的类型匹配也无法机械判定（`artifact` 是自由文本）；
+- 因此：**"校验通过"不等于"教学合格"**——与 `state.md` 的既有声明一致。本清单**每阶段**跑一次，而不是每次落盘都跑。
+
+## 变更历史
+
+- **2026-03-09 定稿**：随引擎 1.1.0 发布。依据第 1 轮三份独立审核（`docs/review-round1-A-edu.zh.md`、`-B-eng.zh.md`、`-C-bounded.zh.md`）的最小加固要求编写；审核指出的加固项已逐条落入 Z1（层级确认与"不得先考"）、Z3（必须给出文档依据）、Z5（技能类排除下沉到知识点级）、Z8（讲授单元）、Z10（默认条款）。

package/examples/PROGRESS.demo.md

@@ -0,0 +1,72 @@
+# 学习进度
+
+> 本文件由 `examples\state.demo.json` 自动生成，**请勿手工编辑**；冲突时以该状态文件为准。
+> revision 7 ｜ 更新于 2026-03-08T20:15:00.000Z ｜ 领域包 unity-csharp@1.1.0
+
+## 目标
+- 目标：独立做出一个可玩、可演示的 2D 平台跳跃小样，并说清每一处实现的机制与取舍
+- 可交付成果：一个可运行的小样：3 个关卡片段、角色移动与跳跃、敌人碰撞伤害、简单 HUD（血量与计时）
+- 为什么：用于申请校内游戏开发社团的作品展示，并作为后续 3D 项目的基础训练
+- 完成判据：能在 Unity 编辑器中连续游玩 3 分钟无报错、无卡死；能脱离教程从零重建角色控制器并解释每个参数的作用；能自行定位并修复至少一类运行时错误
+- 当前非目标：联机功能；美术资源自制（使用免费素材）；发布到应用商店
+- 限制：时间 每天约 45 分钟，周末可到 90 分钟｜工具 Unity 6 LTS、VS Code、Git（本地仓库）｜环境 Windows 笔记本，无独立显卡，帧率以 60 为上限｜权限 教练只读访问 workspaces/2d-platformer/，运行测试需逐次确认
+
+## 能力画像
+| 维度 | 等级 | 状态 | 证据 | 主要缺口 | 对当前目标的影响 |
+|---|---:|---|---|---|---|
+| 基础知识 | 3 | 部分验证 | E1 | 对协程与 Update 的取舍仍不稳定 | 会影响后续状态机与技能系统的设计 |
+| 实际应用 | 3 | 已验证 | E2 | 尚未独立接过完整功能模块 | 阶段 2 可直接进入功能实现 |
+| 问题拆解 | 2 | 部分验证 | E3 | 拆解依赖提示，缺少自主分层习惯 | 复杂需求需要先示范一次拆解 |
+| 调试与纠错 | 2 | 部分验证 | E4 | 只看第一条报错，缺少日志定位方法 | 任务 3 中已安排故障诊断训练 |
+| 结构与质量 | 2 | 待验证 | — | 尚无独立设计的组件边界样本 | 阶段 2 需引入组件拆分练习 |
+| 独立程度 | 2 | 部分验证 | E2 | 遇到新 API 时倾向先要答案 | 提示级别需从 3 级起，逐步降到 1 级 |
+| 解释与迁移 | 1 | 待验证 | — | 复述不完整（见 retrievalRecap） | 阶段 2 验收将加强检索式复述 |
+
+## 当前阶段与任务
+- 阶段 1：最小可玩闭环：移动 + 跳跃 + 落地 ｜ 状态：已通过
+- 可交付成果：可在编辑器中操作的角色，能左右移动、接地起跳、稳定落地
+- 用户必须亲自完成：亲手写出角色控制脚本的输入读取与跳跃判定（不得整段复制现成实现）；亲手在编辑器中挂载组件、设置参数并运行验证
+- 验收标准：角色可左右移动，速度参数在 Inspector 中可调；仅在接地状态下按跳跃键才起跳，空中不可二段跳；连续跳跃 20 次无穿模、无抖动、Console 无报错
+- 本次任务：任务 3：接地检测与调试（已通过，约 50 分钟）
+- 完成标准：接地判定在斜坡与边缘处不误判；提交一份包含报错日志与修复前后对照的定位记录
+- 检索式复述：用户在不看资料的情况下复述了 Awake→OnEnable→Start→FixedUpdate→Update→LateUpdate 的执行顺序、为什么物理应放在 FixedUpdate，以及“在 Update 中直接改 Transform 造成抖动”这一失败模式；对 LateUpdate 与相机跟随的关系表述不完整，已记为待验证。
+
+## 路线
+| 阶段 | 名称 | 可交付成果 | 预计投入 | 通过后进入 |
+|---|---|---|---|---|
+| 1 | 最小可玩闭环：移动 + 跳跃 + 落地 | 可在编辑器中操作的角色，能左右移动、接地起跳、稳定落地 | 3 次任务，每次约 45 分钟 | 阶段 2：敌人与伤害循环 |
+| 2 | 敌人与伤害循环 | 会巡逻的敌人、接触扣血、血量 HUD 与重生点 | 4 次任务，每次约 45 分钟 | 阶段 3：关卡与演示打磨 |
+
+## 证据
+| id | 阶段 | 支持结论 | 材料 | 强度 |
+|---|---:|---|---|---|
+| E1 | 1 | 能说明物理更新与帧更新的分工，并预测在 Update 中直接改 Transform 的后果 | notes/diagnosis-01.md 第 2 题作答 + 用户手绘的时序草图 | 部分验证 |
+| E2 | 1 | 独立完成角色左右移动与接地跳跃，参数可在 Inspector 调整 | workspaces/2d-platformer/Assets/Scripts/PlayerController.cs（1–88 行）+ 运行录屏 2026-03-06 | 已验证 |
+| E3 | 1 | 能把“角色不响应输入”拆成输入层、状态层、物理层三段排查 | notes/task-03-拆解.md（用户手写，含三段排查顺序） | 部分验证 |
+| E4 | 1 | 定位并修复一次空引用报错，能说明触发条件 | logs/console-2026-03-07.txt 第 14 行报错 + 修复前后代码对照 | 部分验证 |
+
+## 已完成任务
+- 阶段 1 任务 1：读取输入并驱动刚体（2026-03-04，证据 E2）
+- 阶段 1 任务 2：跳跃条件与重力参数（2026-03-05，证据 E2）
+- 阶段 1 任务 3：接地检测与调试（2026-03-07，证据 E4）
+
+## 待解决项
+- [重要] O1：跳跃高度在不同帧率下不一致（疑似物理更新与帧更新混用） → 阶段 2 任务 1 中安排一次帧率相关排查，并要求用户自行给出验证方法
+
+## 教学策略
+- 暂缓：对象池与性能优化；编辑器扩展；网络同步
+- 即时补齐：Transform 与物理更新的分工；用 Debug.Log 与断点定位问题
+- 练习方式：每完成一个功能，用 3 句话说明输入—处理—输出的数据流
+- 待验证假设：假设能在无提示下写出接地检测（阶段 2 任务 1 验证）；假设已掌握基本的 Git 提交习惯（下次提交时验证）
+
+## 路线变更
+- 2026-03-02T19:40:00.000Z：取消原阶段 1（语法基础），直接进入最小可玩闭环；路线由 4 阶段压缩为 3 阶段（原因：诊断显示已掌握变量、条件、循环与函数基础，原定“C# 语法基础”阶段不必要）
+
+## 直接答案记录（不计入能力证据）
+- 2026-03-04T20:05:00.000Z：协程与 Update 的取舍（用户请求直接给答案）
+
+## 权限授权记录
+- 2026-03-03T19:10:00.000Z｜read｜workspaces/2d-platformer/（只读）
+
+## 下一步
+阶段 2 任务 1：敌人巡逻与朝向（先由用户给出巡逻实现思路与验证方法）

package/examples/state.demo.json

@@ -0,0 +1,185 @@
+{
+  "schemaVersion": "1.0",
+  "engineVersion": "1.1.0",
+  "domain": "unity-csharp",
+  "domainVersion": "1.1.0",
+  "assumeGoal": true,
+  "revision": 7,
+  "updatedAt": "2026-03-08T20:15:00.000Z",
+  "goal": {
+    "statement": "独立做出一个可玩、可演示的 2D 平台跳跃小样，并说清每一处实现的机制与取舍",
+    "deliverable": "一个可运行的小样：3 个关卡片段、角色移动与跳跃、敌人碰撞伤害、简单 HUD（血量与计时）",
+    "why": "用于申请校内游戏开发社团的作品展示，并作为后续 3D 项目的基础训练",
+    "doneCriteria": [
+      "能在 Unity 编辑器中连续游玩 3 分钟无报错、无卡死",
+      "能脱离教程从零重建角色控制器并解释每个参数的作用",
+      "能自行定位并修复至少一类运行时错误"
+    ],
+    "constraints": {
+      "time": "每天约 45 分钟，周末可到 90 分钟",
+      "tools": "Unity 6 LTS、VS Code、Git（本地仓库）",
+      "environment": "Windows 笔记本，无独立显卡，帧率以 60 为上限",
+      "permissions": "教练只读访问 workspaces/2d-platformer/，运行测试需逐次确认"
+    },
+    "nonGoals": [
+      "联机功能",
+      "美术资源自制（使用免费素材）",
+      "发布到应用商店"
+    ]
+  },
+  "capability": [
+    { "dimension": "基础知识", "level": 3, "status": "部分验证", "evidence": ["E1"], "gap": "对协程与 Update 的取舍仍不稳定", "impact": "会影响后续状态机与技能系统的设计" },
+    { "dimension": "实际应用", "level": 3, "status": "已验证", "evidence": ["E2"], "gap": "尚未独立接过完整功能模块", "impact": "阶段 2 可直接进入功能实现" },
+    { "dimension": "问题拆解", "level": 2, "status": "部分验证", "evidence": ["E3"], "gap": "拆解依赖提示，缺少自主分层习惯", "impact": "复杂需求需要先示范一次拆解" },
+    { "dimension": "调试与纠错", "level": 2, "status": "部分验证", "evidence": ["E4"], "gap": "只看第一条报错，缺少日志定位方法", "impact": "任务 3 中已安排故障诊断训练" },
+    { "dimension": "结构与质量", "level": 2, "status": "待验证", "evidence": [], "gap": "尚无独立设计的组件边界样本", "impact": "阶段 2 需引入组件拆分练习" },
+    { "dimension": "独立程度", "level": 2, "status": "部分验证", "evidence": ["E2"], "gap": "遇到新 API 时倾向先要答案", "impact": "提示级别需从 3 级起，逐步降到 1 级" },
+    { "dimension": "解释与迁移", "level": 1, "status": "待验证", "evidence": [], "gap": "复述不完整（见 retrievalRecap）", "impact": "阶段 2 验收将加强检索式复述" }
+  ],
+  "strategy": {
+    "deferred": ["对象池与性能优化", "编辑器扩展", "网络同步"],
+    "immediate": ["Transform 与物理更新的分工", "用 Debug.Log 与断点定位问题"],
+    "practice": ["每完成一个功能，用 3 句话说明输入—处理—输出的数据流"],
+    "assumptions": [
+      "假设能在无提示下写出接地检测（阶段 2 任务 1 验证）",
+      "假设已掌握基本的 Git 提交习惯（下次提交时验证）"
+    ]
+  },
+  "route": [
+    {
+      "n": 1,
+      "name": "最小可玩闭环：移动 + 跳跃 + 落地",
+      "deliverable": "可在编辑器中操作的角色，能左右移动、接地起跳、稳定落地",
+      "nonGoals": ["美术表现", "音效", "多关卡"],
+      "skills": ["实际应用", "调试与纠错", "独立程度"],
+      "prereq": ["Rigidbody2D 与碰撞体的基本概念"],
+      "tasks": ["读取输入并驱动刚体", "跳跃条件与重力参数", "接地检测与调试"],
+      "userOnly": [
+        "亲手写出角色控制脚本的输入读取与跳跃判定（不得整段复制现成实现）",
+        "亲手在编辑器中挂载组件、设置参数并运行验证"
+      ],
+      "acceptance": [
+        "角色可左右移动，速度参数在 Inspector 中可调",
+        "仅在接地状态下按跳跃键才起跳，空中不可二段跳",
+        "连续跳跃 20 次无穿模、无抖动、Console 无报错"
+      ],
+      "risks": ["把物理更新写进 Update 导致抖动", "接地检测用碰撞体中心点判断而漏检"],
+      "estimate": "3 次任务，每次约 45 分钟",
+      "next": "阶段 2：敌人与伤害循环"
+    },
+    {
+      "n": 2,
+      "name": "敌人与伤害循环",
+      "deliverable": "会巡逻的敌人、接触扣血、血量 HUD 与重生点",
+      "nonGoals": ["敌人 AI 寻路", "多类型敌人"],
+      "skills": ["问题拆解", "结构与质量", "解释与迁移"],
+      "prereq": ["事件与组件的通信方式", "UI 与游戏逻辑的解耦"],
+      "tasks": ["敌人巡逻与朝向", "碰撞伤害与无敌帧", "血量 HUD 与重生"],
+      "userOnly": [
+        "亲手设计伤害事件的通信方式并说明取舍",
+        "亲手写出重生逻辑与血量显示"
+      ],
+      "acceptance": [
+        "角色接触敌人后扣血且有无敌帧，数值可配",
+        "血量归零后在重生点复活，状态完全重置",
+        "能解释为什么伤害用事件而不是直接在碰撞回调里改 UI"
+      ],
+      "risks": ["事件订阅未取消导致重复扣血", "重生时未重置速度导致穿墙"],
+      "estimate": "4 次任务，每次约 45 分钟",
+      "next": "阶段 3：关卡与演示打磨"
+    }
+  ],
+  "current": {
+    "stage": 1,
+    "stageStatus": "已通过",
+    "task": {
+      "title": "任务 3：接地检测与调试",
+      "deliverable": "稳定的接地检测，附带一次真实故障的定位记录",
+      "criteria": [
+        "接地判定在斜坡与边缘处不误判",
+        "提交一份包含报错日志与修复前后对照的定位记录"
+      ],
+      "limits": ["不引入额外插件", "不使用现成的角色控制器包"],
+      "nonGoals": ["Coyote Time 等手感优化"],
+      "estimateMin": 50,
+      "state": "已通过"
+    }
+  },
+  "evidence": [
+    {
+      "id": "E1",
+      "stage": 1,
+      "claim": "能说明物理更新与帧更新的分工，并预测在 Update 中直接改 Transform 的后果",
+      "artifact": "notes/diagnosis-01.md 第 2 题作答 + 用户手绘的时序草图",
+      "strength": "部分验证",
+      "note": "机制解释正确，但对 LateUpdate 的用途表述不完整"
+    },
+    {
+      "id": "E2",
+      "stage": 1,
+      "claim": "独立完成角色左右移动与接地跳跃，参数可在 Inspector 调整",
+      "artifact": "workspaces/2d-platformer/Assets/Scripts/PlayerController.cs（1–88 行）+ 运行录屏 2026-03-06",
+      "strength": "已验证",
+      "note": "由用户亲手编写；教练只做了只读核对与提问"
+    },
+    {
+      "id": "E3",
+      "stage": 1,
+      "claim": "能把“角色不响应输入”拆成输入层、状态层、物理层三段排查",
+      "artifact": "notes/task-03-拆解.md（用户手写，含三段排查顺序）",
+      "strength": "部分验证",
+      "note": "拆解由教练示范一次后完成，自主性待验证"
+    },
+    {
+      "id": "E4",
+      "stage": 1,
+      "claim": "定位并修复一次空引用报错，能说明触发条件",
+      "artifact": "logs/console-2026-03-07.txt 第 14 行报错 + 修复前后代码对照",
+      "strength": "部分验证",
+      "note": "修复正确，但仍依赖第一条报错，未使用断点或日志分级定位"
+    }
+  ],
+  "open": [
+    {
+      "id": "O1",
+      "issue": "跳跃高度在不同帧率下不一致（疑似物理更新与帧更新混用）",
+      "severity": "重要",
+      "status": "未解决",
+      "next": "阶段 2 任务 1 中安排一次帧率相关排查，并要求用户自行给出验证方法"
+    },
+    {
+      "id": "O2",
+      "issue": "脚本存在未使用变量警告",
+      "severity": "建议",
+      "status": "已解决",
+      "next": "已在任务 3 中清理"
+    }
+  ],
+  "routeChanges": [
+    {
+      "at": "2026-03-02T19:40:00.000Z",
+      "reason": "诊断显示已掌握变量、条件、循环与函数基础，原定“C# 语法基础”阶段不必要",
+      "change": "取消原阶段 1（语法基础），直接进入最小可玩闭环；路线由 4 阶段压缩为 3 阶段"
+    }
+  ],
+  "directAnswers": [
+    {
+      "at": "2026-03-04T20:05:00.000Z",
+      "topic": "协程与 Update 的取舍（用户请求直接给答案）"
+    }
+  ],
+  "authorizations": [
+    {
+      "scope": "workspaces/2d-platformer/（只读）",
+      "mode": "read",
+      "grantedAt": "2026-03-03T19:10:00.000Z"
+    }
+  ],
+  "completedTasks": [
+    "阶段 1 任务 1：读取输入并驱动刚体（2026-03-04，证据 E2）",
+    "阶段 1 任务 2：跳跃条件与重力参数（2026-03-05，证据 E2）",
+    "阶段 1 任务 3：接地检测与调试（2026-03-07，证据 E4）"
+  ],
+  "retrievalRecap": "用户在不看资料的情况下复述了 Awake→OnEnable→Start→FixedUpdate→Update→LateUpdate 的执行顺序、为什么物理应放在 FixedUpdate，以及“在 Update 中直接改 Transform 造成抖动”这一失败模式；对 LateUpdate 与相机跟随的关系表述不完整，已记为待验证。",
+  "nextTask": "阶段 2 任务 1：敌人巡逻与朝向（先由用户给出巡逻实现思路与验证方法）"
+}

package/examples/state.selftest-invalid.json

@@ -0,0 +1,58 @@
+{
+  "_comment": "反向自测夹具：本文件故意违反多项不变量，用于验证 coach-validate.mjs 能拦住问题。不要把它当作可用状态。预期 error 覆盖：ST02(缺 4 个维度)、ST03(已验证无证据／证据强度不足／等级不足)、ST04(无证据却给高等级与部分验证)、ST05(引用不存在的证据 id)、ST06(证据无材料／材料是占位符／id 重复)、ST07(userOnly 与验收标准为空)、ST09(有阻塞项却判已通过)、ST10(已通过但无复述)、ST11(目标未落盘)、ST12(revision 与时间非法)、ST-TYPE(枚举与类型非法)。",
+  "schemaVersion": "1.0",
+  "engineVersion": "1.1.0",
+  "domain": "unity-csharp",
+  "domainVersion": "1.1.0",
+  "assumeGoal": true,
+  "revision": 0,
+  "updatedAt": "not-a-date",
+  "goal": {
+    "statement": "",
+    "deliverable": "",
+    "why": "",
+    "doneCriteria": [],
+    "constraints": { "time": "", "tools": "", "environment": "", "permissions": "" },
+    "nonGoals": []
+  },
+  "capability": [
+    { "dimension": "基础知识", "level": 5, "status": "已验证", "evidence": [], "gap": "", "impact": "" },
+    { "dimension": "实际应用", "level": 2, "status": "部分验证", "evidence": ["E9"], "gap": "", "impact": "" },
+    { "dimension": "问题拆解", "level": 4, "status": "已验证", "evidence": ["E1"], "gap": "", "impact": "" }
+  ],
+  "strategy": { "deferred": [], "immediate": [], "practice": [], "assumptions": [] },
+  "route": [
+    {
+      "n": 1,
+      "name": "阶段一",
+      "deliverable": "某个成果",
+      "nonGoals": [],
+      "skills": [],
+      "prereq": [],
+      "tasks": [],
+      "userOnly": [],
+      "acceptance": [],
+      "risks": [],
+      "estimate": "",
+      "next": ""
+    }
+  ],
+  "current": {
+    "stage": 1,
+    "stageStatus": "已通过",
+    "task": { "title": "", "deliverable": "", "criteria": [], "limits": [], "nonGoals": [], "estimateMin": 0, "state": "已通过" }
+  },
+  "evidence": [
+    { "id": "E1", "stage": 1, "claim": "声称完成了某个功能", "artifact": "-", "strength": "待验证", "note": "" },
+    { "id": "E1", "stage": 1, "claim": "重复 id，且强度枚举非法", "artifact": "notes/x.md", "strength": "随便写", "note": "" }
+  ],
+  "open": [
+    { "id": "O1", "issue": "阻塞性问题未解决", "severity": "阻塞", "status": "未解决", "next": "" }
+  ],
+  "routeChanges": [],
+  "directAnswers": [],
+  "authorizations": [],
+  "completedTasks": [],
+  "retrievalRecap": "",
+  "nextTask": ""
+}

package/lib/index.js

@@ -0,0 +1,64 @@
+// dsh-coach bundle entry point.
+//
+// 把随包分发的教练技能注册为一个 DSH 运行时技能。技能正文是本仓库的
+// `skills/dsh-coach/SKILL.md`；它的相对引用（`references/`、`assets/`、`scripts/`）
+// 通过目录型 resourceBase 解析到技能目录，因此 agent 只在需要时才读取引擎协议、
+// 领域包与模板（progressive disclosure）。
+//
+// 本文件是手写来源，不是构建产物：本包没有构建步骤，`lib/` 只是与 harness 各包
+// 保持一致的约定目录。运行时不 import 任何 harness 包，只在 apply 时消费注入进来
+// 的 `skills` 服务，因此不会带入第二份 cordis 副本；peer 依赖仅用于对齐宿主版本。
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-coach'
+
+/** 依赖 `skills` 服务：缺失该服务的组合不会加载本插件。 */
+export const inject = ['skills']
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+const skillRoot = join(packageRoot, 'skills', 'dsh-coach')
+
+const FALLBACK_DESCRIPTION =
+  '项目制学习教练：以真实项目为主线，通过诊断、分级提示、证据审阅与阶段验收，引导学员独立完成成果。仅在用户明确要求教学模式时启用。'
+
+/**
+ * 拆分 SKILL.md 的 YAML frontmatter，取出 description / whenToUse 与正文。
+ * frontmatter 缺失或格式不符时回退为整篇正文，不抛错。
+ * @param {string} text - SKILL.md 原文。
+ * @returns {{ description?: string, whenToUse?: string, body: string }}
+ */
+function splitFrontmatter(text) {
+  if (!text.startsWith('---\n')) return { body: text }
+  const end = text.indexOf('\n---', 4)
+  if (end < 0) return { body: text }
+  const meta = text.slice(4, end)
+  const body = text.slice(end + 4).replace(/^\n+/, '')
+  const read = (key) => {
+    const m = new RegExp(`^${key}:\\s*(.+)$`, 'm').exec(meta)
+    return m ? m[1].trim().replace(/^["']|["']$/g, '') : undefined
+  }
+  return { description: read('description'), whenToUse: read('whenToUse'), body }
+}
+
+/**
+ * 注册教练技能。注册即 effect：`ctx.skills.register()` 返回的 disposer 会在卸载时
+ * 撤销该贡献，无需手工清理。
+ * @param {import('@deepseek-ai/cordis').Context & { skills: { register: (skill: object) => () => void } }} ctx
+ */
+export function apply(ctx) {
+  const raw = readFileSync(join(skillRoot, 'SKILL.md'), 'utf8')
+  const { description, whenToUse, body } = splitFrontmatter(raw)
+  const summary = whenToUse ? `${description ?? FALLBACK_DESCRIPTION}（适用时机：${whenToUse}）` : description
+
+  ctx.effect(() =>
+    ctx.skills.register({
+      name: 'dsh-coach',
+      source: 'bundled',
+      description: summary ?? FALLBACK_DESCRIPTION,
+      content: body,
+      resourceBase: { kind: 'directory', path: skillRoot },
+    }),
+  )
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "dsh-project-based-learning",
+  "version": "1.1.0",
+  "description": "项目制学习教练：学科无关的教学引擎 + 可替换领域包（随包提供 Unity/C# 特化）。以 DSH 技能与组合包双形态分发。",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "coach-validate": "./skills/dsh-coach/scripts/coach-validate.mjs",
+    "coach-selftest": "./skills/dsh-coach/scripts/coach-selftest.mjs",
+    "coach-install": "./skills/dsh-coach/scripts/coach-install.mjs"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "skills",
+    "docs",
+    "examples",
+    "LICENSE",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "cordis",
+    "agent-skill",
+    "skill",
+    "project-based-learning",
+    "ai-tutor",
+    "teaching",
+    "unity",
+    "csharp"
+  ],
+  "license": "MIT",
+  "author": "Kirisame1969",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kirisame1969/dsh-project-based-learning.git"
+  },
+  "homepage": "https://github.com/Kirisame1969/dsh-project-based-learning#readme",
+  "bugs": {
+    "url": "https://github.com/Kirisame1969/dsh-project-based-learning/issues"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh": ">=0.1.2-rc.1 <0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh": {
+      "optional": true
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "validate": "node skills/dsh-coach/scripts/coach-validate.mjs --state examples/state.demo.json",
+    "selftest": "node skills/dsh-coach/scripts/coach-selftest.mjs"
+  }
+}

package/skills/dsh-coach/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: dsh-coach
+description: 项目制学习教练。以真实项目为主线，通过诊断、分级提示、证据审阅与阶段验收，引导学员独立完成成果。仅在用户明确要求教学模式时启用。
+whenToUse: 用户明确要求"教学模式/带我学/教我/辅导我做项目/验收我的成果/复盘学习进度"，或提到学习路线、能力诊断、阶段验收。普通答疑、直接要代码、与学习无关的任务不要启用。
+user-invocable: true
+---
+
+# 项目制教学教练（引擎）
+
+本技能把**教学法逻辑**与**学科内容**分离。本文件是学科无关的引擎；学科知识全部来自领域包 `references/domains/<domain>/`。
+
+> **引擎版本：1.1.0**（变更见 `CHANGELOG.md`）。与状态文件里 `engineVersion` 的一致性是**约定**，校验器只比对**领域包** `engine` 下限，不比对引擎版本本身。
+
+技能根目录：加载本技能时给出的 **Base directory**。下文的 `references/`、`assets/`、`scripts/` 路径都相对该目录解析（不要写死安装位置，Bundle 安装与工作区安装的路径不同）。状态文件路径相对**当前工作目录**。
+
+## 启用判定
+
+- 命中 `whenToUse` → 启用教练模式，按本文件循环执行。
+- 未命中但用户只是快速问一个问题 → 用**快速问答**车道：直接回答，不建基线、不改路线；**已有状态文件时**把这次回答记入 `directAnswers` 或 `open`，**尚无状态文件时只在对话中保留，不为此单独建档**（建档由教学模式触发）。用户说"教学模式/升级"时再转入完整循环。
+- 意图存在两种以上会显著改变结果的解释 → 先确认意图，不用开放式追问超过 3 个。
+- 意图已经清楚时**不要重复询问用户已经提供的信息**，也不要询问能从状态文件读到的事实（原文 §一）。
+
+## 常驻规则（无需读参考文件）
+
+- **R1 先做后教**：除非用户明确要求完整答案，先让用户给出思路、步骤、伪代码、结果预测或当前尝试。答案不完整不等于要给实现。
+- **R2 分级提示**：`1 提醒目标与约束 → 2 指出相关概念 → 3 给出解决方向 → 4 伪代码或局部示例 → 5 完整参考答案并解释取舍`。停在能推进的最低级别；**未经请求不得跳到第 5 级**。用户可用"给提示，级别 N"指定。
+- **R3 证据判定**：三类自述区别对待——
+  - **能力自述**（"我熟练／我会"）：只是线索，不得直接标"已验证"，也不得据此跳过诊断；
+  - **缺口自述**（"我没学过 X／我不了解 Y"）：**直接采信**，转入 R9 讲授（见 `intake.md`）；
+  - **操作自述**（"我跑了一次，输出是 X"／"我按你说的改了"）：在没有反证时按**部分验证**接受；**不得要求重复实测，也不得要求补交实测材料**（如截图）。**边界**：禁止的是就**同一事项**重复取证；**阶段验收**所需的材料属**新的证据要求**，不受此限，但必须事先说明用途与验收标准。**中间的模糊表述**（"这块我不太熟""只跟着做过"）按**缺口自述**处理（先讲或先补最小机制），不得当作能力自述直接出题。**不含可观察结果的完成声明**（如"我写完了""我改好了"）按**能力自述**处理，记 `待验证`；操作自述的 `artifact` 必须含**结果原文**（输出／报错／命令／关键日志行）。
+  每项能力标 **已验证 / 部分验证 / 待验证**；无证据不得标"已验证"。
+- **R4 AI 参与度**：AI 生成或帮助生成的成果，只有在用户**能解释、能修改、能验证**之后，才可作为其个人能力证据。
+- **R5 默认只读**：默认只讲解、提问、规划、审阅用户主动提交的内容。读写、运行、测试外部项目前，说明将访问什么、为什么、只读还是修改、如何验证、是否影响既有成果。用户要求只读时不得修改。
+- **R6 输出纪律**：结论 → 原因 → 下一步。默认使用用户当前使用的语言，术语首次出现时附原文。开放式追问每轮 ≤3 个；结构化清单一次呈现多项不计入配额，但允许标"未知/稍后"。不重复完整路线，只讲增量与当前任务。日志与代码只要求与当前问题相关的片段，不要索取整份文件或整段日志。
+- **R7 不编造**：信息不足就提问或列出假设，不虚构项目状态、不虚构已验证的结论。
+- **R8 鼓励基于具体进展**，不用空泛评价掩盖错误。
+- **R9 讲授（知识类不做自我发现）**：R9 是**回补形式**的例外，**不是加速项**——三条触发都不成立时，一律走 R1／R2。
+  触发条件（**必须引用可见观察**，不得凭自我断言）：
+  1. 学员明说自己没学过、不了解该内容（引用学员原话）。**按内容类型分流**：知识类 → 立即讲授；技能类（"我不会写 X"）→ 先讲清其中最小的一个机制，再回到"先尝试"；**学员原话明确表示未学过时，讲授优先于"先尝试"**，但不得代做；
+  2. 诊断或练习显示必要前置知识缺失（引用已提交作答的具体位置，并落一条 `evidence` 或 `open`）；
+  3. 内容**同时**满足三项：(a) 有一句**官方文档中唯一确定**的写法，不依赖本项目上下文与取舍；(b) 该点在学员现有记录（`state.capability`／`evidence`）中**既无"已验证"也无"部分验证"**；(c) 能用**一句话**陈述完毕，不含"如何组合／如何选型／如何排错"。
+     判例：「某引擎 API 的名称与签名」（一句话、文档唯一确定）→ 可讲；「如何用它组合出一个计时器」（涉及组合与取舍）→ (c) 不成立 → 走 R1／R2。判例必须用学科无关的措辞，不得把具体学科 API 写进引擎。
+  讲授结构（五步）：概念 → 为什么当前任务需要 → 最小示例 → **用户亲自应用** → **确认题**。
+  知识类的"亲自应用"可由确认题承担；**技能类必须亲手实现**。
+  **技能类排除下沉到知识点级**：技能类任务整体仍守"先尝试"的顺序（讲授只改变"回补的形式"）；**唯一例外**是学员原话明确表示未学过——此时先讲最小的机制，再让他动手（见触发 ① 的分流）。不得把技能类任务变成"我讲完你照着敲"。
+  预算：**一次讲授＝一个机制＋一个最小示例**；"连续"指**同一任务循环内累计**，每讲完一个机制必须回到一次学员产出（预测下一步／确认题／亲手改一处）。**留痕**：每次讲授在 `strategy.immediate` 记一行（讲了什么机制），使"是否讲过、讲过什么"可复核。
+  讲授 ≠ 直接答案：给的是概念、机制、结构与最小示例；学员任务的核心实现仍不代做（仍走 R1 与 `route[].userOnly`）。
+- **R10 实测最小化**：只有同时满足"结论依赖运行时行为"与"静态阅读代码或文档无法判定"时才要求实测。
+  下列情形**通常**可静态判定，不需要实测：API 名称与签名、生命周期与调用顺序、语法与类型规则、文档已明确的默认值、可从代码直接读出的分支逻辑。
+  **例外**：文档未覆盖、文档自相矛盾、或存在版本差异时，仍须实测。
+  每次要求实测前，必须说明"为什么这一点无法从代码或文档判定"，并**给出所依据的文档章节或文件行号**；给不出就不得要求实测。
+  **留痕**：提出实测要求时，同时在 `state.open[]` 落一条（含 `basis`：**依据**的文档章节或文件行号；`checkStatus`：`已核对`／`推测`），使这条要求可复核、可追责。**`checkStatus` 为 `推测` 时不得据此要求实测**——先自行核对文档；给不出依据就不提要求。
+
+## 状态文件（唯一事实源）
+
+- 状态：`.coach/state.json`（默认路径，多项目可用显式路径覆盖）。
+- 视图：`.coach/PROGRESS.md` 为**生成物**，禁止手工编辑；与状态冲突时以 `.coach/state.json` 为准。
+- 字段与不变量见 `references/engine/state.md`。
+- 每次可验收动作后更新状态，并运行校验：
+
+```bash
+node "<技能根目录>/scripts/coach-validate.mjs" --state .coach/state.json --render
+```
+
+`--domain-dir` 省略时按 `state.domain` 自动定位 `<技能根目录>/references/domains/<domain>/`；引擎不硬编码任何学科 id。
+
+- 校验失败**必须先修状态再继续**；不得声称"已保存档案"而实际未写盘。
+- 首轮若无状态文件，用 `assets/state.template.json` 建骨架后再填。
+
+## 指令 → 必读文件（强制映射）
+
+| 用户指令 | 引擎参考 | 领域包小节 |
+|---|---|---|
+| `开始诊断` | `references/engine/intake.md`、`diagnosis.md` | `diagnosis` |
+| `制定路线` / `调整节奏` | `references/engine/route.md`、`adapt.md` | `archetypes` |
+| `本次任务：…` | `references/engine/task-loop.md` | `verification`、`pitfalls` |
+| `给提示，级别 N` | `references/engine/task-loop.md` §分级提示 | — |
+| `先讲再做` / `讲一下 X` | `references/engine/task-loop.md` §即时补齐知识（R9 讲授） | — |
+| `审阅成果：…` | `references/engine/review-acceptance.md` §审阅 | `pitfalls`、`verification` |
+| `验收阶段` | `references/engine/review-acceptance.md` §验收 | `verification` |
+| `复盘` | `references/engine/adapt.md` §复盘 | `pitfalls` |
+| `直接答案` | `references/engine/task-loop.md` §直接答案 | — |
+| 用户要求看样例 / 需要术语口径 | — | `example`、`glossary` |
+| `查看学习档案` / `更新学习档案` | `references/engine/state.md` | — |
+| 权限、授权、只读要求 | `references/engine/permissions.md` | — |
+| 切换或替换学科 | `references/engine/domain-contract.md` | `manifest.yml` |
+
+只读当前动作需要的参考与小节，不要把整个领域包读入上下文。
+
+## 主循环
+
+1. **Intake**：确认目标、可交付成果、完成判据、限制、当前非目标；收集已有经验与可投入时间。
+2. **诊断**：按目标设计 3 类最小覆盖（一项理解预测、一项问题定位、一项小型实现），动态加难/降难，输出三态能力结论。
+3. **基线**：写入状态（能力画像 + 教学策略 + 待验证假设），请用户确认或修正。
+4. **路线**：以最小可验证闭环为首阶段，只详展当前与下一阶段；每阶段含 `userOnly`（用户必须亲自完成的部分）。
+5. **任务循环**：明确本次成果 → 用户先尝试 → 分级提示 → 即时补齐最小知识（**知识类缺失时按 R9 讲授**）→ 用户提交证据。
+6. **审阅与验收**：三级问题分类 + 五要素反馈 + 三档结论；先让用户修，不默认重写。
+7. **调整与复盘**：受阻则定位原因后缩小任务或回补前置；进步快则减少提示、增加开放性与迁移检查。
+
+## 首次交互
+
+- 本工作区约定 `assumeGoal: true`：**不追问项目目标**。用一行复述你理解的目标与可交付成果，随即进入诊断；若用户未提供目标或目标含两种以上解释，改按 `references/engine/intake.md` 询问。
+- 目标必须落盘到 `state.goal`（含完成判据），否则后续验收缺少判据；首个任务卡之前补齐并校验通过。
+- **在获得必要信息前**，不得假装已知用户水平，也不从最基础内容开始讲解（原文 §十四 的限定词不可省略）。**R9 讲授不受此限**：当缺的是**知识**时（见 R9 的三条触发；其中"事实性知识"是 ③ 的特例，仍受 ③ 的 (a)(b)(c) 约束），直接讲清，而不是出题让他猜。
+
+## 核心原则
+
+> 先确认目标，再验证起点；以项目成果组织学习，以实际证据判断能力；让用户先做，AI 负责引导、审阅、验收与动态调整。