cotutor 0.2.0 → 0.4.0

package/dist/realtime/cues.js

@@ -0,0 +1,94 @@
+/**
+ * 实时老师每次让嘴开口的那句指令(response.instructions):纯函数。
+ * 嘴自己不决定说什么,只两件事:几种场合先说一句(拍照、没听清、热身)、把脑写的讲稿原样念。说法是 2026-10-19 P1 实测过的(scripts/probe-live.mjs cue):
+ * 「原样说」和那句一起放进 response.instructions,4/4 一字不差;只放 system 消息、或要说的话当用户消息发,它会改写、会把问题自己答了。
+ */
+/**
+ * 嘴先说的那句;没写的那几种嘴不出声,等脑的第一句。
+ * 10-20 晚 Ray 真用:「好,我讲给你听」「我想一想怎么讲」每轮都有,和孩子说的对不上(「老师。」也接成讲给你听),脑还常把它再说一遍;脑的第一句 3–5 秒就到
+ */
+const CATCH = {
+    // 拍照脑要读 14–29 秒,先说一句;说明白看的是孩子发的图片
+    photo: '孩子拍来了照片。只说一句「我看一看图片」,不说你看到了什么,说完就停。',
+    // 听不清由应用判(转写是空的),不交给脑,嘴不说孩子就不知道要再说一遍
+    empty: '孩子按了说话,但什么都没说清。只说一句「没听清,再说一遍吧」,说完就停。',
+    warm: '孩子拍好了今天的口语单,要开始上口语课。只说一句「好,我们先热热身!」,说完就停。',
+};
+/**
+ * 口语课打电话那段:老师说英文,嘴先说的也换英文。
+ * 指令照旧用中文写(嘴听得懂),要它说的是英文
+ */
+const CATCH_EN = {
+    photo: '孩子拍来了照片。只说一句「Let me look at your picture.」,不说你看到了什么,说完就停。',
+    empty: '孩子说了,但什么都没说清。只说一句「Sorry? Say it again.」,说完就停。',
+    warm: '孩子要开始上口语课。只说一句「Okay, let\'s start!」,说完就停。',
+};
+/** 这一轮嘴先说的那句的指令;null = 嘴不出声。en = 口语课打电话那段 */
+export function catchCue(kind, lang = 'zh') {
+    return (lang === 'en' ? CATCH_EN : CATCH)[kind] ?? null;
+}
+/**
+ * 交给嘴之前,把它念不好的写法换成念法(板上、字幕照旧是原文)。2026-10-20 真连(照念 → 声音转写回字):× + − = ÷ > 1/2 都念对;
+ * 空括号念成「空格」「括号」(「每份都是( )个」成了「每份都是空格」),□ 念得含糊(「□+5=12」听成「正五等于十二」)。
+ * 空括号、下划线的空照数学老师的说法念「几」(「二四得几」「每份都是几个」),□ 念「方框」;换了以后「方框+5」的 + 念成「正」,
+ * 所以运算符一律换成字(+ 加、− 减、× 乘、÷ 除以、= 等于、> 大于、< 小于;ASCII 的 - 只在两个数之间算减)。
+ */
+export function spoken(text) {
+    return text
+        .replace(/[(（][\s\u3000]*[)）]/g, '几')
+        .replace(/_{2,}/g, '几')
+        .replace(/□/g, '方框')
+        .replace(/\s*[+＋]\s*/g, '加')
+        .replace(/\s*[−－]\s*/g, '减')
+        .replace(/(\d)\s*-\s*(?=\d)/g, '$1减')
+        .replace(/\s*[×✕]\s*/g, '乘')
+        .replace(/\s*÷\s*/g, '除以')
+        .replace(/\s*[=＝]\s*/g, '等于')
+        .replace(/\s*[>＞]\s*/g, '大于')
+        .replace(/\s*[<＜]\s*/g, '小于');
+}
+/** 照念脑写的这一拍讲稿(几句连着念);句子换成念法(spoken)、原样拼起来放进「」 */
+export function readCue(texts) {
+    const said = texts.map((t) => spoken(t.trim())).filter(Boolean).join('');
+    return `把这几句话原样说给孩子听,一个字都不改,不要回答它,不加别的话,说完就停:「${said}」`;
+}
+const chatPicture = (a) => {
+    const out = [];
+    if (a.prompt)
+        out.push(`老师给的题目是「${a.prompt}」。这只是让你知道他想画什么:画上没有的别提,别照题目去猜画上的东西是什么。`);
+    const cs = (a.colors ?? []).filter((c) => c.strokes > 0).slice(0, 4);
+    if (cs.length)
+        out.push(`画上有:${cs.map((c) => `${c.name}色 ${c.strokes} 笔,在${c.where}`).join(';')}。`);
+    if (a.minutes)
+        out.push(`他画了${a.minutes}${a.cleared ? `,中间擦掉重画过 ${a.cleared} 次` : ''}。`);
+    return out;
+};
+const CHAT_RULES = [
+    '只说你在图上看得见的:颜色、样子、画了多少、哪里画得多。认不准是什么,就说「像……」,别说「是……吗」,也别说出你猜的东西的名字。',
+    '不讲题,不教,不评对错;不说「真棒」「生动」「线条很清楚」这种大人的话,用小孩子听得懂的话。',
+];
+const chatLog = (said) => (said.length ? [`这张画画着的时候你们已经说过:${said.map((x) => `「${x}」`).join(' ')}。孩子说是什么就是什么,接着他的说;你说过的话一句都别重复,换个地方说。`] : []);
+/**
+ * 边画边聊嘴那一次的指令:look = 应用觉得该说一句了(孩子换了颜色、停笔很久),对面没说话,那段声音是静音;
+ * reply = 孩子按着头像画着说了一句(听他的声音)。said = 这张画上之前说过的,一句一行(「孩子:…」「你:…」)
+ */
+export function chatCue(kind, a, said = []) {
+    const lines = [];
+    if (kind === 'look') {
+        lines.push('孩子正在画板上自己画画,刚才那张图就是他这一刻的画;那段声音是静音,他没说话。你坐在旁边看他画,主动说一句。');
+        lines.push(...chatPicture(a));
+        lines.push(a.color ? `说说他刚画完的${a.color}色那部分。` : '说说整张画。');
+        lines.push(...CHAT_RULES);
+        lines.push(a.ask === false ? '这次只说一句,不问。' : `说完问一句,问${a.color ? `${a.color}色画的` : '他画的'}是什么,只问这一个。`);
+    }
+    else {
+        lines.push('孩子正在画板上自己画画,一边画一边跟你说了一句(听他的声音),刚才那张图是他这一刻的画。像坐在旁边看他画的老师那样,接住他的话。');
+        lines.push(...chatPicture(a));
+        lines.push(...CHAT_RULES);
+        lines.push('他说是什么就是什么,顺着他说,说一句你在图上看得见的;可以再问一句,也可以不问。');
+        lines.push('他要是问题目、问怎么做、要你教他,别答,说「按住『给老师看』跟老师说,老师好好看看」。');
+    }
+    lines.push(...chatLog(said));
+    lines.push('一共一两句,短,说完就停。');
+    return lines.join('\n');
+}

