cotutor 0.1.0 → 0.3.0

package/dist/app/talk/route.js

@@ -0,0 +1,142 @@
+/**
+ * /talk 与 /api/talk/*:口语课的页面与接口。孩子在这里拍一页、改好口语单,交给英语老师的实时页上课
+ * (src/runtime/talk-run.ts,activity「口语课」);这一页自己不打电话。
+ * cotutor 只在 app.ts 的 route() 里接一行;这里引用 cotutor 的东西,cotutor 别处不引用这里。拆掉 = 删 src/{app,ui,scenes}/talk/ 和那一行(实时页里口语课热身那几处另算)。
+ *
+ *   GET    /talk                       孩子端的页面:拍照、看口语单(按 hash 切;家长端没有这一页)
+ *   GET    /api/talk                   开关、全部口语单(新的在前)
+ *   POST   /api/talk                   {photo?: dataURL} 开一次;有照片就交给 omni 读口语单(孩子拍的,读完才回)
+ *                                      {from: 'latest'} 拍照屏的「接着上」:最近那份改好了的口语单(404 = 还没有)
+ *   GET    /api/talk/<id>              一次的全部({meta})
+ *   PUT    /api/talk/<id>/list         {words, sentences, ready?} 改过的口语单;ready = 交给老师
+ *   DELETE /api/talk/<id>
+ *   GET    /api/talk/<id>/photo        那页照片
+ */
+import { join } from 'node:path';
+import { readList, wordCardOf } from "./list.js";
+import { talkPage } from "../../ui/talk/page.js";
+import { backTutorOf } from "../../ui/kid/tutor-face.js";
+import { ID_RE, createTalk, deleteTalk, dirOf, listTalks, readMeta, writeMeta } from "../../scenes/talk/store.js";
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const bad = (message) => ({ status: 400, json: { error: 'bad_request', message } });
+const PHOTO_MIME = { jpeg: 'image/jpeg', jpg: 'image/jpeg', png: 'image/png', webp: 'image/webp' };
+const PHOTO_B64_MAX = 5_600_000;
+/** data:image/…;base64,… → 字节;不是图、太大 → undefined */
+export function photoData(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const m = /^data:image\/([a-z]+)(?:;[^,]*)?;base64,([A-Za-z0-9+/=]+)$/.exec(v);
+    const mime = m ? PHOTO_MIME[m[1]] : undefined;
+    if (!m || !mime || m[2].length > PHOTO_B64_MAX)
+        return undefined;
+    return { data: Buffer.from(m[2], 'base64'), mime };
+}
+/** 改过的口语单:两组各最多 12 / 8 条,去空去重;词带回来的 emoji 与分段再过一遍单词卡的 parse(改了词,旧分段拼不回就丢) */
+export function parseItems(v, max, card = false) {
+    if (!Array.isArray(v) || v.length > 50)
+        return null;
+    const out = [];
+    for (const x of v) {
+        if (!isObj(x) || typeof x.en !== 'string')
+            return null;
+        const en = x.en.replace(/\s+/g, ' ').trim();
+        const zh = typeof x.zh === 'string' ? x.zh.replace(/\s+/g, ' ').trim() : '';
+        if (!en || en.length > 120 || zh.length > 120)
+            continue;
+        if (out.some((o) => o.en.toLowerCase() === en.toLowerCase()))
+            continue;
+        const ch = x.chunks;
+        out.push(card ? { en, zh, ...wordCardOf(en, x.emoji, Array.isArray(ch) ? ch.join('-') : undefined) } : { en, zh });
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+export function makeTalkRoute(deps = { readList }) {
+    return async function talkRoute(method, url, ctx, body) {
+        const p = url.pathname;
+        if (p === '/talk' || p === '/talk/')
+            return method === 'GET' ? { status: 200, html: talkPage(backTutorOf(ctx.ws.config.tutors, url.searchParams.get('tutor'))) } : { status: 405, json: { error: 'method_not_allowed' } };
+        if (p !== '/api/talk' && !p.startsWith('/api/talk/'))
+            return null;
+        const ws = ctx.ws;
+        const cfg = ws.config.talk;
+        const root = ws.root;
+        const env = deps.env ?? process.env;
+        if (p === '/api/talk') {
+            if (method === 'GET')
+                return { status: 200, json: { enabled: cfg.enabled, talks: await listTalks(root) } };
+            if (method !== 'POST')
+                return { status: 405, json: { error: 'method_not_allowed' } };
+            if (!cfg.enabled)
+                return { status: 404, json: { error: 'talk_disabled', message: 'cotutor.json 的 talk.enabled 还是 false' } };
+            const b = isObj(body) ? body : {};
+            if (b.from !== undefined) {
+                if (b.from !== 'latest')
+                    return bad("from 只认 'latest'");
+                const last = (await listTalks(root)).find((t) => t.status === 'ready' && t.list.words.length + t.list.sentences.length > 0);
+                if (!last)
+                    return { status: 404, json: { error: 'no_list', message: '还没有给孩子的口语单' } };
+                return { status: 200, json: last };
+            }
+            const photo = b.photo === undefined ? null : photoData(b.photo);
+            if (photo === undefined)
+                return bad('photo 要是 data:image/…;base64,…,不超过 4MB');
+            const meta = await createTalk(root, ctx.now(), photo?.data ?? null);
+            if (photo) {
+                const r = await deps.readList(photo, { env, model: cfg.listModel });
+                if (r.ok) {
+                    meta.list = r.list;
+                    meta.listBy = 'omni';
+                    meta.listMs = r.ms;
+                }
+                else {
+                    meta.listError = r.error;
+                    meta.listMs = r.ms;
+                }
+                await writeMeta(root, meta);
+            }
+            return { status: 201, json: meta };
+        }
+        const m = /^\/api\/talk\/([^/]+)(?:\/(.*))?$/.exec(p);
+        if (!m)
+            return null;
+        const id = m[1];
+        const rest = m[2] ?? '';
+        if (!ID_RE.test(id))
+            return { status: 404, json: { error: 'not_found' } };
+        const meta = await readMeta(root, id);
+        if (!meta)
+            return { status: 404, json: { error: 'not_found' } };
+        const dir = dirOf(root, id);
+        if (rest === '' && method === 'GET')
+            return { status: 200, json: { meta } };
+        if (rest === '' && method === 'DELETE') {
+            await deleteTalk(root, id);
+            return { status: 200, json: { ok: true } };
+        }
+        if (rest === 'list' && method === 'PUT') {
+            const b = isObj(body) ? body : {};
+            const words = parseItems(b.words ?? [], 12, true);
+            const sentences = parseItems(b.sentences ?? [], 8);
+            if (!words || !sentences)
+                return bad('words / sentences 要是 [{en, zh}]');
+            const changed = JSON.stringify({ words, sentences }) !== JSON.stringify(meta.list);
+            meta.list = { words, sentences };
+            if (changed)
+                meta.listBy = 'parent';
+            meta.status = b.ready === true && words.length + sentences.length ? 'ready' : 'draft';
+            await writeMeta(root, meta);
+            return { status: 200, json: meta };
+        }
+        if (rest === 'photo' && method === 'GET')
+            return meta.photo ? { status: 200, file: join(dir, meta.photo), contentType: 'image/jpeg', cacheControl: 'private, max-age=3600' } : { status: 404, json: { error: 'no_photo' } };
+        return { status: 404, json: { error: 'not_found' } };
+    };
+}
+/** 探针用的假读口语单(COTUTOR_TALK_FAKE_LIST=1):不看照片,0.8 秒后回一个词一句 */
+const fakeReadList = async () => {
+    await new Promise((r) => setTimeout(r, 800));
+    return { ok: true, list: { words: [{ en: 'red', zh: '红色', emoji: '🔴' }], sentences: [{ en: 'It is a red car.', zh: '这是一辆红色的车。' }] }, model: 'fake', ms: 800 };
+};
+export const talkRoute = makeTalkRoute({ readList: process.env.COTUTOR_TALK_FAKE_LIST ? fakeReadList : readList });

package/dist/app/workspace.d.ts

@@ -0,0 +1,58 @@
+import { ConfigError, UsageError } from '../shared/errors.ts';
+import { redactDeep, redactHome } from '../shared/home.ts';
+import { type RootSource, type Workspace } from '../schema/workspace.ts';
+import { type CotutorConfig } from '../schema/index.ts';
+export { ConfigError, UsageError, redactDeep, redactHome };
+export type { RootSource, Workspace };
+export declare const CONFIG_FILE = "cotutor.json";
+export declare const USER_CONFIG: string;
+/** 机器级自签证书目录(cotutor cert 写 cert.pem + key.pem):证书签的是本机名与局域网 IP,与孩子无关,所以不在 workspace 里 */
+export declare const USER_CERT_DIR: string;
+export declare const HOME_ROOT: string;
+export interface ResolvedRoot {
+    root: string;
+    source: RootSource;
+}
+export declare function expandPath(p: string, base: string): string;
+/** 读 JSON:不存在 → null;坏 → ConfigError */
+export declare function readJson(file: string): unknown | null;
+/** 从 dir 向上找 cotutor.json,找到返回目录 */
+export declare function findUp(dir: string): string | null;
+/** ~/cotutor/ 下带 cotutor.json 的子目录 */
+export declare function homeWorkspaces(homeRoot?: string): string[];
+export interface ResolveOptions {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    homeRoot?: string;
+}
+export declare function resolveRoot(override?: string, opts?: ResolveOptions): ResolvedRoot;
+/** 校验 cotutor.json 的形状;失败 → ConfigError,信息是逐条修复指南 */
+export declare function parseConfig(raw: unknown, file: string): CotutorConfig;
+export declare function resolvePaths(root: string, paths: Record<string, string>): Workspace['paths'];
+export declare function assembleWorkspace(root: string, source: RootSource, config: CotutorConfig): Workspace;
+/** 定根 + 读配置 + 校验 + 展开角色。cotutor.json 缺失也是错(它是必需的)。 */
+export declare function loadWorkspace(override?: string, opts?: ResolveOptions): Workspace;
+/** --json / 启动日志里回报workspace(脱敏) */
+export declare function workspaceReport(ws: Workspace): Record<string, unknown>;
+/** PATCH 允许改的顶层键(老师团页与设置页);kid / version / 运行时模板走编辑器 */
+export declare const CONFIG_PATCH_KEYS: readonly ["title", "policyDefaults", "tutors", "agents", "paths", "server", "vault", "live"];
+/**
+ * 深合并:对象递归、其余覆盖、null 删键(老师条目可整体删:tutors.x = null)。
+ * 底下没有这个对象时也要**先剥掉 null 再放**——页面上留空的字段发的就是 null,
+ * 直接把补丁原样放进去会写出 `policy: {replyMaxChars: null, …}`,整份过不了契约、一保存就报错
+ * (2026-09-11:老师条目本来没有 policy 键时必然撞上,出厂六位都是这样)。
+ */
+export declare function deepMerge(base: unknown, patch: unknown): unknown;
+/**
+ * 补丁合到原始 JSON 上(保留 _note 等机器不认识的键),整份过契约再写;写坏了不落盘。
+ * 返回新配置;agents 只允许改 default(运行时模板走编辑器,页面上改错一个引号就把老师全弄哑)。
+ */
+/** also:除了工作台能改的,这次还放行哪几个顶层键(家长端设置自己拼好补丁,只放 talk 的几项) */
+export declare function patchConfig(ws: Workspace, patch: Record<string, unknown>, opts?: {
+    also?: readonly string[];
+}): Promise<CotutorConfig>;
+/** 文件改了(页面写的、或家长在编辑器改的)就重读;坏了抛 ConfigError,调用方决定是留旧的还是响 */
+export declare function reloadIfChanged(ws: Workspace, lastMtime: number): Promise<{
+    ws: Workspace;
+    mtime: number;
+}>;

package/dist/{cli → app}/workspace.js

@@ -1,5 +1,5 @@
 /**
- * 工作区解析:一孩一 workspace(`~/cotutor/<slug>/`,2026-09-08 拍板)。
+ * workspace解析:一孩一 workspace(`~/cotutor/<slug>/`)。
  * 解析链(定根):`--workspace <dir>` → 环境变量 COTUTOR_WORKSPACE → cwd 或其祖先有 cotutor.json
  * (老师的 cwd 是 <ws>/agents/<name>/,从那里跑 doctor 也要找得到根)→ 用户配置
  * ~/.config/cotutor/config.json 的 workspace → ~/cotutor/ 下**唯一**的一个孩子目录 → 都没有就报错附修复指南。
@@ -7,22 +7,19 @@
  * 配置"在但解析不了"响亮报错,不静默走缺省(沿 drawtell 的教训)。
  */
 import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { writeFile, rename, stat } from 'node:fs/promises';
+import { ConfigError, UsageError } from "../shared/errors.js";
+import { redactDeep, redactHome } from "../shared/home.js";
+import { SKILLS_DIR } from "../schema/workspace.js";
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { CotutorConfigSchema, PATH_ROLES, ROLE_DEFAULTS, explainIssues, } from "../schema/index.js";
-/** 用法错误:main 捕获后 exit 2,错误信息即修复指南。 */
-export class UsageError extends Error {
-}
-/** 配置文件损坏或形状不对:文件在,但用不了。 */
-export class ConfigError extends UsageError {
-    file;
-    constructor(file, cause) {
-        super(`配置文件用不了:${redactHome(file)}\n${cause}\n修好它;文件在 git 里就 git diff 看改动、git checkout 回退。cotutor doctor 可逐项体检。`);
-        this.file = file;
-    }
-}
+import { CotutorConfigSchema, PATH_ROLES, ROLE_DEFAULTS, WORKSPACE_ROLES, explainIssues, } from "../schema/index.js";
+// 挪走了的几样照旧从这里转出(旧的引法不用改)
+export { ConfigError, UsageError, redactDeep, redactHome };
 export const CONFIG_FILE = 'cotutor.json';
 export const USER_CONFIG = join(homedir(), '.config', 'cotutor', 'config.json');
+/** 机器级自签证书目录(cotutor cert 写 cert.pem + key.pem):证书签的是本机名与局域网 IP,与孩子无关,所以不在 workspace 里 */
+export const USER_CERT_DIR = join(homedir(), '.config', 'cotutor', 'certs');
 export const HOME_ROOT = join(homedir(), 'cotutor');
 export function expandPath(p, base) {
     if (p === '~')
@@ -31,20 +28,6 @@ export function expandPath(p, base) {
         return join(homedir(), p.slice(2));
     return isAbsolute(p) ? p : resolve(base, p);
 }
-export function redactHome(value) {
-    const home = homedir();
-    return home && value.startsWith(home) ? '$HOME' + value.slice(home.length) : value;
-}
-export function redactDeep(value) {
-    if (typeof value === 'string')
-        return redactHome(value);
-    if (Array.isArray(value))
-        return value.map(redactDeep);
-    if (value && typeof value === 'object') {
-        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactDeep(v)]));
-    }
-    return value;
-}
 const isDir = (p) => {
     try {
         return statSync(p).isDirectory();
@@ -146,7 +129,7 @@ export function resolvePaths(root, paths) {
     for (const role of PATH_ROLES) {
         if (role === 'vault')
             continue;
-        out[role] = expandPath(paths[role] ?? ROLE_DEFAULTS[role], vault);
+        out[role] = expandPath(paths[role] ?? ROLE_DEFAULTS[role], WORKSPACE_ROLES.includes(role) ? root : vault);
     }
     for (const [role, value] of Object.entries(paths))
         if (!(role in out))
@@ -163,15 +146,15 @@ export function assembleWorkspace(root, source, config) {
             agents: join(root, 'agents'),
             ledger: join(root, 'ledger'),
             conversations: join(root, 'conversations'),
-            claudeAgents: join(root, '.claude', 'agents'),
-            qwenAgents: join(root, '.qwen', 'agents'),
+            skills: join(root, SKILLS_DIR),
+            bundles: join(root, 'bundles'),
+            home: join(root, 'home'),
+            lectures: join(root, 'lectures'),
+            tts: join(root, '.cotutor', 'tts'),
         },
         files: {
             config: join(root, CONFIG_FILE),
-            observations: join(root, 'ledger', 'observations.jsonl'),
             artifacts: join(root, 'ledger', 'artifacts.jsonl'),
-            rulesClaude: join(root, 'CLAUDE.md'),
-            rulesQwen: join(root, 'QWEN.md'),
         },
     };
 }
@@ -184,7 +167,7 @@ export function loadWorkspace(override, opts = {}) {
         throw new ConfigError(file, `不存在。cotutor init <slug> --dir ${redactHome(root)} 可生成模板(已有文件不动)。`);
     return assembleWorkspace(root, source, parseConfig(raw, file));
 }
-/** --json / 启动日志里回报工作区(脱敏) */
+/** --json / 启动日志里回报workspace(脱敏) */
 export function workspaceReport(ws) {
     return redactDeep({
         workspace: ws.root,
@@ -193,7 +176,70 @@ export function workspaceReport(ws) {
         title: ws.config.title,
         port: ws.config.server.port,
         vault: ws.paths.vault,
-        teachers: Object.keys(ws.config.teachers),
-        agent: ws.config.agents.default,
+        tutors: Object.keys(ws.config.tutors),
+        runtime: ws.config.runtimes.default,
     });
 }
+// ---- cotutor.json 的补丁写回与热重载(从 runtime/journal/store.ts 搬来,2026-10-29) ----
+/** PATCH 允许改的顶层键(老师团页与设置页);kid / version / 运行时模板走编辑器 */
+export const CONFIG_PATCH_KEYS = ['title', 'policyDefaults', 'tutors', 'agents', 'paths', 'server', 'vault', 'live'];
+const isPlainObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+/**
+ * 深合并:对象递归、其余覆盖、null 删键(老师条目可整体删:tutors.x = null)。
+ * 底下没有这个对象时也要**先剥掉 null 再放**——页面上留空的字段发的就是 null,
+ * 直接把补丁原样放进去会写出 `policy: {replyMaxChars: null, …}`,整份过不了契约、一保存就报错
+ * (2026-09-11:老师条目本来没有 policy 键时必然撞上,出厂六位都是这样)。
+ */
+export function deepMerge(base, patch) {
+    if (!isPlainObj(patch))
+        return patch;
+    const out = isPlainObj(base) ? { ...base } : {};
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null) {
+            delete out[k];
+            continue;
+        }
+        const had = k in out;
+        const merged = deepMerge(out[k], v);
+        // 补丁里一组字段全留空(全是 null)时别凭空造个空对象出来:policy: {contextPack: {}} 这种噪音不该进政策文件
+        if (!had && isPlainObj(merged) && !Object.keys(merged).length)
+            continue;
+        out[k] = merged;
+    }
+    return out;
+}
+/**
+ * 补丁合到原始 JSON 上(保留 _note 等机器不认识的键),整份过契约再写;写坏了不落盘。
+ * 返回新配置;agents 只允许改 default(运行时模板走编辑器,页面上改错一个引号就把老师全弄哑)。
+ */
+/** also:除了工作台能改的,这次还放行哪几个顶层键(家长端设置自己拼好补丁,只放 talk 的几项) */
+export async function patchConfig(ws, patch, opts = {}) {
+    const allowed = [...CONFIG_PATCH_KEYS, ...(opts.also ?? [])];
+    const unknown = Object.keys(patch).filter((k) => !allowed.includes(k));
+    if (unknown.length)
+        throw new ConfigError(ws.files.config, `页面只能改 ${CONFIG_PATCH_KEYS.join(' / ')},不认识:${unknown.join(', ')};其余字段请直接编辑文件`);
+    if (isPlainObj(patch.agents) && Object.keys(patch.agents).some((k) => k !== 'default')) {
+        throw new ConfigError(ws.files.config, 'agents 只能在页面上改 default;运行时模板请直接编辑文件');
+    }
+    const raw = readJson(ws.files.config);
+    if (raw === null)
+        throw new ConfigError(ws.files.config, '不存在');
+    const merged = deepMerge(raw, patch);
+    const r = CotutorConfigSchema.safeParse(merged);
+    if (!r.success)
+        throw new ConfigError(ws.files.config, `补丁应用后不合契约,未写入:\n${explainIssues(r.error.issues).map((l) => `  - ${l}`).join('\n')}`);
+    const tmp = `${ws.files.config}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(merged, null, 2)}\n`);
+    await rename(tmp, ws.files.config);
+    return r.data;
+}
+/** 文件改了(页面写的、或家长在编辑器改的)就重读;坏了抛 ConfigError,调用方决定是留旧的还是响 */
+export async function reloadIfChanged(ws, lastMtime) {
+    const st = await stat(ws.files.config);
+    if (st.mtimeMs === lastMtime)
+        return { ws, mtime: lastMtime };
+    const raw = readJson(ws.files.config);
+    if (raw === null)
+        throw new ConfigError(ws.files.config, '不存在了');
+    return { ws: assembleWorkspace(ws.root, ws.source, parseConfig(raw, ws.files.config)), mtime: st.mtimeMs };
+}

