cotutor 0.2.0 → 0.4.0

package/dist/chalk/text-metrics.js

@@ -0,0 +1,156 @@
+/**
+ * 机器生成(scripts/gen-text-metrics.mjs),别手改:excalidraw 手写字体里每个字的宽(字号 1),用真播放器量的。
+ * 表里没有的:CJK 统一表意文字按 CJK_EM(量了 49 个常用字取平均,最宽最窄差 0.000),其余按 FALLBACK_EM。
+ */
+export const LINE_HEIGHT = 1.25;
+export const CJK_EM = 1;
+export const FALLBACK_EM = 0.55;
+export const CHAR_EM = {
+    "0": 0.664,
+    "1": 0.467,
+    "2": 0.7,
+    "3": 0.608,
+    "4": 0.585,
+    "5": 0.618,
+    "6": 0.64,
+    "7": 0.558,
+    "8": 0.636,
+    "9": 0.629,
+    " ": 0.4,
+    "!": 0.333,
+    "\"": 0.408,
+    "#": 0.783,
+    "$": 0.721,
+    "%": 0.928,
+    "&": 0.778,
+    "'": 0.218,
+    "(": 0.441,
+    ")": 0.402,
+    "*": 0.525,
+    "+": 0.564,
+    ",": 0.257,
+    "-": 0.411,
+    ".": 0.274,
+    "/": 0.381,
+    ":": 0.278,
+    ";": 0.298,
+    "<": 0.564,
+    "=": 0.564,
+    ">": 0.564,
+    "?": 0.466,
+    "@": 0.921,
+    "A": 0.722,
+    "B": 0.761,
+    "C": 0.667,
+    "D": 0.78,
+    "E": 0.707,
+    "F": 0.661,
+    "G": 0.78,
+    "H": 0.722,
+    "I": 0.545,
+    "J": 0.569,
+    "K": 0.722,
+    "L": 0.611,
+    "M": 0.889,
+    "N": 0.722,
+    "O": 0.767,
+    "P": 0.698,
+    "Q": 0.768,
+    "R": 0.736,
+    "S": 0.622,
+    "T": 0.857,
+    "U": 0.73,
+    "V": 0.722,
+    "W": 0.944,
+    "X": 0.722,
+    "Y": 0.722,
+    "Z": 0.832,
+    "[": 0.472,
+    "\\": 0.409,
+    "]": 0.497,
+    "^": 0.51,
+    "_": 0.67,
+    "`": 0.6,
+    "a": 0.576,
+    "b": 0.555,
+    "c": 0.504,
+    "d": 0.605,
+    "e": 0.537,
+    "f": 0.415,
+    "g": 0.555,
+    "h": 0.567,
+    "i": 0.278,
+    "j": 0.418,
+    "k": 0.533,
+    "l": 0.278,
+    "m": 0.778,
+    "n": 0.526,
+    "o": 0.6,
+    "p": 0.537,
+    "q": 0.539,
+    "r": 0.412,
+    "s": 0.543,
+    "t": 0.553,
+    "u": 0.548,
+    "v": 0.552,
+    "w": 0.722,
+    "x": 0.591,
+    "y": 0.53,
+    "z": 0.572,
+    "{": 0.504,
+    "|": 0.299,
+    "}": 0.544,
+    "~": 0.669,
+    "−": 0.564,
+    "×": 0.564,
+    "÷": 0.55,
+    "±": 0.55,
+    "→": 1,
+    "←": 1,
+    "↑": 1,
+    "↓": 1,
+    "·": 0.25,
+    "°": 0.412,
+    "²": 0.5,
+    "³": 0.5,
+    "√": 1,
+    "≈": 0.782,
+    "≠": 0.788,
+    "≤": 0.788,
+    "≥": 0.788,
+    "…": 1,
+    "—": 1,
+    "–": 0.702,
+    "○": 1,
+    "●": 1,
+    "□": 1,
+    "■": 1,
+    "△": 1,
+    "▲": 1,
+    "☆": 1,
+    "★": 1,
+    "✓": 0.764,
+    "✗": 0.571,
+    "①": 1,
+    "②": 1,
+    "③": 1,
+    "④": 1,
+    "⑤": 1,
+    "⑥": 1,
+    "⑦": 1,
+    "⑧": 1,
+    "⑨": 1,
+    "⑩": 1,
+    "。": 1,
+    "、": 1,
+    "「": 1,
+    "」": 1,
+    "『": 1,
+    "』": 1,
+    "《": 1,
+    "》": 1,
+    "“": 0.444,
+    "”": 0.444,
+    "‘": 0.267,
+    "’": 0.304
+};

