@arcaneorion/dsh-teaching-board 0.4.1 → 0.5.1

package/skills/stage-panel/submode/code/examples/py-ai-parameters-intro.json

@@ -0,0 +1,65 @@
+{
+  "schema_version": 1,
+  "id": "py-ai-parameters-intro",
+  "title": "AI 的参数：模型如何学习",
+  "subtitle": "从最简单的例子理解 AI 参数调整",
+  "summary": "用一个简单的温度预测例子，理解 AI 模型的参数（权重和偏置）如何影响预测结果。不用复杂语法，只用基础 Python。",
+  "domain": "machine-learning",
+  "lang": "python",
+  "level": "intro",
+  "objectives": [
+    "理解什么是模型参数（权重 w 和偏置 b）",
+    "看到参数改变如何影响预测结果",
+    "理解预测值和真实值的误差"
+  ],
+  "starter": {
+    "filename": "ai_params.py",
+    "code": "# AI 模型的核心：参数\n# 假设我们要预测温度：输入小时数，输出温度\n\n# 真实数据：(小时, 温度)\ndata = [\n    (6, 15),\n    (12, 25),\n    (18, 20),\n]\n\n# 模型参数（这就是 AI 要学习的东西）\nw = 1.0\nb = 10.0\n\nprint(\"当前参数\")\nprint(\"权重 w =\", w)\nprint(\"偏置 b =\", b)\nprint()\n\n# 用当前参数做预测\nprint(\"预测结果\")\nfor hour, real_temp in data:\n    predicted_temp = w * hour + b\n    error = predicted_temp - real_temp\n    print(\"小时\", hour, \": 真实温度\", real_temp, \"预测温度\", predicted_temp, \"误差\", error)\n\nprint()\nprint(\"参数不好，预测就不准！\")\n"
+  },
+  "run": {},
+  "activities": [
+    {
+      "id": "predict-output",
+      "type": "predict",
+      "prompt": "运行前先预测：当 w=1.0, b=10.0 时，中午12点的预测温度是多少度？",
+      "required": true,
+      "before_run": true
+    },
+    {
+      "id": "run-and-observe",
+      "type": "trace",
+      "prompt": "点击运行，观察输出。预测值和真实值的误差有多大？哪个时间点的误差最大？",
+      "required": false
+    },
+    {
+      "id": "adjust-params",
+      "type": "implement",
+      "prompt": "试着修改参数 w 和 b，再运行一次。看看误差有没有变小？",
+      "required": true
+    },
+    {
+      "id": "explain-params",
+      "type": "explain",
+      "prompt": "用自己的话解释：什么是模型参数？为什么调整参数能改变预测结果？",
+      "required": true
+    }
+  ],
+  "checks": [
+    {
+      "id": "check-runs",
+      "label": "代码能运行",
+      "type": "exit_code",
+      "expected": 0
+    },
+    {
+      "id": "check-output",
+      "label": "输出包含预测结果",
+      "type": "stdout_contains",
+      "expected": "预测温度"
+    }
+  ],
+  "submission": {
+    "require_run": true,
+    "require_reflection": true
+  }
+}

package/skills/stage-panel/submode/code/examples/py-fizzbuzz-intro.json

