cotutor 0.2.0 → 0.3.0

package/dist/chalk/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 播放器数据面。
+ *
+ * 场景语言 = excalidraw skeleton(契约 1),这里只声明我们消费的最小面,
+ * 深路径类型脆弱,一律不 import excalidraw 内部类型。
+ * 运行时校验在 src/schema/scene.ts(zod),两处结构保持对齐。
+ */
+/**
+ * 三层墨迹(交互重新设计的 InkLayerKind):
+ * base = 生成的底层(家长验收,锁定,永久);ink = 孩子手写(持久,是数据);
+ * feedback = 系统反馈(高亮、弹窗,短暂,用完自清)。
+ * 场景文件里的元素缺省即 base;ink/feedback 是运行时产物,场景一般不落它们。
+ * 标记放 customData.layer(excalidraw 编辑器往返可保全),不占顶层字段。
+ */
+export type ChalkLayer = 'base' | 'ink' | 'feedback';
+/**
+ * skeleton 元素:draw 顺序 = 数组顺序;id 保持干净,单笔时长走 animateDuration 字段。
+ * 笔顺里除了画的(excalidraw 元素,x / y 必填,check 把关),还可以有两种动作(ChalkErase、ChalkBoard):
+ * 它们和画一笔一样占时间、被步覆盖、跟着配音拉伸,只是不画东西,改的是画面上已经有的。
+ */
+export interface ChalkSkeleton {
+    type: string;
+    id: string;
+    /** 画的元素必填;动作(erase / board)没有位置 */
+    x?: number;
+    y?: number;
+    /** 单笔时长(毫秒),缺省 500;时钟(timeline / core 的 lessonClock)按它排笔 */
+    animateDuration?: number;
+    /** excalidraw 自定义数据;协议认领 layer(见 ChalkLayer)与 tool 两个键,其余透传 */
+    /**
+     * tool: 'eraser' = 这一笔是橡皮笔画:沿旧笔迹盖一道纸色粗线,画这一笔时笔尖换成橡皮,只用来擦一笔的一部分;
+     * 整样擦掉用 ChalkErase 动作。strokeColor 缺省取纸面底色;有背景图的地方擦不干净(盖住的是图)。
+     */
+    customData?: {
+        layer?: ChalkLayer;
+        tool?: 'eraser';
+        [key: string]: unknown;
+    };
+    /**
+     * 这一笔是什么(给人与应用读,不画出来):如「散的第 1 根小棒」「圈出剩下的 2 根」。
+     * 孩子圈住它时,应用说的就是这几个字;不写 = 按种类、颜色、第几步说(「第 1 步画的 3 条线」)。
+     */
+    label?: string;
+    [key: string]: unknown;
+}
+/**
+ * 擦掉前面画过的几样(整样擦,不是擦一半):擦的时候橡皮在它们上面来回走、它们渐渐淡掉,擦完就不在画面上了
+ * (播放、截图、圈住了什么都不算它)。要擦一笔的一部分,还是用 customData.tool: 'eraser' 的橡皮笔画。
+ */
+export interface ChalkErase extends ChalkSkeleton {
+    type: 'erase';
+    /** 擦哪几样:前面画过、还在这块画板上、还没擦掉的元素 id */
+    targets: string[];
+}
+/**
+ * 换一块画板:这块板上的东西(连背景图)橡皮擦干净,之后画在新的一块上。
+ * 每块画板自己的视口(有背景图 = 图片;没有 = 这块板上元素的包围盒),坐标各写各的,不用为了挤进一块板手算缩放。
+ * 第一块画板是场景的 background(或白板)。
+ */
+export interface ChalkBoard extends ChalkSkeleton {
+    type: 'board';
+    /** 新画板的背景图;缺省 = 白板。src 相对场景文件(build 拷进课包,改名 background-<id>.<ext>) */
+    background?: ChalkBackground;
+}
+/**
+ * 一组元素合起来是一样东西:「一捆 10 根小棒」「散的 3 根」「答案 5」。只是语义,不影响画法与笔顺;
+ * 一个元素可以在几组里(「散的 3 根」与「13 根小棒」)。孩子圈住这一组的大半,应用就说这一组的 label。
+ */
+export interface ChalkGroup {
+    id: string;
+    label: string;
+    elementIds: string[];
+}
+/**
+ * 词/字级命中块:孩子圈中(或点中)后播词音频、可再弹出子场景。
+ * 命中区域 = elementIds 所指底层元素包围盒的并——块锚在元素上,家长在编辑器里
+ * 挪动词块,命中区跟着走,不存坐标副本。
+ */
+export interface ChalkBlock {
+    id: string;
+    /** 组成该词条的底层元素(可跨相邻多个 text,如重点字母色拆出的 r + am) */
+    elementIds: string[];
+    /** 词条文本(英文单词或汉字串);与元素文本一致性由 check 把关,事件记录也用它 */
+    text: string;
+    /** 圈中即播,相对课包目录(如 audio/tokens/ram.mp3) */
+    audioSrc?: string;
+    /** 圈中后弹出的子场景(subscenes[].id);与 audioSrc 至少给一个,否则块无事发生 */
+    subsceneId?: string;
+}
+/**
+ * 子场景 = 弹窗:excalidraw fill 方框打底的小场景,逐笔画出、读完倒放擦除
+ * (反馈层生命周期,永不留存)。坐标系独立于主场景,叠放位置是运行时决定。
+ */
+export interface ChalkSubscene {
+    id: string;
+    skeletons: ChalkSkeleton[];
+    /** 可选步进(带讲稿);缺省 = 一笔到底连续画完 */
+    steps?: ChalkStep[];
+    /** 整窗音频(如慢速拼读),相对课包目录 */
+    audioSrc?: string;
+}
+export interface ChalkStep {
+    step: number;
+    /** 本步揭示的元素,必须与 skeleton 顺序连续对齐(模板保证笔顺) */
+    elementIds: string[];
+    /** 讲稿。v1 换 TTS 音轨,当前作字幕 */
+    line: string;
+    /** 步后气口:停,等孩子点一下(接力交互) */
+    pauseAfter: boolean;
+    /** 相对课包目录的音频路径,TTS 就绪后启用 */
+    audioSrc?: string;
+    /** 该步讲稿音频时长(毫秒),由 dub 写入;播放器据此把该步笔画拉伸到讲稿长度(只拉不缩) */
+    audioDurationMs?: number;
+}
+/**
+ * 背景图:垫在笔迹底下的一张图(题目原图、课本照片),笔迹直接圈画在它上面。
+ * 有背景图时画板 = 图片本身:场景坐标 (0,0)–(width,height) 就是图片像素,
+ * 画板不再随元素包围盒伸缩;画到图外的笔迹会被裁掉(check 提醒)。
+ */
+export interface ChalkBackground {
+    /** 场景源里相对场景文件;课包里相对课包目录(build 拷贝并改写) */
+    src: string;
+    /** 图片像素宽高,也是画板的场景坐标尺寸 */
+    width: number;
+    height: number;
+}
+export interface ChalkScene {
+    id: string;
+    title: string;
+    /** 题面,读题环节展示 */
+    problem: string;
+    /** 讲解模型名:时间数轴、实物图……;静态场景写生成来源(如 reading-page) */
+    model: string;
+    /** 讲解模板三档(架构.md)+ static(静态场景:无时间轴的点读/圈读页,steps 必空) */
+    template: 'paper-strict' | 'camera-free' | 'motion' | 'static';
+    /** 学科标签(自由文本,如 语文/数学/英语),入口按它归类;机制不枚举,枚举是应用政策 */
+    subject?: string;
+    /** 第一块画板的背景图(可选);缺省 = 白板。换画板见 ChalkBoard */
+    background?: ChalkBackground;
+    skeletons: ChalkSkeleton[];
+    /** 元素分组(语义,可选):孩子圈住了什么、检验方按名字说话都用它 */
+    groups?: ChalkGroup[];
+    /** 空数组 = 静态场景(装载即整幅定格);讲解三档必须非空,check 把关 */
+    steps: ChalkStep[];
+    /** 词/字级命中块;缺省 = 本场景没有块逻辑 */
+    blocks?: ChalkBlock[];
+    /** 弹窗子场景;由 blocks[].subsceneId 触发 */
+    subscenes?: ChalkSubscene[];
+}
+export type ChalkPhase = 'loading' | 'ready' | 'drawing' | 'gap' | 'done';

