cotutor 0.2.0 → 0.3.0

package/dist/scenes/dictation/store.d.ts

@@ -0,0 +1,112 @@
+import type { DictationWord } from '../../board/cards/index.ts';
+import type { CharJudge, InkPoint } from './match.ts';
+import type { PhotoItem } from './recognize.ts';
+export declare const ID_RE: RegExp;
+/** 擦掉的一笔:什么时候擦的(离开始多少毫秒,撤销、擦掉、点「给答案」清掉的都算) */
+export interface InkGone {
+    t: number;
+    pts: InkPoint[];
+}
+/** 一个格里写的:留下来的笔,撤销 / 擦掉了几次;擦掉的笔另记在 gone(录像里在擦的那一刻消失;老数据没有) */
+export interface CharInk {
+    strokes: InkPoint[][];
+    undos: number;
+    gone?: InkGone[];
+    /** 写之前点了「不会写,给答案」,看了笔顺照着描红写的 */
+    revealed?: boolean;
+}
+/** 一个词写的一遍 */
+export interface Attempt {
+    at: string;
+    chars: CharInk[];
+    judges: CharJudge[];
+}
+/**
+ * 孩子做的事,录像按它排时间:
+ * 写的时候 show 出了这个词、say 老师念了一遍(n 第几遍)、again 点了再念、reveal 点了「给答案」(服务端记)、order 看了一遍笔顺、done 写好了这个字;
+ * 对答案时 strokeOrder 点开一个字逐笔看、rewrite 问了再写一遍点「好」、self 自己说「我想再写」。
+ * 录像要的:trace 给答案后换成照着写(看笔顺放完或落笔,老记录是点「我来写」)、open 点听写本上的一格回去改、close 从逐笔看 / 再写一遍回到对一对、
+ * view 屏幕多大(w、h,进页面与转屏)与写字格的档(pad,换档也记)、away / back 切到别处 / 回来。
+ */
+export declare const EVENT_KINDS: readonly ["show", "say", "again", "reveal", "order", "done", "strokeOrder", "rewrite", "self", "trace", "open", "close", "view", "away", "back"];
+export interface DictationEvent {
+    /** 服务端收到的时刻 */
+    at: string;
+    /** 孩子端的时刻:离这次听写开始(startedAt)多少毫秒,和笔迹的点同一个尺子;老数据没有 */
+    t?: number;
+    kind: (typeof EVENT_KINDS)[number];
+    word: number;
+    char?: number;
+    /** say 是第几遍 */
+    n?: number;
+    /** view:孩子屏幕的 CSS 尺寸 */
+    w?: number;
+    h?: number;
+    /** view:写字格的档(l 铺满 / m 500 / s 380);老数据没有,按 l */
+    pad?: 'l' | 'm' | 's';
+}
+export interface Session {
+    id: string;
+    /** 从哪份首页的第几张听写卡来的(首页 id 与听写卡的序号,0 起);拍照开始的 home = null、n = -1 */
+    home: string | null;
+    n: number;
+    /** 拍照开始的:哪张照片(dictation/photos/<photo>.jpg)、照片上认出的课名 */
+    photo?: string;
+    lesson?: string | null;
+    tutor: string | null;
+    /** 英文单词听写(一个单词一个四线三格,不逐字母比);汉字的不写 */
+    lang?: 'en';
+    words: DictationWord[];
+    startedAt: string;
+    /** 第一遍:一个词一项,还没写的 null */
+    first: (Attempt | null)[];
+    /** 交了、开始对答案的时刻;之后第一遍不能改 */
+    checkedAt: string | null;
+    /** 对答案时问了「这个再写一遍?」的词 */
+    asked: number[];
+    /** 再写的:一个词可以写几遍 */
+    rewrites: {
+        word: number;
+        self: boolean;
+        attempt: Attempt;
+    }[];
+    events: DictationEvent[];
+    doneAt: string | null;
+}
+export declare const rootOf: (wsRoot: string) => string;
+export declare function writeSession(wsRoot: string, s: Session): Promise<void>;
+export declare function readSession(wsRoot: string, id: string): Promise<Session | null>;
+/** 全部听写,新的在前 */
+export declare function listSessions(wsRoot: string): Promise<Session[]>;
+/** 新 id:日期-时分;同一分钟已经有了(taken)加 -2、-3 */
+export declare function newId(wsRoot: string, now: Date, taken?: (id: string) => boolean): string;
+export declare function createSession(wsRoot: string, init: {
+    home: string | null;
+    n: number;
+    tutor: string | null;
+    words: DictationWord[];
+    photo?: string;
+    lesson?: string | null;
+    lang?: 'en';
+}, now: Date): Promise<Session>;
+export interface PhotoRecord {
+    id: string;
+    at: string;
+    /** running 正在认(items 是已经认出的)/ done 认完 / failed 没认成(error 说为什么,items 是失败前认出的) */
+    state: 'running' | 'done' | 'failed';
+    items: PhotoItem[];
+    lesson: string | null;
+    /** 正文全文:一行一个字符串,词之间空一格(孩子端能点着加词) */
+    full: string[];
+    error?: string;
+    model?: string;
+    ms?: number;
+    /** 认的是英文单词(英语老师卡上的拍照听写) */
+    lang?: 'en';
+}
+export declare const photosDir: (wsRoot: string) => string;
+export declare const photoFile: (wsRoot: string, id: string) => string;
+export declare function writePhotoRecord(wsRoot: string, r: PhotoRecord): Promise<void>;
+export declare function readPhotoRecord(wsRoot: string, id: string): Promise<PhotoRecord | null>;
+/** 存一张照片,开一份 running 的记录 */
+export declare function createPhoto(wsRoot: string, data: Buffer, now: Date, lang?: 'en'): Promise<PhotoRecord>;

