@arcaneorion/dsh-teaching-board 0.4.1 → 0.5.0

package/README.md

@@ -16,7 +16,7 @@ dsh plugin --profile web add @arcaneorion/dsh-teaching-board
 它是一个 **profile 级 bundle**：装一次，这个进程里所有会话都拿得到 `stage_*` 工具与「教学平面」页签。
 （`dsh plugin add` 会把依赖与 bundles 条目一起写进该 profile 的 manifest。）
 
-> **发布状态**：`@arcaneorion/dsh-teaching-board` 已发布（`0.4.0` 于 2026-09-15 10:17 CST 上线，当前 `0.4.1`）。
+> **发布状态**：`@arcaneorion/dsh-teaching-board` 已发布（`0.4.0` 于 2026-09-15 10:17 CST 上线，当前 `0.5.0`）。
 > 改名前的 `@arcaneorion/dsh-stage-panel@0.1.0` 仍在 registry 上，对应本仓早期版本——**别再用**，
 > 装它只会拿到残缺面板（`npm deprecate @arcaneorion/dsh-stage-panel "renamed to @arcaneorion/dsh-teaching-board"` 可让老名字自己说明去向）。
 
@@ -44,6 +44,7 @@ dsh plugin --profile web add @arcaneorion/dsh-teaching-board
 | 截图交给 agent | client（父层） | PNG → `conversation.createDraftImages` → `inputActions.addImages` → 草稿图片 |
 | agent 主动截图 | host 工具 + client 监听 | `stage_snapshot` 工具 → client 从快照看到调用 → 拍图 → 作为用户消息提交 |
 | 状态条 / 方向选择 | host 工具 | `stage_status` / `stage_choice` |
+| 自带使用手册 | host（`src/skills.js`） | 插件把包内 `skills/stage-panel/` 注册成 bundled skill：挂上插件就有纪律，任何 preset 都无需另外安装 |
 
 ## 架构：两条硬约束
 
@@ -63,14 +64,18 @@ dsh plugin --profile web add @arcaneorion/dsh-teaching-board
 | 文件 | 说明 |
 |---|---|
 | `src/index.js` | host 半：`stage_panel / stage_status / stage_choice / stage_snapshot` 四个无状态工具 |
+| `src/skills.js` | host 半：把包内 `skills/stage-panel/` 注册成 bundled skill（provider 模式，随 fiber 注销） |
+| `skills/stage-panel/` | 行为层：使用手册 `SKILL.md` + 选型/布局/视觉三份规范 + 五个素材库 |
 | `src/client.js` | client 半：「教学平面」视图（工具栏 + 注入 runtime + 截图交付 + agent 请求监听） |
 | `package.json` / `cordis.patch.yml` | bundle 声明（行 id `teaching-board`），挂载进 `web` profile |
 | `PROTOTYPE-*.js` | 早期动态原型（`lwst-2`）存档，仅供历史参考 |
 
 ## 分层
 
-- **能力层（本 bundle，profile 级）**：投影 + 勾画 + 截图 + 工具。
-- **行为层（preset `arcane-stage-panel`）**：教学模式纪律、内容规范（图型/HTML 模式/视觉风格）。
+- **能力层（本 bundle，profile 级）**：投影 + 勾画 + 截图 + 四个 `stage_*` 工具。
+- **行为层（同一 bundle 自带）**：`skills/stage-panel/` —— 使用手册、选型/布局/视觉三份规范、五个素材库；插件 `apply` 时以 provider 方式注册进 `ctx.skills`（`skill-filesystem` 只扫固定的本地根目录，扫不到包内文件，所以必须由插件自己发布）。
+
+  > 旧布局把行为层放在 preset `arcane-stage-panel` 的 `skills/` 里：教学平面会话拿得到，**其余会话停在「有工具、没纪律」**。现已合并进插件——一份手册，所有挂载本插件的会话都能读到。
 
 ## 板面模型：一块板 = 一个主题
 

package/cordis.patch.yml

