cotutor 0.1.0 → 0.3.0

package/dist/runtime/live/call.d.ts

@@ -0,0 +1,219 @@
+import type { Runner } from '../runner.ts';
+/** 孩子端那条 WebSocket 里一次通话用得上的(app/ws/ws.ts 的 ServerSocket 满足它) */
+export interface KidSocket {
+    sendText(text: string): boolean;
+    sendBinary(data: Buffer | Uint8Array): boolean;
+    close(code?: number, reason?: string): void;
+}
+/** 实时老师从应用拿的(app/http/app.ts 的 AppContext 满足它):运行时与时钟,不认路由与页面 */
+export interface LiveApp {
+    readonly runner: Runner;
+    now(): Date;
+}
+export interface LiveDeps {
+    ctx: LiveApp;
+    tutor: string;
+    /** 哪一台设备(升级请求里的设备 cookie):孩子发的每一条记上 */
+    deviceId?: string | null;
+    /** 测试:realtime 的端点与环境 */
+    endpoint?: string;
+    env?: NodeJS.ProcessEnv;
+    /** 测试:心跳间隔、孩子多久没动静就不跳、输入多少 token 换连接 */
+    heartbeatMs?: number;
+    keepAliveMs?: number;
+    swapTokens?: number;
+    /** 一直听:进来就是(连接带 ?listen=open);测试:放过的句子攒着多久没回答就换连接 */
+    listen?: 'hold' | 'open';
+    idleSwapMs?: number;
+    /** 测试:热身那句念完等孩子多久、打电话先响多久的铃 */
+    echoWaitMs?: number;
+    ringMs?: number;
+    /** 测试:要嘴说了多久一个字没出算卡住 */
+    stallMs?: number;
+    onFinished?(why: string): void;
+}
+export declare class LiveCall {
+    private session;
+    private readonly rec;
+    /** 交付:讲稿排队、嘴的声音在孩子端排到哪、第几句开始放、打断时听到第几句(./delivery.ts) */
+    private readonly d;
+    private holding;
+    /** 这一次按着推进去多少字节的声音 */
+    private heldBytes;
+    /** 要了还没出完的那次回答;afterDone = 它出完(或被掐)之后再做的 */
+    private said;
+    private afterDone;
+    private cancelOnCreate;
+    /** 这次回答出过声音或字没有(看门狗 STALL_MS 看它) */
+    private saidOut;
+    /** 这一轮:嘴接住时说的、接住出完没有 */
+    private caught;
+    private caughtDone;
+    /** 嘴这一道的事件(补进那一轮的 events.jsonl)与字幕重放的声音(./journal.ts) */
+    private readonly events;
+    private readonly takes;
+    /** 交给脑:验与拼、runner.send、脑忙时排着(./turns.ts) */
+    private readonly turns;
+    private turnSeq;
+    /** 按住说的这一轮还在等转写 */
+    private pendingVoice;
+    private readonly timers;
+    /** 孩子最近一次按下、松手、发来,或嘴说完一次的墙钟(心跳看它) */
+    private lastActive;
+    /** 嘴最近一次回答的输入 token(连接的历史越长越多);过了 SWAP_TOKENS 安静时换连接 */
+    private lastInput;
+    private swapping;
+    /** 第一次连上了:之后嘴没了是断了要现连,不是连不上 */
+    private opened;
+    /** 正在现连;连上之前孩子端来的按下、松手、发来、按着的声音照到达的顺序攒着 */
+    private reviving;
+    private backlog;
+    private backlogBytes;
+    private backlogHolding;
+    /** 一直听:孩子端要的(open)与嘴这条会话开着 VAD 没有(mouthOpen);不一样就在安静时换连接 */
+    private open;
+    private mouthOpen;
+    /** 一直听:VAD 判着孩子在说、开口的时刻(通话毫秒);说完了在等转写的(说完的时刻) */
+    private vadOn;
+    private vadFrom;
+    /** 孩子开口那一刻嘴的声音还在放(或刚放完 300 毫秒内):只有这时才可能是回声 */
+    private vadOverMouth;
+    private vadAwait;
+    /** 一直听:嘴的声音让孩子端压低着 */
+    private ducked;
+    /** 一直听:孩子端开口时报的这一轮上下文(话题、设备、via、舞台上的卡),收下时当松手的 body */
+    private ctxBody;
+    /** 嘴最近说过的话(比回声),at = 那段在孩子端放完的墙钟 */
+    private saidLog;
+    /** 一直听:收下了还没交给脑的几句(孩子停一下接着说的并进来) */
+    private draft;
+    /** 一直听:孩子的声音最后到的墙钟、上次回答以后有没有 commit 过、上次回答(或连上)的墙钟、孩子端关着麦 */
+    private lastAudioAt;
+    private committedSince;
+    private lastResponseAt;
+    private gated;
+    /** 热身:交给嘴的那段最后一句要孩子跟。endAt = 那句在孩子端放完的通话毫秒(嘴出完才知道);heardAt = 孩子开口的通话毫秒;overdue = 等够了时孩子正在说 */
+    private echoing;
+    /** 热身:按住说时松手了、在等这一下的转写(跟读还是对老师说的);那一下松手的 body */
+    private echoHeld;
+    /** 热身每拍记的(摸底)、连着没开口的拍数 */
+    private warm;
+    private quietBeats;
+    /** 打电话从哪一刻起(墙钟,[[call]] 那句在孩子端放完、开始响铃);null = 还没打 */
+    private phoneAt;
+    /** 边画边聊:每张画(画板卡 <job>/<n>,纸 paper)上孩子说的、嘴说的,一句一行;交画那轮给脑后清掉 */
+    private readonly drawTalk;
+    /** 边画边聊:按着头像说的那句在等转写(记到哪张画上) */
+    private chatHeard;
+    private chatHeardUntil;
+    /** 嘴主动说那几次垫的静音:几段转写还没回来、等到什么时候(空的转写吞掉,不说没听清) */
+    private chatQuiet;
+    private chatQuietUntil;
+    private offEvents;
+    private ended;
+    private readonly sock;
+    private readonly deps;
+    constructor(sock: KidSocket, deps: LiveDeps);
+    private ms;
+    /** 通话里的毫秒 → 墙钟 */
+    private wall;
+    /** 记嘴这一道的一条:那一轮起来了就补进它的事件,还不知道是哪一轮(job = null)就先攒着 */
+    private mouth;
+    private send;
+    private playing;
+    private state;
+    /** 排队说这一拍该交给嘴了:要嘴照念;热身那句念完要等孩子跟 */
+    private read;
+    /** 让嘴说一次;接住要先告诉排队,嘴出完之前别交讲稿 */
+    private ask;
+    /** 要嘴说的这次一个字、一块声音都没出(STALL_MS):当这条连接坏了,照念的那段放回排头、换一条接着念;接住、边画边聊那句不补 */
+    private stalled;
+    /** 连嘴;连不上告诉孩子端(它灰着「正在叫老师」、过一会儿重连)、挂掉 */
+    start(): Promise<void>;
+    /** 开一条嘴的会话(第一次、断了以后现连、换连接都走这里);不是 this.session 的会话,回调都不认 */
+    private openMouth;
+    /** 开一条嘴的会话并换上(第一次、断了以后现连) */
+    private connectMouth;
+    /** 换上一条嘴的会话:一直听的状态都从头来 */
+    private mounted;
+    /** 安静:孩子没按着、嘴没在说也没要说的、讲稿没排着、脑没在写、没在现连 / 换连接 */
+    private quiet;
+    /**
+     * 换连接:嘴的输入每次回答都带着整条连接的历史,一轮约多 230 token(2026-10-20 真连 15 轮:843 涨到 5468,
+     * 首包不变,只是钱);嘴每次都给词、不靠前情,安静时开一条新的换上就行,不用摘要。开的时候孩子动了就作废这次。
+     */
+    private maybeSwap;
+    /** 嘴的会话断了(百炼 300 秒没输入就关、网断了):电话不挂;讲稿还排着就马上连、接着念,不然等孩子下次按下或发来再连 */
+    private lost;
+    /** 现连嘴(最多两次);连上了把攒着的照到达的顺序补上、排着的讲稿接着念;连不上告诉孩子端、挂掉 */
+    private revive;
+    /** 心跳(RealtimeSession.heartbeat):嘴连着、孩子没按着、嘴没在说、最近有动静;孩子走开久了就不跳,让百炼关,回来按下再连 */
+    private keepAlive;
+    /** 字幕重放:这次照念在它那一轮里的那一段(第一块声音到时开;make = false 只找不开);接住、那一轮不在内存里的不留 */
+    private mouthSeg;
+    /** 字幕重放:一段出完了(done)/ 被掐了、断了:这一轮整份重落一次 */
+    private mouthEnd;
+    /** 孩子按下(或不是说的那一轮开始):嘴在出就掐、还在放就清孩子端;排着的丢掉;记下孩子听到第几句 */
+    private interrupt;
+    /** 孩子的一条文本消息 */
+    onText(raw: string): void;
+    /** 一条孩子端的消息;at = 到的墙钟(现连时补的那几条照原来到的时刻记事件) */
+    private handle;
+    /**
+     * 一轮开始:多半嘴不出声,等脑的第一句(孩子端左栏头像在想);拍照、热身这几种才先说一句(src/realtime/cues.ts;上一次回答被掐了还没回 done 就等它回了再说)。
+     * 说的等转写回来再交给脑,不是说的直接交
+     */
+    private turn;
+    /** 孩子那句的转写回来了:空的改说没听清、不交给脑;不空交给脑 */
+    private heard;
+    /** 边画边聊:这张画上记一句(孩子说的、嘴说的),交画那轮给脑 */
+    private noteDraw;
+    /**
+     * 边画边聊:画板开着时按着头像说完松手。声音太少照「没听清」;不然这一刻的画跟着这段声音 commit,嘴接住(看图、顺着他的话),不起脑。
+     * 按下时攒的那几条嘴的事件不归哪一轮(没有这一轮),丢掉
+     */
+    private chatRelease;
+    /**
+     * 边画边聊:孩子端觉得该说一句了(src/board/canvas-chat.ts 的规矩)。只在安静时说(孩子没按着、嘴没在说也没要说、脑没在写、讲稿没排着),
+     * 一直听、热身时不说;0.5 秒静音 + 这一刻的画 commit(百炼要先有声音再有图),嘴照应用给的题说一两句。说不了回 {t:'chat', skipped}
+     */
+    private chatLook;
+    /** 一直听:VAD 判出孩子开口 / 说完。开口先暂停照念(不丢)、嘴在放就让孩子端压低;说完了等转写 */
+    private speech;
+    /** 一直听:放过一句(或孩子端关麦作废了一句),照念接着走、压低的恢复 */
+    private resume;
+    /** 一直听:一句的转写回来了(null = VAD 不收、转写失败)。收下 = 按下 + 松手;放过的什么都不做,照念接着走 */
+    private verdict;
+    /** 孩子那句转写失败:按住说的照转写是空的办;一直听时不到 1 秒的放过,长的嘴说没听清 */
+    private kidFailed;
+    /** 等嘴接住(最多 CATCH_WAIT_MS),交给脑;脑在忙就排着,它写完合并发 */
+    private toBrain;
+    /**
+     * 这一轮实时的那些(收下了才算,交给脑时带):口语课热身的摸底一直带着,打了电话带打了几分钟,应用起的这一轮说明为什么;
+     * 交画那一轮(交画板卡、纸上的画):这张画上边画边说的带给脑,之后清掉;上一轮念到第几句被打断,带了就清
+     */
+    private liveOf;
+    /** 接住说中文还是英文:口语课打了电话以后说英文 */
+    private lang;
+    /** 热身那句在孩子端放完的时刻(通话毫秒)知道了:从那时起等 ECHO_WAIT_MS */
+    private armEcho;
+    /** 热身等够了:孩子正在说(或说完了在等转写、按着)就等它判完;没开口记一笔,接着下一拍;连着 QUIET_BEATS 拍没开口停下交脑 */
+    private echoDue;
+    /** 热身记一拍(摸底;录像里一条 {t:'echo'},只记不发) */
+    private noteEcho;
+    /** 热身这拍过了:开闸,下一拍接着念;压低的恢复 */
+    private echoed;
+    /** 热身里按住说的那一下转写回来了:空的接着等;像跟读开闸;对老师说的同松手(打断、接住、交给脑) */
+    private echoHeard;
+    /** [[call]] 那句出齐了:它在孩子端放完时开始响铃、算打电话的起点;马上交脑写英文开场(铃声垫着,嘴不接) */
+    private startPhone;
+    /** 应用起的一轮(不是孩子说的):嘴不出声,接在这次通话的话题后面交给脑 */
+    private appTurn;
+    /** 孩子端的一块声音:按着才推,一直听时一直推;嘴在现连时按着说的先攒着(最多一分钟),一直听的只留最近 10 秒 */
+    onAudio(pcm: Buffer): void;
+    private pushAudio;
+    /** 收:关嘴、落录像、告诉孩子端 */
+    end(why: string): Promise<void>;
+    /** 孩子端断了 */
+    onSocketClose(): void;
+}