cotutor 0.1.0 → 0.3.0

package/dist/app/cli/activities.d.ts

@@ -0,0 +1,63 @@
+import { type ActivityIssue } from '../../runtime/activity.ts';
+import type { Activity } from '../../schema/index.ts';
+import { type TutorState } from './tutors.ts';
+import { ACTIVITIES_DIR, EXAMPLES_SUFFIX, activityFile, activityRunFor, listActivities, type ActivityRef } from '../../runtime/activities.ts';
+export { ACTIVITIES_DIR, EXAMPLES_SUFFIX, activityFile, activityRunFor, listActivities, type ActivityRef };
+/** 出厂的 activity 与它们的例子文件 */
+export declare const shippedActivities: (root?: string) => Promise<ActivityRef[]>;
+export interface ActivityStatus {
+    key: string;
+    state: TutorState;
+    file: string;
+    basedOn?: string;
+}
+export declare function activityStatuses(root: string): Promise<ActivityStatus[]>;
+export interface ActivityInstallStep {
+    item: string;
+    action: 'created' | 'exists' | 'kept' | 'replaced';
+    note?: string;
+}
+/** init 用:缺的拷,有的不动(家长的) */
+export declare function installActivities(root: string): Promise<ActivityInstallStep[]>;
+export interface ActivityUpgradeStep {
+    key: string;
+    action: 'upgraded' | 'latest' | 'kept-custom' | 'forced' | 'installed';
+    basedOn?: string;
+    diff?: string[];
+}
+/** upgrade 用:同 upgradeTutors;force 里写「老师/名」才覆盖(原文留 .bak) */
+export declare function upgradeActivities(root: string, opts?: {
+    force?: string[];
+}): Promise<ActivityUpgradeStep[]>;
+/**
+ * 只把一个出厂 activity 换回出厂那份(工作台「恢复出厂」,与 upgrade --force 老师/名 同一条路,但不碰别的):
+ * 现在那份和出厂不一样就先存 .bak。不是出厂的 → UsageError。返回 .bak 的路径(没存就是 null)
+ */
+export declare function restoreActivity(root: string, tutor: string, name: string): Promise<{
+    bak: string | null;
+}>;
+/** 出厂那份的原文;不是出厂的 → null */
+export declare function shippedActivityText(tutor: string, name: string, root?: string): Promise<string | null>;
+/** workspace 里一个 activity 现在的状态(出厂的看新旧;自家加的是 untracked) */
+export declare function activityStatusOf(root: string, tutor: string, name: string): Promise<ActivityStatus>;
+export interface ActivityCheck {
+    tutor: string;
+    name: string;
+    file: string;
+    activity: Activity | null;
+    issues: ActivityIssue[];
+}
+/**
+ * cotutor activity check:workspace 里每个(或某位老师的、某一个)activity 文件解析 + 检查。
+ * tutors 是 cotutor.json 的老师表(键 → 这位老师的 cards;没写 cards 是 undefined = 全部);老师不在表里也报一条。
+ */
+export declare function checkActivities(root: string, tutors: Readonly<Record<string, {
+    cards?: readonly string[];
+}>>, opts?: {
+    tutor?: string;
+    name?: string;
+}): Promise<ActivityCheck[]>;
+/**
+ * 终端里起一个 activity 话题(cotutor send / pack --activity):读 workspace 里那份,参数照首页按钮的写法给(`名=值`,几个用 ; 隔开),
+ * 和孩子点按钮同一条解析(补缺省、按类型转)。不在、参数不对 → UsageError。
+ */

package/dist/app/cli/activities.js