@@ -1,5 +1,9 @@
-# 教学平面 bundle row: 板书视图（勾画 / 截图）+ stage_* 工具（能力层，profile 级）。
-# 行为层 = preset arcane-stage-panel（模式纪律与内容规范）。
+# 教学平面 bundle row（能力层 + 行为层都在 @arcaneorion/dsh-teaching-board 里）。
+#
+# 能力层：板书视图（勾画 / 截图）+ stage_* 工具。
+# 行为层：插件在 apply 时把自带的 skills/stage-panel/ 注册进 ctx.skills
+#        （bundled skill，见 src/skills.js）——挂上本插件就有使用手册，
+#        不需要任何 preset 另外装一份。
 - insert:
     - id: teaching-board
       name: '@arcaneorion/dsh-teaching-board'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcaneorion/dsh-teaching-board",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -8,7 +8,7 @@
     "./client": "./src/client.js",
     "./package.json": "./package.json"
   },
-  "description": "DSH teaching surface: project agent-generated self-contained HTML into a sandboxed in-session board with handwriting annotation and a built-in screenshot that returns to the conversation as a real user message.",
+  "description": "DSH teaching surface: project agent-generated self-contained HTML into a sandboxed in-session board with handwriting annotation and a built-in screenshot that returns to the conversation as a real user message. Ships its own usage skill (skills/stage-panel).",
   "license": "MIT",
   "author": "arcanexis",
   "repository": {
@@ -26,10 +26,12 @@
     "screenshot",
     "ui",
     "panel",
-    "iframe"
+    "iframe",
+    "skill"
   ],
   "files": [
     "src",
+    "skills",
     "cordis.patch.yml",
     "README.md"
   ],