package/dist/app/ws/route.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 实时老师的那条 WebSocket:WS /api/live/<老师>/ws,一次连接一个 LiveCall(call.ts)。
+ * serve.ts 的 upgrade 里接一行;有脸的老师都走这里,不是有脸的、关着的、藏着的回 404。
+ * ?listen=open = 一直听(孩子不用按);缺省按住说。
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { type LiveApp } from '../../runtime/live/call.ts';
+export interface LiveRouteDeps {
+    /** realtime 端点(测试、探针换假的);不给用真的 */
+    endpoint?: string;
+    env?: NodeJS.ProcessEnv;
+    /** 测试:心跳间隔、多久没动静停跳、输入多少 token 换连接 */
+    heartbeatMs?: number;
+    keepAliveMs?: number;
+    swapTokens?: number;
+    idleSwapMs?: number;
+    echoWaitMs?: number;
+    ringMs?: number;
+    stallMs?: number;
+    onFinished?(tutor: string, why: string): void;
+}
+export declare function makeLiveUpgrade(deps?: LiveRouteDeps): (req: IncomingMessage, socket: Duplex, head: Buffer, ctx: LiveApp) => Promise<boolean>;
+/** 探针:COTUTOR_LIVE_ENDPOINT 指到假百炼 */
+export declare const liveUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer, ctx: LiveApp) => Promise<boolean>;

