cotutor 0.2.0 → 0.3.0

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 { logParser, 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, m.runtime);
+    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(() => ''), logParser(ws.config.runtimes, m.runtime))).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/machine/bailian.d.ts

@@ -0,0 +1,28 @@
+import type { Who } from '../http/access.ts';
+import type { AppContext, RouteResult } from '../http/app.ts';
+export interface BailianAuth {
+    key: string;
+    workspaceId: string;
+}
+export interface BailianStatus {
+    /** 孩子端能用:按量 key 与业务空间 id 都有(或指了假端点) */
+    ready: boolean;
+    /** 用的那份是哪来的:parent = 家长端配的;machine = 这台电脑别处配的(环境变量、qwen、voxtell);null = 没有 */
+    from: 'parent' | 'machine' | null;
+    /** key 的末四位(不回显整把) */
+    keyTail: string | null;
+    workspaceId: string | null;
+}
+export interface Bailian {
+    status(): BailianStatus;
+    /** 试连;不给 auth 就用现在那份。null = 通 */
+    probe(auth?: BailianAuth): Promise<string | null>;
+    save(auth: BailianAuth): Promise<void>;
+}
+export declare function createBailian(opts?: {
+    env?: NodeJS.ProcessEnv;
+    probe?: (auth?: BailianAuth) => Promise<string | null>;
+}): Bailian;
+/** 试连没通的原因,写给家长看 */
+export declare function probeMessage(why: string): string;
+export declare function bailianRoute(method: string, p: string, ctx: AppContext, body: unknown, who: Who): Promise<RouteResult | null>;

package/dist/app/machine/bailian.js

@@ -0,0 +1,88 @@
+/**
+ * 百炼:孩子端的老师靠实时模型开口,没配百炼孩子端打不开,家长在家长端「首页」里配。
+ * 配的是按量的 key + 业务空间 id(Token Plan 的 `sk-sp-` 没有 realtime;端点要业务空间 id 的域名)。
+ * 存机器级 ~/.config/cotutor/bailian.json(0600,同 PIN、证书,几个孩子的 workspace 共用),不进 cotutor.json:
+ * workspace 是 git 仓,工作台的 PATCH /api/config 也能改它。读的顺序(家长端配的在最前)见 src/shared/qianwen.ts。
+ *
+ *   GET  /api/parent/bailian        {ready, from, keyTail, workspaceId, canEdit}
+ *   PUT  /api/parent/bailian        {key, workspaceId}:先试连,通了才存;回 GET 那份 + ms
+ *   POST /api/parent/bailian/test   拿现在用的那份试连一次:{ok, ms, message?}
+ *
+ * 改 key 要么在这台电脑上(本机免密),要么设了家长密码:没设 PIN 时局域网谁都进得了家长端,不让别的设备往这台电脑写 key。
+ * 测试与探针指了假的实时端点(COTUTOR_LIVE_ENDPOINT)就当配好了,试连也连那个。
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { bailianFile, cotutorBailian } from "../../shared/qianwen.js";
+import { dashscopeAuth } from "../../realtime/bailian.js";
+import { probeRealtime } from "../../realtime/preview.js";
+export function createBailian(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = env.HOME || homedir();
+    const fake = env.COTUTOR_LIVE_ENDPOINT || undefined;
+    return {
+        status() {
+            const auth = dashscopeAuth(env);
+            if (!auth)
+                return { ready: Boolean(fake), from: null, keyTail: null, workspaceId: null };
+            const mine = cotutorBailian(home);
+            return { ready: true, from: mine.apiKey === auth.key && mine.workspaceId === auth.workspaceId ? 'parent' : 'machine', keyTail: auth.key.slice(-4), workspaceId: auth.workspaceId };
+        },
+        probe: opts.probe ?? ((auth) => probeRealtime({ auth, env, endpoint: fake })),
+        async save(auth) {
+            const file = bailianFile(home);
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, `${JSON.stringify({ apiKey: auth.key, workspaceId: auth.workspaceId, at: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+        },
+    };
+}
+/** 试连没通的原因,写给家长看 */
+export function probeMessage(why) {
+    if (why === 'no_auth')
+        return '还没配 key 和业务空间 id';
+    if (why === 'connect' || why.startsWith('connect:') || why.startsWith('closed:'))
+        return '连不上:key 或业务空间 id 不对,或者这台电脑上不了网';
+    if (why === 'timeout')
+        return '连上了,等不到回音(超时),过一会儿再试';
+    return `百炼说:${why}`;
+}
+const KEY_RE = /^sk-[A-Za-z0-9._-]{16,}$/;
+const WS_RE = /^[A-Za-z0-9][A-Za-z0-9-]{2,62}$/;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const bad = (message) => ({ status: 400, json: { error: 'bad_request', message } });
+export async function bailianRoute(method, p, ctx, body, who) {
+    if (p !== '/api/parent/bailian' && p !== '/api/parent/bailian/test')
+        return null;
+    const canEdit = who === 'local' || (await ctx.access.pinSet());
+    const view = () => ({ ...ctx.bailian.status(), canEdit });
+    if (p === '/api/parent/bailian/test') {
+        if (method !== 'POST')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        const t0 = Date.now();
+        const why = await ctx.bailian.probe();
+        return { status: 200, json: { ok: why === null, ms: Date.now() - t0, ...(why === null ? {} : { message: probeMessage(why) }) } };
+    }
+    if (method === 'GET')
+        return { status: 200, json: view() };
+    if (method !== 'PUT')
+        return { status: 405, json: { error: 'method_not_allowed' } };
+    if (!canEdit)
+        return { status: 403, json: { error: 'need_pin', message: '先设家长密码(在电脑上跑 cotutor pin),或者在这台电脑上打开家长端来配' } };
+    if (!isObj(body))
+        return bad('要 {key, workspaceId}');
+    const key = typeof body.key === 'string' ? body.key.trim() : '';
+    const workspaceId = typeof body.workspaceId === 'string' ? body.workspaceId.trim() : '';
+    if (key.startsWith('sk-sp-'))
+        return bad('这是 Token Plan 的 key(sk-sp- 开头),老师开口要百炼按量的 key(sk- 开头)');
+    if (!KEY_RE.test(key))
+        return bad('key 不像百炼的 API key(sk- 开头)');
+    if (!WS_RE.test(workspaceId))
+        return bad('业务空间 id 不对(百炼控制台「业务空间」里那串,只有字母、数字、横线)');
+    const t0 = Date.now();
+    const why = await ctx.bailian.probe({ key, workspaceId });
+    if (why !== null)
+        return { status: 400, json: { error: 'probe_failed', message: probeMessage(why) } };
+    await ctx.bailian.save({ key, workspaceId });
+    return { status: 200, json: { ...view(), ms: Date.now() - t0 } };
+}

