cotutor 0.2.0 → 0.4.0

package/dist/runtime/journal/store.d.ts

@@ -0,0 +1,123 @@
+import { type CardAssets, type CardStateFile, type CardStates } from '../../schema/index.ts';
+import { type Transcript } from '../../brain/transcript.ts';
+import { type ConversationIndex } from '../../schema/index.ts';
+import { type ThreadUndo } from '../../memory/vault.ts';
+import type { Workspace } from '../../schema/index.ts';
+export declare class IndexError extends Error {
+    constructor(file: string, cause: string);
+}
+export declare function readIndex(ws: Workspace, tutor: string, date: string): Promise<ConversationIndex>;
+/** 先写 .tmp 再 rename:进程半路死掉不会留下半份索引 */
+export declare function writeIndex(ws: Workspace, index: ConversationIndex): Promise<void>;
+/** 有过对话的日期,新的在前 */
+export declare function listDates(ws: Workspace, tutor: string): Promise<string[]>;
+/** 一轮的转录:统一事件,旧轮次的 stream-json 也读(src/brain/log.ts) */
+export declare function readTranscript(ws: Workspace, tutor: string, date: string, job: string): Promise<Transcript | null>;
+/**
+ * 一天里卡的目录 <date>.<job>.cards/ 全扫一遍:<n>.json 是孩子做的事(坏文件跳过,孩子端不报),<n>/<k>.mp3 是后台生成好的资产。
+ */
+export declare function scanCards(ws: Workspace, tutor: string, date: string): Promise<{
+    states: CardStates;
+    assets: CardAssets;
+}>;
+/** 只要孩子做的事(发消息时挑「上一轮之后改过的」) */
+export declare function readCardStates(ws: Workspace, tutor: string, date: string): Promise<CardStates>;
+/** 存一张卡的状态(先 .tmp 再 rename);turn = 存的时候索引里最后一条的 job */
+export declare function writeCardState(ws: Workspace, tutor: string, date: string, job: string, n: number, file: CardStateFile): Promise<void>;
+/** 画板导出的 png:<date>.<job>.cards/<n>.png;返回相对 conversations/<老师>/ 的名字 */
+export declare function writeCardImage(ws: Workspace, tutor: string, date: string, job: string, n: number, png: Buffer): Promise<string>;
+/**
+ * 作业照片(R5,2026-09-14):落 workspace 的 captures/<日期>/<HHMM>-<n>.<ext>(paths.captures,相对 workspace 根),
+ * 不落 vault。返回相对 workspace 根的路径(消息的 photos、上下文包的 photos: 段、/api/kid/image?p= 都用它)。
+ */
+export declare function writeCapture(ws: Workspace, at: Date, data: Buffer, ext: 'jpg' | 'png'): Promise<string>;
+/** 消息里的照片路径合不合法:相对 workspace 根、落在 paths.captures 里、文件在 */
+export declare function capturePathOk(ws: Workspace, rel: string): Promise<boolean>;
+/**
+ * 这一轮真发出去的东西(<date>.<job>.run.json):上下文包与完整命令行。
+ * 跑完就丢的话「老师为什么没看见孩子选了 C」永远查不了,所以落一份;只有家长端「看原文」读它。
+ */
+/** 这轮用的老师文件与技能的快照(2026-09-15):文件后来改了就查不回当时那份,所以记正文与 hash;技能只记 hash,变没变一眼看 */
+export interface RunSources {
+    agent: {
+        file: string;
+        hash: string;
+        body: string;
+    } | null;
+    /** 技能名 → SKILL.md 的 hash(workspace .agents/skills/ 下有的全部) */
+    skills: Record<string, string>;
+    /** 这轮上下文包里带了原文的笔记(守则、档案、记忆、口径……):role、路径、带进去那段的 hash 与字数、截没截(2026-10-30;续话题「未变」的不在这里) */
+    notes?: {
+        role: string;
+        path: string;
+        hash: string;
+        chars: number;
+        cut?: true;
+    }[];
+    /** 替老师查的(memory/retrieval.ts):文件(相对 vault 根)、整篇的 hash、为什么查 */
+    retrieved?: {
+        path: string;
+        hash: string;
+        why: string;
+    }[];
+}
+export interface RunFile {
+    at: string;
+    /** 拼好的上下文包(消息正文在最后) */
+    prompt: string;
+    runtime: string;
+    /** 完整命令行,argv[0] 是可执行文件 */
+    argv: string[];
+    resume: boolean;
+    session: string | null;
+    /** 老师文件与技能的快照;2026-09-15 之前的轮次没有 */
+    sources?: RunSources;
+    /** 老师正文进了系统提示(API 运行时总是;旧轮次看那时的命令模板) */
+    agentBody: boolean;
+}
+export declare function writeRunFile(ws: Workspace, tutor: string, date: string, job: string, r: {
+    at: string;
+    prompt: string;
+    plan: {
+        runtime: string;
+        argv: string[];
+        resume: boolean;
+        session: string | null;
+    };
+    agentBody: boolean;
+    sources?: RunSources;
+}): Promise<void>;
+export declare function readRunFile(ws: Workspace, tutor: string, date: string, job: string): Promise<RunFile | null>;
+export declare function readErrLog(ws: Workspace, tutor: string, date: string, job: string): Promise<string>;
+/** 这轮起跑时老师文件与技能长什么样(记进 run.json;读不到的就 null / 空,不拦这一轮) */
+export declare function snapshotSources(ws: Workspace, name: string): Promise<RunSources>;
+/** 老师文件正文(系统提示的前半);从 agents/<name>.md 读 */
+export declare function readAgentBody(ws: Workspace, name: string): Promise<string>;
+/** 给一个话题打星(1–5;null 清掉):话题要在这天的索引里;写回索引 */
+export declare function rateThread(ws: Workspace, tutor: string, date: string, thread: string, rating: number | null): Promise<ConversationIndex>;
+export { readDiaries, readTextbooks, scanVault, undoThreadVault, writeDiary, type ThreadUndo, type Vault } from '../../memory/vault.ts';
+/**
+ * 删掉一天里的一个话题(家长板书页清单上的「删」,2026-09-22):索引里它的消息、会话、星、记账标记都去掉,
+ * 这些轮的文件(转录、run、事件、配音、卡的状态与资产)按 <日期>.<job>.* 整个删。
+ * 这个话题留下的痕迹一起撤(2026-10-05,家长在孩子端试过再删):各轮写进 vault 记忆的行(memoryLines)倒着撤、记账写进日记的那段(diaryBlock)摘掉;
+ * 写到一半断了的(还带着 pending)先对照文件补记,写成了的一样撤。不动的:captures/ 里的照片。跑着的轮由路由先挡(409)。
+ */
+export declare function deleteThread(ws: Workspace, tutor: string, date: string, thread: string): Promise<{
+    index: ConversationIndex;
+    undo: ThreadUndo;
+}>;
+/** 话题写进 vault 的一笔:memory = 这位老师(或这个 activity)的记忆,child = 孩子的记忆,diary = 记账写进日记的那段 */
+export type VaultWrite = {
+    job: string;
+    kind: 'memory' | 'child' | 'diary';
+    n: number;
+};
+/**
+ * 撤回一个话题写进 vault 的一笔(家长端「记录」的「撤回」,2026-10-30,《vault重构方案》§8):n = 那一轮 memoryLines / childLines 的第几条(diary 不用)。
+ * 撤法同删话题(undoThreadVault):家长后来改过那行就找不到,不动,回 misses。撤成了就从那一轮的记录里去掉(删话题时不再撤一遍);
+ * 日记那段撤了 booked 照留,不再自动记它。写到一半断了的先补记。跑着的轮由路由先挡(409)。
+ */
+export declare function undoVaultWrite(ws: Workspace, tutor: string, date: string, thread: string, w: VaultWrite): Promise<{
+    index: ConversationIndex;
+    undo: ThreadUndo;
+}>;

