@arcaneorion/dsh-teaching-board 0.4.1 → 0.5.1

package/src/client.js

@@ -56,12 +56,22 @@ window.__ModuleLoader__.load({
   if (window.__stagePanelInk) return;
   var P = { mode: 'off', color: '#e5484d', size: 3 };
   var strokes = [], cur = null, drawing = false;
+  var anchorCache = {};   // 一次重绘内，同一块只算一次位移
+  var lastSX = -1, lastSY = -1;   // 上次重绘时的滚动位置（判断要不要重画）
   var MAX_BYTES = 1200 * 1024;
 
   function send(m) { try { parent.postMessage(m, '*'); } catch (e) {} }
 
   var cv = document.createElement('canvas');
   cv.setAttribute('data-stage-ink', '');
+  /**
+   * 画布仍是**视口大小**（内存恒定，不受板面长度影响 —— 铺满整份文档在长板子上
+   * 会变成几十 MB 的位图，移动端还有 canvas 面积上限），
+   * 但笔迹存的是**文档坐标**，重绘时按滚动量平移 —— 于是它钉在板面内容上。
+   *
+   * 原实现存 clientX/clientY 且不平移：笔迹其实钉在**屏幕**上，
+   * 一滚动（或 AI 增量写板把内容推下去）就与内容错位。
+   */
   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');
@@ -69,11 +79,20 @@ window.__ModuleLoader__.load({
   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));
+    var w = Math.max(1, Math.round(window.innerWidth));
+    var h = Math.max(1, Math.round(window.innerHeight));
+    cv.style.width = w + 'px';
+    cv.style.height = h + 'px';
+    var nw = Math.max(1, Math.round(w * d));
+    var nh = Math.max(1, Math.round(h * d));
+    if (nw === cv.width && nh === cv.height) return;   // 尺寸没变就别白清一次位图
+    cv.width = nw;
+    cv.height = nh;
     redraw();
   }
-  function paintStroke(s) {
+  function paintStroke(s, dx, dy) {
+    dx = dx || 0;
+    dy = dy || 0;
     g.globalCompositeOperation = s.erase ? 'destination-out' : 'source-over';
     g.strokeStyle = s.color;
     g.lineWidth = s.erase ? s.size * 5 : s.size;
@@ -81,19 +100,45 @@ window.__ModuleLoader__.load({
     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 (i === 0) g.moveTo(s.pts[i][0] + dx, s.pts[i][1] + dy);
+      else g.lineTo(s.pts[i][0] + dx, s.pts[i][1] + dy);
     }
-    if (s.pts.length === 1) g.lineTo(s.pts[0][0] + 0.1, s.pts[0][1]);
+    if (s.pts.length === 1) g.lineTo(s.pts[0][0] + dx + 0.1, s.pts[0][1] + dy);
     g.stroke();
     g.globalCompositeOperation = 'source-over';
   }
   function redraw() {
     var d = dpr();
+    lastSX = window.scrollX || 0;
+    lastSY = window.scrollY || 0;
+    anchorCache = {};   // 每次重绘重新解析锚点（块可能刚被 AI 改写 / 移动过）
     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);
+    // ★ 视口画布 + 按滚动量平移：笔迹存的是文档坐标，平移之后正好落在板面内容上。
+    g.translate(-lastSX, -lastSY);
+    for (var i = 0; i < strokes.length; i++) {
+      var off = strokeDelta(strokes[i]);
+      paintStroke(strokes[i], off[0], off[1]);
+    }
+    if (cur) {
+      var offCur = strokeDelta(cur);
+      paintStroke(cur, offCur[0], offCur[1]);
+    }
+  }
+
+  /**
+   * 滚动 = 笔迹要跟着内容走。
+   *
+   * ⚠️ 必须**同步**重画，不能塞进 requestAnimationFrame：
+   * 后台标签页 / 被遮挡的 iframe 里 rAF 会被浏览器暂停，那样笔迹就定格在旧位置
+   * （实测：审计测试 C/D 两项就是被这个坑掉的）。浏览器本来就把 scroll 事件
+   * 节流到每帧一次，同步重画不会把主线程刷爆。
+   */
+  function syncScroll() {
+    var x = window.scrollX || 0, y = window.scrollY || 0;
+    if (x === lastSX && y === lastSY) return;   // 位置没动就别白画一遍
+    redraw();
   }
   function count() { send({ __stagePanel: true, type: 'ink', strokes: strokes.length, data: strokes }); }
 
@@ -137,17 +182,89 @@ window.__ModuleLoader__.load({
     if (n && n.parentNode) n.parentNode.removeChild(n);
   }
 
+  /** 视口坐标 → **文档坐标**（笔迹的坐标系：原点 = 文档左上角）。
+      画布是视口大小的浮层，指针事件给的是 clientX/clientY，所以必须加上
+      当前滚动量换算成文档坐标；原实现直接把 clientX/clientY 存下来，
+      笔迹其实钉在屏幕上 —— 一滚动、或 AI 增量写板把内容推下去，就与内容错位。 */
+  function toBoard(e) {
+    var r = cv.getBoundingClientRect();
+    return [
+      e.clientX - r.left + (window.scrollX || 0),
+      e.clientY - r.top + (window.scrollY || 0),
+    ];
+  }
+
+  /**
+   * 这一笔落在哪一块上（.stg-block），记下它的**文档原点**当锚点。
+   *
+   * 为什么需要锚点：文档坐标只解决「滚动」，解决不了「重排」——
+   * AI 在用户圈过的那段上面又写了一段（set/remove 也会改变高度），
+   * 那段文字整体下移，而笔迹的文档坐标没变，于是又脱开了。
+   * 锚在「它所在的那一块」上，块移动多少，笔迹就跟着移动多少 —— 这才是写在书上。
+   *
+   * ⚠️ 不能用 elementFromPoint：画布盖在最上层，内容层根本点不到。
+   */
+  function anchorAt(clientX, clientY) {
+    var blocks = document.querySelectorAll('.stg-block');
+    for (var i = 0; i < blocks.length; i++) {
+      var r = blocks[i].getBoundingClientRect();
+      if (clientY >= r.top && clientY <= r.bottom && clientX >= r.left && clientX <= r.right) {
+        return {
+          region: blocks[i].getAttribute('data-stage-region') || null,
+          index: i,
+          ox: r.left + (window.scrollX || 0),
+          oy: r.top + (window.scrollY || 0),
+        };
+      }
+    }
+    return null;   // 落在块外的空白上（比如最后一块下面那片留白）：只能靠文档坐标
+  }
+
+  /** 锚点现在跑到哪了（相对画下去时的位置）。块没了就退回绝对坐标。 */
+  function anchorDeltaByKey(key) {
+    var cached = anchorCache[key];
+    if (cached !== undefined) return cached;
+
+    var a = JSON.parse(key);   // [region, index, ox, oy]
+    var node = null;
+    if (a[0]) {
+      try { node = document.querySelector('[data-stage-region="' + String(a[0]).replace(/"/g, '') + '"]'); } catch (e) { node = null; }
+    }
+    if (!node) {
+      var all = document.querySelectorAll('.stg-block');
+      node = all[a[1]] || null;
+    }
+    var out = [0, 0];
+    if (node) {
+      var r = node.getBoundingClientRect();
+      out = [r.left + (window.scrollX || 0) - a[2], r.top + (window.scrollY || 0) - a[3]];
+    }
+    anchorCache[key] = out;
+    return out;
+  }
+
+  function strokeDelta(s) {
+    var a = s.anchor;
+    if (!a) return [0, 0];
+    return anchorDeltaByKey(JSON.stringify([a.region, a.index, Math.round(a.ox), Math.round(a.oy)]));
+  }
+
   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]] };
+    cur = {
+      color: P.color, size: P.size, erase: P.mode === 'erase',
+      pts: [toBoard(e)],
+      // 记下「这一笔写在哪一段上」—— 那一段以后被推下去，笔迹跟着它走
+      anchor: anchorAt(e.clientX, e.clientY),
+    };
     redraw();
   });
   cv.addEventListener('pointermove', function (e) {
     if (!drawing) return;
-    cur.pts.push([e.clientX, e.clientY]);
+    cur.pts.push(toBoard(e));
     redraw();
   });
   function end() {
@@ -166,6 +283,8 @@ window.__ModuleLoader__.load({
     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 sx = Math.max(0, window.scrollX || 0);
+      var sy = Math.max(0, window.scrollY || 0);
       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]);
@@ -173,15 +292,31 @@ window.__ModuleLoader__.load({
       var dsts = clone.querySelectorAll('canvas');
       for (var i = 0; i < srcs.length && i < dsts.length; i++) {
         var st = window.getComputedStyle(srcs[i]);
+        var rect = srcs[i].getBoundingClientRect();
         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 + ';');
+        /**
+         * ★ img 要放到**文档坐标**上，不能照抄 computed left/top。
+         *
+         * 画布是 position:fixed（视口锚定）的浮层，它的 left/top 恒为 0px ——
+         * 照抄的话，位图会被贴到「文档最顶端」，而它画的却是当前这一屏的笔迹，
+         * 于是截图里的圈和内容差着整整一个滚动距离。
+         * 位图本身画的是「当前视口 + 滚动量平移」的结果，所以要换算成文档坐标再绝对定位；
+         * 再配合下面 SVG 的 viewBox（= 当前视口），拍到的才是「你正在看的那一屏」。
+         */
+        var left = Math.round(rect.left + sx);
+        var top = Math.round(rect.top + sy);
+        im.setAttribute('style', 'position:absolute;left:' + left + 'px;top:' + top + 'px;' +
+          'width:' + st.width + ';height:' + st.height + ';z-index:2147483000;');
         dsts[i].parentNode.replaceChild(im, dsts[i]);
       }
       var xml = new XMLSerializer().serializeToString(clone);
+      // 文档可能比视口长：foreignObject 装整份文档，viewBox 只框当前视口 ——
+      // 拍到的就是你正在看的区域（含笔迹），而不是文档开头。
+      var docW = Math.max(w, document.documentElement.scrollWidth || 0);
+      var docH = Math.max(h, document.documentElement.scrollHeight || 0);
       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 +
+        '" viewBox="' + sx + ' ' + sy + ' ' + w + ' ' + h + '"><foreignObject x="0" y="0" width="' + docW + '" height="' + docH +
         '">' + xml + '</foreignObject></svg>';
       var img = new Image();
       img.onload = function () {
@@ -257,19 +392,42 @@ window.__ModuleLoader__.load({
         else if (po.op === 'set') setRegionBlock(po.region, po.html);
         else if (po.op === 'remove') removeRegionBlock(po.region);
       }
+      // 内容长高不影响画布（画布是视口大小、按滚动量平移），不用重新 fit
     } 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) {}
       }
+      redraw();   // 平移量取决于滚动位置，滚动还原之后必须重画一次
+      count();
     } else if (d.cmd === 'ping') {
       send({ __stagePanel: true, type: 'ready' });
     }
   });
 