@@ -0,0 +1,74 @@
+{
+  "schema_version": 1,
+  "id": "py-fizzbuzz-intro",
+  "title": "Python：先跑起来再改 FizzBuzz",
+  "subtitle": "用一次成功运行建立 Code Lab 手感",
+  "lang": "python",
+  "langs": [
+    "python"
+  ],
+  "level": "intro",
+  "stage": "编辑 → 运行 → 改输出",
+  "summary": "先让脚本打印 1..15 的 FizzBuzz，再按练习改规则。运行在本机 python3 上完成。",
+  "objectives": [
+    "成功运行 starter 并看到输出",
+    "把 15 的倍数改成同时打印 FizzBuzz",
+    "向导师说明 if 顺序为什么重要"
+  ],
+  "focus": {
+    "concept": "control-flow",
+    "trap": "wrong-if-order"
+  },
+  "starter": {
+    "filename": "main.py",
+    "code": "def fizzbuzz(n: int) -> str:\n    if n % 3 == 0:\n        return \"Fizz\"\n    if n % 5 == 0:\n        return \"Buzz\"\n    return str(n)\n\n\nif __name__ == \"__main__\":\n    for i in range(1, 16):\n        print(fizzbuzz(i))\n"
+  },
+  "snippets": [
+    {
+      "id": "main",
+      "lang": "python",
+      "title": "FizzBuzz starter",
+      "filename": "main.py",
+      "role": "primary",
+      "editable": true,
+      "code": "def fizzbuzz(n: int) -> str:\n    if n % 3 == 0:\n        return \"Fizz\"\n    if n % 5 == 0:\n        return \"Buzz\"\n    return str(n)\n\n\nif __name__ == \"__main__\":\n    for i in range(1, 16):\n        print(fizzbuzz(i))\n",
+      "annotations": [
+        {
+          "line": 2,
+          "kind": "warn",
+          "text": "只判断 %3 时，15 会过早返回 Fizz"
+        },
+        {
+          "line": 10,
+          "kind": "info",
+          "text": "入口：打印 1..15"
+        }
+      ]
+    }
+  ],
+  "run": {
+    "snippet_id": "main",
+    "filename": "main.py"
+  },
+  "exercises": [
+    {
+      "id": "e1",
+      "type": "predict_output",
+      "prompt": "当前实现对 15 会打印什么？",
+      "snippet_id": "main"
+    },
+    {
+      "id": "e2",
+      "type": "fix_code",
+      "prompt": "改到 15 打印 FizzBuzz，且 3/5 仍正确。",
+      "snippet_id": "main"
+    }
+  ],
+  "hints": [
+    "先处理 n % 15 == 0（或同时整除 3 与 5）。",
+    "改完点「运行」，看 1..15 整表。"
+  ],
+  "next": [
+    "py-list-comprehension"
+  ]
+}

package/skills/stage-panel/submode/code/examples/py-training-loop.json