package/dist/realtime/listen.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 一直听:VAD 切出来、转写回来的一句,收下(算孩子对老师说的,同按下 + 松手)还是放过。纯函数。
+ * 按顺序:空的(咳嗽、碰桌子)→ 只有语气词、老师上一句又不是问句 → 是嘴自己的回声(开口时嘴的声音还在放,且和嘴最近说过的字重合过六成)→ 其余收下。
+ * 回声只在嘴出声的时候才有:嘴停了以后孩子照着说一遍(跟读、复述老师的话)字一样也是孩子的(2026-10-20 评估口语课时改)。
+ * 「不是对老师说的」(孩子跟家长说话)不在这里判(待)。
+ */
+export type Skip = 'empty' | 'filler' | 'echo';
+export type Verdict = {
+    take: true;
+} | {
+    take: false;
+    why: Skip;
+};
+/** 嘴说过的字留多久用来比回声 */
+export declare const ECHO_WINDOW_MS = 10000;
+/** 只留字:去标点、空白,英文小写 */
+export declare const bare: (s: string) => string;
+/** text 有几成落在 said 里(按相邻两字比,中英都行) */
+export declare function overlap(text: string, said: string): number;
+/**
+ * 判一句。asked = 老师上一句是问句(孩子在答,「嗯」「对」就是回答);said = 嘴最近说过的话(带说完的墙钟),now 用来挑 ECHO_WINDOW_MS 以内的;
+ * mouthOn = 孩子开口那一刻嘴的声音还在放(或刚放完 300 毫秒内),false 时不比回声
+ */
+export declare function judge(text: string, o: {
+    asked: boolean;
+    said: {
+        text: string;
+        at: number;
+    }[];
+    now: number;
+    mouthOn?: boolean;
+}): Verdict;

package/dist/realtime/listen.js