@@ -0,0 +1,158 @@
+/**
+ * activity 文件的安装、升级与检查。和老师文件同一套:**拷贝,不链**。
+ * 包里的 grades/grade-<n>/agents/<老师>/activities/<名>.md 是出厂件;init 拷进 workspace 同一个位置(老师的家里,会话 cwd 下),这份是家长的;
+ * 出厂 hash 记 .cotutor/shipped.json 的 activities(键「老师/名」),据此分 latest / upgradable / custom / untracked / missing,意思同 tutors.ts。
+ */
+import { readFile, mkdir, writeFile, lstat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { lintActivity } from "../../runtime/activity.js";
+import { PACKAGE_AGENTS_DIR, PACKAGE_VERSION } from "./skeleton.js";
+import { lineDiff, readManifest, sha256, writeManifest } from "./tutors.js";
+import { UsageError } from "../workspace.js";
+import { workspaceGradePack } from "./grades.js";
+import { ACTIVITIES_DIR, EXAMPLES_SUFFIX, activityFile, activityRunFor, listActivities } from "../../runtime/activities.js";
+// 读的那一半在 src/runtime/activities.ts;照旧从这里转出
+export { ACTIVITIES_DIR, EXAMPLES_SUFFIX, activityFile, activityRunFor, listActivities };
+/** 出厂的 activity 与它们的例子文件 */
+export const shippedActivities = async (root) => listActivities(root ? (await workspaceGradePack(root)).agentsDir : PACKAGE_AGENTS_DIR, undefined, { examples: true });
+const keyOf = (a) => `${a.tutor}/${a.name}`;
+async function readState(root, a, manifest) {
+    const key = keyOf(a);
+    const file = activityFile(root, a.tutor, a.name);
+    if (!(await lstat(file).catch(() => null)))
+        return { key, state: 'missing', file };
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return { key, state: 'broken', file };
+    }
+    const h = sha256(text);
+    const rec = manifest.activities?.[key];
+    if (h === sha256(await readFile(a.file, 'utf8')))
+        return { key, state: 'latest', file, basedOn: rec?.version };
+    if (rec && rec.hash === h)
+        return { key, state: 'upgradable', file, basedOn: rec.version };
+    return { key, state: rec ? 'custom' : 'untracked', file, basedOn: rec?.version };
+}
+export async function activityStatuses(root) {
+    const manifest = await readManifest(root);
+    return Promise.all((await shippedActivities(root)).map((a) => readState(root, a, manifest)));
+}
+async function installOne(root, a, manifest) {
+    const file = activityFile(root, a.tutor, a.name);
+    await mkdir(dirname(file), { recursive: true });
+    const text = await readFile(a.file, 'utf8');
+    await writeFile(file, text);
+    manifest.teachingPack ??= { grade: (await workspaceGradePack(root)).grade };
+    manifest.activities ??= {};
+    manifest.activities[keyOf(a)] = { hash: sha256(text), version: PACKAGE_VERSION };
+}
+/** init 用:缺的拷,有的不动(家长的) */
+export async function installActivities(root) {
+    const steps = [];
+    const manifest = await readManifest(root);
+    let touched = !manifest.teachingPack;
+    manifest.teachingPack ??= { grade: (await workspaceGradePack(root)).grade };
+    for (const a of await shippedActivities(root)) {
+        const s = await readState(root, a, manifest);
+        const item = `agents/${a.tutor}/${ACTIVITIES_DIR}/${a.name}.md`;
+        if (s.state === 'missing' || s.state === 'broken') {
+            await installOne(root, a, manifest);
+            touched = true;
+            steps.push({ item, action: s.state === 'missing' ? 'created' : 'replaced', note: s.state === 'broken' ? '读不到,重新拷贝' : `拷自本包 ${PACKAGE_VERSION}` });
+        }
+        else
+            steps.push({ item, action: s.state === 'untracked' ? 'kept' : 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor upgrade)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
+    }
+    if (touched)
+        await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/** upgrade 用:同 upgradeTutors;force 里写「老师/名」才覆盖(原文留 .bak) */
+export async function upgradeActivities(root, opts = {}) {
+    const manifest = await readManifest(root);
+    manifest.teachingPack ??= { grade: (await workspaceGradePack(root)).grade };
+    const steps = [];
+    for (const a of await shippedActivities(root)) {
+        const s = await readState(root, a, manifest);
+        if (s.state === 'latest')
+            steps.push({ key: s.key, action: 'latest', basedOn: s.basedOn });
+        else if (s.state === 'missing' || s.state === 'broken') {
+            await installOne(root, a, manifest);
+            steps.push({ key: s.key, action: 'installed' });
+        }
+        else if (s.state === 'upgradable') {
+            await installOne(root, a, manifest);
+            steps.push({ key: s.key, action: 'upgraded', basedOn: s.basedOn });
+        }
+        else if (opts.force?.includes(s.key)) {
+            await writeFile(`${s.file}.bak`, await readFile(s.file, 'utf8'));
+            await installOne(root, a, manifest);
+            steps.push({ key: s.key, action: 'forced', basedOn: s.basedOn });
+        }
+        else
+            steps.push({ key: s.key, action: 'kept-custom', basedOn: s.basedOn, diff: lineDiff(await readFile(s.file, 'utf8'), await readFile(a.file, 'utf8')) });
+    }
+    await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/**
+ * 只把一个出厂 activity 换回出厂那份(工作台「恢复出厂」,与 upgrade --force 老师/名 同一条路,但不碰别的):
+ * 现在那份和出厂不一样就先存 .bak。不是出厂的 → UsageError。返回 .bak 的路径(没存就是 null)
+ */
+export async function restoreActivity(root, tutor, name) {
+    const ref = (await shippedActivities(root)).find((a) => a.tutor === tutor && a.name === name);
+    if (!ref)
+        throw new UsageError(`${tutor}/${name} 不是出厂的 activity,没有出厂那份可换`);
+    const manifest = await readManifest(root);
+    const file = activityFile(root, tutor, name);
+    const cur = await readFile(file, 'utf8').catch(() => null);
+    let bak = null;
+    if (cur !== null && cur !== (await readFile(ref.file, 'utf8'))) {
+        bak = `${file}.bak`;
+        await writeFile(bak, cur);
+    }
+    await installOne(root, ref, manifest);
+    await writeManifest(root, manifest);
+    return { bak };
+}
+/** 出厂那份的原文;不是出厂的 → null */
+export async function shippedActivityText(tutor, name, root) {
+    const ref = (await shippedActivities(root)).find((a) => a.tutor === tutor && a.name === name);
+    return ref ? readFile(ref.file, 'utf8') : null;
+}
+/** workspace 里一个 activity 现在的状态(出厂的看新旧;自家加的是 untracked) */
+export async function activityStatusOf(root, tutor, name) {
+    const ref = (await shippedActivities(root)).find((a) => a.tutor === tutor && a.name === name);
+    if (ref)
+        return readState(root, ref, await readManifest(root));
+    const file = activityFile(root, tutor, name);
+    return { key: `${tutor}/${name}`, state: (await lstat(file).catch(() => null)) ? 'untracked' : 'missing', file };
+}
+/**
+ * cotutor activity check:workspace 里每个(或某位老师的、某一个)activity 文件解析 + 检查。
+ * tutors 是 cotutor.json 的老师表(键 → 这位老师的 cards;没写 cards 是 undefined = 全部);老师不在表里也报一条。
+ */
+export async function checkActivities(root, tutors, opts = {}) {
+    const refs = (await listActivities(join(root, 'agents'), opts.tutor)).filter((r) => !opts.name || r.name === opts.name);
+    const out = [];
+    for (const r of refs) {
+        const text = await readFile(r.file, 'utf8').catch(() => null);
+        if (text === null) {
+            out.push({ ...r, activity: null, issues: [{ level: 'fix', text: '读不到' }] });
+            continue;
+        }
+        const t = tutors[r.tutor];
+        const { activity, issues } = lintActivity(text, { fileName: r.name, tutorCards: t?.cards });
+        if (!t)
+            issues.unshift({ level: 'fix', text: `cotutor.json 里没有 ${r.tutor} 这位老师,这个 activity 没人带` });
+        out.push({ ...r, activity, issues });
+    }
+    return out;
+}
+/**
+ * 终端里起一个 activity 话题(cotutor send / pack --activity):读 workspace 里那份,参数照首页按钮的写法给(`名=值`,几个用 ; 隔开),
+ * 和孩子点按钮同一条解析(补缺省、按类型转)。不在、参数不对 → UsageError。
+ */

package/dist/app/cli/cert.d.ts

@@ -0,0 +1,7 @@
+export interface CertResult {
+    cert: string;
+    key: string;
+    hosts: string[];
+    caRoot: string;
+}
+export declare function makeCert(extraHosts?: string[]): Promise<CertResult>;

package/dist/app/cli/cert.js

@@ -0,0 +1,36 @@
+/**
+ * cotutor cert:用 mkcert 给这台机器签一张证书到 ~/.config/cotutor/certs/(cert.pem + key.pem),serve 看到就走 HTTPS。
+ * 为什么要:iPad Safari 的录音 / 语音识别只在安全上下文里给;局域网 IP 不是 localhost,得自签。
+ * 为什么放机器级而不是 workspace:签的是本机名与局域网 IP,与孩子无关;多个 workspace 共用一张,IP 变了只重签一次。
+ * 主机名 = 本机名、本机名.local、所有局域网 IPv4、localhost、127.0.0.1,再加 --host 给的。已有证书就覆盖(证书可再生)。不需要 workspace。
+ */
+import { execFile } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { lanAddresses } from "./serve.js";
+import { USER_CERT_DIR, UsageError } from "../workspace.js";
+const execFileP = promisify(execFile);
+export async function makeCert(extraHosts = []) {
+    let caRoot;
+    try {
+        caRoot = (await execFileP('mkcert', ['-CAROOT'], { timeout: 8000 })).stdout.trim();
+    }
+    catch {
+        throw new UsageError('PATH 里没有 mkcert。装:brew install mkcert && mkcert -install(在 Mac 上信任一次根证书);iPad / iPhone 端见 cert 命令输出的提示与 docs/iPad与iPhone.md。');
+    }
+    const host = hostname();
+    const hosts = [...new Set([host, host.endsWith('.local') ? host : `${host}.local`, ...lanAddresses(), 'localhost', '127.0.0.1', ...extraHosts])];
+    const dir = USER_CERT_DIR;
+    await mkdir(dir, { recursive: true });
+    const cert = join(dir, 'cert.pem');
+    const key = join(dir, 'key.pem');
+    try {
+        await execFileP('mkcert', ['-cert-file', cert, '-key-file', key, ...hosts], { timeout: 60_000 });
+    }
+    catch (err) {
+        throw new UsageError(`mkcert 签证书失败:${err instanceof Error ? err.message : String(err)}\n先跑 mkcert -install,再重试。`);
+    }
+    return { cert, key, hosts, caRoot };
+}

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

@@ -0,0 +1,10 @@
+export declare const BAKE_FILE = "bake.json";
+/** 课包有没有烤过、烤的是不是现在这幅画面 */
+export declare function bakeIsFresh(bundleDir: string): Promise<boolean>;
+/** 烤一个或几个课包(同一个浏览器);返回每个写到哪 */
+export declare function bakeBundles(bundlesDir: string, ids: readonly string[]): Promise<{
+    id: string;
+    file: string;
+    elements: number;
+    bytes: number;
+}[]>;

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

@@ -0,0 +1,58 @@
+/**
+ * bake:课包 → bake.json(格式在 src/chalk/paint.ts)。起临时页面服务(./serve.ts)与本机 Chrome(./browser.ts),开舞台的 ?chalk=bake,
+ * 在浏览器里用 excalidraw 静态导出一次、量好路径;孩子端播放(src/ui/stage/chalk/render.ts)与服务端出图(renderFrameSvg)就不用 excalidraw 了。
+ * source.hash 是画面的指纹(skeletons + background):scene.json 的画面变了 bakeIsFresh 就是 false,要重烤;配音与时长不算画面。
+ * 服务端(src/runtime/lecture.ts 的 ensureBaked)遇到没烤过的课包,起 cotutor chalk bake 补烤。
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { bakeMatches, pictureHash } from "../../../chalk/paint.js";
+import { withBrowser } from "./browser.js";
+import { startPageServer } from "./serve.js";
+export const BAKE_FILE = 'bake.json';
+function excalidrawVersion() {
+    try {
+        return createRequire(import.meta.url)('@excalidraw/excalidraw/package.json').version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** 课包有没有烤过、烤的是不是现在这幅画面 */
+export async function bakeIsFresh(bundleDir) {
+    try {
+        const scene = JSON.parse(await readFile(join(bundleDir, 'scene.json'), 'utf8'));
+        return bakeMatches(JSON.parse(await readFile(join(bundleDir, BAKE_FILE), 'utf8')), scene);
+    }
+    catch {
+        return false;
+    }
+}
+/** 烤一个或几个课包(同一个浏览器);返回每个写到哪 */
+export async function bakeBundles(bundlesDir, ids) {
+    const server = await startPageServer(bundlesDir);
+    try {
+        return await withBrowser(async (page) => {
+            const out = [];
+            for (const id of ids) {
+                await page.goto(`${server.origin}/stage/?chalk=bake&bundle=${encodeURIComponent(`/api/bundles/${id}/`)}`);
+                await page.waitFor(`document.body.dataset.chalkDone === '1'`, 120_000);
+                const err = await page.evaluate('window.__chalkError ?? null');
+                if (err)
+                    throw new Error(`课包 '${id}' 烤不了:${err}`);
+                const picture = JSON.parse(await page.evaluate('JSON.stringify(window.__chalkBake)'));
+                const scene = JSON.parse(await readFile(join(bundlesDir, id, 'scene.json'), 'utf8'));
+                const baked = { ...picture, source: { excalidraw: excalidrawVersion(), hash: pictureHash(scene) } };
+                const file = join(bundlesDir, id, BAKE_FILE);
+                const text = `${JSON.stringify(baked)}\n`;
+                await writeFile(file, text);
+                out.push({ id, file, elements: baked.elements.length, bytes: Buffer.byteLength(text) });
+            }
+            return out;
+        });
+    }
+    finally {
+        await server.close();
+    }
+}

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

@@ -0,0 +1,16 @@
+/** 本机 Chrome 的可执行文件;找不到 null */
+export declare function chromePath(env?: NodeJS.ProcessEnv): string | null;
+export interface Page {
+    goto(url: string): Promise<void>;
+    /** 轮询到页面里这个表达式为真;超时报错 */
+    waitFor(expr: string, timeoutMs?: number): Promise<void>;
+    evaluate<T>(expr: string): Promise<T>;
+    /** 截一个元素(CSS 选择器)那一块,png */
+    screenshot(selector: string): Promise<Buffer>;
+}
+/** 起一个 Chrome、开一页交给 fn;不论成败都收干净 */
+export declare function withBrowser<T>(fn: (page: Page) => Promise<T>, opts?: {
+    width?: number;
+    height?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<T>;

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

@@ -0,0 +1,142 @@
+/**
+ * 做课包用的浏览器(2026-10-31 替掉 drawtell 的 playwright):起本机的 Chrome(无头、自己的临时 profile,不碰平时用的那个),
+ * 走 DevTools 协议(CDP)开页面、等、取值、截图。不另装浏览器:烤画面、截图与孩子端是同一种渲染就够。
+ * 每条命令都有超时(回包不来就报错,不挂着);收尾杀进程、删临时 profile,出错也在 finally 里收(scripts/_guard.mjs 那次的教训:无头 Chrome 挂了两天)。
+ * Chrome 在哪:环境变量 CHROME > macOS 的 /Applications/Google Chrome.app > PATH 里的 google-chrome / chromium。
+ */
+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';
+const MAC_CHROME = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+const PATH_NAMES = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser'];
+/** 一条 CDP 命令最多等多久 */
+const SEND_MS = 60_000;
+/** 本机 Chrome 的可执行文件;找不到 null */
+export function chromePath(env = process.env) {
+    const set = env.CHROME?.trim();
+    if (set)
+        return existsSync(set) ? set : null;
+    if (process.platform === 'darwin' && existsSync(MAC_CHROME))
+        return MAC_CHROME;
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        for (const name of PATH_NAMES)
+            if (dir && existsSync(join(dir, name)))
+                return join(dir, name);
+    }
+    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 Error('找不到 Chrome:装 Google Chrome,或环境变量 CHROME 指到 Chrome / Chromium 的可执行文件');
+    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>;