cotutor 0.2.0 → 0.4.0

package/dist/brain/stream-json.js

@@ -0,0 +1,82 @@
+const blocks = (c) => (Array.isArray(c) ? c : []);
+/** 结果块的文字:字符串原样,块数组拼各块的 text */
+export const blockText = (c) => (typeof c === 'string' ? c : blocks(c).map((b) => (typeof b.text === 'string' ? b.text : '')).join(''));
+const num = (v) => (typeof v === 'number' ? v : undefined);
+/** 输入 = 没命中的 + 缓存读 + 缓存写;一样都没报 → undefined */
+const inputOf = (u) => [u.input_tokens, u.cache_read_input_tokens, u.cache_creation_input_tokens].reduce((s, v) => (typeof v === 'number' ? (s ?? 0) + v : s), undefined);
+function finalOf(e) {
+    const failed = Boolean(e.is_error) || Boolean(e.subtype && e.subtype !== 'success');
+    const text = typeof e.result === 'string' && e.result.trim() ? e.result.trim() : null;
+    const u = e.usage;
+    const inTokens = u ? inputOf(u) : undefined;
+    return {
+        ok: !failed,
+        text,
+        reason: failed ? (e.subtype && e.subtype !== 'success' ? e.subtype : (e.terminal_reason ?? '未知')) : null,
+        numTurns: num(e.num_turns),
+        ...(num(u?.output_tokens) !== undefined ? { outTokens: num(u?.output_tokens) } : {}),
+        ...(inTokens !== undefined ? { inTokens } : {}),
+    };
+}
+export function parseStreamJson(line) {
+    if (!line.trim())
+        return [];
+    let e;
+    try {
+        e = JSON.parse(line);
+    }
+    catch {
+        return [];
+    }
+    if (!e || typeof e !== 'object')
+        return [];
+    const out = [];
+    if (typeof e.session_id === 'string' && e.session_id)
+        out.push({ kind: 'session', id: e.session_id });
+    const sub = typeof e.parent_tool_use_id === 'string' && e.parent_tool_use_id.length > 0;
+    switch (e.type) {
+        case 'system':
+            if (Array.isArray(e.tools))
+                out.push({ kind: 'init', tools: e.tools.filter((t) => typeof t === 'string') });
+            break;
+        case 'stream_event': {
+            const ev = e.event;
+            if (ev?.type === 'message_start')
+                out.push({ kind: 'start', sub });
+            else if (ev?.type === 'content_block_delta' && ev.delta?.type === 'text_delta' && typeof ev.delta.text === 'string' && ev.delta.text)
+                out.push({ kind: 'delta', text: ev.delta.text, sub });
+            else if (ev?.type === 'content_block_delta' && ev.delta?.type === 'thinking_delta')
+                out.push({ kind: 'thinking', sub });
+            break;
+        }
+        case 'assistant': {
+            if (!Array.isArray(e.message?.content))
+                break;
+            const parts = [];
+            for (const b of blocks(e.message.content)) {
+                if (b.type === 'text' && typeof b.text === 'string')
+                    parts.push({ type: 'text', text: b.text });
+                else if (b.type === 'tool_use' && b.name)
+                    parts.push({ type: 'tool', tool: { ...(b.id ? { id: b.id } : {}), name: b.name, ...(b.input ? { input: b.input } : {}) } });
+            }
+            const u = e.message.usage;
+            const id = typeof e.message.id === 'string' ? e.message.id : typeof e.uuid === 'string' ? e.uuid : null;
+            const inTok = u ? inputOf(u) : undefined;
+            out.push({ kind: 'assistant', parts, sub, ...(u && id && inTok !== undefined ? { usage: { id, in: inTok, out: num(u.output_tokens) ?? 0, cached: num(u.cache_read_input_tokens) ?? 0 } } : {}) });
+            break;
+        }
+        case 'user': {
+            const results = [];
+            for (const b of blocks(e.message?.content))
+                if (b.type === 'tool_result' && b.tool_use_id)
+                    results.push({ id: b.tool_use_id, ok: !b.is_error, text: blockText(b.content) });
+            if (results.length)
+                out.push({ kind: 'results', results, sub });
+            break;
+        }
+        case 'result':
+            out.push({ kind: 'result', final: finalOf(e) });
+            break;
+    }
+    return out;
+}