package/skills/stage-panel/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: stage-panel
+description: DSH 教学平面（板书面板）使用手册，随 @arcaneorion/dsh-teaching-board 插件发布：board id 与 op 语义、data-stage-region 替换约定、self-contained HTML 与 MathML 铁律、本地交互与 stage_choice 的分工、圈画与截图的往返纪律，以及选型 / 布局 / 视觉三份规范与五个素材库。
+---
+
+# 教学平面 · 使用手册
+
+> 这份手册随 `@arcaneorion/dsh-teaching-board` 一起发布：**会话挂着这个插件，就能读到它**，不需要任何 preset 额外安装。
+> 它讲的是**怎么用**；「能开板、能圈画、能截图」是插件本身的**能力**。
+
+## 单一数据流
+
+```text
+会话  = 主上下文、唯一真相
+面板  = 会话的投影：agent 生成 self-contained HTML → stage_panel → 隔离 iframe
+本地  = 面板内交互（筛选 / tab / hover / 滑块 / 折叠）→ 只在面板里变，不打扰会话
+回声  = 需要 agent 知道的事 → 真实用户消息（stage_choice 点选 / DSH 输入框 / 截图）
+```
+
+没有私有状态、没有 RPC、没有 wait 闸门：面板当前的样子 = 会话里最近一次 `stage_*` 调用的参数。
+
+## 工具
+
+| 工具 | 用途 | 必须记住的一点 |
+|---|---|---|
+| `stage_panel` | 写板书（HTML） | 同一个 `board` 的连续调用是**同一块板在演进**；换 `board` 才是换板 |
+| `stage_status` | 状态条 + 上下文行 | 讲到哪、任务、阶段、等待态 |
+| `stage_choice` | 发布方向选项 | 用户点选 = 一条真实用户消息；**发布后结束本轮**，不要 wait |
+| `stage_snapshot` | 把当前画面（含圈画）截图发回 | 图在**下一轮**才看得到；每轮最多一次 |
+
+## 板面身份：`board` 与 `op`
+
+一块板 = 一个主题 / 一节课。`board` 用语义短名（`stats-se5`、`gradient-descent`），不要用序号。
+
+| op | 语义 | 何时用 |
+|---|---|---|
+| `append`（默认） | 在板尾再写一段 | **默认选择**：接着讲、加一节、补一张表 |
+| `open` | 开板，或整块重写 | 开新主题，或确实要推翻全部内容 |
+| `set` | 替换一个区域 | 只更新某一块（例如"当前步骤"高亮） |
+| `remove` | 擦掉一个区域 | 删掉已经讲完的临时块 |
+
+**再讲一段时不要重发整块 HTML**：那会丢掉用户的圈画笔迹、把滚动位置顶回去，也白烧 token。用 `append`。
+
+### 区域替换的约定
+
+`set` / `remove` 靠 HTML 里的 `data-stage-region="名称"` 定位，所以**写第一版时就要预判哪些块以后会被单独替换**，给它们挂上这个属性：
+
+```html
+<section data-stage-region="当前步骤">…</section>
+<section data-stage-region="练习">…</section>
+```
+
+没挂属性的内容只能靠 `open` 整块重写，而整块重写会清掉笔迹。**区域名从第一版就带上**，后面才改得动。
+
+## 铁律：self-contained
+
+面板运行在 `sandbox="allow-scripts"` 的隔离 iframe 里（没有 `allow-same-origin`），且按设计必须自带全部依赖：
+
+- CSS / JS 全部内联；字体用系统字体栈，不要 web font。
+- 图片用 `data:` URI；不要引用远程图片、CDN、外链样式表。
+- **公式用 MathML**（浏览器原生，零依赖）。不要引 KaTeX / MathJax：它们要从外网加载脚本和字体，一失败就是空白公式。
+- 交互脚本写在同一个文件的 `<script>` 里，数据写在同一个文件里；不要 `fetch()`。
+
+## 交互分工
+
+- **面板内本地交互**（筛选、tab、hover、滑块、折叠）：面板自己变就行，不进入会话，尽管加。
+- **需要用户推进时**才用 `stage_choice`：下一步讲什么、要不要继续、选哪条路。发布后结束本轮——点选会以用户消息到达。
+- **长文本输入**走 DSH 自己的输入框。不要在面板里复制"手动回传 / 发送到 CLI"卡片：那是旧原型的做法，现在唯一的回声通道是真实用户消息。
+- 聊天区只留**推理与结论**，画面内容放面板；一轮只问一个决定。
+
+## 圈画与截图
+
+- 用户可以用面板工具栏圈画、擦除、撤销、清空。
+- `stage_snapshot` 把当前画面（含笔迹）截图发回会话，作为**一条带图片的真实用户消息**。
+- 所以：调用后**结束本轮**，下一轮才看得到图。不要在同一个回合里假装已经看过。
+- 前提是用户此刻停在「教学平面」页签；没挂着就截不到，会返回失败原因——请用户切过去再试。
+- 每轮最多一次，不要连发。
+
+## 什么时候**不**开板
+
+- 纯文本或一张小表格就能说清 → **纯文本就是正确答案**。板是放大器，不是入口。
+- 选不出图型、或内容不值得可视化 → 不要为了"用上面板"而开板。
+- 内容结构决定形式：证明推导、代码路径、协议时序、调试排查、错因复盘、密集图谱各有各的信息结构。**不要把任意内容塞进固定栏目的模板。**
+
+## 规范：选型 → 布局 → 视觉
+
+按这个顺序读，不要跳：
+
+| 文件 | 管什么 |
+|---|---|
+| `references/diagram-selection.md` | 选型：信息类型 → 图型、Shannon 依据、生成前的声明格式 |
+| `references/html-patterns.md` | 选型之后的 HTML 组织：不同任务类型的布局模式 |
+| `references/visual-style.md` | 视觉语言：蓝灰控制台 / 硬描边 / 高对比（可选风格，不是强制） |
+
+生成前用 1-3 行在会话里说明"信息类型 → 图型"，再开板。
+
+## 素材库（按需取用，不是五个必须套的模式）
+
+| 素材 | 内容 | 用得上时 |
+|---|---|---|
+| `submode/code/` | lesson schema（starter / snippets / exercises / annotations / hints）+ lab.html + 7 个真实课程示例 | 代码展示与讲解 |
+| `submode/learn/` | lesson schema（概念卡 / 结构 / 例子 / 问题）+ lesson.html + epsilon-delta 范例 | 结构化讲解 |
+| `submode/game-study/` | quest schema（主动回忆 / 干扰项 / 错因）+ quiz.html + 两个真题库 | 出题与答题面板 |
+| `submode/quant/` | 因子回测 dashboard.html + 数据导出脚本 | 回测结果呈现 |
+| `submode/ml/` | 交互式数值可视化 gd.html + gd.json | 训练 / 优化过程演示 |
+
+它们是**起点素材**：可以借用布局与 schema，但内容结构说了算——不要为了套模板生成空 section 或不贴合内容的控件。

package/skills/stage-panel/references/diagram-selection.md

