cotutor 0.2.0 → 0.4.0

package/dist/app/http/app.js

@@ -0,0 +1,1159 @@
+/**
+ * 服务的路由层:route(method, path, ctx, body) → {status, json|html},测试不用起端口。
+ * R1 的查询接口照旧;R2 加:对话(列日期、看一天的家长视图、发消息)、cotutor.json 补丁(老师团页)、工作台 /dev(2026-09-22 之前叫家长页 /parent;
+ * 现在 /parent 是家长端 = 家长板书页,给不懂技术的家长日常用)。
+ * R3 加:孩子端 `/`(kidPage)与 /api/kid/*(首页:课程表 + 老师卡 + 家长发布的首页卡;对话:服务端过滤后的孩子视图;发消息:from 固定 kid)、配音文件 /api/audio。
+ * 配置热重载:每个请求先读一遍 cotutor.json,原文变了就重读(不比修改时间,Windows 上连写两次常常一样);改坏了留旧配置并把错误挂在 /api/health 上。
+ */
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { foldRuns } from "../../brain/transcript.js";
+import { RuntimeError } from "../../brain/index.js";
+import { PHOTO_MAX_SIDE } from "../../ui/kid/photo-edit.js";
+import { currentThread, lastJobOf, sameRuntime } from "../../runtime/journal/conversation.js";
+import { localDate, weekOf } from "../../shared/time.js";
+import { conversationFiles, threads } from "../../schema/index.js";
+import { kidConversation, kidThreads, submittedCards, parentConversation } from "../../runtime/kid-view.js";
+import { parseEvents } from "../../runtime/journal/events.js";
+import {} from "../../schema/index.js";
+import { NEUTRAL_COLOR, SUBJECT_COLORS, TUTOR_PALETTE, tutorColors } from "../../ui/shared/tutor-color.js";
+import { boardMarkOf } from "../../ui/kid/board-mark.js";
+import { buildReel, playRecordOk, reelCardTook, reelHolds, reelMissRuns } from "../../ui/kid/reel.js";
+import { DATE_RE, FocusSchema, MESSAGE_FROM, listTutors, subjectLang, viaSendsLabel } from "../../schema/index.js";
+import { ConfigError, patchConfig, reloadIfChanged, workspaceReport } from "../workspace.js";
+import { UsageError } from "../../shared/errors.js";
+import { redactHome } from "../../shared/home.js";
+import { tutorStatuses } from "../cli/tutors.js";
+import { configGapsOf, upgradeConfig } from "../cli/migrate.js";
+import { ICON_SIZES, appIconPng, webManifest } from "../../ui/shared/icon.js";
+import { faviconResponse } from "../../ui/shared/favicon.js";
+import { cookieOf, createAccess, gatePage, isKidPath } from "./access.js";
+import { factoryAvatarFile, shownAvatar } from "./avatars.js";
+import { deviceCookie, newDeviceId, parseKidLog, readDevices, recordKidLog, renameDevice, validDevice } from "../../runtime/journal/kid-log.js";
+import { DEVICE_COOKIE } from "../../schema/kid-device.js";
+import { BUILD, codeChanged, headNow, shortCommit } from "../build.js";
+import { qrPage } from "../../ui/parent/qr-page.js";
+import { kidPage } from "../../ui/kid/kid-page.js";
+import { parentPage } from "../../ui/parent/parent-page.js";
+import { kidHomeView } from "../../runtime/home/store.js";
+import { photosOf } from "../../runtime/kid-input.js";
+import { DEV_PAGE } from "../../ui/dev/dev-page.js";
+import { devOverview } from "./dev-overview.js";
+import { ActivityConflict, checkDevActivity, findDevActivity, listDevActivities, readDevActivity, restoreDevActivity, saveDevActivity } from "./dev-activities.js";
+import { checkDevTutorFile, hasDevTutorFile, listDevTutorFiles, readDevTutorFile, restoreDevTutorFile, saveDevTutorFile } from "./dev-tutor-files.js";
+import { doctorWorkspace } from "../cli/doctor.js";
+import { VOICE_GALLERY_PAGE } from "../../ui/dev/voice-gallery-page.js";
+import { BusyError, Runner } from "../../runtime/runner.js";
+import { sendFile } from "./send-file.js";
+import { talkRoute } from "../talk/route.js";
+import { parentHomeRoute } from "./parent-home.js";
+import { parentLookRoute } from "./parent-look.js";
+import { bailianRoute, createBailian } from "../machine/bailian.js";
+import { PARENT_HOME_PAGE } from "../../ui/parent/parent-home-page.js";
+import { PARENT_SETTINGS_PAGE } from "../../ui/parent/parent-settings-page.js";
+import { dictationRoute } from "../dictation/route.js";
+import { IndexError, capturePathOk, deleteThread, listDates, rateThread, readErrLog, readIndex, readTranscript, scanCards, undoVaultWrite, writeCapture, writeCardImage, writeCardState } from "../../runtime/journal/store.js";
+import { memoryLineText } from "../../memory/vault-notes.js";
+import { childItem } from "../../memory/proposals.js";
+import { IMAGE_EXT, parseCardState, stripSecrets } from "../../board/cards/index.js";
+import { isAbsolute, resolve, sep } from 'node:path';
+import { bundleAsset, stageAsset, stageIndex, stageVersion } from "./stage.js";
+import { themeFiles } from "./theme.js";
+import { enrichPaints } from "../../scenes/paint/painter.js";
+import { enrichLectures, inspectLecture, bakeSectionSoon, ensureBaked, lectureFrameSvg, parseRing, parseSvgMs } from "../../runtime/lecture.js";
+import { tianzigeData } from "../../ui/kid/tianzige.js";
+import { lettersData } from "../../ui/kid/letters.js";
+import { fixtureOf, rawView } from "./raw-view.js";
+import { DeviceSchema } from "../../schema/index.js";
+import { CanvasStateSchema } from "../../board/cards/canvas.js";
+import { PAPER_KEY_RE, dropPaper, readPaper, writePaper } from "../../board/paper.js";
+import { addTutorFile, readTutorFile, removeTutorFile, writeTutorFile } from "../cli/tutors.js";
+export function createContext(ws, opts = {}) {
+    let configText = null;
+    const ctx = {
+        ws,
+        runner: new Runner(() => ctx.ws, opts),
+        now: opts.now ?? (() => new Date()),
+        configError: null,
+        listen: null,
+        openCalls: null,
+        access: opts.access ?? createAccess({ now: () => ctx.now() }),
+        bailian: opts.bailian ?? createBailian({ env: opts.env }),
+        async reload() {
+            try {
+                const r = await reloadIfChanged(ctx.ws, configText);
+                ctx.ws = r.ws;
+                configText = r.text;
+                ctx.configError = null;
+            }
+            catch (err) {
+                if (!(err instanceof ConfigError))
+                    throw err;
+                ctx.configError = err.message;
+            }
+        },
+    };
+    return ctx;
+}
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] ?? c);
+export async function dayView(ctx, tutor, date) {
+    const index = await readIndex(ctx.ws, tutor, date);
+    const runs = {};
+    const errors = {};
+    for (const m of index.messages) {
+        const t = await readTranscript(ctx.ws, tutor, date, m.job);
+        runs[m.job] = t ? foldRuns(t.items) : [];
+        if (m.result === 'error') {
+            const tail = (await readErrLog(ctx.ws, tutor, date, m.job)).trim().split('\n').slice(-5).join('\n');
+            if (tail)
+                errors[m.job] = tail;
+        }
+    }
+    const active = ctx.runner.running(tutor);
+    return { index, running: active && active.date === date ? active.job : null, runs, errors };
+}
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+export async function kidTutors(ctx) {
+    const out = [];
+    const colors = tutorColors(ctx.ws.config.tutors);
+    for (const t of listTutors(ctx.ws.config, { kidOnly: true })) {
+        out.push({ name: t.name, display: t.display, avatar: shownAvatar(t), subject: t.subject ?? null, color: colors[t.name], mark: boardMarkOf(t.subject), lang: subjectLang(t.subject), hasVoice: Boolean(t.voice), extras: t.extras.filter((x) => (x !== 'talk' || ctx.ws.config.talk.enabled)), listen: ctx.ws.config.live.listen });
+    }
+    return out;
+}
+export async function kidHome(ctx, now) {
+    const ws = ctx.ws;
+    const date = localDate(now);
+    const view = await kidHomeView(ws, now);
+    const figshot = ws.config.figshot ? { port: ws.config.figshot.port } : null;
+    return { title: ws.config.title, date, tutors: await kidTutors(ctx), home: view.home, cards: view.cards, figshot, hand: ws.config.kid.hand ?? 'right', ready: ctx.bailian.status().ready };
+}
+export async function kidHistory(ctx, tutor, days) {
+    const today = localDate(ctx.now());
+    const floor = localDate(new Date(ctx.now().getTime() - (days - 1) * 86400000));
+    const dates = (await listDates(ctx.ws, tutor)).filter((d) => d >= floor && d <= today).sort().reverse();
+    const out = [];
+    for (const date of dates) {
+        const index = await readIndex(ctx.ws, tutor, date);
+        const list = kidThreads(kidConversation(index)).reverse();
+        if (list.length)
+            out.push({ date, threads: list });
+    }
+    return { tutor, today, days: out };
+}
+export async function kidDay(ctx, tutor, date) {
+    const index = await readIndex(ctx.ws, tutor, date);
+    const active = ctx.runner.running(tutor);
+    const { states, assets } = await scanCards(ctx.ws, tutor, date);
+    const messages = kidConversation(index, states, assets);
+    // 流式:正在回的那条带上已经出来的板书(partial),卡随围栏闭合逐张出现;答案照样剥
+    const partial = active && active.date === date ? ctx.runner.partial(tutor) : null;
+    if (partial) {
+        const m = messages.find((x) => x.job === active.job);
+        if (m)
+            m.section = stripSecrets(partial);
+    }
+    // 小课堂卡:课读不读得出、那一段的起止,每次现读
+    for (const m of messages)
+        if (m.section) {
+            bakeSectionSoon(ctx.ws.dirs.bundles, m.section);
+            m.section = await enrichPaints(ctx.ws, tutor, date, m.job, m.at, await enrichLectures(ctx.ws, m.section));
+        }
+    return { tutor, date, messages, pending: active && active.date === date ? active.job : null, thread: currentThread(index) };
+}
+export async function parentDay(ctx, tutor, date) {
+    const index = await readIndex(ctx.ws, tutor, date);
+    const active = ctx.runner.running(tutor);
+    const { states, assets } = await scanCards(ctx.ws, tutor, date);
+    const messages = parentConversation(index, states, assets);
+    const partial = active && active.date === date ? ctx.runner.partial(tutor) : null;
+    if (partial) {
+        const m = messages.find((x) => x.job === active.job);
+        if (m)
+            m.section = partial;
+    }
+    for (const m of messages)
+        if (m.section) {
+            bakeSectionSoon(ctx.ws.dirs.bundles, m.section);
+            m.section = await enrichPaints(ctx.ws, tutor, date, m.job, m.at, await enrichLectures(ctx.ws, m.section), { parent: true });
+        }
+    // 「做了」旁注带上孩子在弹窗里想了多久、改过几次(有实录才有):这张卡从同一话题上一条消息到这条之间的弹窗
+    const plays = await readPlays(ctx.ws, tutor, date);
+    if (plays.length) {
+        const th = threads(index.messages);
+        const at = (m) => Date.parse(m.timing?.startedAt ?? '') || Date.parse(m.at);
+        for (const pm of messages) {
+            if (!pm.cards?.length)
+                continue;
+            const i = index.messages.findIndex((x) => x.job === pm.job);
+            if (i < 0)
+                continue;
+            const prev = index.messages.slice(0, i).reverse().find((_x, k) => th[i - 1 - k] === th[i]);
+            const [from, to] = [prev ? at(prev) : -Infinity, at(index.messages[i])];
+            pm.cards = pm.cards.map((c) => { const [job, n] = c.card.split('/'); const took = reelCardTook(plays, job, Number(n), from, to); return took ? { ...c, took } : c; });
+        }
+    }
+    return { tutor, date, messages, pending: active && active.date === date ? active.job : null, thread: currentThread(index) };
+}
+/** 一天里各轮的实录(<日期>.<job>.play.jsonl;jobs 给了就只读这几轮),合在一起按时刻排;坏行丢掉 */
+async function readPlays(ws, tutor, date, jobs) {
+    const dir = join(ws.dirs.conversations, tutor);
+    const out = [];
+    const names = await readdir(dir).catch(() => []);
+    for (const name of names) {
+        const m = new RegExp(`^${date}\\.(\\d{4}-\\d+)\\.play\\.jsonl$`).exec(name);
+        if (!m || (jobs && !jobs.has(m[1])))
+            continue;
+        const text = await readFile(join(dir, name), 'utf8').catch(() => '');
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const r = JSON.parse(line);
+                if (playRecordOk(r))
+                    out.push(r);
+            }
+            catch { /* 坏行丢掉 */ }
+        }
+    }
+    return out.sort((a, b) => a.at - b.at);
+}
+export async function parentReel(ctx, tutor, date, thread) {
+    const index = await readIndex(ctx.ws, tutor, date);
+    const ths = threads(index.messages);
+    const mine = index.messages.filter((_m, i) => ths[i] === thread);
+    if (!mine.length)
+        return null;
+    const files = conversationFiles(ctx.ws.dirs.conversations, tutor, date);
+    const events = {};
+    for (const m of mine) {
+        const text = await readFile(files.events(m.job), 'utf8').catch(() => null);
+        if (text !== null)
+            events[m.job] = parseEvents(text);
+    }
+    const { states } = await scanCards(ctx.ws, tutor, date);
+    const jobs = new Set(mine.map((m) => m.job));
+    const cards = Object.fromEntries(Object.entries(states).filter(([job]) => jobs.has(job)));
+    const plays = await readPlays(ctx.ws, tutor, date, jobs);
+    const calls = mine.some((m) => m.live) ? await liveCalls(ctx, tutor, date, jobs) : [];
+    const reel = buildReel({ messages: mine, events, cards, now: ctx.now().getTime(), plays, calls });
+    if (!reel)
+        return null;
+    const day = await parentDay(ctx, tutor, date);
+    const kid = await kidDay(ctx, tutor, date);
+    const device = [...mine].reverse().find((m) => m.device)?.device ?? null;
+    const t = ctx.ws.config.tutors[tutor];
+    const face = { name: tutor, display: t?.display ?? tutor, avatar: t ? shownAvatar(t) : null, subject: t?.subject ?? null, color: tutorColors(ctx.ws.config.tutors)[tutor] ?? NEUTRAL_COLOR, mark: boardMarkOf(t?.subject) };
+    const live = date === localDate(ctx.now()) || mine.some((m) => m.result === 'running');
+    return { tutor, date, thread, reel, messages: day.messages.filter((m) => m.thread === thread), kid: kid.messages.filter((m) => m.thread === thread), device, face, live, realtime: mine.some((m) => m.live) };
+}
+/** 这一天实时老师的通话录像(<日期>.live/<时分秒>.reel.json,src/runtime/live/call.ts 落的)里有这几轮的;声音是同名的 .wav。坏的、没声音的跳过 */
+async function liveCalls(ctx, tutor, date, jobs) {
+    const dir = join(ctx.ws.dirs.conversations, tutor, `${date}.live`);
+    const out = [];
+    for (const f of (await readdir(dir).catch(() => [])).filter((x) => /^\d{6}\.reel\.json$/.test(x)).sort()) {
+        const r = await readFile(join(dir, f), 'utf8').then((t) => JSON.parse(t), () => null);
+        const startAt = Date.parse(r?.startedAt ?? '');
+        if (!r || !Array.isArray(r.msgs) || !Array.isArray(r.playing) || Number.isNaN(startAt))
+            continue;
+        if (!r.msgs.some((x) => Array.isArray(x) && x[1] === 'o' && x[2]?.t === 'turn' && jobs.has(String(x[2].job))))
+            continue;
+        const wav = f.replace(/\.reel\.json$/, '.wav');
+        if (!existsSync(join(dir, wav)))
+            continue;
+        out.push({ audio: `${date}.live/${wav}`, startAt, msgs: r.msgs, playing: r.playing });
+    }
+    return out;
+}
+/**
+ * 一轮写进 vault 的每一笔,给家长过目(2026-10-30):记忆的行(memoryLines)、孩子的记忆的行(childLines)、日记那段(diaryBlock)。
+ * quote = 那一行对上了的孩子原话(这一轮的 memoryProposals 里核对过的那条)
+ */
+function vaultWrites(m) {
+    const verified = (m.memoryProposals ?? []).filter((p) => p.check === 'verified' && p.quote);
+    const quoteOf = (text, child) => verified.find((p) => {
+        const item = child ? childItem(p.item) : p.item;
+        return item === text || item.replace(/\s*(?:→|->)\s*/, ' → ').endsWith(` → ${text.replace(/^改:.*? → /, '')}`);
+    })?.quote;
+    const lines = (kind, ls) => (ls ?? []).map((l, n) => {
+        const text = memoryLineText(l);
+        const quote = quoteOf(text, kind === 'child');
+        return { job: m.job, kind, n, text: kind === 'child' ? `孩子的记忆:${text}` : text, ...(quote ? { quote } : {}) };
+    });
+    const diary = m.diaryBlock ? [{ job: m.job, kind: 'diary', n: 0, text: `日记:${m.diaryBlock.split('\n')[0].replace(/^##\s*/, '')}` }] : [];
+    return [...lines('memory', m.memoryLines), ...lines('child', m.childLines), ...diary];
+}
+export async function overview(ctx, date) {
+    const tutors = [];
+    const colors = tutorColors(ctx.ws.config.tutors);
+    for (const t of listTutors(ctx.ws.config, { kidOnly: true })) {
+        const index = await readIndex(ctx.ws, t.name, date);
+        const ths = threads(index.messages);
+        const by = new Map();
+        const diaries = [];
+        for (const [i, m] of index.messages.entries()) {
+            // 记账那轮不算一节,写进日记的那段挂回它记的话题
+            if (m.bookkeep && m.diaryBlock)
+                diaries.push({ id: ths[i], m });
+            if (m.bookkeep || m.tidy)
+                continue;
+            const id = ths[i];
+            let th = by.get(id);
+            if (!th) {
+                const via = m.via?.label ?? null;
+                const raw = via ? `首页 · ${via}` : m.from === 'kid' ? m.text : `系统:${m.text}`;
+                const b = m.via?.button;
+                const kind = m.from === 'system' ? 'system' : m.lecture ? 'lecture' : m.continues ? 'continue' : m.activity ? 'activity' : typeof b === 'number' ? 'start' : 'new';
+                th = { thread: id, at: m.at, title: Array.from(raw.trim()).slice(0, 20).join(''), from: m.from, via, start: { kind, label: kind === 'new' ? '新话题' : (via ?? m.lecture?.title ?? '') }, said: null, endAt: null, notes: [], remembered: [], writes: [], sections: 0, cards: 0, stoppedAt: null, rating: index.ratings[id] ?? null, booked: id in index.booked };
+                by.set(id, th);
+            }
+            if (m.lecture && !th.lecture)
+                th.lecture = { bundle: m.lecture.bundle, title: m.lecture.title, ...(m.lecture.video ? { video: true } : {}), watchedMs: m.lecture.watchedMs, finished: m.lecture.finished, marks: (m.lecture.marks ?? []).length };
+            // 孩子自己说的第一句:首页开场 / 接着按钮发出去的那句(正文就是按钮上的字)不算
+            if (th.said === null && m.from === 'kid' && m.text.trim() && !(m.via && viaSendsLabel(m.via) && m.via.label === m.text))
+                th.said = Array.from(m.text.trim()).slice(0, 30).join('');
+            const t0 = Date.parse(m.timing?.startedAt ?? '');
+            const dt = m.timing?.doneMs;
+            if (Number.isFinite(t0) && dt !== undefined)
+                th.endAt = new Date(t0 + dt).toISOString();
+            const tail = (m.parentText ?? '').replace(/^##\s*家长\s*/, '').trim();
+            if (tail)
+                th.notes.push(tail);
+            if (m.remembered?.length)
+                th.remembered.push(...m.remembered);
+            th.writes.push(...vaultWrites(m));
+            if (m.result === 'running')
+                th.stoppedAt = 'writing';
+            else if (m.result === 'ok' && m.section && (m.section.cards.length || m.section.lines.length)) {
+                th.sections++;
+                th.cards += m.section.cards.length;
+                const last = m.section.lines[m.section.lines.length - 1];
+                th.stoppedAt = last?.ask ? 'ask' : null;
+            }
+        }
+        for (const d of diaries)
+            by.get(d.id)?.writes.push(...vaultWrites(d.m));
+        // 换过运行时的话题:卡上说一句,记账按钮不算它(runner.bookkeep 也会跳过)
+        const runtimeName = ctx.ws.config.tutors[t.name]?.runtime ?? ctx.ws.config.runtimes.default;
+        for (const th of by.values())
+            if (!th.booked && !sameRuntime(index, th.thread, runtimeName))
+                th.oldRuntime = index.sessions[th.thread].runtime;
+        // 按住说话连着没发出去:实录里的 hold;孩子发成的一句(开口、打字发出去)把一串断开
+        for (const th of by.values()) {
+            const mine = index.messages.filter((_m, i) => ths[i] === th.thread);
+            const plays = await readPlays(ctx.ws, t.name, date, new Set(mine.map((m) => m.job)));
+            const holds = reelHolds(plays);
+            if (!holds.length)
+                continue;
+            const sent = [...mine.filter((m) => m.from === 'kid').map((m) => (Date.parse(m.timing?.startedAt ?? '') || Date.parse(m.at))), ...plays.filter((r) => r.k === 'type' && r.e === 'send').map((r) => r.at)];
+            const n = Math.max(0, ...reelMissRuns(holds, sent).map((x) => x.n));
+            if (n)
+                th.misses = n;
+        }
+        const booking = index.messages.some((m) => (m.bookkeep || m.tidy) && m.result === 'running');
+        tutors.push({ name: t.name, display: t.display, avatar: shownAvatar(t), subject: t.subject ?? null, color: colors[t.name] ?? NEUTRAL_COLOR, turns: index.messages.length, threads: [...by.values()], booking, extras: t.extras.filter((x) => (x !== 'talk' || ctx.ws.config.talk.enabled)) });
+    }
+    const today = localDate(ctx.now());
+    const names = tutors.map((t) => t.name);
+    const week = await Promise.all(weekOf(date, today).map(async (d) => ({
+        date: d,
+        tutors: (await Promise.all(names.map(async (n) => ((await readIndex(ctx.ws, n, d)).messages.some((m) => !m.bookkeep && !m.tidy) ? n : null)))).filter((n) => n !== null),
+    })));
+    return { title: ctx.ws.config.title, date, today, tutors, week, ready: ctx.bailian.status().ready };
+}
+/**
+ * 卡的状态:孩子在舞台里选了、填了 → 存 <日期>.<job>.cards/<n>.json,不起老师;下一条消息带给老师。
+ * 画板:body 里可以带 image(data:image/png;base64,…),存成 .cards/<n>.png,状态里只留路径(相对 workspace 根,老师 Read 看)
+ */
+async function putCardState(ctx, ws, tutor, job, n, body) {
+    const date = localDate(ctx.now());
+    const index = await readIndex(ws, tutor, date);
+    const msg = index.messages.find((m) => m.job === job);
+    const target = msg?.result === 'ok' ? msg.section?.cards[n] : undefined;
+    if (!target)
+        return { status: 404, json: { error: 'no_such_card' } };
+    // 交过的卡锁住了,不能再改
+    if (submittedCards(index).has(`${job}/${n}`))
+        return { status: 409, json: { error: 'submitted' } };
+    let state = body;
+    if (target.kind === 'canvas' && isObj(body) && typeof body.image === 'string') {
+        const { image, ...rest } = body;
+        const m = /^data:image\/png;base64,([A-Za-z0-9+/=]+)$/.exec(image);
+        if (!m || m[1].length > 8_000_000)
+            return { status: 400, json: { error: 'bad_state' } };
+        const png = await writeCardImage(ws, tutor, date, job, n, Buffer.from(m[1], 'base64'));
+        state = { ...rest, image: `conversations/${tutor}/${png}` };
+    }
+    const r = parseCardState(target, state);
+    if (!r.ok)
+        return { status: 400, json: { error: 'bad_state' } };
+    // 画板清空前存的那几版:图只认 captures/ 里在的(先 POST photos 拿到的),别的路径不给老师 Read
+    if (target.kind === 'canvas' && isObj(r.state) && Array.isArray(r.state.cleared)) {
+        for (const c of r.state.cleared)
+            if (c.image && !(await capturePathOk(ws, c.image)))
+                delete c.image;
+    }
+    const last = index.messages[index.messages.length - 1];
+    // turn = 这张卡所在话题的末条 job:下一条发给同一话题时才算「上一轮之后改过的」
+    const mine = threads(index.messages)[index.messages.findIndex((m) => m.job === job)];
+    await writeCardState(ws, tutor, date, job, n, { at: ctx.now().toISOString(), turn: lastJobOf(index, mine) ?? last.job, state: r.state });
+    // 录像的实录:孩子的每一次存都记一条(选了又改、填空的过程、画板一笔一笔)
+    await appendFile(conversationFiles(ws.dirs.conversations, tutor, date).play(job), `${JSON.stringify({ at: ctx.now().getTime(), k: 'card', job, card: n, state: r.state })}\n`).catch(() => { });
+    return { status: 200, json: { ok: true, card: `${job}/${n}`, state: r.state } };
+}
+/** 卡的配音:<日期>.<job>.cards/<n>/<k>.mp3(第 n 张卡的第 k 个资产) */
+const AUDIO_FILE_RE = /^\d{4}-\d{2}-\d{2}\.\d{4}-\d+\.cards\/\d+\/\d+\.mp3$/;
+/** 实时老师一次通话的声音(两边混好的,src/runtime/live/call.ts):<日期>.live/<时分秒>.wav;录像里实时的轮从这里放 */
+const LIVE_CALL_RE = /^\d{4}-\d{2}-\d{2}\.live\/\d{6}\.wav$/;
+/** 实时那一轮嘴照念的声音(字幕重放,src/runtime/live/call.ts 落的):<日期>.<job>.mouth.wav */
+const MOUTH_FILE_RE = /^\d{4}-\d{2}-\d{2}\.\d{4}-\d+\.mouth\.wav$/;
+const IMAGE_TYPES = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif', svg: 'image/svg+xml' };
+/** 作业照片一张最多这么大(解码后;页面先缩到长边 PHOTO_MAX_SIDE 的 jpeg,通常几百 KB) */
+export const PHOTO_MAX_BYTES = 3_000_000;
+/**
+ * 上传作业照片(R5):body {image: "data:image/jpeg;base64,…"}(也认 png)→ 落 captures/<日期>/<HHMM>-<n>.jpg → {path}。
+ * 孩子端与家长端同一条路;照片只是落盘,发消息时把 path 放进 photos[] 才到老师那里。
+ */
+async function uploadPhoto(ws, body, now) {
+    if (!isObj(body) || typeof body.image !== 'string')
+        return { status: 400, json: { error: 'bad_request', message: '要 {image: data:image/jpeg;base64,…}' } };
+    const m = /^data:image\/(jpeg|png);base64,([A-Za-z0-9+/=]+)$/.exec(body.image);
+    if (!m)
+        return { status: 400, json: { error: 'bad_request', message: '只认 data:image/jpeg 或 image/png 的 base64' } };
+    const data = Buffer.from(m[2], 'base64');
+    if (!data.length || data.length > PHOTO_MAX_BYTES)
+        return { status: 413, json: { error: 'too_large', message: `一张最多 ${PHOTO_MAX_BYTES / 1_000_000} MB,页面该先缩到长边 ${PHOTO_MAX_SIDE}` } };
+    const path = await writeCapture(ws, now, data, m[1] === 'png' ? 'png' : 'jpg');
+    return { status: 201, json: { path } };
+}
+/** 左栏的纸:读 / 存一张;key 是话题 id 或 new */
+async function paperRoute(ctx, tutor, date, method, url, body) {
+    const ws = ctx.ws;
+    const key = method === 'GET' ? (url.searchParams.get('key') ?? '') : isObj(body) && typeof body.key === 'string' ? body.key : '';
+    if (method !== 'GET' && method !== 'PUT')
+        return { status: 405, json: { error: 'method_not_allowed' } };
+    if (!PAPER_KEY_RE.test(key))
+        return { status: 400, json: { error: 'bad_request' } };
+    if (method === 'GET')
+        return { status: 200, json: { key, state: await readPaper(ws, tutor, date, key) } };
+    const r = CanvasStateSchema.safeParse(isObj(body) ? body.state : null);
+    if (!r.success)
+        return { status: 400, json: { error: 'bad_state' } };
+    const cleared = [];
+    for (const c of r.data.cleared ?? [])
+        cleared.push(c.image && !(await capturePathOk(ws, c.image)) ? { ...c, image: undefined } : c);
+    await writePaper(ws, tutor, date, key, { ink: r.data.ink, ...(cleared.length ? { cleared } : {}) }, ctx.now());
+    // 话题有了,孩子端把 new 那张存到话题名下:new 那张删掉(服务端第一条已经改过名的话,这里没有可删的)
+    if (isObj(body) && body.from === 'new' && key !== 'new')
+        await dropPaper(ws, tutor, date, 'new');
+    return { status: 200, json: { ok: true, key } };
+}
+/** who:请求是谁发的(createHandler 按来源地址与 cookie 算);直接调 route 的测试与 CLI 缺省 local = 本机免密 */
+export async function route(method, path, ctx, body, who = 'local', client = {}) {
+    await ctx.reload();
+    const ws = ctx.ws;
+    const url = new URL(path, 'http://x');
+    const p = url.pathname;
+    try {
+        // 服务起来的时刻、版本、跑的是哪个提交;仓里的提交变了 = 代码更新了,重起才用上(build.ts)。
+        // pid、mode(后台服务 service / 终端里 foreground)、vault 读不读得到(macOS 上后台服务读「文稿」、iCloud 云盘里的 vault 会被系统拦,没有弹窗):cotutor service status 看
+        if (p === '/api/health') {
+            const head = await headNow();
+            const vault = await readdir(ws.paths.vault).then(() => 'ok', (err) => (err.code === 'EPERM' || err.code === 'EACCES' ? 'denied' : 'missing'));
+            return { status: 200, json: { ok: true, configError: ctx.configError, started: BUILD.started, version: BUILD.version, commit: shortCommit(BUILD.commit), dirty: BUILD.dirty, head: shortCommit(head), changed: codeChanged(BUILD.commit, head), pid: process.pid, mode: process.env.COTUTOR_SERVICE ? 'service' : 'foreground', vault, calls: ctx.openCalls?.() ?? 0, bailian: ctx.bailian.status().ready } };
+        }
+        // 家长端与工作台的锁(access.ts):对 PIN 换 cookie;设了 PIN、没凭证的设备,孩子端以外的页面回输 PIN 的页、接口回 401。没设 PIN 什么都不拦
+        if (p === '/api/auth') {
+            if (method === 'GET')
+                return { status: 200, json: { who, pin: await ctx.access.pinSet() } };
+            if (method !== 'POST')
+                return { status: 405, json: { error: 'method_not_allowed' } };
+            const r = await ctx.access.login(isObj(body) && typeof body.pin === 'string' ? body.pin : '', { secure: Boolean(ctx.listen?.().https) });
+            if (r.ok)
+                return { status: 200, json: { ok: true }, setCookie: r.cookie };
+            return { status: r.retryMs ? 429 : 401, json: { error: r.retryMs ? 'locked' : 'pin', ...(r.retryMs ? { retryMs: r.retryMs } : {}) } };
+        }
+        if (who === 'anon' && !isKidPath(p) && (await ctx.access.pinSet())) {
+            return method === 'GET' && !p.startsWith('/api/') ? { status: 401, html: gatePage(ws.config.title) } : { status: 401, json: { error: 'auth', message: '要家长 PIN:在 /parent 或 /dev 上输一次' } };
+        }
+        // 工作台概览:近七天的轮数、今天各老师、用量、要看一眼的轮次;体检 = doctor 不带 --live(不花钱)
+        if (p === '/api/dev/overview' && method === 'GET')
+            return { status: 200, json: await devOverview(ws) };
+        // 孩子端的设备:对话页拿它给每轮写设备名;起名写进设备表,空着 = 去掉名字
+        if (p === '/api/dev/devices' && method === 'GET') {
+            const table = await readDevices(ws);
+            return { status: 200, json: Object.fromEntries(Object.entries(table).map(([id, d]) => [id, { name: d.name ?? null, label: d.label }])) };
+        }
+        const devRename = /^\/api\/dev\/devices\/([0-9a-f]{12})$/.exec(p);
+        if (devRename && method === 'PATCH') {
+            if (!isObj(body) || typeof body.name !== 'string')
+                return { status: 400, json: { error: 'bad_request' } };
+            return (await renameDevice(ws, devRename[1], body.name)) ? { status: 200, json: { ok: true } } : { status: 404, json: { error: 'no_such_device' } };
+        }
+        if (p === '/api/dev/doctor' && method === 'POST') {
+            const r = await doctorWorkspace(ws.root, { live: false });
+            return { status: 200, json: { ok: r.ok, at: new Date().toISOString(), checks: r.checks.map((c) => ({ name: c.name, ok: c.ok, required: c.required, detail: redactHome(c.detail), fix: c.fix })) } };
+        }
+        // 工作台改 activity:只认 workspace 里列得出的名字;存要带读进来时的 hash,对不上 409
+        if (p === '/api/dev/activities' && method === 'GET')
+            return { status: 200, json: await listDevActivities(ws) };
+        const da = /^\/api\/dev\/activities\/([a-z0-9][a-z0-9-]*)\/([^/]+?)(\/check|\/restore)?$/.exec(p);
+        if (da) {
+            const [, tutor, raw, sub] = da;
+            let name;
+            try {
+                name = decodeURIComponent(raw);
+            }
+            catch {
+                return { status: 400, json: { error: 'bad_request' } };
+            }
+            if (!(await findDevActivity(ws, tutor, name)))
+                return { status: 404, json: { error: 'no_such_activity', tutor, name } };
+            if (!sub && method === 'GET')
+                return { status: 200, json: await readDevActivity(ws, tutor, name) };
+            if (sub === '/check' && method === 'POST') {
+                if (!isObj(body) || typeof body.text !== 'string')
+                    return { status: 400, json: { error: 'bad_request', message: '要 {text, params?}' } };
+                const params = isObj(body.params) ? Object.fromEntries(Object.entries(body.params).filter(([, v]) => typeof v === 'string')) : {};
+                return { status: 200, json: await checkDevActivity(ws, tutor, name, body.text, params) };
+            }
+            if (!sub && method === 'PUT') {
+                if (!isObj(body) || typeof body.text !== 'string' || typeof body.base !== 'string')
+                    return { status: 400, json: { error: 'bad_request', message: '要 {text, base}' } };
+                try {
+                    return { status: 200, json: await saveDevActivity(ws, tutor, name, body.text, body.base) };
+                }
+                catch (err) {
+                    if (err instanceof ActivityConflict)
+                        return { status: 409, json: { error: 'conflict', message: '这份文件在别处改过了', hash: err.hash } };
+                    throw err;
+                }
+            }
+            if (sub === '/restore' && method === 'POST')
+                return { status: 200, json: await restoreDevActivity(ws, tutor, name) };
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        }
+        // 工作台改老师文件:「新话题」照的提示词;和 activity 同一套(存带 hash、对不上 409),检查有要改的不存(400)
+        if (p === '/api/dev/tutor-files' && method === 'GET')
+            return { status: 200, json: await listDevTutorFiles(ws) };
+        const dt = /^\/api\/dev\/tutor-files\/([a-z0-9][a-z0-9-]*)(\/check|\/restore)?$/.exec(p);
+        if (dt) {
+            const [, tutor, sub] = dt;
+            if (!(await hasDevTutorFile(ws, tutor)))
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            if (!sub && method === 'GET')
+                return { status: 200, json: await readDevTutorFile(ws, tutor) };
+            if (sub === '/check' && method === 'POST') {
+                if (!isObj(body) || typeof body.text !== 'string')
+                    return { status: 400, json: { error: 'bad_request', message: '要 {text}' } };
+                return { status: 200, json: await checkDevTutorFile(ws, tutor, body.text) };
+            }
+            if (!sub && method === 'PUT') {
+                if (!isObj(body) || typeof body.text !== 'string' || typeof body.base !== 'string')
+                    return { status: 400, json: { error: 'bad_request', message: '要 {text, base}' } };
+                try {
+                    return { status: 200, json: await saveDevTutorFile(ws, tutor, body.text, body.base) };
+                }
+                catch (err) {
+                    if (err instanceof ActivityConflict)
+                        return { status: 409, json: { error: 'conflict', message: '这份文件在别处改过了', hash: err.hash } };
+                    throw err;
+                }
+            }
+            if (sub === '/restore' && method === 'POST')
+                return { status: 200, json: await restoreDevTutorFile(ws, tutor) };
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        }
+        if (p === '/api/workspace' && method === 'GET')
+            return { status: 200, json: workspaceReport(ws) };
+        if (p === '/api/config') {
+            if (method === 'GET') {
+                return {
+                    status: 200,
+                    json: {
+                        title: ws.config.title,
+                        root: redactHome(ws.root),
+                        kid: ws.config.kid,
+                        server: ws.config.server,
+                        runtime: ws.config.runtimes.default,
+                        runtimes: Object.keys(ws.config.runtimes).filter((k) => k !== 'default'),
+                        policyDefaults: ws.config.policyDefaults,
+                        paths: ws.config.paths,
+                        resolvedPaths: Object.fromEntries(Object.entries(ws.paths).map(([k, v]) => [k, redactHome(v)])),
+                        /** 实时老师:总开关、嘴的模型、哪几位老师走实时用哪个音色(家长端「样子与声音」改) */
+                        live: ws.config.live,
+                        theme: ws.config.kid.theme,
+                        https: ws.config.server.https ?? null,
+                        shipped: (await tutorStatuses(ws.root)).map((s) => s.name),
+                        /** 老 workspace 的政策文件缺的出厂件(新老师 / 新运行时 / 模板里的新旗标);设置页据此提示一行 */
+                        migrate: await configGapsOf(ws.root),
+                        tutors: listTutors(ws.config),
+                        /** 学科色:每位老师现在用的(写了的、主科的、自动分的),与工作台点选的色块 */
+                        colors: tutorColors(ws.config.tutors),
+                        palette: { subject: SUBJECT_COLORS, auto: TUTOR_PALETTE },
+                        /** 老师条目的原始政策补丁(页面区分「继承」与「覆盖」) */
+                        tutorPatches: Object.fromEntries(Object.entries(ws.config.tutors).map(([k, t]) => [k, t.policy ?? {}])),
+                    },
+                };
+            }
+            if (method === 'PATCH') {
+                if (!isObj(body))
+                    return { status: 400, json: { error: 'bad_request', message: '要一个 JSON 对象' } };
+                // 孩子那段(kid)工作台不改:按住说话在哪边在家长端设置页(/api/parent/settings),别的直接编辑文件
+                await patchConfig(ws, body);
+                await ctx.reload();
+                return { status: 200, json: { ok: true, tutors: listTutors(ctx.ws.config), runtime: ctx.ws.config.runtimes.default } };
+            }
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        }
+        // 政策文件补缺(与 cotutor upgrade --config 同一条路):只加缺的出厂件,家长写过的值不动
+        if (p === '/api/config/migrate' && method === 'POST') {
+            const r = await upgradeConfig(ws.root);
+            await ctx.reload();
+            return { status: 200, json: { ok: true, gaps: r.gaps, applied: r.applied, installed: r.installed } };
+        }
+        if (p === '/api/tutors' && method === 'GET') {
+            return { status: 200, json: listTutors(ws.config, { kidOnly: url.searchParams.get('kid') === '1' }) };
+        }
+        // ---- 加老师 / 老师文件 / 删老师:与 cotutor add 同一条路 ----
+        if (p === '/api/tutors' && method === 'POST') {
+            if (!isObj(body) || typeof body.name !== 'string' || typeof body.display !== 'string' || !body.display.trim())
+                return { status: 400, json: { error: 'bad_request', message: '要 {name, display, subject?, avatar?, hidden?, description?}' } };
+            const name = body.name.trim();
+            if (ws.config.tutors[name])
+                return { status: 409, json: { error: 'exists', message: `cotutor.json 里已经有 ${name}` } };
+            const str = (k) => (typeof body[k] === 'string' && body[k].trim() ? body[k].trim() : undefined);
+            const r = await addTutorFile(ws.root, { name, display: body.display.trim(), subject: str('subject'), description: str('description') });
+            await patchConfig(ws, { tutors: { [name]: { display: body.display.trim(), ...(str('subject') ? { subject: str('subject') } : {}), ...(str('avatar') ? { avatar: str('avatar') } : {}), enabled: true, ...(body.hidden === true ? { hidden: true } : {}) } } });
+            await ctx.reload();
+            return { status: 201, json: { ok: true, ...r, tutors: listTutors(ctx.ws.config) } };
+        }
+        const tf = /^\/api\/tutors\/([a-z0-9][a-z0-9-]*)(\/file)?$/.exec(p);
+        if (tf) {
+            const [, name, isFile] = tf;
+            if (!ws.config.tutors[name])
+                return { status: 404, json: { error: 'no_such_tutor', tutor: name } };
+            if (isFile && method === 'GET')
+                return { status: 200, json: await readTutorFile(ws.root, name) };
+            if (isFile && method === 'PUT') {
+                if (!isObj(body) || typeof body.text !== 'string')
+                    return { status: 400, json: { error: 'bad_request', message: '要 {text}' } };
+                return { status: 200, json: await writeTutorFile(ws.root, name, body.text) };
+            }
+            if (!isFile && method === 'DELETE') {
+                const r = await removeTutorFile(ws.root, name);
+                await patchConfig(ws, { tutors: { [name]: null } });
+                await ctx.reload();
+                return { status: 200, json: { ok: true, ...r, tutors: listTutors(ctx.ws.config) } };
+            }
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        }
+        // ---- 孩子端:过滤在服务端做,永远不带工具 / 错误 / 评判 ----
+        if (p === '/api/kid/home' && method === 'GET')
+            return { status: 200, json: await kidHome(ctx, ctx.now()) };
+        // 按住说话的诊断:识别全在浏览器里、出错静默,真机上哪一步断了只有它自己知道;只收事件码与毫秒,不收字也不收声音
+        // 孩子端的流水:一次打开、页面脚本出错;没有设备 cookie 就种一枚
+        if (p === '/api/kid/log' && method === 'POST') {
+            const row = parseKidLog(body);
+            if (!row)
+                return { status: 400, json: { error: 'bad_request' } };
+            const known = validDevice(client.device);
+            const device = known ?? newDeviceId();
+            await recordKidLog(ws, row, { device, ip: client.ip, srv: { v: BUILD.version, commit: shortCommit(BUILD.commit), started: BUILD.started } }, ctx.now()).catch((err) => console.error('kid-log: 落盘失败', err));
+            return { status: 200, json: { ok: true }, ...(known ? {} : { setCookie: deviceCookie(device, Boolean(ctx.listen?.().https)) }) };
+        }
+        if (p === '/api/kid/voice-diag' && method === 'POST') {
+            if (!isObj(body) || JSON.stringify(body).length > 4000)
+                return { status: 400, json: { error: 'bad_request' } };
+            const row = { at: ctx.now().toISOString(), ...body };
+            await mkdir(join(ws.root, '.cotutor'), { recursive: true });
+            await appendFile(join(ws.root, '.cotutor', 'voice-diag.jsonl'), `${JSON.stringify(row)}\n`).catch(() => { });
+            return { status: 200, json: { ok: true } };
+        }
+        const kid = /^\/api\/kid\/conversations\/([a-z0-9][a-z0-9-]*)\/(today|messages|history|photos|play|paper|\d{4}-\d{2}-\d{2})$/.exec(p);
+        if (kid) {
+            const [, tutor, tail] = kid;
+            const t = ws.config.tutors[tutor];
+            if (!t || !t.enabled || t.hidden)
+                return { status: 404, json: { error: 'no_such_tutor' } };
+            const date = localDate(ctx.now());
+            // 录像的实录:孩子端每 10 秒一批 {thread, sentAt, records};时刻按 sentAt 把两边的钟差校到服务端;
+            // 形状不对的、不是这个话题的、太旧太新的丢掉,卡的改动只认服务端自己记的;不回错(孩子端不报错)。记在话题当时的末条 job 上,删话题一起删
+            if (tail === 'play' && method === 'POST') {
+                if (!isObj(body) || typeof body.thread !== 'string' || !Array.isArray(body.records) || body.records.length > 400)
+                    return { status: 400, json: { error: 'bad_request' } };
+                const index = await readIndex(ws, tutor, date);
+                const ths = threads(index.messages);
+                const jobs = new Set(index.messages.filter((_m, i) => ths[i] === body.thread).map((m) => m.job));
+                const last = jobs.size ? lastJobOf(index, body.thread) : null;
+                if (!last)
+                    return { status: 200, json: { kept: 0 } };
+                const now = ctx.now().getTime();
+                const skew = typeof body.sentAt === 'number' && Math.abs(now - body.sentAt) < 86_400_000 ? now - body.sentAt : 0;
+                const rows = [];
+                for (const x of body.records) {
+                    if (!playRecordOk(x) || x.k === 'card')
+                        continue;
+                    const at = Math.round(x.at + skew);
+                    if (at > now + 60_000 || at < now - 86_400_000)
+                        continue;
+                    if ((x.k === 'stage' || x.k === 'scroll') && !jobs.has(x.job))
+                        continue;
+                    rows.push(JSON.stringify({ ...x, at }));
+                }
+                if (rows.length)
+                    await appendFile(conversationFiles(ws.dirs.conversations, tutor, date).play(last), `${rows.join('\n')}\n`).catch(() => { });
+                return { status: 200, json: { kept: rows.length } };
+            }
+            // 作业照片(R5):先传图拿 path,再连 path 一起发消息;不起老师、不计上限
+            if (tail === 'photos')
+                return method === 'POST' ? uploadPhoto(ws, body, ctx.now()) : { status: 405, json: { error: 'method_not_allowed' } };
+            // 左栏的纸:GET ?key=<话题 | new> 读;PUT {key, state} 存(清掉那几版的图只认 captures/ 里在的)。不起老师
+            if (tail === 'paper')
+                return paperRoute(ctx, tutor, date, method, url, body);
+            if (tail === 'today' && method === 'GET') {
+                return { status: 200, json: await kidDay(ctx, tutor, date) };
+            }
+            // 以前的某一天(只读回放;未来的日期与坏日期 400)
+            if (DATE_RE.test(tail) && method === 'GET') {
+                if (tail > date || Number.isNaN(Date.parse(tail)))
+                    return { status: 400, json: { error: 'bad_request' } };
+                return { status: 200, json: await kidDay(ctx, tutor, tail) };
+            }
+            if (tail === 'history' && method === 'GET') {
+                const days = Math.min(365, Math.max(1, Number(url.searchParams.get('days') ?? 30) || 30));
+                return { status: 200, json: await kidHistory(ctx, tutor, days) };
+            }
+            // 孩子端发一条只走实时那条连接(/api/live/<老师>/ws,src/runtime/live/turns.ts);2026-11-04 删了 HTTP 的发
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        }
+        // 字幕重放:实时那一轮嘴照念的声音在哪、多长、讲稿每句从哪开始(毫秒);只给实时的轮,没落过声音 404
+        const mouth = /^\/api\/kid\/conversations\/([a-z0-9][a-z0-9-]*)\/mouth\/(\d{4}-\d{2}-\d{2})\/(\d{4}-\d+)$/.exec(p);
+        if (mouth) {
+            const [, tutor, d, job] = mouth;
+            const t = ws.config.tutors[tutor];
+            if (!t || !t.enabled || t.hidden)
+                return { status: 404, json: { error: 'no_such_tutor' } };
+            if (method !== 'GET')
+                return { status: 405, json: { error: 'method_not_allowed' } };
+            const m = (await readIndex(ws, tutor, d)).messages.find((x) => x.job === job);
+            if (m?.live !== true)
+                return { status: 404, json: { error: 'not_found' } };
+            const raw = await readFile(conversationFiles(ws.dirs.conversations, tutor, d).mouth(job, 'json'), 'utf8').catch(() => null);
+            // 正在重落的那一下可能读到半截:当没有
+            let idx = null;
+            try {
+                idx = raw === null ? null : JSON.parse(raw);
+            }
+            catch {
+                idx = null;
+            }
+            if (!idx?.lines?.length)
+                return { status: 404, json: { error: 'not_found' } };
+            return { status: 200, json: { audio: `/api/audio/${tutor}/${d}.${job}.mouth.wav`, ms: idx.ms, lines: idx.lines } };
+        }
+        // 卡的状态:孩子在舞台里选了、填了 → 存 <日期>.<job>.cards/<n>.json,不起老师;下一条消息带给老师
+        const card = /^\/api\/kid\/conversations\/([a-z0-9][a-z0-9-]*)\/cards\/(\d{4}-\d+)\/(\d+)$/.exec(p);
+        if (card) {
+            const [, tutor, job, nStr] = card;
+            const t = ws.config.tutors[tutor];
+            if (!t || !t.enabled || t.hidden)
+                return { status: 404, json: { error: 'no_such_tutor' } };
+            if (method !== 'PUT')
+                return { status: 405, json: { error: 'method_not_allowed' } };
+            return putCardState(ctx, ws, tutor, job, Number(nStr), body);
+        }
+        // 老师头像(R5b,2026-09-16):cotutor.json 里 avatar 是图片相对路径时(figshot 写的 avatars/<老师>.png)从这里取;
+        // 没写(或还是旧的出厂 emoji)的三门主科给包里的出厂头像(avatars.ts);
+        // emoji 头像、越界、不是图、不存在都 404(孩子端退回显示 emoji / 首字)。no-cache:figshot 换了脸孩子端要马上见到
+        const av = /^\/api\/kid\/avatar\/([a-z0-9][a-z0-9-]*)$/.exec(p);
+        if (av && method === 'GET') {
+            const factory = ws.config.tutors[av[1]] ? factoryAvatarFile(ws.config.tutors[av[1]]) : null;
+            if (factory)
+                return { status: 200, file: factory, contentType: 'image/webp', cacheControl: 'no-cache' };
+            const rel = ws.config.tutors[av[1]]?.avatar ?? '';
+            const file = resolve(ws.root, rel);
+            const ext = IMAGE_EXT.exec(rel)?.[1]?.toLowerCase() ?? '';
+            if (!rel || isAbsolute(rel) || !file.startsWith(ws.root + sep) || !IMAGE_TYPES[ext])
+                return { status: 404, json: { error: 'not_found' } };
+            if (!(await stat(file).catch(() => null))?.isFile())
+                return { status: 404, json: { error: 'not_found' } };
+            return { status: 200, file, contentType: IMAGE_TYPES[ext], cacheControl: 'no-cache' };
+        }
+        // 写字卡的笔顺:一个汉字一份 JSON,数据包里现读;不是汉字 / 没有这个字 404(页面只显示字形不动)
+        const hz = /^\/api\/kid\/tianzige\/([^/]+)$/.exec(p);
+        if (hz && method === 'GET') {
+            const d = await tianzigeData(decodeURIComponent(hz[1]));
+            return d ? { status: 200, json: d, cacheControl: 'max-age=86400' } : { status: 404, json: { error: 'not_found' } };
+        }
+        // 单词卡的笔顺:词里每个字母的点序列(src/chalk/glyphs 现采);写不出的词 404(页面退成字体的字)
+        const lt = /^\/api\/kid\/letters\/([^/]+)$/.exec(p);
+        if (lt && method === 'GET') {
+            const d = lettersData(decodeURIComponent(lt[1]));
+            return d ? { status: 200, json: d, cacheControl: 'max-age=86400' } : { status: 404, json: { error: 'not_found' } };
+        }
+        // 视频小课堂(第 4 步):lectures/<id>/ 的课名与一句一段(舞台包的播放器拼时钟用),与 video.mp4(Range 由 sendFile 管)
+        const lv = /^\/api\/kid\/lectures\/([a-z0-9][a-z0-9-]*)\/(lecture\.json|video\.mp4)$/.exec(p);
+        if (lv && method === 'GET') {
+            const { lecture: l } = await inspectLecture(ws, lv[1]);
+            if (!l?.video)
+                return { status: 404, json: { error: 'not_found' } };
+            if (lv[2] === 'video.mp4')
+                return { status: 200, file: join(ws.dirs.lectures, lv[1], 'video.mp4'), contentType: 'video/mp4', cacheControl: 'no-cache' };
+            return { status: 200, json: { title: l.title, total: l.clock.total, segments: l.clock.segments.map((x) => ({ start: x.start, len: x.len, line: x.line })) } };
+        }
+        // 图片卡的图:只认 workspace 根以内的图片文件(产物、照片);越界、不是图、不存在都 404
+        if (p === '/api/kid/image' && method === 'GET') {
+            const rel = url.searchParams.get('p') ?? '';
+            const file = resolve(ws.root, rel);
+            const ext = IMAGE_EXT.exec(rel)?.[1]?.toLowerCase() ?? '';
+            if (!rel || isAbsolute(rel) || !file.startsWith(ws.root + sep) || !IMAGE_TYPES[ext])
+                return { status: 404, json: { error: 'not_found' } };
+            if (!(await stat(file).catch(() => null))?.isFile())
+                return { status: 404, json: { error: 'not_found' } };
+            return { status: 200, file, contentType: IMAGE_TYPES[ext] };
+        }
+        const audio = /^\/api\/audio\/([a-z0-9][a-z0-9-]*)\/(.+)$/.exec(p);
+        if (audio && method === 'GET') {
+            const [, tutor, name] = audio;
+            const call = LIVE_CALL_RE.test(name) || MOUTH_FILE_RE.test(name);
+            if (!ws.config.tutors[tutor] || (!AUDIO_FILE_RE.test(name) && !call))
+                return { status: 404, json: { error: 'not_found' } };
+            const file = join(ws.dirs.conversations, tutor, name);
+            if (!(await stat(file).catch(() => null))?.isFile())
+                return { status: 404, json: { error: 'not_found' } };
+            // 嘴照念的那份一段一段重落(这一轮还在念时就取得到),别让孩子端拿到缓存里的半截
+            return { status: 200, file, contentType: call ? 'audio/wav' : 'audio/mpeg', ...(MOUTH_FILE_RE.test(name) ? { cacheControl: 'no-cache' } : {}) };
+        }
+        // 看原文(2026-09-11):一轮拆成六站,一个接口给全;/fixture 是原文原样一份,开发者放进 tests/fixtures/board/
+        const rawRe = /^\/api\/conversations\/([a-z0-9][a-z0-9-]*)\/(\d{4}-\d{2}-\d{2}|today)\/raw\/(\d{4}-\d+)(\/fixture)?$/.exec(p);
+        if (rawRe) {
+            const [, tutor, d, job, fixture] = rawRe;
+            if (method !== 'GET')
+                return { status: 405, json: { error: 'method_not_allowed' } };
+            if (!ws.config.tutors[tutor])
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            const view = await rawView(ws, tutor, d === 'today' ? localDate(ctx.now()) : d, job);
+            if (!view)
+                return { status: 404, json: { error: 'not_found', message: `${d} 没有 ${job} 这一轮` } };
+            return { status: 200, json: fixture ? fixtureOf(view) : view };
+        }
+        // 话题打星(《obsidian仓库设计.md》§4):PUT {rating: 1–5 | null};记账:POST {threads?: [..]} → 每个话题一轮记账任务,老师回「## 记账」段,应用写日记
+        const rate = /^\/api\/conversations\/([a-z0-9][a-z0-9-]*)\/(\d{4}-\d{2}-\d{2})\/threads\/([^/]+)\/rating$/.exec(p);
+        if (rate && method === 'PUT') {
+            const [, tutor, date, thread] = rate;
+            if (!ws.config.tutors[tutor])
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            const rating = isObj(body) ? body.rating : undefined;
+            if (!(rating === null || (typeof rating === 'number' && Number.isInteger(rating) && rating >= 1 && rating <= 5)))
+                return { status: 400, json: { error: 'bad_request', message: '要 {rating: 1–5 或 null}' } };
+            try {
+                const index = await rateThread(ws, tutor, date, decodeURIComponent(thread), rating);
+                return { status: 200, json: { tutor, date, thread: decodeURIComponent(thread), rating: index.ratings[decodeURIComponent(thread)] ?? null, keepScore: ws.config.vault.keepScore } };
+            }
+            catch (err) {
+                return { status: 404, json: { error: 'no_such_thread', message: err instanceof Error ? err.message : String(err) } };
+            }
+        }
+        // 看录像:一个话题按时间排好的轨道;没有孩子开口的话题 404
+        const reel = /^\/api\/conversations\/([a-z0-9][a-z0-9-]*)\/(today|\d{4}-\d{2}-\d{2})\/threads\/([^/]+)\/reel$/.exec(p);
+        if (reel && method === 'GET') {
+            const [, tutor, tail, raw] = reel;
+            if (!ws.config.tutors[tutor])
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            const date = tail === 'today' ? localDate(ctx.now()) : tail;
+            if (date > localDate(ctx.now()) || Number.isNaN(Date.parse(date)))
+                return { status: 400, json: { error: 'bad_request', message: '日期要是今天或以前' } };
+            const r = await parentReel(ctx, tutor, date, decodeURIComponent(raw));
+            return r ? { status: 200, json: r } : { status: 404, json: { error: 'no_reel', message: '这个话题没有录像' } };
+        }
+        // 删掉一个话题(家长板书页清单上的「删」,2026-09-22):那个话题还有轮在跑就 409;这个话题写进记忆、日记的一起撤(store.deleteThread,2026-10-05),回撤了多少
+        const del = /^\/api\/conversations\/([a-z0-9][a-z0-9-]*)\/(\d{4}-\d{2}-\d{2})\/threads\/([^/]+)$/.exec(p);
+        if (del && method === 'DELETE') {
+            const [, tutor, date, raw] = del;
+            const thread = decodeURIComponent(raw);
+            if (!ws.config.tutors[tutor])
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            const target = ws;
+            const active = ctx.runner.running(tutor);
+            if (active && active.date === date) {
+                const idx = await readIndex(target, tutor, date);
+                const i = idx.messages.findIndex((m) => m.job === active.job);
+                if (i >= 0 && threads(idx.messages)[i] === thread)
+                    return { status: 409, json: { error: 'busy', message: '老师还在写这个话题,等它写完再删' } };
+            }
+            try {
+                const { index, undo } = await deleteThread(target, tutor, date, thread);
+                return { status: 200, json: { tutor, date, thread, threadsLeft: new Set(threads(index.messages)).size, undo } };
+            }
+            catch (err) {
+                if (err instanceof IndexError)
+                    return { status: 404, json: { error: 'no_such_thread', message: err.message } };
+                throw err;
+            }
+        }
+        // 撤回话题写进 vault 的一笔(家长端「记录」的「记住了」,2026-10-30):{job, kind, n},kind = memory / child / diary;这位老师这天还有轮在跑就 409(会写同一篇)
+        const unw = /^\/api\/conversations\/([a-z0-9][a-z0-9-]*)\/(\d{4}-\d{2}-\d{2})\/threads\/([^/]+)\/vault\/undo$/.exec(p);
+        if (unw && method === 'POST') {
+            const [, tutor, date, raw] = unw;
+            if (!ws.config.tutors[tutor])
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            const kinds = ['memory', 'child', 'diary'];
+            if (!isObj(body) || typeof body.job !== 'string' || typeof body.kind !== 'string' || !kinds.includes(body.kind) || (body.kind !== 'diary' && (typeof body.n !== 'number' || !Number.isInteger(body.n) || body.n < 0)))
+                return { status: 400, json: { error: 'bad_request', message: '要 {job, kind: memory | child | diary, n}' } };
+            if (ctx.runner.running(tutor)?.date === date)
+                return { status: 409, json: { error: 'busy', message: '老师还在写,等它写完再撤' } };
+            try {
+                const { undo } = await undoVaultWrite(ws, tutor, date, decodeURIComponent(raw), { job: body.job, kind: body.kind, n: typeof body.n === 'number' ? body.n : 0 });
+                return undo.memory || undo.diary ? { status: 200, json: { ok: true, undo } } : { status: 409, json: { error: 'changed', message: undo.misses.join(';') || '找不到那一行,没撤', undo } };
+            }
+            catch (err) {
+                if (err instanceof IndexError)
+                    return { status: 404, json: { error: 'no_such_write', message: err.message } };
+                throw err;
+            }
+        }
+        const book = /^\/api\/conversations\/([a-z0-9][a-z0-9-]*)\/(\d{4}-\d{2}-\d{2})\/bookkeep$/.exec(p);
+        if (book && method === 'POST') {
+            const [, tutor, date] = book;
+            if (!ws.config.tutors[tutor])
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            const only = isObj(body) && Array.isArray(body.threads) ? body.threads.filter((t) => typeof t === 'string') : undefined;
+            const { queued, skipped } = await ctx.runner.bookkeep(tutor, date, only);
+            return { status: 202, json: { tutor, date, queued, skipped } };
+        }
+        // 家长板书页:清单与一天的板书,都在家长命名空间下;/api/kid/* 不动
+        const ov = /^\/api\/overview\/(today|\d{4}-\d{2}-\d{2})$/.exec(p);
+        if (ov && method === 'GET') {
+            const date = ov[1] === 'today' ? localDate(ctx.now()) : ov[1];
+            if (date > localDate(ctx.now()) || Number.isNaN(Date.parse(date)))
+                return { status: 400, json: { error: 'bad_request', message: '日期要是今天或以前' } };
+            return { status: 200, json: await overview(ctx, date) };
+        }
+        const pb = /^\/api\/conversations\/([a-z0-9][a-z0-9-]*)\/(today|\d{4}-\d{2}-\d{2})\/board$/.exec(p);
+        if (pb && method === 'GET') {
+            const [, tutor, tail] = pb;
+            if (!ws.config.tutors[tutor])
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            const date = tail === 'today' ? localDate(ctx.now()) : tail;
+            if (date > localDate(ctx.now()) || Number.isNaN(Date.parse(date)))
+                return { status: 400, json: { error: 'bad_request', message: '日期要是今天或以前' } };
+            return { status: 200, json: await parentDay(ctx, tutor, date) };
+        }
+        const conv = /^\/api\/conversations\/([a-z0-9][a-z0-9-]*)(?:\/([^/]+))?$/.exec(p);
+        if (conv) {
+            const [, tutor, tail] = conv;
+            if (!ws.config.tutors[tutor])
+                return { status: 404, json: { error: 'no_such_tutor', tutor } };
+            if (tail === undefined && method === 'GET') {
+                return { status: 200, json: { tutor, today: localDate(ctx.now()), dates: await listDates(ws, tutor), running: ctx.runner.running(tutor) } };
+            }
+            // 工作台传照片:与孩子端同一条路(落 captures/,回 {path})
+            if (tail === 'photos')
+                return method === 'POST' ? uploadPhoto(ws, body, ctx.now()) : { status: 405, json: { error: 'method_not_allowed' } };
+            if (tail === 'messages' && method === 'POST') {
+                if (!isObj(body) || typeof body.text !== 'string')
+                    return { status: 400, json: { error: 'bad_request', message: '要 {text, from?, focus?, runtime?, photos?}' } };
+                // 工作台 /dev 与 cotutor send 发的都算孩子的话(2026-10-05 起没有 from: parent;旧客户端带 parent 也当 kid)
+                const from = body.from === undefined || body.from === 'parent' ? 'kid' : body.from;
+                if (!MESSAGE_FROM.includes(from))
+                    return { status: 400, json: { error: 'bad_request', message: `from 只能是 ${MESSAGE_FROM.join(' / ')}` } };
+                const focus = body.focus === undefined ? undefined : FocusSchema.safeParse(body.focus);
+                if (focus && !focus.success)
+                    return { status: 400, json: { error: 'bad_request', message: 'focus 形状不对' } };
+                const photos = await photosOf(ws, body.photos);
+                if (photos === null)
+                    return { status: 400, json: { error: 'bad_request', message: 'photos 要是 captures/ 里在的文件(先 POST …/photos 传图拿 path)' } };
+                // 工作台 /dev 不带 device,缺省当平板横屏
+                const device = body.device === undefined ? undefined : DeviceSchema.safeParse(body.device);
+                if (device && !device.success)
+                    return { status: 400, json: { error: 'bad_request', message: 'device 只能是 phone / tablet' } };
+                const action = body.action === undefined ? undefined : body.action === 'submit' ? 'submit' : null;
+                if (action === null)
+                    return { status: 400, json: { error: 'bad_request', message: 'action 只能是 continue / submit' } };
+                if (!body.text.trim() && !action && !photos?.length)
+                    return { status: 400, json: { error: 'bad_request', message: '要说点什么' } };
+                const started = await ctx.runner.send(tutor, {
+                    from: from,
+                    text: body.text,
+                    action,
+                    focus: focus?.data,
+                    runtime: typeof body.runtime === 'string' ? body.runtime : undefined,
+                    newThread: body.newThread === true,
+                    thread: typeof body.thread === 'string' ? body.thread : undefined,
+                    photos,
+                    device: device?.data,
+                    // 孩子的话照实时写(同孩子端、同 replay:上下文包带 live:、不补提问卡、讲稿不截);嘴不在,接住与打断不带。系统发的不算(2026-11-04)
+                    ...(from === 'kid' ? { live: {} } : {}),
+                });
+                return { status: 202, json: { tutor, date: started.date, job: started.job, thread: started.thread, runtime: started.plan.runtime, resume: started.plan.resume } };
+            }
+            if (tail !== undefined && tail !== 'messages' && method === 'GET') {
+                const date = tail === 'today' ? localDate(ctx.now()) : tail;
+                if (!DATE_RE.test(date))
+                    return { status: 400, json: { error: 'bad_request', message: '日期要是 YYYY-MM-DD 或 today' } };
+                return { status: 200, json: await dayView(ctx, tutor, date) };
+            }
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        }
+        // 孩子端的主题(themes/<kid.theme>/):css 与清单现读,mtime 缓存;坏了退出厂 default(孩子端永远有样子)
+        if (method === 'GET' && (p === '/kid/theme.css' || p === '/kid/theme.json')) {
+            const t = await themeFiles(ws.root, ws.config.kid.theme);
+            if (p === '/kid/theme.css')
+                return { status: 200, html: t.css, contentType: 'text/css; charset=utf-8' };
+            return { status: 200, json: { ...t.manifest, theme: ws.config.kid.theme, source: t.source, ...(t.error ? { error: t.error } : {}) } };
+        }
+        // 舞台包(重卡在 iframe 里开)与课包文件:静态,越界 404
+        if (method === 'GET' && p.startsWith('/stage/')) {
+            if (p === '/stage/') {
+                const html = await stageIndex();
+                return html === null ? { status: 404, json: { error: 'not_found' } } : { status: 200, html };
+            }
+            const f = await stageAsset(p);
+            return f ? { status: 200, file: f.file, contentType: f.contentType } : { status: 404, json: { error: 'not_found' } };
+        }
+        // 课包某一刻的画面(画的卡、lecture 卡的缩略图、播放器截图的底):烤过的课包服务端现画;没烤过先烤,烤不了 404
+        const frame = /^\/api\/bundles\/([a-z0-9][a-z0-9-]*)\/frame\.svg$/.exec(p);
+        if (method === 'GET' && frame) {
+            const svg = await lectureFrameSvg(ws, frame[1], parseSvgMs(url.searchParams.get('svg')), parseRing(url.searchParams.get('ring')), { bake: ensureBaked });
+            return svg === null ? { status: 404, json: { error: 'not_found' } } : { status: 200, body: Buffer.from(svg), contentType: 'image/svg+xml; charset=utf-8' };
+        }
+        if (method === 'GET' && p.startsWith('/api/bundles/')) {
+            const f = await bundleAsset(ws.dirs.bundles, p);
+            return f ? { status: 200, file: f.file, contentType: f.contentType } : { status: 404, json: { error: 'not_found' } };
+        }
+        // 家长端「首页」的接口(/api/parent/*)
+        const phr = await parentHomeRoute(method, p, ctx, body);
+        if (phr)
+            return phr;
+        const plr = await parentLookRoute(method, p, url, ctx, body);
+        if (plr)
+            return plr;
+        const blr = await bailianRoute(method, p, ctx, body, who);
+        if (blr)
+            return blr;
+        // 口语课(路由 src/app/talk/,页面 src/ui/talk/,规则与存取 src/scenes/talk/):/talk 与 /api/talk/* 交给它;上课在英语老师的实时页(talk-run.ts)
+        const tk = await talkRoute(method, url, ctx, body);
+        if (tk)
+            return tk;
+        // 听写(路由 src/app/dictation/,页面 src/ui/dictation/,规则与存取 src/scenes/dictation/):/dictation 与 /api/dictation/* 交给它;首页的听写卡在 kid-page 画
+        const tx = await dictationRoute(method, url, ctx, body);
+        if (tx)
+            return tx;
+        if (method !== 'GET')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        // 工作台:对话原始视图、看原文、老师团、activity、设置——给有技术背景的家长与开发者;家长端在 /parent
+        if (p === '/dev')
+            return { status: 200, html: DEV_PAGE };
+        // 按住说话的试验页(真机上比策略用;不在孩子端与家长端的入口里)
+        // 按钮样张:老师页那颗「头像 + 按住说话」的每一种样子,调动画时看这一页
+        if (p === '/dev/voice')
+            return { status: 200, html: VOICE_GALLERY_PAGE };
+        // 主屏幕(iPad「添加到主屏幕」):清单与图标都按标题现生成,没有静态资源
+        if (p === '/manifest.webmanifest')
+            return { status: 200, json: webManifest(ws.config.title), contentType: 'application/manifest+json; charset=utf-8' };
+        const icon = /^\/icon-(\d{2,4})\.png$/.exec(p);
+        if (icon) {
+            const n = Number(icon[1]);
+            if (!ICON_SIZES.includes(n))
+                return { status: 404, json: { error: 'not_found' } };
+            return { status: 200, body: appIconPng(n), contentType: 'image/png' };
+        }
+        // 网页图标(src/ui/shared/favicon.ts):所有页面都是 cotutor 的双 C;no-cache:换了 logo 马上见到
+        const fav = faviconResponse(p);
+        if (fav)
+            return { status: 200, ...fav, cacheControl: 'no-cache' };
+        if (p === '/')
+            return { status: 200, html: kidPage(esc(ws.config.title), {}, await stageVersion()) };
+        // 家长端:也是孩子端页面本身,数据走家长接口(答案在、家长的话在),卡锁着;自己的清单,加到主屏幕才不会拿到孩子端那份
+        if (p === '/parent')
+            return { status: 200, html: parentPage(esc(ws.config.title)) };
+        // 家长端「首页」(设孩子的首页与几项常改的设置)
+        if (p === '/parent/home')
+            return { status: 200, html: PARENT_HOME_PAGE };
+        // 家长端「设置」(设一次就不常动的:孩子的平板上按住说话那一栏放哪边)
+        if (p === '/parent/settings')
+            return { status: 200, html: PARENT_SETTINGS_PAGE };
+        // 二维码的打印页:家长端「扫码打开」的「打印 ›」开它(不在孩子端的入口里)
+        if (p === '/parent/qr')
+            return ctx.listen ? { status: 200, html: qrPage(ws.config.title, ctx.listen(), url.searchParams.get('via') === 'ip' ? 'ip' : 'name', url.searchParams.get('to') === 'parent' ? 'parent' : 'kid') } : { status: 404, json: { error: 'not_listening' } };
+        // 录像里孩子的屏幕:家长端录像时开在 iframe 里;直接打开也能看(调试),?tutor=&date=&thread=[&at=时:分:秒]
+        if (p === '/reel')
+            return { status: 200, html: kidPage(esc(ws.config.title), { reel: true }, await stageVersion()) };
+        if (p === '/preview')
+            return { status: 200, html: kidPage(esc(ws.config.title), { preview: true }, await stageVersion()) };
+        if (p === '/parent/manifest.webmanifest')
+            return { status: 200, json: webManifest(`${ws.config.title} · 家长`, { startUrl: '/parent', scope: '/parent' }), contentType: 'application/manifest+json; charset=utf-8' };
+        return { status: 404, json: { error: 'not_found', path: p } };
+    }
+    catch (err) {
+        if (err instanceof BusyError)
+            return { status: 409, json: { error: 'busy', message: err.message } };
+        if (err instanceof RuntimeError)
+            return { status: 400, json: { error: 'bad_runtime', message: err.message } };
+        if (err instanceof ConfigError)
+            return { status: 422, json: { error: 'config', message: err.message } };
+        if (err instanceof IndexError)
+            return { status: 500, json: { error: 'index', message: err.message } };
+        if (err instanceof UsageError)
+            return { status: 400, json: { error: 'usage', message: err.message } };
+        throw err;
+    }
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        size += c.length;
+        if (size > 6_000_000)
+            throw new UsageError('请求体超过 6MB');
+        chunks.push(c);
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    if (!text.trim())
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UsageError('请求体不是合法 JSON');
+    }
+}
+/**
+ * 发文件(配音、图、小课堂的视频……):都带 accept-ranges 与长度;GET 带单段 Range → 206 只发那一段(iPad Safari 放视频非这样不可,
+ * 先要 bytes=0-1,拿不到 206 就不放;音频拖动也靠它),起点越界 416;HEAD 只发头。文件读之前没了 → 404
+ */
+/** 这个进程的启动号:每个 JSON 响应都带(x-cotutor-boot)。页面轮询时见它变了 = 服务重起过(多半是换了新代码),空下来就自己重载——iPad 上下拉刷新常拉不到位 */
+const BOOT = Date.now().toString(36);
+export function createHandler(ctx) {
+    return (req, res) => {
+        void (async () => {
+            let r;
+            try {
+                const body = req.method === 'GET' || req.method === 'HEAD' ? undefined : await readBody(req);
+                // HEAD 照 GET 走路由;Node 对 HEAD 的响应本来就不发正文
+                r = await route(req.method === 'HEAD' ? 'GET' : (req.method ?? 'GET'), req.url ?? '/', ctx, body, await ctx.access.whoOf(req), { device: cookieOf(req.headers.cookie, DEVICE_COOKIE), ip: req.socket.remoteAddress });
+            }
+            catch (err) {
+                r = err instanceof UsageError ? { status: 400, json: { error: 'usage', message: err.message } } : { status: 500, json: { error: 'internal', message: err instanceof Error ? err.message : String(err) } };
+                if (r.status === 500)
+                    console.error(err);
+            }
+            if (r.file !== undefined)
+                await sendFile(req, res, r);
+            else if (r.body !== undefined) {
+                res.writeHead(r.status, { 'content-type': r.contentType ?? 'application/octet-stream', 'cache-control': r.cacheControl ?? 'private, max-age=86400' });
+                res.end(Buffer.from(r.body));
+            }
+            else if (r.html !== undefined) {
+                res.writeHead(r.status, { 'content-type': r.contentType ?? 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+                res.end(r.html);
+            }
+            else {
+                res.writeHead(r.status, { 'content-type': r.contentType ?? 'application/json; charset=utf-8', 'cache-control': r.cacheControl ?? 'no-store', 'x-cotutor-boot': BOOT, ...(r.setCookie ? { 'set-cookie': r.setCookie } : {}) });
+                res.end(JSON.stringify(r.json ?? null));
+            }
+        })();
+    };
+}