package/dist/app/mock/mock-live.d.ts

@@ -0,0 +1,16 @@
+/**
+ * mock 的实时老师(`cotutor mock`;老师都走实时):不经百炼、不花钱看实时老师页。
+ * 协议同 src/runtime/live/call.ts:松手(或打字、拍照、交卡)马上接住一句 → 发一条消息给 mock 的老师(照脚本出节,带 live)→ 老师写完,讲稿一句一句「念」:
+ * 字幕 + 静音的声音(按字数估长短,孩子端照常排着放),read 按孩子端的排法算好时刻发;按下 = 打断(清了,没念的不念)。
+ * 讲稿的 [[play]]:那句念完先停,孩子端放完小课堂那一段(staged)再接着念。没有转写:按住说的当成「(按住说的话)」。
+ * 边画边聊:画板开着时按头像说的(松手带 chat)只接住一句、不交给老师;孩子端觉得该说一句了({t:'chat'})安静时说一句、不安静回 skipped。
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Mock } from './mock.ts';
+/** 按住说的那句(mock 没有转写) */
+export declare const MOCK_LIVE_SAID = "(\u6309\u4F4F\u8BF4\u7684\u8BDD)";
+/** 边画边聊时假嘴说的(mock 不看图):接住孩子画着说的一句、主动说的一句(带上孩子端定的颜色) */
+export declare const MOCK_CHAT_REPLY = "\u55EF,\u4F60\u753B\u5F97\u597D\u8BA4\u771F,\u63A5\u7740\u753B\u5427\u3002";
+export declare const mockChatLook: (color: unknown) => string;
+export declare function mockLiveUpgrade(mock: Mock): (req: IncomingMessage, socket: Duplex, head: Buffer) => boolean;

package/dist/app/mock/mock-live.js