package/dist/brain/stream.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 流式:老师还在说的时候,从脑的输出事件里拼出「当前这条顶层回复的正文」,给板书的 partial 解析用。
+ * 增量来的每一小段是一条 delta,每条新回复前有 start;只有整条 assistant 的(旧轮次的一些 CLI)也认:
+ * delta 往当前文本上追加,start 时当前段带围栏或 H2 就留下(与 kid-view 的 kidSource 同一条规则:老师板书完再用工具,卡不丢)、否则丢掉,
+ * 新段从空开始;顶层 assistant 的正文直接当作当前段(与拼出来的一样)。text() = 留下的段 + 当前段。
+ * 子代理的一律跳过(旧轮次的 CLI 才有)。这里只认统一事件(./log.ts 读)。
+ */
+import { type CliEvent } from './types.ts';
+export interface PartialReader {
+    /** 喂一块 stdout(原始字节,行没收完的先攒着);返回文本有没有变 */
+    feed(chunk: string): boolean;
+    /** 喂已经读好的事件(runner 自己切行、解析一次,同一批事件还要给工具与会话用);返回文本有没有变 */
+    apply(events: readonly CliEvent[]): boolean;
+    /** 当前这条顶层回复的正文(还在长) */
+    text(): string;
+    /** 只要当前这段(还没收到整条 assistant 的那段;断流时它没进会话,要递回给老师) */
+    current(): string;
+}
+/** parse:一行输出 → 统一事件;缺省 parseLogLine(统一事件,旧轮次的 stream-json 也认) */
+export declare function createPartialReader(parse?: (line: string) => CliEvent[]): PartialReader;

package/dist/brain/stream.js

