cotutor 0.1.0 → 0.2.0

package/dist/lib/kid-view.js

@@ -1,3 +1,11 @@
+/**
+ * 孩子视图(《cotutor契约草案.md》§4,2026-09-10 改板书):最终文本剥掉「待裁量」「转交」段后,正文就是板书——
+ * 普通段落是讲稿(一行一句),围栏是卡(src/lib/board.ts 解析);kidText = 讲稿各句拼起来(家长视图的「孩子看到」摘要),
+ * 每句按 replyMaxChars 截;第一个 H2 起是给家长的尾巴(parentText),孩子看不到。出错什么都不出现。机械规则,不靠模型判断。
+ * 正文取自 kidSource:带卡 / 带固定段的顶层文本段 + 最后一段(老师板书之后又用了工具也不丢)。
+ */
+import { stripSecrets } from "../cards/index.js";
+import { parseBoard } from "./board.js";
 import { parseSections } from "./sections.js";
 const SENTENCE_END = new Set(['。', '!', '!', '?', '?', ';', ';', '\n']);
 /** 以空行分段,取最后一个非空段(段内换行保留) */
@@ -24,15 +32,62 @@ export function truncateReply(text, max) {
         return { text: cps.slice(0, cut).join('').trim(), truncated: true };
     return { text: `${cps.slice(0, max).join('').trim()}…`, truncated: true };
 }
