@arcaneorion/dsh-teaching-board 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arcanexis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @arcaneorion/dsh-teaching-board
+
+DSH 会话内的**教学平面**：把 agent 生成的 self-contained HTML 投影成可讲解的板书界面，
+并让使用者直接在板面上**圈画**、把画面**截图**发回对话。
+
+**单一数据流**：面板 = 会话快照的投影，无私有状态、无 RPC、无 wait 闸门。
+用户的每一次推进（点选、发图）都是**真实用户消息**。
+
+## 安装
+
+```bash
+dsh plugin --profile web add @arcaneorion/dsh-teaching-board
+# 然后重启 dsh --profile web 并刷新页面
+```
+
+它是一个 **profile 级 bundle**：装一次，这个进程里所有会话都拿得到 `stage_*` 工具与「教学平面」页签。
+（`dsh plugin add` 会把依赖与 bundles 条目一起写进该 profile 的 manifest。）
+
+## 能力
+
+| 能力 | 实现位置 | 说明 |
+|---|---|---|
+| 板书展示 | client | 面板 HTML 在 `sandbox="allow-scripts"` 的 iframe 里渲染（无同源、无外网） |
+| 手写勾画 | **iframe 内部**（注入 runtime） | 画笔/橡皮、4 色、粗细、撤销、清空；默认不拦截指针事件，切到画笔才接管 |
+| 内置截图 | **iframe 内部**（注入 runtime） | 克隆自身文档 → canvas 换位图 → `XMLSerializer` → `<svg><foreignObject>` → PNG，零依赖零外网 |
+| 截图交给 agent | client（父层） | PNG → `conversation.createDraftImages` → `inputActions.addImages` → 草稿图片 |
+| agent 主动截图 | host 工具 + client 监听 | `stage_snapshot` 工具 → client 从快照看到调用 → 拍图 → 作为用户消息提交 |
+| 状态条 / 方向选择 | host 工具 | `stage_status` / `stage_choice` |
+
+## 架构：两条硬约束
+
+1. **面板 iframe 是 `sandbox="allow-scripts"`（无 `allow-same-origin`）**
+   → 父页面永远读不到面板内部 DOM，也截不了它的图。
+   所以勾画与光栅化都必须在 iframe 内部完成：client 半把一段 runtime **注入**进面板 HTML
+   （`injectRuntime`），父层只通过 `postMessage` 下命令、收结果。
+   好处是笔迹与板书同坐标系：面板内滚动不会让笔迹错位，截图也天然包含笔迹。
+
+2. **静态 bundle 无法注册自定义 Remote，宿主拿不到浏览器里的像素**
+   → 截图**不可能**出现在工具结果里。它走产品既有的用户输入通道回来：
+   client 把 PNG 放进输入草稿，agent 主动请求时再替用户提交——
+   图片作为一条真实用户消息进入会话，模型下一轮就能看见（与 `stage_choice` 同机制）。
+
+## 文件
+
+| 文件 | 说明 |
+|---|---|
+| `src/index.js` | host 半：`stage_panel / stage_status / stage_choice / stage_snapshot` 四个无状态工具 |
+| `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 模式/视觉风格）。
+
+## 板面模型：一块板 = 一个主题
+
+`stage_panel` 不是「一次调用画一张图」，而是**一块板可以被写很多次**——像上课时的黑板：老师写、擦一角、再写，学生上台补几笔，板本身不换。
+
+| 参数 | 作用 |
+|---|---|
+| `board` | 板面 id。同一 id 的连续调用 = **同一块板的演进**；换 id 才是换新板（新主题）。省略 = 一次性整块替换，不保留笔迹 |
+| `op` | `open`（开板/整块重写）/ `append`（默认，在板尾再写一段）/ `set`（替换 `data-stage-region="名称"` 的区域）/ `remove`（擦掉该区域） |
+| `region` | `set`/`remove` 的目标区域名 |
+
+**折叠而非存储**：客户端的板 = 会话日志里同一 `board` id 的那串调用按顺序折叠出来的（`composeBoard`）。没有客户端私有状态，板面内容仍然只是快照的函数——和这套设计的单一数据流一致。`set`/`remove` 用父页面自己的 `DOMParser` 定位区域再序列化，不触碰沙箱里的文档。
+
+**为什么必须这样**：整块重发有三个代价——把学生的笔迹冲掉、把滚动位置顶回顶部、白烧 token（一块 8KB 的板写十次 = 80KB 输出）。`append` 让「再写一段」的成本与「老师在板上再写一行」相当。
+
+**增量而不是重载**：面板是沙箱 iframe，父页面碰不到它的 DOM，所以「换 `srcdoc`」= 整块文档重建：JS 状态、滚动、动画、展开状态全部归零。因此只有三种情况才真的重装——**首次挂载、换 `board`、`op:"open"`**（外加切走页签再切回来这种客户端重挂）。其余 `append`/`set`/`remove` 由父层 `postMessage {cmd:'patch'}` 交给 runtime **原地打进活着的文档**：不重载 → 板内交互状态、滚动位置、动画、笔迹全都不受影响。
+
+**一笔带过的限制**：增量块用 `innerHTML` 插入，所以**块内的 `<script>` 不会执行**——交互逻辑写在 `op:"open"` 那一次里；静态排版、MathML、内联 `onclick` 属性都正常。切走页签再回来会整块重装，那时脚本照常跑。
+
+**画笔与点击共存**：画笔模式下，`pointerdown` 会先做一次 `elementFromPoint` 命中测试，落点是 `a[href]/button/input/select/textarea/label/summary/[role=button]/[onclick]/[contenteditable]` 就把这次点击**转发给控件**、不落笔。所以「偶尔画、偶尔点」不需要来回切模式；唯一代价是控件正上方那几个像素画不了线（要先退出画笔）。
+
+**保留与边界**：
+- 笔迹按 `board` id 存在客户端，板面更新后由父层重新注入（`cmd:'load'`）；滚动位置同理。
+- 笔迹是**视口坐标**：`append` 只往板尾加内容、已有内容不动，所以笔迹对得上；若演进时上半部分重排，旧笔迹会错位——规范是「接着写」时保持板上半部分稳定。
+- 笔迹存在每个客户端自己那里：同一会话开了两个浏览器，两边各画各的，不互相同步。
+- 第一块（`op:"open"`）决定整块板的样式：后续片段共享它的 CSS，所以视觉规范要写在开板那一次里。
+
+## 已知边界
+
+- **截图需要面板处于挂载状态**：`conversation.view` 是「一次只渲染一个」的页签环，
+  用户切到「对话/轨迹」时面板卸载，`stage_snapshot` 就拍不到图（页签没挂载）。
+  （下一步可加一个常驻的离屏截图宿主，挂在对话视图的常驻槽位上。）
+- 外链字体/图片不会进截图，也不会渲染（面板规范要求 self-contained）。
+- 截图为**视口**画面（所见即所得），不是整页长图。
+- 单图超过约 1.2 MB 时自动退化为 JPEG / 等比缩小（模型单图预算）。
+
+## 加载/验证
+
+```bash
+dsh plugin --profile web install        # 补 link symlink（改包源后必须重跑）
+# 重启 dsh --profile web 后：
+# 视图槽位 occupancy 出现 id=teaching-board；工具目录出现 stage_*
+```
+
+> 静态 bundle 改动**需要重启 dsh 进程并刷新页面**，与动态 Cordis 插件的热更新不同。
+> 其它静态化踩坑（boot 解析 / host 需 JS 源 / ModuleLoader handoff / 空配置分支）详见 `../README.md` §4。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# 教学平面 bundle row: 板书视图（勾画 / 截图）+ stage_* 工具（能力层，profile 级）。
+# 行为层 = preset arcane-stage-panel（模式纪律与内容规范）。
+- insert:
+    - id: teaching-board
+      name: '@arcaneorion/dsh-teaching-board'

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@arcaneorion/dsh-teaching-board",
+  "version": "0.4.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./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.",
+  "license": "MIT",
+  "author": "arcanexis",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArcaneOrion/dsh-teaching-board.git"
+  },
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "teaching",
+    "whiteboard",
+    "annotation",
+    "screenshot",
+    "ui",
+    "panel",
+    "iframe"
+  ],
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.1.1-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "slots"
+      ],
+      "platform": "web"
+    }
+  },
+  "homepage": "https://github.com/ArcaneOrion/dsh-teaching-board#readme",
+  "bugs": {
+    "url": "https://github.com/ArcaneOrion/dsh-teaching-board/issues"
+  }
+}

package/src/client.js

@@ -0,0 +1,760 @@
+/** @arcaneorion/dsh-teaching-board — client 半（静态 bundle）。
+ *
+ * 定位：会话内「教学平面」——板书展示 + 手写勾画 + 内置截图。
+ *
+ * 原生设计（单一数据流）：视图 = 会话快照的投影（消费最近一次 stage_panel /
+ * stage_status / stage_choice / stage_snapshot 工具调用，无轮询、无私有 RPC）；
+ * 交互 = inputActions 发真实用户消息。
+ *
+ * 两个硬约束决定了这里的架构：
+ *  1) 面板 iframe 是 sandbox="allow-scripts"（无 allow-same-origin）→ 父页面永远读不到
+ *     面板内部 DOM，也截不了它的图。所以勾画与光栅化都必须在 iframe 内部完成：
+ *     我们把一段 runtime 注入进面板 HTML，父层只通过 postMessage 下命令。
+ *  2) 静态 bundle 无法注册自定义 Remote，宿主拿不到浏览器里的像素 → 截图只能经产品
+ *     既有的用户输入通道回来（草稿图片 + 提交），而不是塞进工具结果。
+ *
+ * client-modules 加载协议：bundle 必须通过 window.__ModuleLoader__.load({ id, factory })
+ * 注册自己（id = 包名，须与 boot graph row 匹配）；factory 接收绑定到模块表的同步
+ * require，一次性执行并返回模块导出（{ name, inject, apply }）。参照 dsh-context。
+ */
+window.__ModuleLoader__.load({
+  id: '@arcaneorion/dsh-teaching-board',
+  factory: (require) => {
+    const { createElement, useEffect, useRef, useState } = require('react')
+
+    const CSS = `
+.stgp-root { display: flex; flex-direction: column; height: 100%; min-height: 0; }
+.stgp-head { flex: none; display: flex; align-items: center; flex-wrap: wrap; gap: 10px; padding: 8px 12px; border-bottom: 1px solid var(--dsw-alias-border-l2); background: var(--dsw-specific-sidebar-fill); }
+.stgp-title { font-weight: 700; color: var(--dsw-alias-label-primary); }
+.stgp-state { font-size: 12px; color: var(--dsw-alias-label-secondary); }
+.stgp-ctx { font-size: 12px; color: var(--dsw-alias-label-secondary); }
+.stgp-tools { display: flex; align-items: center; gap: 6px; margin-left: auto; flex-wrap: wrap; }
+.stgp-tool { border: 1px solid var(--dsw-alias-border-l2); background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); border-radius: 6px; padding: 3px 10px; font: inherit; font-size: 12px; cursor: pointer; }
+.stgp-tool:hover { border-color: var(--dsw-alias-brand-primary); }
+.stgp-tool.on { background: var(--dsw-alias-button-primary-fill); border-color: var(--dsw-alias-button-primary-fill); color: var(--dsw-alias-label-primary-foreground); }
+.stgp-tool.primary { border-color: var(--dsw-alias-brand-primary); color: var(--dsw-alias-brand-primary); }
+.stgp-sw { width: 16px; height: 16px; border-radius: 50%; border: 2px solid transparent; box-shadow: 0 0 0 1px var(--dsw-alias-border-l2); cursor: pointer; padding: 0; }
+.stgp-sw.on { box-shadow: 0 0 0 2px var(--dsw-alias-brand-primary); }
+.stgp-size { width: 62px; }
+.stgp-count { font-size: 12px; color: var(--dsw-alias-label-secondary); min-width: 42px; }
+.stgp-body { flex: 1 1 auto; min-height: 0; position: relative; }
+.stgp-frame { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; background: var(--dsw-alias-bg-base); }
+.stgp-empty { position: absolute; inset: 0; display: grid; place-items: center; color: var(--dsw-alias-label-secondary); font-size: 14px; }
+.stgp-toast { position: absolute; left: 50%; transform: translateX(-50%); bottom: 14px; z-index: 5; max-width: 88%;
+  background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 999px; padding: 6px 16px; font-size: 12.5px; box-shadow: 0 8px 24px rgba(0,0,0,.16); }
+.stgp-choices { flex: none; display: flex; flex-wrap: nowrap; gap: 8px; padding: 10px 12px; border-top: 1px solid var(--dsw-alias-border-l2); overflow-x: auto; overflow-y: hidden; -webkit-overflow-scrolling: touch; mask-image: linear-gradient(to right, #000 0, #000 calc(100% - 24px), transparent 100%); }
+.stgp-choice { flex: none; white-space: nowrap; border: 1px solid var(--dsw-alias-border-l2); background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); border-radius: 6px; padding: 6px 14px; font: inherit; cursor: pointer; }
+.stgp-choice:hover { border-color: var(--dsw-alias-brand-primary); }
+`
+
+    const COLORS = ['#e5484d', '#2f6feb', '#1a7f37', '#111827']
+
+    /** 注入面板文档的 runtime：勾画层 + 光栅化截图。零依赖、零外网。 */
+    const RUNTIME = `
+(function () {
+  if (window.__stagePanelInk) return;
+  var P = { mode: 'off', color: '#e5484d', size: 3 };
+  var strokes = [], cur = null, drawing = false;
+  var MAX_BYTES = 1200 * 1024;
+
+  function send(m) { try { parent.postMessage(m, '*'); } catch (e) {} }
+
+  var cv = document.createElement('canvas');
+  cv.setAttribute('data-stage-ink', '');
+  cv.style.cssText = 'position:fixed;left:0;top:0;width:100%;height:100%;z-index:2147483000;pointer-events:none;touch-action:none;';
+  (document.body || document.documentElement).appendChild(cv);
+  var g = cv.getContext('2d');
+
+  function dpr() { return window.devicePixelRatio || 1; }
+  function fit() {
+    var d = dpr();
+    cv.width = Math.max(1, Math.round(window.innerWidth * d));
+    cv.height = Math.max(1, Math.round(window.innerHeight * d));
+    redraw();
+  }
+  function paintStroke(s) {
+    g.globalCompositeOperation = s.erase ? 'destination-out' : 'source-over';
+    g.strokeStyle = s.color;
+    g.lineWidth = s.erase ? s.size * 5 : s.size;
+    g.lineCap = 'round';
+    g.lineJoin = 'round';
+    g.beginPath();
+    for (var i = 0; i < s.pts.length; i++) {
+      if (i === 0) g.moveTo(s.pts[i][0], s.pts[i][1]); else g.lineTo(s.pts[i][0], s.pts[i][1]);
+    }
+    if (s.pts.length === 1) g.lineTo(s.pts[0][0] + 0.1, s.pts[0][1]);
+    g.stroke();
+    g.globalCompositeOperation = 'source-over';
+  }
+  function redraw() {
+    var d = dpr();
+    g.setTransform(1, 0, 0, 1, 0, 0);
+    g.clearRect(0, 0, cv.width, cv.height);
+    g.setTransform(d, 0, 0, d, 0, 0);
+    for (var i = 0; i < strokes.length; i++) paintStroke(strokes[i]);
+    if (cur) paintStroke(cur);
+  }
+  function count() { send({ __stagePanel: true, type: 'ink', strokes: strokes.length, data: strokes }); }
+
+  var INTERACTIVE = 'a[href],button,input,select,textarea,label,summary,[role="button"],[onclick],[contenteditable="true"]';
+
+  /** 画笔模式下点到控件：把这次点击转发给控件，而不是画一条线。
+   *  这样「偶尔画、偶尔点」不需要来回切模式。 */
+  function forwardClick(x, y) {
+    var prev = cv.style.pointerEvents;
+    cv.style.pointerEvents = 'none';
+    var el = null;
+    try { el = document.elementFromPoint(x, y); } catch (e) { el = null; }
+    cv.style.pointerEvents = prev;
+    if (!el || el === cv) return false;
+    var hit = null;
+    try { hit = el.closest ? el.closest(INTERACTIVE) : null; } catch (e) { hit = null; }
+    if (!hit) return false;
+    try { hit.click(); } catch (e) {}
+    return true;
+  }
+
+  // ── 增量：把新到的 op 原地打进自己的 DOM（不重载、不丢状态） ──────────────
+  function regionNode(name) {
+    if (typeof name !== 'string' || name === '') return null;
+    try { return document.querySelector('[data-stage-region="' + name.replace(/"/g, '') + '"]'); } catch (e) { return null; }
+  }
+  function appendBlock(html, region) {
+    var s = document.createElement('section');
+    s.className = 'stg-block';
+    if (typeof region === 'string' && region !== '') s.setAttribute('data-stage-region', region);
+    s.innerHTML = typeof html === 'string' ? html : '';
+    (document.body || document.documentElement).appendChild(s);
+  }
+  function setRegionBlock(region, html) {
+    var n = regionNode(region);
+    if (!n) return appendBlock(html, region);
+    n.innerHTML = typeof html === 'string' ? html : '';
+  }
+  function removeRegionBlock(region) {
+    var n = regionNode(region);
+    if (n && n.parentNode) n.parentNode.removeChild(n);
+  }
+
+  cv.addEventListener('pointerdown', function (e) {
+    if (P.mode === 'off') return;
+    if (forwardClick(e.clientX, e.clientY)) return;
+    drawing = true;
+    try { cv.setPointerCapture(e.pointerId); } catch (err) {}
+    cur = { color: P.color, size: P.size, erase: P.mode === 'erase', pts: [[e.clientX, e.clientY]] };
+    redraw();
+  });
+  cv.addEventListener('pointermove', function (e) {
+    if (!drawing) return;
+    cur.pts.push([e.clientX, e.clientY]);
+    redraw();
+  });
+  function end() {
+    if (!drawing) return;
+    drawing = false;
+    strokes.push(cur);
+    cur = null;
+    redraw();
+    count();
+  }
+  cv.addEventListener('pointerup', end);
+  cv.addEventListener('pointercancel', end);
+
+  /** 克隆自身文档，把每个 canvas 换成它自己的位图，再交给 foreignObject 光栅化。 */
+  function rasterize() {
+    return new Promise(function (resolve, reject) {
+      var w = Math.max(1, Math.round(window.innerWidth));
+      var h = Math.max(1, Math.round(window.innerHeight));
+      var clone = document.documentElement.cloneNode(true);
+      var drop = clone.querySelectorAll('[data-stage-capture-ignore]');
+      for (var d = 0; d < drop.length; d++) drop[d].parentNode.removeChild(drop[d]);
+      var srcs = document.querySelectorAll('canvas');
+      var dsts = clone.querySelectorAll('canvas');
+      for (var i = 0; i < srcs.length && i < dsts.length; i++) {
+        var st = window.getComputedStyle(srcs[i]);
+        var im = document.createElement('img');
+        try { im.setAttribute('src', srcs[i].toDataURL('image/png')); } catch (e) { continue; }
+        im.setAttribute('style', 'position:fixed;left:' + st.left + ';top:' + st.top +
+          ';width:' + st.width + ';height:' + st.height + ';');
+        dsts[i].parentNode.replaceChild(im, dsts[i]);
+      }
+      var xml = new XMLSerializer().serializeToString(clone);
+      var svg = '<svg xmlns="http://www.w3.org/2000/svg" width="' + w + '" height="' + h +
+        '" viewBox="0 0 ' + w + ' ' + h + '"><foreignObject x="0" y="0" width="' + w + '" height="' + h +
+        '">' + xml + '</foreignObject></svg>';
+      var img = new Image();
+      img.onload = function () {
+        var c = document.createElement('canvas');
+        c.width = w;
+        c.height = h;
+        var cc = c.getContext('2d');
+        cc.fillStyle = '#ffffff';
+        cc.fillRect(0, 0, w, h);
+        cc.drawImage(img, 0, 0, w, h);
+        resolve(c);
+      };
+      img.onerror = function () { reject(new Error('foreignObject 光栅化失败')); };
+      img.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg);
+    });
+  }
+
+  /** PNG 优先；超过模型单图预算就退到 JPEG，再不行等比缩小。 */
+  function encode(c) {
+    var out = c.toDataURL('image/png');
+    if (out.length * 0.75 <= MAX_BYTES) return out;
+    out = c.toDataURL('image/jpeg', 0.85);
+    if (out.length * 0.75 <= MAX_BYTES) return out;
+    var scale = Math.sqrt(MAX_BYTES / (out.length * 0.75));
+    var c2 = document.createElement('canvas');
+    c2.width = Math.max(1, Math.round(c.width * scale));
+    c2.height = Math.max(1, Math.round(c.height * scale));
+    c2.getContext('2d').drawImage(c, 0, 0, c2.width, c2.height);
+    return c2.toDataURL('image/jpeg', 0.85);
+  }
+
+  function capture(meta) {
+    meta = meta || {};
+    rasterize().then(function (c) {
+      send({
+        __stagePanel: true, type: 'capture', ok: true, dataUrl: encode(c),
+        w: c.width, h: c.height, strokes: strokes.length,
+        auto: meta.auto === true, requestId: meta.requestId || null,
+      });
+    }).catch(function (e) {
+      send({
+        __stagePanel: true, type: 'capture', ok: false, error: String(e && e.message || e),
+        auto: meta.auto === true, requestId: meta.requestId || null,
+      });
+    });
+  }
+
+  window.addEventListener('message', function (e) {
+    var d = e.data;
+    if (!d || d.__stagePanel !== true || typeof d.cmd !== 'string') return;
+    if (d.cmd === 'mode') {
+      P.mode = d.value === 'pen' || d.value === 'erase' ? d.value : 'off';
+      cv.style.pointerEvents = P.mode === 'off' ? 'none' : 'auto';
+      cv.style.cursor = P.mode === 'erase' ? 'cell' : 'crosshair';
+    } else if (d.cmd === 'color') {
+      P.color = String(d.value || P.color);
+    } else if (d.cmd === 'size') {
+      P.size = Number(d.value) || P.size;
+    } else if (d.cmd === 'undo') {
+      strokes.pop();
+      redraw();
+      count();
+    } else if (d.cmd === 'clear') {
+      strokes = [];
+      redraw();
+      count();
+    } else if (d.cmd === 'capture') {
+      capture({ auto: d.auto === true, requestId: d.requestId || null });
+    } else if (d.cmd === 'patch' && Array.isArray(d.ops)) {
+      for (var pi = 0; pi < d.ops.length; pi++) {
+        var po = d.ops[pi] || {};
+        if (po.op === 'append') appendBlock(po.html, po.region);
+        else if (po.op === 'set') setRegionBlock(po.region, po.html);
+        else if (po.op === 'remove') removeRegionBlock(po.region);
+      }
+    } else if (d.cmd === 'load') {
+      // 同一块板的演进：把父层保存的笔迹重新注入新板。
+      strokes = Array.isArray(d.strokes) ? d.strokes : [];
+      redraw();
+      count();
+      if (typeof d.scrollY === 'number' && d.scrollY > 0) {
+        try { window.scrollTo(0, d.scrollY); } catch (e) {}
+      }
+    } else if (d.cmd === 'ping') {
+      send({ __stagePanel: true, type: 'ready' });
+    }
+  });
+
+  // 把滚动位置报给父层，换板后用来还原（学生正在看的那一段不该跳回顶部）。
+  var scrollTimer = null;
+  window.addEventListener('scroll', function () {
+    if (scrollTimer) return;
+    scrollTimer = setTimeout(function () {
+      scrollTimer = null;
+      send({ __stagePanel: true, type: 'scroll', y: window.scrollY || 0 });
+    }, 120);
+  });
+
+  window.addEventListener('resize', fit);
+  fit();
+  count();
+  send({ __stagePanel: true, type: 'ready' });
+  window.__stagePanelInk = { capture: capture, count: function () { return strokes.length; } };
+})();
+`
+
+    /** 把 runtime 注入面板 HTML；没有 </body> 就追加在末尾。 */
+    function injectRuntime(html) {
+      const tag = '<script data-stage-runtime>' + RUNTIME + '<\/script>'
+      if (/<\/body>/i.test(html)) return html.replace(/<\/body>/i, tag + '</body>')
+      if (/<\/html>/i.test(html)) return html.replace(/<\/html>/i, tag + '</html>')
+      return html + tag
+    }
+
+    // ── 板面合成：一块板 = 会话日志里同一 board id 的那串调用折叠出来的 ──────
+    // 投影 = 快照的函数，这条设计在这里也没有例外：不存客户端状态，op 序列就是板的全部真相。
+    const SHELL_HEAD = '<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8">'
+      + '<meta name="viewport" content="width=device-width, initial-scale=1">'
+      + '<style>:root{--ink:#1f2937;--muted:#6b7280;--dim:#9ca3af;--line:#e5e7eb;--brand:#2f6feb;--soft:#f7f8fa}'
+      + '*{box-sizing:border-box}body{margin:0;background:var(--soft);color:var(--ink);'
+      + 'font:15px/1.7 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif}'
+      + '.stg-block{max-width:920px;margin:0 auto;padding:18px 24px 30px;background:#fff;'
+      + 'border-bottom:1px solid var(--line)}'
+      + '.stg-block:first-child{padding-top:24px}'
+      + '.stg-block h2{font-size:14px;margin:0 0 10px;color:var(--muted);letter-spacing:.4px}'
+      + '.stg-block table{width:100%;border-collapse:collapse;font-size:13.5px}'
+      + '.stg-block th,.stg-block td{text-align:left;padding:7px 8px;border-bottom:1px solid var(--line)}'
+      + '</style></head><body>'
+    const SHELL_TAIL = '</body></html>'
+
+    function isDocument(html) {
+      return /<html[\s>]/i.test(html) || /<!doctype/i.test(html)
+    }
+
+    function wrapBlock(frag, region) {
+      const attr = region ? ' data-stage-region="' + String(region).replace(/"/g, '') + '"' : ''
+      return '\n<section class="stg-block"' + attr + '>\n' + frag + '\n</section>\n'
+    }
+
+    function ensureDocument(html) {
+      if (isDocument(html)) return html
+      return SHELL_HEAD + wrapBlock(html, null) + SHELL_TAIL
+    }
+
+    function appendFragment(html, frag, region) {
+      const block = wrapBlock(frag, region)
+      if (/<\/body>/i.test(html)) return html.replace(/<\/body>/i, block + '</body>')
+      return html + block
+    }
+
+    /** op=set/remove：用父页面自己的 DOMParser 定位 data-stage-region，改完序列化回字符串。 */
+    function patchRegion(html, region, frag) {
+      if (typeof region !== 'string' || region === '') return html
+      try {
+        const doc = new DOMParser().parseFromString(ensureDocument(html), 'text/html')
+        const node = doc.querySelector('[data-stage-region="' + region.replace(/"/g, '') + '"]')
+        if (!node) return frag === null ? html : appendFragment(html, frag, region)
+        if (frag === null) {
+          node.parentNode.removeChild(node)
+        } else if (frag.trimStart().slice(0, 1) === '<' && node.tagName === 'SECTION') {
+          node.innerHTML = frag
+        } else {
+          node.innerHTML = frag
+        }
+        return '<!DOCTYPE html>' + doc.documentElement.outerHTML
+      } catch {
+        return html
+      }
+    }
+
+    /** 把一条 op 作用到 HTML 字符串上（首装 / 重载走这条路）。 */
+    function applyOp(html, op) {
+      if (op.op === 'append') return appendFragment(html, op.html, op.region)
+      if (op.op === 'set') return patchRegion(html, op.region, op.html)
+      if (op.op === 'remove') return patchRegion(html, op.region, null)
+      return html
+    }
+
+    /** 把同一 board id 的 stage_panel 调用按顺序折叠成一块板的 HTML。 */
+    function composeBoard(calls) {
+      if (!Array.isArray(calls) || calls.length === 0) return null
+      const last = calls[calls.length - 1]
+      const boardId = typeof last.board === 'string' && last.board !== '' ? last.board : null
+      const list = boardId === null
+        ? [last]
+        : calls.filter((c) => typeof c.board === 'string' && c.board === boardId)
+      if (list.length === 0) return null
+
+      let base = null          // 开板那次的文档（或第一条调用）
+      const ops = []           // 基准之后的增量：可以原地打进活着的 iframe，不必重载
+      let title = null
+      let openCount = 0
+      for (const call of list) {
+        const op = typeof call.op === 'string' && call.op !== '' ? call.op : (base === null ? 'open' : 'append')
+        const frag = typeof call.html === 'string' ? call.html : null
+        const region = typeof call.region === 'string' && call.region !== '' ? call.region : null
+        if (typeof call.title === 'string' && call.title !== '') title = call.title
+        if (op === 'open') {
+          if (frag !== null) {
+            base = frag
+            ops.length = 0
+            openCount += 1
+          }
+          continue
+        }
+        if (base === null) {
+          base = frag === null ? '' : frag
+          continue
+        }
+        ops.push({ op, region, html: frag })
+      }
+      if (base === null) return null
+
+      const baseHtml = ensureDocument(base)
+      let html = baseHtml
+      for (const op of ops) html = applyOp(html, op)
+      return {
+        board: boardId,
+        title,
+        ops,
+        baseHtml,
+        html,
+        openCount,
+        signature: (boardId || 'adhoc') + '|' + openCount + '|' + ops.length,
+      }
+    }
+
+    function parseArgs(raw) {
+      try {
+        const value = JSON.parse(raw)
+        return value && typeof value === 'object' ? value : null
+      } catch {
+        return null
+      }
+    }
+
+    /** data:image/...;base64,xxx → File（走产品既有的草稿图片通道）。 */
+    function dataUrlToFile(dataUrl, name) {
+      const comma = dataUrl.indexOf(',')
+      const head = dataUrl.slice(0, comma)
+      const type = (head.match(/^data:([^;]+)/) || [])[1] || 'image/png'
+      const binary = atob(dataUrl.slice(comma + 1))
+      const bytes = new Uint8Array(binary.length)
+      for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+      return new File([bytes], name, { type })
+    }
+
+    function apply(ctx) {
+      ctx.effect(() => {
+        const tag = document.createElement('style')
+        tag.dataset.stagePanelStyle = ''
+        tag.textContent = CSS
+        document.head.appendChild(tag)
+        return () => tag.remove()
+      }, 'teaching-board: styles')
+
+      function StagePanelView(props) {
+        const { useSession, useInput, inputActions } = props
+        const latest = useSession((snapshot) => {
+          const panels = []
+          let status = null
+          let choice = null
+          let snapReq = null
+          for (const node of snapshot.nodes) {
+            if (!node) continue
+            const call = node.call || null
+            const name = (call && call.name) || node.name || null
+            if (name === 'stage_snapshot') {
+              // 工具调用先于结果出现；用 callId 去重，保证每个请求只截一次。
+              const callId = node.callId || (call && call.callId) || null
+              if (callId) {
+                const args = parseArgs(node.argsRaw || (call && call.argsRaw) || '')
+                snapReq = { callId, note: args && typeof args.note === 'string' ? args.note : '' }
+              }
+            }
+            if (node.kind !== 'tool-result' || !call) continue
+            if (call.name === 'stage_panel') {
+              const args = parseArgs(call.argsRaw)
+              if (args) panels.push(args)
+            } else if (call.name === 'stage_status') status = parseArgs(call.argsRaw)
+            else if (call.name === 'stage_choice') choice = parseArgs(call.argsRaw)
+          }
+          return { panels, status, choice, snapReq }
+        })
+
+        const frameRef = useRef(null)
+        const handledRef = useRef(new Set())
+        const warnedRef = useRef(new Set())
+        const toolRef = useRef({ mode: 'off', color: COLORS[0], size: 3 })
+        const boardsRef = useRef(new Map())   // boardId -> { strokes, scrollY }
+        const boardIdRef = useRef(null)
+        // 新 iframe 载入时，runtime 会先报一次空笔迹（初始 count）；那一条必须丢掉，
+        // 否则它会在 ready 触发的“还笔迹”之前把存下来的笔迹冲掉。
+        const awaitingReadyRef = useRef(true)
+        // 活着的 iframe 已经吃进去多少条 op（装载时烘进 HTML 的 + 之后 postMessage 打进去的）
+        const appliedRef = useRef(0)
+        const opsRef = useRef([])
+        const docRef = useRef({ key: null, html: null })
+        const [doc, setDoc] = useState(docRef.current)
+        const [tool, setTool] = useState(toolRef.current)
+        const [strokes, setStrokes] = useState(0)
+        const [toast, setToast] = useState('')
+
+        const status = latest.status || null
+        const choice = latest.choice || null
+        const options = choice && Array.isArray(choice.options) ? choice.options : []
+        const composed = composeBoard(latest.panels)
+        const boardId = composed ? composed.board : null
+        boardIdRef.current = boardId
+        const boardTitle = (composed && composed.title) || (status && status.title) || '教学平面'
+        opsRef.current = composed === null ? [] : composed.ops
+        const signature = composed === null ? 'none' : composed.signature
+        const srcDoc = doc.html
+
+        // 输入框是否空闲。agent 主动截图只在空闲时替用户提交——否则会把人家正在写的
+        // 草稿一起发出去。hook 必须在组件顶层调用，结果存进 ref 供消息监听器
+        // （那个闭包早于后续渲染）读到最新值。
+        const useInputSafe = typeof useInput === 'function' ? useInput : null
+        const idleNow = useInputSafe
+          ? useInputSafe((s) => s.draft === '' && (Array.isArray(s.imageIds) ? s.imageIds.length === 0 : true))
+          : true
+        const idleRef = useRef(true)
+        idleRef.current = idleNow !== false
+
+        const send = (text) => {
+          try {
+            if (inputActions) {
+              inputActions.setDraft(text)
+              inputActions.submit()
+            }
+          } catch {
+            /* 提交失败仅静默，不阻塞视图 */
+          }
+        }
+
+        const post = (msg) => {
+          const frame = frameRef.current
+          if (frame && frame.contentWindow) {
+            try { frame.contentWindow.postMessage({ __stagePanel: true, ...msg }, '*') } catch { /* 面板已卸载 */ }
+          }
+        }
+
+        const flash = (text) => {
+          setToast(text)
+          window.setTimeout(() => setToast((cur) => (cur === text ? '' : cur)), 3600)
+        }
+
+        /** 截图 → 草稿图片；auto=true 时再替用户提交（agent 主动请求的路径）。 */
+        const deliver = (dataUrl, auto, note) => {
+          const conversation = ctx.get('conversation')
+          if (!conversation || typeof conversation.createDraftImages !== 'function') {
+            flash('截图成功，但 conversation 服务不可用，无法放入输入框')
+            return
+          }
+          if (!inputActions || typeof inputActions.addImages !== 'function') {
+            flash('截图成功，但输入框不可用，无法放入草稿')
+            return
+          }
+          let ids
+          try {
+            const file = dataUrlToFile(dataUrl, `stage-panel-${Date.now()}.png`)
+            const created = conversation.createDraftImages([file])
+            ids = (created || []).map((a) => a.id)
+          } catch (error) {
+            flash('截图已生成，但附件创建失败：' + (error && error.message ? error.message : error))
+            return
+          }
+          if (ids.length === 0) {
+            flash('截图已生成，但附件创建失败')
+            return
+          }
+          // 提交阶段可能短暂拒绝（admission/claim 中），退避重试几次再放弃。
+          const attempt = (left) => {
+            let accepted = false
+            try { accepted = inputActions.addImages(ids) } catch { accepted = false }
+            if (accepted) {
+              if (auto) {
+                if (!idleRef.current) {
+                  // 用户正在写东西：只放入口，不替他按回车。
+                  flash('agent 请求了这个板面的截图：已放入输入框（你正在输入，没有自动发送）')
+                  return
+                }
+                try {
+                  if (note) inputActions.setDraft(note)
+                  inputActions.submit()
+                  flash('已把面板截图发回会话')
+                } catch {
+                  flash('截图已放入输入框，但自动发送失败，请手动回车')
+                }
+              } else {
+                flash('截图已放入输入框 —— 补充一句说明后回车发送')
+              }
+              return
+            }
+            if (left <= 1) {
+              flash('截图已生成，但输入框当前拒绝图片（可能在忙或超限）')
+              return
+            }
+            window.setTimeout(() => attempt(left - 1), 700)
+          }
+          attempt(5)
+        }
+
+        useEffect(() => {
+          const onMessage = (event) => {
+            const d = event.data
+            if (!d) return
+            if (d.__stagePanel === true) {
+              if (d.type === 'capture') {
+                if (d.ok === true && typeof d.dataUrl === 'string') {
+                  deliver(d.dataUrl, d.auto === true, d.note || '')
+                } else {
+                  flash('截图失败：' + (d.error || '未知原因'))
+                }
+              } else if (d.type === 'ink') {
+                if (awaitingReadyRef.current) return   // 初始空笔迹：丢掉，等 ready 还笔迹
+                setStrokes(Number(d.strokes) || 0)
+                const id = boardIdRef.current
+                if (id && Array.isArray(d.data)) {
+                  const rec = boardsRef.current.get(id) || { strokes: [], scrollY: 0 }
+                  rec.strokes = d.data
+                  boardsRef.current.set(id, rec)
+                }
+              } else if (d.type === 'scroll') {
+                const id = boardIdRef.current
+                if (id) {
+                  const rec = boardsRef.current.get(id) || { strokes: [], scrollY: 0 }
+                  rec.scrollY = Number(d.y) || 0
+                  boardsRef.current.set(id, rec)
+                }
+              } else if (d.type === 'ready') {
+                awaitingReadyRef.current = false
+                // iframe 刚载入：把当前工具状态推回去（用 ref 避免闭包过期），
+                // 补上装载之后才到的增量，再把这块板之前存下的笔迹与滚动位置还回去。
+                const t = toolRef.current
+                post({ cmd: 'mode', value: t.mode })
+                post({ cmd: 'color', value: t.color })
+                post({ cmd: 'size', value: t.size })
+                const all = opsRef.current || []
+                const tail = all.slice(appliedRef.current)
+                appliedRef.current = all.length
+                if (tail.length > 0) post({ cmd: 'patch', ops: tail })
+                const id = boardIdRef.current
+                const rec = id ? boardsRef.current.get(id) : null
+                post({ cmd: 'load', strokes: (rec && rec.strokes) || [], scrollY: (rec && rec.scrollY) || 0 })
+              }
+              return
+            }
+            if (d.localweb === true && d.type === 'panel_input' && typeof d.text === 'string') {
+              send(d.text)
+            }
+          }
+          window.addEventListener('message', onMessage)
+          return () => window.removeEventListener('message', onMessage)
+        }, [])
+
+        useEffect(() => {
+          if (composed === null) {
+            if (docRef.current.key !== null) {
+              docRef.current = { key: null, html: null }
+              setDoc(docRef.current)
+            }
+            return
+          }
+          const key = composed.board + '#' + composed.openCount
+          // 同一份文档：不再换 srcdoc（换 = 整块重载），增量走 postMessage。
+          if (docRef.current.key === key) return
+          const next = { key, html: injectRuntime(composed.html) }
+          docRef.current = next
+          appliedRef.current = composed.ops.length   // 这份文档里已经烘进去了
+          awaitingReadyRef.current = true
+          setDoc(next)
+        }, [signature])
+
+        // 增量：新到的 op 原地打进活着的 iframe —— 不重载 → 板内状态、滚动、动画都不受影响。
+        useEffect(() => {
+          if (composed === null) return
+          if (docRef.current.key !== composed.board + '#' + composed.openCount) return
+          if (awaitingReadyRef.current) return       // 装载中：等 ready 统一同步
+          const tail = composed.ops.slice(appliedRef.current)
+          if (tail.length === 0) return
+          appliedRef.current = composed.ops.length
+          post({ cmd: 'patch', ops: tail })
+        }, [signature])
+
+        // agent 主动截图：快照里出现未处理的 stage_snapshot 调用就拍一张。
+        // 面板没挂载时不标记已处理，等它挂上再拍。
+        useEffect(() => {
+          const req = latest.snapReq
+          if (!req || !req.callId) return
+          if (handledRef.current.has(req.callId)) return
+          if (srcDoc === null) {
+            if (!warnedRef.current.has(req.callId)) {
+              warnedRef.current.add(req.callId)
+              flash('agent 请求截图，但面板未打开 —— 请切到「面板」页签')
+            }
+            return
+          }
+          handledRef.current.add(req.callId)
+          post({ cmd: 'capture', auto: true, requestId: req.callId, note: req.note })
+        }, [latest.snapReq && latest.snapReq.callId, srcDoc])
+
+        const setMode = (mode) => {
+          const next = tool.mode === mode ? 'off' : mode
+          toolRef.current = { ...toolRef.current, mode: next }
+          setTool(toolRef.current)
+          post({ cmd: 'mode', value: next })
+        }
+
+        return createElement('div', { className: 'stgp-root' },
+          createElement('div', { className: 'stgp-head' },
+            createElement('span', { className: 'stgp-title' }, (status && status.title) || '教学平面'),
+            createElement('span', { className: 'stgp-state' }, (status && status.state) || 'idle'),
+            status && Array.isArray(status.context) ? status.context.map((c, i) =>
+              createElement('span', { className: 'stgp-ctx', key: i }, `${c.label}: ${c.value}`)) : null,
+            createElement('div', { className: 'stgp-tools' },
+              createElement('button', { className: 'stgp-tool' + (tool.mode === 'pen' ? ' on' : ''), onClick: () => setMode('pen') }, '画笔'),
+              createElement('button', { className: 'stgp-tool' + (tool.mode === 'erase' ? ' on' : ''), onClick: () => setMode('erase') }, '橡皮'),
+              COLORS.map((c) => createElement('button', {
+                key: c,
+                className: 'stgp-sw' + (tool.color === c ? ' on' : ''),
+                style: { background: c },
+                title: c,
+                onClick: () => {
+                  toolRef.current = { ...toolRef.current, color: c }
+                  setTool(toolRef.current)
+                  post({ cmd: 'color', value: c })
+                },
+              })),
+              createElement('input', {
+                className: 'stgp-size', type: 'range', min: 1, max: 14, value: tool.size,
+                onChange: (e) => {
+                  const v = Number(e.target.value)
+                  toolRef.current = { ...toolRef.current, size: v }
+                  setTool(toolRef.current)
+                  post({ cmd: 'size', value: v })
+                },
+              }),
+              createElement('button', { className: 'stgp-tool', onClick: () => post({ cmd: 'undo' }) }, '撤销'),
+              createElement('button', { className: 'stgp-tool', onClick: () => post({ cmd: 'clear' }) }, '清空'),
+              createElement('span', { className: 'stgp-count' }, strokes + ' 笔'),
+              createElement('button', { className: 'stgp-tool primary', onClick: () => post({ cmd: 'capture', auto: false }) }, '截图'),
+            ),
+          ),
+          createElement('div', { className: 'stgp-body' },
+            srcDoc !== null
+              ? createElement('iframe', {
+                  ref: frameRef,
+                  className: 'stgp-frame',
+                  sandbox: 'allow-scripts',
+                  title: boardTitle,
+                  srcDoc,
+                })
+              : createElement('div', { className: 'stgp-empty' }, '暂无板书 —— 让 agent 调用 stage_panel 渲染一个'),
+            toast ? createElement('div', { className: 'stgp-toast' }, toast) : null,
+          ),
+          options.length > 0
+            ? createElement('div', { className: 'stgp-choices' },
+                options.map((o) => createElement('button', {
+                  className: 'stgp-choice',
+                  key: o.id,
+                  onClick: () => send(`[面板选择] ${o.label}`),
+                }, o.label)))
+            : null,
+        )
+      }
+
+      ctx.slots.inject('conversation.view', () => ctx.slots.register(
+        { name: 'conversation.view', id: 'stage-panel', order: 40, label: '教学平面' },
+        (props) => createElement(StagePanelView, props),
+      ))
+    }
+
+    return { name: 'teaching-board', inject: ['slots'], apply }
+  },
+})

package/src/index.js

@@ -0,0 +1,126 @@
+/** @arcaneorion/dsh-teaching-board — host 半（静态 bundle）。
+ *
+ * 定位：会话内「教学平面」——把 agent 生成的 self-contained HTML 投影为可讲解、
+ * 可勾画、可截图的板书界面。
+ *
+ * 原生设计（单一数据流）：只注册模型工具，无私有状态、无 RPC、无 wait。
+ * 「面板」状态 = 会话中最近一次 stage_* 工具调用的参数（client 从会话快照消费）；
+ * 用户点选/回传 = 真实用户消息（DSH 原生输入流）。
+ *
+ * 截图为什么不能出现在工具结果里：面板渲染在用户浏览器的沙箱 iframe 内，宿主拿不到
+ * 那些像素，而静态 bundle 也无法向客户端注册自定义 Remote 端点。所以截图走产品既有的
+ * 用户输入通道回来——client 半捕获后把 PNG 放进输入草稿并提交，图片作为一条真实用户
+ * 消息进入会话，模型在下一轮就能看见。这与 stage_choice 的机制完全一致。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'teaching-board'
+export const inject = ['tools']
+
+export function apply(ctx) {
+  const textRender = (_args, value) => [{ type: 'text', text: value }]
+
+  ctx.tools.register(defineTool({
+    name: 'stage_panel',
+    description:
+      '在教学平面（「教学平面」页签，沙箱 iframe）上写板书。'
+      + '一块板 = 一个主题/一节课：用同一个 board id 连续调用很多次都算「同一块板在演进」，'
+      + '学生的圈画笔迹与滚动位置会保留；换 board id 才是换新板（新板 = 新主题）。'
+      + '更新方式用 op 选择：append（默认，在板尾再写一段，最省 token）/ open（开板或整块重写）/ '
+      + 'set（替换 HTML 里 data-stage-region="名称" 的那块）/ remove（擦掉某块）。'
+      + '所以「再写一段」不要重发整块 HTML——那会丢掉学生笔迹、把滚动顶回去，也白烧 token。'
+      + '面板 HTML 必须 self-contained（内联 CSS/JS、data: 资源，不依赖外网）；公式用 MathML（浏览器原生，零依赖）。'
+      + '面板内纯本地交互（筛选/tab/滑块等）不打扰对话；需要用户在方向上做选择时另用 stage_choice；'
+      + '要看学生圈了什么用 stage_snapshot。',
+    parameters: {
+      html: { type: 'string', description: '本次写入板面的 HTML（op=open/append/set 必需；可为完整文档，也可为片段）' },
+      board: { type: 'string', description: '板面 id（如 "stats-se5"）。同一 id 的多次调用 = 同一块板的连续演进。省略 = 一次性整块替换，不保留笔迹。' },
+      op: { type: 'string', description: 'open=开板/整块替换；append=在板尾追加（默认）；set=替换某个 data-stage-region 区域；remove=移除该区域。' },
+      region: { type: 'string', description: 'op=set/remove 时的区域名，对应 HTML 里的 data-stage-region="名称"。' },
+      title: { type: 'string', description: '板面标题（显示在状态条）' },
+    },
+    output: { schema: { type: 'string' }, render: textRender },
+    execute: async (args) => {
+      const op = typeof args.op === 'string' && args.op !== '' ? args.op : 'append'
+      const board = typeof args.board === 'string' && args.board !== '' ? args.board : null
+      const region = typeof args.region === 'string' && args.region !== '' ? args.region : null
+      const html = typeof args.html === 'string' ? args.html : null
+      if (html === null && op !== 'remove') {
+        return JSON.stringify({ ok: false, error: `op=${op} 需要 html` })
+      }
+      if ((op === 'set' || op === 'remove') && region === null) {
+        return JSON.stringify({ ok: false, error: `op=${op} 需要 region` })
+      }
+      return JSON.stringify({
+        ok: true,
+        rendered: true,
+        board: board === null ? '(一次性板面)' : board,
+        op,
+        region,
+        title: typeof args.title === 'string' ? args.title : null,
+        note: board === null
+          ? '未给 board：一次性整块替换，学生笔迹会被清掉。同一主题的演进请带上 board id。'
+          : '请结束本轮回复；教学平面按这个 op 更新，学生笔迹保留。',
+      })
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'stage_status',
+    description: '更新「教学平面」的状态条与上下文信息（当前讲到哪、任务、阶段、等待态等）。',
+    parameters: {
+      title: { type: 'string', description: '状态条标题（通常是当前这一段教学的主题）' },
+      state: { type: 'string', description: '状态：idle / working / waiting_for_user / done' },
+      context: { type: 'array', description: '上下文行数组 [{label,value}]，例如 [{label:"进度",value:"3/8"}]' },
+    },
+    output: { schema: { type: 'string' }, render: textRender },
+    execute: async (args) => JSON.stringify({
+      ok: true,
+      status: {
+        title: typeof args.title === 'string' ? args.title : null,
+        state: typeof args.state === 'string' ? args.state : null,
+        context: Array.isArray(args.context) ? args.context.length : 0,
+      },
+    }),
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'stage_choice',
+    description:
+      '在教学平面底部发布方向选项（choice 栏），用于「下一步讲什么 / 要不要继续」这类分支。'
+      + '发布后结束本轮：用户点选会以用户消息（“[面板选择] <选项>”）到达本会话，无需也不要用任何 wait 工具。',
+    parameters: {
+      id: { type: 'string', required: true, description: 'choice 组 id' },
+      options: { type: 'array', required: true, description: '[{id,label}] 选项数组' },
+    },
+    output: { schema: { type: 'string' }, render: textRender },
+    execute: async (args) => {
+      const opts = Array.isArray(args.options)
+        ? args.options.filter((o) => o && typeof o.id === 'string').map((o) => ({ id: o.id, label: typeof o.label === 'string' ? o.label : o.id }))
+        : []
+      return JSON.stringify({ ok: true, choiceId: args.id, optionCount: opts.length, next: '用户点选后将以用户消息到达，无需 wait' })
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'stage_snapshot',
+    description:
+      '请求把「教学平面」当前的画面截图（含用户在其上的圈画笔迹），并把这张图发回本会话。'
+      + '图片不会出现在本工具的结果里：它会作为一条带图片的真实用户消息回来，你在下一轮就能看到它——'
+      + '所以调用后请结束本轮，不要在同一轮里假装已经看到图。'
+      + '生效前提：用户此刻正停留在「教学平面」页签（该页签没挂载就截不到图，此时会返回失败原因，请让用户切到教学平面页签后重试）。'
+      + '典型用途：学生圈出了看不懂的地方让你看、你想核对自己画的板书是否讲清楚了、想把当前画面留档。'
+      + '不要连续调用；每轮最多一次。',
+    parameters: {
+      note: { type: 'string', description: '随图片一起发回的一句话说明（例如「请看我圈的这一步」）。默认“［面板截图］”。' },
+    },
+    output: { schema: { type: 'string' }, render: textRender },
+    execute: async (args) => JSON.stringify({
+      ok: true,
+      requested: true,
+      requestId: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+      note: typeof args.note === 'string' && args.note.trim() !== '' ? args.note : '［面板截图］',
+      next: '结束本轮；client 半会在面板挂载时截图并以用户消息发回，你在下一轮看到图片。',
+    }),
+  }))
+}