@@ -0,0 +1,70 @@
+/**
+ * 流式:老师还在说的时候,从脑的输出事件里拼出「当前这条顶层回复的正文」,给板书的 partial 解析用。
+ * 增量来的每一小段是一条 delta,每条新回复前有 start;只有整条 assistant 的(旧轮次的一些 CLI)也认:
+ * delta 往当前文本上追加,start 时当前段带围栏或 H2 就留下(与 kid-view 的 kidSource 同一条规则:老师板书完再用工具,卡不丢)、否则丢掉,
+ * 新段从空开始;顶层 assistant 的正文直接当作当前段(与拼出来的一样)。text() = 留下的段 + 当前段。
+ * 子代理的一律跳过(旧轮次的 CLI 才有)。这里只认统一事件(./log.ts 读)。
+ */
+import { parseLogLine } from "./log.js";
+import { textsOf } from "./types.js";
+const KEEP = /^\s*(?:```|~~~|## )/m;
+/** parse:一行输出 → 统一事件;缺省 parseLogLine(统一事件,旧轮次的 stream-json 也认) */
+export function createPartialReader(parse = parseLogLine) {
+    let rest = '';
+    let text = '';
+    // 当前段收到过整条 assistant 了(已进会话,不算「断在半截」)
+    let sealed = false;
+    const kept = [];
+    const one = (e) => {
+        if ('sub' in e && e.sub)
+            return false;
+        if (e.kind === 'start') {
+            if (!text)
+                return false;
+            if (KEEP.test(text))
+                kept.push(text.trim());
+            text = '';
+            sealed = false;
+            return true;
+        }
+        if (e.kind === 'delta') {
+            text += e.text;
+            sealed = false;
+            return true;
+        }
+        if (e.kind === 'assistant') {
+            const t = textsOf(e.parts).join('');
+            if (t)
+                sealed = true;
+            if (t && t !== text) {
+                text = t;
+                return true;
+            }
+        }
+        return false;
+    };
+    const apply = (events) => {
+        let changed = false;
+        for (const e of events)
+            if (one(e))
+                changed = true;
+        return changed;
+    };
+    return {
+        feed(chunk) {
+            rest += chunk;
+            let changed = false;
+            let at;
+            while ((at = rest.indexOf('\n')) >= 0) {
+                const line = rest.slice(0, at);
+                rest = rest.slice(at + 1);
+                if (apply(parse(line)))
+                    changed = true;
+            }
+            return changed;
+        },
+        apply,
+        text: () => [...kept, text].filter(Boolean).join('\n\n'),
+        current: () => (sealed ? '' : text),
+    };
+}

package/dist/brain/transcript.d.ts

@@ -0,0 +1,45 @@
+import type { CliEvent, CliFinal } from './types.ts';
+/** 一行输出 → 统一事件(./log.ts) */
+export type LineParser = (line: string) => CliEvent[];
+export interface TranscriptItem {
+    /** text 说话 / tool 用工具 / tool-error 工具报错 / done 收尾 */
+    kind: 'text' | 'tool' | 'tool-error' | 'done';
+    text: string;
+    /** 来自子代理(parent_tool_use_id 非空) */
+    sub?: boolean;
+}
+export type TranscriptRow = TranscriptItem | {
+    kind: 'fold';
+    tools: TranscriptItem[];
+};
+/** 收尾:result 的最终正文、成没成、费用或 token(见 ./types.ts 的 CliFinal) */
+export type TranscriptFinal = CliFinal;
+export interface Transcript {
+    sessionId: string | null;
+    items: TranscriptItem[];
+    /** 收尾;还在跑就是 null */
+    final: TranscriptFinal | null;
+}
+/**
+ * 展示前折叠:连续 ≥3 条工具行收成一组;报错行永不折;末尾还在长的段留最后 2 条直播。
+ */
+export declare function foldRuns(items: TranscriptItem[]): TranscriptRow[];
+export declare function toolSummary(name: string, input: Record<string, unknown> | undefined): string;
+/**
+ * 一轮里模型用了哪些工具、读了什么(2026-09-15,记录层):从 .log 的 stream-json 把 tool_use 与 tool_result 按 id 配对,
+ * 一条 = 工具名、最要紧的那个参数(路径 / 命令 / 模式)、成没成、结果多少字。events.jsonl 的工具事件只有一个 120 字的显示串;
+ * 这份物化进索引消息的 tools,回答「老师为什么没看见档案那一行」「这轮读了几个文件」。
+ */
+export interface ToolCall {
+    name: string;
+    /** 最要紧的参数:Read / Edit / Write 的 file_path、Bash 的 command、Grep 的 pattern in path、Skill 的 skill;没有就空串 */
+    arg: string;
+    /** true 成功 / false 报错 / null 没等到结果(被杀、还在跑、或 CLI 没回) */
+    ok: boolean | null;
+    /** 结果文本的字数 */
+    chars: number;
+    sub?: boolean;
+}
+export declare function toolArg(input: Record<string, unknown> | undefined): string;
+export declare function toolCalls(text: string, parse?: LineParser): ToolCall[];
+export declare function parseTranscript(text: string, parse?: LineParser): Transcript;

package/dist/brain/transcript.js

@@ -0,0 +1,132 @@
+/**
+ * 一轮的转录(.log,一行一个 JSON)→ 家长视图条目 + 最终文本。起初抄自 growth-apps 的 gen-transcript(2026-08-26,claude 2.1.220),
+ * 现在读成统一事件再拼(./log.ts:API 轮次的统一事件,旧轮次的 stream-json):子代理的条目标 sub(旧轮次的 CLI 才有),
+ * 收尾的最终正文单独取出作 final,孩子视图只看它。
+ */
+import { parseLogLine } from "./log.js";
+import { tokenText } from "../shared/tokens.js";
+const FOLD_AT = 3;
+/**
+ * 展示前折叠:连续 ≥3 条工具行收成一组;报错行永不折;末尾还在长的段留最后 2 条直播。
+ */
+export function foldRuns(items) {
+    const rows = [];
+    let i = 0;
+    while (i < items.length) {
+        if (items[i].kind !== 'tool') {
+            rows.push(items[i]);
+            i++;
+            continue;
+        }
+        let j = i;
+        while (j < items.length && items[j].kind === 'tool')
+            j++;
+        const run = items.slice(i, j);
+        const keep = j === items.length ? Math.min(2, run.length) : 0;
+        const folded = run.slice(0, run.length - keep);
+        if (folded.length >= FOLD_AT) {
+            rows.push({ kind: 'fold', tools: folded });
+            rows.push(...run.slice(run.length - keep));
+        }
+        else
+            rows.push(...run);
+        i = j;
+    }
+    return rows;
+}
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n)}…` : s);
+/** 路径截头留尾:要紧的是文件名(作业照片的绝对路径在 workspace 深的机器上会超长) */
+const clipPath = (s, n) => (s.length > n ? `…${s.slice(-n)}` : s);
+export function toolSummary(name, input) {
+    for (const k of ['description', 'command', 'file_path', 'skill', 'pattern', 'prompt', 'url']) {
+        const v = input?.[k];
+        if (typeof v === 'string' && v.trim())
+            return `${name} · ${k === 'file_path' ? clipPath(v.trim(), 120) : clip(v.trim(), 120)}`;
+    }
+    return name;
+}
+const ARG_KEYS = ['file_path', 'command', 'pattern', 'path', 'skill', 'url', 'query', 'description', 'prompt'];
+export function toolArg(input) {
+    if (!input)
+        return '';
+    if (typeof input.pattern === 'string' && typeof input.path === 'string')
+        return clip(`${input.pattern} in ${input.path}`, 300);
+    for (const k of ARG_KEYS) {
+        const v = input[k];
+        if (typeof v === 'string' && v.trim())
+            return clip(v.trim(), 300);
+    }
+    return '';
+}
+export function toolCalls(text, parse = parseLogLine) {
+    const calls = [];
+    const byId = new Map();
+    for (const line of text.split('\n')) {
+        for (const e of parse(line)) {
+            if (e.kind === 'assistant') {
+                for (const p of e.parts) {
+                    if (p.type !== 'tool')
+                        continue;
+                    const c = { name: p.tool.name, arg: toolArg(p.tool.input), ok: null, chars: 0, ...(e.sub ? { sub: true } : {}) };
+                    calls.push(c);
+                    if (p.tool.id)
+                        byId.set(p.tool.id, c);
+                }
+            }
+            else if (e.kind === 'results') {
+                for (const r of e.results) {
+                    const c = byId.get(r.id);
+                    if (!c)
+                        continue;
+                    c.ok = r.ok;
+                    c.chars = r.text.length;
+                }
+            }
+        }
+    }
+    return calls;
+}
+export function parseTranscript(text, parse = parseLogLine) {
+    let sessionId = null;
+    const items = [];
+    let final = null;
+    // 每次请求自己的 token,按消息 id 去重(同一条回复分几行出时 usage 是重复的,留最后一份);子代理的也算钱
+    const used = new Map();
+    for (const line of text.split('\n')) {
+        for (const e of parse(line)) {
+            if (e.kind === 'session') {
+                if (!sessionId)
+                    sessionId = e.id;
+            }
+            else if (e.kind === 'assistant') {
+                if (e.usage)
+                    used.set(e.usage.id, e.usage);
+                const sub = e.sub ? true : undefined;
+                for (const p of e.parts) {
+                    if (p.type === 'text' && p.text.trim())
+                        items.push({ kind: 'text', text: p.text.trim(), sub });
+                    else if (p.type === 'tool')
+                        items.push({ kind: 'tool', text: toolSummary(p.tool.name, p.tool.input), sub });
+                }
+            }
+            else if (e.kind === 'results') {
+                const sub = e.sub ? true : undefined;
+                for (const r of e.results)
+                    if (!r.ok)
+                        items.push({ kind: 'tool-error', text: clip(r.text.trim(), 300), sub });
+            }
+            else if (e.kind === 'result') {
+                // 收尾报的可能是整个会话的累计(qwen 续会话):有每次请求的就按它们加总
+                const reqs = [...used.values()];
+                const f = reqs.length ? { ...e.final, inTokens: reqs.reduce((n, u) => n + u.in, 0), outTokens: reqs.reduce((n, u) => n + u.out, 0), cachedTokens: reqs.reduce((n, u) => n + u.cached, 0) } : e.final;
+                if (f.text && !items.some((i) => i.kind === 'text' && !i.sub))
+                    items.push({ kind: 'text', text: f.text });
+                const cost = f.inTokens !== undefined ? ` · ${tokenText({ in: f.inTokens, out: f.outTokens ?? 0 })}` : '';
+                const turns = f.numTurns !== undefined ? ` · ${f.numTurns} 轮` : '';
+                items.push({ kind: 'done', text: f.ok ? `本轮结束${turns}${cost}` : `本轮出错(${f.reason})${turns}${cost}` });
+                final = f;
+            }
+        }
+    }
+    return { sessionId, items, final };
+}