package/dist/runtime/journal/store.js

@@ -0,0 +1,316 @@
+/**
+ * 对话与配置的文件层:索引读写(坏索引响亮报错,不静默覆盖)、日期列表、转录读取、老师正文、cotutor.json 补丁写回。
+ * 纯函数在 lib/,这里只碰文件系统。
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { parseAgentFile } from "../agent-file.js";
+import { emptyIndex } from "./conversation.js";
+import { localDate } from "../../shared/time.js";
+import { cardAssetName, conversationFiles, threads, tutorFilePath } from "../../schema/index.js";
+import { parseTranscript } from "../../brain/transcript.js";
+import { parseLogLine } from "../../brain/index.js";
+import { ConversationIndexSchema, DATE_RE, explainIssues, } from "../../schema/index.js";
+import { undoThreadVault } from "../../memory/vault.js";
+import { recoverPending } from "../../memory/commit.js";
+import { ConfigError } from "../../shared/errors.js";
+import { redactHome } from "../../shared/home.js";
+export class IndexError extends Error {
+    constructor(file, cause) {
+        super(`对话索引用不了:${redactHome(file)}\n${cause}\n修好它或改名挪开(转录 .log 还在,能重建);不要删。`);
+    }
+}
+export async function readIndex(ws, tutor, date) {
+    const file = conversationFiles(ws.dirs.conversations, tutor, date).index;
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return emptyIndex(tutor, date);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new IndexError(file, `不是合法 JSON:${err instanceof Error ? err.message : String(err)}`);
+    }
+    const r = ConversationIndexSchema.safeParse(raw);
+    if (!r.success)
+        throw new IndexError(file, explainIssues(r.error.issues).map((l) => `  - ${l}`).join('\n'));
+    return r.data;
+}
+/** 先写 .tmp 再 rename:进程半路死掉不会留下半份索引 */
+export async function writeIndex(ws, index) {
+    const { index: file } = conversationFiles(ws.dirs.conversations, index.tutor, index.date);
+    await mkdir(join(ws.dirs.conversations, index.tutor), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(index, null, 2)}\n`);
+    await rename(tmp, file);
+}
+/** 有过对话的日期,新的在前 */
+export async function listDates(ws, tutor) {
+    try {
+        return (await readdir(join(ws.dirs.conversations, tutor)))
+            .filter((f) => /^\d{4}-\d{2}-\d{2}\.json$/.test(f))
+            .map((f) => f.slice(0, 10))
+            .filter((d) => DATE_RE.test(d))
+            .sort()
+            .reverse();
+    }
+    catch {
+        return [];
+    }
+}
+/** 一轮的转录:统一事件,旧轮次的 stream-json 也读(src/brain/log.ts) */
+export async function readTranscript(ws, tutor, date, job) {
+    try {
+        return parseTranscript(await readFile(conversationFiles(ws.dirs.conversations, tutor, date).log(job), 'utf8'), parseLogLine);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 一天里卡的目录 <date>.<job>.cards/ 全扫一遍:<n>.json 是孩子做的事(坏文件跳过,孩子端不报),<n>/<k>.mp3 是后台生成好的资产。
+ */
+export async function scanCards(ws, tutor, date) {
+    const dir = join(ws.dirs.conversations, tutor);
+    const states = {};
+    const assets = {};
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { states, assets };
+    }
+    for (const name of names) {
+        const m = new RegExp(`^${date}\\.(\\d{4}-\\d+)\\.cards$`).exec(name);
+        if (!m)
+            continue;
+        const job = m[1];
+        let files;
+        try {
+            files = await readdir(join(dir, name), { withFileTypes: true }).then((es) => es.map((e) => (e.isDirectory() ? `${e.name}/` : e.name)));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            const n = /^(\d+)\.json$/.exec(f);
+            if (n) {
+                try {
+                    const raw = JSON.parse(await readFile(join(dir, name, f), 'utf8'));
+                    if (raw && typeof raw.at === 'string' && typeof raw.turn === 'string' && 'state' in raw)
+                        (states[job] ??= {})[Number(n[1])] = raw;
+                }
+                catch {
+                    /* 坏文件:当没做过 */
+                }
+                continue;
+            }
+            const d = /^(\d+)\/$/.exec(f);
+            if (!d)
+                continue;
+            try {
+                const inner = (await readdir(join(dir, name, d[1]))).filter((x) => /^\d+\.mp3$/.test(x)).sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
+                if (inner.length)
+                    (assets[job] ??= {})[Number(d[1])] = inner.map((x) => cardAssetName(date, job, Number(d[1]), x));
+            }
+            catch {
+                /* 目录没了:当没有 */
+            }
+        }
+    }
+    return { states, assets };
+}
+/** 只要孩子做的事(发消息时挑「上一轮之后改过的」) */
+export async function readCardStates(ws, tutor, date) {
+    return (await scanCards(ws, tutor, date)).states;
+}
+/** 存一张卡的状态(先 .tmp 再 rename);turn = 存的时候索引里最后一条的 job */
+export async function writeCardState(ws, tutor, date, job, n, file) {
+    const files = conversationFiles(ws.dirs.conversations, tutor, date);
+    await mkdir(files.cardsDir(job), { recursive: true });
+    const target = files.card(job, n);
+    await writeFile(`${target}.tmp`, `${JSON.stringify(file, null, 2)}\n`);
+    await rename(`${target}.tmp`, target);
+}
+/** 画板导出的 png:<date>.<job>.cards/<n>.png;返回相对 conversations/<老师>/ 的名字 */
+export async function writeCardImage(ws, tutor, date, job, n, png) {
+    const files = conversationFiles(ws.dirs.conversations, tutor, date);
+    await mkdir(files.cardsDir(job), { recursive: true });
+    const target = `${files.cardsDir(job)}/${n}.png`;
+    await writeFile(target, png);
+    return `${date}.${job}.cards/${n}.png`;
+}
+/**
+ * 作业照片(R5,2026-09-14):落 workspace 的 captures/<日期>/<HHMM>-<n>.<ext>(paths.captures,相对 workspace 根),
+ * 不落 vault。返回相对 workspace 根的路径(消息的 photos、上下文包的 photos: 段、/api/kid/image?p= 都用它)。
+ */
+export async function writeCapture(ws, at, data, ext) {
+    const date = localDate(at);
+    const dir = join(ws.paths.captures, date);
+    await mkdir(dir, { recursive: true });
+    const hhmm = `${String(at.getHours()).padStart(2, '0')}${String(at.getMinutes()).padStart(2, '0')}`;
+    const taken = new Set(await readdir(dir).catch(() => []));
+    let n = 1;
+    while (taken.has(`${hhmm}-${n}.jpg`) || taken.has(`${hhmm}-${n}.png`))
+        n++;
+    const file = join(dir, `${hhmm}-${n}.${ext}`);
+    await writeFile(file, data);
+    return relative(ws.root, file).split(sep).join('/');
+}
+/** 消息里的照片路径合不合法:相对 workspace 根、落在 paths.captures 里、文件在 */
+export async function capturePathOk(ws, rel) {
+    if (!rel || rel.startsWith('/') || rel.includes('..') || rel.includes('\\'))
+        return false;
+    const file = join(ws.root, rel);
+    if (!(file === ws.paths.captures || file.startsWith(ws.paths.captures + sep)))
+        return false;
+    return (await stat(file).catch(() => null))?.isFile() ?? false;
+}
+export async function writeRunFile(ws, tutor, date, job, r) {
+    const file = conversationFiles(ws.dirs.conversations, tutor, date).run(job);
+    const row = { at: r.at, prompt: r.prompt, runtime: r.plan.runtime, argv: r.plan.argv, resume: r.plan.resume, session: r.plan.session, agentBody: r.agentBody, ...(r.sources ? { sources: r.sources } : {}) };
+    try {
+        await mkdir(join(ws.dirs.conversations, tutor), { recursive: true });
+        await writeFile(file, `${JSON.stringify(row, null, 2)}\n`);
+    }
+    catch {
+        /* 落不下就算了:这只是给「看原文」看的,不能拦着老师说话 */
+    }
+}
+export async function readRunFile(ws, tutor, date, job) {
+    try {
+        const text = await readFile(conversationFiles(ws.dirs.conversations, tutor, date).run(job), 'utf8');
+        const v = JSON.parse(text);
+        return typeof v?.prompt === 'string' && Array.isArray(v.argv) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readErrLog(ws, tutor, date, job) {
+    try {
+        return await readFile(conversationFiles(ws.dirs.conversations, tutor, date).err(job), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+const sha = (text) => `sha256:${createHash('sha256').update(text).digest('hex').slice(0, 16)}`;
+/** 这轮起跑时老师文件与技能长什么样(记进 run.json;读不到的就 null / 空,不拦这一轮) */
+export async function snapshotSources(ws, name) {
+    let agent = null;
+    const file = tutorFilePath(ws.dirs.agents, name);
+    try {
+        const body = await readFile(file, 'utf8');
+        agent = { file: relative(ws.root, file).split(sep).join('/'), hash: sha(body), body };
+    }
+    catch {
+        /* 读不到:记 null */
+    }
+    const skills = {};
+    for (const d of await readdir(ws.dirs.skills, { withFileTypes: true }).catch(() => [])) {
+        if (!d.isDirectory() && !d.isSymbolicLink())
+            continue;
+        const text = await readFile(join(ws.dirs.skills, d.name, 'SKILL.md'), 'utf8').catch(() => null);
+        if (text !== null)
+            skills[d.name] = sha(text);
+    }
+    return { agent, skills };
+}
+/** 老师文件正文(系统提示的前半);从 agents/<name>.md 读 */
+export async function readAgentBody(ws, name) {
+    const file = tutorFilePath(ws.dirs.agents, name);
+    try {
+        return parseAgentFile(await readFile(file, 'utf8')).body;
+    }
+    catch {
+        throw new ConfigError(file, '老师文件读不到;cotutor init 补拷');
+    }
+}
+/** 给一个话题打星(1–5;null 清掉):话题要在这天的索引里;写回索引 */
+export async function rateThread(ws, tutor, date, thread, rating) {
+    const index = await readIndex(ws, tutor, date);
+    if (!threads(index.messages).includes(thread))
+        throw new IndexError(conversationFiles(ws.dirs.conversations, tutor, date).index, `${date} 没有话题 ${thread}`);
+    const ratings = { ...index.ratings };
+    if (rating === null)
+        delete ratings[thread];
+    else
+        ratings[thread] = rating;
+    const next = { ...index, ratings };
+    await writeIndex(ws, next);
+    return next;
+}
+// ---- vault 搬到了 src/memory/vault.ts;旧路径留转发,迁完删 ----
+export { readDiaries, readTextbooks, scanVault, undoThreadVault, writeDiary } from "../../memory/vault.js";
+/**
+ * 删掉一天里的一个话题(家长板书页清单上的「删」,2026-09-22):索引里它的消息、会话、星、记账标记都去掉,
+ * 这些轮的文件(转录、run、事件、配音、卡的状态与资产)按 <日期>.<job>.* 整个删。
+ * 这个话题留下的痕迹一起撤(2026-10-05,家长在孩子端试过再删):各轮写进 vault 记忆的行(memoryLines)倒着撤、记账写进日记的那段(diaryBlock)摘掉;
+ * 写到一半断了的(还带着 pending)先对照文件补记,写成了的一样撤。不动的:captures/ 里的照片。跑着的轮由路由先挡(409)。
+ */
+export async function deleteThread(ws, tutor, date, thread) {
+    const { index } = await recoverPending(ws, await readIndex(ws, tutor, date));
+    const ths = threads(index.messages);
+    if (!ths.includes(thread))
+        throw new IndexError(conversationFiles(ws.dirs.conversations, tutor, date).index, `${date} 没有话题 ${thread}`);
+    const gone = index.messages.filter((_, i) => ths[i] === thread);
+    const kept = index.messages.filter((_, i) => ths[i] !== thread);
+    const dir = join(ws.dirs.conversations, tutor);
+    const prefixes = gone.map((m) => `${date}.${m.job}.`);
+    for (const e of await readdir(dir).catch(() => []))
+        if (prefixes.some((p) => e.startsWith(p)))
+            await rm(join(dir, e), { recursive: true, force: true });
+    const { [thread]: _s, ...sessions } = index.sessions;
+    const { [thread]: _r, ...ratings } = index.ratings;
+    const { [thread]: _b, ...booked } = index.booked;
+    // 当前话题(末条所在)的会话:删的正是它就换成剩下的末条那个;不是就不动
+    const keptThreads = threads(kept);
+    const last = keptThreads[keptThreads.length - 1];
+    const session = ths[ths.length - 1] === thread ? (last ? (sessions[last] ?? null) : null) : index.session;
+    const next = { ...index, messages: kept, sessions, ratings, booked, session };
+    const undo = await undoThreadVault(ws, tutor, date, gone);
+    await writeIndex(ws, next);
+    return { index: next, undo };
+}
+/**
+ * 撤回一个话题写进 vault 的一笔(家长端「记录」的「撤回」,2026-10-30,《vault重构方案》§8):n = 那一轮 memoryLines / childLines 的第几条(diary 不用)。
+ * 撤法同删话题(undoThreadVault):家长后来改过那行就找不到,不动,回 misses。撤成了就从那一轮的记录里去掉(删话题时不再撤一遍);
+ * 日记那段撤了 booked 照留,不再自动记它。写到一半断了的先补记。跑着的轮由路由先挡(409)。
+ */
+export async function undoVaultWrite(ws, tutor, date, thread, w) {
+    const { index } = await recoverPending(ws, await readIndex(ws, tutor, date));
+    const ths = threads(index.messages);
+    const file = conversationFiles(ws.dirs.conversations, tutor, date).index;
+    const at = index.messages.findIndex((m, i) => m.job === w.job && ths[i] === thread);
+    if (at < 0)
+        throw new IndexError(file, `${date} 的话题 ${thread} 里没有 ${w.job} 这一轮`);
+    const m = index.messages[at];
+    const lines = w.kind === 'memory' ? m.memoryLines : w.kind === 'child' ? m.childLines : undefined;
+    if (w.kind === 'diary' ? !m.diaryBlock : !lines?.[w.n])
+        throw new IndexError(file, `${w.job} 这一轮没有这一笔(${w.kind} ${w.n})`);
+    // 一笔撤一笔:拼一条只带这一笔的消息交给删话题那套;activity 话题的记忆在 activity 自己那篇,activity 记在话题第一条
+    const activity = index.messages.find((x, i) => ths[i] === thread && x.activity)?.activity;
+    const one = { ...m, ...(activity ? { activity } : {}), memoryLines: w.kind === 'memory' ? [lines[w.n]] : [], childLines: w.kind === 'child' ? [lines[w.n]] : [], diaryBlock: w.kind === 'diary' ? m.diaryBlock : undefined };
+    const undo = await undoThreadVault(ws, tutor, date, [one]);
+    if (!undo.memory && !undo.diary)
+        return { index, undo };
+    // remembered = 自己的改动在前、孩子的记忆在后(和 memoryLines、childLines 一一对上);对不上的老数据不动它
+    const mem = m.memoryLines ?? [];
+    const kid = m.childLines ?? [];
+    const remembered = m.remembered && m.remembered.length === mem.length + kid.length && w.kind !== 'diary' ? m.remembered.filter((_, k) => k !== (w.kind === 'memory' ? w.n : mem.length + w.n)) : m.remembered;
+    const next = w.kind === 'diary'
+        ? (({ diaryBlock: _d, ...rest }) => rest)(m)
+        : { ...m, ...(w.kind === 'memory' ? { memoryLines: mem.filter((_, k) => k !== w.n) } : { childLines: kid.filter((_, k) => k !== w.n) }), ...(remembered ? { remembered } : {}) };
+    const out = { ...index, messages: index.messages.map((x, k) => (k === at ? next : x)) };
+    await writeIndex(ws, out);
+    return { index: out, undo };
+}
+// cotutor.json 的补丁写回与热重载在 src/app/workspace.ts(读配置那边)

package/dist/runtime/kid-input.d.ts

@@ -0,0 +1,16 @@
+import type { Workspace } from '../schema/index.ts';
+import type { SendInput } from './runner.ts';
+export interface KidReject {
+    status: 400 | 409;
+    error: 'bad_request' | 'submitted' | 'bad_via' | 'bad_talk';
+    /** 给人看的一句(多数没有) */
+    message?: string;
+}
+export type KidAccept = {
+    input: SendInput;
+} | {
+    reject: KidReject;
+};
+export declare function kidInput(ws: Workspace, tutor: string, body: unknown, date: string, deviceId?: string | null): Promise<KidAccept>;
+/** 消息里的 photos[]:都得是 captures/ 里在的文件(相对 workspace 根);不合法 → null */
+export declare function photosOf(ws: Workspace, v: unknown): Promise<string[] | null | undefined>;

package/dist/runtime/kid-input.js

@@ -0,0 +1,194 @@
+/**
+ * 孩子端发一条的验与拼:孩子端只走实时那条连接(src/runtime/live/turns.ts;HTTP 的发 2026-11-04 删了),经 Runner.accept 进来。
+ * 验正文、话题、首页按钮、小课堂、activity、照片,拼成 Runner.send 的入参;不对回 reject(状态码 + 错误名),连接上回 {t:'err'}。不起老师。
+ */
+import { FocusSchema, HomeViaSchema, DeviceSchema } from "../schema/index.js";
+import { BUNDLE_ID_RE } from "../board/cards/kind.js";
+import { threads } from "../schema/index.js";
+import { submittedCards } from "./kid-view.js";
+import { MARK_MAX, MARK_MAX_POINTS, MARK_MAX_STROKES } from "../board/lecture.js";
+import { messageVia, resolveVia } from "./home/store.js";
+import { validDevice } from "./journal/kid-log.js";
+import { PAPER_KEY_RE, paperDrawing, readPaper } from "../board/paper.js";
+import { capturePathOk, readIndex } from "./journal/store.js";
+import { talkRun } from "./talk-run.js";
+const reject = (status, error, message) => ({ reject: { status, error, ...(message ? { message } : {}) } });
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+export async function kidInput(ws, tutor, body, date, deviceId) {
+    if (!isObj(body) || typeof body.text !== 'string')
+        return reject(400, 'bad_request');
+    const focus = body.focus === undefined ? undefined : FocusSchema.safeParse(body.focus);
+    if (focus && !focus.success)
+        return reject(400, 'bad_request');
+    const action = body.action === undefined ? undefined : body.action === 'submit' ? 'submit' : null;
+    if (action === null)
+        return reject(400, 'bad_request');
+    const photos = await photosOf(ws, body.photos);
+    if (photos === null)
+        return reject(400, 'bad_request');
+    // 左栏的纸交的画:{key, image};图得在 captures/ 里,摘要按那张纸上的笔迹算
+    let drawing;
+    if (body.drawing !== undefined) {
+        const d = body.drawing;
+        if (!isObj(d) || typeof d.key !== 'string' || !PAPER_KEY_RE.test(d.key) || typeof d.image !== 'string' || !(await capturePathOk(ws, d.image)))
+            return reject(400, 'bad_request');
+        drawing = paperDrawing(await readPaper(ws, tutor, date, d.key), d.image);
+    }
+    const thread = body.thread === undefined ? undefined : typeof body.thread === 'string' && /^\d{4}-\d+$/.test(body.thread) ? body.thread : null;
+    if (thread === null)
+        return reject(400, 'bad_request');
+    const today = await readIndex(ws, tutor, date);
+    // 交过的卡不能再交(kid-view 的 submittedCards)
+    if (action === 'submit' && focus?.data?.card && submittedCards(today).has(focus.data.card))
+        return reject(409, 'submitted');
+    const device = body.device === undefined ? undefined : DeviceSchema.safeParse(body.device);
+    if (device && !device.success)
+        return reject(400, 'bad_request');
+    // 首页的按钮:via 只带 id,按钮是什么、讲法是什么都从服务端的发布件查;对不上就 400(孩子端刷新首页)
+    const via = body.via === undefined ? undefined : HomeViaSchema.safeParse(body.via);
+    if (via && !via.success)
+        return reject(400, 'bad_request');
+    const button = via ? await resolveVia(ws, tutor, via.data) : null;
+    if (via && !button)
+        return reject(400, 'bad_via');
+    let text = body.text;
+    let newThread = body.newThread === true;
+    let pick = thread;
+    let home;
+    let continues;
+    let activity;
+    // 小课堂:看完才能开口——这一条要带 lecture(哪份课包、看完了、看了多久、停过几次、画过的几处),字是孩子说的;新开话题。
+    // 问过以后「再看一遍」:同一话题的下一条带 lecture(新画的、又看的过程;话题得是从这份课包开始的)
+    let lecture = lectureOf(body.lecture);
+    if (lecture === null)
+        return reject(400, 'bad_request');
+    if (lecture) {
+        const shots = lecture.marks.flatMap((k) => (k.image ? [k.image] : []));
+        if (shots.length + (photos?.length ?? 0) > 9)
+            return reject(400, 'bad_request', '照片和画的截图一共最多 9 张');
+        for (const x of shots)
+            if (!(await capturePathOk(ws, x)))
+                return reject(400, 'bad_request');
+    }
+    if (lecture && button?.kind !== 'lecture') {
+        const idx = thread && !via ? await readIndex(ws, tutor, date) : null;
+        const ths = idx ? threads(idx.messages) : [];
+        const from = idx?.messages.find((m, i) => ths[i] === thread && m.lecture && !m.lecture.again);
+        if (!from || from.lecture?.bundle !== lecture.bundle || (!lecture.marks.length && !lecture.log.length))
+            return reject(400, 'bad_request');
+        lecture = { ...lecture, again: true };
+    }
+    if (button?.kind === 'lecture') {
+        if (!lecture || lecture.bundle !== button.bundle || !lecture.finished)
+            return reject(400, 'bad_request', '小课堂要看完才能问');
+        home = { button: button.label, ...(button.brief ? { brief: button.brief } : {}) };
+        if (button.activity)
+            activity = button.activity;
+        newThread = true;
+        pick = undefined;
+    }
+    if (button && (button.kind === 'start' || button.kind === 'continue')) {
+        text = button.label;
+        home = { button: button.label, ...(button.brief ? { brief: button.brief } : {}) };
+        if (button.kind === 'continue' && button.date === date) {
+            newThread = false;
+            pick = button.thread;
+        }
+        else {
+            newThread = true;
+            pick = undefined;
+            if (button.kind === 'continue')
+                continues = { date: button.date, thread: button.thread };
+        }
+    }
+    // activity 按钮:和开场按钮一样新开话题、发按钮上的字;参数是 resolveVia 按 activity 文件解析好的,记在这条消息上
+    if (button?.kind === 'activity') {
+        text = button.label;
+        home = { button: button.label, ...(button.brief ? { brief: button.brief } : {}) };
+        newThread = true;
+        pick = undefined;
+        activity = { name: button.activity, params: button.params };
+    }
+    // 口语课:口语课页拍好、改好的那份口语单,新开话题跑这位老师的 activity「口语课」
+    let talk;
+    if (body.talk !== undefined) {
+        const t = await talkRun(ws, tutor, body.talk);
+        if (!t)
+            return reject(400, 'bad_talk');
+        newThread = true;
+        pick = undefined;
+        activity = t.run;
+        talk = t.id;
+    }
+    if (!text.trim() && !action && !photos?.length && !drawing)
+        return reject(400, 'bad_request');
+    return { input: { ...(talk ? { talk } : {}), from: 'kid', text, focus: focus?.data, action, newThread, thread: pick, device: device?.data, ...(validDevice(deviceId) ? { deviceId: deviceId } : {}), photos, ...(drawing ? { drawing } : {}), ...(via && button ? { via: messageVia(via.data, button) } : {}), ...(home ? { home } : {}), ...(continues ? { continues } : {}), ...(activity ? { activity } : {}), ...(lecture ? { lecture } : {}) } };
+}
+/** 消息里的 photos[]:都得是 captures/ 里在的文件(相对 workspace 根);不合法 → null */
+export async function photosOf(ws, v) {
+    if (v === undefined)
+        return undefined;
+    if (!Array.isArray(v) || v.length > 9 || !v.every((p) => typeof p === 'string'))
+        return null;
+    for (const p of v)
+        if (!(await capturePathOk(ws, p)))
+            return null;
+    return v;
+}
+/** 一处画里一笔最多几个点(播放器抽到 MARK_STROKE_POINTS,这里松一点);一条消息最多几处、一处几笔几个点见 src/board/lecture.ts */
+const MAX_STROKE_POINTS = 400;
+/** 看的过程最多几条(拖进度条只记松手那一下,一堂课几十条) */
+const MAX_WATCH_LOG = 500;
+/** 孩子看完小课堂带来的:{bundle, watchedMs, finished, pauses, marks?};没带 undefined,形状不对 null(路由回 400) */
+function lectureOf(v) {
+    if (v === undefined)
+        return undefined;
+    if (!isObj(v) || typeof v.bundle !== 'string' || !BUNDLE_ID_RE.test(v.bundle) || typeof v.watchedMs !== 'number' || !(v.watchedMs >= 0) || v.watchedMs > 6 * 3600_000 || typeof v.finished !== 'boolean')
+        return null;
+    const pauses = v.pauses === undefined ? 0 : v.pauses;
+    if (typeof pauses !== 'number' || !Number.isInteger(pauses) || pauses < 0 || pauses > 999)
+        return null;
+    const raw = v.marks === undefined ? [] : v.marks;
+    if (!Array.isArray(raw) || raw.length > MARK_MAX)
+        return null;
+    const marks = [];
+    const point = (p) => (Array.isArray(p) && p.length === 2 && p.every((x) => typeof x === 'number' && Number.isFinite(x) && Math.abs(x) < 1e5) ? [Math.round(p[0]), Math.round(p[1])] : null);
+    for (const m of raw) {
+        if (!isObj(m) || typeof m.atMs !== 'number' || !(m.atMs >= 0) || m.atMs > 6 * 3600_000)
+            return null;
+        // 一处 = 停在同一刻画的几笔(strokes);2026-10-19 以前一笔一处(path),照读
+        const rawStrokes = Array.isArray(m.strokes) ? m.strokes : Array.isArray(m.path) ? [m.path] : null;
+        if (!rawStrokes || !rawStrokes.length || rawStrokes.length > MARK_MAX_STROKES)
+            return null;
+        const strokes = [];
+        for (const st of rawStrokes) {
+            if (!Array.isArray(st) || st.length < 2 || st.length > MAX_STROKE_POINTS)
+                return null;
+            const pts = st.map(point);
+            if (pts.some((p) => p === null))
+                return null;
+            strokes.push(pts);
+        }
+        if (strokes.reduce((n, st) => n + st.length, 0) > MARK_MAX_POINTS)
+            return null;
+        // 截图(先 POST photos 拿到的 captures/ 路径;在不在由路由再查)
+        if (m.image !== undefined && (typeof m.image !== 'string' || m.image.length > 200))
+            return null;
+        // 画下去的那一刻(离发出去多少毫秒,≤ 0;录像用)
+        const t = m.t === undefined ? undefined : typeof m.t === 'number' && Number.isFinite(m.t) && m.t <= 0 && m.t > -6 * 3600_000 ? Math.round(m.t) : null;
+        if (t === null)
+            return null;
+        marks.push({ atMs: Math.round(m.atMs), strokes, ...(typeof m.image === 'string' ? { image: m.image } : {}), ...(t !== undefined ? { t } : {}) });
+    }
+    // 看的过程(录像用):放 / 停 / 拖到哪,一次一条,t ≤ 0
+    const rawLog = v.log === undefined ? [] : v.log;
+    if (!Array.isArray(rawLog) || rawLog.length > MAX_WATCH_LOG)
+        return null;
+    const log = [];
+    for (const e of rawLog) {
+        if (!isObj(e) || typeof e.t !== 'number' || !Number.isFinite(e.t) || e.t > 0 || e.t < -6 * 3600_000 || typeof e.pos !== 'number' || !(e.pos >= 0) || e.pos > 6 * 3600_000 || typeof e.play !== 'boolean')
+            return null;
+        log.push({ t: Math.round(e.t), pos: Math.round(e.pos), play: e.play });
+    }
+    return { bundle: v.bundle, watchedMs: Math.round(v.watchedMs), finished: v.finished, pauses, marks, log };
+}