package/dist/chalk/types.js

@@ -0,0 +1,8 @@
+/**
+ * 播放器数据面。
+ *
+ * 场景语言 = excalidraw skeleton(契约 1),这里只声明我们消费的最小面,
+ * 深路径类型脆弱,一律不 import excalidraw 内部类型。
+ * 运行时校验在 src/schema/scene.ts(zod),两处结构保持对齐。
+ */
+export {};

package/dist/lib/index.d.ts

@@ -1,13 +1,15 @@
 /** 纯函数层:全部离屏可测,不依赖文件系统与网络。 */
-export * from './agent-file.ts';
-export * from './sections.ts';
-export * from './transcript.ts';
-export * from './kid-view.ts';
-export * from './kid-board.ts';
-export * from './board.ts';
-export * from './context-pack.ts';
-export * from './plan.ts';
-export * from './ledger.ts';
-export * from './conversation.ts';
-export * from './run-plan.ts';
-export * from './timetable.ts';
+export * from '../runtime/agent-file.ts';
+export * from '../board/sections.ts';
+export * from '../brain/transcript.ts';
+export * from '../runtime/kid-view.ts';
+export * from '../board/presentation.ts';
+export * from '../board/parse.ts';
+export * from '../runtime/context/context-pack.ts';
+export * from '../runtime/context/tutor-rules.ts';
+export * from '../memory/plan.ts';
+export * from '../runtime/journal/ledger.ts';
+export * from '../runtime/journal/conversation.ts';
+export * from '../shared/time.ts';
+export * from '../brain/cli/run-plan.ts';
+export * from '../memory/timetable.ts';