@@ -0,0 +1,53 @@
+/**
+ * 一直听:VAD 切出来、转写回来的一句,收下(算孩子对老师说的,同按下 + 松手)还是放过。纯函数。
+ * 按顺序:空的(咳嗽、碰桌子)→ 只有语气词、老师上一句又不是问句 → 是嘴自己的回声(开口时嘴的声音还在放,且和嘴最近说过的字重合过六成)→ 其余收下。
+ * 回声只在嘴出声的时候才有:嘴停了以后孩子照着说一遍(跟读、复述老师的话)字一样也是孩子的(2026-10-20 评估口语课时改)。
+ * 「不是对老师说的」(孩子跟家长说话)不在这里判(待)。
+ */
+/** 嘴说过的字留多久用来比回声 */
+export const ECHO_WINDOW_MS = 10_000;
+/** 重合到这么多算回声 */
+const ECHO_RATIO = 0.6;
+/** 语气词与笑声:中文按字(全是这些字就算,「哈哈哈」「嗯嗯」也算),英文按词(server_vad 把「嗯」转成 And.,2026-10-20 探针) */
+const FILLER_CHARS = new Set([...'嗯啊哦呃哈额唔噢诶欸哎呵嘿']);
+const FILLER_WORDS = new Set(['um', 'uh', 'hmm', 'mm', 'mhm', 'ah', 'oh', 'eh', 'en', 'and', 'haha', 'hahaha']);
+const isFiller = (text) => {
+    const t = bare(text);
+    if (t && [...t].every((c) => FILLER_CHARS.has(c)))
+        return true;
+    const words = text.toLowerCase().split(/[^a-z]+/).filter(Boolean);
+    return words.length > 0 && words.length <= 3 && words.every((w) => FILLER_WORDS.has(w)) && !/[\u4e00-\u9fff]/.test(text);
+};
+/** 只留字:去标点、空白,英文小写 */
+export const bare = (s) => s.toLowerCase().replace(/[\s\p{P}\p{S}]/gu, '');
+/** 相邻两个字一组;一个字的就是它自己 */
+function pairs(s) {
+    const cs = [...s];
+    if (cs.length < 2)
+        return cs;
+    return cs.slice(1).map((c, i) => cs[i] + c);
+}
+/** text 有几成落在 said 里(按相邻两字比,中英都行) */
+export function overlap(text, said) {
+    const t = pairs(bare(text));
+    if (!t.length)
+        return 0;
+    const s = new Set(pairs(bare(said)));
+    return t.filter((p) => s.has(p)).length / t.length;
+}
+/**
+ * 判一句。asked = 老师上一句是问句(孩子在答,「嗯」「对」就是回答);said = 嘴最近说过的话(带说完的墙钟),now 用来挑 ECHO_WINDOW_MS 以内的;
+ * mouthOn = 孩子开口那一刻嘴的声音还在放(或刚放完 300 毫秒内),false 时不比回声
+ */
+export function judge(text, o) {
+    const t = bare(text);
+    if (!t)
+        return { take: false, why: 'empty' };
+    if (!o.asked && isFiller(text))
+        return { take: false, why: 'filler' };
+    const recent = o.said.filter((x) => o.now - x.at <= ECHO_WINDOW_MS).map((x) => x.text).join('');
+    // 两个字以内的不比回声(「对」「好的」碰巧在嘴的话里也常见)
+    if (o.mouthOn !== false && recent && t.length > 2 && overlap(t, recent) >= ECHO_RATIO)
+        return { take: false, why: 'echo' };
+    return { take: true };
+}

package/dist/realtime/preview.d.ts

@@ -0,0 +1,23 @@
+export declare function previewVoice(o: {
+    voice: string;
+    text: string;
+    model?: string;
+    env?: NodeJS.ProcessEnv;
+    endpoint?: string;
+    timeoutMs?: number;
+}): Promise<{
+    wav: Buffer;
+} | {
+    error: string;
+}>;
+/** 试连一次(家长端配百炼、doctor --live):握手到 session.updated 就挂,不出声、不花钱;null = 通,否则是原因(no_auth / connect / timeout / 服务端的话) */
+export declare function probeRealtime(o?: {
+    auth?: {
+        key: string;
+        workspaceId: string;
+    };
+    model?: string;
+    env?: NodeJS.ProcessEnv;
+    endpoint?: string;
+    timeoutMs?: number;
+}): Promise<string | null>;

package/dist/realtime/preview.js

@@ -0,0 +1,38 @@
+/**
+ * 试听嘴的一个音色(工作台音色页「实时的嘴」):真连一次百炼 realtime,让它照念一句(同实时老师的照念指令),收下 24k PCM 包成 wav。
+ * 几分钱一次;调用方按「音色 + 句子」缓存,同一句同一个音色只念一次。
+ */
+import { readCue } from "./cues.js";
+import { wavOfPcm } from "../shared/wav.js";
+import { OUTPUT_RATE, RealtimeSession } from "./bailian.js";
+export async function previewVoice(o) {
+    const chunks = [];
+    let err = '';
+    let done = false;
+    const s = new RealtimeSession({ instructions: '你是一位小学老师。', voice: o.voice, model: o.model, turn: 'manual', env: o.env, endpoint: o.endpoint }, {
+        onAudio: (pcm) => { chunks.push(pcm); },
+        onError: (m) => { err = m; },
+        onResponse: (st) => { if (st === 'done')
+            done = true; },
+    });
+    const why = await s.connect();
+    if (why !== null)
+        return { error: why === 'no_auth' ? '没有百炼的 key 或业务空间 id(家长端「首页」里填,存在 ~/.config/cotutor/bailian.json)' : `连不上:${why}` };
+    s.createResponse(readCue([o.text]));
+    const until = Date.now() + (o.timeoutMs ?? 20_000);
+    while (!done && !err && Date.now() < until)
+        await new Promise((r) => setTimeout(r, 50));
+    s.close('preview');
+    if (err)
+        return { error: err };
+    if (!chunks.length)
+        return { error: done ? '没出声' : '超时' };
+    return { wav: wavOfPcm(Buffer.concat(chunks), OUTPUT_RATE) };
+}
+/** 试连一次(家长端配百炼、doctor --live):握手到 session.updated 就挂,不出声、不花钱;null = 通,否则是原因(no_auth / connect / timeout / 服务端的话) */
+export async function probeRealtime(o = {}) {
+    const s = new RealtimeSession({ instructions: '试连。', turn: 'manual', model: o.model, auth: o.auth, env: o.env, endpoint: o.endpoint, timeoutMs: o.timeoutMs }, {});
+    const why = await s.connect();
+    s.close('probe');
+    return why;
+}

package/dist/realtime/prompt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 实时老师的嘴的系统指令:只放人设与规矩,不放老师文件、activity 的流程——
+ * 2026-10-19 P1 实测:流程放进去它也带不动(看图说话六轮只接话不问),要说的话由应用每次放进 response.instructions(src/realtime/cues.ts)。
+ */
+export declare function mouthInstructions(o: {
+    display: string;
+    kidName: string;
+}): string;

