cotutor 0.2.0 → 0.4.0

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

@@ -0,0 +1,199 @@
+/**
+ * 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 { cardVoice } from "../../../schema/index.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) ?? cardVoice(ws.config.tutors, tutor);
+                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[]>;

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

@@ -0,0 +1,103 @@
+/**
+ * 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 { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { bboxOf } from "../../../chalk/check.js";
+import { isAction, resolveActions } from "../../../chalk/actions.js";
+import { withBrowser } from "./browser.js";
+import { startPageServer } from "./serve.js";
+const VIEWBOX_EXPR = `document.querySelector('#chalk-snap svg')?.getAttribute('viewBox') ?? null`;
+function describe(el, erases) {
+    if (isAction(el))
+        return { id: el.id, type: el.type, erases: erases ?? [] };
+    const b = bboxOf(el);
+    const out = {
+        id: el.id,
+        type: el.type,
+        bbox: { x: round(b.minX), y: round(b.minY), w: round(b.maxX - b.minX), h: round(b.maxY - b.minY) },
+    };
+    if (typeof el.strokeColor === 'string')
+        out.strokeColor = el.strokeColor;
+    if (typeof el.backgroundColor === 'string' && el.backgroundColor !== 'transparent') {
+        out.backgroundColor = el.backgroundColor;
+        if (typeof el.fillStyle === 'string')
+            out.fillStyle = el.fillStyle;
+    }
+    if (typeof el.strokeStyle === 'string' && el.strokeStyle !== 'solid')
+        out.strokeStyle = el.strokeStyle;
+    if (el.type === 'text' && typeof el.text === 'string')
+        out.text = el.text;
+    return out;
+}
+const round = (n) => Math.round(n * 10) / 10;
+function parseViewBox(s) {
+    if (!s)
+        return null;
+    const nums = s.trim().split(/[\s,]+/).map(Number);
+    if (nums.length !== 4 || nums.some((n) => !Number.isFinite(n)))
+        return null;
+    return { viewBox: [nums[0], nums[1], nums[2], nums[3]] };
+}
+/** 读已有 index.json(同一场景才合并;读不到或格式不对就当没有) */
+async function readExistingIndex(outDir, sceneId) {
+    try {
+        const raw = JSON.parse(await readFile(join(outDir, 'index.json'), 'utf8'));
+        if (raw.schema !== 'drawtell-snaps' || raw.scene !== sceneId || !Array.isArray(raw.shots))
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export async function snapScene({ scene, bundlesDir, outDir, step, cursor = true }) {
+    const byId = new Map(scene.skeletons.map((e) => [e.id, e]));
+    const acts = resolveActions(scene.skeletons, scene.background);
+    const addedOf = (n) => n === 0 ? [] : scene.steps[n - 1].elementIds.map((id) => byId.get(id)).filter((e) => !!e).map((e) => describe(e, acts.targets.get(e.id)));
+    const server = await startPageServer(bundlesDir);
+    try {
+        return await withBrowser(async (page) => {
+            const stepNums = step != null ? [step] : Array.from({ length: scene.steps.length + 1 }, (_, i) => i);
+            await mkdir(outDir, { recursive: true });
+            const shots = [];
+            let board = null;
+            for (const n of stepNums) {
+                await page.goto(`${server.origin}/stage/?chalk=snap&bundle=${encodeURIComponent(`/api/bundles/${scene.id}/`)}&step=${n}${cursor ? '' : '&cursor=0'}`);
+                await page.waitFor(`document.body.dataset.chalkDone === '1'`, 60_000);
+                const pageErr = await page.evaluate('window.__chalkError ?? null');
+                if (pageErr)
+                    throw new Error(`截图那页出错(step ${n}):${pageErr}`);
+                const vb = parseViewBox(await page.evaluate(VIEWBOX_EXPR));
+                if (!board)
+                    board = vb;
+                const file = join(outDir, `step-${n}.png`);
+                await writeFile(file, await page.screenshot('#chalk-snap'));
+                shots.push({ step: n, file, line: n === 0 ? `(题面)${scene.problem}` : scene.steps[n - 1].line, added: addedOf(n), cursor, ...(vb ? { viewBox: vb.viewBox } : {}) });
+            }
+            // 单步重截:与已有对照表合并,只替换这一步(第一批真题里三组生成方都踩过"覆盖成单条")
+            let merged = shots.map((s) => ({ ...s, file: basename(s.file) }));
+            if (step != null) {
+                const existing = await readExistingIndex(outDir, scene.id);
+                if (existing) {
+                    const others = existing.shots.filter((s) => s.step !== step);
+                    merged = [...others, ...merged].sort((a, b) => a.step - b.step);
+                    if (!board)
+                        board = existing.board ?? null;
+                }
+            }
+            // schema 名照旧(drawtell-snaps):检验技能与已有的截图目录认它
+            const index = { schema: 'drawtell-snaps', version: 2, scene: scene.id, title: scene.title, problem: scene.problem, board, shots: merged };
+            await writeFile(join(outDir, 'index.json'), `${JSON.stringify(index, null, 2)}\n`);
+            return shots;
+        });
+    }
+    finally {
+        await server.close();
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { Finding } from '../../../chalk/check.ts';
+export interface TypecheckResult {
+    /** false = 类型层没跑(typescript 缺席等),findings 里有一条 warning 说明原因 */
+    ran: boolean;
+    findings: Finding[];
+}
+export declare function typecheckScene(file: string): Promise<TypecheckResult>;

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

@@ -0,0 +1,51 @@
+/**
+ * 阶梯层 1:类型。`cotutor chalk check` 内嵌 tsc 过一遍场景文件——工作区不需要 tsconfig、不需要自己装 typescript、
+ * 不需要知道类型在哪:场景里的 `import type … from 'cotutor/chalk'` 在这里被映射到包内的类型文件
+ * (仓库内跑是 src/chalk/types.ts,npm 安装后是 dist/chalk/types.d.ts);并进来之前写的 `from 'drawtell'` 照认。
+ * 这是"CLI 中心、工作区只剩源"原则在类型层的落法:以前要求工作区放一个 tsconfig 垫片,现在不用了。
+ * typescript 是 dependency;万一缺席降级为一条 warning,不拦后面几层。
+ */
+import { existsSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = dirname(fileURLToPath(import.meta.url));
+const TYPES = ['../../../chalk/types.ts', '../../../chalk/types.d.ts'].map((p) => resolve(here, p)).find(existsSync);
+export async function typecheckScene(file) {
+    let ts;
+    try {
+        ts = (await import('typescript')).default;
+    }
+    catch {
+        return { ran: false, findings: [{ level: 'warning', rule: 'types-unavailable', message: '类型层未跑:找不到 typescript 包(它是 cotutor 的依赖;重新 pnpm install 即可)。后续各层照常。' }] };
+    }
+    if (!TYPES) {
+        return { ran: false, findings: [{ level: 'warning', rule: 'types-unavailable', message: '类型层未跑:找不到场景的类型文件(chalk/types)。后续各层照常。' }] };
+    }
+    const abs = resolve(file);
+    const options = {
+        noEmit: true,
+        strict: true,
+        skipLibCheck: true,
+        types: [],
+        // DOM 是给仓库内种子场景用的:它们从 ../src/player 引类型,会把播放器(用到 SVG/DOM 类型)一起拉进程序
+        lib: ['lib.esnext.d.ts', 'lib.dom.d.ts', 'lib.dom.iterable.d.ts'],
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        allowImportingTsExtensions: true,
+        jsx: ts.JsxEmit.ReactJSX,
+        baseUrl: dirname(abs),
+        paths: { 'cotutor/chalk': [TYPES], drawtell: [TYPES] },
+    };
+    const program = ts.createProgram([abs], options);
+    const diags = ts.getPreEmitDiagnostics(program).filter((d) => d.category === ts.DiagnosticCategory.Error);
+    const findings = diags.map((d) => {
+        let where = '';
+        if (d.file && d.start != null) {
+            const { line, character } = d.file.getLineAndCharacterOfPosition(d.start);
+            where = `${relative(process.cwd(), d.file.fileName)}:${line + 1}:${character + 1} `;
+        }
+        return { level: 'error', rule: 'types', message: `${where}TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, '\n')}` };
+    });
+    return { ran: true, findings };
+}

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

@@ -0,0 +1,24 @@
+import { type ResolveOptions, type RootSource } from '../workspace.ts';
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    required: boolean;
+    detail: string;
+    fix?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    root: string | null;
+    source: RootSource | null;
+    checks: DoctorCheck[];
+}
+export declare function doctorWorkspace(override?: string, opts?: ResolveOptions & {
+    probeEnv?: boolean;
+    live?: boolean;
+    /** 测试钉时间用:首页「几天前发布的」按它算 */
+    now?: Date;
+    /** Windows 上查防火墙放没放行(起一次 PowerShell,一秒多):缺省跟 probeEnv;serve 起来时要查 */
+    firewall?: boolean;
+    /** 防火墙按哪个端口查:缺省 cotutor.json 的 server.port,serve --port 换了就传进来 */
+    port?: number;
+}): Promise<DoctorReport>;