cotutor 0.2.0 → 0.4.0

package/dist/app/ws/ws.js

@@ -0,0 +1,169 @@
+/**
+ * 最小的 WebSocket 服务端(RFC 6455),零依赖:孩子端 ↔ 本服务那条线用它(口语课、实时老师),测试里也拿它假扮百炼。
+ * 只做用得上的:握手、文本 / 二进制帧、分片拼接、ping/pong、close;不做扩展(permessage-deflate 不协商就不会来)。
+ * 客户端发来的帧必须带掩码(浏览器、Node 都带);服务端发出去的不带。
+ */
+import { createHash } from 'node:crypto';
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+/** 一帧最多收这么大(一块音频 100 毫秒 3200 字节;JSON 控制消息更小) */
+const MAX_FRAME = 4 * 1024 * 1024;
+/** 是不是 WebSocket 升级请求 */
+export function isUpgrade(req) {
+    return (req.headers.upgrade ?? '').toLowerCase() === 'websocket' && typeof req.headers['sec-websocket-key'] === 'string';
+}
+export function acceptKey(key) {
+    return createHash('sha1').update(key + GUID).digest('base64');
+}
+/** 把一帧编出来(服务端不打掩码) */
+export function encodeFrame(opcode, payload) {
+    const len = payload.length;
+    let head;
+    if (len < 126) {
+        head = Buffer.alloc(2);
+        head[1] = len;
+    }
+    else if (len < 65536) {
+        head = Buffer.alloc(4);
+        head[1] = 126;
+        head.writeUInt16BE(len, 2);
+    }
+    else {
+        head = Buffer.alloc(10);
+        head[1] = 127;
+        head.writeBigUInt64BE(BigInt(len), 2);
+    }
+    head[0] = 0x80 | opcode;
+    return Buffer.concat([head, payload]);
+}
+/** 从缓冲区头上解一帧;不够一帧回 null;坏帧抛 */
+export function decodeFrame(buf) {
+    if (buf.length < 2)
+        return null;
+    const fin = (buf[0] & 0x80) !== 0;
+    const opcode = buf[0] & 0x0f;
+    const masked = (buf[1] & 0x80) !== 0;
+    let len = buf[1] & 0x7f;
+    let p = 2;
+    if (len === 126) {
+        if (buf.length < 4)
+            return null;
+        len = buf.readUInt16BE(2);
+        p = 4;
+    }
+    else if (len === 127) {
+        if (buf.length < 10)
+            return null;
+        const big = buf.readBigUInt64BE(2);
+        if (big > BigInt(MAX_FRAME))
+            throw new Error('frame too large');
+        len = Number(big);
+        p = 10;
+    }
+    if (len > MAX_FRAME)
+        throw new Error('frame too large');
+    if (!masked)
+        throw new Error('client frame without mask');
+    if (buf.length < p + 4 + len)
+        return null;
+    const mask = buf.subarray(p, p + 4);
+    p += 4;
+    const payload = Buffer.allocUnsafe(len);
+    for (let i = 0; i < len; i++)
+        payload[i] = buf[p + i] ^ mask[i & 3];
+    return { fin, opcode, payload, size: p + len };
+}
+/**
+ * 接受一条升级请求:写握手响应,之后 socket 归这里管。
+ * 回的对象发消息;事件在 ev 里。只在 isUpgrade(req) 为真时调。
+ */
+export function acceptWebSocket(req, socket, head, ev) {
+    const key = String(req.headers['sec-websocket-key']);
+    socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${acceptKey(key)}\r\n\r\n`);
+    let buf = head.length ? Buffer.from(head) : Buffer.alloc(0);
+    let open = true;
+    let partial = null;
+    const closeWith = (code, reason) => {
+        if (!open)
+            return;
+        open = false;
+        try {
+            socket.end();
+        }
+        catch { /* 已经断了 */ }
+        ev.onClose?.(code, reason);
+    };
+    const raw = (opcode, payload) => {
+        if (!open || socket.destroyed)
+            return false;
+        socket.write(encodeFrame(opcode, payload));
+        return true;
+    };
+    const deliver = (opcode, payload) => {
+        if (opcode === 0x1)
+            ev.onText?.(payload.toString('utf8'));
+        else if (opcode === 0x2)
+            ev.onBinary?.(payload);
+    };
+    socket.on('data', (chunk) => {
+        buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+        try {
+            for (;;) {
+                const f = decodeFrame(buf);
+                if (!f)
+                    break;
+                buf = buf.subarray(f.size);
+                if (f.opcode === 0x8) {
+                    const code = f.payload.length >= 2 ? f.payload.readUInt16BE(0) : 1005;
+                    raw(0x8, f.payload.subarray(0, 2));
+                    closeWith(code, f.payload.length > 2 ? f.payload.subarray(2).toString('utf8') : '');
+                    return;
+                }
+                if (f.opcode === 0x9) {
+                    raw(0xa, f.payload);
+                    continue;
+                }
+                if (f.opcode === 0xa)
+                    continue;
+                if (f.opcode === 0x0) {
+                    if (!partial)
+                        throw new Error('continuation without start');
+                    partial.chunks.push(f.payload);
+                    if (f.fin) {
+                        const whole = Buffer.concat(partial.chunks);
+                        const op = partial.opcode;
+                        partial = null;
+                        deliver(op, whole);
+                    }
+                    continue;
+                }
+                if (!f.fin) {
+                    partial = { opcode: f.opcode, chunks: [f.payload] };
+                    continue;
+                }
+                deliver(f.opcode, f.payload);
+            }
+        }
+        catch (err) {
+            raw(0x8, Buffer.from([0x03, 0xea]));
+            closeWith(1002, err instanceof Error ? err.message : 'protocol error');
+        }
+    });
+    socket.on('error', () => closeWith(1006, 'socket error'));
+    socket.on('close', () => closeWith(1006, 'socket closed'));
+    socket.on('end', () => closeWith(1006, 'socket ended'));
+    return {
+        get open() { return open; },
+        sendText: (text) => raw(0x1, Buffer.from(text, 'utf8')),
+        sendBinary: (data) => raw(0x2, Buffer.isBuffer(data) ? data : Buffer.from(data.buffer, data.byteOffset, data.byteLength)),
+        close: (code = 1000, reason = '') => {
+            if (!open)
+                return;
+            const r = Buffer.from(reason, 'utf8');
+            const p = Buffer.alloc(2 + r.length);
+            p.writeUInt16BE(code, 0);
+            r.copy(p, 2);
+            raw(0x8, p);
+            closeWith(code, reason);
+        },
+    };
+}

package/dist/board/canvas-chat.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 画板:孩子的笔迹怎么数(各色几笔、大致在哪、画了多久),边画边聊时嘴什么时候主动说一句、说哪个颜色。纯函数。
+ * 剥类型内联进孩子端页面(同 runtime/delivery/player.ts),名字都带 canvas 前缀;服务端的画板卡 describe、纸交画时的摘要也用它。
+ * 改「什么时候说」先改的规矩,再改 tests/canvas-chat.test.ts,最后改这里(CANVAS_CHAT 是调参表)。
+ */
+/** 舞台的三支笔(src/ui/stage/canvas.tsx 的 INK_COLORS)叫什么;别的颜色(以后加的)叫「别的颜色」 */
+export declare const CANVAS_COLOR_NAMES: Readonly<Record<string, string>>;
+/** 一笔:颜色名、画完的时刻(excalidraw 元素的 updated,毫秒)、外框(画布坐标) */
+export interface CanvasStroke {
+    color: string;
+    at: number;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** 一种颜色:几笔、在整张画里大致哪儿(上边偏右、中间、铺满大半张) */
+export interface CanvasColor {
+    name: string;
+    strokes: number;
+    where: string;
+}
+export interface CanvasSummary {
+    strokes: number;
+    /** 笔多的在前 */
+    colors: CanvasColor[];
+    /** 第一笔、最后一笔画完的时刻;没画是 null */
+    firstAt: number | null;
+    lastAt: number | null;
+}
+/** 笔迹(舞台存回来的 excalidraw 元素,customData.layer = 'ink')→ 一笔一行;删掉的、不是线条的不算 */
+export declare function canvasStrokes(ink: readonly Record<string, unknown>[]): CanvasStroke[];
+/** 整张画的摘要:几笔、各颜色几笔在哪、第一笔与最后一笔的时刻 */
+export declare function canvasSummary(strokes: readonly CanvasStroke[]): CanvasSummary;
+/** 「红 40 笔、蓝 51 笔」;只有一种颜色就只写几笔 */
+export declare function canvasColorsText(s: CanvasSummary): string;
+/** 画了多久(第一笔到最后一笔,加上清空前画的那几版):不到 1 分钟写「不到 1 分钟」 */
+export declare function canvasMinutesText(ms: number): string;
+/**
+ * 边画边聊的规矩(10-22 :先这样,跑一周再调)。毫秒。
+ * 换色:一种颜色从上一句到现在新画了 ≥ colorStrokes 笔、孩子换了颜色 → 说刚画完的那种;
+ * 久停:这一张 ≥ pauseStrokes 笔以后停笔 ≥ pauseMs → 说整张(上一句之后又画过才算);
+ * 不说:点开后 openQuietMs 内、上一笔不到 drawingMs(正在画)、清空后 clearQuietMs 内、孩子按头像说过 kidQuietMs 内、离上一句不到 gapMs、一张已经说了 maxLines 句;
+ * 不追:上一句问了没回 → 这句只说不问;连着 stopUnanswered 句没回 → 这一张不说了(他画得入神)
+ */
+export declare const CANVAS_CHAT: {
+    colorStrokes: number;
+    pauseStrokes: number;
+    pauseMs: number;
+    openQuietMs: number;
+    drawingMs: number;
+    clearQuietMs: number;
+    kidQuietMs: number;
+    gapMs: number;
+    maxLines: number;
+    stopUnanswered: number;
+};
+/** 嘴主动说过的一句:时刻、说的哪种颜色(null = 整张)、问没问、孩子回了没有、那时各颜色几笔 */
+export interface CanvasChatLine {
+    at: number;
+    color: string | null;
+    ask: boolean;
+    answered: boolean;
+    counts: Record<string, number>;
+    strokes: number;
+}
+/** 这一张纸(清空算新的一张)上边画边聊到哪了;kidAt = 孩子最近一次按头像说话 */
+export interface CanvasChatState {
+    openedAt: number;
+    clearedAt: number | null;
+    kidAt: number | null;
+    lines: CanvasChatLine[];
+}
+/** 要不要说:say = false 带为什么(测试、录像看);说的话带说哪种颜色(null = 整张)、问不问 */
+export type CanvasChatDue = {
+    say: false;
+    why: string;
+} | {
+    say: true;
+    color: string | null;
+    ask: boolean;
+    why: 'color' | 'pause';
+};
+export declare function canvasChatInit(now: number): CanvasChatState;
+/** 清空了:新的一张,计数重来 */
+export declare function canvasChatCleared(st: CanvasChatState, now: number): CanvasChatState;
+/** 孩子按着头像说了话(边画边聊):最近一句算回了;嘴刚接住他,一会儿内不再主动说 */
+export declare function canvasChatAnswered(st: CanvasChatState, now: number): CanvasChatState;
+/**
+ * 这一刻要不要说。busy = 孩子按着说话、嘴或卡在出声、脑在写(页面凑);strokes = 这一刻的笔(画完的时刻是 at)。
+ * 换色比久停先:刚画完的那种颜色具体,好问
+ */
+export declare function canvasChatDue(st: CanvasChatState, now: number, strokes: readonly CanvasStroke[], busy: boolean): CanvasChatDue;
+/** 说了:记下这一句(那时各颜色几笔,下次算「新画了几笔」) */
+export declare function canvasChatSaid(st: CanvasChatState, now: number, due: Extract<CanvasChatDue, {
+    say: true;
+}>, strokes: readonly CanvasStroke[]): CanvasChatState;

package/dist/board/canvas-chat.js

@@ -0,0 +1,175 @@
+/**
+ * 画板:孩子的笔迹怎么数(各色几笔、大致在哪、画了多久),边画边聊时嘴什么时候主动说一句、说哪个颜色。纯函数。
+ * 剥类型内联进孩子端页面(同 runtime/delivery/player.ts),名字都带 canvas 前缀;服务端的画板卡 describe、纸交画时的摘要也用它。
+ * 改「什么时候说」先改的规矩,再改 tests/canvas-chat.test.ts,最后改这里(CANVAS_CHAT 是调参表)。
+ */
+/** 舞台的三支笔(src/ui/stage/canvas.tsx 的 INK_COLORS)叫什么;别的颜色(以后加的)叫「别的颜色」 */
+export const CANVAS_COLOR_NAMES = { '#2b2b2b': '黑', '#d9482b': '红', '#2f6fd6': '蓝' };
+const canvasNum = (v, d = 0) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+/** 笔迹(舞台存回来的 excalidraw 元素,customData.layer = 'ink')→ 一笔一行;删掉的、不是线条的不算 */
+export function canvasStrokes(ink) {
+    const out = [];
+    for (const el of ink) {
+        if (!el || el.isDeleted === true)
+            continue;
+        const x = canvasNum(el.x), y = canvasNum(el.y);
+        const pts = Array.isArray(el.points) ? el.points.filter((p) => Array.isArray(p) && p.length >= 2 && typeof p[0] === 'number' && typeof p[1] === 'number') : [];
+        let x0 = x, y0 = y, x1 = x + canvasNum(el.width), y1 = y + canvasNum(el.height);
+        if (pts.length) {
+            x0 = Infinity;
+            y0 = Infinity;
+            x1 = -Infinity;
+            y1 = -Infinity;
+            for (const p of pts) {
+                x0 = Math.min(x0, x + p[0]);
+                y0 = Math.min(y0, y + p[1]);
+                x1 = Math.max(x1, x + p[0]);
+                y1 = Math.max(y1, y + p[1]);
+            }
+        }
+        const raw = typeof el.strokeColor === 'string' ? el.strokeColor.toLowerCase() : '';
+        out.push({ color: CANVAS_COLOR_NAMES[raw] ?? '别的颜色', at: canvasNum(el.updated), x0, y0, x1, y1 });
+    }
+    return out;
+}
+/** 一块外框在整张画的外框里大致哪儿:占了一半以上 = 铺满大半张;不然按中心落在九宫格哪格 */
+function canvasWhere(b, all) {
+    const W = Math.max(1, all.x1 - all.x0), H = Math.max(1, all.y1 - all.y0);
+    const area = (Math.max(0, b.x1 - b.x0) * Math.max(0, b.y1 - b.y0)) / (W * H);
+    if (area >= 0.5)
+        return '铺满大半张';
+    const cx = ((b.x0 + b.x1) / 2 - all.x0) / W, cy = ((b.y0 + b.y1) / 2 - all.y0) / H;
+    const v = cy < 1 / 3 ? '上边' : cy > 2 / 3 ? '下边' : '中间';
+    const hz = cx < 1 / 3 ? '偏左' : cx > 2 / 3 ? '偏右' : '';
+    return v === '中间' && hz ? (hz === '偏左' ? '左边' : '右边') : v + hz;
+}
+/** 整张画的摘要:几笔、各颜色几笔在哪、第一笔与最后一笔的时刻 */
+export function canvasSummary(strokes) {
+    if (!strokes.length)
+        return { strokes: 0, colors: [], firstAt: null, lastAt: null };
+    const all = { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity };
+    const by = new Map();
+    let firstAt = Infinity, lastAt = -Infinity;
+    strokes.forEach((s, i) => {
+        all.x0 = Math.min(all.x0, s.x0);
+        all.y0 = Math.min(all.y0, s.y0);
+        all.x1 = Math.max(all.x1, s.x1);
+        all.y1 = Math.max(all.y1, s.y1);
+        if (s.at > 0) {
+            firstAt = Math.min(firstAt, s.at);
+            lastAt = Math.max(lastAt, s.at);
+        }
+        const c = by.get(s.color) ?? { n: 0, first: i, b: { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity } };
+        c.n++;
+        c.b = { x0: Math.min(c.b.x0, s.x0), y0: Math.min(c.b.y0, s.y0), x1: Math.max(c.b.x1, s.x1), y1: Math.max(c.b.y1, s.y1) };
+        by.set(s.color, c);
+    });
+    const colors = [...by.entries()].sort((a, b) => b[1].n - a[1].n || a[1].first - b[1].first).map(([name, c]) => ({ name, strokes: c.n, where: canvasWhere(c.b, all) }));
+    return { strokes: strokes.length, colors, firstAt: Number.isFinite(firstAt) ? firstAt : null, lastAt: Number.isFinite(lastAt) ? lastAt : null };
+}
+/** 「红 40 笔、蓝 51 笔」;只有一种颜色就只写几笔 */
+export function canvasColorsText(s) {
+    if (!s.strokes)
+        return '还没画';
+    if (s.colors.length <= 1)
+        return `${s.strokes} 笔${s.colors[0] ? `(${s.colors[0].name})` : ''}`;
+    return s.colors.map((c) => `${c.name} ${c.strokes} 笔`).join('、');
+}
+/** 画了多久(第一笔到最后一笔,加上清空前画的那几版):不到 1 分钟写「不到 1 分钟」 */
+export function canvasMinutesText(ms) {
+    if (!(ms >= 60_000))
+        return '不到 1 分钟';
+    return `约 ${Math.round(ms / 60_000)} 分钟`;
+}
+/**
+ * 边画边聊的规矩(10-22 :先这样,跑一周再调)。毫秒。
+ * 换色:一种颜色从上一句到现在新画了 ≥ colorStrokes 笔、孩子换了颜色 → 说刚画完的那种;
+ * 久停:这一张 ≥ pauseStrokes 笔以后停笔 ≥ pauseMs → 说整张(上一句之后又画过才算);
+ * 不说:点开后 openQuietMs 内、上一笔不到 drawingMs(正在画)、清空后 clearQuietMs 内、孩子按头像说过 kidQuietMs 内、离上一句不到 gapMs、一张已经说了 maxLines 句;
+ * 不追:上一句问了没回 → 这句只说不问;连着 stopUnanswered 句没回 → 这一张不说了(他画得入神)
+ */
+export const CANVAS_CHAT = {
+    colorStrokes: 5,
+    pauseStrokes: 10,
+    pauseMs: 12_000,
+    openQuietMs: 20_000,
+    drawingMs: 2_000,
+    clearQuietMs: 30_000,
+    kidQuietMs: 15_000,
+    gapMs: 45_000,
+    maxLines: 4,
+    stopUnanswered: 2,
+};
+export function canvasChatInit(now) {
+    return { openedAt: now, clearedAt: null, kidAt: null, lines: [] };
+}
+/** 清空了:新的一张,计数重来 */
+export function canvasChatCleared(st, now) {
+    return { ...st, clearedAt: now, lines: [] };
+}
+/** 孩子按着头像说了话(边画边聊):最近一句算回了;嘴刚接住他,一会儿内不再主动说 */
+export function canvasChatAnswered(st, now) {
+    const lines = st.lines.slice();
+    if (lines.length)
+        lines[lines.length - 1] = { ...lines[lines.length - 1], answered: true };
+    return { ...st, kidAt: now, lines };
+}
+const canvasCounts = (strokes) => {
+    const c = {};
+    for (const s of strokes)
+        c[s.color] = (c[s.color] ?? 0) + 1;
+    return c;
+};
+/**
+ * 这一刻要不要说。busy = 孩子按着说话、嘴或卡在出声、脑在写(页面凑);strokes = 这一刻的笔(画完的时刻是 at)。
+ * 换色比久停先:刚画完的那种颜色具体,好问
+ */
+export function canvasChatDue(st, now, strokes, busy) {
+    const T = CANVAS_CHAT;
+    if (busy)
+        return { say: false, why: 'busy' };
+    if (now - st.openedAt < T.openQuietMs)
+        return { say: false, why: 'opened' };
+    if (st.clearedAt !== null && now - st.clearedAt < T.clearQuietMs)
+        return { say: false, why: 'cleared' };
+    if (st.kidAt !== null && now - st.kidAt < T.kidQuietMs)
+        return { say: false, why: 'kid' };
+    if (!strokes.length)
+        return { say: false, why: 'empty' };
+    const lines = st.lines;
+    if (lines.length >= T.maxLines)
+        return { say: false, why: 'max' };
+    const tail = lines.slice(-T.stopUnanswered);
+    if (tail.length === T.stopUnanswered && tail.every((l) => !l.answered))
+        return { say: false, why: 'unanswered' };
+    const last = lines[lines.length - 1];
+    if (last && now - last.at < T.gapMs)
+        return { say: false, why: 'gap' };
+    const lastAt = strokes.reduce((m, s) => Math.max(m, s.at), 0);
+    if (now - lastAt < T.drawingMs)
+        return { say: false, why: 'drawing' };
+    const ask = !(last && last.ask && !last.answered);
+    // 换色:按画完的先后排,最后一段同色之前那段的颜色;它从上一句到现在新画了够多
+    const seq = strokes.slice().sort((a, b) => a.at - b.at);
+    const now0 = seq[seq.length - 1].color;
+    let k = seq.length - 1;
+    while (k >= 0 && seq[k].color === now0)
+        k--;
+    const counts = canvasCounts(strokes);
+    if (k >= 0) {
+        const prev = seq[k].color;
+        const fresh = (counts[prev] ?? 0) - (last?.counts[prev] ?? 0);
+        if (fresh >= T.colorStrokes)
+            return { say: true, color: prev, ask, why: 'color' };
+    }
+    // 还没换色、这一种已经画了很多(一整张都是一种颜色):停笔够久也说它
+    if (strokes.length >= T.pauseStrokes && now - lastAt >= T.pauseMs && (!last || lastAt > last.at)) {
+        const only = Object.keys(counts).length === 1 ? now0 : null;
+        return { say: true, color: only, ask, why: 'pause' };
+    }
+    return { say: false, why: 'wait' };
+}
+/** 说了:记下这一句(那时各颜色几笔,下次算「新画了几笔」) */
+export function canvasChatSaid(st, now, due, strokes) {
+    return { ...st, lines: [...st.lines, { at: now, color: due.color, ask: due.ask, answered: false, counts: canvasCounts(strokes), strokes: strokes.length }] };
+}

package/dist/board/card-guards.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 按卡裁的段落(《卡片协议.md》「谁拿到哪些卡」):板书写法的手写部分(cards/板书怎么写.md)与守则(cotutor-tutor)里,
+ * 只对某几种卡有用的段落用 `{{有 x y}}` … `{{/有}}` 包起来,递给某位老师时按他的卡留或去。纯函数,不读文件。
+ * activity 文件的「老师怎么带」也用它,名字还可以是参数(填了才留,src/runtime/activity.ts)。
+ */
+/** 守卫行;名字是卡的种类(英文小写),或 activity 的参数名(汉字,src/runtime/activity.ts) */
+export declare const GUARD_OPEN: RegExp;
+export declare const GUARD_CLOSE: RegExp;
+/**
+ * 按卡裁的段落:`{{有 x y}}` 到 `{{/有}}` 之间的行,x、y 都在 kinds 里才留;守卫行本身不留,能套。
+ * 删掉一段留下的连续空行并成一行。守卫不配对就抛(gen:skills 与测试先红)。
+ */
+export declare function applyCardGuards(text: string, kinds: readonly string[]): string;
+/** 同上,「有没有」由 has 定:activity 递给老师时,名字是参数就看填没填,是卡就看这个话题有没有 */
+export declare function applyGuards(text: string, has: (name: string) => boolean): string;

package/dist/board/card-guards.js

@@ -0,0 +1,38 @@
+/**
+ * 按卡裁的段落(《卡片协议.md》「谁拿到哪些卡」):板书写法的手写部分(cards/板书怎么写.md)与守则(cotutor-tutor)里,
+ * 只对某几种卡有用的段落用 `{{有 x y}}` … `{{/有}}` 包起来,递给某位老师时按他的卡留或去。纯函数,不读文件。
+ * activity 文件的「老师怎么带」也用它,名字还可以是参数(填了才留,src/runtime/activity.ts)。
+ */
+/** 守卫行;名字是卡的种类(英文小写),或 activity 的参数名(汉字,src/runtime/activity.ts) */
+export const GUARD_OPEN = /^\{\{有((?:\s+[^\s{}]+)+)\}\}\s*$/;
+export const GUARD_CLOSE = /^\{\{\/有\}\}\s*$/;
+/**
+ * 按卡裁的段落:`{{有 x y}}` 到 `{{/有}}` 之间的行,x、y 都在 kinds 里才留;守卫行本身不留,能套。
+ * 删掉一段留下的连续空行并成一行。守卫不配对就抛(gen:skills 与测试先红)。
+ */
+export function applyCardGuards(text, kinds) {
+    return applyGuards(text, (name) => kinds.includes(name));
+}
+/** 同上,「有没有」由 has 定:activity 递给老师时,名字是参数就看填没填,是卡就看这个话题有没有 */
+export function applyGuards(text, has) {
+    const keep = [];
+    const out = [];
+    for (const line of text.split('\n')) {
+        const open = GUARD_OPEN.exec(line);
+        if (open) {
+            keep.push(open[1].trim().split(/\s+/).every(has));
+            continue;
+        }
+        if (GUARD_CLOSE.test(line)) {
+            if (!keep.length)
+                throw new Error('{{/有}} 多了一个');
+            keep.pop();
+            continue;
+        }
+        if (keep.every(Boolean))
+            out.push(line);
+    }
+    if (keep.length)
+        throw new Error('{{有 …}} 没有配对的 {{/有}}');
+    return out.join('\n').replace(/\n{3,}/g, '\n\n');
+}

package/dist/board/cards/canvas.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 画板卡:孩子在上面画。底图四种——课包 id(整幅终帧做底层)、行内小骨架 JSON、一张图(孩子拍的作业
+ * captures/… 或别的 workspace 里的图片,R5:在自己的作业照片上圈错题、写答案)、空白 + 题目;
+ * 舞台是舞台包里的 excalidraw 编辑器(底层锁定,孩子的笔打 customData.layer = 'ink');「给老师看」→ 导出 png 存 .cards/<n>.png,
+ * 状态存 ink 元素;清空前那一版存一张图(cleared);describe 给笔数、各颜色几笔、画了多久、清空过几次与图的路径,
+ * 老师 Read 看图(进上下文包时 runner 换成绝对路径、这轮带只读工具;看不了图就靠笔数)。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const CanvasPropsSchema: z.ZodObject<{
+    base: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        bundle: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        skeletons: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        image: z.ZodString;
+    }, z.core.$strip>]>>;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CanvasProps = z.infer<typeof CanvasPropsSchema>;
+/** 清空过的一版(页面记):清空的时刻、那一版第一笔画完的时刻、几笔、清空前导出的那张图(captures/…,先 POST photos 拿到的路径) */
+export declare const CanvasClearedSchema: z.ZodObject<{
+    at: z.ZodNumber;
+    from: z.ZodOptional<z.ZodNumber>;
+    strokes: z.ZodNumber;
+    image: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const CanvasStateSchema: z.ZodObject<{
+    ink: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    image: z.ZodOptional<z.ZodString>;
+    cleared: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        from: z.ZodOptional<z.ZodNumber>;
+        strokes: z.ZodNumber;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CanvasState = z.infer<typeof CanvasStateSchema>;
+/** 「画了 103 笔(黑 12、红 40、蓝 51),画了约 7 分钟,清空重画过 4 次,清掉的那几版:…(用 Read 看)」;图另写 */
+export declare function canvasInkText(s: Pick<CanvasState, 'ink' | 'cleared'>): string;
+export declare const canvas: CardKind<CanvasProps, CanvasState>;

package/dist/board/cards/canvas.js

@@ -0,0 +1,83 @@
+/**
+ * 画板卡:孩子在上面画。底图四种——课包 id(整幅终帧做底层)、行内小骨架 JSON、一张图(孩子拍的作业
+ * captures/… 或别的 workspace 里的图片,R5:在自己的作业照片上圈错题、写答案)、空白 + 题目;
+ * 舞台是舞台包里的 excalidraw 编辑器(底层锁定,孩子的笔打 customData.layer = 'ink');「给老师看」→ 导出 png 存 .cards/<n>.png,
+ * 状态存 ink 元素;清空前那一版存一张图(cleared);describe 给笔数、各颜色几笔、画了多久、清空过几次与图的路径,
+ * 老师 Read 看图(进上下文包时 runner 换成绝对路径、这轮带只读工具;看不了图就靠笔数)。
+ */
+import { z } from 'zod';
+import { BUNDLE_ID_RE, bodyLines } from "./kind.js";
+import { IMAGE_EXT } from "./image.js";
+import { canvasMinutesText, canvasStrokes, canvasSummary } from "../canvas-chat.js";
+export const CanvasPropsSchema = z.object({
+    /** 底图:课包 id / 行内骨架 / 一张图(相对 workspace 根,如 captures/2026-09-14/1620-1.jpg)/ 没有(空白) */
+    base: z.union([z.object({ bundle: z.string().regex(BUNDLE_ID_RE) }), z.object({ skeletons: z.array(z.record(z.string(), z.unknown())).min(1).max(40) }), z.object({ image: z.string().min(1) })]).nullable(),
+    /** 题目(空白画板必须有;有底图时可选,画在顶栏) */
+    prompt: z.string().optional(),
+});
+/** 清空过的一版(页面记):清空的时刻、那一版第一笔画完的时刻、几笔、清空前导出的那张图(captures/…,先 POST photos 拿到的路径) */
+export const CanvasClearedSchema = z.object({ at: z.number(), from: z.number().optional(), strokes: z.number().int().nonnegative(), image: z.string().optional() });
+export const CanvasStateSchema = z.object({
+    /** 孩子画的 excalidraw 元素(customData.layer = 'ink') */
+    ink: z.array(z.record(z.string(), z.unknown())).max(2000),
+    /** 「给老师看」时导出的 png(相对 workspace 根,如 conversations/math-tutor/2026-09-10.1620-1.cards/2.png);服务端写,页面不填 */
+    image: z.string().optional(),
+    /** 清空过的几版(清空前自动存一张图,脑和家长都看得到) */
+    cleared: z.array(CanvasClearedSchema).max(50).optional(),
+});
+/** 「画了 103 笔(黑 12、红 40、蓝 51),画了约 7 分钟,清空重画过 4 次,清掉的那几版:…(用 Read 看)」;图另写 */
+export function canvasInkText(s) {
+    const sum = canvasSummary(canvasStrokes(s.ink));
+    const cleared = s.cleared ?? [];
+    if (!sum.strokes && !cleared.length)
+        return '还没画';
+    const named = sum.colors.filter((c) => c.name !== '别的颜色');
+    const parts = [`画了 ${sum.strokes} 笔${named.length ? `(${named.map((c) => `${c.name} ${c.strokes}`).join('、')})` : ''}`];
+    const starts = [...cleared.map((c) => c.from ?? c.at), ...(sum.firstAt !== null ? [sum.firstAt] : [])].filter((x) => x > 0);
+    const end = sum.lastAt ?? (cleared.length ? cleared[cleared.length - 1].at : null);
+    if (starts.length && end !== null)
+        parts.push(`画了${canvasMinutesText(end - Math.min(...starts))}`);
+    if (cleared.length) {
+        const imgs = cleared.flatMap((c) => (c.image ? [c.image] : []));
+        parts.push(`清空重画过 ${cleared.length} 次${imgs.length ? `,清掉的那几版:${imgs.join('、')}(用 Read 看)` : ''}`);
+    }
+    return parts.join(',');
+}
+export const canvas = {
+    name: 'canvas',
+    props: CanvasPropsSchema,
+    parse(body, mods) {
+        const lines = bodyLines(body);
+        const first = lines[0] ?? '';
+        const rest = lines.slice(1).join(' ').trim();
+        const promptFromTag = mods.join(' ').trim();
+        if (first.startsWith('{')) {
+            let obj;
+            try {
+                obj = JSON.parse(lines.join('\n'));
+            }
+            catch (err) {
+                throw new Error(`行内骨架不是合法 JSON:${err instanceof Error ? err.message : String(err)}`);
+            }
+            const sk = obj.skeletons;
+            if (!Array.isArray(sk) || !sk.length)
+                throw new Error('行内骨架要有 skeletons 数组');
+            return { base: { skeletons: sk }, ...(promptFromTag ? { prompt: promptFromTag } : {}) };
+        }
+        if (first && IMAGE_EXT.test(first) && !/^https?:\/\//.test(first))
+            return { base: { image: first }, ...(rest || promptFromTag ? { prompt: rest || promptFromTag } : {}) };
+        if (first && BUNDLE_ID_RE.test(first) && !/[一-鿿]/.test(first))
+            return { base: { bundle: first }, ...(rest || promptFromTag ? { prompt: rest || promptFromTag } : {}) };
+        const prompt = [promptFromTag, ...lines].filter(Boolean).join(' ').trim();
+        if (!prompt)
+            throw new Error('空白画板要有题目(写在正文或标签后面)');
+        return { base: null, prompt };
+    },
+    state: CanvasStateSchema,
+    describe(_p, s) {
+        const ink = canvasInkText(s);
+        if (ink === '还没画')
+            return ink;
+        return `${ink}${s.image ? `,图:${s.image}(用 Read 看)` : ''}`;
+    },
+};

package/dist/{cards → board/cards}/choice.js

@@ -61,16 +61,4 @@ export const choice = {
         const key = p.answer?.length ? `(答案:${p.answer.map((i) => `「${optionLabel(p.options, i)}」`).join('')})` : '';
         return `选了${chosen}${key}`;
     },
-    doc: `### choice — 选择题
-
-第一行是问题,后面每行 \`- [ ] 选项\`,对的那项写 \`- [x]\`(标了多个就是多选)。答案孩子看不到,只有你知道;孩子选了、交给你,上下文包的 cards 段会写「选了「B …」(答案:「…」)」,对错由你口头说。
-
-\`\`\`\`
-\`\`\`choice
-底 6 厘米、高 4 厘米的三角形,面积是多少?
-- [ ] 24 平方厘米
-- [x] 12 平方厘米
-- [ ] 10 平方厘米
-\`\`\`
-\`\`\`\``,
 };

package/dist/{cards → board/cards}/code.js

@@ -7,7 +7,4 @@ export const code = {
     parse(body, mods) {
         return { lang: mods[0] ?? null, text: body.replace(/\s+$/, '') };
     },
-    doc: `### code — 代码或原样的文字
-
-围栏标签写语言名(\`\`\`python)就是代码卡,原样显示,不念。`,
 };