@@ -0,0 +1,140 @@
+import { playsLecture } from "../../board/parse.js";
+import { lineDurationMs, plainLine } from "../../board/presentation.js";
+import { LEAD_MS } from "../../runtime/delivery/playback.js";
+import { acceptWebSocket, isUpgrade } from "../ws/ws.js";
+/** 按住说的那句(mock 没有转写) */
+export const MOCK_LIVE_SAID = '(按住说的话)';
+/** 边画边聊时假嘴说的(mock 不看图):接住孩子画着说的一句、主动说的一句(带上孩子端定的颜色) */
+export const MOCK_CHAT_REPLY = '嗯,你画得好认真,接着画吧。';
+export const mockChatLook = (color) => (typeof color === 'string' && color ? `${color}色画了好多,像一大片。这是什么呀?` : '这一张画了好多,你画的是哪里呀?');
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export function mockLiveUpgrade(mock) {
+    return (req, socket, head) => {
+        const m = /^\/api\/live\/([a-z0-9][a-z0-9-]*)\/ws(?:\?.*)?$/.exec(req.url ?? '');
+        if (!m || !isUpgrade(req))
+            return false;
+        const tutor = m[1];
+        const timers = new Set();
+        /** 孩子端的声音排到哪(墙钟);turn 每打断一次加一,在路上的那一轮看见变了就不念了 */
+        let playEnd = 0;
+        let turn = 0;
+        let holding = false;
+        const clear = () => { for (const t of timers)
+            clearTimeout(t); timers.clear(); };
+        const later = (ms, f) => { const t = setTimeout(() => { timers.delete(t); f(); }, Math.max(0, ms)); timers.add(t); };
+        const sock = acceptWebSocket(req, socket, head, { onText: (x) => onText(x), onBinary: () => { }, onClose: () => { clear(); turn++; } });
+        const send = (o) => { sock.sendText(JSON.stringify(o)); };
+        /** 嘴说一段:字幕 + 静音的声音;回它在孩子端开始放的时刻(上一段放完或到达 + 60 毫秒,取晚的) */
+        const say = (of, text) => {
+            const ms = lineDurationMs(text);
+            const start = Math.max(Date.now() + LEAD_MS, playEnd);
+            playEnd = start + ms;
+            send({ t: 'tutor', of, done: text });
+            sock.sendBinary(Buffer.alloc(Math.round(ms * 48)));
+            return start;
+        };
+        const interrupt = () => {
+            clear();
+            turn++;
+            if (playEnd > Date.now())
+                send({ t: 'flush' });
+            playEnd = 0;
+        };
+        /** 一轮:(拍照先说一句)交给 mock 的老师、写完了一句一句念;别的嘴不先说 */
+        const begin = async (body, caught) => {
+            const my = turn;
+            if (caught)
+                say('catch', caught);
+            const r = await mock.route('POST', `/api/kid/conversations/${tutor}/messages`, { ...body, live: true });
+            if (my !== turn)
+                return;
+            if (r.status !== 202) {
+                send({ t: 'err', status: r.status, error: r.json?.error ?? 'error' });
+                return;
+            }
+            const { job, thread } = r.json;
+            send({ t: 'turn', job, thread });
+            await mock.settleJob(job);
+            if (my !== turn)
+                return;
+            const day = (await mock.route('GET', `/api/kid/conversations/${tutor}/today`)).json;
+            const sec = day.messages.find((x) => x.job === job)?.section;
+            readFrom(job, sec?.lines ?? [], sec?.cards ?? [], 0, my);
+        };
+        /** 讲稿一句一句「念」;[[play]] 那句念完先停,孩子端放完小课堂那一段(staged)再接着念 */
+        let rest = null;
+        const readFrom = (job, lines, cards, from, my) => {
+            for (let i = from; i < lines.length; i++) {
+                const text = plainLine(lines[i].text);
+                const start = say('read', text);
+                const play = playsLecture(lines[i], cards);
+                later(start - Date.now(), () => send({ t: 'read', job, line: i, text, ...(play ? { play: true } : {}) }));
+                if (play) {
+                    rest = () => { if (my === turn)
+                        readFrom(job, lines, cards, i + 1, my); };
+                    return;
+                }
+            }
+        };
+        const onText = (raw) => {
+            let x;
+            try {
+                x = JSON.parse(raw);
+            }
+            catch {
+                return;
+            }
+            switch (x.t) {
+                case 'hold':
+                    holding = true;
+                    interrupt();
+                    send({ t: 'state', speaking: false, holding: true });
+                    break;
+                case 'release':
+                    if (!holding)
+                        return;
+                    holding = false;
+                    send({ t: 'kid', text: MOCK_LIVE_SAID });
+                    // 边画边聊:只接住,不交给老师
+                    if (isObj(x.chat) && typeof x.chat.canvas === 'string') {
+                        say('catch', MOCK_CHAT_REPLY);
+                        break;
+                    }
+                    void begin({ ...(isObj(x.body) ? x.body : {}), text: MOCK_LIVE_SAID }, null);
+                    break;
+                case 'chat':
+                    if (holding || playEnd > Date.now() || typeof x.canvas !== 'string') {
+                        send({ t: 'chat', canvas: x.canvas, skipped: true });
+                        break;
+                    }
+                    say('catch', mockChatLook(isObj(x.ask) ? x.ask.color : null));
+                    send({ t: 'chat', canvas: x.canvas, said: true });
+                    break;
+                case 'hush':
+                    holding = false;
+                    interrupt();
+                    break;
+                case 'staged': {
+                    const r = rest;
+                    rest = null;
+                    r?.();
+                    break;
+                }
+                case 'send': {
+                    if (!isObj(x.body))
+                        return;
+                    const b = x.body;
+                    interrupt();
+                    void begin(b, Array.isArray(b.photos) && b.photos.length ? '我看一看图片' : null);
+                    break;
+                }
+                case 'bye':
+                    sock.close(1000, 'bye');
+                    break;
+                default: break;
+            }
+        };
+        send({ t: 'ready' });
+        return true;
+    };
+}