+  /**
+   * 滚动 = 笔迹要跟着内容走（syncScroll 定义在上面，和 redraw 放一起）。
+   *
+   * ⚠️ 必须**同步**重画，不能塞进 requestAnimationFrame：
+   * 后台标签页 / 被遮挡的 iframe 里 rAF 会被浏览器暂停，那样笔迹就定格在旧位置
+   * （实测：审计测试 C/D 两项就是被这个坑掉的）。浏览器本来就把 scroll 事件
+   * 节流到每帧一次，同步重画不会把主线程刷爆。
+   */
+  window.addEventListener('scroll', syncScroll, { passive: true });
+  /**
+   * 回到前台 / 重新获得焦点时**强制**重画一次。
+   *
+   * 为什么需要：滚动事件属于「渲染帧」的生命周期 —— 标签页被遮挡、iframe 不在视口里时
+   * 浏览器会暂停出帧，scroll 事件也就不派发，位图可能停在旧位置；
+   * 用户切回来第一眼就会看到错位的笔迹。（这也正是自动化测试在后台标签页里
+   * 会看到「滚动之后笔迹不动」的原因 —— 不是坐标算错了，是事件没来。）
+   */
+  function forceRedraw() { lastSX = -1; lastSY = -1; syncScroll(); }
+  document.addEventListener('visibilitychange', function () { if (!document.hidden) forceRedraw(); });
+  window.addEventListener('focus', forceRedraw);
+  window.addEventListener('pageshow', forceRedraw);
+
   // 把滚动位置报给父层，换板后用来还原（学生正在看的那一段不该跳回顶部）。
   var scrollTimer = null;
   window.addEventListener('scroll', function () {
@@ -280,7 +438,11 @@ window.__ModuleLoader__.load({
     }, 120);
   });
 