@@ -0,0 +1,114 @@
+{
+  "schema_version": 1,
+  "id": "py-training-loop",
+  "title": "模型训练：亲手跑一次梯度下降",
+  "subtitle": "不用框架，直接观察参数、损失与预测如何更新",
+  "summary": "用纯 Python 拟合 y = 2x + 1。代码展示训练数据、前向计算、损失、梯度和参数更新之间的完整关系。",
+  "domain": "machine-learning",
+  "lang": "python",
+  "level": "intro",
+  "stage": "预测 → 训练 → 观察 → 迁移",
+  "objectives": [
+    "指出训练循环的五个组成部分",
+    "解释 loss 下降意味着什么",
+    "修改学习率并比较收敛"
+  ],
+  "prerequisites": [
+    "Python 循环和函数",
+    "导数的直觉"
+  ],
+  "starter": {
+    "filename": "train.py",
+    "code": "data = [(0.0, 1.0), (1.0, 3.0), (2.0, 5.0), (3.0, 7.0)]\n\nw = 0.0\nb = 0.0\nlr = 0.05\n\nfor step in range(201):\n    predictions = [w * x + b for x, _ in data]\n    errors = [pred - y for pred, (_, y) in zip(predictions, data)]\n    loss = sum(error ** 2 for error in errors) / len(data)\n\n    dw = 2 * sum(error * x for error, (x, _) in zip(errors, data)) / len(data)\n    db = 2 * sum(errors) / len(data)\n    w -= lr * dw\n    b -= lr * db\n\n    if step in {0, 20, 100, 200}:\n        print(f\"step={step:3d} loss={loss:.6f} w={w:.4f} b={b:.4f}\")\n\nprint(f\"prediction={w * 5 + b:.2f}\")\n"
+  },
+  "snippets": [
+    {
+      "id": "main",
+      "lang": "python",
+      "title": "最小训练循环",
+      "filename": "train.py",
+      "role": "primary",
+      "editable": true,
+      "code": "data = [(0.0, 1.0), (1.0, 3.0), (2.0, 5.0), (3.0, 7.0)]\n\nw = 0.0\nb = 0.0\nlr = 0.05\n\nfor step in range(201):\n    predictions = [w * x + b for x, _ in data]\n    errors = [pred - y for pred, (_, y) in zip(predictions, data)]\n    loss = sum(error ** 2 for error in errors) / len(data)\n\n    dw = 2 * sum(error * x for error, (x, _) in zip(errors, data)) / len(data)\n    db = 2 * sum(errors) / len(data)\n    w -= lr * dw\n    b -= lr * db\n\n    if step in {0, 20, 100, 200}:\n        print(f\"step={step:3d} loss={loss:.6f} w={w:.4f} b={b:.4f}\")\n\nprint(f\"prediction={w * 5 + b:.2f}\")\n",
+      "annotations": [
+        {
+          "line": 7,
+          "kind": "info",
+          "text": "前向计算：当前参数产生预测"
+        },
+        {
+          "line": 9,
+          "kind": "info",
+          "text": "目标函数：均方误差"
+        },
+        {
+          "line": 11,
+          "kind": "warn",
+          "text": "梯度决定参数应向哪个方向变化"
+        },
+        {
+          "line": 13,
+          "kind": "info",
+          "text": "优化器最小形式：参数减去学习率乘梯度"
+        }
+      ]
+    }
+  ],
+  "run": {
+    "snippet_id": "main",
+    "filename": "train.py"
+  },
+  "activities": [
+    {
+      "id": "predict-loss",
+      "type": "predict",
+      "prompt": "训练过程中 loss 应整体上升还是下降？w 和 b 最终应接近什么值？",
+      "required": true,
+      "before_run": true
+    },
+    {
+      "id": "trace-loop",
+      "type": "trace",
+      "prompt": "用自己的话串起：数据 → 预测 → 误差 → loss → 梯度 → 参数更新。",
+      "required": true
+    },
+    {
+      "id": "transfer-lr",
+      "type": "transfer",
+      "prompt": "把 lr 改为 0.5 和 0.005 分别运行。比较收敛速度或不稳定现象。",
+      "required": true
+    }
+  ],
+  "checks": [
+    {
+      "id": "exit-ok",
+      "label": "训练脚本正常退出",
+      "type": "exit_code",
+      "expected": 0
+    },
+    {
+      "id": "has-loss",
+      "label": "输出包含训练损失",
+      "type": "stdout_contains",
+      "expected": "loss="
+    },
+    {
+      "id": "predict-eleven",
+      "label": "模型对 x=5 的预测接近 11",
+      "type": "stdout_contains",
+      "expected": "prediction=11.00"
+    }
+  ],
+  "hints": [
+    "线性模型只有两个参数：斜率 w 和截距 b。",
+    "学习率过大可能越过最低点，过小则需要更多步。"
+  ],
+  "submission": {
+    "require_run": true,
+    "require_reflection": true
+  },
+  "next": [
+    "py-autograd",
+    "py-train-validation-split"
+  ]
+}

package/skills/stage-panel/submode/code/examples/rs-move-basics.json

