cotutor 0.2.0 → 0.4.0

package/dist/runtime/context/context-pack.js

@@ -0,0 +1,182 @@
+/**
+ * 上下文包序列化:固定 YAML 块 + 老师守则原文(<cotutor-rules>)、家长笔记原文段(<vault-note>)+ `---` + 消息原文。
+ * 手写 YAML 子集:标量能裸写就裸写,其余 JSON 双引号(合法 YAML);空的 plan / recent 不写。
+ */
+import { ContextPackSchema, VAULT_PACK_ROLES } from "../../schema/index.js";
+const BARE = /^[A-Za-z0-9_][A-Za-z0-9_\-.:T]*$/;
+export function yamlScalar(v) {
+    if (typeof v !== 'string')
+        return String(v);
+    return BARE.test(v) && !/^(true|false|null|~|yes|no)$/i.test(v) ? v : JSON.stringify(v);
+}
+export function renderContextPack(pack) {
+    const p = ContextPackSchema.parse(pack);
+    const out = ['cotutor:', `  at: ${yamlScalar(p.at)}`];
+    if (p.slot)
+        out.push(`  slot: ${yamlScalar(p.slot)}`);
+    if (p.focus?.card)
+        out.push('  focus:', `    card: ${yamlScalar(p.focus.card)}`);
+    if (p.rules)
+        out.push(`  rules: ${yamlScalar(p.rules)}`);
+    if (p.boardGuide)
+        out.push(`  boardGuide: ${yamlScalar(p.boardGuide)}`);
+    if (p.activityGuide)
+        out.push(`  activityGuide: ${yamlScalar(p.activityGuide)}`);
+    if (p.semester)
+        out.push(`  semester: ${yamlScalar(p.semester)}`);
+    if (p.profile)
+        out.push(`  profile: ${yamlScalar(p.profile)}`);
+    if (p.child)
+        out.push(`  child: ${yamlScalar(p.child)}`);
+    if (p.entry)
+        out.push(`  entry: ${yamlScalar(p.entry)}`);
+    if (p.memory)
+        out.push(`  memory: ${yamlScalar(p.memory)}`);
+    if (p.lesson)
+        out.push(`  lesson: ${yamlScalar(p.lesson)}`);
+    if (p.refs?.length) {
+        out.push('  refs:');
+        for (const r of p.refs)
+            out.push(`    - ${yamlScalar(r)}`);
+    }
+    if (p.plan.length) {
+        out.push('  plan:');
+        for (const l of p.plan)
+            out.push(`    - ${yamlScalar(l)}`);
+    }
+    if (p.recent.length) {
+        out.push('  recent:');
+        for (const r of p.recent)
+            out.push(`    - ${yamlScalar(`${r.date} ${r.claim}`)}`);
+    }
+    if (p.lookup?.length) {
+        out.push('  lookup:');
+        for (const l of p.lookup)
+            out.push(`    - ${yamlScalar(l)}`);
+    }
+    // vault 是 workspace 级的,放在每条消息才变的 board / cards / photos 前面
+    if (p.vault) {
+        out.push('  vault:', `    root: ${yamlScalar(p.vault.root)}`);
+        for (const r of VAULT_PACK_ROLES)
+            if (p.vault[r])
+                out.push(`    ${r}: ${yamlScalar(p.vault[r])}`);
+    }
+    if (p.board === 'off')
+        out.push('  board: off');
+    if (p.home) {
+        out.push('  home:', `    button: ${yamlScalar(p.home.button)}`);
+        if (p.home.brief)
+            out.push(`    brief: ${yamlScalar(p.home.brief)}`);
+    }
+    if (p.lecture) {
+        const l = p.lecture;
+        out.push('  lecture:', `    title: ${yamlScalar(l.title)}`, `    source: ${yamlScalar(l.source)}`, `    length: ${yamlScalar(l.length)}`);
+        if (l.lines.length) {
+            out.push('    lines:');
+            for (const x of l.lines)
+                out.push(`      - ${yamlScalar(x)}`);
+        }
+        out.push(`    watched: ${yamlScalar(l.watched)}`);
+        if (l.marks.length) {
+            out.push('    marks:');
+            for (const x of l.marks)
+                out.push(`      - ${yamlScalar(x)}`);
+        }
+    }
+    if (p.continue) {
+        const c = p.continue;
+        out.push('  continue:', `    from: ${yamlScalar(c.from)}`);
+        if (c.title)
+            out.push(`    title: ${yamlScalar(c.title)}`);
+        if (c.said.length) {
+            out.push('    said:');
+            for (const l of c.said)
+                out.push(`      - ${yamlScalar(l)}`);
+        }
+        if (c.cards.length) {
+            out.push('    cards:');
+            for (const l of c.cards)
+                out.push(`      - ${yamlScalar(l)}`);
+        }
+        out.push(`    index: ${yamlScalar(c.index)}`);
+    }
+    if (p.live) {
+        const l = p.live;
+        if (!l.caught && l.cut === undefined && !l.warmup?.length && l.phone === undefined && !l.app && !l.draw?.length)
+            out.push('  live: true');
+        else {
+            out.push('  live:');
+            if (l.caught)
+                out.push(`    caught: ${yamlScalar(l.caught)}`);
+            if (l.cut !== undefined)
+                out.push(`    cut: ${l.cut}`);
+            if (l.app)
+                out.push(`    app: ${l.app}`);
+            if (l.phone !== undefined)
+                out.push(`    phone: ${l.phone}`);
+            if (l.warmup?.length) {
+                out.push('    warmup:');
+                for (const x of l.warmup)
+                    out.push(`      - ${yamlScalar(x)}`);
+            }
+            if (l.draw?.length) {
+                out.push('    draw:');
+                for (const x of l.draw)
+                    out.push(`      - ${yamlScalar(x)}`);
+            }
+        }
+    }
+    if (p.drawing)
+        out.push(`  drawing: ${yamlScalar(p.drawing)}`);
+    if (p.cards?.length) {
+        out.push('  cards:');
+        for (const c of p.cards)
+            out.push(`    - ${yamlScalar(c)}`);
+    }
+    if (p.photos?.length) {
+        out.push('  photos:');
+        for (const c of p.photos)
+            out.push(`    - ${yamlScalar(c)}`);
+    }
+    if (p.photoFiles?.length) {
+        out.push('  photoFiles:');
+        for (const c of p.photoFiles)
+            out.push(`    - ${yamlScalar(c)}`);
+    }
+    // activity 放最后、键序固定:剩几张这种每条会变的,离孩子的话最近
+    if (p.activity) {
+        const a = p.activity;
+        out.push('  activity:', `    name: ${yamlScalar(a.name)}`);
+        for (const [key, values] of [['params', a.params], ['state', a.state]]) {
+            const entries = Object.entries(values);
+            if (!entries.length)
+                continue;
+            out.push(`    ${key}:`);
+            for (const [k, v] of entries) {
+                if (!Array.isArray(v))
+                    out.push(`      ${yamlScalar(k)}: ${yamlScalar(v)}`);
+                else {
+                    out.push(`      ${yamlScalar(k)}:`);
+                    for (const x of v)
+                        out.push(`        - ${yamlScalar(x)}`);
+                }
+            }
+        }
+    }
+    // 守则是出厂的,不是家长的笔记,换个标签;路径相对 workspace 根(家长笔记的相对 vault 根)
+    for (const n of p.notes ?? []) {
+        const shipped = n.role === 'rules' || n.role === 'boardGuide' || n.role === 'activityGuide';
+        const tag = n.role === 'rules' ? 'cotutor-rules' : n.role === 'boardGuide' ? 'cotutor-board' : n.role === 'activityGuide' ? 'cotutor-activity' : 'vault-note';
+        out.push(shipped ? `<${tag} path=${JSON.stringify(n.path)}>` : `<${tag} role="${n.role}" path=${JSON.stringify(n.path)}>`, n.text.replace(/\s+$/, ''), `</${tag}>`);
+    }
+    return out.join('\n');
+}
+/** 按政策截 plan / recent,再拼成「YAML 块 + 笔记原文 --- 消息」(笔记原文已在取材时按 entryChars 截) */
+export function buildContextPack(pack, message, limits) {
+    const trimmed = {
+        ...pack,
+        plan: (pack.plan ?? []).slice(0, limits.planLines),
+        recent: (pack.recent ?? []).slice(-limits.recent),
+    };
+    return `${renderContextPack(trimmed)}\n---\n${message.trim()}\n`;
+}

