cotutor 0.2.0 → 0.4.0

package/dist/app/http/voice-preview.js

@@ -0,0 +1,34 @@
+/**
+ * 试听一个音色(家长端「样子与声音」):
+ * 嘴(realtime)真连一次照念这一句(几分钱),存在 .cotutor/live-preview/,同一句同一音色以后直接给文件;
+ * 卡的配音合成一句,在配音缓存里(.cotutor/tts/),之后直接给文件。失败回 JSON 说原因(页面拿 message 显示)。
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { synthesize } from "../../media/tts.js";
+import { previewVoice } from "../../realtime/preview.js";
+import { isRealtimeVoice } from "../../realtime/voices.js";
+const VOICE_ID_RE = /^[A-Za-z0-9._:-]{1,120}$/;
+export async function mouthPreview(ws, voice, text) {
+    if (!isRealtimeVoice(voice))
+        return { status: 400, json: { error: 'bad_voice', message: `这个模型不认「${voice}」这个音色` } };
+    const dir = join(ws.root, '.cotutor', 'live-preview');
+    const file = join(dir, `${createHash('sha1').update(`${ws.config.live.model}\n${voice}\n${text}`).digest('hex').slice(0, 20)}.wav`);
+    if (!(await stat(file).catch(() => null))?.isFile()) {
+        const r = await previewVoice({ voice, text, model: ws.config.live.model, env: process.env, endpoint: process.env.COTUTOR_LIVE_ENDPOINT });
+        if ('error' in r)
+            return { status: 502, json: { error: 'realtime_failed', voice, message: r.error } };
+        await mkdir(dir, { recursive: true });
+        await writeFile(file, r.wav);
+    }
+    return { status: 200, file, contentType: 'audio/wav' };
+}
+export async function cardPreview(ws, voice, text) {
+    if (!VOICE_ID_RE.test(voice))
+        return { status: 400, json: { error: 'bad_voice', message: '音色 id 只能是字母数字与 . _ : -' } };
+    const r = await synthesize({ text, voice }, { cacheDir: ws.dirs.tts, env: process.env });
+    if (!r.file)
+        return { status: 502, json: { error: 'tts_failed', voice, message: r.error } };
+    return { status: 200, file: r.file, contentType: 'audio/mpeg' };
+}

package/dist/app/machine/bailian.d.ts

@@ -0,0 +1,26 @@
+import type { Who } from '../http/access.ts';
+import type { AppContext, RouteResult } from '../http/app.ts';
+export interface BailianAuth {
+    key: string;
+    workspaceId: string;
+}
+export interface BailianStatus {
+    /** 孩子端能用:按量 key 与业务空间 id 都有(或指了假端点) */
+    ready: boolean;
+    /** key 的末四位(不回显整把) */
+    keyTail: string | null;
+    workspaceId: string | null;
+}
+export interface Bailian {
+    status(): BailianStatus;
+    /** 试连;不给 auth 就用现在那份。null = 通 */
+    probe(auth?: BailianAuth): Promise<string | null>;
+    save(auth: BailianAuth): Promise<void>;
+}
+export declare function createBailian(opts?: {
+    env?: NodeJS.ProcessEnv;
+    probe?: (auth?: BailianAuth) => Promise<string | null>;
+}): Bailian;
+/** 试连没通的原因,写给家长看 */
+export declare function probeMessage(why: string): string;
+export declare function bailianRoute(method: string, p: string, ctx: AppContext, body: unknown, who: Who): Promise<RouteResult | null>;

package/dist/app/machine/bailian.js