package/dist/app/ws/route.js

@@ -0,0 +1,29 @@
+import { LiveCall } from "../../runtime/live/call.js";
+import { acceptWebSocket, isUpgrade } from "./ws.js";
+import { cookieOf } from "../http/access.js";
+import { DEVICE_COOKIE } from "../../schema/kid-device.js";
+export function makeLiveUpgrade(deps = {}) {
+    return async function liveUpgrade(req, socket, head, ctx) {
+        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 cfg = ctx.runner.ws.config;
+        const refuse = (status, why) => { socket.end(`HTTP/1.1 ${status} ${why}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`); return true; };
+        const t = cfg.tutors[tutor];
+        if (!tutor.endsWith('-tutor') || !t || !t.enabled || t.hidden)
+            return refuse(404, 'not live');
+        let call = null;
+        const sock = acceptWebSocket(req, socket, head, {
+            onText: (x) => call?.onText(x),
+            onBinary: (b) => call?.onAudio(b),
+            onClose: () => call?.onSocketClose(),
+        });
+        const listen = new URL(req.url ?? '', 'http://x').searchParams.get('listen') === 'open' ? 'open' : 'hold';
+        call = new LiveCall(sock, { ctx, tutor, deviceId: cookieOf(req.headers.cookie, DEVICE_COOKIE), listen, endpoint: deps.endpoint, env: deps.env, heartbeatMs: deps.heartbeatMs, keepAliveMs: deps.keepAliveMs, swapTokens: deps.swapTokens, idleSwapMs: deps.idleSwapMs, echoWaitMs: deps.echoWaitMs, ringMs: deps.ringMs, stallMs: deps.stallMs, onFinished: (why) => deps.onFinished?.(tutor, why) });
+        void call.start();
+        return true;
+    };
+}
+/** 探针:COTUTOR_LIVE_ENDPOINT 指到假百炼 */
+export const liveUpgrade = makeLiveUpgrade(process.env.COTUTOR_LIVE_ENDPOINT ? { endpoint: process.env.COTUTOR_LIVE_ENDPOINT, env: { ...process.env, DASHSCOPE_API_KEY: process.env.DASHSCOPE_API_KEY ?? 'sk-probe' } } : {});