-  window.addEventListener('resize', fit);
+  window.addEventListener('resize', function () {
+    fit();
+    lastSX = -1; lastSY = -1;   // 尺寸/方向变了，强制重画一次
+    syncScroll();
+  });
   fit();
   count();
   send({ __stagePanel: true, type: 'ready' });

package/src/index.js

@@ -3,6 +3,11 @@
  * 定位：会话内「教学平面」——把 agent 生成的 self-contained HTML 投影为可讲解、
  * 可勾画、可截图的板书界面。
  *
+ * 两层都在这个包里：
+ *   能力层 = 本文件注册的 stage_* 工具 + client 半的「面板」视图；
+ *   行为层 = src/skills.js 把包内 skills/stage-panel/ 注册成 bundled skill。
+ * 挂上插件就同时拿到两者——不再依赖任何 preset 单独装一份使用手册。
+ *
  * 原生设计（单一数据流）：只注册模型工具，无私有状态、无 RPC、无 wait。
  * 「面板」状态 = 会话中最近一次 stage_* 工具调用的参数（client 从会话快照消费）；
  * 用户点选/回传 = 真实用户消息（DSH 原生输入流）。
@@ -13,11 +18,17 @@
  * 消息进入会话，模型在下一轮就能看见。这与 stage_choice 的机制完全一致。
  */
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createSkillProvider } from './skills.js'
 
 export const name = 'teaching-board'
 export const inject = ['tools']
 
 export function apply(ctx) {
+  // 行为层：把自带的使用手册发布进技能目录。这里用可选读取而不是 inject——
+  // 技能注册是增益，不该让白板因为缺 skills 服务而整个不挂载。
+  const skills = ctx.get('skills')
+  if (skills !== undefined) skills.registerProvider(createSkillProvider)
+
   const textRender = (_args, value) => [{ type: 'text', text: value }]
 
   ctx.tools.register(defineTool({

package/src/skills.js

@@ -0,0 +1,88 @@
+/** 教学平面的「行为层」：把本包自带的使用手册注册成一个 bundled skill。
+ *
+ * 为什么由插件自己注册：纪律要跟着能力走。任何挂载本插件的会话（不论用哪个 preset）
+ * 都应该在技能目录里看到 stage-panel。手册若只放在某个 preset 的 skills/ 里，
+ * 其余会话就会停在「有工具、没纪律」的状态——白板能开，但不知道该怎么用。
+ *
+ * 与官方 @deepseek-ai/dsh-skill-badge 同一模式：list() 只给候选，get() 才读正文；
+ * resourceBase 指向本包目录，正文里的相对路径（references/…、submode/…）才能解析。
+ * provider 由 skills 服务托管，随插件 fiber 一起注销，不需要手动 cleanup。
+ */
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+const SKILL_NAME = 'stage-panel'
+const PROVIDER_NAME = 'teaching-board'
+const SKILL_DIR = new URL('../skills/stage-panel/', import.meta.url)
+const SKILL_BODY_URL = new URL('SKILL.md', SKILL_DIR)
+const RESOURCE_BASE = { kind: 'directory', path: fileURLToPath(SKILL_DIR) }
+const INVOCATION = { modelInvocable: true, userInvocable: true }
+/** `@deepseek-ai/dsh-skill` 导出的 BUNDLED_SKILL_RANK，随包发布技能的档次。
+ *  这里写字面量而不 import：本插件只依赖 dsh-tools，不为了一个排序常量多一条依赖边。
+ *  rank 只用于同一层内的重名排序（project > runtime > user），跨层由层远近决定。 */
+const BUNDLED_SKILL_RANK = 600
+/** frontmatter 缺 description 时的兜底；正常情况下以 SKILL.md 为准（单一真相）。 */
+const FALLBACK_DESCRIPTION = 'DSH 教学平面（板书面板）使用手册。'
+
+/** 拆掉正文首部的 YAML frontmatter：它服务于「被文件系统扫描」那种用法，
+ *  由 provider 读取时属于元数据而非正文。只解析需要的一层 key: value。 */
+function splitFrontmatter(raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
+  if (match === null) return { meta: {}, content: raw }
+  const meta = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const entry = /^([A-Za-z][\w-]*)\s*:\s*(.*)$/.exec(line.trim())
+    if (entry !== null) meta[entry[1]] = entry[2].trim()
+  }
+  return { meta, content: raw.slice(match[0].length).replace(/^\n+/, '') }
+}
+
+/** 构造 stage-panel 的 bundled 技能 provider（交给 ctx.skills.registerProvider）。 */
+export function createSkillProvider() {
+  let loaded
+  const load = () => {
+    if (loaded === undefined) {
+      loaded = readFile(SKILL_BODY_URL, 'utf8').then((raw) => {
+        const { meta, content } = splitFrontmatter(raw)
+        return { description: meta.description ?? FALLBACK_DESCRIPTION, content }
+      })
+    }
+    return loaded
+  }
+
+  return {
+    name: PROVIDER_NAME,
+    async list() {
+      let description = FALLBACK_DESCRIPTION
+      try {
+        description = (await load()).description
+      } catch {
+        // 手册文件缺失时仍让目录条目可用，正文读取会在 get() 处明确报错。
+      }
+      return [{
+        name: SKILL_NAME,
+        description,
+        invocation: INVOCATION,
+        provider: PROVIDER_NAME,
+        source: 'bundled',
+        resourceBase: RESOURCE_BASE,
+        rank: BUNDLED_SKILL_RANK,
+        locator: SKILL_BODY_URL,
+        path: fileURLToPath(SKILL_BODY_URL),
+      }]
+    },
+    async get() {
+      const { description, content } = await load()
+      return {
+        name: SKILL_NAME,
+        description,
+        invocation: INVOCATION,
+        provider: PROVIDER_NAME,
+        source: 'bundled',
+        resourceBase: RESOURCE_BASE,
+        content,
+        path: fileURLToPath(SKILL_BODY_URL),
+      }
+    },
+  }
+}