@@ -0,0 +1,118 @@
+{
+  "schema_version": 1,
+  "id": "rs-move-basics",
+  "title": "Rust move：为什么 s 不能再读",
+  "subtitle": "用一次编译失败学会所有权转移",
+  "lang": "rust",
+  "level": "intro",
+  "stage": "编辑 → 运行 → 读编译错误",
+  "summary": "Rust 默认 move。String 被赋值给另一个变量后，旧名字不能再使用；编译器在运行前拦住 use-after-move。Python 同一写法只是多了一个引用名。",
+  "objectives": [
+    "指出哪一行发生 move",
+    "根据 E0382 说明为什么第 3 行非法",
+    "用一句话对比 Python 的引用语义"
+  ],
+  "focus": {
+    "concept": "ownership-move",
+    "trap": "use-after-move"
+  },
+  "starter": {
+    "filename": "main.rs",
+    "code": "fn main() {\n    let s = String::from(\"hi\");\n    let t = s;\n    println!(\"{s}\");\n}\n"
+  },
+  "snippets": [
+    {
+      "id": "main",
+      "lang": "rust",
+      "title": "会编译失败的例子",
+      "filename": "main.rs",
+      "role": "primary",
+      "editable": true,
+      "code": "fn main() {\n    let s = String::from(\"hi\");\n    let t = s;\n    println!(\"{s}\");\n}\n",
+      "annotations": [
+        {
+          "line": 2,
+          "kind": "info",
+          "text": "在堆上创建 String，s 拥有它"
+        },
+        {
+          "line": 3,
+          "kind": "move",
+          "text": "所有权从 s 移到 t，s 失效"
+        },
+        {
+          "line": 4,
+          "kind": "error",
+          "text": "use after move → 编译期 E0382"
+        }
+      ]
+    }
+  ],
+  "run": {
+    "snippet_id": "main",
+    "filename": "main.rs"
+  },
+  "trace": {
+    "steps": [
+      {
+        "id": "s1",
+        "title": "创建 s",
+        "focus_snippet": "main",
+        "lines": [
+          2
+        ],
+        "note": "s 拥有堆上的 String。"
+      },
+      {
+        "id": "s2",
+        "title": "move 到 t",
+        "focus_snippet": "main",
+        "lines": [
+          3
+        ],
+        "note": "赋值转移所有权，不是共享。"
+      },
+      {
+        "id": "s3",
+        "title": "再读 s",
+        "focus_snippet": "main",
+        "lines": [
+          4
+        ],
+        "note": "编译器拒绝；可改为用 t，或 s.clone()，或只传 &s。"
+      }
+    ]
+  },
+  "exercises": [
+    {
+      "id": "e1",
+      "type": "spot_bug",
+      "prompt": "标出会触发 use-after-move 的那一行（相对 main 片段）。",
+      "snippet_id": "main",
+      "hint": "move 发生在赋值之后的下一次使用。"
+    },
+    {
+      "id": "e2",
+      "type": "fix_code",
+      "prompt": "改到能编译并打印 hi。至少一种：打印 t、clone、或借用。",
+      "snippet_id": "main"
+    },
+    {
+      "id": "e3",
+      "type": "short",
+      "prompt": "为什么 Python 对照片段能直接 print(s)？"
+    }
+  ],
+  "hints": [
+    "先让 rustc 报错，再读 error code，比背规则快。",
+    "Copy 类型（如 i32）赋值是复制，不会 move；String 不是 Copy。"
+  ],
+  "solution": {
+    "code": "fn main() {\n    let s = String::from(\"hi\");\n    let t = s.clone();\n    println!(\"{s}\");\n    println!(\"{t}\");\n}\n",
+    "explanation": "clone 显式复制堆数据；或直接 println!(\"{t}\") 使用新主人；需要共享只读时用 &s。"
+  },
+  "next": [
+    "rs-borrow-intro",
+    "rs-copy-vs-clone"
+  ]
+}

package/skills/stage-panel/submode/code/references/host-toolchains.md

@@ -0,0 +1,61 @@
+# 宿主工具链检测与安装提示
+
+Code Lab **不**捆绑编译器。运行前检测本机工具；缺失则 `blocked` 并提示安装。
+
+## 检测命令（doctor 可用）
+
+```bash
+python3 --version
+uv --version
+rustc --version
+cargo --version
+go version
+```
+
+项目信号文件：
+
+| 语言 | 信号 |
+|------|------|
+| Python | `pyproject.toml`, `uv.lock`, `requirements.txt` |
+| Rust | `Cargo.toml`, `Cargo.lock` |
+| Go | `go.mod`, `go.sum` |
+
+## MVP runner 最小依赖
+
+| profile | 需要 |
+|---------|------|
+| `python-script` | `python3` |
+| `python-uv-script` | `uv`（推荐 NixOS/本环境） |
+| `rust-rustc-single` | `rustc` |
+| `go-run-single` | `go` |
+
+`cargo` / `go test` 为 Phase 2。
+
+## NixOS 提示（示例，按用户 flake 调整）
+
+```bash
+# 临时 shell 示例
+nix-shell -p python3 uv rustc cargo go
+
+# 或进入项目 devShell（若有 flake）
+nix develop
+```
+
+不要在 skill 内 `nix-build` 出一套私有工具链当默认路径；应复用用户环境。
+
+## 库从哪里来
+
+- **单文件课**：尽量 std  only，降低依赖摩擦。  
+- **需要第三方库的课**：在**用户项目**里用 uv/cargo/go.mod 声明；lesson 文档写明前置。  
+- skill `examples/` 只放 lesson JSON，不 vendoring site-packages / target。
+
+## 失败语义
+
+| 情况 | run status | 对用户 |
+|------|------------|--------|
+| 无 rustc | `blocked` | 显示缺失工具 + 安装提示 |
+| 编译/运行失败 | `failed` | 展示 stderr，供教学 |
+| 超时 | `timeout` | 提示减小输入或查死循环 |
+| 成功 | `ok` | 展示 stdout |
+
+禁止在工具缺失时回退到「浏览器假执行」而不告知。

