cotutor 0.2.0 → 0.4.0

package/dist/app/activity-eval.js

@@ -0,0 +1,159 @@
+/**
+ * cotutor activity eval:照例子文件,真老师 + 模拟孩子跑多轮,判只看板书。
+ * 跑在 evals/ 里(同回放:不进孩子的对话、不配音、不写记忆);画家是假的(不花钱,当画好了)。一个例子跑几次,次次都过才算过(pass^k)。
+ * 模拟孩子交给千问的对话模型(缺省 qwen3.8-flash,有 Token Plan 走它,不然百炼按量);写死的那几句先说完再交给它。
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { chatUrl, qianwenKeys, qianwenLine } from "../shared/qianwen.js";
+import { ACTIVITIES_DIR, activityRunFor } from "../runtime/activities.js";
+import { workspaceGradePack } from "./cli/grades.js";
+import { UsageError } from "../shared/errors.js";
+import { gradeRun, kidPrompt, parseExamples } from "./activity-eval-rules.js";
+import { evalWorkspace, EVALS_DIR } from "./replay.js";
+import { readLecture } from "../runtime/lecture.js";
+import { Runner } from "../runtime/runner.js";
+import { writeCapture } from "../runtime/journal/store.js";
+/** 模拟孩子缺省的模型(2026-10-13 从 qwen-plus 换来:Token Plan 有它,回归跑得最多) */
+export const KID_MODEL = 'qwen3.8-flash';
+export function makeKidModel(opts = {}) {
+    const env = opts.env ?? process.env;
+    return async (prompt) => {
+        const model = opts.model ?? KID_MODEL;
+        const line = qianwenLine(model, qianwenKeys(env));
+        if (!line)
+            return null;
+        try {
+            const res = await fetch(opts.endpoint ?? chatUrl(line.host), {
+                method: 'POST',
+                headers: { authorization: `Bearer ${line.key}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ model, enable_thinking: false, messages: [{ role: 'user', content: prompt }] }),
+                signal: AbortSignal.timeout(opts.timeoutMs ?? 30_000),
+            });
+            if (!res.ok)
+                return null;
+            const text = (await res.json()).choices?.[0]?.message?.content ?? '';
+            return text.replace(/^["“「]|["”」]$/g, '').replace(/^孩子[:\uFF1A]\s*/, '').trim() || null;
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/** 画家是假的:当画好了(1×1 的 png),不花钱 */
+const PNG = Buffer.from('89504e470d0a1a0a0000000d4948445200000001000000010806000000', 'hex');
+const fakeDraw = async ({ model }) => ({ ok: true, data: PNG, model, ms: 1 });
+export function examplesFile(root, tutor, name) {
+    return join(root, 'agents', tutor, 'activities', `${name}.例子.md`);
+}
+/**
+ * 跑一个 activity 的例子。onTurn 每一轮回调一次(终端现场打印)。
+ * 例子文件不在、写坏、参数不对 → UsageError(不起老师)。
+ */
+export async function evalActivity(ws, tutor, name, opts = {}) {
+    if (!ws.config.tutors[tutor])
+        throw new UsageError(`没有叫 ${tutor} 的老师`);
+    const file = examplesFile(ws.root, tutor, name);
+    const text = await readFile(file, 'utf8').catch(() => null);
+    if (text === null)
+        throw new UsageError(`${file} 不在:写几个例子再跑(写法见出厂的 agents/chinese-tutor/activities/你说我画.例子.md)`);
+    const parsed = parseExamples(text);
+    if (parsed.issues.length)
+        throw new UsageError(`例子文件要改:\n${parsed.issues.map((i) => `  ${i.line ? `第 ${i.line} 行 ` : ''}${i.text}`).join('\n')}`);
+    if (parsed.activity !== name)
+        throw new UsageError(`例子文件头上写的是 activity: ${parsed.activity},不是 ${name}`);
+    const examples = parsed.examples.filter((e) => !opts.only || e.name === opts.only);
+    if (!examples.length)
+        throw new UsageError(`没有叫「${opts.only}」的例子;有:${parsed.examples.map((e) => e.name).join('、')}`);
+    const runsN = opts.runs ?? 3;
+    // 参数先都解析一遍:写错了一轮都不跑
+    const runsOf = new Map();
+    for (const e of examples)
+        runsOf.set(e, await activityRunFor(ws.root, tutor, name, e.params));
+    // 照片先拷进 captures/(和孩子端拍照、cotutor send --photo 同一条路);读不到一轮都不跑
+    const photosOf = new Map();
+    for (const e of examples) {
+        const saved = [];
+        for (const p of e.photos) {
+            const src = isAbsolute(p) ? p : join(dirname(file), p);
+            // 出厂例子的图跟着包走,不拷进 workspace:workspace 里没有,就找包里同一个位置的
+            const data = (await readFile(src).catch(() => null)) ?? (isAbsolute(p) ? null : await readFile(join((await workspaceGradePack(ws.root)).agentsDir, tutor, ACTIVITIES_DIR, p)).catch(() => null));
+            if (!data)
+                throw new UsageError(`例子「${e.name}」的照片读不到:${src}`);
+            saved.push(await writeCapture(ws, new Date(), data, /\.png$/i.test(p) ? 'png' : 'jpg'));
+        }
+        photosOf.set(e, saved);
+    }
+    // 先看小课堂的例子:课要在 workspace 里(bundles/ 或 lectures/);读不出来一轮都不跑
+    for (const e of examples)
+        if (e.lecture && !(await readLecture(ws, e.lecture.bundle)))
+            throw new UsageError(`例子「${e.name}」的课 ${e.lecture.bundle} 不在 bundles/ 或 lectures/ 里:拷一份进来,或把「课:」换成你自己的课`);
+    const kid = opts.kid ?? makeKidModel({ env: opts.env });
+    const evalWs = evalWorkspace(ws);
+    const runner = new Runner(() => evalWs, { env: opts.env, draw: opts.draw ?? fakeDraw });
+    const out = [];
+    for (const e of examples) {
+        const run = runsOf.get(e);
+        const runs = [];
+        for (let k = 0; k < runsN; k++) {
+            const turns = [];
+            let thread = '';
+            let date = '';
+            const tokens = { in: 0, out: 0 };
+            let error;
+            // 第一句是按钮上的字(activity 的名字),和孩子点首页按钮一样;照片随第一句写死的孩子的话发。
+            // 先看小课堂的:第一句就是孩子看完问的那句(写死的第一句),带着 lecture(看完了、停过几次、画的几处)
+            let scripted = e.lecture ? 1 : 0;
+            let say = e.lecture ? e.kid[0] : name;
+            let photos = [];
+            let lecture = e.lecture ? { bundle: e.lecture.bundle, watchedMs: 0, finished: true, pauses: e.lecture.pauses, marks: e.lecture.marks.map((m) => ({ atMs: m.atMs, strokes: [], hit: m.text })) } : undefined;
+            while (say !== null && turns.length < e.maxTurns) {
+                // 真孩子都是实时的:模拟孩子的每一句也照实时写(上下文包带 live:、不补提问卡、讲稿不截);嘴不在,接住与打断不带
+                const started = await runner.send(tutor, { from: 'kid', text: say, eval: true, live: {}, ...(photos.length ? { photos } : {}), ...(lecture ? { lecture } : {}), ...(thread ? { thread } : { newThread: true, activity: run }) });
+                photos = [];
+                lecture = undefined;
+                thread = started.thread;
+                date = started.date;
+                const index = await started.done;
+                await runner.flush();
+                const m = index.messages.find((x) => x.job === started.job);
+                tokens.in += m?.tokens?.in ?? 0;
+                tokens.out += m?.tokens?.out ?? 0;
+                if (!m || m.result !== 'ok') {
+                    error = `第 ${turns.length + 1} 轮老师出错:${m?.error ?? '未知'}`;
+                    break;
+                }
+                const section = m.section ?? null;
+                turns.push({ kid: say, section });
+                const paint = (section?.cards ?? []).some((c) => c.kind === 'paint');
+                opts.onTurn?.({ example: e.name, run: k + 1, turn: turns.length, kid: say, said: (section?.lines ?? []).map((l) => l.text).join(''), paint });
+                if (paint)
+                    break;
+                if (scripted < e.kid.length) {
+                    say = e.kid[scripted++];
+                    if (scripted === 1)
+                        photos = photosOf.get(e) ?? [];
+                }
+                else if (e.persona || e.story) {
+                    say = await kid(kidPrompt(e, turns));
+                    if (say === null) {
+                        error = '模拟孩子不通(百炼 key?)';
+                        break;
+                    }
+                }
+                else
+                    say = null;
+            }
+            const grades = gradeRun(e.checks, turns, run.params);
+            runs.push({ turns, grades, pass: !error && grades.every((g) => g.pass), ...(error ? { error } : {}), tokens, thread, date });
+        }
+        out.push({ name: e.name, runs, pass: runs.every((r) => r.pass) });
+    }
+    const at = new Date().toISOString();
+    const rel = join(EVALS_DIR, 'activity-eval', `${tutor}-${name}-${at.replace(/[:.]/g, '-')}.json`);
+    const all = out.flatMap((x) => x.runs);
+    const report = { tutor, activity: name, at, examples: out, tokens: { in: all.reduce((a, r) => a + r.tokens.in, 0), out: all.reduce((a, r) => a + r.tokens.out, 0) }, file: rel };
+    await mkdir(join(ws.root, EVALS_DIR, 'activity-eval'), { recursive: true });
+    await writeFile(join(ws.root, rel), `${JSON.stringify(report, null, 2)}\n`);
+    return report;
+}

package/dist/app/build.d.ts

@@ -0,0 +1,11 @@
+/** 起来那一刻:commit 是完整哈希,显示时取前 7 位 */
+export declare const BUILD: {
+    version: string | null;
+    commit: string | null;
+    dirty: boolean;
+    started: string;
+};
+export declare const shortCommit: (c: string | null) => string | null;
+export declare function headNow(): Promise<string | null>;
+/** 代码更新了没有:起来时的提交与仓里现在的都知道、而且不一样 */
+export declare const codeChanged: (started: string | null, head: string | null) => boolean;

package/dist/app/build.js

@@ -0,0 +1,45 @@
+/**
+ * 这个 serve 跑的是哪份代码:版本号、git 提交(包目录自己是 git 仓才有;npm 装的没有)、有没有没提交的改动、启动时刻。
+ * 仓里的提交后来变了 = 代码更新了,要重起 serve 才用上(serve 只热重载 cotutor.json;Ray 跑的是仓里检出的分支)。
+ * 工作台侧栏(/api/health)与孩子端流水的打开那行(srv)用。
+ */
+import { execFile, execFileSync } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const ROOT = fileURLToPath(new URL('../..', import.meta.url));
+function readVersion() {
+    try {
+        return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+    }
+    catch {
+        return null;
+    }
+}
+/** 包目录自己是 git 仓才认(装在别人的仓里的 node_modules 不算) */
+function readCommit() {
+    const git = (args) => execFileSync('git', ['-C', ROOT, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 }).trim();
+    try {
+        if (realpathSync(git(['rev-parse', '--show-toplevel'])) !== realpathSync(ROOT))
+            return { commit: null, dirty: false };
+        return { commit: git(['rev-parse', 'HEAD']), dirty: git(['status', '--porcelain', '--untracked-files=no']) !== '' };
+    }
+    catch {
+        return { commit: null, dirty: false };
+    }
+}
+/** 起来那一刻:commit 是完整哈希,显示时取前 7 位 */
+export const BUILD = { version: readVersion(), ...readCommit(), started: new Date().toISOString() };
+export const shortCommit = (c) => (c ? c.slice(0, 7) : null);
+/** 仓里现在的提交(十秒内复用);不是 git 仓 → null */
+let cached = { at: 0, head: null };
+export async function headNow() {
+    if (!BUILD.commit)
+        return null;
+    if (Date.now() - cached.at < 10_000)
+        return cached.head;
+    const head = await new Promise((resolve) => execFile('git', ['-C', ROOT, 'rev-parse', 'HEAD'], { timeout: 3000 }, (err, out) => resolve(err ? null : String(out).trim() || null)));
+    cached = { at: Date.now(), head };
+    return head;
+}
+/** 代码更新了没有:起来时的提交与仓里现在的都知道、而且不一样 */
+export const codeChanged = (started, head) => Boolean(started && head && started !== head);

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

@@ -0,0 +1,70 @@
+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 ActivityRename {
+    /** 新的键「老师/新名」 */
+    key: string;
+    from: string;
+}
+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' | 'renamed';
+    basedOn?: string;
+    diff?: string[];
+    /** renamed:原来的名字 */
+    from?: 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,196 @@
+/**
+ * activity 文件的安装、升级与检查。和老师文件同一套:**拷贝,不链**。
+ * 包里的 grades/grade-<n>/agents/<老师>/activities/<名>.md 是出厂件;init 拷进 workspace 同一个位置(老师的家里,会话 cwd 下),这份是家长的;
+ * 出厂 hash 记 .cotutor/shipped.json 的 activities(键「老师/名」),据此分 latest / upgradable / custom / untracked / missing,意思同 tutors.ts。
+ */
+import { existsSync } from 'node:fs';
+import { readFile, readdir, mkdir, writeFile, lstat, unlink } 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, ACTIVITY_RENAMES, 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 };
+}
+/** 头上的 name(activity 文件)/ activity(例子文件)从旧名改成新名;别处不动 */
+function renameHead(text, from, to) {
+    return text.replace(/^---\n[\s\S]*?\n---/, (fm) => fm.replace(new RegExp(`^(name|activity):[ \t]*${from}[ \t]*$`, 'm'), `$1: ${to}`));
+}
+/**
+ * 改过名的出厂 activity(ACTIVITY_RENAMES):workspace 里旧名的文件与例子挪成新名,头上的名字跟着改;出厂记录跟着挪——
+ * 没改过的照旧算没改过(下面比新旧时换成新版),家长改过的照旧算自定义(内容不动,只改头上的名字)。新名已经有了就不动旧的
+ */
+async function migrateRenames(root, manifest) {
+    const out = [];
+    const tutors = (await readdir(join(root, 'agents'), { withFileTypes: true }).catch(() => [])).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+    for (const t of tutors) {
+        for (const [from, to] of Object.entries(ACTIVITY_RENAMES)) {
+            for (const [a, b] of [[from, to], [from + EXAMPLES_SUFFIX, to + EXAMPLES_SUFFIX]]) {
+                const src = activityFile(root, t, a);
+                const dst = activityFile(root, t, b);
+                const text = await readFile(src, 'utf8').catch(() => null);
+                if (text === null || existsSync(dst))
+                    continue;
+                const next = renameHead(text, from, to);
+                await writeFile(dst, next);
+                await unlink(src);
+                const rec = manifest.activities?.[`${t}/${a}`];
+                if (rec && manifest.activities) {
+                    delete manifest.activities[`${t}/${a}`];
+                    manifest.activities[`${t}/${b}`] = { ...rec, hash: rec.hash === sha256(text) ? sha256(next) : rec.hash };
+                }
+                out.push({ key: `${t}/${b}`, from: a });
+            }
+        }
+    }
+    return out;
+}
+/** init 用:缺的拷,有的不动(家长的) */
+export async function installActivities(root) {
+    const steps = [];
+    const manifest = await readManifest(root);
+    // 改过名的先挪:不然 init 会在旧名旁边再拷一份新名的
+    const renamed = await migrateRenames(root, manifest);
+    let touched = !manifest.teachingPack || renamed.length > 0;
+    manifest.teachingPack ??= { grade: (await workspaceGradePack(root)).grade };
+    for (const r of renamed)
+        steps.push({ item: `agents/${r.key.replace('/', `/${ACTIVITIES_DIR}/`)}.md`, action: 'replaced', note: `改了名(原来叫「${r.from}」)` });
+    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 = (await migrateRenames(root, manifest)).map((r) => ({ key: r.key, action: 'renamed', from: r.from }));
+    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,12 @@
+/**
+ * 这个系统上怎么装 mkcert、信任一次根证书(doctor 与 cert 共用)。Windows 上 mkcert -install 装进当前用户的根证书,会弹窗问,点「是」;
+ * 没有 winget 的(11-02 那台就没有)下官方的 exe。
+ */
+export declare function mkcertHint(platform?: NodeJS.Platform): string;
+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,49 @@
+/**
+ * cotutor cert:用 mkcert 给这台机器签一张证书到 ~/.config/cotutor/certs/(cert.pem + key.pem),serve 看到就走 HTTPS。
+ * 为什么要:平板、手机浏览器的录音 / 语音识别只在安全上下文里给;局域网 IP 不是 localhost,得自签。
+ * 为什么放机器级而不是 workspace:签的是电脑名与局域网 IP,与孩子无关;多个 workspace 共用一张。
+ * 主机名 = 电脑名、电脑名.local、所有局域网 IPv4、localhost、127.0.0.1,再加 --host 给的。已有证书就覆盖(证书可再生)。不需要 workspace。
+ * 地址认电脑名,IP 变了不用重签;证书里的 IP 只给手输数字地址的退路用。改了电脑名才要重签。
+ */
+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 { computerName, lanAddresses } from "./serve.js";
+import { USER_CERT_DIR, UsageError } from "../workspace.js";
+const execFileP = promisify(execFile);
+/**
+ * 这个系统上怎么装 mkcert、信任一次根证书(doctor 与 cert 共用)。Windows 上 mkcert -install 装进当前用户的根证书,会弹窗问,点「是」;
+ * 没有 winget 的(11-02 那台就没有)下官方的 exe。
+ */
+export function mkcertHint(platform = process.platform) {
+    if (platform === 'darwin')
+        return 'brew install mkcert && mkcert -install';
+    if (platform === 'win32')
+        return 'winget install FiloSottile.mkcert(没有 winget 就到 https://github.com/FiloSottile/mkcert/releases 下 windows-amd64 那个,改名 mkcert.exe 放进 PATH),重开终端跑 mkcert -install(弹窗问装不装根证书,点「是」)';
+    return '用系统的包管理器装 mkcert(如 apt install mkcert),再 mkcert -install';
+}
+export async function makeCert(extraHosts = []) {
+    let caRoot;
+    try {
+        caRoot = (await execFileP('mkcert', ['-CAROOT'], { timeout: 8000 })).stdout.trim();
+    }
+    catch {
+        throw new UsageError(`PATH 里没有 mkcert。装:${mkcertHint()}(这台电脑信任一次根证书);平板、手机端见 cert 命令输出的提示与 docs/iPad与iPhone.md。`);
+    }
+    const name = computerName();
+    // os.hostname() 也带上:和电脑名不一样时(macOS 上可能跟着网络变),以前能开的地址别丢
+    const hosts = [...new Set([name, `${name}.local`, hostname(), ...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(Windows 上没有 Chrome 就是 Edge)的可执行文件;找不到 null */
+export declare function chromePath(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): 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>;