cotutor 0.1.0 → 0.3.0

package/dist/app/http/dev-tutor-files.d.ts

@@ -0,0 +1,80 @@
+import { type TutorState } from '../cli/tutors.ts';
+import type { Workspace } from '../../schema/index.ts';
+import { type AgentFileIssue } from '../../runtime/agent-file.ts';
+import { type DiffHunk } from './dev-activities.ts';
+/** 列表上这一行叫什么:有脸的老师是「新话题」(孩子点的那颗),工具人没有新话题按钮,叫「老师文件」 */
+export declare const tutorFileLabel: (tutor: string) => string;
+export type TutorFileState = TutorState | 'own';
+export interface DevTutorFileRow {
+    kind: 'tutor';
+    tutor: string;
+    name: string;
+    description: string;
+    state: TutorFileState;
+    basedOn?: string;
+    fixes: number;
+    notes: number;
+    /** 孩子端首页上照它带的按钮几个(新话题 + 开场按钮) */
+    buttons: number;
+}
+export declare function listDevTutorFiles(ws: Workspace): Promise<DevTutorFileRow[]>;
+/** 这位老师在 cotutor.json 里、文件读得到 */
+export declare function hasDevTutorFile(ws: Workspace, tutor: string): Promise<boolean>;
+export declare function readDevTutorFile(ws: Workspace, tutor: string): Promise<{
+    kind: 'tutor';
+    tutor: string;
+    name: string;
+    path: string;
+    text: string;
+    hash: string;
+    state: TutorFileState;
+    basedOn?: string;
+    shipped: boolean;
+    examples: number;
+}>;
+/** 节:frontmatter 一节给 CLI,正文开头与每个 ## 给老师(系统提示);围栏里的 ## 不算 */
+export declare function tutorFileSections(text: string): {
+    title: string;
+    reader: string;
+    line: number;
+}[];
+export interface DevTutorFileCheck {
+    issues: AgentFileIssue[];
+    sections: {
+        title: string;
+        reader: string;
+        line: number;
+    }[];
+    buttons: {
+        label: string;
+        kind: 'new' | 'start';
+    }[];
+    /** 老师在一个新话题里收到什么:系统提示 = 正文(+ 板书写法);话题第一条带守则(机器件,这里不改) */
+    preview: {
+        text: string;
+        chars: number;
+        board: {
+            chars: number;
+            cards: string[];
+        } | null;
+        rules: {
+            path: string;
+            text: string;
+            chars: number;
+        } | null;
+    };
+    diff: DiffHunk[] | null;
+}
+export declare function checkDevTutorFile(ws: Workspace, tutor: string, text: string): Promise<DevTutorFileCheck>;
+/**
+ * 存:磁盘上那份的 hash 要还是 base(读进来时的),不然不存(ActivityConflict);检查有「要改」的不存(UsageError):
+ * 老师文件写坏了这位老师整个起不来,不像 activity 有首页护栏兜着。先写 .tmp 再 rename
+ */
+export declare function saveDevTutorFile(ws: Workspace, tutor: string, text: string, base: string): Promise<{
+    hash: string;
+    state: TutorFileState;
+    fixes: number;
+}>;
+export declare function restoreDevTutorFile(ws: Workspace, tutor: string): Promise<{
+    bak: string | null;
+}>;

package/dist/app/http/dev-tutor-files.js