package/dist/brain/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 脑的统一事件与工具:API 脑(./api.ts)写进 .log、孩子端的流式板书、家长端看原文、转录都只认这些。
+ * 名字里的 Cli 是 2026-11-02 以前起 Qwen Code 时留下的;那时的 .log 是 stream-json,由 ./stream-json.ts 读成同样的事件。
+ */
+/** 工具的类别:应用要知道「读了哪个文件」「是不是用技能回读板书写法」时按类别认,不比工具名 */
+export type ToolKind = 'read' | 'shell' | 'search' | 'edit' | 'skill' | 'other';
+export declare const toolKind: (name: string) => ToolKind;
+/**
+ * 这轮带不带工具(政策 tools 与消息种类定):off 一个不带;read 只读(看照片、读 vault、查教材);
+ * on 与 read 一样只读,不提供 shell 与写入工具
+ */
+export type ToolSet = 'off' | 'read' | 'on';
+export interface ToolUse {
+    /** 和工具结果配对用;有的 CLI 可能不给 */
+    id?: string;
+    name: string;
+    input?: Record<string, unknown>;
+}
+export interface ToolResult {
+    id: string;
+    ok: boolean;
+    /** 结果的文字(图片等非文字块不算) */
+    text: string;
+}
+/** 一条整的回复里的一段:正文或一次工具调用 */
+export type AssistantPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool';
+    tool: ToolUse;
+};
+/** 一条回复的正文段 / 工具调用 */
+export declare const textsOf: (parts: readonly AssistantPart[]) => string[];
+export declare const toolsOf: (parts: readonly AssistantPart[]) => ToolUse[];
+/** 一次模型请求的 token:in 含缓存读、缓存写,cached 是其中命中缓存的;id 是那条回复的消息 id */
+export interface RequestUsage {
+    id: string;
+    in: number;
+    out: number;
+    cached: number;
+}
+/** 一轮的收尾 */
+export interface CliFinal {
+    ok: boolean;
+    /** 最终正文(孩子视图只看它);没有就是 null */
+    text: string | null;
+    /** 不 ok 时的原因 */
+    reason: string | null;
+    numTurns?: number;
+    /** 这一轮的 token:输入(含缓存读、缓存写)与输出;记账按它(报的钱数不认,src/shared/tokens.ts)。
+     *  CLI 收尾报的可能是整个会话的累计(qwen 续会话时就是),parseTranscript 有每次请求的 usage 就按它们加总 */
+    inTokens?: number;
+    outTokens?: number;
+    /** 输入里命中缓存的那部分(API 运行时报;CLI 有每次请求的 usage 时也有) */
+    cachedTokens?: number;
+    /** 这一轮最后一次请求的输入 = 这一轮结束时上下文多大(API 运行时报;过 32k 整段压缩看它) */
+    contextTokens?: number;
+}
+/**
+ * 统一事件:一行输出读出零到几条。sub = 来自子代理(老师不派子代理,有也不算老师的话)。
+ * - session:这行带着会话 id(取第一次见到的)
+ * - init:进程起来报的工具表(用来核对「不带工具」真的一个没有)
+ * - start:开始新的一条回复(增量模式)
+ * - delta:回复正文的一小段(增量模式)
+ * - thinking:模型在想(增量模式,只说明模型开始回了)
+ * - assistant:一条整的回复:正文段与工具调用,按原来的先后;usage = 这一次请求自己的 token(消息 id 去重用,同一条回复可能分几行出)
+ * - results:工具结果
+ * - result:一轮收尾
+ */
+export type CliEvent = {
+    kind: 'session';
+    id: string;
+} | {
+    kind: 'init';
+    tools: string[];
+} | {
+    kind: 'start';
+    sub: boolean;
+} | {
+    kind: 'delta';
+    text: string;
+    sub: boolean;
+} | {
+    kind: 'thinking';
+    sub: boolean;
+} | {
+    kind: 'assistant';
+    parts: AssistantPart[];
+    sub: boolean;
+    usage?: RequestUsage;
+} | {
+    kind: 'results';
+    results: ToolResult[];
+    sub: boolean;
+} | {
+    kind: 'result';
+    final: CliFinal;
+};