package/dist/chalk/timeline.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 步进时间轴:笔画按数组顺序串行,单笔时长 animateDuration(缺省 500ms),起点 START_MS(1000)。
+ * 最早是镜像 excalidraw-animate 的调度规则(0.7.2);播放改成烤好的画面 + 自己的时钟以后(drawtell 重新设计第 4 步),
+ * 这里就是时间的唯一来源:ChalkPlayer、core 的 lessonClock、应用的时钟都从这里算,规则没变,老课包的节奏不变。
+ * groupIds、id 里带 animate 指令仍然拒绝(老规矩,check 也拦)。
+ */
+import type { ChalkSkeleton, ChalkStep } from './types.ts';
+export declare const START_MS = 1000;
+/**
+ * 步尾定格不能停在 endMs 整点:SMIL 在 t == begin 时下一笔已经 active——
+ * round 线帽会露出下一笔起点的一个点,笔尖也跳到下一笔起点(第一批真题检验方反复报"下一步痕迹")。
+ * 退半毫秒:本步末笔 99.9% 以上已画完(肉眼不可辨),下一笔仍处于 opacity 0。
+ */
+export declare const FREEZE_EPS_MS = 0.5;
+/** 步尾定格时刻(秒),给 setCurrentTime 用 */
+export declare function freezeTimeSec(win: StepWindow): number;
+export declare function durationOf(el: ChalkSkeleton): number;
+export interface StepWindow {
+    startMs: number;
+    endMs: number;
+}
+/**
+ * 校验并计算每步的时间窗。
+ * 要求:steps 的 elementIds 恰好按顺序覆盖全部 skeleton(笔顺即步序)。
+ */
+export declare function computeStepWindows(skeletons: readonly ChalkSkeleton[], steps: readonly ChalkStep[]): StepWindow[];
+/** 拉伸后的每步账目:画多久、音多久、放大了几倍 */
+export interface StretchInfo {
+    step: number;
+    drawMs: number;
+    audioMs: number | null;
+    factor: number;
+}
+/**
+ * 按讲稿音频时长拉伸该步笔画(只拉不缩):有配音的步,若音频比画长,把该步全部笔画的
+ * animateDuration 等比放大到 ≈ 音频时长——"一边画一边数:1、2……14"时,14 个圈跟着数的节奏出现,
+ * 而不是 3 秒画完干等 8 秒。作者写的时长变成步内相对权重。音频短于画:照原速画完再等音。
+ * maxStretch 封顶:超过说明这步讲稿太长或画得太少,该回讲法层修,不该把一笔拖成十几秒。
+ * durations[i] 可覆盖 steps[i].audioDurationMs(播放器兜底探测到的时长)。
+ */
+export declare function stretchToAudio(skeletons: readonly ChalkSkeleton[], steps: readonly ChalkStep[], opts?: {
+    maxStretch?: number;
+    durations?: ReadonlyArray<number | null | undefined>;
+}): {
+    skeletons: ChalkSkeleton[];
+    info: StretchInfo[];
+};

package/dist/chalk/timeline.js