package/dist/runtime/context/thread-digest.d.ts

@@ -0,0 +1,4 @@
+import type { ConversationMessage } from '../../schema/index.ts';
+export declare const DIGEST_HEAD = "(\u5E94\u7528\u6CE8:\u8FD9\u4E2A\u8BDD\u9898\u524D\u9762\u804A\u5F97\u957F\u4E86,\u4E4B\u524D\u7684\u5BF9\u8BDD\u4E0D\u518D\u539F\u6837\u7ED9\u4F60\u3002\u4E0B\u9762\u662F\u524D\u9762\u7684\u7ECF\u8FC7,\u6309\u5148\u540E:\u5B69\u5B50\u7684\u539F\u8BDD\u3001\u4F60\u8BF4\u8FC7\u7684\u8BDD\u3001\u51FA\u8FC7\u7684\u5361\u3002\u63A5\u7740\u5F80\u4E0B\u6559,\u8BB2\u8FC7\u7684\u3001\u505A\u8FC7\u7684\u522B\u518D\u91CD\u590D\u3002)";
+/** messages:这个话题里这一轮之前的消息,按先后 */
+export declare function threadDigest(messages: readonly ConversationMessage[]): string;

package/dist/runtime/context/thread-digest.js

@@ -0,0 +1,35 @@
+/**
+ * 长话题的前情(API 运行时整段压缩的那一轮用,src/runtime/runner.ts):照索引按先后拼——
+ * 孩子的原话(交卡、拍照、交画、看小课堂各写成一句)、老师说的讲稿、出过的卡(种类与标签);最后一轮的卡给全,孩子可能正在答。
+ * 不交给模型去摘:不花钱、不用等、不会编出孩子没说过的话(你说我画那种要一句句攒孩子故事的,原话一个字不能动)。
+ */
+import { cardLabel } from "../../board/cards/index.js";
+export const DIGEST_HEAD = '(应用注:这个话题前面聊得长了,之前的对话不再原样给你。下面是前面的经过,按先后:孩子的原话、你说过的话、出过的卡。接着往下教,讲过的、做过的别再重复。)';
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n)}…` : s);
+/** messages:这个话题里这一轮之前的消息,按先后 */
+export function threadDigest(messages) {
+    const out = [DIGEST_HEAD];
+    messages.forEach((m, i) => {
+        const last = i === messages.length - 1;
+        if (m.bookkeep)
+            out.push('应用:(记账)');
+        else {
+            const did = [
+                m.text.trim(),
+                m.photos?.length ? `(拍了 ${m.photos.length} 张照片)` : '',
+                m.drawing ? '(交了一张画)' : '',
+                m.lecture ? `(看完小课堂「${m.lecture.title}」)` : '',
+                ...(m.cards ?? []).map((c) => `(卡 ${c.card}:${c.text})`),
+            ].filter(Boolean);
+            out.push(`${m.from === 'kid' ? '孩子' : '应用'}:${clip(did.join(' '), m.from === 'kid' ? 2000 : 200)}`);
+        }
+        if (m.result === 'error') {
+            out.push('老师:(这一轮没回完)');
+            return;
+        }
+        const said = (m.section?.lines ?? []).map((l) => l.text).join(' ') || m.kidText || '';
+        const cards = (m.section?.cards ?? []).map((c) => (last ? `${c.kind}:${clip(JSON.stringify(c.props), 600)}` : `${c.kind}「${cardLabel(c)}」`));
+        out.push(`老师:${said}${cards.length ? ` [卡:${cards.join(';')}]` : ''}`);
+    });
+    return out.join('\n');
+}

package/dist/runtime/context/tutor-rules.d.ts

@@ -0,0 +1,25 @@
+export declare const TUTOR_SKILL = "cotutor-tutor";
+/** 相对 workspace 根 */
+export declare const TUTOR_RULES_PATH = ".agents/skills/cotutor-tutor/SKILL.md";
+/**
+ * 放进上下文包的正文:去掉 frontmatter(那是给 CLI 的技能索引看的)与给人看的注释,按这位老师的卡裁 `{{有 …}}` 段(没给 = 全部)。
+ * 守卫写坏了(家长改过的机器件)就只去掉守卫行,整篇照给。
+ */
+export declare function tutorRulesBody(skillMd: string, kinds?: readonly string[]): string;
+/** 谁拿守则:有脸的老师(键以 -tutor 结尾);工具人的工作流写在自己文件里 */
+export declare function takesTutorRules(agent: string): boolean;
+/** 板书写法(机器技能 cotutor-board 的 SKILL.md),相对 workspace 根。由应用递给老师:运行时能预载就进系统提示,否则进话题第一条的 <cotutor-board> */
+export declare const BOARD_GUIDE_PATH = ".agents/skills/cotutor-board/SKILL.md";
+/** 递给老师的正文:去掉 frontmatter 与给人看的注释 */
+export declare function boardGuideBody(skillMd: string): string;
+/** 上下文包 boardGuide: 行在预载时写的话(事实陈述,不让老师自查) */
+export declare const BOARD_GUIDE_IN_SYSTEM = "\u5DF2\u5728\u4F60\u7684\u7CFB\u7EDF\u63D0\u793A\u91CC(\u300C# \u677F\u4E66\u600E\u4E48\u5199\u300D),\u4E0D\u7528\u8BFB";
+/**
+ * 回归检查:板书写法已经在系统提示里,老师这轮还用工具去读它 → 系统提示里那份没起作用(换模型后最先坏的地方)。
+ * 认三种:技能工具(旧轮次 claude 的 Skill、qwen 的 skill,按工具类别认)点名 cotutor-board;任何工具的参数里带 cotutor-board/SKILL.md(read_file 等),或旧轮次按老师裁的那份 .cotutor/board/。
+ * references/<种类>.md 是按需读的,不算。
+ */
+export declare function boardGuideReads(tools: readonly {
+    name: string;
+    arg: string;
+}[]): string[];

package/dist/runtime/context/tutor-rules.js

@@ -0,0 +1,47 @@
+/**
+ * 老师守则(机器技能 cotutor-tutor):有脸的老师共同的那几段(上下文包、三种回复、记忆段、不变的规矩)。
+ * 老师文件拷进 workspace 就归家长、改过 upgrade 就不再换,公共规矩放在那里修不到每一家;放进机器技能每次 upgrade 覆盖,
+ * 由应用在每个话题第一条把原文放进上下文包(<cotutor-rules>,同一话题没改过的写「未变」),不靠老师自己去 Read。
+ */
+import { parseAgentFile } from "../agent-file.js";
+import { stripHumanNotes } from "../../shared/human-notes.js";
+import { applyCardGuards } from "../../board/card-guards.js";
+import { BOARD_CARD_KINDS } from "../../schema/config.js";
+import { toolKind } from "../../brain/index.js";
+import { SKILLS_DIR } from "../../schema/workspace.js";
+export const TUTOR_SKILL = 'cotutor-tutor';
+/** 相对 workspace 根 */
+export const TUTOR_RULES_PATH = `${SKILLS_DIR}/${TUTOR_SKILL}/SKILL.md`;
+/**
+ * 放进上下文包的正文:去掉 frontmatter(那是给 CLI 的技能索引看的)与给人看的注释,按这位老师的卡裁 `{{有 …}}` 段(没给 = 全部)。
+ * 守卫写坏了(家长改过的机器件)就只去掉守卫行,整篇照给。
+ */
+export function tutorRulesBody(skillMd, kinds = BOARD_CARD_KINDS) {
+    const body = stripHumanNotes(parseAgentFile(skillMd).body);
+    try {
+        return applyCardGuards(body, kinds);
+    }
+    catch {
+        return body.replace(/^\{\{\/?有[^}]*\}\}\s*\n/gm, '');
+    }
+}
+/** 谁拿守则:有脸的老师(键以 -tutor 结尾);工具人的工作流写在自己文件里 */
+export function takesTutorRules(agent) {
+    return agent.endsWith('-tutor');
+}
+/** 板书写法(机器技能 cotutor-board 的 SKILL.md),相对 workspace 根。由应用递给老师:运行时能预载就进系统提示,否则进话题第一条的 <cotutor-board> */
+export const BOARD_GUIDE_PATH = `${SKILLS_DIR}/cotutor-board/SKILL.md`;
+/** 递给老师的正文:去掉 frontmatter 与给人看的注释 */
+export function boardGuideBody(skillMd) {
+    return stripHumanNotes(parseAgentFile(skillMd).body);
+}
+/** 上下文包 boardGuide: 行在预载时写的话(事实陈述,不让老师自查) */
+export const BOARD_GUIDE_IN_SYSTEM = '已在你的系统提示里(「# 板书怎么写」),不用读';
+/**
+ * 回归检查:板书写法已经在系统提示里,老师这轮还用工具去读它 → 系统提示里那份没起作用(换模型后最先坏的地方)。
+ * 认三种:技能工具(旧轮次 claude 的 Skill、qwen 的 skill,按工具类别认)点名 cotutor-board;任何工具的参数里带 cotutor-board/SKILL.md(read_file 等),或旧轮次按老师裁的那份 .cotutor/board/。
+ * references/<种类>.md 是按需读的,不算。
+ */
+export function boardGuideReads(tools) {
+    return tools.filter((t) => (toolKind(t.name) === 'skill' && t.arg.trim() === 'cotutor-board') || t.arg.includes('cotutor-board/SKILL.md') || t.arg.includes('.cotutor/board/')).map((t) => `${t.name} ${t.arg}`.trim());
+}

package/dist/runtime/delivery/delivery.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 实时那一轮的交付(从 call.ts 拆出来,2026-10-29,行为不变):
+ * 讲稿排队(src/runtime/delivery/queue.ts)、嘴的声音在孩子端排到哪(src/runtime/delivery/playback.ts)、告诉孩子端第几句开始放、打断时孩子听到第几句。
+ * 哪一拍该交给嘴由排队定,交给嘴(要嘴说、热身那句要不要等孩子)由 LiveCall 在 onRead 里做;嘴这次回答的进度(要了没、出完没)也在 LiveCall。
+ * - 按句不按拍(2026-10-19):讲稿定稿一句交一句(lines),嘴一空就把排着的几句一起交给它照念
+ * - 一段照念的第一句按第一块声音到孩子端的时刻发 read;第二句起等这段的声音出齐、按字数比例摊(readRest)
+ * - 打断(cut):孩子端在放的那段里亮到了哪句就报哪句,还没亮报段首;这一轮一句都没念到就被打断报 0;进下一轮的上下文包 live:,带了就清
+ */
+import type { MouthEvent } from '../journal/mouth.ts';
+import { type Beat, type Echo, type QueueEvent, type QueueState } from './queue.ts';
+/** 嘴这次回答是什么:接住(孩子这一轮)、照念哪几句、边画边聊(哪张画) */
+export type Said = {
+    kind: 'catch';
+} | {
+    kind: 'read';
+    beat: Beat;
+} | {
+    kind: 'chat';
+    canvas: string;
+};
+export interface DeliveryDeps {
+    /** 通话里的毫秒(录像的钟) */
+    now(): number;
+    /** 发给孩子端 */
+    send(o: Record<string, unknown>): void;
+    /** 记嘴这一道的一条事件(那一轮起来了补进它的 events.jsonl) */
+    event(job: string | null, at: number, ev: MouthEvent): void;
+    /** 排队说这一拍该交给嘴了 */
+    onRead(beat: Beat): void;
+    ended(): boolean;
+}
+export declare class Delivery {
+    private q;
+    /** 嘴的声音在孩子端排到哪(按它的排法算),每段带它是接住还是哪一拍 */
+    private play;
+    /** 最近告诉孩子端开始放的那句;打断时报它 */
+    private lastRead;
+    /** 最近开始放的那句是问句:孩子再开口就是在答(接住只「嗯」一声,cue 的 answer) */
+    private askedNow;
+    /** 一段里第一句的 read(挂电话时撤)与第二句起的(按字数摊的时刻;打断时撤) */
+    private readonly firstTimers;
+    private readTimers;
+    /** 正在写的那一轮(脑)与已经交给排队的讲稿句数 */
+    private current;
+    private queued;
+    /** 上一轮讲稿念到第几句被打断(1 起);交给脑时带上,带了就清 */
+    private cutAt;
+    private readonly deps;
+    constructor(deps: DeliveryDeps);
+    get job(): string | null;
+    get asked(): boolean;
+    /** 排着没交给嘴的拍数、闸关着没有(小课堂那段、热身那句、打电话的铃) */
+    get pending(): number;
+    get gated(): QueueState['gated'];
+    /** 嘴的声音在孩子端放到什么时候(通话毫秒) */
+    get end(): number;
+    /** 排队走一步;该交给嘴的交给 onRead;回按下时丢掉的拍 */
+    step(ev: QueueEvent): Beat[];
+    /** 告诉排队一件事,不管它回什么(要了接住、松手、开口暂停) */
+    note(ev: QueueEvent): void;
+    /** 嘴这次回答完了(或断了):排队可以交下一段 */
+    idle(): void;
+    /** 交给嘴的那段一个字都没出就卡住了:放回排头,换好连接 done 了再交 */
+    retry(beat: Beat): void;
+    /** 嘴的一块声音到了:接在孩子端排着的后面;回它在孩子端开始放的时刻 */
+    add(said: Said, ms: number): number;
+    /** 孩子端清了播放队列:时间线从 at(缺省现在)截断 */
+    flush(at?: number): void;
+    /** 脑开始写新的一轮 */
+    begin(job: string): void;
+    /** 讲稿又定稿了几句:按序号接着交给排队(重复的、跳号的不收) */
+    lines(lines: {
+        i: number;
+        text: string;
+        play?: boolean;
+        echo?: Echo;
+        call?: true;
+    }[]): void;
+    /** 到 at(孩子端放到的时刻)告诉孩子端:这一段的第 k 句开始放了 */
+    readAt(beat: Beat, k: number, at: number): void;
+    /** 一段照念的声音出齐了:这段在孩子端从哪放到哪已知,第二句起按字数比例摊开各发一个 read */
+    readRest(said: Said & {
+        kind: 'read';
+    }): void;
+    /**
+     * 孩子按下(或不是说的那一轮开始):排着的丢掉,记下孩子听到第几句,撤掉还没发的 read。
+     * playing = 嘴的声音还在出 / 还在放;said = 嘴这次在要的回答;now = 打断的时刻
+     */
+    interrupt(playing: boolean, said: Said | null, now: number): void;
+    /** 交给脑时带上上一轮念到第几句被打断;带了就清 */
+    takeCut(): number | undefined;
+    /** 挂电话:还没发的 read 都撤 */
+    stop(): void;
+}

package/dist/runtime/delivery/delivery.js

@@ -0,0 +1,145 @@
+import { addChunk, flushAt, playbackInit, playingAt } from "./playback.js";
+import { queueInit, queueStep } from "./queue.js";
+export class Delivery {
+    q = queueInit();
+    /** 嘴的声音在孩子端排到哪(按它的排法算),每段带它是接住还是哪一拍 */
+    play = playbackInit();
+    /** 最近告诉孩子端开始放的那句;打断时报它 */
+    lastRead = null;
+    /** 最近开始放的那句是问句:孩子再开口就是在答(接住只「嗯」一声,cue 的 answer) */
+    askedNow = false;
+    /** 一段里第一句的 read(挂电话时撤)与第二句起的(按字数摊的时刻;打断时撤) */
+    firstTimers = [];
+    readTimers = [];
+    /** 正在写的那一轮(脑)与已经交给排队的讲稿句数 */
+    current = null;
+    queued = 0;
+    /** 上一轮讲稿念到第几句被打断(1 起);交给脑时带上,带了就清 */
+    cutAt;
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get job() {
+        return this.current;
+    }
+    get asked() {
+        return this.askedNow;
+    }
+    /** 排着没交给嘴的拍数、闸关着没有(小课堂那段、热身那句、打电话的铃) */
+    get pending() {
+        return this.q.pending.length;
+    }
+    get gated() {
+        return this.q.gated;
+    }
+    /** 嘴的声音在孩子端放到什么时候(通话毫秒) */
+    get end() {
+        return this.play.end;
+    }
+    /** 排队走一步;该交给嘴的交给 onRead;回按下时丢掉的拍 */
+    step(ev) {
+        const { s, act } = queueStep(this.q, ev);
+        this.q = s;
+        if (act?.kind === 'read')
+            this.deps.onRead(act.beat);
+        return act?.kind === 'dropped' ? act.beats : [];
+    }
+    /** 告诉排队一件事,不管它回什么(要了接住、松手、开口暂停) */
+    note(ev) {
+        this.q = queueStep(this.q, ev).s;
+    }
+    /** 嘴这次回答完了(或断了):排队可以交下一段 */
+    idle() {
+        this.q = { ...this.q, busy: false };
+    }
+    /** 交给嘴的那段一个字都没出就卡住了:放回排头,换好连接 done 了再交 */
+    retry(beat) {
+        this.note({ e: 'retry', beat });
+    }
+    /** 嘴的一块声音到了:接在孩子端排着的后面;回它在孩子端开始放的时刻 */
+    add(said, ms) {
+        const r = addChunk(this.play, said, this.deps.now(), ms);
+        this.play = r.p;
+        return r.start;
+    }
+    /** 孩子端清了播放队列:时间线从 at(缺省现在)截断 */
+    flush(at = this.deps.now()) {
+        this.play = flushAt(this.play, at);
+    }
+    /** 脑开始写新的一轮 */
+    begin(job) {
+        this.current = job;
+        this.queued = 0;
+    }
+    /** 讲稿又定稿了几句:按序号接着交给排队(重复的、跳号的不收) */
+    lines(lines) {
+        if (!this.current)
+            return;
+        for (const l of lines) {
+            if (l.i !== this.queued)
+                continue;
+            this.queued++;
+            this.step({ e: 'beat', beat: { job: this.current, lines: [l.i], texts: [l.text], ...(l.play ? { play: true } : {}), ...(l.echo ? { echo: l.echo } : {}), ...(l.call ? { call: true } : {}) } });
+        }
+    }
+    /** 到 at(孩子端放到的时刻)告诉孩子端:这一段的第 k 句开始放了 */
+    readAt(beat, k, at) {
+        const t = setTimeout(() => {
+            if (this.deps.ended() || this.q.dropJob === beat.job)
+                return;
+            this.lastRead = { job: beat.job, line: beat.lines[k] };
+            this.askedNow = /[?？]\s*$/.test(beat.texts[k] ?? '');
+            // play:这句念完孩子端放小课堂那一段(放完回 staged);echo:念完卡亮「轮到你」;call:念完响铃
+            const last = k === beat.lines.length - 1;
+            this.deps.send({ t: 'read', job: beat.job, line: beat.lines[k], text: beat.texts[k], ...(beat.play && last ? { play: true } : {}), ...(beat.echo && last ? { echo: true } : {}), ...(beat.call && last ? { call: true } : {}) });
+            this.deps.event(beat.job, Date.now(), { lane: 'mouth', kind: 'read', line: beat.lines[k] });
+        }, Math.max(0, at - this.deps.now()));
+        (k === 0 ? this.firstTimers : this.readTimers).push(t);
+    }
+    /** 一段照念的声音出齐了:这段在孩子端从哪放到哪已知,第二句起按字数比例摊开各发一个 read */
+    readRest(said) {
+        const { beat } = said;
+        const span = this.play.spans.find((x) => x.tag === said);
+        if (!span || beat.lines.length < 2)
+            return;
+        const lens = beat.texts.map((x) => Math.max(1, x.length));
+        const total = lens.reduce((a, b) => a + b, 0);
+        let before = lens[0];
+        for (let k = 1; k < beat.lines.length; k++) {
+            this.readAt(beat, k, span.start + ((span.end - span.start) * before) / total);
+            before += lens[k];
+        }
+    }
+    /**
+     * 孩子按下(或不是说的那一轮开始):排着的丢掉,记下孩子听到第几句,撤掉还没发的 read。
+     * playing = 嘴的声音还在出 / 还在放;said = 嘴这次在要的回答;now = 打断的时刻
+     */
+    interrupt(playing, said, now) {
+        const at = playingAt(this.play, now)?.tag;
+        const dropped = this.step({ e: 'hold', drop: this.current });
+        const heard = at?.kind === 'read' ? at.beat : said?.kind === 'read' ? said.beat : dropped[0];
+        // 孩子端在放的那段里亮到了哪句就报哪句;那段还没亮(声音没到孩子端)报段首
+        if (heard)
+            this.cutAt = (this.lastRead && this.lastRead.job === heard.job && heard.lines.includes(this.lastRead.line) ? this.lastRead.line : heard.lines[0]) + 1;
+        // 脑这一轮还一句都没念到(还没写出第一句)就被打断:报 0,下一轮脑才知道孩子一句没听到
+        // (10-20 21:18 连着两轮在第一句之前被按掉,脑以为提示给过了,下一轮直接讲了答案)
+        else if (this.current && this.lastRead?.job !== this.current)
+            this.cutAt = 0;
+        if (playing && this.current)
+            this.deps.event(this.current, Date.now(), { lane: 'mouth', kind: 'cut', line: at?.kind === 'read' && this.lastRead?.job === this.current ? this.lastRead.line : null });
+        for (const t of this.readTimers.splice(0))
+            clearTimeout(t);
+    }
+    /** 交给脑时带上上一轮念到第几句被打断;带了就清 */
+    takeCut() {
+        const c = this.cutAt;
+        this.cutAt = undefined;
+        return c;
+    }
+    /** 挂电话:还没发的 read 都撤 */
+    stop() {
+        for (const t of [...this.firstTimers, ...this.readTimers])
+            clearTimeout(t);
+    }
+}

package/dist/runtime/delivery/playback.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 嘴的声音在孩子端什么时候放(纯函数,时间都是通话的毫秒):照孩子端 makeAudio().play 的排法——一块到了,上一块放完或到达 + LEAD_MS,取晚的(同 src/runtime/journal/mix.ts)。
+ * 实时老师用它:一段讲稿什么时候开始放(到点告诉孩子端亮哪几句)、孩子按下时在放哪一段(打断报到哪句)、还在不在放(要不要清孩子端的队列)。
+ */
+/** 孩子端排队的起步(play 里的 0.06 秒) */
+export declare const LEAD_MS = 60;
+export interface Span<T> {
+    tag: T;
+    start: number;
+    end: number;
+}
+export interface Playback<T> {
+    end: number;
+    spans: Span<T>[];
+}
+export declare const playbackInit: <T>() => Playback<T>;
+/** 一块声音到了:排在哪、放到哪;同一个 tag 接着的并进上一段 */
+export declare function addChunk<T>(p: Playback<T>, tag: T, arrival: number, ms: number): {
+    p: Playback<T>;
+    start: number;
+};
+/** t 这一刻在放的那段;没在放 null */
+export declare function playingAt<T>(p: Playback<T>, t: number): Span<T> | null;
+/** 孩子端清了队列:t 之后的都不放了 */
+export declare function flushAt<T>(p: Playback<T>, t: number): Playback<T>;

package/dist/runtime/delivery/playback.js

@@ -0,0 +1,29 @@
+/**
+ * 嘴的声音在孩子端什么时候放(纯函数,时间都是通话的毫秒):照孩子端 makeAudio().play 的排法——一块到了,上一块放完或到达 + LEAD_MS,取晚的(同 src/runtime/journal/mix.ts)。
+ * 实时老师用它:一段讲稿什么时候开始放(到点告诉孩子端亮哪几句)、孩子按下时在放哪一段(打断报到哪句)、还在不在放(要不要清孩子端的队列)。
+ */
+/** 孩子端排队的起步(play 里的 0.06 秒) */
+export const LEAD_MS = 60;
+export const playbackInit = () => ({ end: 0, spans: [] });
+/** 一块声音到了:排在哪、放到哪;同一个 tag 接着的并进上一段 */
+export function addChunk(p, tag, arrival, ms) {
+    const start = Math.max(arrival + LEAD_MS, p.end);
+    const end = start + ms;
+    const last = p.spans[p.spans.length - 1];
+    const spans = last && last.tag === tag && last.end === start ? [...p.spans.slice(0, -1), { ...last, end }] : [...p.spans, { tag, start, end }];
+    return { p: { end, spans }, start };
+}
+/** t 这一刻在放的那段;没在放 null */
+export function playingAt(p, t) {
+    for (let i = p.spans.length - 1; i >= 0; i--) {
+        const s = p.spans[i];
+        if (s.start <= t && t < s.end)
+            return s;
+    }
+    return null;
+}
+/** 孩子端清了队列:t 之后的都不放了 */
+export function flushAt(p, t) {
+    const spans = p.spans.filter((s) => s.start < t).map((s) => (s.end > t ? { ...s, end: t } : s));
+    return { end: Math.min(p.end, t), spans };
+}