@@ -0,0 +1,80 @@
+# 展现方式选型：信息类型 → 图型
+
+生成任何 panel 之前先完成选型。本文件是「选型」的唯一家：关系类型→图型的完整目录、Shannon 依据、声明格式。选型之后的 HTML 组织方式见 `html-patterns.md`，视觉语言见 `visual-style.md`。
+
+## 0. 一次三问
+
+1. **核心关系是哪一种？**（§2 结构关系 8 种 / §3 数据图表族）——决定图型。
+2. **读者在哪个阶段？** 读（第一眼建骨架）→ 看（第二遍看关系）→ 玩（深挖探索）——决定交互密度。
+3. **纯文本＋表格能否说清？** 能 → 不生成 panel。文本是一等公民，panel 是放大器不是入口。
+
+## 1. Shannon 三把尺子
+
+展现形式的取舍本质是信息传输的取舍。三把尺子：
+
+- **信息密度（熵）**：每元素承载的不可预测性。线性文本每字符熵最高、但需逐字解码；结构图把「关系」编码进位置，每元素熵降低、辨识提速。
+- **冗余**：同一信息重复编码的次数。好的展示有意冗余——同一关系用「位置＋颜色＋标签」至少编码两遍，帮读者抗噪；装饰性动画不承载任何区分度，是噪声不是冗余。
+- **信道带宽**：读者单次能接收的量有限（工作记忆约 4 组块）。一屏活跃元素超过约 9 个就必须分组、分页或分层展开；交互的本质是**按需分配带宽**——默认只给骨架，点击才注入细节。
+
+推导出的四条规则：
+
+1. 内容熵高（新颖叙述、不可预测的推理多）→ 以线性文本为主，图只给骨架。
+2. 关系可预测（层级/流程/状态）→ 图的压缩效率最高，优先用图。
+3. 一屏超过约 9 个活跃元素 → 分组或分层展开，不要硬塞。
+4. 想强调一个关系 → 给它至少两种编码（位置＋颜色/标签）；想删一个元素 → 先问它承载了什么区分度。
+
+## 2. 结构关系 8 种 → 图型
+
+| # | 关系 | 选它的问句 | 图型 | 何时不用 |
+|---|------|-----------|------|---------|
+| 1 | 包含/层级 | 谁套着谁？ | 树状图（思维导图=放射变体、旭日图=径向变体） | 只有一层 → 改列表 |
+| 2 | 步骤顺序 | 先做什么后做什么？ | 流程图；无分支时用时间线 | ≤3 步且无分支 → 编号列表 |
+| 3 | 参与者消息 | 多方之间谁发给谁、按什么顺序？ | 时序图/泳道图 | 只有两方一问一答 → 两行对照 |
+| 4 | 静态连接 | 谁跟谁有联系（无层级）？ | 网络图/组件框图/依赖 DAG | 边数会变毛球（>15 条）→ 矩阵表 |
+| 5 | 状态变迁 | 它待在哪，什么事件让它换地方？ | 状态机图 | 状态 >7 个 → 先分组 |
+| 6 | 数据形状 | 实体之间是 1:N 还是 N:M？ | ER 图 | 设计存储/日志格式前画，之后当参考 |
+| 7 | 依赖方向 | 谁依赖谁、只能向下调？ | 分层架构图 | 依赖双向或无分层 → 改网络图 |
+| 8 | 交叉对照 | 两组维度要交叉看？ | 矩阵表 | 关系只有一组维度 → 改清单 |
+
+树、时序、状态机、分层的最小骨架：
+
+```text
+A                      你      循环      模型        [空闲] --输入--> [思考]         ┌─────────┐
+├─ B                   │──提问──→│         │           [思考] --工具调用--> [执行]      │ 装配层  │
+│  └─ D                │         │──请求──→│           [执行] --完成--> [空闲]         ├─────────┤
+└─ C                   │         │←─分片───│                                           │ 服务层  │
+                                                                                   ├─────────┤
+                                                                                   │ 适配层  │
+                                                                                   └─────────┘
+```
+
+## 3. 数据图表族（数值型信息）
+
+选型问句：**这些数字在回答什么问题？**
+
+| 数字在回答 | 图型 | 防坑 |
+|-----------|------|------|
+| 类别之间比大小 | 柱状图 | 类别名太长转条形图 |
+| 随时间怎么变 | 折线图 | 别截断 y 轴夸大变化 |
+| 整体由什么构成 | 饼/环/堆叠柱 | 块 >5 改条形 |
+| 两个量是否相关 | 散点图 | 相关≠因果，把第三变量标出来 |
+| 数值怎么分布 | 直方图/箱线图 | 别拿均值冒充分布 |
+| 总量怎么分流 | 桑基图 | 只用于守恒型流动 |
+
+## 4. 组合与递进
+
+- 一个 panel 常是 2-3 种图组合，但**每层必须能独立回答一个不同的问题**——不是同一份数据换花样画三遍。
+- 默认递进：读层给结论句 → 看层给主图 → 玩层做交互放大器（点开细节/筛选/对照）。
+- 跨图一致性：同一实体在不同图里同名同色，读者不用重新对表。
+
+## 5. 声明格式（与 SKILL.md 标准流程挂钩）
+
+生成 panel 前，在 CLI 用 1-3 行声明选型，让用户可检查、可纠正：
+
+```text
+选型：核心关系=包含层级 → 树；次关系=依赖方向 → 分层图
+交互：第二步放大器（点节点看上下文），首屏纯读
+```
+
+- 核心关系选不出图型 → 说明需求还没长成，先回终端问用户。
+- 「不生成 panel：文本足够」也是合法的选型结论。

