cotutor 0.1.0 → 0.3.0

package/dist/app/activity-eval-rules.d.ts

@@ -0,0 +1,62 @@
+/**
+ * activity 的例子与判分:`agents/<老师>/activities/<名>.例子.md`,一个 `## ` 一个例子。
+ * 例子 = 孩子心里的故事 + 人设(模拟孩子照它答)+ 开头几句写死的孩子的话 + 参数 + 几条判。判只看板书(讲稿与卡),应用就能判,不用再请模型。
+ * 纯函数:解析、判分;跑在 src/app/activity-eval.ts。
+ */
+import type { BoardSection } from '../board/presentation.ts';
+import type { ActivityValue } from '../schema/index.ts';
+export interface ActivityExample {
+    name: string;
+    line: number;
+    /** 首页按钮下面那几行的写法:名=值;名=值 */
+    params: string;
+    /** 孩子心里的故事(模拟孩子照它答;不写 = 只有写死的那几句) */
+    story?: string;
+    /** 模拟孩子是什么样的孩子 */
+    persona?: string;
+    /** 写死的孩子的话,按顺序先说;说完了有人设就交给模拟孩子 */
+    kid: string[];
+    /** 随第一句写死的孩子的话一起发的照片(相对例子文件所在的目录,或绝对路径) */
+    photos: string[];
+    /** 先看了一堂小课堂(小课堂 activity):课包或视频的 id、停过几次、画的几处(时刻 + 画的地方盖着什么,原样给老师);第一句写死的孩子的话带着它发 */
+    lecture?: {
+        bundle: string;
+        pauses: number;
+        marks: {
+            atMs: number;
+            text: string;
+        }[];
+    };
+    /** 最多几轮(孩子说一句、老师回一节算一轮) */
+    maxTurns: number;
+    /** 判,原文一行一条(见 GRADERS) */
+    checks: string[];
+}
+export interface ExampleIssue {
+    text: string;
+    line?: number;
+}
+/** 认得的判:名字 → 一句话。带参数的写成「名字: 参数」 */
+export declare const GRADERS: Readonly<Record<string, string>>;
+/** 分幅里不该有的:心里的、看不见的 */
+export declare const INVISIBLE_WORDS: string[];
+/** 解析例子文件;写坏的行进 issues,不抛 */
+export declare function parseExamples(text: string): {
+    activity: string;
+    examples: ActivityExample[];
+    issues: ExampleIssue[];
+};
+/** 一轮:孩子说的,和老师回的那一节 */
+export interface EvalTurn {
+    kid: string;
+    section: BoardSection | null;
+}
+export interface GradeResult {
+    check: string;
+    pass: boolean;
+    why?: string;
+}
+/** 判一次跑下来的这些轮;params 是这个话题的参数(词落到幅用) */
+export declare function gradeRun(checks: readonly string[], turns: readonly EvalTurn[], params?: Readonly<Record<string, ActivityValue>>): GradeResult[];
+/** 模拟孩子的提示词:故事、人设、到现在的对话;只回孩子说的一句 */
+export declare function kidPrompt(e: Pick<ActivityExample, 'story' | 'persona'>, turns: readonly EvalTurn[]): string;

package/dist/app/activity-eval-rules.js