@@ -0,0 +1,87 @@
+/**
+ * 百炼:孩子端的老师靠实时模型开口,没配百炼孩子端打不开,家长在家长端「首页」里配。
+ * 配的是按量的 key + 业务空间 id(Token Plan 的 `sk-sp-` 没有 realtime;端点要业务空间 id 的域名)。
+ * 存机器级 ~/.config/cotutor/bailian.json(0600,同 PIN、证书,几个孩子的 workspace 共用),不进 cotutor.json:
+ * workspace 是 git 仓,工作台的 PATCH /api/config 也能改它。cotutor 的 key 只认这里(开发机另有 token-plan.json),见 src/shared/qianwen.ts。
+ *
+ *   GET  /api/parent/bailian        {ready, keyTail, workspaceId, canEdit}
+ *   PUT  /api/parent/bailian        {key, workspaceId}:先试连,通了才存;回 GET 那份 + ms
+ *   POST /api/parent/bailian/test   拿现在用的那份试连一次:{ok, ms, message?}
+ *
+ * 改 key 要么在这台电脑上(本机免密),要么设了家长密码:没设 PIN 时局域网谁都进得了家长端,不让别的设备往这台电脑写 key。
+ * 测试与探针指了假的实时端点(COTUTOR_LIVE_ENDPOINT)就当配好了,试连也连那个。
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { bailianFile } from "../../shared/qianwen.js";
+import { dashscopeAuth } from "../../realtime/bailian.js";
+import { probeRealtime } from "../../realtime/preview.js";
+export function createBailian(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = env.HOME || homedir();
+    const fake = env.COTUTOR_LIVE_ENDPOINT || undefined;
+    return {
+        status() {
+            const auth = dashscopeAuth(env);
+            if (!auth)
+                return { ready: Boolean(fake), keyTail: null, workspaceId: null };
+            return { ready: true, keyTail: auth.key.slice(-4), workspaceId: auth.workspaceId };
+        },
+        probe: opts.probe ?? ((auth) => probeRealtime({ auth, env, endpoint: fake })),
+        async save(auth) {
+            const file = bailianFile(home);
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, `${JSON.stringify({ apiKey: auth.key, workspaceId: auth.workspaceId, at: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+        },
+    };
+}
+/** 试连没通的原因,写给家长看 */
+export function probeMessage(why) {
+    if (why === 'no_auth')
+        return '还没配 key 和业务空间 id';
+    if (why === 'connect' || why.startsWith('connect:') || why.startsWith('closed:'))
+        return '连不上:key 或业务空间 id 不对,或者这台电脑上不了网';
+    if (why === 'timeout')
+        return '连上了,等不到回音(超时),过一会儿再试';
+    return `百炼说:${why}`;
+}
+const KEY_RE = /^sk-[A-Za-z0-9._-]{16,}$/;
+const WS_RE = /^[A-Za-z0-9][A-Za-z0-9-]{2,62}$/;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const bad = (message) => ({ status: 400, json: { error: 'bad_request', message } });
+export async function bailianRoute(method, p, ctx, body, who) {
+    if (p !== '/api/parent/bailian' && p !== '/api/parent/bailian/test')
+        return null;
+    const canEdit = who === 'local' || (await ctx.access.pinSet());
+    const view = () => ({ ...ctx.bailian.status(), canEdit });
+    if (p === '/api/parent/bailian/test') {
+        if (method !== 'POST')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        const t0 = Date.now();
+        const why = await ctx.bailian.probe();
+        return { status: 200, json: { ok: why === null, ms: Date.now() - t0, ...(why === null ? {} : { message: probeMessage(why) }) } };
+    }
+    if (method === 'GET')
+        return { status: 200, json: view() };
+    if (method !== 'PUT')
+        return { status: 405, json: { error: 'method_not_allowed' } };
+    if (!canEdit)
+        return { status: 403, json: { error: 'need_pin', message: '先设家长密码(在电脑上跑 cotutor pin),或者在这台电脑上打开家长端来配' } };
+    if (!isObj(body))
+        return bad('要 {key, workspaceId}');
+    const key = typeof body.key === 'string' ? body.key.trim() : '';
+    const workspaceId = typeof body.workspaceId === 'string' ? body.workspaceId.trim() : '';
+    if (key.startsWith('sk-sp-'))
+        return bad('这是 Token Plan 的 key(sk-sp- 开头),老师开口要百炼按量的 key(sk- 开头)');
+    if (!KEY_RE.test(key))
+        return bad('key 不像百炼的 API key(sk- 开头)');
+    if (!WS_RE.test(workspaceId))
+        return bad('业务空间 id 不对(百炼控制台「业务空间」里那串,只有字母、数字、横线)');
+    const t0 = Date.now();
+    const why = await ctx.bailian.probe({ key, workspaceId });
+    if (why !== null)
+        return { status: 400, json: { error: 'probe_failed', message: probeMessage(why) } };
+    await ctx.bailian.save({ key, workspaceId });
+    return { status: 200, json: { ...view(), ms: Date.now() - t0 } };
+}