package/dist/app/ws/ws.d.ts

@@ -0,0 +1,31 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+export interface SocketEvents {
+    onText?(text: string): void;
+    onBinary?(data: Buffer): void;
+    onClose?(code: number, reason: string): void;
+}
+export interface ServerSocket {
+    sendText(text: string): boolean;
+    sendBinary(data: Buffer | Uint8Array): boolean;
+    close(code?: number, reason?: string): void;
+    readonly open: boolean;
+}
+/** 是不是 WebSocket 升级请求 */
+export declare function isUpgrade(req: IncomingMessage): boolean;
+export declare function acceptKey(key: string): string;
+/** 把一帧编出来(服务端不打掩码) */
+export declare function encodeFrame(opcode: number, payload: Buffer): Buffer;
+export interface Frame {
+    fin: boolean;
+    opcode: number;
+    payload: Buffer;
+    size: number;
+}
+/** 从缓冲区头上解一帧;不够一帧回 null;坏帧抛 */
+export declare function decodeFrame(buf: Buffer): Frame | null;
+/**
+ * 接受一条升级请求:写握手响应,之后 socket 归这里管。
+ * 回的对象发消息;事件在 ev 里。只在 isUpgrade(req) 为真时调。
+ */
+export declare function acceptWebSocket(req: IncomingMessage, socket: Duplex, head: Buffer, ev: SocketEvents): ServerSocket;