@@ -0,0 +1,276 @@
+/** 认得的判:名字 → 一句话。带参数的写成「名字: 参数」 */
+export const GRADERS = {
+    每节有讲稿: '每一轮至少有一句非空讲稿;只有卡、空回复或没有轮次都不通过',
+    出画图卡: '最后写了画图卡',
+    不出画图卡: '一张画图卡都没写',
+    画图卡前放过整段: '第一张画图卡之前,有一节放过三行以上的 read 卡,孩子在它后面开过口',
+    放过整段: '有一节放过三行以上的 read 卡(连成的一段)',
+    分幅没有看不见的词: '画图卡的分幅里没有「高兴」「羞愧」这种看不见的词',
+    分幅至少: '每张画图卡至少这么多幅(「分幅至少: 3」;三四件事挤成两幅就不过)',
+    画图卡带题干和词: '每张画图卡都写了「题:」和「词:」(我来出题)',
+    每节末句是问句: '有卡的每一节(讲解),最后一句讲稿以问号结尾;没卡的随口问答不查(守则:问答一两句、没有卡)',
+    一节一问: '有卡的每一节,讲稿里最多一个问号(看图说话:一节只问一个问题)',
+    收尾不问: '最后一轮的末句不是问句(守则「答完就停」:答案出来了、孩子说懂了,一句收住,不再考他)',
+    不说: '老师的讲稿里没有这几个说法(「不说: 你没说清楚、错了」)',
+    说到: '老师的讲稿里出现过这几个说法(「说到: 你画的」;同「问到」,不要求是问句)',
+    放课里一段: '写过 lecture 卡(放小课堂里的一段)',
+    一节最多一段: '每一节最多一张 lecture 卡',
+    问到: '老师的讲稿里出现过这个词(「问到: 画家」)',
+    并排: '有一张 read 卡同时有这两句里的字(「并排: 睡大觉 | 浇了水」)',
+    卡上有: '老师写的卡上出现过这几个说法(「卡上有: 先看清」,如顺口溜)',
+    出拍给我看卡: '写过拍给我看卡(photo):要孩子拍照片发来时',
+    词落到幅: '参数「词」里至少这么多个原样出现在分幅里(「词落到幅: 2」);只适合画得出来的词,「羞愧」「满满」老师会照规矩换成看得见的样子',
+};
+/** 分幅里不该有的:心里的、看不见的 */
+export const INVISIBLE_WORDS = ['高兴', '开心', '难过', '伤心', '生气', '害怕', '羞愧', '着急', '得意', '后悔', '觉得', '心里', '想着'];
+const DEFAULT_TURNS = 12;
+const KEYS = '故事: / 人设: / 孩子: / 照片: / 课: / 看: / 画: / 参数: / 最多轮: / 判:';
+/** 「1:05」「0:26」→ 毫秒 */
+const clockMs = (s) => { const m = /^(\d+):([0-5]\d)$/.exec(s); return m ? (Number(m[1]) * 60 + Number(m[2])) * 1000 : null; };
+const MAX_TURNS = 30;
+/** 解析例子文件;写坏的行进 issues,不抛 */
+export function parseExamples(text) {
+    const issues = [];
+    const rows = text.replace(/\r\n?/g, '\n').split('\n');
+    let activity = '';
+    let i = 0;
+    if (/^---\s*$/.test(rows[0] ?? '')) {
+        const end = rows.findIndex((r, k) => k > 0 && /^---\s*$/.test(r));
+        for (const r of rows.slice(1, end > 0 ? end : 1)) {
+            const m = /^activity:\s*(.+)$/.exec(r.trim());
+            if (m)
+                activity = m[1].trim();
+        }
+        i = end > 0 ? end + 1 : 1;
+    }
+    if (!activity)
+        issues.push({ text: '头上要写 activity: <名>', line: 1 });
+    const examples = [];
+    let cur = null;
+    let inChecks = false;
+    let inNote = false;
+    for (; i < rows.length; i++) {
+        const raw = rows[i];
+        const no = i + 1;
+        const line = raw.trim();
+        if (inNote) {
+            if (line.includes('-->'))
+                inNote = false;
+            continue;
+        }
+        if (line.startsWith('<!--')) {
+            if (!line.includes('-->'))
+                inNote = true;
+            continue;
+        }
+        const h = /^##\s+(.+)$/.exec(line);
+        if (h) {
+            cur = { name: h[1].trim(), line: no, params: '', kid: [], photos: [], maxTurns: DEFAULT_TURNS, checks: [] };
+            examples.push(cur);
+            inChecks = false;
+            continue;
+        }
+        if (!cur || !line)
+            continue;
+        if (inChecks && /^[-*]\s+/.test(line)) {
+            cur.checks.push(line.replace(/^[-*]\s+/, ''));
+            continue;
+        }
+        inChecks = false;
+        const m = /^([^:：]+)[:：]\s*(.*)$/.exec(line);
+        if (!m) {
+            issues.push({ text: `「${line}」认不出:例子里一行写「${KEYS}」`, line: no });
+            continue;
+        }
+        const [, key, value] = m;
+        if (key === '故事')
+            cur.story = value;
+        else if (key === '人设')
+            cur.persona = value;
+        else if (key === '孩子')
+            cur.kid.push(value);
+        else if (key === '参数')
+            cur.params = value;
+        else if (key === '照片')
+            cur.photos.push(...value.split(/[,，\s]+/).filter(Boolean));
+        else if (key === '课')
+            cur.lecture = { bundle: value.trim(), pauses: cur.lecture?.pauses ?? 0, marks: cur.lecture?.marks ?? [] };
+        else if (key === '看') {
+            const n = /停过\s*(\d+)\s*次/.exec(value);
+            cur.lecture = { bundle: cur.lecture?.bundle ?? '', pauses: n ? Number(n[1]) : 0, marks: cur.lecture?.marks ?? [] };
+        }
+        else if (key === '画' || key === '圈') {
+            // 「圈:」是 2026-10-19 改成画一画以前的写法,照认
+            const m2 = /^(\d+:\d\d)\s*(.*)$/.exec(value.trim());
+            const at = m2 ? clockMs(m2[1]) : null;
+            if (at === null)
+                issues.push({ text: `「${key}:」后面先写时刻,再写画的地方盖着什么:「画: 0:14 画的地方盖着:散的 3 根小棒」`, line: no });
+            else
+                cur.lecture = { bundle: cur.lecture?.bundle ?? '', pauses: cur.lecture?.pauses ?? 0, marks: [...(cur.lecture?.marks ?? []), { atMs: at, text: m2[2].trim() }] };
+        }
+        else if (key === '最多轮') {
+            const n = Number(value);
+            if (Number.isInteger(n) && n >= 1 && n <= MAX_TURNS)
+                cur.maxTurns = n;
+            else
+                issues.push({ text: `最多轮要是 1 到 ${MAX_TURNS} 的整数`, line: no });
+        }
+        else if (key === '判') {
+            inChecks = true;
+            if (value)
+                cur.checks.push(value);
+        }
+        else
+            issues.push({ text: `「${key}」认不出:例子里一行写「${KEYS}」`, line: no });
+    }
+    for (const e of examples) {
+        if (!e.kid.length && !e.persona)
+            issues.push({ text: `例子「${e.name}」:孩子一句都没有,也没有人设`, line: e.line });
+        if (!e.checks.length)
+            issues.push({ text: `例子「${e.name}」:没有判`, line: e.line });
+        if (e.photos.length && !e.kid.length)
+            issues.push({ text: `例子「${e.name}」:照片随第一句写死的孩子的话发,要写一句「孩子:」`, line: e.line });
+        if (e.lecture && !e.lecture.bundle)
+            issues.push({ text: `例子「${e.name}」:写了「看:」或「画:」,要先写「课: <课包 id>」`, line: e.line });
+        if (e.lecture && !e.kid.length)
+            issues.push({ text: `例子「${e.name}」:看完课第一句是孩子问的,要写一句「孩子:」`, line: e.line });
+        for (const p of e.photos)
+            if (!/\.(jpe?g|png)$/i.test(p))
+                issues.push({ text: `例子「${e.name}」:照片只认 jpg / png(${p})`, line: e.line });
+        for (const c of e.checks) {
+            const name = c.split(/[:：]/)[0].trim();
+            if (!GRADERS[name])
+                issues.push({ text: `例子「${e.name}」:判「${name}」不认得(有:${Object.keys(GRADERS).join('、')})`, line: e.line });
+        }
+    }
+    if (!examples.length)
+        issues.push({ text: '一个例子都没有(一个 `## ` 一个例子)' });
+    return { activity, examples, issues };
+}
+const paintCards = (s) => (s?.cards ?? []).filter((c) => c.kind === 'paint');
+const panelsOf = (c) => (Array.isArray(c.props.panels) ? c.props.panels : []);
+const segmentsOf = (c) => (c.kind === 'read' && Array.isArray(c.props.segments) ? c.props.segments : []);
+const listArg = (arg) => arg.split(/[、,，;；]/).map((x) => x.trim()).filter(Boolean);
+/** 判一次跑下来的这些轮;params 是这个话题的参数(词落到幅用) */
+export function gradeRun(checks, turns, params = {}) {
+    const firstPaint = turns.findIndex((t) => paintCards(t.section).length > 0);
+    const allPanels = turns.flatMap((t) => paintCards(t.section).flatMap(panelsOf));
+    const lines = turns.flatMap((t) => t.section?.lines.map((l) => l.text) ?? []);
+    return checks.map((check) => {
+        const [name, ...rest] = check.split(/[:：]/);
+        const arg = rest.join(':').trim();
+        switch (name.trim()) {
+            case '每节有讲稿': {
+                const silent = turns.findIndex((t) => !t.section?.lines.some((l) => l.text.trim()));
+                return { check, pass: turns.length > 0 && silent < 0, ...(!turns.length ? { why: '没有老师回复' } : silent >= 0 ? { why: `第 ${silent + 1} 轮没有讲稿` } : {}) };
+            }
+            case '出画图卡':
+                return { check, pass: firstPaint >= 0, ...(firstPaint < 0 ? { why: `${turns.length} 轮都没写画图卡` } : {}) };
+            case '不出画图卡':
+                return { check, pass: firstPaint < 0, ...(firstPaint >= 0 ? { why: `第 ${firstPaint + 1} 轮写了画图卡` } : {}) };
+            case '画图卡前放过整段': {
+                if (firstPaint < 0)
+                    return { check, pass: true, why: '没写画图卡,不用判' };
+                // 整段那一节之后(含画图卡那一轮孩子说的话)孩子开过口:轮 k 的孩子话在轮 k 的老师那节之前,所以整段要在画图卡那一轮之前
+                const story = turns.slice(0, firstPaint).some((t) => (t.section?.cards ?? []).some((c) => segmentsOf(c).length >= 3));
+                return { check, pass: story, ...(story ? {} : { why: `第 ${firstPaint + 1} 轮写画图卡之前没放过整段` }) };
+            }
+            case '放过整段': {
+                const ok = turns.some((t) => (t.section?.cards ?? []).some((c) => segmentsOf(c).length >= 3));
+                return { check, pass: ok, ...(ok ? {} : { why: `${turns.length} 轮都没放过三行以上的 read 卡` }) };
+            }
+            case '分幅至少': {
+                const need = Number(arg) || 1;
+                const bad = turns.flatMap((t, k) => paintCards(t.section).filter((c) => panelsOf(c).length < need).map((c) => `第 ${k + 1} 轮的画图卡 ${panelsOf(c).length} 幅`));
+                return { check, pass: !bad.length, ...(bad.length ? { why: `${bad.join(';')},要至少 ${need} 幅` } : {}) };
+            }
+            case '画图卡带题干和词': {
+                const bad = turns.flatMap((t, k) => paintCards(t.section).filter((c) => !c.props.ask || !(c.props.words ?? []).length).map(() => `第 ${k + 1} 轮的画图卡`));
+                return { check, pass: !bad.length, ...(bad.length ? { why: `${bad.join(';')}没写题干或词` } : {}) };
+            }
+            case '分幅没有看不见的词': {
+                const bad = allPanels.flatMap((p) => INVISIBLE_WORDS.filter((w) => p.includes(w)).map((w) => `「${w}」在「${p}」`));
+                return { check, pass: !bad.length, ...(bad.length ? { why: bad.join(';') } : {}) };
+            }
+            case '每节末句是问句': {
+                const bad = turns.flatMap((t, k) => {
+                    const last = t.section?.lines[t.section.lines.length - 1]?.text.trim() ?? '';
+                    return t.section?.cards.length && !/[?？]$/.test(last) ? [`第 ${k + 1} 轮末句「${last}」`] : [];
+                });
+                return { check, pass: !bad.length, ...(bad.length ? { why: bad.join(';') } : {}) };
+            }
+            case '收尾不问': {
+                const k = turns.length - 1;
+                const last = turns[k]?.section?.lines.at(-1)?.text.trim() ?? '';
+                const asked = /[?？]$/.test(last);
+                return { check, pass: !asked, ...(asked ? { why: `第 ${k + 1} 轮(最后一轮)末句「${last}」` } : {}) };
+            }
+            case '一节一问': {
+                const bad = turns.flatMap((t, k) => {
+                    const n = (t.section?.lines ?? []).reduce((a, l) => a + (l.text.match(/[?？]/g)?.length ?? 0), 0);
+                    return t.section?.cards.length && n > 1 ? [`第 ${k + 1} 轮问了 ${n} 个`] : [];
+                });
+                return { check, pass: !bad.length, ...(bad.length ? { why: bad.join(';') } : {}) };
+            }
+            case '出拍给我看卡': {
+                const ok = turns.some((t) => (t.section?.cards ?? []).some((c) => c.kind === 'photo'));
+                return { check, pass: ok, ...(ok ? {} : { why: `${turns.length} 轮都没写拍给我看卡` }) };
+            }
+            case '卡上有': {
+                const cards = turns.flatMap((t) => (t.section?.cards ?? []).map((c) => JSON.stringify(c.props)));
+                const miss = listArg(arg).filter((w) => !cards.some((c) => c.includes(w)));
+                return { check, pass: !miss.length, ...(miss.length ? { why: `卡上没有:${miss.join('、')}` } : {}) };
+            }
+            case '不说': {
+                const said = listArg(arg).flatMap((w) => lines.filter((l) => l.includes(w)).map((l) => `「${l}」`));
+                return { check, pass: !said.length, ...(said.length ? { why: said.join(';') } : {}) };
+            }
+            case '放课里一段': {
+                const ok = turns.some((t) => (t.section?.cards ?? []).some((c) => c.kind === 'lecture'));
+                return { check, pass: ok, ...(ok ? {} : { why: `${turns.length} 轮都没放课里的一段` }) };
+            }
+            case '一节最多一段': {
+                const bad = turns.flatMap((t, k) => { const n = (t.section?.cards ?? []).filter((c) => c.kind === 'lecture').length; return n > 1 ? [`第 ${k + 1} 轮放了 ${n} 段`] : []; });
+                return { check, pass: !bad.length, ...(bad.length ? { why: bad.join(';') } : {}) };
+            }
+            case '说到':
+            case '问到': {
+                const want = listArg(arg);
+                const miss = want.filter((w) => !lines.some((l) => l.includes(w)));
+                return { check, pass: !miss.length, ...(miss.length ? { why: `没说过:${miss.join('、')}` } : {}) };
+            }
+            case '并排': {
+                const [a, b] = arg.split('|').map((x) => x.trim());
+                const ok = Boolean(a && b) && turns.some((t) => (t.section?.cards ?? []).some((c) => { const seg = segmentsOf(c).join('\n'); return seg.includes(a) && seg.includes(b); }));
+                return { check, pass: ok, ...(ok ? {} : { why: `没有一张 read 卡同时有「${a}」和「${b}」` }) };
+            }
+            case '词落到幅': {
+                const words = Array.isArray(params.词) ? params.词 : [];
+                const need = Number(arg) || words.length;
+                const hit = words.filter((w) => allPanels.some((p) => p.includes(w)));
+                return { check, pass: hit.length >= need, ...(hit.length >= need ? {} : { why: `落到幅的词 ${hit.length} 个(${hit.join('、') || '无'}),要 ${need} 个` }) };
+            }
+            default:
+                return { check, pass: false, why: '不认得这条判' };
+        }
+    });
+}
+/** 模拟孩子的提示词:故事、人设、到现在的对话;只回孩子说的一句 */
+export function kidPrompt(e, turns) {
+    const said = turns.flatMap((t) => [`孩子:${t.kid}`, `老师:${(t.section?.lines.map((l) => l.text) ?? []).join('')}${(t.section?.cards ?? []).filter((c) => c.kind === 'read').map((c) => `(板上:${segmentsOf(c).join(' / ')})`).join('')}`]);
+    return [
+        '你在扮演一个小学二年级的孩子,在和语文老师说话。',
+        e.persona ? `你是这样的孩子:${e.persona}` : '',
+        e.story ? `你心里想讲的故事是:${e.story}` : '',
+        '规矩:',
+        '- 只回孩子说的一句话,不加引号、不加「孩子:」,不超过 30 个字。',
+        '- 老师问什么答什么,照你心里的故事答;老师没问到的不主动说完。',
+        '- 老师请你连起来说一遍,就把整个故事一口气说出来(这时可以长一点)。',
+        '- 说孩子的话,不像大人。',
+        '',
+        '到现在的对话:',
+        ...said,
+        '',
+        '孩子接下来说:',
+    ].filter((x) => x !== '').join('\n');
+}