package/skills/stage-panel/references/html-patterns.md

@@ -0,0 +1,93 @@
+# HTML Panel Patterns
+
+当视觉结构比线性文字更适合表达任务时，生成 self-contained HTML panel。
+
+> **高优先级：模板只是建议/参考，不是固定框架。先判断内容的认知结构，再选择布局、视觉层级和交互方式。**
+>
+> **展现选型的家在 `diagram-selection.md`：先按它声明「信息类型→图型」，本文件只管选型之后的 HTML 组织。**
+>
+> **不要为了套模板而生成固定栏目、空 section 或不贴合内容的控件。概念、证明、代码路径、协议时序、调试、审查和研究总结应拥有不同的信息结构。**
+
+## 默认视觉方向
+
+panel 可以拥有自己的视觉语言，但默认应尽量呼应默认的蓝灰控制台风格（见 `visual-style.md`），而不是生成通用 dashboard。
+
+建议：
+
+- 使用硬黑描边、小圆角、清晰分区和高对比文字。
+- 优先使用 `#ffd43b` 黄、蓝灰/孔雀蓝背景、`#fff8d6` 奶油色内容面、`#35d8ff` 青色和 `#ffb454` 橙色点缀。
+- 布局应像“任务控制台”：主信息最大，辅助说明和操作靠边，不用大块空洞营销式 hero。
+- 可以使用网格、角标、编号、状态灯、HUD 小标签、漫画式阴影，但不要让装饰压过内容。
+- 字体可优先选择清晰的 monospace 或有技术感的 display 字体；避免默认 AI 风格的紫色渐变、泛白卡片流和过度圆角。
+- 如果任务需要不同基调，可以偏离默认风格，但要先服务任务语义，例如审查面板更克制，学习面板更友好，调试面板更强调证据。
+
+## 最小交互建议
+
+**交互应嵌在信息附近，而不是被固定到底部或变成 A/B/C/D 模板。**
+
+- 纯展示是有效输出；不需要用户继续推理时，不要强行加输入控件。
+- tab、筛选、hover、展开、局部排序等只在 panel 内部改变显示，不回传会话。
+- 只有需要 agent 继续使用用户补充的上下文时，才用 `stage_choice` 发布一个明确入口（点选 = 一条真实用户消息）。
+- 需要用户写长文本时，请他使用 DSH 自己的输入框；不要在面板里复制“回传”控件。
+- 不要把 Web 交互用于权限批准、命令执行、文件删除或网络授权。
+
+## 学习讲解
+
+用于概念、仓库行为、API、协议和算法。
+
+可包含：
+
+- TL;DR 横幅
+- 可点击或 hover 的流程图
+- 术语条
+- 示例 tab
+- 需要用户信号时才加入热点、筛选器、排序 chips、小表单或下一步卡片
+
+**`submode/learn` 是概念型学习面板的参考素材（lesson schema + lesson.html）。** 它适合用 lesson JSON 生成概念卡、结构图、例子、主动回忆问题和下一步候选。若内容更像证明推导、代码跟踪、协议时序、调试排查、错因复盘或密集图谱，应生成自定义 HTML panel，而不是套它的模板。
+
+## 代码理解
+
+用于陌生包、模块、执行路径或依赖地图。
+
+可包含：
+
+- 模块盒子和箭头
+- 高亮 hot path
+- 入口点
+- 测试表面
+- 风险标记
+
+## 计划和对比
+
+用于需要空间化比较多个方案的任务。
+
+可包含：
+
+- 并排方案
+- 取舍矩阵
+- 时间线
+- 风险表
+- 推荐路径
+
+## 调试和审查
+
+用于事故时间线、失败测试、带注释 diff 和根因分析。
+
+可包含：
+
+- 按时间排列的事件轨
+- 失败命令和输出片段
+- 可疑原因
+- 验证清单
+
+## 输出规则
+
+- 每个 panel 优先是一个完整 HTML 文档。
+- CSS 和 JavaScript 内联。
+- 除非用户明确允许，不要依赖远程资源。
+- panel 必须能在 iframe 中响应式显示。
+- 纯展示是一等输出。只有交互能帮助用户表达文字里难以描述的上下文时，才加入交互。
+- 需要用户推进时用 `stage_choice`：选项发布在面板底部，点选会以一条真实用户消息到达会话。
+  面板内没有旧原型那种 `postMessage` 回传通道，也不需要自己造一个“发送”控件。
+
+- 不要自动回传 hover、拖拽或探索性点击：这些交互只更新面板本地状态。