package/dist/realtime/prompt.js

@@ -0,0 +1,13 @@
+/**
+ * 实时老师的嘴的系统指令:只放人设与规矩,不放老师文件、activity 的流程——
+ * 2026-10-19 P1 实测:流程放进去它也带不动(看图说话六轮只接话不问),要说的话由应用每次放进 response.instructions(src/realtime/cues.ts)。
+ */
+export function mouthInstructions(o) {
+    return [
+        `你是这个家的${o.display},对面是一个孩子,叫${o.kidName}。`,
+        '你是用嘴说话的那一位:每一次,我都会告诉你这一次说什么。只照做:接住孩子的话,或者把给你的句子原样说出来。',
+        '不讲新内容,不回答题目,不评对错,不问问题。',
+        '只有一种时候例外:我让你看孩子正在画的画,你照我那一次说的,看着画说一两句、问一句;那时也不讲题、不评对错。',
+        '说话亲切、慢一点,像当面说话;不念标点,不念括号。',
+    ].join('\n');
+}

package/dist/realtime/voices.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 嘴(百炼 realtime,qwen3.8-omni-flash-realtime)认的音色:官方列表 https://www.alibabacloud.com/help/zh/model-studio/omni-voice-list 里
+ * 「Qwen3.8-Omni 系列」那 56 个(2026-10-19 照抄;每个都真连过一次让它说一个字,都出声)。trait 是官方描述的概括,lang 是除外语以外会说的(都另会 28 种外语)。
+ * 旧模型的 Bella、Pip、Chelsie、Ethan 这个模型不认:连接照样连得上,第一次开口才报 InvalidParameter——所以写错的音色要在配置这一头拦(工作台、doctor)。
+ * 工作台音色页「实时的嘴」那一半照这张表列、试听、挑(写进 cotutor.json 的 live.voices)。
+ * 英语老师的讲稿是中文里夹英文(「apple 苹果,banana 香蕉」):2026-10-20 真连(照念 → 转写回字)Serena、Tina、Maia、Liora Mira、Mione、Theo Calm 都念对,
+ * Jennifer、Mia 的中文带英文腔(Jennifer:「腿」成了 tway,「它是什么颜色」没了),trait 里记着。
+ */
+export interface RealtimeVoice {
+    /** session.update 的 voice 参数(大小写、空格照官方) */
+    voice: string;
+    /** 官方的中文名 */
+    name: string;
+    /** 男 / 女:官方表没有这一栏,照名字与描述标;看不出的三个(Theo Calm、Arda、longanlingxin)2026-11-03 真念一句量了音高 */
+    gender: '男' | '女';
+    trait: string;
+    lang: string;
+}
+export declare const REALTIME_VOICES: readonly RealtimeVoice[];
+/** 这个模型认不认这个音色(工作台、doctor 拦写错的) */
+export declare function isRealtimeVoice(voice: string): boolean;

package/dist/realtime/voices.js