+const none = (ok, holdup = null, handoff = null) => ({ kidText: null, truncated: false, holdup, handoff, ok, section: null, warnings: [], parentText: '' });
+const FENCE_OR_H2 = /^\s*(?:```|~~~|## )/m;
+/**
+ * 孩子看的正文从哪来(2026-09-10 拍板,两次真跑的教训):`result.result` 只是这轮**最后一段**顶层文本——老师写完板书再用一次工具、再补一句,
+ * 板书和「## 转交」段就没了。所以正文 = 这轮里**带围栏(卡)或带 H2 固定段的顶层文本段** + **最后一段**(顺序不变,重复不算两次);
+ * 中间那些「我先看看账本」之类没卡没段的话不进。子代理的话本来就不在顶层。
+ */
+export function kidSource(t) {
+    if (!t.final?.text)
+        return null;
+    const last = t.final.text.trim();
+    const blocks = t.items.filter((i) => i.kind === 'text' && !i.sub).map((i) => i.text.trim());
+    const kept = blocks.filter((b) => b !== last && FENCE_OR_H2.test(b));
+    return [...kept, last].join('\n\n');
+}
 export function deriveKidView(t, policy) {
     if (!t.final)
-        return { kidText: null, truncated: false, holdup: null, handoff: null, ok: false };
+        return none(false);
     if (!t.final.ok || !t.final.text)
-        return { kidText: null, truncated: false, holdup: null, handoff: null, ok: t.final.ok };
-    const { body, holdup, handoff } = parseSections(t.final.text);
-    const last = lastParagraph(body);
-    if (!last)
-        return { kidText: null, truncated: false, holdup, handoff, ok: true };
-    const { text, truncated } = truncateReply(last, policy.replyMaxChars);
-    return { kidText: text, truncated, holdup, handoff, ok: true };
+        return none(t.final.ok);
+    const { body, holdup, handoff } = parseSections(kidSource(t) ?? t.final.text);
+    const board = parseBoard(body);
+    const { cards, lines } = board.section;
+    if (!cards.length && !lines.length)
+        return { ...none(true, holdup, handoff), warnings: board.warnings, parentText: board.tail };
+    let truncated = false;
+    const cut = lines.map((l) => {
+        const r = truncateReply(l.text, policy.replyMaxChars);
+        truncated = truncated || r.truncated;
+        return { ...l, text: r.text };
+    });
+    const section = { ...board.section, lines: cut };
+    const kidText = cut.map((l) => l.text).join('\n');
+    return { kidText: kidText || null, truncated, holdup, handoff, ok: true, section, warnings: board.warnings, parentText: board.tail };
+}
+/**
+ * 对话索引 → 孩子端条目(《契约草案.md》§4 的机械过滤在服务端做):不带 result / error / holdup / handoff / 费用 / 家长尾巴;
+ * 卡上的答案剥掉,孩子自己做的状态(states)与已生成的资产(assets,都从 .cards/ 读)并到卡上。出错的运行:没有 question 的直接不出现;有 question 的只留问句(老师头像不灰,下一条照常)。
+ */
+export function kidConversation(index, states = {}, assets = {}) {
+    const out = [];
+    for (const m of index.messages) {
+        const question = m.from === 'kid' ? m.text : null;
+        const reply = m.result === 'ok' ? (m.kidText ?? null) : null;
+        const pending = m.result === 'running';
+        if (question === null && reply === null && !pending)
+            continue;
+        const per = states[m.job];
+        const files = assets[m.job];
+        const withState = m.section && (per || files) ? { ...m.section, cards: m.section.cards.map((c, n) => ({ ...c, ...(per?.[n] ? { state: per[n].state } : {}), ...(files?.[n]?.length ? { assets: files[n] } : {}) })) } : m.section;
+        const section = m.result === 'ok' && withState ? stripSecrets(withState) : undefined;
+        out.push({ job: m.job, at: m.at, question, reply, audio: reply ? (m.audio ?? null) : null, pending, artifacts: reply ? [...m.artifacts] : [], ...(section ? { section } : {}) });
+    }
+    return out;
+}
+/** 今天孩子已发的条数(每日上限按它算;家长发的不算,「继续」不算,交答案算) */
+export function kidMessageCount(index) {
+    return index.messages.filter((m) => m.from === 'kid' && m.action !== 'continue').length;
 }

package/dist/lib/ledger.d.ts

@@ -19,3 +19,11 @@ export declare function mergeArtifacts(events: ArtifactEvent[]): {
 };
 /** o-YYYYMMDD-NNN,同日顺延 */
 export declare function nextObservationId(date: string, existing: Iterable<string>): string;
+/** 上下文包的 recent:未撤回、本学科(没配 subject 就全量)的最近 n 条,按日期与出现顺序,只带 date + claim */
+export declare function recentObservations(obs: Observation[], opts: {
+    subject?: string;
+    n: number;
+}): {
+    date: string;
+    claim: string;
+}[];

package/dist/lib/ledger.js

@@ -90,3 +90,11 @@ export function nextObservationId(date, existing) {
     }
     return `o-${day}-${String(n + 1).padStart(3, '0')}`;
 }
+/** 上下文包的 recent:未撤回、本学科(没配 subject 就全量)的最近 n 条,按日期与出现顺序,只带 date + claim */
+export function recentObservations(obs, opts) {
+    return obs
+        .filter((o) => !o.retracted && (!opts.subject || o.subject === opts.subject))
+        .sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0))
+        .slice(-opts.n)
+        .map((o) => ({ date: o.date, claim: o.claim }));
+}

package/dist/lib/plan.d.ts

@@ -10,3 +10,5 @@ export interface PlanParse {
 export declare function parsePlan(md: string): PlanParse;
 /** 抽「与这位老师相关的行」:H2 标题等于显示名(两侧空白不计),最多 limit 行 */
 export declare function planLinesFor(plan: Plan, display: string, limit: number): string[];
+/** ISO 周号 YYYY-Www(周一起,含 1 月 4 日的那周是第 1 周),计划文件按它命名 */
+export declare function isoWeek(d: Date): string;

package/dist/lib/plan.js

@@ -76,3 +76,12 @@ export function planLinesFor(plan, display, limit) {
             out.push(...s.lines);
     return out.slice(0, limit);
 }
+/** ISO 周号 YYYY-Www(周一起,含 1 月 4 日的那周是第 1 周),计划文件按它命名 */
+export function isoWeek(d) {
+    const t = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+    const day = t.getUTCDay() || 7;
+    t.setUTCDate(t.getUTCDate() + 4 - day);
+    const yearStart = Date.UTC(t.getUTCFullYear(), 0, 1);
+    const week = Math.ceil(((t.getTime() - yearStart) / 86400000 + 1) / 7);
+    return `${t.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}

package/dist/lib/run-plan.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 一次运行的命令规划(纯函数):按运行时选 run 还是 resume、填占位符、定 cwd 相对路径。
+ * 规则:当天索引里已有会话**且**是同一运行时跑出来的 → resume;否则新开(跨天索引本来就是新的,零点后第一条自然不带 --resume;
+ * 换了运行时也新开——claude 的会话 id qwen 不认)。{agentBody} 只给模板里真用到它的运行时读老师正文。
+ */
+import { type Runtime, type ConversationIndex, type CotutorConfig } from '../schema/index.ts';
+export interface RunPlan {
+    /** 运行时名(runtimes 里的键) */
+    runtime: string;
+    /** 完整命令行,argv[0] 是可执行文件 */
+    argv: string[];
+    /** 这次是 resume 还是新开 */
+    resume: boolean;
+    /** resume 的会话 id */
+    session: string | null;
+}
+export declare class RuntimeError extends Error {
+}
+export declare function getRuntime(config: CotutorConfig, name?: string): {
+    name: string;
+    runtime: Runtime;
+};
+/** 模板里有没有用到某个占位符(决定要不要去读老师正文) */
+export declare function runtimeUses(runtime: Runtime, placeholder: string): boolean;
+export declare function planRun(config: CotutorConfig, index: Pick<ConversationIndex, 'session'>, vars: {
+    agent: string;
+    prompt: string;
+    agentBody?: string;
+    runtime?: string;
+}): RunPlan;

package/dist/lib/run-plan.js

@@ -0,0 +1,32 @@
+/**
+ * 一次运行的命令规划(纯函数):按运行时选 run 还是 resume、填占位符、定 cwd 相对路径。
+ * 规则:当天索引里已有会话**且**是同一运行时跑出来的 → resume;否则新开(跨天索引本来就是新的,零点后第一条自然不带 --resume;
+ * 换了运行时也新开——claude 的会话 id qwen 不认)。{agentBody} 只给模板里真用到它的运行时读老师正文。
+ */
+import { fillRuntime } from "../schema/index.js";
+export class RuntimeError extends Error {
+}
+export function getRuntime(config, name) {
+    const n = name ?? config.runtimes.default;
+    const p = config.runtimes[n];
+    if (n === 'default' || !p || typeof p === 'string') {
+        const known = Object.keys(config.runtimes).filter((k) => k !== 'default');
+        throw new RuntimeError(`运行时 "${n}" 不存在;cotutor.json 的 runtimes 里有:${known.join('、')}`);
+    }
+    return { name: n, runtime: p };
+}
+/** 模板里有没有用到某个占位符(决定要不要去读老师正文) */
+export function runtimeUses(runtime, placeholder) {
+    return [...runtime.run, ...runtime.resume].some((a) => a.includes(placeholder));
+}
+export function planRun(config, index, vars) {
+    const { name, runtime } = getRuntime(config, vars.runtime);
+    const session = index.session && index.session.runtime === name ? index.session.id : null;
+    const template = session ? runtime.resume : runtime.run;
+    return {
+        runtime: name,
+        argv: fillRuntime(template, { agent: vars.agent, prompt: vars.prompt, session: session ?? undefined, agentBody: vars.agentBody }),
+        resume: session !== null,
+        session,
+    };
+}

package/dist/lib/stream.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 流式:老师还在说的时候,从 stream-json 的增量事件里拼出「当前这条顶层回复的正文」,给板书的 partial 解析用。
+ * claude 2.1.220 加 `--include-partial-messages` 后每个字来一条 `stream_event`(content_block_delta / text_delta),
+ * 每条新消息前有 message_start;qwen 0.21.13 没有增量开关,只有整条 `assistant` 事件——两种都认:
+ * delta 往当前文本上追加,message_start 时当前段带围栏或 H2 就留下(与 kid-view 的 kidSource 同一条规则:老师板书完再用工具,卡不丢)、否则丢掉,
+ * 新段从空开始;顶层 assistant 的 text 块直接当作当前段(与拼出来的一样)。text() = 留下的段 + 当前段。
+ * parent_tool_use_id 非空的(子代理)一律跳过;喂进来的是原始字节块,行没收完的先攒着。
+ */
+export interface PartialReader {
+    /** 喂一块 stdout;返回文本有没有变 */
+    feed(chunk: string): boolean;
+    /** 当前这条顶层回复的正文(还在长) */
+    text(): string;
+}
+export declare function createPartialReader(): PartialReader;

package/dist/lib/stream.js

@@ -0,0 +1,69 @@
+/**
+ * 流式:老师还在说的时候,从 stream-json 的增量事件里拼出「当前这条顶层回复的正文」,给板书的 partial 解析用。
+ * claude 2.1.220 加 `--include-partial-messages` 后每个字来一条 `stream_event`(content_block_delta / text_delta),
+ * 每条新消息前有 message_start;qwen 0.21.13 没有增量开关,只有整条 `assistant` 事件——两种都认:
+ * delta 往当前文本上追加,message_start 时当前段带围栏或 H2 就留下(与 kid-view 的 kidSource 同一条规则:老师板书完再用工具,卡不丢)、否则丢掉,
+ * 新段从空开始;顶层 assistant 的 text 块直接当作当前段(与拼出来的一样)。text() = 留下的段 + 当前段。
+ * parent_tool_use_id 非空的(子代理)一律跳过;喂进来的是原始字节块,行没收完的先攒着。
+ */
+const KEEP = /^\s*(?:```|~~~|## )/m;
+export function createPartialReader() {
+    let rest = '';
+    let text = '';
+    const kept = [];
+    const apply = (line) => {
+        if (!line.trim())
+            return false;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return false;
+        }
+        if (typeof e.parent_tool_use_id === 'string' && e.parent_tool_use_id)
+            return false;
+        if (e.type === 'stream_event') {
+            const ev = e.event;
+            if (ev?.type === 'message_start') {
+                if (!text)
+                    return false;
+                if (KEEP.test(text))
+                    kept.push(text.trim());
+                text = '';
+                return true;
+            }
+            if (ev?.type === 'content_block_delta' && ev.delta?.type === 'text_delta' && typeof ev.delta.text === 'string' && ev.delta.text) {
+                text += ev.delta.text;
+                return true;
+            }
+            return false;
+        }
+        if (e.type === 'assistant' && Array.isArray(e.message?.content)) {
+            const t = e.message.content
+                .filter((b) => b.type === 'text' && typeof b.text === 'string')
+                .map((b) => b.text)
+                .join('');
+            if (t && t !== text) {
+                text = t;
+                return true;
+            }
+        }
+        return false;
+    };
+    return {
+        feed(chunk) {
+            rest += chunk;
+            let changed = false;
+            let at;
+            while ((at = rest.indexOf('\n')) >= 0) {
+                const line = rest.slice(0, at);
+                rest = rest.slice(at + 1);
+                if (apply(line))
+                    changed = true;
+            }
+            return changed;
+        },
+        text: () => [...kept, text].filter(Boolean).join('\n\n'),
+    };
+}

package/dist/lib/timetable.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 课程表解析(抄自 growth-apps apps/web/src/timetable.ts,2026-09-09;孩子列改为可选)。
+ * 表头须含 星期/时间/学科 三列(孩子列可有可无,顺序不限,多余列忽略);可以有多张表;列名对不上的表整张跳过。
+ * 错误即修复指南,带行号;解析尽量往下走,一次报全。
+ */
+import type { TimetableEntry } from '../schema/index.ts';
+export interface TimetableParse {
+    entries: TimetableEntry[];
+    /** 没找到任何课程表时 entries 为空且这里有整体指南 */
+    errors: string[];
+    found: boolean;
+}
+export declare function dayName(day: number): string;
+export declare function parseTimetable(md: string): TimetableParse;
+/** js Date → 1–7(周一–周日) */
+export declare function dayOf(now: Date): number;
+/** 本周(周一起算)第 day 天的日期 YYYY-MM-DD */
+export declare function weekDate(now: Date, day: number): string;
+/** 当前正在进行的时段(第一条命中;不在任何时段 = null,不猜) */
+export declare function currentSlot(entries: readonly TimetableEntry[], now: Date): TimetableEntry | null;
+/** 上下文包的 slot 字段:「数学 16:00-17:00」 */
+export declare function slotLabel(e: TimetableEntry): string;

package/dist/lib/timetable.js

@@ -0,0 +1,106 @@
+const REQUIRED = ['星期', '时间', '学科'];
+const DAY_MAP = { 一: 1, 二: 2, 三: 3, 四: 4, 五: 5, 六: 6, 日: 7, 天: 7 };
+const DAY_NAMES = ['', '一', '二', '三', '四', '五', '六', '日'];
+export function dayName(day) {
+    return `周${DAY_NAMES[day] ?? '?'}`;
+}
+const cells = (line) => line
+    .replace(/^\s*\|/, '')
+    .replace(/\|\s*$/, '')
+    .split('|')
+    .map((c) => c.trim());
+const isTableRow = (line) => /^\s*\|.*\|\s*$/.test(line);
+const isSeparatorRow = (line) => isTableRow(line) && cells(line).every((c) => /^:?-{2,}:?$/.test(c) || c === '');
+function parseDay(raw) {
+    const s = raw.replace(/^(星期|周)/, '').trim();
+    if (/^[1-7]$/.test(s))
+        return Number(s);
+    return DAY_MAP[s] ?? null;
+}
+const TIME_RE = /^(\d{1,2}):(\d{2})\s*[-–—~至]+\s*(\d{1,2}):(\d{2})$/;
+function parseTime(raw) {
+    const m = TIME_RE.exec(raw.trim());
+    if (!m)
+        return null;
+    const [h1, m1, h2, m2] = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+    if (h1 > 23 || h2 > 23 || m1 > 59 || m2 > 59)
+        return null;
+    const start = `${String(h1).padStart(2, '0')}:${m[2]}`;
+    const end = `${String(h2).padStart(2, '0')}:${m[4]}`;
+    if (start >= end)
+        return null;
+    return { start, end };
+}
+export function parseTimetable(md) {
+    const lines = md.split('\n');
+    const errors = [];
+    const entries = [];
+    let found = false;
+    let i = 0;
+    while (i < lines.length) {
+        if (!isTableRow(lines[i])) {
+            i++;
+            continue;
+        }
+        const header = cells(lines[i]);
+        const col = { 星期: header.indexOf('星期'), 时间: header.indexOf('时间'), 学科: header.indexOf('学科'), 孩子: header.indexOf('孩子') };
+        if (REQUIRED.some((name) => col[name] < 0)) {
+            i++;
+            while (i < lines.length && isTableRow(lines[i]))
+                i++;
+            continue;
+        }
+        found = true;
+        i++;
+        if (i < lines.length && isSeparatorRow(lines[i]))
+            i++;
+        for (; i < lines.length && isTableRow(lines[i]); i++) {
+            const row = cells(lines[i]);
+            const ln = i + 1;
+            const get = (name) => (col[name] >= 0 ? (row[col[name]] ?? '') : '');
+            const day = parseDay(get('星期'));
+            if (day === null) {
+                errors.push(`第 ${ln} 行:星期「${get('星期')}」认不出;写 一/二/…/日(或 1–7)`);
+                continue;
+            }
+            const time = parseTime(get('时间'));
+            if (!time) {
+                errors.push(`第 ${ln} 行:时间「${get('时间')}」应形如 19:00–19:40(起止用 – 或 - 连接,且结束晚于开始)`);
+                continue;
+            }
+            const subject = get('学科');
+            if (!subject) {
+                errors.push(`第 ${ln} 行:学科为空;写 语文/数学/英语 等(与 cotutor.json 里老师的 subject 对齐即归到那位老师)`);
+                continue;
+            }
+            const kid = get('孩子');
+            entries.push({ day, ...time, subject, ...(kid ? { kid } : {}) });
+        }
+    }
+    if (!found)
+        return { entries: [], errors: ['没找到课程表:课程表.md 里需要一张含 星期/时间/学科 三列表头的 markdown 表(孩子列可选)'], found: false };
+    entries.sort((a, b) => a.day - b.day || a.start.localeCompare(b.start));
+    return { entries, errors, found: true };
+}
+/** js Date → 1–7(周一–周日) */
+export function dayOf(now) {
+    const d = now.getDay();
+    return d === 0 ? 7 : d;
+}
+/** 本周(周一起算)第 day 天的日期 YYYY-MM-DD */
+export function weekDate(now, day) {
+    const d = new Date(now);
+    d.setDate(d.getDate() + (day - dayOf(now)));
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+/** 当前正在进行的时段(第一条命中;不在任何时段 = null,不猜) */
+export function currentSlot(entries, now) {
+    const day = dayOf(now);
+    const hm = `${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`;
+    return entries.find((e) => e.day === day && e.start <= hm && hm < e.end) ?? null;
+}
+/** 上下文包的 slot 字段:「数学 16:00-17:00」 */
+export function slotLabel(e) {
+    return `${e.subject} ${e.start}-${e.end}`;
+}

package/dist/schema/board.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 板书(孩子端老师页)一节的契约:卡 {kind, props} + 讲稿句。类型的真相在 src/lib/kid-board.ts(它要内联进页面,不能 import),
+ * 这里的 zod 与之对齐,文件底部用赋值断言锁住。每种卡的 props 契约在 src/cards/<kind>.ts。
+ */
+import { z } from 'zod';
+export declare const BoardCardSchema: z.ZodObject<{
+    kind: z.ZodString;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    state: z.ZodOptional<z.ZodUnknown>;
+    assets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const BoardMarkSchema: z.ZodObject<{
+    card: z.ZodNumber;
+    phrase: z.ZodString;
+}, z.core.$strip>;
+export declare const BoardCueSchema: z.ZodObject<{
+    card: z.ZodNumber;
+    name: z.ZodString;
+    arg: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const BoardLineSchema: z.ZodObject<{
+    text: z.ZodString;
+    audio: z.ZodNullable<z.ZodString>;
+    marks: z.ZodArray<z.ZodObject<{
+        card: z.ZodNumber;
+        phrase: z.ZodString;
+    }, z.core.$strip>>;
+    ask: z.ZodBoolean;
+    anchor: z.ZodNullable<z.ZodNumber>;
+    cues: z.ZodArray<z.ZodObject<{
+        card: z.ZodNumber;
+        name: z.ZodString;
+        arg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const BoardSectionSchema: z.ZodObject<{
+    cards: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        state: z.ZodOptional<z.ZodUnknown>;
+        assets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    lines: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        audio: z.ZodNullable<z.ZodString>;
+        marks: z.ZodArray<z.ZodObject<{
+            card: z.ZodNumber;
+            phrase: z.ZodString;
+        }, z.core.$strip>>;
+        ask: z.ZodBoolean;
+        anchor: z.ZodNullable<z.ZodNumber>;
+        cues: z.ZodArray<z.ZodObject<{
+            card: z.ZodNumber;
+            name: z.ZodString;
+            arg: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    partial: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;

package/dist/schema/board.js

@@ -0,0 +1,30 @@
+/**
+ * 板书(孩子端老师页)一节的契约:卡 {kind, props} + 讲稿句。类型的真相在 src/lib/kid-board.ts(它要内联进页面,不能 import),
+ * 这里的 zod 与之对齐,文件底部用赋值断言锁住。每种卡的 props 契约在 src/cards/<kind>.ts。
+ */
+import { z } from 'zod';
+export const BoardCardSchema = z.object({
+    kind: z.string().min(1),
+    props: z.record(z.string(), z.unknown()),
+    /** 孩子在卡上做的事(形状由那种卡的 state 契约定);索引里不存,下发孩子端时从 .cards/ 文件并进来 */
+    state: z.unknown().optional(),
+    /** 已生成好的配音资产(相对 conversations/<老师>/);索引里不存,下发时从 .cards/<n>/ 目录并进来 */
+    assets: z.array(z.string()).optional(),
+});
+export const BoardMarkSchema = z.object({ card: z.number().int().nonnegative(), phrase: z.string().min(1) });
+export const BoardCueSchema = z.object({ card: z.number().int().nonnegative(), name: z.string().min(1), arg: z.string().optional() });
+export const BoardLineSchema = z.object({
+    text: z.string(),
+    audio: z.string().nullable(),
+    marks: z.array(BoardMarkSchema),
+    ask: z.boolean(),
+    anchor: z.number().int().nonnegative().nullable(),
+    cues: z.array(BoardCueSchema),
+});
+export const BoardSectionSchema = z.object({
+    cards: z.array(BoardCardSchema),
+    lines: z.array(BoardLineSchema),
+    partial: z.boolean().optional(),
+});
+const assertAligned = (s) => s;
+void assertAligned;