cotutor 0.2.0 → 0.3.0

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 { logParser } 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 [];
+    }
+}
+/** runtime:这轮的运行时名(消息上记着),按它的 CLI 适配器读;不给按 stream-json */
+export async function readTranscript(ws, tutor, date, job, runtime) {
+    try {
+        return parseTranscript(await readFile(conversationFiles(ws.dirs.conversations, tutor, date).log(job), 'utf8'), logParser(ws.config.runtimes, runtime));
+    }
+    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), 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 };
+}
+/** 老师文件正文(系统提示),给 {agentBody} / {systemBody};从 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,195 @@
+/**
+ * 孩子端发一条的验与拼:HTTP 的 POST /api/kid/conversations/<老师>/messages 与实时老师那条线(src/runtime/live/call.ts)共用,
+ * 都经 Runner.accept 进来。验正文、话题、首页按钮、小课堂、activity、照片,拼成 Runner.send 的入参;不对回 reject(状态码 + 错误名),
+ * 怎么告诉孩子端由各自的协议定(HTTP 回 JSON,WS 回 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 };
+}

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

@@ -0,0 +1,124 @@
+import { type Bookkeeping, type ConversationMessage } from '../schema/index.ts';
+import { type CardAssets, type CardStates } from '../schema/index.ts';
+import type { BoardSection, KidDrawing, KidLecture } from '../board/presentation.ts';
+import type { Transcript } from '../brain/transcript.ts';
+export interface KidView {
+    /** 给孩子的话(讲稿各句,换行分隔);null = 这次运行没有(出错、还在跑、或最终文本剥完是空的) */
+    kidText: string | null;
+    truncated: boolean;
+    /** 记账任务的回答(「## 记账」段);应用按它写日记 */
+    bookkeeping: Bookkeeping | null;
+    /** 「## 记忆」段的条目;应用追加进 vault 的记忆文件 */
+    memory: string[];
+    /** 运行是否正常收尾 */
+    ok: boolean;
+    /** 板书节(卡 + 讲稿);没有卡也没有讲稿 = null */
+    section: BoardSection | null;
+    /** 解析时的提醒(卡没解析成等),家长视图转录里显示 */
+    warnings: string[];
+    /** 第一个 H2 起给家长的尾巴(老师写的任何标题段);没有 = 空串 */
+    parentText: string;
+}
+/** 按码点数截断;能在句末断就在句末断(不加省略号),否则硬截加 … */
+export declare function truncateReply(text: string, max: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * 孩子看的正文从哪来:`result.result` 只是这轮**最后一段**顶层文本——老师写完板书再用一次工具、再补一句,
+ * 板书和「## 记账」段就没了。所以正文 = 这轮里**带围栏(卡)或带 H2 固定段的顶层文本段** + **最后一段**(顺序不变,重复不算两次);
+ * 中间那些「我先看看账本」之类没卡没段的话不进。子代理的话本来就不在顶层。
+ */
+export declare function kidSource(t: Transcript): string | null;
+/** opts.live = 实时的一轮:解析器不补提问卡(src/board/parse.ts) */
+export declare function deriveKidView(t: Transcript, policy: {
+    replyMaxChars: number;
+}, opts?: {
+    live?: boolean;
+}): KidView;
+/** 孩子端的一条:自己问的话(别人问的不显示)+ 老师给孩子的话 + 配音;出错的运行什么都不出现(问句还在) */
+export interface KidMessage {
+    job: string;
+    /** 话题 id(话题第一条的 job) */
+    thread: string;
+    at: string;
+    /** 孩子自己说的;系统发的不给孩子看,为 null */
+    question: string | null;
+    /** 老师给孩子的话;还在跑或这轮没有 = null */
+    reply: string | null;
+    /** 老师还在想 */
+    pending: boolean;
+    /** 本次运行新增的产物 id */
+    artifacts: string[];
+    /** 板书节(卡 + 讲稿;答案等秘密已剥;配音在讲稿句上) */
+    section?: BoardSection | null;
+    /** 孩子这条带的作业照片(相对 workspace 根;页面经 /api/kid/image?p= 取);只在孩子自己的问句上 */
+    photos?: string[];
+    /** 这条是看完小课堂后的第一条:哪份课包、课名、画过的几处(节前的小课堂卡与画的卡从这里画);again = 再看一遍又画的那条,节前只画画的卡 */
+    lecture?: KidLecture;
+    /** 孩子从左栏的纸交的画:节前一张孩子的画卡 */
+    drawing?: KidDrawing;
+    /** 孩子的话怎么上板:交卡不写;首页按钮发的(正文就是按钮上的字)不写,从按钮进来后孩子自己说的照写 */
+    action?: 'submit';
+    fromHome?: true;
+    /** 这一轮是实时的:讲稿不配音、嘴照念;不出卡的一轮板上留讲稿的字,还在跑时有句就出节 */
+    live?: true;
+}
+/**
+ * 对话索引 → 孩子端条目(的机械过滤在服务端做):不带 result / error / 费用 / 家长尾巴;
+ * 卡上的答案剥掉,孩子自己做的状态(states)与已生成的资产(assets,都从 .cards/ 读)并到卡上。出错的运行:没有 question 的直接不出现;有 question 的只留问句(老师头像不灰,下一条照常)。
+ */
+export declare function kidConversation(index: {
+    messages: readonly ConversationMessage[];
+}, states?: CardStates, assets?: CardAssets): KidMessage[];
+/**
+ * 家长板书页的一条:形状同 KidMessage,家长多看到的都是可选字段;
+ * `section` **不剥答案**;`question` 不管谁发的都给;记账 / 整理记忆那两种轮也在(旁注写「已记进日记」「整理了记忆」)。
+ */
+export interface ParentMessage extends KidMessage {
+    from: ConversationMessage['from'];
+    via?: ConversationMessage['via'];
+    action?: ConversationMessage['action'];
+    /** 这条带给老师的卡(上一轮之后孩子改过状态的):「孩子在板书上做的」;took = 在弹窗里想了多久(毫秒,没改过 = null)、改过几次(有实录才有,app.ts parentDay 挂上) */
+    cards?: (NonNullable<ConversationMessage['cards']>[number] & {
+        took?: {
+            think: number | null;
+            changes: number;
+        };
+    })[];
+    parentText?: string;
+    remembered?: string[];
+    warnings?: string[];
+    /** 不 ok 时的原因;孩子端什么都不出现,家长页出一行 */
+    error?: string;
+    bookkeep?: ConversationMessage['bookkeep'];
+    tidy?: true;
+    /** 家长端多看到看的情况:看了多久、看完没、停过几次 */
+    lectureWatch?: Pick<NonNullable<ConversationMessage['lecture']>, 'watchedMs' | 'finished' | 'pauses'>;
+}
+/** 对话索引 → 家长板书页条目:和 kidConversation 同一个循环,差集恰好是 ParentMessage 里多出的字段与「答案不剥」 */
+export declare function parentConversation(index: {
+    messages: readonly ConversationMessage[];
+}, states?: CardStates, assets?: CardAssets): ParentMessage[];
+export interface KidThread {
+    thread: string;
+    /** 话题第一条的时间 */
+    at: string;
+    /** 话题名:孩子的第一句话截 20 字;没有孩子的话 → 「老师主动说的」 */
+    title: string;
+    /** 老师讲了几节 */
+    sections: number;
+    /** 一共几张卡 */
+    cards: number;
+}
+/**
+ * 「以前的」列表:一天的孩子端条目按话题分组。一句孩子的话都没有的话题不列;还在跑的、出错的轮不算节。
+ */
+export declare function kidThreads(messages: readonly KidMessage[]): KidThread[];
+/**
+ * 今天交给老师过的卡(`<job>/<n>`):交答案那条的 focus.card。交过的卡锁住——不能改、不能再交(2026-10-21,Jack:
+ * 孩子改了交过的卡的答案又交一次,老师再答一遍,孩子糊涂)。
+ */
+export declare function submittedCards(index: {
+    messages: readonly ConversationMessage[];
+}): Set<string>;