cotutor 0.2.0 → 0.4.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,63 @@
+import { ConfigError, UsageError } from '../shared/errors.ts';
+import { redactDeep, redactHome } from '../shared/home.ts';
+import { type RootSource, type SandboxMark, 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'];
+/** 根下的 sandbox 标记(.cotutor/sandbox.json):没有 → null;坏了响亮报错(不当成真 workspace 静默往下跑) */
+export declare function readSandboxMark(root: string): SandboxMark | null;
+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,调用方决定是留旧的还是响。
+ * 比原文不比修改时间:Windows 上写 .tmp 再 rename 连写两次,修改时间常常一模一样(10-31 实测 200 次里 105 次);文件只有几 K,每次读一遍不贵。
+ */
+export declare function reloadIfChanged(ws: Workspace, lastText: string | null): Promise<{
+    ws: Workspace;
+    text: string;
+}>;

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

@@ -1,5 +1,5 @@
 /**
- * workspace解析:一孩一 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,23 +7,18 @@
  * 配置"在但解析不了"响亮报错,不静默走缺省(沿 drawtell 的教训)。
  */
 import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { ConfigError, UsageError } from "../shared/errors.js";
+import { redactDeep, redactHome } from "../shared/home.js";
+import { SANDBOX_MARK, SKILLS_DIR, SandboxMarkSchema } 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 里(2026-09-09 拍板) */
+/** 机器级自签证书目录(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) {
@@ -33,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();
@@ -137,22 +118,6 @@ export function resolveRoot(override, opts = {}) {
 }
 /** 校验 cotutor.json 的形状;失败 → ConfigError,信息是逐条修复指南 */
 export function parseConfig(raw, file) {
-    // 2026-09-09 术语统一(teacher → tutor,homework-aide → homework-tutor):旧键旧名响亮报,不静默变成零位老师
-    if (raw && typeof raw === 'object') {
-        const o = raw;
-        if ('teachers' in o && !('tutors' in o)) {
-            throw new ConfigError(file, '  - teachers:这个键 2026-09-09 起叫 tutors(术语统一为 tutor / 老师);把 "teachers" 改成 "tutors",老师名 *-teacher 改成 *-tutor、homework-aide 改成 homework-tutor,.claude/agents/ 下的文件同名改,然后 cotutor init 补齐');
-        }
-        if ('agents' in o && !('runtimes' in o)) {
-            throw new ConfigError(file, '  - agents:这个键 2026-09-09 起叫 runtimes(它是跑老师的运行时,与 .claude/agents/ 的 agent 文件、agents/<老师>/ 的老师目录是三回事);把 "agents" 改成 "runtimes" 即可,模板内容与占位 {agent} {agentBody} 不变');
-        }
-        const tutors = o.tutors;
-        if (tutors && typeof tutors === 'object') {
-            const old = Object.keys(tutors).filter((k) => k.endsWith('-teacher') || k === 'homework-aide');
-            if (old.length)
-                throw new ConfigError(file, `  - tutors:${old.join('、')} 是旧名;2026-09-09 起叫 ${old.map((k) => (k === 'homework-aide' ? 'homework-tutor' : k.replace(/-teacher$/, '-tutor'))).join('、')}(文件名与 frontmatter name 一起改),然后 cotutor init 补齐`);
-        }
-    }
     const r = CotutorConfigSchema.safeParse(raw);
     if (r.success)
         return r.data;
@@ -164,35 +129,45 @@ 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))
             out[role] = expandPath(value, vault);
     return out;
 }
+/** 根下的 sandbox 标记(.cotutor/sandbox.json):没有 → null;坏了响亮报错(不当成真 workspace 静默往下跑) */
+export function readSandboxMark(root) {
+    const file = join(root, SANDBOX_MARK);
+    const raw = readJson(file);
+    if (raw === null)
+        return null;
+    const r = SandboxMarkSchema.safeParse(raw);
+    if (!r.success)
+        throw new ConfigError(file, explainIssues(r.error.issues).map((l) => `  - ${l}`).join('\n'));
+    return r.data;
+}
 export function assembleWorkspace(root, source, config) {
+    const sandbox = readSandboxMark(root);
     return {
         root,
         source,
         config,
+        ...(sandbox ? { sandbox } : {}),
         paths: resolvePaths(root, config.paths),
         dirs: {
             agents: join(root, 'agents'),
             ledger: join(root, 'ledger'),
             conversations: join(root, 'conversations'),
-            claudeAgents: join(root, '.claude', 'agents'),
-            qwenAgents: join(root, '.qwen', 'agents'),
-            scenes: join(root, 'scenes'),
+            skills: join(root, SKILLS_DIR),
             bundles: join(root, 'bundles'),
-            snaps: join(root, 'snaps'),
+            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'),
         },
     };
 }
@@ -216,5 +191,78 @@ export function workspaceReport(ws) {
         vault: ws.paths.vault,
         tutors: Object.keys(ws.config.tutors),
         runtime: ws.config.runtimes.default,
+        ...(ws.sandbox ? { sandbox: { from: ws.sandbox.from, forkedAt: ws.sandbox.forkedAt } } : {}),
     });
 }
+// ---- 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,调用方决定是留旧的还是响。
+ * 比原文不比修改时间:Windows 上写 .tmp 再 rename 连写两次,修改时间常常一模一样(10-31 实测 200 次里 105 次);文件只有几 K,每次读一遍不贵。
+ */
+export async function reloadIfChanged(ws, lastText) {
+    const text = await readFile(ws.files.config, 'utf8').catch(() => null);
+    if (text === null)
+        throw new ConfigError(ws.files.config, '不存在了');
+    if (text === lastText)
+        return { ws, text };
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new ConfigError(ws.files.config, `不是合法 JSON:${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { ws: assembleWorkspace(ws.root, ws.source, parseConfig(raw, ws.files.config)), text };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 实时老师的那条 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;
+    idleCutMs?: number;
+    maxTakeMs?: number;
+    onFinished?(tutor: string, why: string): void;
+}
+/** 接升级的函数;openCalls = 现在开着几通(serve 看它定这台电脑能不能睡) */
+export type LiveUpgrade = ((req: IncomingMessage, socket: Duplex, head: Buffer, ctx: LiveApp) => Promise<boolean>) & {
+    openCalls(): number;
+};
+export declare function makeLiveUpgrade(deps?: LiveRouteDeps): LiveUpgrade;
+/** 探针:COTUTOR_LIVE_ENDPOINT 指到假百炼 */
+export declare const liveUpgrade: LiveUpgrade;

package/dist/app/ws/route.js

@@ -0,0 +1,33 @@
+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 = {}) {
+    const open = new Set();
+    const liveUpgrade = 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, idleCutMs: deps.idleCutMs, maxTakeMs: deps.maxTakeMs, onFinished: (why) => { if (call)
+                open.delete(call); deps.onFinished?.(tutor, why); } });
+        open.add(call);
+        void call.start();
+        return true;
+    };
+    return Object.assign(liveUpgrade, { openCalls: () => open.size });
+}
+/** 探针:COTUTOR_LIVE_ENDPOINT 指到假百炼 */
+export const liveUpgrade = makeLiveUpgrade(process.env.COTUTOR_LIVE_ENDPOINT ? { endpoint: process.env.COTUTOR_LIVE_ENDPOINT } : {});

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;