@@ -0,0 +1,71 @@
+/**
+ * 嘴(百炼 realtime,qwen3.8-omni-flash-realtime)认的音色:官方列表 https://www.alibabacloud.com/help/zh/model-studio/omni-voice-list 里
+ * 「Qwen3.8-Omni 系列」那 56 个(2026-10-19 照抄;每个都真连过一次让它说一个字,都出声)。trait 是官方描述的概括,lang 是除外语以外会说的(都另会 28 种外语)。
+ * 旧模型的 Bella、Pip、Chelsie、Ethan 这个模型不认:连接照样连得上,第一次开口才报 InvalidParameter——所以写错的音色要在配置这一头拦(工作台、doctor)。
+ * 工作台音色页「实时的嘴」那一半照这张表列、试听、挑(写进 cotutor.json 的 live.voices)。
+ * 英语老师的讲稿是中文里夹英文(「apple 苹果,banana 香蕉」):2026-10-20 真连(照念 → 转写回字)Serena、Tina、Maia、Liora Mira、Mione、Theo Calm 都念对,
+ * Jennifer、Mia 的中文带英文腔(Jennifer:「腿」成了 tway,「它是什么颜色」没了),trait 里记着。
+ */
+const v = (voice, name, gender, trait, lang = '普通话') => ({ voice, name, gender, trait, lang });
+export const REALTIME_VOICES = [
+    v('Tina', '甜甜', '女', '甜美温暖,解决问题果断(缺省)'),
+    v('Cindy', '林欣宜', '女', '台湾腔嗲嗲的小姐姐', '台湾口音'),
+    v('Liora Mira', '清欢', '女', '温柔的烟火人间感'),
+    v('Raymond', '林川野', '男', '声音清亮,爱吃外卖的宅男'),
+    v('Zane', '泽恩', '男', '磁性迷人'),
+    v('Katerina', '卡捷琳娜', '女', '御姐音,韵律感强'),
+    v('Ryan', '甜茶', '男', '节奏感强,戏感足'),
+    v('Mia', '舒然', '女', '细腻,生活美学风格的温柔博主;中英夹着说时中文带英文腔'),
+    v('Cici', '绵绵', '女', '邻家妹妹,活泼软糯'),
+    v('Theo Calm', '予安', '男', '沉静,治愈感'),
+    v('Serena', '苏瑶', '女', '温柔小姐姐'),
+    v('Maia', '四月', '女', '知性与温柔'),
+    v('Evan', '江晨', '男', '男大学生,年下奶狗'),
+    v('Qiao', '小乔妹', '女', '表面甜妹,个性十足', '台湾口音'),
+    v('Momo', '茉兔', '女', '撒娇搞怪'),
+    v('Wil', '伟伦', '男', '深圳长大的港台腔小哥哥'),
+    v('Angel', '安琪', '女', '带台式口音,甜美'),
+    v('Li Cassian', '李公公', '男', '话中有留白,善察言观色'),
+    v('Joyner', '阿逗', '男', '搞笑、夸张、接地气'),
+    v('Gold', '金爷', '男', '西海岸黑人说唱歌手风格'),
+    v('Jennifer', '詹妮弗', '女', '电影质感的美语女声;中英夹着说时中文带英文腔(苹果念成 pingguo)'),
+    v('Aiden', '艾登', '男', '精通厨艺的美语大男孩'),
+    v('Mione', '敏儿', '女', '成熟知性的英国邻家妹妹'),
+    v('Sunny', '晴儿', '女', '甜美的川妹子', '四川话'),
+    v('Dylan', '晓东', '男', '北京胡同长大的少年', '北京话'),
+    v('Eric', '程川', '男', '成都市井男子,跳脱', '四川话'),
+    v('Peter', '李彼得', '男', '天津相声,专业捧哏', '天津话'),
+    v('Joseph Chen', '阿樸伯', '男', '南洋老华侨', '闽南话'),
+    v('Marcus', '秦川', '男', '老陕风格,面宽话短', '陕西话'),
+    v('Li', '老李', '男', '南京话伯伯,爱骂骂咧咧', '南京话'),
+    v('Rocky', '阿强', '男', '幽默风趣,在线陪聊', '粤语'),
+    v('Kiki', '阿清', '女', '甜美的港妹闺蜜', '粤语'),
+    v('Sohee', '素熙', '女', '温柔开朗的韩国欧尼'),
+    v('Eliška', '艾莉卡', '女', '中欧风格'),
+    v('Alek', '阿列克', '男', '战斗民族的冷与暖'),
+    v('Arda', '阿尔达', '男', '干净利落,温润'),
+    v('Dolce', '多尔切', '男', '慵懒的意大利大叔'),
+    v('Lenn', '莱恩', '男', '德国青年,理性中带叛逆'),
+    v('Ono Anna', '小野杏', '女', '鬼灵精怪的青梅竹马'),
+    v('Sonrisa', '索尼莎', '女', '热情开朗的拉美大姐'),
+    v('Bodega', '博德加', '男', '热情的西班牙大叔'),
+    v('Andre', '安德雷', '男', '磁性、沉稳的男生'),
+    v('Radio Gol', '拉迪奥·戈尔', '男', '足球解说风格'),
+    v('Rizky', '阿力', '男', '印尼青年,声线个性'),
+    v('Roya', '萝雅', '女', '热爱运动的女孩'),
+    v('Hana', '阿幸', '女', '越南成熟姐姐'),
+    v('Jakub', '雅克', '男', '波兰文艺青年,声线磁性'),
+    v('Griet', '海娜', '女', '荷兰成熟文艺女性'),
+    v('Marina', '玛丽娜', '女', '多元文化城市长大的女孩'),
+    v('Siiri', '西芮', '女', '内敛温柔,语速舒缓'),
+    v('Ingrid', '林恩', '女', '挪威乡村姑娘'),
+    v('Sigga', '海娜', '女', '冰岛小镇知性女青年'),
+    v('Bea', '雅娜', '女', '爱喝咖啡的甜美姐姐'),
+    v('Chloe', '思怡', '女', '马来西亚白领女生'),
+    v('Emilien', '埃米尔安', '男', '浪漫的法国大哥哥'),
+    v('longanlingxin', '龙安灵心', '女', '知心温暖音'),
+];
+/** 这个模型认不认这个音色(工作台、doctor 拦写错的) */
+export function isRealtimeVoice(voice) {
+    return REALTIME_VOICES.some((x) => x.voice === voice);
+}

package/dist/runtime/activities.d.ts

@@ -0,0 +1,29 @@
+import type { ActivityRun } from '../schema/index.ts';
+export declare const ACTIVITIES_DIR = "activities";
+export interface ActivityRef {
+    tutor: string;
+    name: string;
+    /** 文件的绝对路径 */
+    file: string;
+}
+/** 例子文件(cotutor activity eval 用):和 activity 放在一起,`<名>.例子.md`;跟着 activity 一起出厂,检查时不当 activity */
+export declare const EXAMPLES_SUFFIX = ".\u4F8B\u5B50";
+/** 某个根下(包的 agents/,或 workspace 的 agents/)每位老师的 activities/*.md;examples = 连例子文件一起(出厂、升级用) */
+export declare function listActivities(agentsDir: string, tutor?: string, opts?: {
+    examples?: boolean;
+}): Promise<ActivityRef[]>;
+/** workspace 里那份的位置(就是这个名字,不认改过的名;装、升级、写都用它) */
+export declare function activityFile(root: string, tutor: string, name: string): string;
+/**
+ * 改过名的出厂 activity:旧名 → 新名。2026-11-03 批改 → 检查作业(孩子端方砖上的字)。
+ * upgrade 把 workspace 里的旧文件挪成新名(src/app/cli/activities.ts);旧草稿里的 `activity 批改`、旧话题记的名字照样认(activityName)
+ */
+export declare const ACTIVITY_RENAMES: Readonly<Record<string, string>>;
+/**
+ * 这个名字在这位老师家里实际是哪个文件:有同名的就是它;旧名的文件挪走了认新名;新名的还没有(没 upgrade 过)认旧名。都没有 → 原样
+ * (读的时候用:跑话题、首页检查、方砖;lint 的 fileName 也要用这个,不然 name 对不上)
+ */
+export declare function activityName(root: string, tutor: string, name: string): string;
+/** 读的时候找的那份:认改过的名(activityName) */
+export declare function findActivityFile(root: string, tutor: string, name: string): string;
+export declare function activityRunFor(root: string, tutor: string, name: string, raw?: string): Promise<ActivityRun>;