package/skills/stage-panel/references/visual-style.md

@@ -0,0 +1,43 @@
+# 默认视觉风格
+
+默认是“本地飞船控制台”风格：蓝灰科幻底、高对比黄色、粗黑漫画描边。它只是**可替换的皮肤**——任务语义优先，不合身就换。
+
+## 方向
+
+- 保留硬朗黑色描边和卡通块面。
+- 黄色是主识别色和注意力颜色，保持强对比。
+- 背景使用更明亮的蓝灰/孔雀蓝，不回到大面积黑色。
+- 科幻感来自细网格、扫描线、状态灯和 HUD 小标签，不使用夸张光晕。
+- 小圆角，避免柔软 pill-heavy UI。
+- 面板自己就是主区域：不要在一个面板里再模拟出“左侧栏 + 底部输入”的旧 shell 布局。
+
+## 色板
+
+```text
+Line:   #07111b
+Base:   #31566e
+Deck:   #2e4f67
+Panel:  #2e4c66
+Rail:   #3a5d78
+Yellow: #ffd43b
+Cream:  #fff8d6
+Orange: #ffb454
+Cyan:   #35d8ff
+```
+
+## 布局
+
+```text
+紧凑顶部状态栏（可选）
+主信息区（占满面板）
+底部选项栏：只在 stage_choice 时出现
+```
+
+面板内容不被强制套用固定风格：可以拥有自己的视觉语言，但默认应呼应蓝灰科幻底、黄色高亮和漫画描边。
+
+布局默认值：
+
+- 如果做顶部状态栏，控制在 ~52px 以内。
+- 主信息区占满面板；不要为未激活的选项预留空白。
+- 辅助说明后置或可折叠，不占主信息的位置。
+- 移动端优先保证主信息可读。

package/skills/stage-panel/submode/code/SKILL.md

@@ -0,0 +1,17 @@
+# code —— 代码展示与讲解（面板交互模式·DSH 版）
+
+内容组织遵循 `schemas/lesson.schema.json`（starter / snippets / exercises / annotations / hints）；
+示例见 `examples/*.json`；纯展示面板起点模板 `templates/lab.html`（语法高亮 + 讲解通道）。
+
+## 投递（DSH 原生）
+
+1. 按 lesson schema 组织好一课的素材；
+2. 渲染为 self-contained HTML（可套 lab.html 的布局与讲解通道，不套死）；
+3. `stage_panel`（title=课程名）投影；文字回复只留推理摘要与讲解结论；
+4. 需要学习者推进（看下一步 / 做练习 / 换例子）→ `stage_choice`；点选/作答 = 用户消息，无 wait。
+
+## 纪律
+
+- 编程主战场仍是编辑器：本子模式只把代码作为讲解素材展示，不编辑、不编译、不在浏览器执行。
+- 讲解回合对 panel 内回传的消息正常继续即可。
+- `references/host-toolchains.md` 只在涉及宿主工具链（编译/运行路径）时查阅。

