cotutor 0.2.0 → 0.4.0

package/dist/app/http/parent-look.js

@@ -0,0 +1,151 @@
+/**
+ * 家长端「样子与声音」(家长端首页点一位老师的那一行):头像、说话的声音(嘴,全部 56 个)、点读的声音(卡的配音,全部 597 个),点了就存。
+ * 声音全给,页面上点「换一个」开弹窗挑:搜、按男女 / 口音 / 中英 / 年纪 / 场景筛;现在用的排最前、出厂的那个标出来。头像与声音只在这里改(工作台不重复);别的头像直接写 cotutor.json。
+ *
+ *   GET  /api/parent/tutors/<老师>/look                          现在用的与可选的(头像、嘴、卡的配音)
+ *   PUT  /api/parent/tutors/<老师>/look                          {avatar?: string | null, mouth?: string, voice?: string};回 GET 那份
+ *   GET  /api/parent/tutors/<老师>/look/avatar?k=factory|image   选项里那两张图:包里的出厂头像、workspace 里 figshot 画的
+ *   GET  /api/parent/tutors/<老师>/look/preview?kind=mouth|card&voice=…   试听,念的句子服务端定(./voice-preview.ts,有缓存)
+ *
+ * 头像只收选项里的值(不让页面往 cotutor.json 写任意路径);avatar null = 用出厂的(三门主科是木钉娃娃,别的显示学科首字)。
+ * 挑回出厂的那个声音就删掉那一项,cotutor.json 里不留和缺省一样的值。
+ */
+import { existsSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { REALTIME_VOICES, isRealtimeVoice } from "../../realtime/voices.js";
+import { TTS_VOICES } from "../../media/tts.js";
+import { SHIPPED_CARD_VOICES, SHIPPED_MOUTHS, canonicalSubject, cardVoice, mouthVoice } from "../../schema/index.js";
+import { patchConfig } from "../workspace.js";
+import { ownAvatar, subjectAvatarFile } from "./avatars.js";
+import { cardPreview, mouthPreview } from "./voice-preview.js";
+/** 不放 📚 🧮 🔤:旧版 init 写的出厂 emoji,当作没写(avatars.ts) */
+const EMOJI = ['📖', '✏️', '🌱', '🦉', '🐼', '⭐'];
+const IMAGE_RE = /\.(png|jpe?g|webp)$/i;
+/** 试听念的句子:学科的口吻 */
+const MOUTH_SAMPLE = { 语文: '你好呀,今天我们读哪一课?', 数学: '你好呀,今天想算点什么?', 英语: 'Hello! 今天我们学哪几个单词?' };
+const CARD_SAMPLE = { 语文: '小蝌蚪找妈妈', 数学: '二十八加十五等于四十三', 英语: 'apple, banana, orange' };
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const bad = (message) => ({ status: 400, json: { error: 'bad_request', message } });
+/** 现在用的排最前,出厂的其次,别的照表里的先后 */
+const ranked = (all, current, shipped) => {
+    const rank = (v) => (v.voice === current ? 0 : v.voice === shipped ? 1 : 2);
+    return [...all].sort((a, b) => rank(a) - rank(b));
+};
+/** 表里十几种「某某型客服」并成一个场景,筛的时候不占一排 */
+const sceneOf = (scene) => (scene.endsWith('客服') ? '客服' : scene);
+function mouthOptions(c, name) {
+    const current = mouthVoice(c.live, name);
+    const known = REALTIME_VOICES.some((v) => v.voice === current) ? [] : [{ voice: current, name: current, gender: '', trait: '', lang: '普通话' }];
+    return ranked([...known, ...REALTIME_VOICES], current, SHIPPED_MOUTHS[name]).map((v) => {
+        // 表里的「(缺省)」是说 realtime 模型自己的缺省,家长用不着;「;中英夹着说……」拆成 warn
+        const [trait, extra = ''] = v.trait.replace(/\(缺省\)$/, '').split(';');
+        return { voice: v.voice, name: v.name, gender: v.gender, lang: v.lang, trait, ...(extra.includes('英文腔') ? { warn: '中英夹着说带英文腔' } : {}), shipped: SHIPPED_MOUTHS[name] === v.voice };
+    });
+}
+function cardOptions(c, name) {
+    const current = cardVoice(c.tutors, name);
+    const known = !current || TTS_VOICES.some((v) => v.voice === current) ? [] : [{ voice: current, name: current, gender: '', age: 0, trait: '', scene: '', lang: '中文' }];
+    return ranked([...known, ...TTS_VOICES], current, SHIPPED_CARD_VOICES[name]).map((v) => ({
+        voice: v.voice, name: v.name, gender: v.gender === '女' || v.gender === '男' ? v.gender : '', lang: v.lang, trait: v.trait,
+        ...(v.age ? { age: v.age } : {}), ...(v.scene ? { scene: sceneOf(v.scene) } : {}), shipped: SHIPPED_CARD_VOICES[name] === v.voice,
+    }));
+}
+/** figshot 画的图:现在用着的那张,或 workspace 里 avatars/<老师>.png 之类(换回别的以后还能选回来) */
+function imageAvatar(ctx, name) {
+    const own = ownAvatar(ctx.ws.config.tutors[name]);
+    if (own && IMAGE_RE.test(own))
+        return own;
+    for (const ext of ['png', 'webp', 'jpg'])
+        if (existsSync(join(ctx.ws.root, 'avatars', `${name}.${ext}`)))
+            return `avatars/${name}.${ext}`;
+    return null;
+}
+function avatarOptions(ctx, name) {
+    const t = ctx.ws.config.tutors[name];
+    const base = `/api/parent/tutors/${name}/look/avatar`;
+    const out = [];
+    if (subjectAvatarFile(t.subject))
+        out.push({ value: null, label: '木钉娃娃', img: `${base}?k=factory` });
+    const img = imageAvatar(ctx, name);
+    if (img)
+        out.push({ value: img, label: 'figshot 画的', img: `${base}?k=image` });
+    const ch = (t.subject || t.display || '?').slice(0, 1);
+    out.push({ value: ch, label: '学科字', text: ch });
+    for (const e of EMOJI)
+        out.push({ value: e, label: '', text: e });
+    return out;
+}
+function look(ctx, name) {
+    const c = ctx.ws.config;
+    const t = c.tutors[name];
+    const own = ownAvatar(t);
+    return {
+        tutor: { name, display: t.display },
+        // 没写的、写的值不在选项里(cotutor.json 里手填的)都照实给,页面只是哪格都不亮
+        avatar: { current: own, options: avatarOptions(ctx, name) },
+        mouth: { current: mouthVoice(c.live, name), options: mouthOptions(c, name) },
+        card: { current: cardVoice(c.tutors, name) ?? null, options: cardOptions(c, name) },
+    };
+}
+export async function parentLookRoute(method, p, url, ctx, body) {
+    const m = /^\/api\/parent\/tutors\/([a-z0-9][a-z0-9-]*)\/look(?:\/(avatar|preview))?$/.exec(p);
+    if (!m)
+        return null;
+    const [, name, sub] = m;
+    const t = ctx.ws.config.tutors[name];
+    if (!t || !name.endsWith('-tutor'))
+        return { status: 404, json: { error: 'no_such_tutor' } };
+    const subject = canonicalSubject(t.subject) ?? '';
+    if (sub === 'avatar') {
+        if (method !== 'GET')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        if (url.searchParams.get('k') === 'factory') {
+            const file = subjectAvatarFile(t.subject);
+            return file ? { status: 200, file, contentType: 'image/webp', cacheControl: 'max-age=86400' } : { status: 404, json: { error: 'not_found' } };
+        }
+        const rel = imageAvatar(ctx, name);
+        const file = rel ? resolve(ctx.ws.root, rel) : '';
+        if (!rel || !file.startsWith(ctx.ws.root + sep) || !existsSync(file))
+            return { status: 404, json: { error: 'not_found' } };
+        const ext = (IMAGE_RE.exec(rel)?.[1] ?? '').toLowerCase();
+        return { status: 200, file, contentType: ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg', cacheControl: 'no-cache' };
+    }
+    if (sub === 'preview') {
+        if (method !== 'GET')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        const voice = url.searchParams.get('voice')?.trim() ?? '';
+        return url.searchParams.get('kind') === 'card' ? cardPreview(ctx.ws, voice, CARD_SAMPLE[subject] ?? CARD_SAMPLE.语文) : mouthPreview(ctx.ws, voice, MOUTH_SAMPLE[subject] ?? MOUTH_SAMPLE.语文);
+    }
+    if (method === 'GET')
+        return { status: 200, json: look(ctx, name) };
+    if (method !== 'PUT')
+        return { status: 405, json: { error: 'method_not_allowed' } };
+    if (!isObj(body))
+        return bad('要 {avatar?, mouth?, voice?}');
+    const tutor = {};
+    const patch = { tutors: { [name]: tutor } };
+    if ('avatar' in body) {
+        const ok = avatarOptions(ctx, name).some((o) => o.value === body.avatar);
+        if (!ok)
+            return bad('头像只能从给的几个里挑;别的(图片路径、别的 emoji)直接写 cotutor.json');
+        tutor.avatar = body.avatar;
+    }
+    if (body.mouth !== undefined) {
+        if (typeof body.mouth !== 'string' || !isRealtimeVoice(body.mouth))
+            return bad(`说话的声音不认「${String(body.mouth)}」`);
+        patch.live = { voices: { [name]: body.mouth === SHIPPED_MOUTHS[name] ? null : body.mouth } };
+    }
+    if (body.voice !== undefined) {
+        if (typeof body.voice !== 'string' || !TTS_VOICES.some((v) => v.voice === body.voice))
+            return bad(`点读的声音不认「${String(body.voice)}」`);
+        tutor.voice = body.voice === SHIPPED_CARD_VOICES[name] ? null : body.voice;
+    }
+    try {
+        await patchConfig(ctx.ws, patch);
+    }
+    catch (err) {
+        return bad(err instanceof Error ? err.message : String(err));
+    }
+    await ctx.reload();
+    return { status: 200, json: look(ctx, name) };
+}

package/dist/app/http/range.d.ts

@@ -0,0 +1,9 @@
+/**
+ * HTTP 分段取(Range,RFC 9110 §14):iPad Safari 放视频一定先要 bytes=0-1,拿不到 206 就不放(小课堂的视频)。
+ * 只认单段 `bytes=a-b` / `bytes=a-` / `bytes=-n`;多段、写坏的、b < a 的当没给(回整份 200,规范允许);起点越过文件尾 → 416。
+ */
+export type ByteRange = {
+    start: number;
+    end: number;
+} | 'unsatisfiable' | null;
+export declare function parseRange(header: string | undefined, size: number): ByteRange;

package/dist/app/http/range.js

@@ -0,0 +1,19 @@
+export function parseRange(header, size) {
+    if (!header)
+        return null;
+    const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!m || (m[1] === '' && m[2] === ''))
+        return null;
+    if (m[1] === '') {
+        // 末尾 n 字节
+        const n = Number(m[2]);
+        if (n === 0 || size === 0)
+            return 'unsatisfiable';
+        return { start: Math.max(0, size - n), end: size - 1 };
+    }
+    const start = Number(m[1]);
+    if (start >= size)
+        return 'unsatisfiable';
+    const end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1);
+    return end < start ? null : { start, end };
+}