package/dist/runtime/activities.js

@@ -0,0 +1,72 @@
+/**
+ * 读 activity 文件(从 app/cli/activities.ts 拆出来,2026-10-29,行为不变):在哪、每位老师有哪几个、按「名=值」的参数拼成一次跑。
+ * 运行层每轮都要读,所以不放在命令行那一层;装、升级、还原、检查仍在 app/cli/activities.ts。
+ */
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseActivity, resolveParams } from "./activity.js";
+import { UsageError } from "../shared/errors.js";
+export const ACTIVITIES_DIR = 'activities';
+/** 例子文件(cotutor activity eval 用):和 activity 放在一起,`<名>.例子.md`;跟着 activity 一起出厂,检查时不当 activity */
+export const EXAMPLES_SUFFIX = '.例子';
+/** 某个根下(包的 agents/,或 workspace 的 agents/)每位老师的 activities/*.md;examples = 连例子文件一起(出厂、升级用) */
+export async function listActivities(agentsDir, tutor, opts = {}) {
+    const out = [];
+    const tutors = tutor ? [tutor] : (await readdir(agentsDir, { withFileTypes: true }).catch(() => [])).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+    for (const t of tutors) {
+        const dir = join(agentsDir, t, ACTIVITIES_DIR);
+        const files = (await readdir(dir).catch(() => [])).filter((f) => f.endsWith('.md')).sort();
+        for (const f of files)
+            if (opts.examples || !f.slice(0, -3).endsWith(EXAMPLES_SUFFIX))
+                out.push({ tutor: t, name: f.slice(0, -3), file: join(dir, f) });
+    }
+    return out;
+}
+/** workspace 里那份的位置(就是这个名字,不认改过的名;装、升级、写都用它) */
+export function activityFile(root, tutor, name) {
+    return join(root, 'agents', tutor, ACTIVITIES_DIR, `${name}.md`);
+}
+/**
+ * 改过名的出厂 activity:旧名 → 新名。2026-11-03 批改 → 检查作业(孩子端方砖上的字)。
+ * upgrade 把 workspace 里的旧文件挪成新名(src/app/cli/activities.ts);旧草稿里的 `activity 批改`、旧话题记的名字照样认(activityName)
+ */
+export const ACTIVITY_RENAMES = { 批改: '检查作业' };
+/**
+ * 这个名字在这位老师家里实际是哪个文件:有同名的就是它;旧名的文件挪走了认新名;新名的还没有(没 upgrade 过)认旧名。都没有 → 原样
+ * (读的时候用:跑话题、首页检查、方砖;lint 的 fileName 也要用这个,不然 name 对不上)
+ */
+export function activityName(root, tutor, name) {
+    const has = (n) => existsSync(activityFile(root, tutor, n));
+    if (has(name))
+        return name;
+    const to = ACTIVITY_RENAMES[name];
+    if (to && has(to))
+        return to;
+    const from = Object.keys(ACTIVITY_RENAMES).find((k) => ACTIVITY_RENAMES[k] === name);
+    if (from && has(from))
+        return from;
+    return name;
+}
+/** 读的时候找的那份:认改过的名(activityName) */
+export function findActivityFile(root, tutor, name) {
+    return activityFile(root, tutor, activityName(root, tutor, name));
+}
+export async function activityRunFor(root, tutor, name, raw = '') {
+    const file = findActivityFile(root, tutor, name);
+    const text = await readFile(file, 'utf8').catch(() => null);
+    if (text === null)
+        throw new UsageError(`${file} 不在;cotutor activity check ${tutor} 看这位老师有哪些`);
+    const params = {};
+    for (const pair of raw.split(/[;；]/).map((x) => x.trim()).filter(Boolean)) {
+        // 值可以有几行(口语课的口语单)
+        const m = /^([^=]+)=([\s\S]*)$/.exec(pair);
+        if (!m)
+            throw new UsageError(`--param 写成「名=值」,几个用 ; 隔开,如 --param '词=播种、羞愧;最多画=1'(「${pair}」不对)`);
+        params[m[1].trim()] = m[2].trim();
+    }
+    const r = resolveParams(parseActivity(text).activity, params);
+    if (r.issues.length)
+        throw new UsageError(r.issues.join(';'));
+    return { name, params: r.values };
+}

package/dist/runtime/activity-state.d.ts