package/skills/stage-panel/submode/code/schemas/lesson.schema.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://localweb.dev/schemas/code.lesson.schema.json",
+  "title": "LocalWeb Code Lab Lesson",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["title", "lang"],
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "subtitle": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    },
+    "lang": {
+      "type": "string",
+      "enum": ["python", "rust", "go"]
+    },
+    "langs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["python", "rust", "go"]
+      },
+      "description": "本课涉及的语言；跨语言对照时使用。"
+    },
+    "level": {
+      "type": "string",
+      "enum": ["intro", "intermediate", "advanced"]
+    },
+    "stage": {
+      "type": "string",
+      "description": "教学阶段标签，如 编辑练习 / 读错信息 / 对照语义"
+    },
+    "objectives": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "focus": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "concept": { "type": "string" },
+        "trap": { "type": "string" }
+      }
+    },
+    "starter": {
+      "type": "object",
+      "description": "单文件课的快速写法；与 snippets 二选一或同时提供。",
+      "required": ["code"],
+      "additionalProperties": true,
+      "properties": {
+        "filename": { "type": "string" },
+        "code": { "type": "string" }
+      }
+    },
+    "snippets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "lang", "code"],
+        "additionalProperties": true,
+        "properties": {
+          "id": { "type": "string" },
+          "lang": {
+            "type": "string",
+            "enum": ["python", "rust", "go"]
+          },
+          "title": { "type": "string" },
+          "filename": { "type": "string" },
+          "code": { "type": "string" },
+          "role": {
+            "type": "string",
+            "enum": ["primary", "contrast", "solution", "tests"],
+            "default": "primary"
+          },
+          "editable": {
+            "type": "boolean",
+            "default": false
+          },
+          "annotations": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["line", "text"],
+              "additionalProperties": true,
+              "properties": {
+                "line": { "type": "integer", "minimum": 1 },
+                "kind": {
+                  "type": "string",
+                  "enum": ["info", "move", "error", "alias", "hint", "warn"]
+                },
+                "text": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "run": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "snippet_id": {
+          "type": "string",
+          "description": "默认展示哪个 snippet；缺省取 role=primary 或 starter。"
+        },
+        "filename": { "type": "string" }
+      }
+    },
+    "compare": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "axes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "rows": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["lang", "cells"],
+            "additionalProperties": true,
+            "properties": {
+              "lang": { "type": "string" },
+              "cells": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "trace": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title"],
+            "additionalProperties": true,
+            "properties": {
+              "id": { "type": "string" },
+              "title": { "type": "string" },
+              "focus_snippet": { "type": "string" },
+              "lines": {
+                "type": "array",
+                "items": { "type": "integer", "minimum": 1 }
+              },
+              "note": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "exercises": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "prompt"],
+        "additionalProperties": true,
+        "properties": {
+          "id": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": [
+              "predict_output",
+              "spot_bug",
+              "fix_code",
+              "short",
+              "choice"
+            ]
+          },
+          "prompt": { "type": "string" },
+          "hint": { "type": "string" },
+          "snippet_id": { "type": "string" },
+          "choices": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["id", "label"],
+              "properties": {
+                "id": { "type": "string" },
+                "label": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "hints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "solution": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "默认不渲染；由 agent 决定是否展示。",
+      "properties": {
+        "code": { "type": "string" },
+        "explanation": { "type": "string" }
+      }
+    },
+    "next": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}