package/dist/brain/types.js

@@ -0,0 +1,14 @@
+/**
+ * 脑的统一事件与工具:API 脑(./api.ts)写进 .log、孩子端的流式板书、家长端看原文、转录都只认这些。
+ * 名字里的 Cli 是 2026-11-02 以前起 Qwen Code 时留下的;那时的 .log 是 stream-json,由 ./stream-json.ts 读成同样的事件。
+ */
+/** 工具名 → 类别:API 脑的三样(./api-tools.ts)与旧轮次里 Qwen Code、Claude Code 的工具名;不认识的是 other */
+const TOOL_KINDS = {
+    read_file: 'read', read_many_files: 'read', zoom_image: 'read', list_directory: 'read', glob: 'search', grep_search: 'search',
+    run_shell_command: 'shell', edit: 'edit', write_file: 'edit', notebook_edit: 'edit', skill: 'skill',
+    Read: 'read', Bash: 'shell', Grep: 'search', Glob: 'search', Edit: 'edit', Write: 'edit', NotebookEdit: 'edit', MultiEdit: 'edit', Skill: 'skill',
+};
+export const toolKind = (name) => TOOL_KINDS[name] ?? 'other';
+/** 一条回复的正文段 / 工具调用 */
+export const textsOf = (parts) => parts.flatMap((p) => (p.type === 'text' ? [p.text] : []));
+export const toolsOf = (parts) => parts.flatMap((p) => (p.type === 'tool' ? [p.tool] : []));