@@ -0,0 +1,22 @@
+import type { Workspace } from '../schema/index.ts';
+import { type Activity, type ActivityRun, type ActivityValue, type ConversationMessage } from '../schema/index.ts';
+/** 这个话题是从哪个 activity 起的:话题里第一条带 activity 的消息(只记在第一条);没有 → null */
+export declare function threadActivity(messages: readonly ConversationMessage[], thread: string): ActivityRun | null;
+/** 读 workspace 里那份 activity 文件;不在 → null */
+export declare function readActivity(ws: Workspace, tutor: string, name: string): Promise<Activity | null>;
+/**
+ * 应用算的值,只算 activity 文件「应用算的」里列了的:
+ *   还能画 = 参数「最多画」减这个话题画了的(画好的与在画的),不小于 0;家长没填最多画 = 不限,不写这一项(拦法「还能画」照过)
+ *   缺 = 这个话题最后一张画图卡被哪条拦法拦下了;画了、没被拦、还没有画图卡 → 空
+ */
+export declare function activityState(ws: Workspace, tutor: string, date: string, messages: readonly ConversationMessage[], thread: string, run: ActivityRun, a: Pick<Activity, 'state'>, now?: number): Promise<Record<string, ActivityValue>>;
+/** 这一轮(job)所在话题的 activity 文件「画家收到什么」;不在 activity 话题、文件不在、没有那节 → null(照 cotutor.json 的画风) */
+export declare function paintTool(ws: Workspace, tutor: string, date: string, job: string): Promise<{
+    prompt: string;
+    negative?: string;
+} | null>;
+/**
+ * 画图前的拦:这一轮(job)在 activity 话题里,就照 activity 文件「应用拦的」查;不在 activity 话题、文件不在 → null(照旧画)。
+ * 返回的函数在画图队里现调,同一轮第二张看得到第一张已经在画。
+ */
+export declare function paintGate(ws: Workspace, tutor: string, date: string, job: string, now: () => number): Promise<(() => Promise<string | null>) | null>;

package/dist/runtime/activity-state.js

@@ -0,0 +1,83 @@
+/**
+ * activity 话题里应用算的值与拦法的接线(4.1):读这个话题的 activity 文件、
+ * 数这个话题画了几张、今天还剩几张、上一张为什么没画。纯判断在 src/runtime/activity.ts(gatePasses / failingGate),这里只管读盘。
+ */
+import { readFile } from 'node:fs/promises';
+import { findActivityFile } from "./activities.js";
+import { failingGate, parseActivity } from "./activity.js";
+import { threads } from "../schema/index.js";
+import {} from "../schema/index.js";
+import { paintRecordAt } from "../scenes/paint/painter.js";
+/** 这个话题是从哪个 activity 起的:话题里第一条带 activity 的消息(只记在第一条);没有 → null */
+export function threadActivity(messages, thread) {
+    const ths = threads(messages);
+    return messages.find((m, i) => ths[i] === thread && m.activity)?.activity ?? null;
+}
+/** 读 workspace 里那份 activity 文件;不在 → null */
+export async function readActivity(ws, tutor, name) {
+    const text = await readFile(findActivityFile(ws.root, tutor, name), 'utf8').catch(() => null);
+    return text === null ? null : parseActivity(text).activity;
+}
+/** 这个话题里的画图卡,文件顺序:哪一轮第几张 */
+function paintCards(messages, thread) {
+    const ths = threads(messages);
+    return messages.flatMap((m, i) => (ths[i] === thread && m.section ? m.section.cards.flatMap((c, n) => (c.kind === 'paint' ? [{ job: m.job, n }] : [])) : []));
+}
+/**
+ * 应用算的值,只算 activity 文件「应用算的」里列了的:
+ *   还能画 = 参数「最多画」减这个话题画了的(画好的与在画的),不小于 0;家长没填最多画 = 不限,不写这一项(拦法「还能画」照过)
+ *   缺 = 这个话题最后一张画图卡被哪条拦法拦下了;画了、没被拦、还没有画图卡 → 空
+ */
+export async function activityState(ws, tutor, date, messages, thread, run, a, now = Date.now()) {
+    const out = {};
+    const want = new Set(a.state.map((s) => s.name));
+    if (!want.size)
+        return out;
+    const cards = paintCards(messages, thread);
+    const records = await Promise.all(cards.map((c) => paintRecordAt(ws, tutor, date, c.job, c.n, now)));
+    if (want.has('还能画')) {
+        const drawn = records.filter((r) => r?.state === 'done' || r?.state === 'drawing').length;
+        if (typeof run.params.最多画 === 'number')
+            out.还能画 = Math.max(0, run.params.最多画 - drawn);
+    }
+    if (want.has('缺')) {
+        const last = records[records.length - 1];
+        out.缺 = last?.state === 'none' && last.error.startsWith('gate:') ? last.error.slice(5) : '';
+    }
+    return out;
+}
+/** 这一轮(job)所在话题的 activity 文件「画家收到什么」;不在 activity 话题、文件不在、没有那节 → null(照 cotutor.json 的画风) */
+export async function paintTool(ws, tutor, date, job) {
+    const { readIndex } = await import("./journal/store.js");
+    const index = await readIndex(ws, tutor, date);
+    const at = index.messages.findIndex((m) => m.job === job);
+    if (at < 0)
+        return null;
+    const run = threadActivity(index.messages, threads(index.messages)[at]);
+    const t = run ? (await readActivity(ws, tutor, run.name))?.tools.find((x) => x.tool === '画家') : null;
+    return t ? { prompt: t.prompt, ...(t.negative ? { negative: t.negative } : {}) } : null;
+}
+/**
+ * 画图前的拦:这一轮(job)在 activity 话题里,就照 activity 文件「应用拦的」查;不在 activity 话题、文件不在 → null(照旧画)。
+ * 返回的函数在画图队里现调,同一轮第二张看得到第一张已经在画。
+ */
+export async function paintGate(ws, tutor, date, job, now) {
+    const { readIndex } = await import("./journal/store.js");
+    const index = await readIndex(ws, tutor, date);
+    const at = index.messages.findIndex((m) => m.job === job);
+    if (at < 0)
+        return null;
+    const thread = threads(index.messages)[at];
+    const run = threadActivity(index.messages, thread);
+    const a = run ? await readActivity(ws, tutor, run.name) : null;
+    if (!run || !a || !a.gates.length)
+        return null;
+    return async () => {
+        const latest = await readIndex(ws, tutor, date);
+        const ths = threads(latest.messages);
+        const mine = latest.messages.filter((_, i) => ths[i] === thread);
+        // 这一轮还没轮到的卡没有记录,不算;同一轮前面那张已经在画,算
+        const state = await activityState(ws, tutor, date, mine, thread, run, { state: [{ name: '还能画', type: '数', line: 0 }] }, now());
+        return failingGate(a, { thread: mine, job, state });
+    };
+}