package/dist/app/ws/ws.js

@@ -0,0 +1,169 @@
+/**
+ * 最小的 WebSocket 服务端(RFC 6455),零依赖:孩子端 ↔ 本服务那条线用它(口语课、实时老师),测试里也拿它假扮百炼。
+ * 只做用得上的:握手、文本 / 二进制帧、分片拼接、ping/pong、close;不做扩展(permessage-deflate 不协商就不会来)。
+ * 客户端发来的帧必须带掩码(浏览器、Node 都带);服务端发出去的不带。
+ */
+import { createHash } from 'node:crypto';
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+/** 一帧最多收这么大(一块音频 100 毫秒 3200 字节;JSON 控制消息更小) */
+const MAX_FRAME = 4 * 1024 * 1024;
+/** 是不是 WebSocket 升级请求 */
+export function isUpgrade(req) {
+    return (req.headers.upgrade ?? '').toLowerCase() === 'websocket' && typeof req.headers['sec-websocket-key'] === 'string';
+}
+export function acceptKey(key) {
+    return createHash('sha1').update(key + GUID).digest('base64');
+}
+/** 把一帧编出来(服务端不打掩码) */
+export function encodeFrame(opcode, payload) {
+    const len = payload.length;
+    let head;
+    if (len < 126) {
+        head = Buffer.alloc(2);
+        head[1] = len;
+    }
+    else if (len < 65536) {
+        head = Buffer.alloc(4);
+        head[1] = 126;
+        head.writeUInt16BE(len, 2);
+    }
+    else {
+        head = Buffer.alloc(10);
+        head[1] = 127;
+        head.writeBigUInt64BE(BigInt(len), 2);
+    }
+    head[0] = 0x80 | opcode;
+    return Buffer.concat([head, payload]);
+}
+/** 从缓冲区头上解一帧;不够一帧回 null;坏帧抛 */
+export function decodeFrame(buf) {
+    if (buf.length < 2)
+        return null;
+    const fin = (buf[0] & 0x80) !== 0;
+    const opcode = buf[0] & 0x0f;
+    const masked = (buf[1] & 0x80) !== 0;
+    let len = buf[1] & 0x7f;
+    let p = 2;
+    if (len === 126) {
+        if (buf.length < 4)
+            return null;
+        len = buf.readUInt16BE(2);
+        p = 4;
+    }
+    else if (len === 127) {
+        if (buf.length < 10)
+            return null;
+        const big = buf.readBigUInt64BE(2);
+        if (big > BigInt(MAX_FRAME))
+            throw new Error('frame too large');
+        len = Number(big);
+        p = 10;
+    }
+    if (len > MAX_FRAME)
+        throw new Error('frame too large');
+    if (!masked)
+        throw new Error('client frame without mask');
+    if (buf.length < p + 4 + len)
+        return null;
+    const mask = buf.subarray(p, p + 4);
+    p += 4;
+    const payload = Buffer.allocUnsafe(len);
+    for (let i = 0; i < len; i++)
+        payload[i] = buf[p + i] ^ mask[i & 3];
+    return { fin, opcode, payload, size: p + len };
+}
+/**
+ * 接受一条升级请求:写握手响应,之后 socket 归这里管。
+ * 回的对象发消息;事件在 ev 里。只在 isUpgrade(req) 为真时调。
+ */
+export function acceptWebSocket(req, socket, head, ev) {
+    const key = String(req.headers['sec-websocket-key']);
+    socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${acceptKey(key)}\r\n\r\n`);
+    let buf = head.length ? Buffer.from(head) : Buffer.alloc(0);
+    let open = true;
+    let partial = null;
+    const closeWith = (code, reason) => {
+        if (!open)
+            return;
+        open = false;
+        try {
+            socket.end();
+        }
+        catch { /* 已经断了 */ }
+        ev.onClose?.(code, reason);
+    };
+    const raw = (opcode, payload) => {
+        if (!open || socket.destroyed)
+            return false;
+        socket.write(encodeFrame(opcode, payload));
+        return true;
+    };
+    const deliver = (opcode, payload) => {
+        if (opcode === 0x1)
+            ev.onText?.(payload.toString('utf8'));
+        else if (opcode === 0x2)
+            ev.onBinary?.(payload);
+    };
+    socket.on('data', (chunk) => {
+        buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+        try {
+            for (;;) {
+                const f = decodeFrame(buf);
+                if (!f)
+                    break;
+                buf = buf.subarray(f.size);
+                if (f.opcode === 0x8) {
+                    const code = f.payload.length >= 2 ? f.payload.readUInt16BE(0) : 1005;
+                    raw(0x8, f.payload.subarray(0, 2));
+                    closeWith(code, f.payload.length > 2 ? f.payload.subarray(2).toString('utf8') : '');
+                    return;
+                }
+                if (f.opcode === 0x9) {
+                    raw(0xa, f.payload);
+                    continue;
+                }
+                if (f.opcode === 0xa)
+                    continue;
+                if (f.opcode === 0x0) {
+                    if (!partial)
+                        throw new Error('continuation without start');
+                    partial.chunks.push(f.payload);
+                    if (f.fin) {
+                        const whole = Buffer.concat(partial.chunks);
+                        const op = partial.opcode;
+                        partial = null;
+                        deliver(op, whole);
+                    }
+                    continue;
+                }
+                if (!f.fin) {
+                    partial = { opcode: f.opcode, chunks: [f.payload] };
+                    continue;
+                }
+                deliver(f.opcode, f.payload);
+            }
+        }
+        catch (err) {
+            raw(0x8, Buffer.from([0x03, 0xea]));
+            closeWith(1002, err instanceof Error ? err.message : 'protocol error');
+        }
+    });
+    socket.on('error', () => closeWith(1006, 'socket error'));
+    socket.on('close', () => closeWith(1006, 'socket closed'));
+    socket.on('end', () => closeWith(1006, 'socket ended'));
+    return {
+        get open() { return open; },
+        sendText: (text) => raw(0x1, Buffer.from(text, 'utf8')),
+        sendBinary: (data) => raw(0x2, Buffer.isBuffer(data) ? data : Buffer.from(data.buffer, data.byteOffset, data.byteLength)),
+        close: (code = 1000, reason = '') => {
+            if (!open)
+                return;
+            const r = Buffer.from(reason, 'utf8');
+            const p = Buffer.alloc(2 + r.length);
+            p.writeUInt16BE(code, 0);
+            r.copy(p, 2);
+            raw(0x8, p);
+            closeWith(code, reason);
+        },
+    };
+}