package/dist/app/activity-eval.d.ts

@@ -0,0 +1,65 @@
+import type { Workspace } from '../schema/index.ts';
+import { type EvalTurn, type GradeResult } from './activity-eval-rules.ts';
+import type { Draw } from '../media/draw.ts';
+/** 模拟孩子:给提示词,回孩子说的一句;不通回 null */
+export type KidModel = (prompt: string) => Promise<string | null>;
+/** 模拟孩子缺省的模型(2026-10-13 从 qwen-plus 换来:Token Plan 有它,回归跑得最多) */
+export declare const KID_MODEL = "qwen3.8-flash";
+export declare function makeKidModel(opts?: {
+    env?: NodeJS.ProcessEnv;
+    model?: string;
+    endpoint?: string;
+    timeoutMs?: number;
+}): KidModel;
+export interface EvalRun {
+    turns: EvalTurn[];
+    grades: GradeResult[];
+    pass: boolean;
+    /** 跑不下去的原因(老师出错、模拟孩子不通) */
+    error?: string;
+    /** 老师这几轮的 token(模拟孩子另算) */
+    tokens: {
+        in: number;
+        out: number;
+    };
+    thread: string;
+    date: string;
+}
+export interface EvalExampleReport {
+    name: string;
+    runs: EvalRun[];
+    /** 次次都过 */
+    pass: boolean;
+}
+export interface EvalReport {
+    tutor: string;
+    activity: string;
+    at: string;
+    examples: EvalExampleReport[];
+    tokens: {
+        in: number;
+        out: number;
+    };
+    /** 报告落在哪(相对 workspace 根) */
+    file: string;
+}
+export declare function examplesFile(root: string, tutor: string, name: string): string;
+/**
+ * 跑一个 activity 的例子。onTurn 每一轮回调一次(终端现场打印)。
+ * 例子文件不在、写坏、参数不对 → UsageError(不起老师)。
+ */
+export declare function evalActivity(ws: Workspace, tutor: string, name: string, opts?: {
+    runs?: number;
+    only?: string;
+    kid?: KidModel;
+    draw?: Draw;
+    env?: NodeJS.ProcessEnv;
+    onTurn?: (e: {
+        example: string;
+        run: number;
+        turn: number;
+        kid: string;
+        said: string;
+        paint: boolean;
+    }) => void;
+}): Promise<EvalReport>;

package/dist/app/activity-eval.js

@@ -0,0 +1,158 @@
+/**
+ * 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, warm: false, 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) {
+                const started = await runner.send(tutor, { from: 'kid', text: say, eval: true, ...(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);