package/dist/app/mock/mock-live.d.ts

@@ -0,0 +1,16 @@
+/**
+ * mock 的实时老师(`cotutor mock`;老师都走实时):不经百炼、不花钱看实时老师页。
+ * 协议同 src/runtime/live/call.ts:松手(或打字、拍照、交卡)马上接住一句 → 发一条消息给 mock 的老师(照脚本出节,带 live)→ 老师写完,讲稿一句一句「念」:
+ * 字幕 + 静音的声音(按字数估长短,孩子端照常排着放),read 按孩子端的排法算好时刻发;按下 = 打断(清了,没念的不念)。
+ * 讲稿的 [[play]]:那句念完先停,孩子端放完小课堂那一段(staged)再接着念。没有转写:按住说的当成「(按住说的话)」。
+ * 边画边聊:画板开着时按头像说的(松手带 chat)只接住一句、不交给老师;孩子端觉得该说一句了({t:'chat'})安静时说一句、不安静回 skipped。
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Mock } from './mock.ts';
+/** 按住说的那句(mock 没有转写) */
+export declare const MOCK_LIVE_SAID = "(\u6309\u4F4F\u8BF4\u7684\u8BDD)";
+/** 边画边聊时假嘴说的(mock 不看图):接住孩子画着说的一句、主动说的一句(带上孩子端定的颜色) */
+export declare const MOCK_CHAT_REPLY = "\u55EF,\u4F60\u753B\u5F97\u597D\u8BA4\u771F,\u63A5\u7740\u753B\u5427\u3002";
+export declare const mockChatLook: (color: unknown) => string;
+export declare function mockLiveUpgrade(mock: Mock): (req: IncomingMessage, socket: Duplex, head: Buffer) => boolean;

package/dist/app/mock/mock-live.js