package/skills/stage-panel/submode/code/examples/go-hello-channel.json

@@ -0,0 +1,36 @@
+{
+  "schema_version": 1,
+  "id": "go-hello-channel",
+  "title": "Go：channel 接收一行消息",
+  "subtitle": "最小可运行并发切片",
+  "lang": "go",
+  "level": "intro",
+  "stage": "运行 → 读输出",
+  "summary": "启动 goroutine 发送字符串，主 goroutine 从 channel 接收并打印。",
+  "objectives": [
+    "运行成功看到 hello from goroutine",
+    "解释若去掉 <-ch 会怎样"
+  ],
+  "focus": {
+    "concept": "channel-recv",
+    "trap": "missing-receive-deadlock"
+  },
+  "starter": {
+    "filename": "main.go",
+    "code": "package main\n\nimport \"fmt\"\n\nfunc main() {\n\tch := make(chan string, 1)\n\tgo func() {\n\t\tch <- \"hello from goroutine\"\n\t}()\n\tmsg := <-ch\n\tfmt.Println(msg)\n}\n"
+  },
+  "run": {
+    "filename": "main.go"
+  },
+  "exercises": [
+    {
+      "id": "e1",
+      "type": "short",
+      "prompt": "为什么这里用带缓冲 channel（容量 1）也能工作？无缓冲时要注意什么？"
+    }
+  ],
+  "hints": [
+    "无缓冲 channel 需要发送与接收双方都准备好。",
+    "教学时优先保证 main 会接收，避免进程挂起触发 timeout。"
+  ]
+}

package/skills/stage-panel/submode/code/examples/go-http-api-basics.json

@@ -0,0 +1,58 @@
+{
+  "schema_version": 1,
+  "id": "go-http-api-basics",
+  "title": "Go 调用 API：逐行注释版",
+  "subtitle": "每行都有注释，零基础看懂",
+  "summary": "Go 完全零基础：每行代码都有中文注释，先运行看输出，再改参数，最后解释。",
+  "domain": "deployment",
+  "lang": "go",
+  "level": "intro",
+  "objectives": [
+    "看懂 Go 基本语法",
+    "理解调 API 的代码结构"
+  ],
+  "starter": {
+    "filename": "main.go",
+    "code": "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n)\n\nfunc main() {\n\trequestBody := map[string]interface{}{\n\t\t\"model\": \"gpt-4o-mini\",\n\t\t\"messages\": []map[string]string{\n\t\t\t{\"role\": \"user\", \"content\": \"你好\"},\n\t\t},\n\t}\n\tjsonBody, err := json.Marshal(requestBody)\n\tif err != nil {\n\t\tfmt.Println(\"JSON失败:\", err)\n\t\treturn\n\t}\n\tfmt.Println(\"JSON:\", string(jsonBody))\n\turl := \"https://api.alice001.top/v1/chat/completions\"\n\treq, err := http.NewRequest(\"POST\", url, bytes.NewReader(jsonBody))\n\tif err != nil {\n\t\tfmt.Println(\"构造请求失败:\", err)\n\t\treturn\n\t}\n\tfmt.Println(\"方法:\", req.Method)\n\tfmt.Println(\"地址:\", req.URL)\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\treq.Header.Set(\"Authorization\", \"Bearer sk-test\")\n\tfmt.Println(\"头:\", req.Header)\n}\n"
+  },
+  "run": {},
+  "activities": [
+    {
+      "id": "predict-output",
+      "type": "predict",
+      "prompt": "运行前预测：JSON 那行输出长什么样？方法、地址各是什么？",
+      "required": true,
+      "before_run": true
+    },
+    {
+      "id": "run-and-observe",
+      "type": "trace",
+      "prompt": "点运行，看输出和预测对比。",
+      "required": false
+    },
+    {
+      "id": "change-content",
+      "type": "implement",
+      "prompt": "把 content 的 你好 改成 你是谁，再运行，看 JSON 哪行变了。",
+      "required": true
+    },
+    {
+      "id": "explain-steps",
+      "type": "explain",
+      "prompt": "用自己的话说：这段代码从上到下做了哪几件事？",
+      "required": true
+    }
+  ],
+  "checks": [
+    {
+      "id": "check-runs",
+      "label": "代码能编译运行",
+      "type": "exit_code",
+      "expected": 0
+    }
+  ],
+  "submission": {
+    "require_run": true,
+    "require_reflection": true
+  }
+}

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