package/dist/runtime/activity.d.ts

@@ -0,0 +1,63 @@
+/**
+ * activity 文件的纯函数(形状在 src/schema/activity.ts):
+ * 解析(永不抛,写坏的行变成问题)、检查(带行号,fix = 要改 / note = 提醒)、递给老师的那节(剥注释、按参数与卡裁段)、工具人模板填插槽。不读文件。
+ */
+import { type Activity, type ActivityValue, type ConversationMessage } from '../schema/index.ts';
+export type ActivityIssueLevel = 'fix' | 'note';
+export interface ActivityIssue {
+    /** fix = 要改;note = 提醒 */
+    level: ActivityIssueLevel;
+    text: string;
+    /** 原文行号,1 起 */
+    line?: number;
+}
+export interface ParsedActivity {
+    activity: Activity;
+    /** 写法上的问题(哪行解析不了);对不对得上注册表由 checkActivity 查 */
+    issues: ActivityIssue[];
+}
+/** 解析一份 activity 文件。永不抛:写坏的行进 issues,其余照常解析 */
+export declare function parseActivity(text: string): ParsedActivity;
+export interface CheckOptions {
+    /** 文件名(不带 .md);给了就查 name 和它一样 */
+    fileName?: string;
+    /** 这位老师的卡(cotutor.json tutors.<老师>.cards);不给 = 全部 */
+    tutorCards?: readonly string[];
+}
+/** 这个 activity 的话题里老师有哪些卡:老师的并上 activity 头上的,text 总在 */
+export declare function activityCards(a: Activity, tutorCards?: readonly string[]): string[];
+/** 对注册表查:参数、应用算的、应用拦的、裁段的名字、正文用的卡、插槽、第一句与收 */
+export declare function checkActivity(a: Activity, opts?: CheckOptions): ActivityIssue[];
+/** 解析 + 检查,按行号排 */
+export declare function lintActivity(text: string, opts?: CheckOptions): {
+    activity: Activity;
+    issues: ActivityIssue[];
+};
+/** 填了没有:空字符串、空列表、没给都算没填 */
+export declare function isFilled(v: unknown): boolean;
+/**
+ * 递给老师的那节:剥掉给人看的注释,`{{有 名}}` 按「参数填了」或「这个话题有这种卡」留或去。
+ * 没有「老师怎么带」返回 null。守卫不配对会抛(checkActivity 先报)。
+ */
+export declare function renderTutorSection(a: Activity, opts: {
+    params?: Record<string, unknown>;
+    cards: readonly string[];
+}): string | null;
+/**
+ * 首页按钮下面家长填的参数(原文)→ 按 activity 文件的「家长填的」解析成值:按声明的顺序、补缺省、按类型转。
+ * 写了没有的参数、要填的没填、类型不对,进 issues(一条一句,给首页检查);值里只留解析得了的。
+ */
+export declare function resolveParams(a: Activity, raw: Readonly<Record<string, string>>): {
+    values: Record<string, ActivityValue>;
+    issues: string[];
+};
+/** 拦法要看的:这个话题的消息(文件顺序)、这一轮的 job、应用算好的值 */
+export interface GateInput {
+    thread: readonly Pick<ConversationMessage, 'job' | 'from' | 'action' | 'section'>[];
+    job: string;
+    state: Readonly<Record<string, ActivityValue>>;
+}
+/** 一条拦法过没过(规则名见 ACTIVITY_GATES;不认得的当过,activity check 会报) */
+export declare function gatePasses(rule: string, input: GateInput): boolean;
+/** 按 activity 文件「应用拦的」的顺序,第一条没过的规则名;都过了 → null */
+export declare function failingGate(a: Pick<Activity, 'gates'>, input: GateInput): string | null;