package/dist/lib/index.js

@@ -1,13 +1,15 @@
 /** 纯函数层:全部离屏可测,不依赖文件系统与网络。 */
-export * from "./agent-file.js";
-export * from "./sections.js";
-export * from "./transcript.js";
-export * from "./kid-view.js";
-export * from "./kid-board.js";
-export * from "./board.js";
-export * from "./context-pack.js";
-export * from "./plan.js";
-export * from "./ledger.js";
-export * from "./conversation.js";
-export * from "./run-plan.js";
-export * from "./timetable.js";
+export * from "../runtime/agent-file.js";
+export * from "../board/sections.js";
+export * from "../brain/transcript.js";
+export * from "../runtime/kid-view.js";
+export * from "../board/presentation.js";
+export * from "../board/parse.js";
+export * from "../runtime/context/context-pack.js";
+export * from "../runtime/context/tutor-rules.js";
+export * from "../memory/plan.js";
+export * from "../runtime/journal/ledger.js";
+export * from "../runtime/journal/conversation.js";
+export * from "../shared/time.js";
+export * from "../brain/cli/run-plan.js";
+export * from "../memory/timetable.js";

package/dist/media/draw.d.ts

@@ -0,0 +1,23 @@
+export declare const DRAW_TIMEOUT_MS = 180000;
+export type Drawn = ({
+    ok: true;
+    data: Buffer;
+    model: string;
+} | {
+    ok: false;
+    error: string;
+}) & {
+    ms: number;
+};
+/** 画一张:提示词、模型、尺寸、反向提示词(缺省 PAINT_NEGATIVE)→ PNG(测试与 mock 注入假的) */
+export type Draw = (job: {
+    prompt: string;
+    model: string;
+    size: string;
+    negative?: string;
+}) => Promise<Drawn>;
+export declare function makeDraw(opts?: {
+    env?: NodeJS.ProcessEnv;
+    endpoint?: string;
+    timeoutMs?: number;
+}): Draw;

package/dist/media/draw.js