package/dist/app/http/raw-view.d.ts

@@ -0,0 +1,117 @@
+import { type BoardWarning, type SourceRow } from '../../board/parse.ts';
+import type { BoardSection } from '../../board/presentation.ts';
+import { type ToolCall, type TranscriptRow } from '../../brain/transcript.ts';
+import { type ToolKind } from '../../brain/index.ts';
+import { type ConversationMessage } from '../../schema/index.ts';
+import type { Workspace } from '../../schema/index.ts';
+import { type RunSources } from '../../runtime/journal/store.ts';
+import { type TimelineSpan } from '../../runtime/journal/events.ts';
+import { type RunEvent } from '../../schema/index.ts';
+export interface RawStation {
+    id: 'pack' | 'timeline' | 'source' | 'parse' | 'kid' | 'tools' | 'trace' | 'ledger';
+    title: string;
+    /** 体量那行小字 */
+    note: string;
+    state: 'ok' | 'warn' | 'none';
+}
+export interface DiffRow {
+    s: '+' | '-' | '·';
+    text: string;
+}
+export interface RawKidLine {
+    text: string;
+    /** 按 replyMaxChars 截掉的尾巴(孩子看不到、也不念);没截就是空串 */
+    cut: string;
+}
+export interface RawCard {
+    n: number;
+    kind: string;
+    label: string;
+    /** 孩子在这张卡上做的(describeCard 出的那句);没动过 = null */
+    state: string | null;
+    /** 已生成的资产(点读段 mp3) */
+    assets: string[];
+    /** 下发给孩子的 props(答案已剥) */
+    props: Record<string, unknown>;
+}
+export interface RawView {
+    tutor: string;
+    date: string;
+    job: string;
+    thread: string | null;
+    at: string;
+    from: string;
+    text: string;
+    result: string;
+    runtime: string | null;
+    tokens: ConversationMessage['tokens'] | null;
+    timing: ConversationMessage['timing'] | null;
+    error: string | null;
+    stations: RawStation[];
+    /** 发出去的:上下文包 + 完整命令行(老 workspace 没落过就是 null) */
+    pack: {
+        prompt: string;
+        argv: string[];
+        runtime: string;
+        resume: boolean;
+        session: string | null;
+        agentBody: boolean;
+        sources: RunSources | null;
+    } | null;
+    /** 老师原文(= 解析器真正吃的那一份)+ 逐行注解 */
+    source: {
+        text: string;
+        rows: SourceRow[];
+        warnings: BoardWarning[];
+    };
+    /** 顶层文本块里没进板书正文的那些(「我先看看账本」之类) */
+    dropped: string[];
+    /** 索引里存着的(当时那版解析器的结果) */
+    stored: {
+        section: BoardSection | null;
+        warnings: string[];
+        kidText: string | null;
+        parentText: string;
+    };
+    /** 拿当前解析器重解一遍 + 与 stored 的差异 */
+    fresh: {
+        section: BoardSection;
+        warnings: BoardWarning[];
+        diff: DiffRow[];
+        same: boolean;
+    };
+    kid: {
+        lines: RawKidLine[];
+        cards: RawCard[];
+    };
+    /** 转录(工具行、子代理),与家长视图同一套折叠 */
+    trace: TranscriptRow[];
+    /** 这轮用了哪些工具、读了什么(索引物化的;老轮次从 .log 现抽);kind 是工具的类别(src/brain/cli/,页面按它认「读了几个文件」,不比工具名) */
+    tools: (ToolCall & {
+        kind: ToolKind;
+    })[];
+    /** 时间线:这轮的事件(<日期>.<job>.events.jsonl;2026-09-13 之前的轮次没有 → 空)+ 甘特的段 + 控制台那种一行一条 */
+    events: RunEvent[];
+    /** from = 最早一条的 t(嘴这一道在老师进程起来之前,负的;没有就是 0);total = 最晚一条 */
+    timeline: {
+        spans: TimelineSpan[];
+        lines: string[];
+        total: number;
+        from: number;
+    };
+    device: string | null;
+    /** stderr 尾巴 */
+    err: string;
+    files: {
+        log: string;
+        run: string | null;
+    };
+}
+/** 卡与讲稿逐条比:同序对齐,不同就一减一加。给「改完解析器,老样本会不会变」用 */
+export declare function diffSections(stored: BoardSection | null, fresh: BoardSection): DiffRow[];
+export declare function rawView(ws: Workspace, tutor: string, date: string, job: string): Promise<RawView | null>;
+/** 「存成 fixture」:原文原样一份,文件名按 job;家长端下载,开发者放进 tests/fixtures/board/ */
+export declare function fixtureOf(view: RawView): {
+    name: string;
+    text: string;
+};