package/dist/scenes/dictation/store.js

@@ -0,0 +1,99 @@
+/**
+ * 听写的存放:workspace 根的 dictation/<id>.json,一次听写一个文件;孩子的笔迹整个不进 git(目录里放一份 .gitignore)。
+ * id = 开始的时刻 YYYY-MM-DD-HHMM,同一分钟再开加 -2、-3。先写临时文件再换名,页面轮询读不到半截。
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const ID_RE = /^\d{4}-\d{2}-\d{2}-\d{4}(?:-\d{1,2})?$/;
+/**
+ * 孩子做的事,录像按它排时间:
+ * 写的时候 show 出了这个词、say 老师念了一遍(n 第几遍)、again 点了再念、reveal 点了「给答案」(服务端记)、order 看了一遍笔顺、done 写好了这个字;
+ * 对答案时 strokeOrder 点开一个字逐笔看、rewrite 问了再写一遍点「好」、self 自己说「我想再写」。
+ * 录像要的:trace 给答案后换成照着写(看笔顺放完或落笔,老记录是点「我来写」)、open 点听写本上的一格回去改、close 从逐笔看 / 再写一遍回到对一对、
+ * view 屏幕多大(w、h,进页面与转屏)与写字格的档(pad,换档也记)、away / back 切到别处 / 回来。
+ */
+export const EVENT_KINDS = ['show', 'say', 'again', 'reveal', 'order', 'done', 'strokeOrder', 'rewrite', 'self', 'trace', 'open', 'close', 'view', 'away', 'back'];
+export const rootOf = (wsRoot) => join(wsRoot, 'dictation');
+const fileOf = (wsRoot, id) => join(rootOf(wsRoot), `${id}.json`);
+const GITIGNORE = '# 听写的数据(孩子的笔迹)不进 git\n*\n';
+async function ensureRoot(wsRoot) {
+    await mkdir(rootOf(wsRoot), { recursive: true });
+    const f = join(rootOf(wsRoot), '.gitignore');
+    if ((await readFile(f, 'utf8').catch(() => null)) !== GITIGNORE)
+        await writeFile(f, GITIGNORE);
+}
+let tmpSeq = 0;
+export async function writeSession(wsRoot, s) {
+    await ensureRoot(wsRoot);
+    const file = fileOf(wsRoot, s.id);
+    // 临时文件各取各的名:同一次听写同时写两回(并发的请求)不能抢同一个临时文件
+    const tmp = `${file}.${process.pid}.${++tmpSeq}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(s)}\n`);
+    await rename(tmp, file);
+}
+export async function readSession(wsRoot, id) {
+    if (!ID_RE.test(id))
+        return null;
+    try {
+        return JSON.parse(await readFile(fileOf(wsRoot, id), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** 全部听写,新的在前 */
+export async function listSessions(wsRoot) {
+    const names = await readdir(rootOf(wsRoot)).catch(() => []);
+    const ids = names.filter((n) => n.endsWith('.json')).map((n) => n.slice(0, -5)).filter((id) => ID_RE.test(id));
+    const out = [];
+    for (const id of ids.sort().reverse()) {
+        const s = await readSession(wsRoot, id);
+        if (s)
+            out.push(s);
+    }
+    return out;
+}
+const p2 = (n) => String(n).padStart(2, '0');
+/** 新 id:日期-时分;同一分钟已经有了(taken)加 -2、-3 */
+export function newId(wsRoot, now, taken = (id) => existsSync(fileOf(wsRoot, id))) {
+    const base = `${now.getFullYear()}-${p2(now.getMonth() + 1)}-${p2(now.getDate())}-${p2(now.getHours())}${p2(now.getMinutes())}`;
+    let id = base;
+    for (let k = 2; taken(id); k++)
+        id = `${base}-${k}`;
+    return id;
+}
+export async function createSession(wsRoot, init, now) {
+    await ensureRoot(wsRoot);
+    const s = { id: newId(wsRoot, now), ...init, startedAt: now.toISOString(), first: init.words.map(() => null), checkedAt: null, asked: [], rewrites: [], events: [], doneAt: null };
+    await writeSession(wsRoot, s);
+    return s;
+}
+export const photosDir = (wsRoot) => join(rootOf(wsRoot), 'photos');
+export const photoFile = (wsRoot, id) => join(photosDir(wsRoot), `${id}.jpg`);
+export async function writePhotoRecord(wsRoot, r) {
+    const file = join(photosDir(wsRoot), `${r.id}.json`);
+    const tmp = `${file}.${process.pid}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(r)}\n`);
+    await rename(tmp, file);
+}
+export async function readPhotoRecord(wsRoot, id) {
+    if (!ID_RE.test(id))
+        return null;
+    try {
+        return JSON.parse(await readFile(join(photosDir(wsRoot), `${id}.json`), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** 存一张照片,开一份 running 的记录 */
+export async function createPhoto(wsRoot, data, now, lang) {
+    await ensureRoot(wsRoot);
+    await mkdir(photosDir(wsRoot), { recursive: true });
+    const id = newId(wsRoot, now, (x) => existsSync(photoFile(wsRoot, x)));
+    await writeFile(photoFile(wsRoot, id), data);
+    const r = { id, at: now.toISOString(), state: 'running', items: [], lesson: null, full: [], ...(lang ? { lang } : {}) };
+    await writePhotoRecord(wsRoot, r);
+    return r;
+}

package/dist/scenes/look.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 场景要的「看一张图」:一张图 + 提示词 + 模型 → 回的字(src/media/vision.ts 的 lookAt 就是这个样子;场景不认 media,由路由那层交进来)。
+ * 给 onDelta 就一块一块交出去(拍照认词边认边出);不给就整段收完再回。
+ */
+export type Seen = {
+    ok: true;
+    text: string;
+    ms: number;
+} | {
+    ok: false;
+    error: string;
+    ms: number;
+};
+export type Look = (o: {
+    image: {
+        data: Buffer;
+        mime: string;
+    };
+    prompt: string;
+    model: string;
+    params?: Record<string, unknown>;
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+    endpoint?: string;
+    onDelta?: (text: string) => void;
+}) => Promise<Seen>;

package/dist/scenes/look.js

@@ -0,0 +1 @@
+export {};

package/dist/scenes/paint/painter.d.ts

@@ -0,0 +1,84 @@
+import type { BoardSection } from '../../board/presentation.ts';
+import { type CotutorConfig } from '../../schema/index.ts';
+/** 画图卡要的 workspace 那几样:对话目录(卡的资产落在这)、根(给孩子端的相对路径)、画图的配置;传整个 workspace 也行 */
+export interface PaintSpace {
+    root: string;
+    dirs: {
+        conversations: string;
+    };
+    config: Pick<CotutorConfig, 'paint'>;
+}
+export type Drawn = ({
+    ok: true;
+    data: Buffer;
+    model: string;
+} | {
+    ok: false;
+    error: string;
+}) & {
+    ms: number;
+};
+/** 画一张(src/media/draw.ts 的 makeDraw 就是这个样子;场景不认 media,由 runner 交进来;测试与 mock 给假的) */
+export type Draw = (job: {
+    prompt: string;
+    model: string;
+    size: string;
+    negative?: string;
+}) => Promise<Drawn>;
+export declare const PAINT_PNG = "paint.png";
+export declare const PAINT_JSON = "paint.json";
+/** 「在画」超过这么久还没落成(服务重起过、进程被杀),当没画成 */
+export declare const PAINT_STALE_MS: number;
+export type PaintRecord = {
+    state: 'drawing';
+    at: string;
+    prompt: string;
+    model: string;
+    negative?: string;
+} | {
+    state: 'done';
+    at: string;
+    prompt: string;
+    model: string;
+    size: string;
+    ms: number;
+    negative?: string;
+} | {
+    state: 'none';
+    at: string;
+    error: string;
+    prompt?: string;
+    model?: string;
+    ms?: number;
+};
+/** 某一轮某张画图卡的记录;过了 PAINT_STALE_MS 还在画的当没画成(stale) */
+export declare function paintRecordAt(ws: PaintSpace, tutor: string, date: string, job: string, n: number, now?: number): Promise<PaintRecord | null>;
+/** 今天各位老师画好的张数(在画的也算);工作台概览用 */
+export declare function paintedToday(ws: PaintSpace, date: string, now?: number): Promise<number>;
+/**
+ * 这一轮板书里的画图卡,一张一张画。已经有记录的不再画(重起、重放都不重画);replay = 回放那轮不画(evals 目录里,不花钱)。
+ * painter = 这个话题的 activity 文件「画家收到什么」(模板与不要的);给了就照它画,没给照出厂的画风。
+ * 返回画完的 Promise(测试与关服前等它),不抛。
+ */
+export declare function startPaints(ws: PaintSpace, tutor: string, date: string, job: string, section: BoardSection, opts: {
+    draw: Draw;
+    now?: () => Date;
+    replay?: boolean;
+    gate?: () => Promise<string | null>;
+    painter?: {
+        prompt: string;
+        negative?: string;
+    } | null;
+}): Promise<void>;
+/** 家长端那一行:画好了用的模型与秒数;没画成的原因说成人话 */
+export declare function paintNote(r: PaintRecord | null): string;
+/**
+ * 下发时补上画好没有(同 enrichLectures):pic = 图(相对 workspace 根,页面经 /api/kid/image 取),drawn = drawing / done / none;
+ * 家长端(parent)再补 note。没有记录:这一轮刚跑完、还没轮到 → drawing;过了 PAINT_STALE_MS 还没有 → none。
+ */
+export declare function enrichPaints(ws: PaintSpace, tutor: string, date: string, job: string, at: string, section: BoardSection, opts?: {
+    parent?: boolean;
+    now?: number;
+}): Promise<BoardSection>;
+/** 交给老师的那一行(下一条消息的 cards:):老师看不到图,只知道画好没有 */
+export declare function paintLines(ws: PaintSpace, tutor: string, date: string, job: string, section: BoardSection, now?: number): Promise<string[]>;

package/dist/scenes/paint/painter.js

@@ -0,0 +1,170 @@
+/**
+ * 画图卡的画:一轮跑完,板书里的 paint 卡在后台画,和配音同一个时机。
+ * 落在这张卡的资产目录 <日期>.<job>.cards/<n>/:paint.png 是图,paint.json 是记录(在画 / 画好了 / 没画成,拼好的提示词、模型、几秒、原因)。
+ * 一天画几张不限;今天画了几张由工作台概览数(paintedToday)。
+ * 一张一张排着画。孩子端没有错误:没画成就停在分幅那几句,原因只给家长看。
+ */
+import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { cardId, conversationFiles } from "../../schema/index.js";
+import { PaintPropsSchema } from "../../board/cards/index.js";
+import { PAINT_DEFAULT, PAINT_NEGATIVE } from "../../schema/index.js";
+import { paintPrompt, paintPromptFrom, paintSize } from "./prompt.js";
+export const PAINT_PNG = 'paint.png';
+export const PAINT_JSON = 'paint.json';
+/** 「在画」超过这么久还没落成(服务重起过、进程被杀),当没画成 */
+export const PAINT_STALE_MS = 5 * 60_000;
+/** 某一轮某张画图卡的记录;过了 PAINT_STALE_MS 还在画的当没画成(stale) */
+export async function paintRecordAt(ws, tutor, date, job, n, now = Date.now()) {
+    const r = await readRecord(join(conversationFiles(ws.dirs.conversations, tutor, date).cardAssetsDir(job, n), PAINT_JSON));
+    return r?.state === 'drawing' && now - Date.parse(r.at) > PAINT_STALE_MS ? { state: 'none', at: r.at, error: 'stale' } : r;
+}
+async function readRecord(file) {
+    try {
+        const r = JSON.parse(await readFile(file, 'utf8'));
+        return r && typeof r.state === 'string' && typeof r.at === 'string' ? r : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeRecord(file, r) {
+    await writeFile(`${file}.tmp`, JSON.stringify(r, null, 2) + '\n');
+    await rename(`${file}.tmp`, file);
+}
+/** 今天各位老师画好的张数(在画的也算);工作台概览用 */
+export async function paintedToday(ws, date, now = Date.now()) {
+    let n = 0;
+    const tutors = await readdir(ws.dirs.conversations, { withFileTypes: true }).catch(() => []);
+    for (const t of tutors) {
+        if (!t.isDirectory())
+            continue;
+        const dir = join(ws.dirs.conversations, t.name);
+        const names = await readdir(dir).catch(() => []);
+        for (const name of names) {
+            if (!name.startsWith(`${date}.`) || !name.endsWith('.cards'))
+                continue;
+            const cards = await readdir(join(dir, name), { withFileTypes: true }).catch(() => []);
+            for (const c of cards) {
+                if (!c.isDirectory())
+                    continue;
+                const r = await readRecord(join(dir, name, c.name, PAINT_JSON));
+                if (r?.state === 'done' || (r?.state === 'drawing' && now - Date.parse(r.at) < PAINT_STALE_MS))
+                    n++;
+            }
+        }
+    }
+    return n;
+}
+/** 一张一张画:整个进程一条队 */
+let chain = Promise.resolve();
+/**
+ * 这一轮板书里的画图卡,一张一张画。已经有记录的不再画(重起、重放都不重画);replay = 回放那轮不画(evals 目录里,不花钱)。
+ * painter = 这个话题的 activity 文件「画家收到什么」(模板与不要的);给了就照它画,没给照出厂的画风。
+ * 返回画完的 Promise(测试与关服前等它),不抛。
+ */
+export function startPaints(ws, tutor, date, job, section, opts) {
+    const cfg = ws.config.paint ?? PAINT_DEFAULT;
+    const painter = opts.painter ?? null;
+    const negative = painter?.negative || PAINT_NEGATIVE;
+    const files = conversationFiles(ws.dirs.conversations, tutor, date);
+    const at = () => (opts.now?.() ?? new Date()).toISOString();
+    const work = section.cards.flatMap((c, n) => {
+        if (c.kind !== 'paint')
+            return [];
+        const p = PaintPropsSchema.safeParse(c.props);
+        return p.success ? [{ n, props: p.data }] : [];
+    });
+    if (!work.length)
+        return Promise.resolve();
+    const run = async () => {
+        for (const { n, props } of work) {
+            const dir = files.cardAssetsDir(job, n);
+            const rec = join(dir, PAINT_JSON);
+            if (await readRecord(rec))
+                continue;
+            await mkdir(dir, { recursive: true });
+            const prompt = painter ? paintPromptFrom(painter.prompt, props) : paintPrompt(props);
+            const model = cfg.model;
+            if (opts.replay) {
+                await writeRecord(rec, { state: 'none', at: at(), error: 'replay' });
+                continue;
+            }
+            // activity「应用拦的」:没过就不画、不占张数,下一条告诉老师缺哪条;排在队里现查,同一轮第二张看得到第一张
+            const stop = opts.gate ? await opts.gate().catch(() => null) : null;
+            if (stop) {
+                await writeRecord(rec, { state: 'none', at: at(), error: `gate:${stop}`, prompt, model });
+                continue;
+            }
+            await writeRecord(rec, { state: 'drawing', at: at(), prompt, model, negative });
+            const size = paintSize(props.panels.length, cfg.size);
+            const r = await opts.draw({ prompt, model, size, negative });
+            if (r.ok) {
+                await writeFile(join(dir, PAINT_PNG), r.data);
+                await writeRecord(rec, { state: 'done', at: at(), prompt, model, size, ms: r.ms, negative });
+            }
+            else
+                await writeRecord(rec, { state: 'none', at: at(), error: r.error, prompt, model, ms: r.ms });
+        }
+    };
+    const p = chain.then(run, run).catch(() => { });
+    chain = p;
+    return p;
+}
+/** 家长端那一行:画好了用的模型与秒数;没画成的原因说成人话 */
+export function paintNote(r) {
+    if (!r)
+        return '还没开始画';
+    if (r.state === 'drawing')
+        return `在画(${r.model})`;
+    if (r.state === 'done')
+        return `画好了:${r.model},${Math.round(r.ms / 1000)} 秒`;
+    const e = r.error;
+    // daily: 是 10-21 前一天几张的上限(去掉了),旧记录照旧说得出来
+    const why = e.startsWith('daily:') ? `今天画了 ${e.slice(6).split('/')[0]} 张,到了当时一天的上限(现在不限了)`
+        : e.startsWith('gate:') ? `应用拦下了,没交给画家(activity「应用拦的」:${e.slice(5)})`
+            : e === 'replay' ? '回放不画'
+                : e === 'no_key' ? '拿不到百炼 key(DASHSCOPE_API_KEY,或本机 ~/.qwen/settings.json)'
+                    : e === 'stale' ? '画到一半服务重起了'
+                        : e.includes('DataInspectionFailed') ? '百炼的内容审核没过'
+                            : e === 'timeout' ? '等了太久(超时)'
+                                : e;
+    return `没画成:${why}`;
+}
+/**
+ * 下发时补上画好没有(同 enrichLectures):pic = 图(相对 workspace 根,页面经 /api/kid/image 取),drawn = drawing / done / none;
+ * 家长端(parent)再补 note。没有记录:这一轮刚跑完、还没轮到 → drawing;过了 PAINT_STALE_MS 还没有 → none。
+ */
+export async function enrichPaints(ws, tutor, date, job, at, section, opts = {}) {
+    if (!section.cards.some((c) => c.kind === 'paint'))
+        return section;
+    const files = conversationFiles(ws.dirs.conversations, tutor, date);
+    const now = opts.now ?? Date.now();
+    const cards = await Promise.all(section.cards.map(async (c, n) => {
+        if (c.kind !== 'paint')
+            return c;
+        let r = await readRecord(join(files.cardAssetsDir(job, n), PAINT_JSON));
+        const since = (x) => now - Date.parse(x);
+        if (r?.state === 'drawing' && since(r.at) > PAINT_STALE_MS)
+            r = { state: 'none', at: r.at, error: 'stale' };
+        const drawn = r ? (r.state === 'done' ? 'done' : r.state) : since(at) > PAINT_STALE_MS ? 'none' : 'drawing';
+        const pic = drawn === 'done' ? relative(ws.root, files.cardAsset(job, n, PAINT_PNG)) : undefined;
+        return { ...c, props: { ...c.props, drawn, ...(pic ? { pic } : {}), ...(opts.parent ? { note: paintNote(r) } : {}) } };
+    }));
+    return { ...section, cards };
+}
+/** 交给老师的那一行(下一条消息的 cards:):老师看不到图,只知道画好没有 */
+export async function paintLines(ws, tutor, date, job, section, now = Date.now()) {
+    const files = conversationFiles(ws.dirs.conversations, tutor, date);
+    const out = [];
+    for (const [n, c] of section.cards.entries()) {
+        if (c.kind !== 'paint')
+            continue;
+        let r = await readRecord(join(files.cardAssetsDir(job, n), PAINT_JSON));
+        if (r?.state === 'drawing' && now - Date.parse(r.at) > PAINT_STALE_MS)
+            r = { state: 'none', at: r.at, error: 'stale' };
+        const said = !r || r.state === 'drawing' ? '画家还在画,孩子还没看到图' : r.state === 'done' ? '画好了,孩子看到了图(你看不到图,问孩子画得怎样)' : r.error === 'gate:连说过一遍' ? '没画:孩子还没看着整段连着说一遍,孩子只看到分好的几幅' : r.error === 'gate:还能画' ? '没画:这个话题能画的张数到头了,孩子只看到分好的几幅' : r.error.startsWith('gate:') ? `没画:${r.error.slice(5)}没过,孩子只看到分好的几幅` : '没画成,孩子只看到分好的几幅';
+        out.push(`${cardId(job, n)} 画图卡:${said}`);
+    }
+    return out;
+}

package/dist/scenes/paint/prompt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 画图卡 → 交给文生图模型的一段:版式(几格怎么排)+ 画风 + 角色 + 分幅。
+ * 画风在 activity 文件「画家收到什么」那节(模板里留 {{版式}} {{角色}} {{分幅}} 三个插槽);
+ * 不在 activity 话题里画,照出厂的画风(PAINT_PROMPT_DEFAULT)夹在版式与角色中间。
+ * 纯函数;版式与角色、分幅由这里接,改画风不会把分幅弄丢。
+ */
+import type { PaintProps } from '../../board/cards/index.ts';
+/** 反向提示词(百炼限 500 字符);出厂那串在 schema,和画风放一起 */
+export { PAINT_NEGATIVE } from '../../schema/index.ts';
+/** 几格怎么排:四格 2×2(练习册的样子),两三格横排,一幅就是一张画(不提编号:提了模型就往一幅的图上点圆圈数字) */
+export declare function paintLayout(n: number): string;
+/** 画多大:四格与一幅照配置(方的);两三格横排,换成宽的 */
+export declare function paintSize(n: number, size: string): string;
+/** 画家那节的三个插槽:版式、角色(没有就空)、分幅 */
+export declare function paintSlots(p: Pick<PaintProps, 'panels' | 'cast'>): {
+    版式: string;
+    角色: string;
+    分幅: string;
+};
+/** 不在 activity 话题里:版式、出厂的画风、角色、分幅,空一行隔开 */
+export declare function paintPrompt(p: Pick<PaintProps, 'panels' | 'cast'>): string;
+/** activity 文件「画家收到什么」的模板填好插槽 */
+export declare function paintPromptFrom(template: string, p: Pick<PaintProps, 'panels' | 'cast'>): string;

package/dist/scenes/paint/prompt.js

@@ -0,0 +1,36 @@
+import { fillSlots } from "../../schema/index.js";
+import { PAINT_PROMPT_DEFAULT } from "../../schema/index.js";
+/** 反向提示词(百炼限 500 字符);出厂那串在 schema,和画风放一起 */
+export { PAINT_NEGATIVE } from "../../schema/index.js";
+const FRAME = '格子之间留白边,每格有细圆角边框。除了这几个圆圈数字,画面里没有别的字。';
+const NUMS = ['1', '2', '3', '4'];
+/** 几格怎么排:四格 2×2(练习册的样子),两三格横排,一幅就是一张画(不提编号:提了模型就往一幅的图上点圆圈数字) */
+export function paintLayout(n) {
+    if (n >= 4)
+        return `一张四格连环画,四格按 2×2 排,从左上到右下依次是第 1、2、3、4 格,每格左上角一个圆圈数字。${FRAME}`;
+    if (n > 1)
+        return `一张${n === 3 ? '三' : '两'}格连环画,${n === 3 ? '三' : '两'}格从左到右横着排,依次是第 ${NUMS.slice(0, n).join('、')} 格,每格左上角一个圆圈数字。${FRAME}`;
+    return '一张画。';
+}
+/** 画多大:四格与一幅照配置(方的);两三格横排,换成宽的 */
+export function paintSize(n, size) {
+    return n === 2 || n === 3 ? '1664*928' : size;
+}
+/** 画家那节的三个插槽:版式、角色(没有就空)、分幅 */
+export function paintSlots(p) {
+    const n = p.panels.length;
+    return {
+        版式: paintLayout(n),
+        角色: p.cast?.length ? [`同一个角色在${n > 1 ? '每一格里' : '画里'}长相、颜色、衣服都照这样画:`, ...p.cast.map((c) => (c.look ? `- ${c.name}:${c.look}` : `- ${c.name}`))].join('\n') : '',
+        分幅: n > 1 ? p.panels.map((t, i) => `第 ${i + 1} 格:${t}`).join('\n') : `画面:${p.panels[0]}`,
+    };
+}
+/** 不在 activity 话题里:版式、出厂的画风、角色、分幅,空一行隔开 */
+export function paintPrompt(p) {
+    const s = paintSlots(p);
+    return [s.版式, PAINT_PROMPT_DEFAULT.join('\n'), s.角色, s.分幅].filter(Boolean).join('\n\n');
+}
+/** activity 文件「画家收到什么」的模板填好插槽 */
+export function paintPromptFrom(template, p) {
+    return fillSlots(template, paintSlots(p));
+}

package/dist/scenes/talk/en-words.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 孩子说的英文说出了几个词:实时老师的热身(src/scenes/talk/warmup.ts)用。纯函数。
+ * 比的是转写的字,不是发音:百炼的转写会往对的词上靠(coach),说出来了不等于念对了。
+ */
+/** 小写、展开常见缩写、去标点,拆成词 */
+export declare function wordsOf(s: string): string[];
+/** 这句(target)的词有多少出现在孩子读的(heard)里,0–1;不分先后 */
+export declare function coverage(target: string, heard: string): number;

package/dist/scenes/talk/en-words.js

@@ -0,0 +1,44 @@
+/**
+ * 孩子说的英文说出了几个词:实时老师的热身(src/scenes/talk/warmup.ts)用。纯函数。
+ * 比的是转写的字,不是发音:百炼的转写会往对的词上靠(coach),说出来了不等于念对了。
+ */
+const CONTRACT = { "it's": 'it is', "i'm": 'i am', "that's": 'that is', "what's": 'what is', "he's": 'he is', "she's": 'she is', "there's": 'there is', "don't": 'do not', "can't": 'can not', "isn't": 'is not', "you're": 'you are', "they're": 'they are', "we're": 'we are', "let's": 'let us', "i'll": 'i will' };
+/** 小写、展开常见缩写、去标点,拆成词 */
+export function wordsOf(s) {
+    const t = s.toLowerCase().replace(/[’`]/g, "'").replace(/[^a-z' ]+/g, ' ');
+    return t.split(/\s+/).flatMap((w) => (CONTRACT[w] ?? w.replace(/^'+|'+$/g, '')).split(' ')).filter(Boolean);
+}
+/** 两个词算不算同一个:一样;或四个字母以上差一个字母(认字的错一个字母常见:colour / color、apples / apple) */
+function near(a, b) {
+    if (a === b)
+        return true;
+    if (Math.min(a.length, b.length) < 4 || Math.abs(a.length - b.length) > 1)
+        return false;
+    let i = 0, j = 0, diff = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            i++;
+            j++;
+            continue;
+        }
+        if (++diff > 1)
+            return false;
+        if (a.length > b.length)
+            i++;
+        else if (b.length > a.length)
+            j++;
+        else {
+            i++;
+            j++;
+        }
+    }
+    return diff + (a.length - i) + (b.length - j) <= 1;
+}
+/** 这句(target)的词有多少出现在孩子读的(heard)里,0–1;不分先后 */
+export function coverage(target, heard) {
+    const want = [...new Set(wordsOf(target))];
+    if (!want.length)
+        return 0;
+    const got = wordsOf(heard);
+    return want.filter((w) => got.some((g) => near(w, g))).length / want.length;
+}

package/dist/scenes/talk/list.d.ts

@@ -0,0 +1,44 @@
+import type { Look } from '../look.ts';
+/** 口语单的一条;词另有单词卡(cards/word)要的 emoji 与自然拼读分段(读照片时出,过 cards/word 的 parse;没有就卡上只有词) */
+export interface ListItem {
+    en: string;
+    zh: string;
+    emoji?: string;
+    chunks?: string[];
+}
+export interface TalkList {
+    words: ListItem[];
+    sentences: ListItem[];
+}
+export declare const LIST_TIMEOUT_MS = 40000;
+export declare const PROMPT = "\u8FD9\u662F\u5BB6\u957F\u62CD\u7684\u4E00\u9875\u5C0F\u5B66\u82F1\u8BED\u8BFE\u672C\u6216\u7EC3\u4E60\u518C\u3002\u628A\u8FD9\u4E00\u9875\u4E0A**\u5370\u5237\u7684**\u82F1\u6587\u5355\u8BCD\u548C\u82F1\u6587\u53E5\u5B50\u8BFB\u51FA\u6765,\u7ED9\u5B69\u5B50\u8DDF\u8BFB\u548C\u53E3\u8BED\u7EC3\u4E60\u7528:\n- words:\u5355\u8BCD\u6216\u77ED\u8BED(\u6700\u591A 12 \u4E2A),\u6BCF\u4E2A\u5E26\u4E2D\u6587\u610F\u601D;\u518D\u5E26\u4E24\u6837\u7ED9\u5355\u8BCD\u5361\u7528:emoji\u2014\u2014\u80FD\u753B\u51FA\u6765\u7684\u4E1C\u897F\u914D\u4E00\u4E2A,\u62BD\u8C61\u7684\u8BCD(like\u3001the)\u4E0D\u914D;split\u2014\u2014\u81EA\u7136\u62FC\u8BFB\u5206\u6BB5,\u7528 - \u9694\u5F00(ap-ple\u3001sh-ee-p\u3001c-a-t),\u62FC\u8D77\u6765\u8981\u548C\u5355\u8BCD\u4E00\u6A21\u4E00\u6837;\n- sentences:\u5B8C\u6574\u7684\u82F1\u6587\u53E5\u5B50(\u6700\u591A 8 \u53E5),\u6BCF\u53E5\u5E26\u4E2D\u6587\u610F\u601D;\n- \u53EA\u8981\u5370\u5237\u7684,\u624B\u5199\u7684\u4E0D\u8981;\u9898\u53F7\u3001\u9875\u7801\u3001\u680F\u76EE\u540D\u4E0D\u8981;\u62FC\u97F3\u3001\u97F3\u6807\u4E0D\u8981;\n- \u8FD9\u4E00\u9875\u6CA1\u6709\u82F1\u6587\u5C31\u4E24\u4E2A\u90FD\u7A7A\u3002\n\u53EA\u56DE\u4E00\u4E2A JSON \u5BF9\u8C61,\u5F62\u5982 {\"words\":[{\"en\":\"red\",\"zh\":\"\u7EA2\u8272\",\"emoji\":\"\uD83D\uDD34\",\"split\":\"r-e-d\"}],\"sentences\":[{\"en\":\"It's a red car.\",\"zh\":\"\u8FD9\u662F\u4E00\u8F86\u7EA2\u8272\u7684\u8F66\u3002\"}]},\u4E0D\u8981\u522B\u7684\u5B57\u3002";
+/**
+ * 口语单的一个词 → 单词卡要的 emoji 与分段:拼成单词卡的正文过 cards/word 的 parse,
+ * 分段拼不回这个词就丢分段、emoji 不是 emoji 就丢——和老师写错时一个下场;词本身写不进四线三格(带标点、整句)两样都不要
+ */
+export declare function wordCardOf(en: string, emoji?: unknown, split?: unknown): {
+    emoji?: string;
+    chunks?: string[];
+};
+export type ListResult = {
+    ok: true;
+    list: TalkList;
+    model: string;
+    ms: number;
+} | {
+    ok: false;
+    error: string;
+    ms: number;
+};
+/** 模型回的字 → 口语单;去掉围栏、找到第一个 {…};形状不对回 null */
+export declare function parseList(text: string): TalkList | null;
+/** 读一张照片(look = 看图的请求,src/media/vision.ts 的 lookAt);不抛,出错回 {ok: false} */
+export declare function readListWith(look: Look, photo: {
+    data: Buffer;
+    mime: string;
+}, opts?: {
+    env?: NodeJS.ProcessEnv;
+    endpoint?: string;
+    model?: string;
+    timeoutMs?: number;
+}): Promise<ListResult>;