cotutor 0.2.0 → 0.4.0

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

@@ -0,0 +1,157 @@
+/**
+ * 做课包用的浏览器(2026-10-31 替掉 drawtell 的 playwright):起本机的 Chrome(无头、自己的临时 profile,不碰平时用的那个),
+ * 走 DevTools 协议(CDP)开页面、等、取值、截图。不另装浏览器:烤画面、截图与孩子端是同一种渲染就够。
+ * 每条命令都有超时(回包不来就报错,不挂着);收尾杀进程、删临时 profile,出错也在 finally 里收(scripts/_guard.mjs 那次的教训:无头 Chrome 挂了两天)。
+ * Chrome 在哪:环境变量 CHROME > macOS 的 /Applications/Google Chrome.app > Windows 的 Chrome、再 Edge(装在 Program Files 或自己的 AppData 下,不在 PATH 里)
+ * > PATH 里的 google-chrome / chromium(Windows 带 .exe)。Edge 是 Windows 10/11 自带的 Chromium,CDP 一样,烤出的画面一字不差(2026-11-02 在 Windows 上对过)。
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { UsageError } from "../../workspace.js";
+const MAC_CHROME = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+const PATH_NAMES = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser'];
+/** Windows:先 Chrome 后 Edge,每样依次看全机装的、32 位的、只给自己装的 */
+const WIN_BROWSERS = [['Google', 'Chrome', 'Application', 'chrome.exe'], ['Microsoft', 'Edge', 'Application', 'msedge.exe']];
+const WIN_ROOTS = ['ProgramFiles', 'ProgramFiles(x86)', 'LOCALAPPDATA'];
+/** 一条 CDP 命令最多等多久 */
+const SEND_MS = 60_000;
+/** 本机 Chrome(Windows 上没有 Chrome 就是 Edge)的可执行文件;找不到 null */
+export function chromePath(env = process.env, platform = process.platform) {
+    const set = env.CHROME?.trim();
+    if (set)
+        return existsSync(set) ? set : null;
+    if (platform === 'darwin' && existsSync(MAC_CHROME))
+        return MAC_CHROME;
+    if (platform === 'win32') {
+        for (const parts of WIN_BROWSERS) {
+            for (const root of WIN_ROOTS) {
+                const dir = env[root];
+                if (dir && existsSync(join(dir, ...parts)))
+                    return join(dir, ...parts);
+            }
+        }
+    }
+    const exe = platform === 'win32' ? '.exe' : '';
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        for (const name of PATH_NAMES)
+            if (dir && existsSync(join(dir, name + exe)))
+                return join(dir, name + exe);
+    }
+    return null;
+}
+/** Chrome 起来时在 stderr 报 DevTools 的地址 */
+function devtoolsUrl(chrome) {
+    return new Promise((resolve, reject) => {
+        let err = '';
+        const timer = setTimeout(() => reject(new Error(`Chrome 15 秒没起来:${err.trim().slice(-300)}`)), 15_000);
+        chrome.stderr?.on('data', (d) => {
+            err += d.toString();
+            const m = /DevTools listening on (ws:\/\/\S+)/.exec(err);
+            if (m) {
+                clearTimeout(timer);
+                resolve(m[1]);
+            }
+        });
+        chrome.once('error', (e) => { clearTimeout(timer); reject(e); });
+        chrome.once('exit', (code) => { clearTimeout(timer); reject(new Error(`Chrome 退出了(${code}):${err.trim().slice(-300)}`)); });
+    });
+}
+async function connect(url) {
+    const ws = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+        ws.addEventListener('open', () => resolve(), { once: true });
+        ws.addEventListener('error', () => reject(new Error('连不上 Chrome 的 DevTools')), { once: true });
+    });
+    let seq = 0;
+    const pending = new Map();
+    ws.addEventListener('message', (e) => {
+        const m = JSON.parse(String(e.data));
+        const p = m.id === undefined ? undefined : pending.get(m.id);
+        if (!p)
+            return;
+        pending.delete(m.id);
+        clearTimeout(p.timer);
+        if (m.error)
+            p.reject(new Error(m.error.message));
+        else
+            p.resolve(m.result ?? {});
+    });
+    const send = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
+        const id = ++seq;
+        const timer = setTimeout(() => { pending.delete(id); reject(new Error(`Chrome 没回 ${method}(${SEND_MS / 1000} 秒)`)); }, SEND_MS);
+        pending.set(id, { resolve, reject, timer });
+        ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+    });
+    return {
+        send,
+        close() {
+            for (const p of pending.values()) {
+                clearTimeout(p.timer);
+                p.reject(new Error('关了'));
+            }
+            pending.clear();
+            ws.close();
+        },
+    };
+}
+/** 起一个 Chrome、开一页交给 fn;不论成败都收干净 */
+export async function withBrowser(fn, opts = {}) {
+    const bin = chromePath(opts.env);
+    if (!bin)
+        throw new UsageError('找不到 Chrome:装 Google Chrome,或环境变量 CHROME 指到 Chrome / Chromium / Edge 的可执行文件');
+    const width = opts.width ?? 1280;
+    const height = opts.height ?? 960;
+    const profile = await mkdtemp(join(tmpdir(), 'cotutor-chalk-'));
+    const chrome = spawn(bin, ['--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check', '--mute-audio', '--hide-scrollbars', `--user-data-dir=${profile}`, '--remote-debugging-port=0', `--window-size=${width},${height}`, 'about:blank'], { stdio: ['ignore', 'ignore', 'pipe'] });
+    try {
+        const cdp = await connect(await devtoolsUrl(chrome));
+        try {
+            const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' });
+            const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+            const s = (method, params) => cdp.send(method, params, String(sessionId));
+            await s('Page.enable');
+            await s('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false });
+            const evaluate = async (expression) => {
+                const r = (await s('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }));
+                if (r.exceptionDetails)
+                    throw new Error(`页面里出错:${r.exceptionDetails.exception?.description ?? r.exceptionDetails.text ?? '?'}`);
+                return r.result?.value;
+            };
+            const page = {
+                async goto(url) {
+                    const r = await s('Page.navigate', { url });
+                    if (typeof r.errorText === 'string' && r.errorText)
+                        throw new Error(`打不开 ${url}:${r.errorText}`);
+                },
+                async waitFor(expr, timeoutMs = 30_000) {
+                    const until = Date.now() + timeoutMs;
+                    while (!(await evaluate(`Boolean(${expr})`).catch(() => false))) {
+                        if (Date.now() > until)
+                            throw new Error(`页面 ${timeoutMs / 1000} 秒没好(${expr})`);
+                        await new Promise((r) => setTimeout(r, 100));
+                    }
+                },
+                evaluate,
+                async screenshot(selector) {
+                    const box = await evaluate(`(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (!el) return null; const r = el.getBoundingClientRect(); return { x: r.x, y: r.y, width: r.width, height: r.height }; })()`);
+                    if (!box || box.width < 1 || box.height < 1)
+                        throw new Error(`页面里没有 ${selector}`);
+                    const r = await s('Page.captureScreenshot', { format: 'png', clip: { ...box, scale: 1 } });
+                    return Buffer.from(String(r.data), 'base64');
+                },
+            };
+            return await fn(page);
+        }
+        finally {
+            cdp.close();
+        }
+    }
+    finally {
+        chrome.kill();
+        await Promise.race([new Promise((r) => (chrome.exitCode !== null || chrome.signalCode !== null ? r(null) : chrome.once('exit', r))), new Promise((r) => setTimeout(r, 3000))]);
+        await rm(profile, { recursive: true, force: true }).catch(() => { });
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * build:场景(已过 check)→ 课包目录。幂等:同输入产出相同字节。
+ * 课包 = 自包含目录:scene.json + manifest.json(+ audio/,由 cotutor chalk dub 落进来;build 不动 audio/)。
+ * audio/index.json 里讲稿 hash 仍匹配的步,build 会把 audioSrc 回填进 manifest——
+ * 讲稿改了的步自动失去音频(等重新 dub),不会拿旧音配新词。
+ */
+import type { ChalkScene } from '../../../chalk/types.ts';
+/**
+ * sourceDir:场景源所在目录,background.src 相对它解析;build 把图拷进课包(background.<ext>)并改写 src。
+ * 不给 sourceDir = 场景已是课包形态(src 相对课包目录),原样保留。
+ */
+export declare function buildBundle(scene: ChalkScene, outDir: string, sourceDir?: string): Promise<string[]>;
+/** 课包 → 场景(拼法与校验在 src/chalk 的 parseBundle):bake / snap / dub 直接吃课包 id 时用 */
+export declare function readBundle(bundlesDir: string, id: string): Promise<ChalkScene>;

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

@@ -0,0 +1,100 @@
+/**
+ * build:场景(已过 check)→ 课包目录。幂等:同输入产出相同字节。
+ * 课包 = 自包含目录:scene.json + manifest.json(+ audio/,由 cotutor chalk dub 落进来;build 不动 audio/)。
+ * audio/index.json 里讲稿 hash 仍匹配的步,build 会把 audioSrc 回填进 manifest——
+ * 讲稿改了的步自动失去音频(等重新 dub),不会拿旧音配新词。
+ */
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { extname, join, resolve } from 'node:path';
+import { attachAudio } from "./dub.js";
+import { sceneBounds } from "../../../chalk/geometry.js";
+import { parseBundle } from "../../../chalk/bundle.js";
+import { LoadError, NotFoundError } from "./load-scene.js";
+/**
+ * sourceDir:场景源所在目录,background.src 相对它解析;build 把图拷进课包(background.<ext>)并改写 src。
+ * 不给 sourceDir = 场景已是课包形态(src 相对课包目录),原样保留。
+ */
+export async function buildBundle(scene, outDir, sourceDir) {
+    await mkdir(outDir, { recursive: true });
+    const files = [];
+    // 背景图拷进课包、改写 src:第一块画板 background.<ext>,换画板的 background-<board id>.<ext>
+    const copyBackground = async (bg, stem, where) => {
+        const from = resolve(sourceDir, bg.src);
+        const name = `${stem}${extname(bg.src).toLowerCase()}`;
+        try {
+            await copyFile(from, join(outDir, name));
+        }
+        catch {
+            throw new LoadError(`背景图读不到:${from}(${where} '${bg.src}' 相对场景文件所在目录解析);检查路径`);
+        }
+        files.push(join(outDir, name));
+        return { ...bg, src: name };
+    };
+    let background = scene.background;
+    let skeletons = scene.skeletons;
+    if (sourceDir) {
+        if (background)
+            background = await copyBackground(background, 'background', 'background.src');
+        skeletons = [];
+        for (const e of scene.skeletons) {
+            const bg = e.type === 'board' ? e.background : undefined;
+            skeletons.push(bg ? { ...e, background: await copyBackground(bg, `background-${e.id}`, `换画板 '${e.id}' 的 background.src`) } : e);
+        }
+    }
+    const sceneJson = {
+        schema: 'chalk-scene',
+        version: 1,
+        id: scene.id,
+        title: scene.title,
+        problem: scene.problem,
+        model: scene.model,
+        template: scene.template,
+        ...(scene.subject ? { subject: scene.subject } : {}),
+        ...(background ? { background } : {}),
+        skeletons,
+        ...(scene.groups?.length ? { groups: scene.groups } : {}),
+        bounds: sceneBounds(skeletons),
+    };
+    const manifest = {
+        schema: 'lesson-manifest',
+        version: 2,
+        steps: scene.steps.map((s) => ({
+            step: s.step,
+            elementIds: s.elementIds,
+            line: s.line,
+            pauseAfter: s.pauseAfter,
+            ...(s.audioSrc ? { audioSrc: s.audioSrc } : {}),
+            ...(s.audioSrc && s.audioDurationMs ? { audioDurationMs: s.audioDurationMs } : {}),
+        })),
+        ...(scene.blocks?.length ? { blocks: scene.blocks } : {}),
+        ...(scene.subscenes?.length ? { subscenes: scene.subscenes } : {}),
+    };
+    await attachAudio(outDir, manifest);
+    for (const [name, data] of [
+        ['scene.json', sceneJson],
+        ['manifest.json', manifest],
+    ]) {
+        const p = join(outDir, name);
+        await writeFile(p, `${JSON.stringify(data, null, 2)}\n`);
+        files.push(p);
+    }
+    return files;
+}
+/** 课包 → 场景(拼法与校验在 src/chalk 的 parseBundle):bake / snap / dub 直接吃课包 id 时用 */
+export async function readBundle(bundlesDir, id) {
+    let sceneJson;
+    let manifest;
+    try {
+        sceneJson = JSON.parse(await readFile(join(bundlesDir, id, 'scene.json'), 'utf8'));
+        manifest = JSON.parse(await readFile(join(bundlesDir, id, 'manifest.json'), 'utf8'));
+    }
+    catch {
+        throw new NotFoundError(`课包 '${id}' 不存在或不完整(${join(bundlesDir, id)}/ 要有 scene.json + manifest.json);先 cotutor chalk build <scene.ts>`);
+    }
+    try {
+        return parseBundle(sceneJson, manifest).scene;
+    }
+    catch (e) {
+        throw new LoadError(`课包 '${id}' ${e.message}。用源 TS 重新 cotutor chalk build`);
+    }
+}

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

@@ -0,0 +1,51 @@
+import type { ChalkScene } from '../../../chalk/types.ts';
+import type { LessonManifest } from '../../../chalk/manifest.ts';
+import { type StretchInfo } from '../../../chalk/timeline.ts';
+/** 讲稿 hash:build 用它判断 audio/ 里的音频是否仍对应当前讲稿(讲稿改了 = 音频失效,不回填) */
+export declare function lineHash(line: string): string;
+export interface AudioIndex {
+    schema: 'drawtell-audio';
+    version: 1;
+    voice: string;
+    model: string | null;
+    instruction: string | null;
+    steps: Array<{
+        step: number;
+        file: string;
+        textHash: string;
+        characters: number;
+        durationMs: number | null;
+    }>;
+}
+export interface DubOptions {
+    scene: ChalkScene;
+    bundleDir: string;
+    voice: string;
+    instruction?: string;
+    /** 只算账:哪几步要合成、约多少计费字符,不花钱 */
+    dryRun?: boolean;
+    /** 配音缓存(workspace 的 dirs.tts) */
+    cacheDir: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface DubResult {
+    ok: boolean;
+    dryRun: boolean;
+    /** 约多少计费字符(汉字算 2、别的算 1;voxtell 实测和账单差 ±5%) */
+    characters: number;
+    /** kept = 讲稿与音色都没变,沿用课包里那份 */
+    steps: Array<{
+        step: number;
+        file: string | null;
+        kept: boolean;
+        characters: number;
+        durationMs: number | null;
+        error?: string;
+    }>;
+    /** 每步 画多久 / 音多久 / 播放器会拉伸几倍(只拉不缩,封顶 5) */
+    pacing: StretchInfo[];
+    manifestUpdated: boolean;
+}
+export declare function dubBundle(o: DubOptions): Promise<DubResult>;
+/** build 用:audio/index.json 里讲稿 hash 仍匹配的步,回填 audioSrc;讲稿改了的步不回填(等重新 dub) */
+export declare function attachAudio(bundleDir: string, manifest: LessonManifest): Promise<number>;

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 {};