package/dist/app/http/raw-view.js

@@ -0,0 +1,149 @@
+/**
+ * 家长端「看原文」的一轮全景(2026-09-11):把一次运行拆成几站,一个接口给全。
+ * 调试时要回答的不是「老师写了什么」,而是「这一层是谁吃掉的」——孩子没看见那张卡,可能是老师没写、
+ * 可能 kidSource 没挑中那一段、可能 parseBoard 没认出那个标签、也可能 stripSecrets 剥过头。
+ * 每站的数据都从盘上现读现算,不进索引:原文在 .log,发出去的在 .run.json,卡的状态与资产在 .cards/。讲稿不配音,「配音」那站跟着删了,卡的资产在「下发给孩子」里。
+ * 「重解」= 拿当前解析器再跑一遍原文与索引里存的比 —— 索引是物化的,改完解析器老样本会不会变,只有这样才知道。
+ */
+import { readFile } from 'node:fs/promises';
+import { cardLabel, describeCard, stripSecrets } from "../../board/cards/index.js";
+import { annotateSource } from "../../board/parse.js";
+import { conversationFiles } from "../../schema/index.js";
+import { kidSource, truncateReply } from "../../runtime/kid-view.js";
+import { foldRuns, toolCalls } from "../../brain/transcript.js";
+import { parseLogLine, toolKind } from "../../brain/index.js";
+import { resolvePolicy } from "../../schema/index.js";
+import { readErrLog, readIndex, readRunFile, readTranscript, scanCards } from "../../runtime/journal/store.js";
+import { formatEvent, parseEvents, timelineSpans } from "../../runtime/journal/events.js";
+import {} from "../../schema/index.js";
+const cardOneLine = (c) => `${c.kind} ${cardLabel(c)}`.trim();
+/** 卡与讲稿逐条比:同序对齐,不同就一减一加。给「改完解析器,老样本会不会变」用 */
+export function diffSections(stored, fresh) {
+    const rows = [];
+    const a = stored?.cards ?? [];
+    const b = fresh.cards;
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i];
+        const y = b[i];
+        const label = (c) => `卡 ${i + 1}　${cardOneLine(c)}`;
+        if (!x && y)
+            rows.push({ s: '+', text: label(y) });
+        else if (x && !y)
+            rows.push({ s: '-', text: label(x) });
+        else if (x && y && (x.kind !== y.kind || JSON.stringify(x.props) !== JSON.stringify(y.props))) {
+            rows.push({ s: '-', text: label(x) });
+            rows.push({ s: '+', text: label(y) });
+        }
+        else if (x)
+            rows.push({ s: '·', text: label(x) });
+    }
+    const la = stored?.lines ?? [];
+    const lb = fresh.lines;
+    for (let i = 0; i < Math.max(la.length, lb.length); i++) {
+        const x = la[i];
+        const y = lb[i];
+        if (!x && y)
+            rows.push({ s: '+', text: `讲稿 ${i + 1}　${y.text}` });
+        else if (x && !y)
+            rows.push({ s: '-', text: `讲稿 ${i + 1}　${x.text}` });
+        else if (x && y && x.text !== y.text) {
+            rows.push({ s: '-', text: `讲稿 ${i + 1}　${x.text}` });
+            rows.push({ s: '+', text: `讲稿 ${i + 1}　${y.text}` });
+        }
+    }
+    return rows;
+}
+const secs = (ms) => (ms === undefined ? '' : ms < 10000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms / 1000)}s`);
+export async function rawView(ws, tutor, date, job) {
+    const index = await readIndex(ws, tutor, date);
+    const m = index.messages.find((x) => x.job === job);
+    if (!m)
+        return null;
+    const files = conversationFiles(ws.dirs.conversations, tutor, date);
+    const policy = resolvePolicy(ws.config, tutor);
+    const transcript = await readTranscript(ws, tutor, date, job);
+    const pack = await readRunFile(ws, tutor, date, job);
+    const blocks = (transcript?.items ?? []).filter((i) => i.kind === 'text' && !i.sub).map((i) => i.text.trim());
+    const src = (transcript ? kidSource(transcript) : null) ?? '';
+    const dropped = blocks.filter((b) => b && !src.includes(b));
+    const ann = annotateSource(src, { live: m.live });
+    const stored = m.section ?? null;
+    // 索引里的讲稿已经按 replyMaxChars 截过,重解的还没有——比之前先截,免得每句都报「不同」
+    const freshCut = { ...ann.section, lines: ann.section.lines.map((l) => ({ ...l, text: truncateReply(l.text, policy.replyMaxChars).text })) };
+    const diff = diffSections(stored, freshCut);
+    const same = diff.every((d) => d.s === '·');
+    // 下发给孩子那一份:讲稿按 replyMaxChars 截、卡剥完答案是什么样、卡的资产
+    const shown = stripSecrets(ann.section);
+    const { states, assets } = await scanCards(ws, tutor, date);
+    const jobStates = states[job] ?? {};
+    // 发出去的是索引里那一份(这轮真下发的);被 replyMaxChars 截掉的尾巴拿没截过的原句比出来
+    const lines = [];
+    for (const [i, l] of (stored?.lines ?? freshCut.lines).entries()) {
+        const full = ann.section.lines[i]?.text ?? l.text;
+        const head = l.text.replace(/…$/, '');
+        lines.push({ text: l.text, cut: full.length > l.text.length && full.startsWith(head) ? full.slice(head.length) : '' });
+    }
+    const cards = (stored?.cards ?? ann.section.cards).map((c, n) => ({
+        n,
+        kind: c.kind,
+        label: cardLabel(c),
+        state: jobStates[n] ? describeCard(c, jobStates[n].state) : null,
+        assets: assets[job]?.[n] ?? [],
+        props: (shown.cards[n]?.props ?? c.props),
+    }));
+    const err = await readErrLog(ws, tutor, date, job);
+    // 读了什么:索引里物化过的优先(和当时一致),没有(老轮次)就从 .log 现抽
+    const tools = (m.tools ?? toolCalls(await readFile(files.log(job), 'utf8').catch(() => ''), parseLogLine)).map((t) => ({ ...t, kind: toolKind(t.name) }));
+    const toolFiles = new Set(tools.filter((t) => t.kind === 'read' && t.arg).map((t) => t.arg)).size;
+    const toolFailed = tools.filter((t) => t.ok === false).length;
+    const events = parseEvents(await readFile(files.events(job), 'utf8').catch(() => ''));
+    const warnCount = ann.warnings.length + (m.warnings?.length ?? 0);
+    // 实时的轮:松手(或发出)到嘴接住开始放、到第一句开始放(嘴这一道的事件)
+    const rel = events.find((e) => e.lane === 'mouth' && e.kind === 'release');
+    const caughtEv = events.find((e) => e.lane === 'mouth' && e.kind === 'catch');
+    const read0 = events.find((e) => e.lane === 'mouth' && e.kind === 'read');
+    const mouthNote = rel ? `${caughtEv ? ` · 松手到接住 ${secs(caughtEv.t - rel.t)}` : ''}${read0 ? ` · 松手到第一句 ${secs(read0.t - rel.t)}` : ''}` : '';
+    const stations = [
+        { id: 'pack', title: '上下文包', note: pack ? `${pack.prompt.length} 字 · ${pack.resume ? 'resume' : '新开'}` : '这一轮没落(老 workspace)', state: pack ? 'ok' : 'none' },
+        { id: 'timeline', title: '时间线', note: events.length ? `${events.length} 条事件${mouthNote}${m.timing?.firstReadyMs !== undefined ? ` · 首句就绪 ${secs(m.timing.firstReadyMs)}` : ''}${m.timing?.doneMs !== undefined ? ` · 老师写完 ${secs(m.timing.doneMs)}` : ''}` : '这轮没有事件(2026-09-13 之前的轮次)', state: events.length ? (events.some((e) => (e.lane === 'tts' && e.kind === 'failed') || (e.lane === 'main' && e.kind === 'exit' && !e.ok)) ? 'warn' : 'ok') : 'none' },
+        { id: 'source', title: '老师原文', note: `${src ? src.split('\n').length : 0} 行 · 顶层 ${blocks.length} 段${dropped.length ? ` · 丢 ${dropped.length} 段` : ''}`, state: src ? 'ok' : 'none' },
+        { id: 'parse', title: '解析结果', note: `${ann.section.cards.length} 卡 · ${ann.section.lines.length} 句${warnCount ? ` · ${warnCount} 提醒` : ''}${same ? '' : ' · 与索引不同'}`, state: warnCount || !same ? 'warn' : 'ok' },
+        { id: 'kid', title: '下发给孩子', note: `${lines.length} 句${lines.some((l) => l.cut) ? ` · 截了 ${lines.filter((l) => l.cut).length} 句` : ''} · ${cards.length} 卡`, state: lines.length || cards.length ? 'ok' : 'none' },
+        { id: 'tools', title: '读了什么', note: tools.length ? `${tools.length} 次工具${toolFiles ? ` · 读了 ${toolFiles} 个文件` : ''}${toolFailed ? ` · ${toolFailed} 次失败` : ''}${tools.some((t) => t.sub) ? ' · 有子代理' : ''}` : '没用工具(只凭上下文包答的)', state: toolFailed ? 'warn' : tools.length ? 'ok' : 'none' },
+        { id: 'trace', title: '转录与报错', note: `${transcript?.items.length ?? 0} 条${err ? ' · stderr 有东西' : ''}`, state: m.result === 'error' || err ? 'warn' : 'ok' },
+    ];
+    if (m.artifacts.length)
+        stations.push({ id: 'ledger', title: '账本', note: `产物 ${m.artifacts.join('、')}`, state: 'ok' });
+    return {
+        tutor,
+        date,
+        job,
+        thread: m.thread ?? null,
+        at: m.at,
+        from: m.from,
+        text: m.text,
+        result: m.result,
+        runtime: m.runtime ?? null,
+        tokens: m.tokens ?? null,
+        timing: m.timing ?? null,
+        error: m.error ?? null,
+        stations,
+        pack: pack ? { prompt: pack.prompt, argv: pack.argv, runtime: pack.runtime, resume: pack.resume, session: pack.session, agentBody: pack.agentBody, sources: pack.sources ?? null } : null,
+        source: { text: src, rows: ann.rows, warnings: ann.warnings },
+        dropped,
+        stored: { section: stored, warnings: m.warnings ?? [], kidText: m.kidText ?? null, parentText: m.parentText ?? '' },
+        fresh: { section: ann.section, warnings: ann.warnings, diff, same },
+        kid: { lines, cards },
+        trace: foldRuns(transcript?.items ?? []),
+        tools,
+        err: err.slice(-4000),
+        events,
+        timeline: { spans: timelineSpans(events), lines: events.map(formatEvent), total: Math.max(1, ...events.map((e) => e.t)), from: Math.min(0, ...events.map((e) => e.t)) },
+        device: m.device ?? null,
+        files: { log: `${date}.${job}.log`, run: pack ? `${date}.${job}.run.json` : null },
+    };
+}
+/** 「存成 fixture」:原文原样一份,文件名按 job;家长端下载,开发者放进 tests/fixtures/board/ */
+export function fixtureOf(view) {
+    return { name: `${view.tutor}-${view.date}-${view.job}.md`, text: view.source.text.endsWith('\n') ? view.source.text : `${view.source.text}\n` };
+}

package/dist/app/http/send-file.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function sendFile(req: IncomingMessage, res: ServerResponse, r: {
+    status: number;
+    file: string;
+    contentType?: string;
+    cacheControl?: string;
+}): Promise<void>;

package/dist/app/http/send-file.js

@@ -0,0 +1,29 @@
+/**
+ * 把一个文件发出去:不在 404,支持分段取(Range,iPad Safari 放 mp4 非这样不可;视频小课堂拖进度条也靠它)。服务与 mock 共用。
+ */
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { parseRange } from "./range.js";
+export async function sendFile(req, res, r) {
+    const st = await stat(r.file).catch(() => null);
+    if (!st?.isFile()) {
+        res.writeHead(404, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+        res.end(JSON.stringify({ error: 'not_found' }));
+        return;
+    }
+    const head = { 'content-type': r.contentType ?? 'application/octet-stream', 'cache-control': r.cacheControl ?? 'private, max-age=86400', 'accept-ranges': 'bytes' };
+    const range = r.status === 200 ? parseRange(req.headers.range, st.size) : null;
+    if (range === 'unsatisfiable') {
+        res.writeHead(416, { ...head, 'content-range': `bytes */${st.size}` });
+        res.end();
+        return;
+    }
+    const start = range ? range.start : 0;
+    const end = range ? range.end : st.size - 1;
+    res.writeHead(range ? 206 : r.status, { ...head, 'content-length': String(st.size ? end - start + 1 : 0), ...(range ? { 'content-range': `bytes ${start}-${end}/${st.size}` } : {}) });
+    if (req.method === 'HEAD' || !st.size) {
+        res.end();
+        return;
+    }
+    createReadStream(r.file, { start, end }).on('error', () => res.end()).pipe(res);
+}

package/dist/{server → app/http}/stage.d.ts

@@ -1,4 +1,6 @@
 export declare const STAGE_DIR: string;
+/** 字体目录:舞台包里带了(dist/stage/fonts/)就用它,运行时不要 excalidraw 这个包;没带从 excalidraw 包里取 */
+export declare function fontsDir(stageDir?: string): string;
 export declare const FONTS_DIR: string;
 export declare const MIME: Record<string, string>;
 export declare const ext: (p: string) => string;
@@ -9,6 +11,13 @@ export interface StaticFile {
 }
 /** 根目录以内的一个文件(越界、不存在、不是文件 → null) */
 export declare function fileUnder(root: string, rel: string): Promise<StaticFile | null>;
+/**
+ * 舞台包的版本:stage.js 的改动时间(打包一次变一次)。拼进孩子端 iframe 的地址与 index.html 里的 stage.js / stage.css:
+ * 舞台包的文件缓存一天,名字又不变,不带版本的话 iPad 上更新后一整天还在跑旧的舞台(2026-10-06 修了的毛病真机上还在)
+ */
+export declare function stageVersion(): Promise<string>;
+/** /stage/ 的 index.html,stage.js / stage.css 带上版本;调用方当 html 发(不缓存)。没打包 → null */
+export declare function stageIndex(): Promise<string | null>;
 /** /stage/ → index.html;/stage/stage.js|css;/stage/fonts/<路径> → excalidraw 的字体目录 */
 export declare function stageAsset(pathname: string): Promise<StaticFile | null>;
 /** 课包文件 /api/bundles/<id>/<路径> → <bundles>/<id>/<路径>(id 只认小写字母数字连字符) */

package/dist/{server → app/http}/stage.js

@@ -1,15 +1,17 @@
 /**
- * 舞台包的静态文件:dist/stage/(esbuild 打的 stage.js / stage.css / index.html)+ /stage/fonts/(excalidraw 的字体,从 node_modules 现取,不进 npm 包)。
+ * 舞台包的静态文件:dist/stage/(esbuild 打的 stage.js / stage.css / index.html)+ /stage/fonts/(excalidraw 的字体:dist/stage/fonts/ 在就给它,
+ * 不在从 node_modules 现取;部署包把字体拷进 dist/stage/fonts/、去掉 excalidraw 依赖,见 docs/wip/deploy/)。
  * serve 与 mock 共用;没打包(开发时没跑 pnpm run build:stage)→ null,页面开重卡舞台时什么都不出现,doctor 点名。
  */
 import { existsSync } from 'node:fs';
-import { stat } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-export const STAGE_DIR = fileURLToPath(new URL('../../dist/stage/', import.meta.url));
+import { KID_LOG_JS } from "../../ui/kid/kid-log.js";
+export const STAGE_DIR = fileURLToPath(new URL('../../../dist/stage/', import.meta.url));
 /**
- * excalidraw 的字体目录(dist/prod/fonts/):从包入口现解析,不写死 `../../node_modules/`——
+ * excalidraw 的字体目录(dist/prod/fonts/):从包入口现解析,不写死 `../../../node_modules/`——
  * npm 扁平安装时依赖在消费者的 node_modules 里,不在本包下,写死的话装出来的 /stage/fonts/ 全 404。
  */
 function excalidrawFontsDir() {
@@ -17,10 +19,15 @@ function excalidrawFontsDir() {
         return join(dirname(createRequire(import.meta.url).resolve('@excalidraw/excalidraw')), 'fonts') + sep;
     }
     catch {
-        return fileURLToPath(new URL('../../node_modules/@excalidraw/excalidraw/dist/prod/fonts/', import.meta.url));
+        return fileURLToPath(new URL('../../../node_modules/@excalidraw/excalidraw/dist/prod/fonts/', import.meta.url));
     }
 }
-export const FONTS_DIR = excalidrawFontsDir();
+/** 字体目录:舞台包里带了(dist/stage/fonts/)就用它,运行时不要 excalidraw 这个包;没带从 excalidraw 包里取 */
+export function fontsDir(stageDir = STAGE_DIR) {
+    const bundled = join(stageDir, 'fonts') + sep;
+    return existsSync(bundled) ? bundled : excalidrawFontsDir();
+}
+export const FONTS_DIR = fontsDir();
 export const MIME = {
     html: 'text/html; charset=utf-8',
     js: 'text/javascript; charset=utf-8',
@@ -29,6 +36,9 @@ export const MIME = {
     mp3: 'audio/mpeg',
     wav: 'audio/wav',
     png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
     svg: 'image/svg+xml',
     woff2: 'font/woff2',
     woff: 'font/woff',
@@ -51,6 +61,24 @@ export async function fileUnder(root, rel) {
         return null;
     return { file, contentType: type };
 }
+/**
+ * 舞台包的版本:stage.js 的改动时间(打包一次变一次)。拼进孩子端 iframe 的地址与 index.html 里的 stage.js / stage.css:
+ * 舞台包的文件缓存一天,名字又不变,不带版本的话 iPad 上更新后一整天还在跑旧的舞台(2026-10-06 修了的毛病真机上还在)
+ */
+export async function stageVersion() {
+    const st = await stat(join(STAGE_DIR, 'stage.js')).catch(() => null);
+    return st ? Math.round(st.mtimeMs).toString(36) : '0';
+}
+/** /stage/ 的 index.html,stage.js / stage.css 带上版本;调用方当 html 发(不缓存)。没打包 → null */
+export async function stageIndex() {
+    const html = await readFile(join(STAGE_DIR, 'index.html'), 'utf8').catch(() => null);
+    if (html === null)
+        return null;
+    const v = await stageVersion();
+    // 舞台开在 iframe 里,自己装孩子端流水的出错监听(kid-log.ts):只记出错,不报打开
+    const log = `<script>${KID_LOG_JS}  kidLog.start({ page: 'stage', mode: 'stage', v: '${v}' });\n</script>\n`;
+    return html.replace('<script', () => `${log}<script`).replace('/stage/stage.js', `/stage/stage.js?v=${v}`).replace('/stage/stage.css', `/stage/stage.css?v=${v}`);
+}
 /** /stage/ → index.html;/stage/stage.js|css;/stage/fonts/<路径> → excalidraw 的字体目录 */
 export async function stageAsset(pathname) {
     if (!pathname.startsWith('/stage/'))

package/dist/app/http/theme.d.ts

@@ -0,0 +1,13 @@
+import { type ThemeManifest } from '../../schema/index.ts';
+export interface ThemeFiles {
+    css: string;
+    manifest: ThemeManifest;
+    /** 用的是哪份:workspace 里的,还是退回了包里的出厂件(读不到 / 坏了) */
+    source: 'workspace' | 'fallback';
+    /** 退回时的原因 */
+    error?: string;
+}
+/** workspace 根 + 主题名 → css 与清单;缓存按两个文件的 mtime */
+export declare function themeFiles(root: string, name: string): Promise<ThemeFiles>;
+/** 测试用:清缓存 */
+export declare function resetThemeCache(): void;

package/dist/app/http/theme.js

@@ -0,0 +1,41 @@
+/**
+ * 孩子端的主题文件:/kid/theme.css 与 /kid/theme.json,按 cotutor.json 的 kid.theme 从 workspace 的 themes/<name>/ 现读(mtime 缓存,热的)。
+ * 主题读不到或坏了 → 退回包里的出厂 default(孩子端永远有样子;坏在哪 doctor 说);mock 直接给出厂的。
+ * 舞台包(iframe)也 link 同一份 css,变量两边一致。
+ */
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { THEME_CSS_FILE, THEME_MANIFEST_FILE } from "../../schema/index.js";
+import { packageTheme, readTheme, themeDir } from "../cli/themes.js";
+import { cardsCss } from "../../board/cards/docs.js";
+let cache = null;
+async function mtimeKey(dir) {
+    const a = await stat(join(dir, THEME_MANIFEST_FILE)).catch(() => null);
+    const b = await stat(join(dir, THEME_CSS_FILE)).catch(() => null);
+    return `${dir}|${a?.mtimeMs ?? 'x'}|${b?.mtimeMs ?? 'x'}`;
+}
+/** workspace 根 + 主题名 → css 与清单;缓存按两个文件的 mtime */
+export async function themeFiles(root, name) {
+    const dir = themeDir(root, name);
+    const key = await mtimeKey(dir);
+    if (cache && cache.key === key)
+        return cache;
+    let loaded;
+    let source = 'workspace';
+    let error;
+    try {
+        loaded = await readTheme(dir);
+    }
+    catch (err) {
+        loaded = await packageTheme('default');
+        source = 'fallback';
+        error = err instanceof Error ? err.message : String(err);
+    }
+    // 各种卡的结构样式(包里 cards/<kind>/card.css)在前,主题在后:主题写同名选择器就能盖
+    cache = { key, css: `${cardsCss()}\n\n/* ---- 主题 ${name} ---- */\n${loaded.css}`, manifest: loaded.manifest, source, ...(error ? { error } : {}) };
+    return cache;
+}
+/** 测试用:清缓存 */
+export function resetThemeCache() {
+    cache = null;
+}

package/dist/app/http/voice-preview.d.ts

@@ -0,0 +1,4 @@
+import type { Workspace } from '../../schema/index.ts';
+import type { RouteResult } from './app.ts';
+export declare function mouthPreview(ws: Workspace, voice: string, text: string): Promise<RouteResult>;
+export declare function cardPreview(ws: Workspace, voice: string, text: string): Promise<RouteResult>;