@@ -0,0 +1,84 @@
+/**
+ * 步进时间轴:笔画按数组顺序串行,单笔时长 animateDuration(缺省 500ms),起点 START_MS(1000)。
+ * 最早是镜像 excalidraw-animate 的调度规则(0.7.2);播放改成烤好的画面 + 自己的时钟以后(drawtell 重新设计第 4 步),
+ * 这里就是时间的唯一来源:ChalkPlayer、core 的 lessonClock、应用的时钟都从这里算,规则没变,老课包的节奏不变。
+ * groupIds、id 里带 animate 指令仍然拒绝(老规矩,check 也拦)。
+ */
+export const START_MS = 1000;
+const DEFAULT_DUR = 500;
+/**
+ * 步尾定格不能停在 endMs 整点:SMIL 在 t == begin 时下一笔已经 active——
+ * round 线帽会露出下一笔起点的一个点,笔尖也跳到下一笔起点(第一批真题检验方反复报"下一步痕迹")。
+ * 退半毫秒:本步末笔 99.9% 以上已画完(肉眼不可辨),下一笔仍处于 opacity 0。
+ */
+export const FREEZE_EPS_MS = 0.5;
+/** 步尾定格时刻(秒),给 setCurrentTime 用 */
+export function freezeTimeSec(win) {
+    return (win.endMs - FREEZE_EPS_MS) / 1000;
+}
+export function durationOf(el) {
+    return el.animateDuration ?? DEFAULT_DUR;
+}
+/**
+ * 校验并计算每步的时间窗。
+ * 要求:steps 的 elementIds 恰好按顺序覆盖全部 skeleton(笔顺即步序)。
+ */
+export function computeStepWindows(skeletons, steps) {
+    // 静态场景(steps 为空)没有时间窗;覆盖检查只对有步进的场景有意义
+    if (!steps.length)
+        return [];
+    const flat = steps.flatMap((s) => s.elementIds);
+    const ids = skeletons.map((e) => e.id);
+    if (flat.length !== ids.length || flat.some((id, i) => id !== ids[i])) {
+        throw new Error(`chalk-player: steps 未按顺序覆盖全部元素\n期望: ${ids.join(', ')}\n实际: ${flat.join(', ')}`);
+    }
+    for (const e of skeletons) {
+        if (e.groupIds && e.groupIds.length) {
+            throw new Error(`chalk-player: 元素 ${e.id} 带 groupIds,会破坏串行调度`);
+        }
+        if (/animate(Order|Duration):/.test(e.id)) {
+            throw new Error(`chalk-player: 元素 ${e.id} 的 id 携带 animate 指令;时长请写 animateDuration 字段,顺序只由数组决定`);
+        }
+    }
+    const end = new Map();
+    let cur = START_MS;
+    for (const e of skeletons) {
+        cur += durationOf(e);
+        end.set(e.id, cur);
+    }
+    let prev = START_MS;
+    return steps.map((s) => {
+        const startMs = prev;
+        const endMs = end.get(s.elementIds[s.elementIds.length - 1]);
+        prev = endMs;
+        return { startMs, endMs };
+    });
+}
+/**
+ * 按讲稿音频时长拉伸该步笔画(只拉不缩):有配音的步,若音频比画长,把该步全部笔画的
+ * animateDuration 等比放大到 ≈ 音频时长——"一边画一边数:1、2……14"时,14 个圈跟着数的节奏出现,
+ * 而不是 3 秒画完干等 8 秒。作者写的时长变成步内相对权重。音频短于画:照原速画完再等音。
+ * maxStretch 封顶:超过说明这步讲稿太长或画得太少,该回讲法层修,不该把一笔拖成十几秒。
+ * durations[i] 可覆盖 steps[i].audioDurationMs(播放器兜底探测到的时长)。
+ */
+export function stretchToAudio(skeletons, steps, opts = {}) {
+    const maxStretch = opts.maxStretch ?? 5;
+    const factorById = new Map();
+    const info = steps.map((s, i) => {
+        const byId = new Map(skeletons.map((e) => [e.id, e]));
+        const els = s.elementIds.map((id) => byId.get(id)).filter((e) => !!e);
+        const drawMs = els.reduce((a, e) => a + durationOf(e), 0);
+        const audioMs = opts.durations?.[i] ?? s.audioDurationMs ?? null;
+        let factor = 1;
+        if (audioMs && drawMs > 0 && audioMs > drawMs)
+            factor = Math.min(audioMs / drawMs, maxStretch);
+        for (const e of els)
+            factorById.set(e.id, factor);
+        return { step: s.step, drawMs, audioMs, factor };
+    });
+    const out = skeletons.map((e) => {
+        const f = factorById.get(e.id) ?? 1;
+        return f === 1 ? e : { ...e, animateDuration: Math.round(durationOf(e) * f) };
+    });
+    return { skeletons: out, info };
+}

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/runtime.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/runtime.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>;