@@ -0,0 +1,140 @@
+import { playsLecture } from "../../board/parse.js";
+import { lineDurationMs, plainLine } from "../../board/presentation.js";
+import { LEAD_MS } from "../../runtime/delivery/playback.js";
+import { acceptWebSocket, isUpgrade } from "../ws/ws.js";
+/** 按住说的那句(mock 没有转写) */
+export const MOCK_LIVE_SAID = '(按住说的话)';
+/** 边画边聊时假嘴说的(mock 不看图):接住孩子画着说的一句、主动说的一句(带上孩子端定的颜色) */
+export const MOCK_CHAT_REPLY = '嗯,你画得好认真,接着画吧。';
+export const mockChatLook = (color) => (typeof color === 'string' && color ? `${color}色画了好多,像一大片。这是什么呀?` : '这一张画了好多,你画的是哪里呀?');
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export function mockLiveUpgrade(mock) {
+    return (req, socket, head) => {
+        const m = /^\/api\/live\/([a-z0-9][a-z0-9-]*)\/ws(?:\?.*)?$/.exec(req.url ?? '');
+        if (!m || !isUpgrade(req))
+            return false;
+        const tutor = m[1];
+        const timers = new Set();
+        /** 孩子端的声音排到哪(墙钟);turn 每打断一次加一,在路上的那一轮看见变了就不念了 */
+        let playEnd = 0;
+        let turn = 0;
+        let holding = false;
+        const clear = () => { for (const t of timers)
+            clearTimeout(t); timers.clear(); };
+        const later = (ms, f) => { const t = setTimeout(() => { timers.delete(t); f(); }, Math.max(0, ms)); timers.add(t); };
+        const sock = acceptWebSocket(req, socket, head, { onText: (x) => onText(x), onBinary: () => { }, onClose: () => { clear(); turn++; } });
+        const send = (o) => { sock.sendText(JSON.stringify(o)); };
+        /** 嘴说一段:字幕 + 静音的声音;回它在孩子端开始放的时刻(上一段放完或到达 + 60 毫秒,取晚的) */
+        const say = (of, text) => {
+            const ms = lineDurationMs(text);
+            const start = Math.max(Date.now() + LEAD_MS, playEnd);
+            playEnd = start + ms;
+            send({ t: 'tutor', of, done: text });
+            sock.sendBinary(Buffer.alloc(Math.round(ms * 48)));
+            return start;
+        };
+        const interrupt = () => {
+            clear();
+            turn++;
+            if (playEnd > Date.now())
+                send({ t: 'flush' });
+            playEnd = 0;
+        };
+        /** 一轮:(拍照先说一句)交给 mock 的老师、写完了一句一句念;别的嘴不先说 */
+        const begin = async (body, caught) => {
+            const my = turn;
+            if (caught)
+                say('catch', caught);
+            const r = await mock.kidSend(tutor, body);
+            if (my !== turn)
+                return;
+            if (r.status !== 202) {
+                send({ t: 'err', status: r.status, error: r.json?.error ?? 'error' });
+                return;
+            }
+            const { job, thread } = r.json;
+            send({ t: 'turn', job, thread });
+            await mock.settleJob(job);
+            if (my !== turn)
+                return;
+            const day = (await mock.route('GET', `/api/kid/conversations/${tutor}/today`)).json;
+            const sec = day.messages.find((x) => x.job === job)?.section;
+            readFrom(job, sec?.lines ?? [], sec?.cards ?? [], 0, my);
+        };
+        /** 讲稿一句一句「念」;[[play]] 那句念完先停,孩子端放完小课堂那一段(staged)再接着念 */
+        let rest = null;
+        const readFrom = (job, lines, cards, from, my) => {
+            for (let i = from; i < lines.length; i++) {
+                const text = plainLine(lines[i].text);
+                const start = say('read', text);
+                const play = playsLecture(lines[i], cards);
+                later(start - Date.now(), () => send({ t: 'read', job, line: i, text, ...(play ? { play: true } : {}) }));
+                if (play) {
+                    rest = () => { if (my === turn)
+                        readFrom(job, lines, cards, i + 1, my); };
+                    return;
+                }
+            }
+        };
+        const onText = (raw) => {
+            let x;
+            try {
+                x = JSON.parse(raw);
+            }
+            catch {
+                return;
+            }
+            switch (x.t) {
+                case 'hold':
+                    holding = true;
+                    interrupt();
+                    send({ t: 'state', speaking: false, holding: true });
+                    break;
+                case 'release':
+                    if (!holding)
+                        return;
+                    holding = false;
+                    send({ t: 'kid', text: MOCK_LIVE_SAID });
+                    // 边画边聊:只接住,不交给老师
+                    if (isObj(x.chat) && typeof x.chat.canvas === 'string') {
+                        say('catch', MOCK_CHAT_REPLY);
+                        break;
+                    }
+                    void begin({ ...(isObj(x.body) ? x.body : {}), text: MOCK_LIVE_SAID }, null);
+                    break;
+                case 'chat':
+                    if (holding || playEnd > Date.now() || typeof x.canvas !== 'string') {
+                        send({ t: 'chat', canvas: x.canvas, skipped: true });
+                        break;
+                    }
+                    say('catch', mockChatLook(isObj(x.ask) ? x.ask.color : null));
+                    send({ t: 'chat', canvas: x.canvas, said: true });
+                    break;
+                case 'hush':
+                    holding = false;
+                    interrupt();
+                    break;
+                case 'staged': {
+                    const r = rest;
+                    rest = null;
+                    r?.();
+                    break;
+                }
+                case 'send': {
+                    if (!isObj(x.body))
+                        return;
+                    const b = x.body;
+                    interrupt();
+                    void begin(b, Array.isArray(b.photos) && b.photos.length ? '我看一看图片' : null);
+                    break;
+                }
+                case 'bye':
+                    sock.close(1000, 'bye');
+                    break;
+                default: break;
+            }
+        };
+        send({ t: 'ready' });
+        return true;
+    };
+}

package/dist/{server → app/mock}/mock.d.ts

@@ -1,14 +1,16 @@
 import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