@@ -0,0 +1,79 @@
+{
+  "schema_version": 1,
+  "id": "py-agent-loop",
+  "title": "Agent：拆开模型、工具与状态循环",
+  "subtitle": "用可运行的 mock model 看清 Agent harness",
+  "summary": "这个最小 Agent 不调用真实模型，而是用确定性 mock 暴露控制结构：模型提出动作，harness 调工具，把观察写回状态，再让模型生成最终回答。",
+  "domain": "agent",
+  "lang": "python",
+  "level": "intro",
+  "stage": "预测 → 运行 → 跟踪状态 → 修改失败路径",
+  "objectives": [
+    "区分模型与 harness",
+    "跟踪 action/observation 状态",
+    "增加未知工具的失败处理"
+  ],
+  "prerequisites": [
+    "Python 字典、函数、循环"
+  ],
+  "starter": {
+    "filename": "agent.py",
+    "code": "def calculator(expression: str) -> str:\n    left, right = expression.split(\"+\")\n    return str(int(left) + int(right))\n\n\ndef mock_model(messages: list[dict[str, str]]) -> dict[str, str]:\n    if not any(message[\"role\"] == \"tool\" for message in messages):\n        return {\"type\": \"tool_call\", \"name\": \"calculator\", \"args\": \"20+22\"}\n    observation = messages[-1][\"content\"]\n    return {\"type\": \"final\", \"content\": f\"The answer is {observation}.\"}\n\n\ndef run_agent() -> None:\n    messages = [{\"role\": \"user\", \"content\": \"What is 20 + 22?\"}]\n    for step in range(3):\n        action = mock_model(messages)\n        print(f\"step={step} action={action['type']}\")\n        if action[\"type\"] == \"final\":\n            print(f\"answer={action['content']}\")\n            return\n        observation = calculator(action[\"args\"])\n        print(f\"tool={action['name']} observation={observation}\")\n        messages.append({\"role\": \"tool\", \"content\": observation})\n    raise RuntimeError(\"agent exceeded step limit\")\n\n\nrun_agent()\n"
+  },
+  "run": {
+    "filename": "agent.py"
+  },
+  "activities": [
+    {
+      "id": "predict-trace",
+      "type": "predict",
+      "prompt": "运行前写出你预计会出现的 action、tool observation 和 final answer 顺序。",
+      "required": true,
+      "before_run": true
+    },
+    {
+      "id": "explain-harness",
+      "type": "explain",
+      "prompt": "哪些代码属于模型决策，哪些属于 Agent harness？",
+      "required": true
+    },
+    {
+      "id": "transfer-unknown-tool",
+      "type": "transfer",
+      "prompt": "让 mock model 请求 unknown_tool，并为 harness 增加可观察的错误结果，而不是直接崩溃。",
+      "required": true
+    }
+  ],
+  "checks": [
+    {
+      "id": "exit-ok",
+      "label": "Agent 循环正常结束",
+      "type": "exit_code",
+      "expected": 0
+    },
+    {
+      "id": "tool-observation",
+      "label": "轨迹包含工具观察",
+      "type": "stdout_contains",
+      "expected": "observation=42"
+    },
+    {
+      "id": "final-answer",
+      "label": "最终答案包含 42",
+      "type": "stdout_contains",
+      "expected": "answer=The answer is 42."
+    }
+  ],
+  "hints": [
+    "模型只提出结构化动作；真正调用函数的是 harness。",
+    "工具失败也应转成 observation，让下一轮模型能够处理。"
+  ],
+  "submission": {
+    "require_run": true,
+    "require_reflection": true
+  },
+  "next": [
+    "agent-tool-schema",
+    "agent-evaluation-loop"
+  ]
+}