@@ -0,0 +1,44 @@
+/**
+ * 交给百炼文生图(同步接口 multimodal-generation)画一张,拿回 PNG。百炼给的图片地址 24 小时就过期,拿到就下载。
+ * key 与端点按模型定(src/shared/qianwen.ts:Token Plan 有这个模型就走它,否则百炼按量),key 只进请求头。出错、超时都不抛。
+ * 2026-10-11 实测:qwen-image-2.0 一张 4 秒、qwen-image-2.0-pro 15 秒(1536*1536);公网域名能用,不用业务空间的域名。
+ */
+import { imageUrl, qianwenKeys, qianwenLine } from "../shared/qianwen.js";
+import { PAINT_NEGATIVE } from "../schema/index.js";
+export const DRAW_TIMEOUT_MS = 180_000;
+export function makeDraw(opts = {}) {
+    return async ({ prompt, model, size, negative }) => {
+        const env = opts.env ?? process.env;
+        const t0 = Date.now();
+        const fail = (error) => ({ ok: false, error, ms: Date.now() - t0 });
+        const line = qianwenLine(model, qianwenKeys(env));
+        if (!line)
+            return fail('no_key');
+        const signal = AbortSignal.timeout(opts.timeoutMs ?? DRAW_TIMEOUT_MS);
+        try {
+            const res = await fetch(opts.endpoint ?? imageUrl(line.host), {
+                method: 'POST',
+                headers: { authorization: `Bearer ${line.key}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ model, input: { messages: [{ role: 'user', content: [{ text: prompt }] }] }, parameters: { size, n: 1, prompt_extend: false, watermark: false, negative_prompt: negative || PAINT_NEGATIVE } }),
+                signal,
+            });
+            const j = (await res.json().catch(() => ({})));
+            // 内容审核没过是 400 + DataInspectionFailed:原样记下,家长端看得到
+            if (!res.ok)
+                return fail(`http_${res.status}${j.code ? `:${j.code}` : ''}`);
+            const url = j.output?.choices?.[0]?.message?.content?.find((c) => typeof c.image === 'string')?.image;
+            if (!url)
+                return fail(j.code ? `no_image:${j.code}` : 'no_image');
+            const img = await fetch(url, { signal });
+            if (!img.ok)
+                return fail(`download_${img.status}`);
+            const data = Buffer.from(await img.arrayBuffer());
+            if (data.length < 8 || data.readUInt32BE(0) !== 0x89504e47)
+                return fail('not_png');
+            return { ok: true, data, model, ms: Date.now() - t0 };
+        }
+        catch (err) {
+            return fail(err instanceof Error && err.name === 'TimeoutError' ? 'timeout' : 'network');
+        }
+    };
+}

package/dist/media/mp3.d.ts

@@ -0,0 +1,6 @@
+/**
+ * mp3 的时长(零依赖,读帧头):有 Xing/Info 头按帧数算,否则按码率算(CBR,和 afinfo 差不到 1%)。2026-10-31 从 voxtell 的 audio-info 搬来:
+ * 课包配音(cotutor chalk dub)量每步讲稿多长,播放器按它把这一步的笔画拉伸到讲稿那么长。
+ */
+/** mp3(Layer III)时长,毫秒;认不出 null */
+export declare function mp3DurationMs(b: Uint8Array): number | null;

package/dist/media/mp3.js

@@ -0,0 +1,58 @@
+/**
+ * mp3 的时长(零依赖,读帧头):有 Xing/Info 头按帧数算,否则按码率算(CBR,和 afinfo 差不到 1%)。2026-10-31 从 voxtell 的 audio-info 搬来:
+ * 课包配音(cotutor chalk dub)量每步讲稿多长,播放器按它把这一步的笔画拉伸到讲稿那么长。
+ */
+const MPEG1_BITRATES = [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320];
+const MPEG2_BITRATES = [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160];
+const SAMPLE_RATES = {
+    3: [44100, 48000, 32000], // MPEG1
+    2: [22050, 24000, 16000], // MPEG2
+    0: [11025, 12000, 8000], // MPEG2.5
+};
+function id3v2Size(b) {
+    if (b.length < 10 || b[0] !== 0x49 || b[1] !== 0x44 || b[2] !== 0x33)
+        return 0;
+    const size = ((b[6] & 0x7f) << 21) | ((b[7] & 0x7f) << 14) | ((b[8] & 0x7f) << 7) | (b[9] & 0x7f);
+    const footer = b[5] & 0x10 ? 10 : 0;
+    return 10 + size + footer;
+}
+/** mp3(Layer III)时长,毫秒;认不出 null */
+export function mp3DurationMs(b) {
+    let off = id3v2Size(b);
+    // 找第一个帧同步(容忍 tag 与帧之间的垃圾字节,最多扫 64KB)
+    const limit = Math.min(b.length - 4, off + 65536);
+    for (; off < limit; off++) {
+        if (b[off] !== 0xff || (b[off + 1] & 0xe0) !== 0xe0)
+            continue;
+        const version = (b[off + 1] >> 3) & 3; // 3=MPEG1 2=MPEG2 0=MPEG2.5
+        const layer = (b[off + 1] >> 1) & 3; // 1 = Layer III
+        if (version === 1 || layer !== 1)
+            continue;
+        const brIdx = (b[off + 2] >> 4) & 0xf;
+        const srIdx = (b[off + 2] >> 2) & 3;
+        if (brIdx === 0 || brIdx === 15 || srIdx === 3)
+            continue;
+        const bitrateKbps = (version === 3 ? MPEG1_BITRATES : MPEG2_BITRATES)[brIdx];
+        const sampleRate = SAMPLE_RATES[version][srIdx];
+        const channelMode = (b[off + 3] >> 6) & 3; // 3 = mono
+        const samplesPerFrame = version === 3 ? 1152 : 576;
+        // Xing/Info(VBR 或带帧数的 CBR):在第一帧 side info 之后
+        const sideInfo = version === 3 ? (channelMode === 3 ? 17 : 32) : channelMode === 3 ? 9 : 17;
+        const x = off + 4 + sideInfo;
+        if (x + 16 <= b.length) {
+            const tag = String.fromCharCode(b[x], b[x + 1], b[x + 2], b[x + 3]);
+            if (tag === 'Xing' || tag === 'Info') {
+                const flags = (b[x + 4] << 24) | (b[x + 5] << 16) | (b[x + 6] << 8) | b[x + 7];
+                if (flags & 1) {
+                    const frames = ((b[x + 8] << 24) | (b[x + 9] << 16) | (b[x + 10] << 8) | b[x + 11]) >>> 0;
+                    if (frames > 0)
+                        return Math.round((frames * samplesPerFrame * 1000) / sampleRate);
+                }
+            }
+        }
+        // CBR:剩余字节 / 每秒字节
+        const bytes = b.length - off;
+        return Math.round((bytes * 8) / bitrateKbps);
+    }
+    return null;
+}

package/dist/media/mp4.d.ts

@@ -0,0 +1 @@
+export declare function mp4DurationMs(file: string): Promise<number | null>;

package/dist/media/mp4.js

@@ -0,0 +1,58 @@
+/**
+ * mp4 的时长(视频小课堂的课长第 4 步):走顶层的盒子找 moov,再在里面找 mvhd,读 timescale 与 duration。
+ * 只读盒子头,不把整个文件读进来(moov 在末尾也行);认不出来回 null,不抛。
+ */
+import { open } from 'node:fs/promises';
+export async function mp4DurationMs(file) {
+    const fh = await open(file, 'r').catch(() => null);
+    if (!fh)
+        return null;
+    try {
+        const size = (await fh.stat()).size;
+        const read = async (at, n) => {
+            const b = Buffer.alloc(n);
+            const { bytesRead } = await fh.read(b, 0, n, at);
+            return b.subarray(0, bytesRead);
+        };
+        /** [from, to) 里找某个盒子:回它的正文起点与终点 */
+        const find = async (from, to, type) => {
+            let at = from;
+            while (at + 8 <= to) {
+                const h = await read(at, 16);
+                if (h.length < 8)
+                    return null;
+                let len = h.readUInt32BE(0);
+                let head = 8;
+                if (len === 1) {
+                    if (h.length < 16)
+                        return null;
+                    len = Number(h.readBigUInt64BE(8));
+                    head = 16;
+                }
+                else if (len === 0)
+                    len = to - at;
+                if (len < head)
+                    return null;
+                if (h.toString('latin1', 4, 8) === type)
+                    return { body: at + head, end: Math.min(at + len, to) };
+                at += len;
+            }
+            return null;
+        };
+        const moov = await find(0, size, 'moov');
+        const mvhd = moov ? await find(moov.body, moov.end, 'mvhd') : null;
+        if (!mvhd)
+            return null;
+        const b = await read(mvhd.body, 32);
+        const v1 = b[0] === 1;
+        const scale = v1 ? b.readUInt32BE(20) : b.readUInt32BE(12);
+        const dur = v1 ? Number(b.readBigUInt64BE(24)) : b.readUInt32BE(16);
+        return scale > 0 ? Math.round((dur / scale) * 1000) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await fh.close();
+    }
+}

package/dist/media/tts-voices.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 卡的配音认的音色:百炼 Qwen-Audio-TTS(qwen-audio-3.0-tts-plus)的 597 个基础音色。2026-10-31 从 voxtell 的 data/voices.json 搬来
+ * (那份是官方音色列表经 video-script 的 docs/qwen3-tts 整理的);id 带模型前缀,旧代短名(如 longanlingxin)也能合成,但不在表里。
+ * 工作台音色页「卡的配音」照这张表列、试听、挑(写进 cotutor.json 的 tutors.<名>.voice);老师开口的嘴是另一张表(src/realtime/voices.ts)。
+ */
+export interface TtsVoice {
+    /** 合成请求的 voice 参数,也是 tutors.<名>.voice 里写的 */
+    voice: string;
+    /** 官方的中文名 */
+    name: string;
+    /** 女 / 男 / 未标注 */
+    gender: string;
+    age: number;
+    trait: string;
+    scene: string;
+    lang: string;
+}
+export declare const TTS_VOICES: readonly TtsVoice[];