-/** mock 的课包目录:仓库里的样本(tests/fixtures/bundles/),场景卡从这里播 */
+/** mock 的课包目录:仓库里的样本(tests/fixtures/bundles/),小课堂从这里放 */
 export declare const MOCK_BUNDLES_DIR: string;
-import type { BoardSection } from '../lib/kid-board.ts';
-export type MockScenario = 'normal' | 'limit' | 'offline';
+/** mock 的视频小课堂目录:仓库里的样本(tests/fixtures/lectures/) */
+export declare const MOCK_LECTURES_DIR: string;
+import { type BoardSection, type PenName } from '../../board/presentation.ts';
+import { type ListenInfo } from '../../ui/parent/qr-page.ts';
+export type MockScenario = 'normal' | 'nokey';
 export interface MockTutor {
     name: string;
     display: string;
     subject: string;
     avatar: string;
-    motto: string;
     /** 每轮一节:老师会写的那种正文(段落 = 讲稿,围栏 = 卡),与真老师的样本同一种写法(tests/fixtures/board/) */
     script: string[];
     /** 打开页面时已经讲过的轮数(取脚本前几节) */
@@ -18,15 +20,38 @@ export interface MockTutor {
 }
 /** 脚本 → 板书节:走真解析器(mock 也是解析器的一次演练) */
 export declare function sectionFromScript(md: string): BoardSection;
+/**
+ * 写死的样子:几节预装板书的底色 / emoji 与带笔的标注(真老师是写在围栏行与讲稿的 [词] 里的),直接套到解析出来的节上,
+ * 页面走的是同一条渲染路(look 的槽、带 pen 的标注;行由页面按卡的宽度排)。键 = 老师名:脚本序号。
+ */
+export declare const MOCK_LOOKS: Record<string, {
+    marks: {
+        line: number;
+        card: number;
+        phrase: string;
+        pen: PenName;
+    }[];
+    look: Record<string, {
+        tint?: string;
+        look?: string;
+        emoji?: string;
+    }>;
+}>;
 export declare const MOCK_TUTORS: MockTutor[];
+/** mock 的首页原文(昨晚 21:30 发布的那份;接着按钮指向 past 里昨天的话题,job = 0930-<老师名长度>) */
+export declare function mockHomeMd(today: string, yesterday: string): string;
 export interface MockRouteResult {
     status: number;
     json?: unknown;
     html?: string;
     /** 静态文件(舞台包、课包) */
     file?: string;
-    /** html / file 的 content-type */
+    /** 现生成的二进制(主屏幕图标、网页图标) */
+    body?: Uint8Array;
+    /** html / file / body / json 的 content-type */
     contentType?: string;
+    /** body 的缓存策略;不给 = 一小时 */
+    cacheControl?: string;
 }
 export interface MockOptions {
     scenario?: MockScenario;
@@ -37,9 +62,15 @@ export interface MockOptions {
 }
 export interface Mock {
     route(method: string, path: string, body?: unknown): Promise<MockRouteResult>;
+    /** 孩子端发一条(同真服务只走实时那条连接:mock-live.ts 收到了交给它,测试也用它);回的形状同路由,收下 202 + {job, thread} */
+    kidSend(tutor: string, body: unknown): Promise<MockRouteResult>;
     /** 等所有还在「想」的老师答完(测试用) */
     settle(): Promise<void>;
+    /** 等这一轮的老师答完(mock 的假嘴等它写完再「念」) */
+    settleJob(job: string): Promise<void>;
     handler(req: IncomingMessage, res: ServerResponse): void;
+    /** 在哪个地址上听着(serveMock 在 listen 之后填;扫码页 /parent/qr 每次现问) */
+    listen: (() => ListenInfo) | null;
 }
 export declare function createMock(opts?: MockOptions): Mock;
 export interface ServeMockOptions extends MockOptions {
@@ -54,5 +85,7 @@ export interface ServeMockResult {
     port: number;
     https: boolean;
     urls: string[];
+    /** 扫码页:在这台电脑上打开的那条 */
+    qrPage: string;
 }
 export declare function serveMock(opts?: ServeMockOptions): Promise<ServeMockResult>;