package/dist/chalk/actions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 笔顺里的动作(drawtell 重新设计第 3 步):erase 擦掉前面画过的几样,board 换一块画板(旧板上的连背景图一起擦干净)。
+ * 动作和画一笔一样占时间、被步覆盖;这里只管「谁擦了谁、谁在第几块画板」,时钟、bake、check、圈住了什么都用这一份。
+ * 纯函数,不抛:引用不对的记进 problems(check 报),其余照样算。
+ */
+import type { ChalkBackground, ChalkSkeleton } from './types.ts';
+export declare const isAction: (e: {
+    type?: unknown;
+}) => boolean;
+export interface ResolvedBoard {
+    /** 换到这块画板的 board 动作;第一块(场景本身)= null */
+    id: string | null;
+    background?: ChalkBackground;
+}
+export interface ResolvedActions {
+    /** 每个元素(含动作)在第几块画板(0 起);board 动作本身算在它擦掉的那块(旧板)上 */
+    boardOf: Map<string, number>;
+    /** 被擦掉的元素 → 擦它的动作 id */
+    erasedBy: Map<string, string>;
+    /** 动作 → 它擦掉的元素(erase:targets 里引用对的;board:旧板上还没擦掉的、画的元素,按笔顺) */
+    targets: Map<string, string[]>;
+    boards: ResolvedBoard[];
+    /** 引用不对的地方(动作 id + 怎么改) */
+    problems: {
+        id: string;
+        message: string;
+    }[];
+}
+export declare function resolveActions(skeletons: readonly ChalkSkeleton[], background?: ChalkBackground): ResolvedActions;
+/**
+ * 课讲完时画面上还留着的:最后一块画板上没擦掉的画的元素,与那块板的背景图。
+ * 应用把课包当底图放进编辑器(画板卡)用它;动作不交给 excalidraw。
+ */
+export declare function finalBoard<T extends ChalkSkeleton>(skeletons: readonly T[], background?: ChalkBackground): {
+    skeletons: T[];
+    background?: ChalkBackground;
+};

package/dist/chalk/actions.js

