cotutor 0.2.0 → 0.3.0

package/dist/app/cli/chalk/dub.js

@@ -0,0 +1,106 @@
+/**
+ * dub:课包配音。manifest 各步的讲稿 → 配音(src/media/tts.ts,和卡的配音同一条线、同一份缓存)→ bundles/<id>/audio/step-<n>.mp3 →
+ * audio/index.json(步 ↔ 文件 ↔ 讲稿 hash ↔ 时长)→ 回填 manifest 的 audioSrc / audioDurationMs。
+ * 课包自包含不变(audio/ 是拷贝,iPad 整目录离线播)。讲稿与音色都没变的步不重配;变了的去合成(缓存里有就不花钱)。
+ * 时长从 mp3 帧头量(src/media/mp3.ts):播放器按它把这一步的笔画拉伸到讲稿那么长。
+ * 2026-10-31 以前是起 voxtell batch;audio/index.json 的格式与 schema 名(drawtell-audio)照旧,已经配好的课包不用重配。
+ */
+import { createHash } from 'node:crypto';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stretchToAudio } from "../../../chalk/timeline.js";
+import { mp3DurationMs } from "../../../media/mp3.js";
+import { synthesize, ttsModelOf } from "../../../media/tts.js";
+/** 讲稿 hash:build 用它判断 audio/ 里的音频是否仍对应当前讲稿(讲稿改了 = 音频失效,不回填) */
+export function lineHash(line) {
+    return createHash('sha1').update(line).digest('hex').slice(0, 16);
+}
+const estimate = (text) => [...text].reduce((n, ch) => n + (/\p{Script=Han}/u.test(ch) ? 2 : 1), 0);
+async function exists(p) {
+    return access(p).then(() => true, () => false);
+}
+async function readIndex(bundleDir) {
+    try {
+        const index = JSON.parse(await readFile(join(bundleDir, 'audio', 'index.json'), 'utf8'));
+        return index?.schema === 'drawtell-audio' && Array.isArray(index.steps) ? index : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function dubBundle(o) {
+    const audioDir = join(o.bundleDir, 'audio');
+    const old = await readIndex(o.bundleDir);
+    const sameVoice = old !== null && old.voice === o.voice && (old.instruction ?? null) === (o.instruction ?? null);
+    const steps = [];
+    for (const s of o.scene.steps) {
+        const file = `step-${s.step}.mp3`;
+        const prev = sameVoice ? old.steps.find((x) => x.step === s.step && x.textHash === lineHash(s.line)) : undefined;
+        const characters = estimate(s.line);
+        if (prev && (await exists(join(audioDir, prev.file)))) {
+            steps.push({ step: s.step, file: prev.file, kept: true, characters, durationMs: prev.durationMs });
+            continue;
+        }
+        if (o.dryRun) {
+            steps.push({ step: s.step, file: null, kept: false, characters, durationMs: null });
+            continue;
+        }
+        await mkdir(audioDir, { recursive: true });
+        const r = await synthesize({ text: s.line, voice: o.voice, instruction: o.instruction, out: join(audioDir, file) }, { cacheDir: o.cacheDir, env: o.env });
+        if (!r.file)
+            steps.push({ step: s.step, file: null, kept: false, characters, durationMs: null, error: r.error ?? '?' });
+        else
+            steps.push({ step: s.step, file, kept: false, characters, durationMs: mp3DurationMs(new Uint8Array(await readFile(r.file))) });
+    }
+    const pacing = stretchToAudio(o.scene.skeletons, o.scene.steps, { durations: steps.map((x) => x.durationMs) }).info;
+    const result = {
+        ok: !steps.some((x) => x.error),
+        dryRun: Boolean(o.dryRun),
+        characters: steps.filter((x) => !x.kept).reduce((n, x) => n + x.characters, 0),
+        steps,
+        pacing,
+        manifestUpdated: false,
+    };
+    if (o.dryRun || !result.ok)
+        return result;
+    const index = {
+        schema: 'drawtell-audio',
+        version: 1,
+        voice: o.voice,
+        model: ttsModelOf(o.voice),
+        instruction: o.instruction ?? null,
+        steps: o.scene.steps.map((s, i) => ({ step: s.step, file: `step-${s.step}.mp3`, textHash: lineHash(s.line), characters: steps[i].characters, durationMs: steps[i].durationMs })),
+    };
+    await writeFile(join(audioDir, 'index.json'), `${JSON.stringify(index, null, 2)}\n`);
+    // 回填 manifest.audioSrc(build 也会按 audio/index.json 回填,这里让当前课包立刻可播)
+    const manifestPath = join(o.bundleDir, 'manifest.json');
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    manifest.steps = manifest.steps.map((s) => {
+        const d = steps.find((x) => x.step === s.step)?.durationMs;
+        return { ...s, audioSrc: `audio/step-${s.step}.mp3`, ...(d ? { audioDurationMs: d } : {}) };
+    });
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    result.manifestUpdated = true;
+    return result;
+}
+/** build 用:audio/index.json 里讲稿 hash 仍匹配的步,回填 audioSrc;讲稿改了的步不回填(等重新 dub) */
+export async function attachAudio(bundleDir, manifest) {
+    const index = await readIndex(bundleDir);
+    if (!index)
+        return 0;
+    let n = 0;
+    for (const s of manifest.steps) {
+        if (s.audioSrc)
+            continue; // 场景作者显式给的优先
+        const e = index.steps.find((x) => x.step === s.step);
+        if (!e || e.textHash !== lineHash(s.line))
+            continue;
+        if (!(await exists(join(bundleDir, 'audio', e.file))))
+            continue;
+        s.audioSrc = `audio/${e.file}`;
+        if (e.durationMs)
+            s.audioDurationMs = e.durationMs;
+        n++;
+    }
+    return n;
+}

package/dist/app/cli/chalk/load-scene.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 阶梯层 1:把场景源变成对象。两条创作路,同一收敛点(checkScene):
+ * - TS 纯数据模块(讲解场景;依赖 Node ≥22.18 原生 type stripping,类型用 import type)
+ * - 双文件目录(生成器/excalidraw 编辑器产物):scene.excalidraw(画面)+ scene.json(信封:
+ *   除 skeletons 外的全部 ChalkScene 字段——id/title/blocks/subscenes…)
+ */
+/** 调用方给错了(路径不存在)→ exit 2 */
+export declare class NotFoundError extends Error {
+}
+/** 场景文件本身有问题(求值失败/没导出场景)→ exit 1 */
+export declare class LoadError extends Error {
+}
+/** 双文件场景源的固定文件名(约定即引用) */
+export declare const ENVELOPE_FILE = "scene.json";
+export declare const EXCALIDRAW_FILE = "scene.excalidraw";
+/** 输入分发:目录或 scene.json 路径 = 双文件;其余 = TS 模块 */
+export declare function resolveSceneInput(file: string): Promise<{
+    kind: 'ts';
+} | {
+    kind: 'files';
+    dir: string;
+}>;
+/**
+ * 双文件 → 与 TS 路同形的 raw 对象:信封字段 + skeletons(excalidraw 元素,滤掉 isDeleted)。
+ * 深校验不在这里——合并后的对象走 checkScene(schema + lint),错误信息同一套。
+ */
+export declare function loadSceneFiles(dir: string): Promise<{
+    raw: unknown;
+    exportName: string;
+}>;
+export declare function loadScene(file: string): Promise<{
+    raw: unknown;
+    exportName: string;
+}>;

package/dist/app/cli/chalk/load-scene.js

@@ -0,0 +1,117 @@
+/**
+ * 阶梯层 1:把场景源变成对象。两条创作路,同一收敛点(checkScene):
+ * - TS 纯数据模块(讲解场景;依赖 Node ≥22.18 原生 type stripping,类型用 import type)
+ * - 双文件目录(生成器/excalidraw 编辑器产物):scene.excalidraw(画面)+ scene.json(信封:
+ *   除 skeletons 外的全部 ChalkScene 字段——id/title/blocks/subscenes…)
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** 调用方给错了(路径不存在)→ exit 2 */
+export class NotFoundError extends Error {
+}
+/** 场景文件本身有问题(求值失败/没导出场景)→ exit 1 */
+export class LoadError extends Error {
+}
+/** 双文件场景源的固定文件名(约定即引用) */
+export const ENVELOPE_FILE = 'scene.json';
+export const EXCALIDRAW_FILE = 'scene.excalidraw';
+/** 输入分发:目录或 scene.json 路径 = 双文件;其余 = TS 模块 */
+export async function resolveSceneInput(file) {
+    const abs = resolve(file);
+    let st;
+    try {
+        st = await stat(abs);
+    }
+    catch {
+        throw new NotFoundError(`找不到场景源:${file}。TS 场景通常在 scenes/ 下(如 scenes/dengche.ts);双文件场景给目录(内含 ${ENVELOPE_FILE} + ${EXCALIDRAW_FILE})`);
+    }
+    if (st.isDirectory())
+        return { kind: 'files', dir: abs };
+    if (basename(abs) === ENVELOPE_FILE)
+        return { kind: 'files', dir: dirname(abs) };
+    return { kind: 'ts' };
+}
+async function readJsonFile(path, what) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        throw new NotFoundError(`双文件场景缺 ${basename(path)}(${what}):${path} 不存在。${ENVELOPE_FILE} 与 ${EXCALIDRAW_FILE} 必须同目录`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new LoadError(`${basename(path)} 不是合法 JSON:${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * 双文件 → 与 TS 路同形的 raw 对象:信封字段 + skeletons(excalidraw 元素,滤掉 isDeleted)。
+ * 深校验不在这里——合并后的对象走 checkScene(schema + lint),错误信息同一套。
+ */
+export async function loadSceneFiles(dir) {
+    const envelope = await readJsonFile(join(dir, ENVELOPE_FILE), '信封');
+    const exca = await readJsonFile(join(dir, EXCALIDRAW_FILE), '画面');
+    if (typeof envelope !== 'object' || envelope === null || Array.isArray(envelope)) {
+        throw new LoadError(`${ENVELOPE_FILE} 应是对象(场景源信封),拿到 ${Array.isArray(envelope) ? '数组' : typeof envelope}`);
+    }
+    const env = envelope;
+    if (env.schema !== 'chalk-scene-src') {
+        throw new LoadError(`${ENVELOPE_FILE} 的 schema 应为 'chalk-scene-src'(场景源信封),拿到 '${String(env.schema)}'。` +
+            `注意:课包产物里的 scene.json 是 'chalk-scene',不能当场景源再 build`);
+    }
+    if (env.version !== 1) {
+        throw new LoadError(`${ENVELOPE_FILE} 的 version 应为 1,拿到 ${String(env.version)}`);
+    }
+    if ('skeletons' in env) {
+        throw new LoadError(`信封不含画面:skeletons 来自 ${EXCALIDRAW_FILE},从 ${ENVELOPE_FILE} 里删掉 skeletons 字段`);
+    }
+    const ex = exca;
+    if (typeof exca !== 'object' || exca === null || ex.type !== 'excalidraw' || !Array.isArray(ex.elements)) {
+        throw new LoadError(`${EXCALIDRAW_FILE} 应是标准 excalidraw 文件(type: 'excalidraw' + elements 数组);用编辑器或生成器导出`);
+    }
+    const { schema: _s, version: _v, ...fields } = env;
+    const skeletons = ex.elements.filter((el) => !(typeof el === 'object' && el !== null && el.isDeleted));
+    return { raw: { ...fields, skeletons }, exportName: `${ENVELOPE_FILE}+${EXCALIDRAW_FILE}` };
+}
+export async function loadScene(file) {
+    const abs = resolve(file);
+    try {
+        await stat(abs);
+    }
+    catch {
+        throw new NotFoundError(`找不到场景文件:${file}。检查路径;场景文件通常在 scenes/ 下,如 scenes/dengche.ts`);
+    }
+    let mod;
+    try {
+        mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(abs).href)));
+    }
+    catch (err) {
+        throw new LoadError(`场景模块求值失败(层 1):${err instanceof Error ? err.message : String(err)}\n` +
+            '场景文件须是纯数据模块:类型用 import type 引入,不要 import 运行时值。');
+    }
+    if (mod.default && typeof mod.default === 'object') {
+        return { raw: mod.default, exportName: 'default' };
+    }
+    const names = Object.keys(mod).filter((k) => k !== 'default');
+    const sceneish = names.filter((k) => {
+        const v = mod[k];
+        return typeof v === 'object' && v !== null && 'skeletons' in v && 'steps' in v;
+    });
+    if (sceneish.length === 1)
+        return { raw: mod[sceneish[0]], exportName: sceneish[0] };
+    if (sceneish.length === 0) {
+        throw new LoadError(`模块没有导出场景对象(需含 skeletons 与 steps 字段)。现有导出:${names.join(', ') || '(无)'}。用 export default 或单个具名导出。`);
+    }
+    throw new LoadError(`模块导出了多个场景(${sceneish.join(', ')}),无法确定目标。一个文件一个场景,或用 export default 指定。`);
+}

package/dist/app/cli/chalk/main.d.ts

@@ -0,0 +1,7 @@
+type Flags = Record<string, string | true>;
+export declare const CHALK_USAGE = "\u7528\u6CD5:\n  cotutor chalk check <scene.ts|\u76EE\u5F55> [--no-types] [--json]\n  cotutor chalk build <scene.ts|\u76EE\u5F55> [--out <dir>] [--json]\n  cotutor chalk bake <scene.ts|\u8BFE\u5305 id> [--bundles <dir>] [--json]\n  cotutor chalk snap <scene.ts|\u8BFE\u5305 id> [--step <n>] [--no-cursor] [--out <dir>] [--bundles <dir>] [--json]\n  cotutor chalk dub <scene.ts|\u8BFE\u5305 id> [--voice <\u97F3\u8272>] [--tutor <\u8001\u5E08>] [--instruction <\u8BED\u6C14>] [--dry-run] [--bundles <dir>] [--json]\n\u8BFE\u5305\u7F3A\u7701\u5728 workspace \u7684 bundles/(--bundles \u6362);\u573A\u666F\u6E90\u4E0E --out / --bundles \u7684\u76F8\u5BF9\u8DEF\u5F84\u6309\u5F53\u524D\u76EE\u5F55\u3002\n";
+export declare function chalkCommand(args: string[], flags: Flags, opts: {
+    workspace?: string;
+    json: boolean;
+}): Promise<void>;
+export {};

package/dist/app/cli/chalk/main.js

@@ -0,0 +1,198 @@
+/**
+ * cotutor chalk:做小课堂的课包(2026-10-31 drawtell 并进来,原来的 drawtell CLI 只留做课包这五样;workspace、课包目录、音色都照 cotutor 的)。
+ *   check <scene.ts|目录> [--no-types]       类型(内嵌 tsc)→ 求值 → 契约 + 笔顺 + 布局;有错 exit 1
+ *   build <scene.ts|目录> [--out <dir>]      先 check,再出课包目录(scene.json + manifest.json),缺省 <workspace>/bundles/<id>/
+ *   bake  <scene.ts|课包 id> [--bundles <dir>]                  画面烤成 bake.json(本机 Chrome 里跑一次 excalidraw)
+ *   snap  <scene.ts|课包 id> [--step <n>] [--no-cursor] [--out <dir>] [--bundles <dir>]   每步画完那一刻截图 + index.json,缺省 bundles 旁边的 snaps/<id>/;画面没烤顺手烤
+ *   dub   <scene.ts|课包 id> [--voice <音色>] [--tutor <老师>] [--instruction <语气>] [--dry-run] [--bundles <dir>]   每步讲稿配音,回填 manifest
+ * 给 .ts 的 bake / snap / dub 先 check + build;给课包 id 的直接用 bundles 里那份。--json 机器可读,路径脱敏。
+ */
+import { dirname, join, resolve } from 'node:path';
+import { checkScene } from "../../../chalk/check.js";
+import { UsageError, loadWorkspace, redactDeep, redactHome } from "../../workspace.js";
+import { buildBundle, readBundle } from "./build.js";
+import { LoadError, NotFoundError, loadScene, loadSceneFiles, resolveSceneInput } from "./load-scene.js";
+import { typecheckScene } from "./typecheck.js";
+export const CHALK_USAGE = `用法:
+  cotutor chalk check <scene.ts|目录> [--no-types] [--json]
+  cotutor chalk build <scene.ts|目录> [--out <dir>] [--json]
+  cotutor chalk bake <scene.ts|课包 id> [--bundles <dir>] [--json]
+  cotutor chalk snap <scene.ts|课包 id> [--step <n>] [--no-cursor] [--out <dir>] [--bundles <dir>] [--json]
+  cotutor chalk dub <scene.ts|课包 id> [--voice <音色>] [--tutor <老师>] [--instruction <语气>] [--dry-run] [--bundles <dir>] [--json]
+课包缺省在 workspace 的 bundles/(--bundles 换);场景源与 --out / --bundles 的相对路径按当前目录。
+`;
+const str = (v) => (typeof v === 'string' ? v : undefined);
+function report(json, r) {
+    const errors = r.findings.filter((f) => f.level === 'error').length;
+    const warnings = r.findings.filter((f) => f.level === 'warning').length;
+    if (json) {
+        process.stdout.write(`${JSON.stringify(redactDeep({ ...r, errors, warnings }), null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`${r.ok ? `✓ ${r.file} — 通过` : `✗ ${r.file} — ${errors} 错误`}${warnings ? `,${warnings} 警告` : ''}\n`);
+    for (const f of r.findings)
+        process.stdout.write(`  [${f.level}] ${f.rule}: ${f.message}\n`);
+    if (r.bundle)
+        process.stdout.write(`  课包 → ${redactHome(r.bundle)}(${(r.files ?? []).map((p) => p.split('/').pop()).join(' + ')})\n`);
+}
+/** 场景源 → 过了 check 的场景;有错就报、exit 1、给 null */
+async function checkedScene(command, file, json) {
+    const input = await resolveSceneInput(file);
+    const { raw, exportName } = input.kind === 'files' ? await loadSceneFiles(input.dir) : await loadScene(file);
+    const { scene, findings } = checkScene(raw);
+    if (!scene || findings.some((f) => f.level === 'error')) {
+        report(json, { command, file, exportName, ok: false, findings });
+        if (!json)
+            process.stdout.write('  先改好上面的错误再重跑\n');
+        process.exitCode = 1;
+        return null;
+    }
+    return { scene, findings, sourceDir: input.kind === 'files' ? input.dir : dirname(resolve(file)) };
+}
+/** .ts / 场景目录 → 先 check + build 进 bundles;课包 id → 读 bundles 里那份 */
+async function sceneOrBundle(command, file, bundlesDir, json) {
+    if (!file.endsWith('.ts'))
+        return { scene: await readBundle(bundlesDir, file), findings: [] };
+    const c = await checkedScene(command, file, json);
+    if (!c)
+        return null;
+    await buildBundle(c.scene, join(bundlesDir, c.scene.id), c.sourceDir);
+    return c;
+}
+export async function chalkCommand(args, flags, opts) {
+    const [sub, file, ...extra] = args;
+    const json = opts.json;
+    if (!sub || flags.help === true) {
+        process.stdout.write(CHALK_USAGE);
+        return;
+    }
+    if (!file)
+        throw new UsageError(`cotutor chalk ${sub} 要一个场景文件(或课包 id)。\n${CHALK_USAGE}`);
+    if (extra.length)
+        throw new UsageError(`多余的参数 '${extra[0]}'。\n${CHALK_USAGE}`);
+    const bundlesOf = () => (str(flags.bundles) ? resolve(str(flags.bundles)) : loadWorkspace(opts.workspace).dirs.bundles);
+    try {
+        switch (sub) {
+            case 'check': {
+                const input = await resolveSceneInput(file);
+                // 类型先跑,错了也往下:一次拿全各层的问题;场景目录是 JSON,没有类型层
+                const types = flags['no-types'] === true || input.kind === 'files' ? { ran: false, findings: [] } : await typecheckScene(file);
+                let exportName;
+                let structural;
+                try {
+                    const loaded = input.kind === 'files' ? await loadSceneFiles(input.dir) : await loadScene(file);
+                    exportName = loaded.exportName;
+                    structural = checkScene(loaded.raw).findings;
+                }
+                catch (err) {
+                    if (!(err instanceof LoadError))
+                        throw err;
+                    structural = [{ level: 'error', rule: 'load', message: err.message }];
+                }
+                const findings = [...types.findings, ...structural];
+                const ok = !findings.some((f) => f.level === 'error');
+                report(json, { command: 'check', file, exportName, ok, findings, typesChecked: types.ran });
+                if (!ok)
+                    process.exitCode = 1;
+                return;
+            }
+            case 'build': {
+                const c = await checkedScene('build', file, json);
+                if (!c)
+                    return;
+                const outDir = str(flags.out) ? resolve(str(flags.out)) : join(bundlesOf(), c.scene.id);
+                const files = await buildBundle(c.scene, outDir, c.sourceDir);
+                report(json, { command: 'build', file, ok: true, findings: c.findings, bundle: outDir, files });
+                return;
+            }
+            case 'bake': {
+                const bundlesDir = bundlesOf();
+                const s = await sceneOrBundle('bake', file, bundlesDir, json);
+                if (!s)
+                    return;
+                const { bakeBundles } = await import("./bake.js");
+                const [r] = await bakeBundles(bundlesDir, [s.scene.id]);
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep({ command: 'bake', file, ok: true, scene: s.scene.id, bake: r.file, elements: r.elements, bytes: r.bytes, findings: s.findings }), null, 2)}\n`);
+                else {
+                    process.stdout.write(`✓ ${file} — ${r.elements} 个元素 → ${redactHome(r.file)}(${Math.round(r.bytes / 1024)} KB)\n`);
+                    for (const f of s.findings)
+                        process.stdout.write(`  [${f.level}] ${f.rule}: ${f.message}\n`);
+                }
+                return;
+            }
+            case 'snap': {
+                const bundlesDir = bundlesOf();
+                const s = await sceneOrBundle('snap', file, bundlesDir, json);
+                if (!s)
+                    return;
+                const { scene } = s;
+                let step;
+                if (flags.step !== undefined) {
+                    step = Number(flags.step);
+                    if (!Number.isInteger(step) || step < 0 || step > scene.steps.length)
+                        throw new UsageError(`--step 要 0–${scene.steps.length} 的整数(0 = 空板),拿到 '${String(flags.step)}'`);
+                }
+                const outDir = str(flags.out) ? resolve(str(flags.out)) : join(dirname(bundlesDir), 'snaps', scene.id);
+                // 截图要开浏览器,顺手把画面烤了(bake.json 没有或画面变了)
+                const { bakeBundles, bakeIsFresh } = await import("./bake.js");
+                const baked = (await bakeIsFresh(join(bundlesDir, scene.id))) ? null : (await bakeBundles(bundlesDir, [scene.id]))[0];
+                const { snapScene } = await import("./snap.js");
+                const cursor = flags['no-cursor'] !== true;
+                const shots = await snapScene({ scene, bundlesDir, outDir, step, cursor });
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep({ command: 'snap', file, ok: true, scene: scene.id, outDir, cursor, findings: s.findings, shots, ...(baked ? { bake: baked.file } : {}) }), null, 2)}\n`);
+                else {
+                    process.stdout.write(`✓ ${file} — ${shots.length} 张 → ${redactHome(outDir)}/(${shots.map((x) => `step-${x.step}.png`).join(' ')} + index.json${step != null ? ',已合并' : ''}${cursor ? '' : ',无笔尖'})${baked ? `;画面烤好了 → ${redactHome(baked.file)}` : ''}\n`);
+                    for (const f of s.findings)
+                        process.stdout.write(`  [${f.level}] ${f.rule}: ${f.message}\n`);
+                }
+                return;
+            }
+            case 'dub': {
+                const ws = loadWorkspace(opts.workspace);
+                const bundlesDir = str(flags.bundles) ? resolve(str(flags.bundles)) : ws.dirs.bundles;
+                const tutor = str(flags.tutor) ?? 'math-tutor';
+                const voice = str(flags.voice) ?? ws.config.tutors[tutor]?.voice;
+                if (!voice)
+                    throw new UsageError(`没有音色:--voice <音色>,或 --tutor <老师>(缺省 math-tutor)在 cotutor.json 里配了卡的音色(工作台「音色」页挑)`);
+                const s = await sceneOrBundle('dub', file, bundlesDir, json);
+                if (!s)
+                    return;
+                const { dubBundle } = await import("./dub.js");
+                const r = await dubBundle({ scene: s.scene, bundleDir: join(bundlesDir, s.scene.id), voice, instruction: str(flags.instruction), dryRun: flags['dry-run'] === true, cacheDir: ws.dirs.tts });
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep({ command: 'dub', file, scene: s.scene.id, voice, findings: s.findings, ...r }), null, 2)}\n`);
+                else {
+                    const failed = r.steps.filter((x) => x.error).length;
+                    process.stdout.write(`${r.ok ? '✓' : '✗'} ${s.scene.id} — ${r.dryRun ? '算账(没合成)' : r.ok ? '配音好了' : `${failed} 步没配上`}:${r.steps.length} 步,约 ${r.characters} 计费字符,要合成 ${r.steps.filter((x) => !x.kept).length} 步\n`);
+                    for (const st of r.steps) {
+                        const pc = r.pacing.find((p) => p.step === st.step);
+                        const pace = pc && pc.audioMs ? `  音 ${(pc.audioMs / 1000).toFixed(1)}s / 画 ${(pc.drawMs / 1000).toFixed(1)}s${pc.factor > 1 ? ` → 拉伸 ×${pc.factor.toFixed(1)}` : ''}${pc.audioMs / pc.drawMs > 5 ? '  ⚠ 超过封顶 5 倍:讲稿太长或这步画得太少' : ''}` : '';
+                        process.stdout.write(`  ${st.error ? '✗' : st.kept ? '=' : r.dryRun ? '+' : '↑'} step-${st.step}  ${st.characters} 字${pace}${st.error ? `  ${st.error}` : ''}\n`);
+                    }
+                    if (r.manifestUpdated)
+                        process.stdout.write('  manifest.json 已回填 audioSrc\n');
+                    for (const f of s.findings)
+                        process.stdout.write(`  [${f.level}] ${f.rule}: ${f.message}\n`);
+                }
+                if (!r.ok)
+                    process.exitCode = 1;
+                return;
+            }
+            default:
+                throw new UsageError(`cotutor chalk 没有 '${sub}'。\n${CHALK_USAGE}`);
+        }
+    }
+    catch (err) {
+        // 找不到场景 / 课包是用法问题;场景求值失败是场景的问题(exit 1)
+        if (err instanceof NotFoundError)
+            throw new UsageError(err.message);
+        if (err instanceof LoadError) {
+            report(json, { command: sub, file, ok: false, findings: [{ level: 'error', rule: 'load', message: err.message }] });
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+}

package/dist/app/cli/chalk/serve.d.ts

@@ -0,0 +1,4 @@
+export declare function startPageServer(bundlesDir: string): Promise<{
+    origin: string;
+    close(): Promise<void>;
+}>;

package/dist/app/cli/chalk/serve.js

@@ -0,0 +1,28 @@
+/**
+ * bake / snap 在浏览器里开的那一页从哪来:临时起一个只听本机的 HTTP 服务,给舞台包(/stage/,和 serve 同一份 dist/stage/ 与字体)
+ * 与课包目录(/api/bundles/<id>/…,和 serve 同一条路)。舞台的 ?chalk=bake / ?chalk=snap 两种样子在 src/ui/stage/chalk/tool.ts。
+ */
+import { createReadStream } from 'node:fs';
+import { createServer } from 'node:http';
+import { bundleAsset, stageAsset, stageBuilt } from "../../http/stage.js";
+import { UsageError } from "../../workspace.js";
+export async function startPageServer(bundlesDir) {
+    if (!stageBuilt())
+        throw new UsageError('舞台包不在(dist/stage/):仓库根 pnpm run build:stage(npm 装的包自带)');
+    const server = createServer((req, res) => {
+        const path = decodeURIComponent(new URL(req.url ?? '/', 'http://x').pathname);
+        void (path.startsWith('/stage/') ? stageAsset(path) : bundleAsset(bundlesDir, path)).then((f) => {
+            if (!f) {
+                res.writeHead(404).end();
+                return;
+            }
+            res.writeHead(200, { 'content-type': f.contentType, 'cache-control': 'no-store' });
+            createReadStream(f.file).pipe(res);
+        }, () => res.writeHead(500).end());
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    return {
+        origin: `http://127.0.0.1:${server.address().port}`,
+        close: () => new Promise((resolve) => { server.closeAllConnections(); server.close(() => resolve()); }),
+    };
+}

package/dist/app/cli/chalk/snap.d.ts

@@ -0,0 +1,65 @@
+/**
+ * snap:阶梯层 4 —— 起临时页面服务(./serve.ts)与本机 Chrome(./browser.ts),逐步打开舞台的 ?chalk=snap&step=<n> 截 keyframe。
+ * 走真浏览器 + 孩子端同一个渲染(src/ui/stage/chalk/render.ts 画烤好的画面):截到的和孩子看到的零偏差。
+ * 产物:<out>/step-<n>.png(n=0 空板起,0 号图配题面)+ index.json(图↔讲稿对照,给检验 skill 吃)。
+ * index.json 里每张图还带该步新增元素清单(id/type/color/text/bbox)与画板 viewBox:
+ * 检验方不读源码也能按 id 报问题、按坐标核对计数与越界。
+ * `--step n` 只重截一步时,index.json 与已有内容合并(只换那一步),不覆盖整份对照表。
+ */
+import type { ChalkScene } from '../../../chalk/types.ts';
+export interface SnapOptions {
+    scene: ChalkScene;
+    bundlesDir: string;
+    outDir: string;
+    /** 只截这一步(0 = 空板);缺省 0..steps 全截 */
+    step?: number;
+    /** 画不画笔尖(默认画);检验用 keyframe 建议关掉,只剩笔迹 */
+    cursor?: boolean;
+}
+/** 该步新增的一个元素:给检验方按 id 说话、按坐标数数;bbox 是 check 的近似包围盒(场景坐标) */
+export interface AddedElement {
+    id: string;
+    type: string;
+    strokeColor?: string;
+    /** 有填充(涂色)时给出 */
+    backgroundColor?: string;
+    fillStyle?: string;
+    strokeStyle?: string;
+    text?: string;
+    /** 动作(erase / board)没有 */
+    bbox?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** 动作擦掉的元素 id(erase 写的 targets;board = 旧板上还在的全部) */
+    erases?: string[];
+}
+export interface Shot {
+    step: number;
+    file: string;
+    /** 该步讲稿(step 0 为题面):检验 skill 逐张对照"画面 ↔ 讲稿" */
+    line: string;
+    /** 该步新增元素(step 0 为空) */
+    added: AddedElement[];
+    /** 这张图截的时候画没画笔尖(单步重截可能与其他步不同) */
+    cursor: boolean;
+    /** 这张图的 viewBox(换过画板的课每块板不一样;bbox 换算按它) */
+    viewBox?: [number, number, number, number];
+}
+export interface SnapIndex {
+    schema: 'drawtell-snaps';
+    version: 2;
+    scene: string;
+    title: string;
+    problem: string;
+    /** 播放器 SVG 的 viewBox(场景坐标 + 出图留白):元素 bbox 与图像像素的换算依据;换过画板的课以每张图自己的 viewBox 为准 */
+    board: {
+        viewBox: [number, number, number, number];
+    } | null;
+    shots: Array<Omit<Shot, 'file'> & {
+        file: string;
+    }>;
+}
+export declare function snapScene({ scene, bundlesDir, outDir, step, cursor }: SnapOptions): Promise<Shot[]>;