@@ -0,0 +1,151 @@
+/**
+ * 工作台改老师文件:「新话题」照的提示词。和 activity 同一个编辑器、同一套规矩——
+ * 读、边改边查(不落盘:检查、老师收到什么、和出厂比)、存(带读进来时的 hash,磁盘上的变了就不存)、恢复出厂(原文留 .bak)。
+ * 老师文件是 agents/<老师>.md:frontmatter 给 CLI,正文就是不走 activity 的话题里老师的系统提示(新话题、开场按钮、隔天接着一个不是 activity 的话题)。
+ * 只认 cotutor.json 里有的老师;和老师团页的 /api/tutors/<老师>/file 是同一份文件,那条路不带 hash,这里带。
+ */
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { restoreTutor, sha256, shippedTutorText, tutorFile, tutorStatuses } from "../cli/tutors.js";
+import { UsageError } from "../../shared/errors.js";
+import { lintAgentFile, parseAgentFile } from "../../runtime/agent-file.js";
+import { TUTOR_RULES_PATH, takesTutorRules, tutorRulesBody } from "../../runtime/context/tutor-rules.js";
+import { tutorCardKinds } from "../../board/cards/index.js";
+import { resolvePolicy } from "../../schema/index.js";
+import { readPublished } from "../../runtime/home/store.js";
+import { boardGuideOf } from "../../runtime/runner.js";
+import { ActivityConflict, diffHunks } from "./dev-activities.js";
+/** 列表上这一行叫什么:有脸的老师是「新话题」(孩子点的那颗),工具人没有新话题按钮,叫「老师文件」 */
+export const tutorFileLabel = (tutor) => (takesTutorRules(tutor) ? '新话题' : '老师文件');
+const fileOf = (ws, tutor) => tutorFile(ws.root, tutor);
+async function stateOf(ws, tutor) {
+    const st = (await tutorStatuses(ws.root)).find((s) => s.name === tutor);
+    if (!st)
+        return { state: 'own' };
+    return { state: st.state, ...(st.basedOn ? { basedOn: st.basedOn } : {}) };
+}
+/** 孩子端首页上照老师文件带的按钮:新话题(永远第一个)+ 开场按钮;没发布过首页就是缺省首页(孩子端露的老师一张只有新话题的卡) */
+async function homeButtons(ws, tutor) {
+    if (!takesTutorRules(tutor))
+        return [];
+    const { home } = await readPublished(ws);
+    const t = ws.config.tutors[tutor];
+    if (!home)
+        return t?.enabled && !t.hidden ? [{ label: '新话题', kind: 'new' }] : [];
+    const card = home.cards.find((c) => c.kind === 'tutor' && c.props.tutor === tutor);
+    if (!card)
+        return [];
+    return [{ label: '新话题', kind: 'new' }, ...(card.props.buttons ?? []).filter((b) => b.kind === 'start').map((b) => ({ label: b.label, kind: 'start' }))];
+}
+export async function listDevTutorFiles(ws) {
+    const rows = [];
+    for (const tutor of Object.keys(ws.config.tutors)) {
+        const text = await readFile(fileOf(ws, tutor), 'utf8').catch(() => null);
+        if (text === null)
+            continue;
+        const issues = lintAgentFile(text, tutor);
+        rows.push({
+            kind: 'tutor',
+            tutor,
+            name: tutorFileLabel(tutor),
+            description: parseAgentFile(text).frontmatter.description ?? '',
+            ...(await stateOf(ws, tutor)),
+            fixes: issues.filter((i) => i.level === 'fix').length,
+            notes: issues.filter((i) => i.level === 'note').length,
+            buttons: (await homeButtons(ws, tutor)).length,
+        });
+    }
+    return rows;
+}
+/** 这位老师在 cotutor.json 里、文件读得到 */
+export async function hasDevTutorFile(ws, tutor) {
+    return Boolean(ws.config.tutors[tutor]) && (await readFile(fileOf(ws, tutor), 'utf8').then(() => true, () => false));
+}
+export async function readDevTutorFile(ws, tutor) {
+    const file = fileOf(ws, tutor);
+    const text = await readFile(file, 'utf8');
+    return {
+        kind: 'tutor',
+        tutor,
+        name: tutorFileLabel(tutor),
+        path: relative(ws.root, file).split(sep).join('/'),
+        text,
+        hash: sha256(text),
+        ...(await stateOf(ws, tutor)),
+        shipped: (await shippedTutorText(tutor, ws.root)) !== null,
+        examples: 0,
+    };
+}
+/** 节:frontmatter 一节给 CLI,正文开头与每个 ## 给老师(系统提示);围栏里的 ## 不算 */
+export function tutorFileSections(text) {
+    const lines = text.split('\n');
+    const out = [];
+    let bodyAt = 1;
+    if (/^---[^\S\n]*$/.test(lines[0] ?? '')) {
+        const end = lines.findIndex((l, i) => i > 0 && /^---[^\S\n]*$/.test(l));
+        if (end > 0) {
+            out.push({ title: '头', reader: 'CLI 认的 name · description', line: 1 });
+            bodyAt = end + 2;
+        }
+    }
+    while (bodyAt <= lines.length && !lines[bodyAt - 1].trim())
+        bodyAt++;
+    out.push({ title: '开头', reader: '老师的系统提示', line: Math.min(bodyAt, lines.length) });
+    let fence = false;
+    lines.forEach((l, i) => {
+        if (/^`{3,}/.test(l))
+            fence = !fence;
+        const m = !fence && i + 1 > bodyAt && /^##[ \t]+(.+?)[ \t]*$/.exec(l);
+        if (m)
+            out.push({ title: m[1], reader: '老师的系统提示', line: i + 1 });
+    });
+    return out;
+}
+const charsOf = (s) => [...s].length;
+export async function checkDevTutorFile(ws, tutor, text) {
+    const body = parseAgentFile(text).body;
+    const faced = takesTutorRules(tutor);
+    const kinds = tutorCardKinds(ws.config.tutors[tutor]?.cards);
+    const guide = faced && resolvePolicy(ws.config, tutor).board !== 'off' ? await boardGuideOf(ws, tutor) : null;
+    let rules = null;
+    if (faced) {
+        const md = await readFile(join(ws.root, TUTOR_RULES_PATH), 'utf8').catch(() => null);
+        if (md !== null) {
+            const r = tutorRulesBody(md, kinds ?? undefined);
+            rules = { path: TUTOR_RULES_PATH, text: r, chars: charsOf(r) };
+        }
+    }
+    const shipped = await shippedTutorText(tutor, ws.root);
+    return {
+        issues: lintAgentFile(text, tutor),
+        sections: tutorFileSections(text),
+        buttons: await homeButtons(ws, tutor),
+        preview: {
+            text: body,
+            chars: charsOf(body),
+            board: guide ? { chars: charsOf(guide.body), cards: kinds ? [...kinds] : [] } : null,
+            rules,
+        },
+        diff: shipped === null ? null : diffHunks(shipped, text),
+    };
+}
+/**
+ * 存:磁盘上那份的 hash 要还是 base(读进来时的),不然不存(ActivityConflict);检查有「要改」的不存(UsageError):
+ * 老师文件写坏了这位老师整个起不来,不像 activity 有首页护栏兜着。先写 .tmp 再 rename
+ */
+export async function saveDevTutorFile(ws, tutor, text, base) {
+    const fixes = lintAgentFile(text, tutor).filter((i) => i.level === 'fix');
+    if (fixes.length)
+        throw new UsageError(`老师文件还有 ${fixes.length} 处要改,改好才能存:${fixes.map((i) => i.text).join(';')}`);
+    const file = fileOf(ws, tutor);
+    const disk = await readFile(file, 'utf8');
+    if (sha256(disk) !== base)
+        throw new ActivityConflict(sha256(disk));
+    await writeFile(`${file}.tmp`, text);
+    await rename(`${file}.tmp`, file);
+    return { hash: sha256(text), ...(await stateOf(ws, tutor)), fixes: 0 };
+}
+export async function restoreDevTutorFile(ws, tutor) {
+    const r = await restoreTutor(ws.root, tutor);
+    return { bak: r.bak ? relative(ws.root, r.bak).split(sep).join('/') : null };
+}

package/dist/app/http/parent-home.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 家长端「首页」:家长在 iPad / 手机上设孩子的首页。
+ * 按钮与听写的词改的是已发布那份首页的原文(editPublished:检查、留历史、发布);开关与几项常改的设置写回 cotutor.json(patchConfig)。
+ * 页面每次现读,不缓存:家长也可能同时在编辑器里改 cotutor.json、在编程助手里发布首页。
+ *
+ *   GET   /api/parent/home                          老师们(按首页的先后)、各自的按钮(带讲法)、听写的词、常驻入口;口语课与孩子端的几项设置
+ *   PUT   /api/parent/home/tutors/<老师>/buttons     {buttons: [{kind, label, brief?, until?, date?, thread?, bundle?}]} 换掉这位老师的按钮
+ *   PUT   /api/parent/home/tutors/<老师>/dictation   {words: [{chars, say?}]} 这周的词;[] = 删掉
+ *   PUT   /api/parent/home/order                    {tutors: [老师…]} 老师的先后(排第一的进首页时在最前)
+ *   PATCH /api/parent/settings                      {tutors?: {<老师>: {extras?: [..] | null, hidden?}}, talk?: {note?, minutes?}}
+ */
+import { type DictationLang, type TutorButton } from '../../board/cards/index.ts';
+import type { AppContext, RouteResult } from './app.ts';
+export interface ParentHomeTutor {
+    name: string;
+    display: string;
+    avatar: string | null;
+    subject: string | null;
+    hidden: boolean;
+    /** 卡上的常驻入口(按学科补过缺省的);extrasSet = cotutor.json 里写的(没写 = null,走缺省) */
+    extras: string[];
+    extrasSet: string[] | null;
+    /** 首页里这位老师的按钮(文件里的,带讲法与留到) */
+    buttons: TutorButton[];
+    /** 这周的词:写了这位老师的听写卡;没有 = null */
+    dictation: {
+        chars: string;
+        say?: string;
+        emoji?: string;
+    }[] | null;
+    /** 他的听写是哪种:学科是英语(含别名)= en(英文单词),别的 zh */
+    lang: DictationLang;
+    /** 学科色(src/ui/shared/tutor-color.ts) */
+    color: string;
+}
+export declare function parentHome(ctx: AppContext): Promise<Record<string, unknown>>;
+export declare function parentHomeRoute(method: string, p: string, ctx: AppContext, body: unknown): Promise<RouteResult | null>;

package/dist/app/http/parent-home.js

@@ -0,0 +1,203 @@
+/**
+ * 家长端「首页」:家长在 iPad / 手机上设孩子的首页。
+ * 按钮与听写的词改的是已发布那份首页的原文(editPublished:检查、留历史、发布);开关与几项常改的设置写回 cotutor.json(patchConfig)。
+ * 页面每次现读,不缓存:家长也可能同时在编辑器里改 cotutor.json、在编程助手里发布首页。
+ *
+ *   GET   /api/parent/home                          老师们(按首页的先后)、各自的按钮(带讲法)、听写的词、常驻入口;口语课与孩子端的几项设置
+ *   PUT   /api/parent/home/tutors/<老师>/buttons     {buttons: [{kind, label, brief?, until?, date?, thread?, bundle?}]} 换掉这位老师的按钮
+ *   PUT   /api/parent/home/tutors/<老师>/dictation   {words: [{chars, say?}]} 这周的词;[] = 删掉
+ *   PUT   /api/parent/home/order                    {tutors: [老师…]} 老师的先后(排第一的进首页时在最前)
+ *   PATCH /api/parent/settings                      {tutors?: {<老师>: {extras?: [..] | null, hidden?}}, talk?: {note?, minutes?}}
+ */
+import { DICTATION_EN_MAX, DICTATION_WORD_MAX, DICTATION_WORDS_MAX, TUTOR_BUTTONS_MAX, TutorButtonSchema, dictationWordLang } from "../../board/cards/index.js";
+import { localDate } from "../../shared/time.js";
+import { orderTutors, setTutorButtons, setTutorDictation } from "../../runtime/home/edit.js";
+import { AGENT_NAME_RE, TUTOR_EXTRAS, subjectLang, tutorExtras } from "../../schema/index.js";
+import { editPublished, readPublished } from "../../runtime/home/store.js";
+import { patchConfig } from "../workspace.js";
+import { tutorColors } from "../../ui/shared/tutor-color.js";
+import { wordEmoji } from "../../ui/kid/word-emoji.js";
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const bad = (message) => ({ status: 400, json: { error: 'bad_request', message } });
+/** 家长端列的老师:有脸的(-tutor 结尾)、开着的;藏着的也列(家长要能把他放回首页) */
+const faceTutors = (c) => Object.entries(c.tutors).filter(([n, t]) => n.endsWith('-tutor') && t.enabled).map(([n]) => n);
+export async function parentHome(ctx) {
+    const c = ctx.ws.config;
+    const { home } = await readPublished(ctx.ws);
+    const cards = home?.cards ?? [];
+    const names = faceTutors(c);
+    const colors = tutorColors(c.tutors);
+    // 先后 = 首页里老师卡的先后,没写卡的照 cotutor.json 的顺序排在后面
+    const written = cards.filter((x) => x.kind === 'tutor').map((x) => String(x.props.tutor)).filter((n, i, a) => names.includes(n) && a.indexOf(n) === i);
+    const order = [...written, ...names.filter((n) => !written.includes(n))];
+    const tutors = order.map((name) => {
+        const t = c.tutors[name];
+        const card = cards.find((x) => x.kind === 'tutor' && x.props.tutor === name);
+        const dict = cards.find((x) => x.kind === 'dictation' && x.props.tutor === name);
+        return {
+            name,
+            display: t.display,
+            avatar: t.avatar ?? null,
+            subject: t.subject ?? null,
+            hidden: t.hidden,
+            extras: tutorExtras(t, c.talk.enabled),
+            extrasSet: t.extras ?? null,
+            buttons: (card?.props.buttons ?? []),
+            dictation: dict ? (dict.props.words ?? []) : null,
+            lang: subjectLang(t.subject),
+            color: colors[name],
+        };
+    });
+    return {
+        title: c.title,
+        kid: c.kid.name ?? '',
+        today: localDate(ctx.now()),
+        home: home ? { id: home.id, publishedAt: home.publishedAt } : null,
+        tutors,
+        talk: { enabled: c.talk.enabled, note: c.talk.note ?? '', minutes: c.talk.minutes },
+        extrasAll: TUTOR_EXTRAS,
+    };
+}
+/** 表单交来的按钮:形状照老师卡的协议;最多 TUTOR_BUTTONS_MAX 个 */
+function parseButtons(v) {
+    if (!Array.isArray(v))
+        return '要 {buttons: [...]}';
+    if (v.length > TUTOR_BUTTONS_MAX)
+        return `按钮最多 ${TUTOR_BUTTONS_MAX} 个(「新话题」不算)`;
+    const out = [];
+    for (const b of v) {
+        const r = TutorButtonSchema.safeParse(isObj(b) ? Object.fromEntries(Object.entries(b).filter(([, x]) => x !== '' && x !== null)) : b);
+        if (!r.success)
+            return `按钮不对:${r.error.issues.map((i) => `${i.path.join('.')} ${i.message}`).join(';')}`;
+        if (/\n/.test(r.data.label))
+            return '按钮的字只写一行';
+        out.push(r.data);
+    }
+    return out;
+}
+/** 这周的词:语文老师一到四个汉字;英语老师(学科「英语」)一个英文单词 */
+function parseWords(v, lang) {
+    if (!Array.isArray(v))
+        return '要 {words: [{chars, say?}]}';
+    if (v.length > DICTATION_WORDS_MAX)
+        return `一次最多 ${DICTATION_WORDS_MAX} 个词`;
+    const out = [];
+    for (const w of v) {
+        if (!isObj(w) || typeof w.chars !== 'string')
+            return '每个词要 {chars, say?}';
+        const chars = lang === 'en' ? w.chars.trim() : w.chars.replace(/\s+/g, '');
+        if (dictationWordLang(chars) !== lang)
+            return lang === 'en' ? `「${w.chars}」:一行一个英文单词(只要字母,最多 ${DICTATION_EN_MAX} 个)` : `「${w.chars}」:一个词一到 ${DICTATION_WORD_MAX} 个汉字`;
+        const say = typeof w.say === 'string' ? w.say.replace(/\s+/g, ' ').trim() : '';
+        out.push({ chars, ...(say ? { say } : {}) });
+    }
+    return out;
+}
+/**
+ * 英文单词配 emoji(只在对一对时出):已发布的那张卡上同一个单词配过的照用,剩下的问一次 qwen3.8-flash;问不到就不配。
+ * COTUTOR_EMOJI_ENDPOINT:测试与探针指到假的千问
+ */
+async function withEmoji(ctx, name, words) {
+    const { home } = await readPublished(ctx.ws);
+    const had = new Map();
+    for (const c of home?.cards ?? [])
+        if (c.kind === 'dictation' && c.props.tutor === name)
+            for (const w of (c.props.words ?? []))
+                if (w.emoji)
+                    had.set(w.chars, w.emoji);
+    const ask = [...new Set(words.map((w) => w.chars).filter((w) => !had.has(w)))];
+    const fake = process.env.COTUTOR_EMOJI_ENDPOINT;
+    const got = ask.length ? await wordEmoji(ask, fake ? { endpoint: fake, env: { DASHSCOPE_API_KEY: 'sk-fake' } } : {}) : {};
+    return words.map((w) => { const e = had.get(w.chars) ?? got[w.chars]; return e ? { ...w, emoji: e } : w; });
+}
+/** 发布的结果:有「要改」的不发,把检查说的回给页面 */
+function published(r) {
+    if (r && !r.ok)
+        return { status: 400, json: { error: 'home_check', message: r.check.issues.filter((i) => i.level === 'fix').map((i) => i.text).join(';') || '首页检查没过' } };
+    return { status: 200, json: { ok: true, home: r?.home ? { id: r.home.id, publishedAt: r.home.publishedAt } : null, changed: Boolean(r) } };
+}
+export async function parentHomeRoute(method, p, ctx, body) {
+    if (p === '/api/parent/home' && method === 'GET')
+        return { status: 200, json: await parentHome(ctx) };
+    const names = faceTutors(ctx.ws.config);
+    const tb = /^\/api\/parent\/home\/tutors\/([^/]+)\/(buttons|dictation)$/.exec(p);
+    if (tb) {
+        if (method !== 'PUT')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        const name = decodeURIComponent(tb[1]);
+        if (!names.includes(name))
+            return { status: 404, json: { error: 'no_such_tutor' } };
+        const b = isObj(body) ? body : {};
+        if (tb[2] === 'buttons') {
+            const buttons = parseButtons(b.buttons);
+            if (typeof buttons === 'string')
+                return bad(buttons);
+            return published(await editPublished(ctx.ws, (md) => setTutorButtons(md, name, buttons), ctx.now()));
+        }
+        const lang = subjectLang(ctx.ws.config.tutors[name].subject);
+        const parsed = parseWords(b.words, lang);
+        if (typeof parsed === 'string')
+            return bad(parsed);
+        const words = lang === 'en' ? await withEmoji(ctx, name, parsed) : parsed;
+        return published(await editPublished(ctx.ws, (md) => setTutorDictation(md, name, words), ctx.now()));
+    }
+    if (p === '/api/parent/home/order') {
+        if (method !== 'PUT')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        const list = isObj(body) && Array.isArray(body.tutors) ? body.tutors : null;
+        if (!list || list.some((n) => typeof n !== 'string' || !names.includes(n)))
+            return bad('要 {tutors: [老师…]}(cotutor.json 里开着的、-tutor 结尾的)');
+        return published(await editPublished(ctx.ws, (md) => orderTutors(md, list), ctx.now()));
+    }
+    if (p === '/api/parent/settings') {
+        if (method !== 'PATCH')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        if (!isObj(body))
+            return bad('要一个 JSON 对象');
+        const patch = {};
+        if (body.tutors !== undefined) {
+            if (!isObj(body.tutors))
+                return bad('tutors 要 {<老师>: {extras?, hidden?}}');
+            const tp = {};
+            for (const [name, v] of Object.entries(body.tutors)) {
+                if (!names.includes(name) || !AGENT_NAME_RE.test(name) || !isObj(v))
+                    return bad(`没有这位老师:${name}`);
+                const one = {};
+                if (v.extras !== undefined) {
+                    if (v.extras !== null && (!Array.isArray(v.extras) || v.extras.some((x) => !TUTOR_EXTRAS.includes(x))))
+                        return bad(`extras 只认 ${TUTOR_EXTRAS.join(' / ')}(null = 按学科的缺省)`);
+                    one.extras = v.extras;
+                }
+                if (v.hidden !== undefined) {
+                    if (typeof v.hidden !== 'boolean')
+                        return bad('hidden 要 true / false');
+                    one.hidden = v.hidden;
+                }
+                tp[name] = one;
+            }
+            patch.tutors = tp;
+        }
+        if (body.talk !== undefined) {
+            if (!isObj(body.talk))
+                return bad('talk 要 {note?, minutes?}');
+            const t = {};
+            if (body.talk.note !== undefined) {
+                if (typeof body.talk.note !== 'string')
+                    return bad('talk.note 要一段字');
+                t.note = body.talk.note.trim() ? body.talk.note.trim() : null;
+            }
+            if (body.talk.minutes !== undefined)
+                t.minutes = body.talk.minutes;
+            patch.talk = t;
+        }
+        try {
+            await patchConfig(ctx.ws, patch, { also: ['talk'] });
+        }
+        catch (err) {
+            return bad(err instanceof Error ? err.message : String(err));
+        }
+        await ctx.reload();
+        return { status: 200, json: await parentHome(ctx) };
+    }
+    return null;
+}

package/dist/app/http/range.d.ts

@@ -0,0 +1,9 @@
+/**
+ * HTTP 分段取(Range,RFC 9110 §14):iPad Safari 放视频一定先要 bytes=0-1,拿不到 206 就不放(小课堂的视频)。
+ * 只认单段 `bytes=a-b` / `bytes=a-` / `bytes=-n`;多段、写坏的、b < a 的当没给(回整份 200,规范允许);起点越过文件尾 → 416。
+ */
+export type ByteRange = {
+    start: number;
+    end: number;
+} | 'unsatisfiable' | null;
+export declare function parseRange(header: string | undefined, size: number): ByteRange;

package/dist/app/http/range.js

@@ -0,0 +1,19 @@
+export function parseRange(header, size) {
+    if (!header)
+        return null;
+    const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!m || (m[1] === '' && m[2] === ''))
+        return null;
+    if (m[1] === '') {
+        // 末尾 n 字节
+        const n = Number(m[2]);
+        if (n === 0 || size === 0)
+            return 'unsatisfiable';
+        return { start: Math.max(0, size - n), end: size - 1 };
+    }
+    const start = Number(m[1]);
+    if (start >= size)
+        return 'unsatisfiable';
+    const end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1);
+    return end < start ? null : { start, end };
+}

package/dist/app/http/raw-view.d.ts

@@ -0,0 +1,117 @@
+import { type BoardWarning, type SourceRow } from '../../board/parse.ts';
+import type { BoardSection } from '../../board/presentation.ts';
+import { type ToolCall, type TranscriptRow } from '../../brain/transcript.ts';
+import { type ToolKind } from '../../brain/index.ts';
+import { type ConversationMessage } from '../../schema/index.ts';
+import type { Workspace } from '../../schema/index.ts';
+import { type RunSources } from '../../runtime/journal/store.ts';
+import { type TimelineSpan } from '../../runtime/journal/events.ts';
+import { type RunEvent } from '../../schema/index.ts';
+export interface RawStation {
+    id: 'pack' | 'timeline' | 'source' | 'parse' | 'kid' | 'tools' | 'trace' | 'ledger';
+    title: string;
+    /** 体量那行小字 */
+    note: string;
+    state: 'ok' | 'warn' | 'none';
+}
+export interface DiffRow {
+    s: '+' | '-' | '·';
+    text: string;
+}
+export interface RawKidLine {
+    text: string;
+    /** 按 replyMaxChars 截掉的尾巴(孩子看不到、也不念);没截就是空串 */
+    cut: string;
+}
+export interface RawCard {
+    n: number;
+    kind: string;
+    label: string;
+    /** 孩子在这张卡上做的(describeCard 出的那句);没动过 = null */
+    state: string | null;
+    /** 已生成的资产(点读段 mp3) */
+    assets: string[];
+    /** 下发给孩子的 props(答案已剥) */
+    props: Record<string, unknown>;
+}
+export interface RawView {
+    tutor: string;
+    date: string;
+    job: string;
+    thread: string | null;
+    at: string;
+    from: string;
+    text: string;
+    result: string;
+    runtime: string | null;
+    tokens: ConversationMessage['tokens'] | null;
+    timing: ConversationMessage['timing'] | null;
+    error: string | null;
+    stations: RawStation[];
+    /** 发出去的:上下文包 + 完整命令行(老 workspace 没落过就是 null) */
+    pack: {
+        prompt: string;
+        argv: string[];
+        runtime: string;
+        resume: boolean;
+        session: string | null;
+        agentBody: boolean;
+        sources: RunSources | null;
+    } | null;
+    /** 老师原文(= 解析器真正吃的那一份)+ 逐行注解 */
+    source: {
+        text: string;
+        rows: SourceRow[];
+        warnings: BoardWarning[];
+    };
+    /** 顶层文本块里没进板书正文的那些(「我先看看账本」之类) */
+    dropped: string[];
+    /** 索引里存着的(当时那版解析器的结果) */
+    stored: {
+        section: BoardSection | null;
+        warnings: string[];
+        kidText: string | null;
+        parentText: string;
+    };
+    /** 拿当前解析器重解一遍 + 与 stored 的差异 */
+    fresh: {
+        section: BoardSection;
+        warnings: BoardWarning[];
+        diff: DiffRow[];
+        same: boolean;
+    };
+    kid: {
+        lines: RawKidLine[];
+        cards: RawCard[];
+    };
+    /** 转录(工具行、子代理),与家长视图同一套折叠 */
+    trace: TranscriptRow[];
+    /** 这轮用了哪些工具、读了什么(索引物化的;老轮次从 .log 现抽);kind 是工具的类别(src/brain/cli/,页面按它认「读了几个文件」,不比工具名) */
+    tools: (ToolCall & {
+        kind: ToolKind;
+    })[];
+    /** 时间线:这轮的事件(<日期>.<job>.events.jsonl;2026-09-13 之前的轮次没有 → 空)+ 甘特的段 + 控制台那种一行一条 */
+    events: RunEvent[];
+    /** from = 最早一条的 t(嘴这一道在老师进程起来之前,负的;没有就是 0);total = 最晚一条 */
+    timeline: {
+        spans: TimelineSpan[];
+        lines: string[];
+        total: number;
+        from: number;
+    };
+    device: string | null;
+    /** stderr 尾巴 */
+    err: string;
+    files: {
+        log: string;
+        run: string | null;
+    };
+}
+/** 卡与讲稿逐条比:同序对齐,不同就一减一加。给「改完解析器,老样本会不会变」用 */
+export declare function diffSections(stored: BoardSection | null, fresh: BoardSection): DiffRow[];
+export declare function rawView(ws: Workspace, tutor: string, date: string, job: string): Promise<RawView | null>;
+/** 「存成 fixture」:原文原样一份,文件名按 job;家长端下载,开发者放进 tests/fixtures/board/ */
+export declare function fixtureOf(view: RawView): {
+    name: string;
+    text: string;
+};