@@ -0,0 +1,69 @@
+/**
+ * 笔顺里的动作(drawtell 重新设计第 3 步):erase 擦掉前面画过的几样,board 换一块画板(旧板上的连背景图一起擦干净)。
+ * 动作和画一笔一样占时间、被步覆盖;这里只管「谁擦了谁、谁在第几块画板」,时钟、bake、check、圈住了什么都用这一份。
+ * 纯函数,不抛:引用不对的记进 problems(check 报),其余照样算。
+ */
+export const isAction = (e) => e.type === 'erase' || e.type === 'board';
+export function resolveActions(skeletons, background) {
+    const boardOf = new Map();
+    const erasedBy = new Map();
+    const targets = new Map();
+    const boards = [{ id: null, ...(background ? { background } : {}) }];
+    const problems = [];
+    const all = new Map(skeletons.map((e) => [e.id, e]));
+    const seen = new Set();
+    // 当前这块板上、还没擦掉的画的元素(按笔顺)
+    let onBoard = [];
+    for (const e of skeletons) {
+        const board = boards.length - 1;
+        boardOf.set(e.id, board);
+        if (e.type === 'erase') {
+            const got = [];
+            const list = Array.isArray(e.targets) ? e.targets : [];
+            if (!list.length)
+                problems.push({ id: e.id, message: `擦除 '${e.id}' 没写 targets;写上要擦掉的元素 id(前面画过的)` });
+            for (const t of list) {
+                const id = String(t);
+                const what = all.get(id);
+                if (!what)
+                    problems.push({ id: e.id, message: `擦除 '${e.id}' 要擦的 '${id}' 不存在;targets 写 skeletons 里的元素 id` });
+                else if (!seen.has(id))
+                    problems.push({ id: e.id, message: `擦除 '${e.id}' 要擦的 '${id}' 在它后面才画;只能擦前面画过的` });
+                else if (isAction(what))
+                    problems.push({ id: e.id, message: `擦除 '${e.id}' 要擦的 '${id}' 是动作,不是画的东西` });
+                else if (erasedBy.has(id))
+                    problems.push({ id: e.id, message: `擦除 '${e.id}' 要擦的 '${id}' 已经被 '${erasedBy.get(id)}' 擦掉了${boardOf.get(id) !== board ? '(换画板时)' : ''}` });
+                else if (got.includes(id))
+                    problems.push({ id: e.id, message: `擦除 '${e.id}' 的 targets 里 '${id}' 写了两遍` });
+                else
+                    got.push(id);
+            }
+            for (const id of got)
+                erasedBy.set(id, e.id);
+            onBoard = onBoard.filter((id) => !got.includes(id));
+            targets.set(e.id, got);
+        }
+        else if (e.type === 'board') {
+            for (const id of onBoard)
+                erasedBy.set(id, e.id);
+            targets.set(e.id, onBoard);
+            onBoard = [];
+            const bg = e.background;
+            boards.push({ id: e.id, ...(bg ? { background: bg } : {}) });
+        }
+        else
+            onBoard.push(e.id);
+        seen.add(e.id);
+    }
+    return { boardOf, erasedBy, targets, boards, problems };
+}
+/**
+ * 课讲完时画面上还留着的:最后一块画板上没擦掉的画的元素,与那块板的背景图。
+ * 应用把课包当底图放进编辑器(画板卡)用它;动作不交给 excalidraw。
+ */
+export function finalBoard(skeletons, background) {
+    const r = resolveActions(skeletons, background);
+    const last = r.boards.length - 1;
+    const bg = r.boards[last].background;
+    return { skeletons: skeletons.filter((e) => !isAction(e) && !r.erasedBy.has(e.id) && r.boardOf.get(e.id) === last), ...(bg ? { background: bg } : {}) };
+}

package/dist/chalk/bundle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 课包 → 场景(纯函数,浏览器外可用):scene.json + manifest.json 拼回 ChalkScene,过一遍 zod。
+ * 取文件是调用方的事(浏览器 fetch、Node readFile);拼法与校验只有这一份,播放页、CLI、应用都用它。
+ * parseBundle 拼 + 校验;assembleBundle 只拼(信得过的课包,省掉 zod)。
+ * 课包可能是旧版本或被手改过,错误要能说清楚改哪里。
+ */
+import type { ChalkScene } from './types.ts';
+import type { BoundsTuple } from './geometry.ts';
+import type { LessonPicture } from './circle.ts';
+export interface LessonBundle {
+    scene: ChalkScene;
+    /** build 时量好的包围盒(scene.json 的 bounds);老课包没有 */
+    bounds?: Record<string, BoundsTuple>;
+    /** 圈住了什么要的画面语义(分组、命中块、包围盒),直接交给 circleHits */
+    picture: LessonPicture;
+}
+export declare class BundleError extends Error {
+    name: string;
+}
+/** 两份 JSON(已 parse)→ 场景,过 zod;不合契约抛 BundleError(消息不带课包名,调用方加) */
+export declare function parseBundle(sceneJson: unknown, manifest: unknown): LessonBundle;
+/**
+ * 只拼不校验:信得过的课包(自己的服务端读过、校验过)在浏览器里用它,首屏不为 zod 付钱
+ * (只 import 它,打包时 zod 会被摇掉)。缺省值同 schema:steps 缺了是空数组。
+ */
+export declare function assembleBundle(sceneJson: Record<string, unknown>, manifest: Record<string, unknown>): LessonBundle;